Namespaces
Variants

C++ named requirements: SequenceContainer

From cppreference.net
C++
C++ named requirements

Un SequenceContainer est un Container qui stocke des objets du même type dans un arrangement linéaire.

Table des matières

Exigences

Étant donné les types et valeurs suivants :

Type Définition
C une classe de conteneur de séquence
T le type d'élément de C
A le type d'allocateur de C :
R (depuis C++23) un type qui modélise container-compatible-range  <T>
Args (depuis C++11) un pack de paramètres de modèle
Iter C::iterator
Ref C::reference
CRef C::const_reference
Valeur Définition
v une valeur de type C
cv une valeur de type const C
i , j LegacyInputIterator s tels que [ i , j ) est un intervalle valide et que les itérateurs se réfèrent à des éléments implicitement convertibles en C::value_type
rg (depuis C++23) une valeur de type R
il (depuis C++11) une valeur de type std:: initializer_list < C :: value_type >
n une valeur de type C::size_type
p un itérateur constant valide dans v
q un itérateur constant déréférençable valide dans v
q1 , q2 des itérateurs constants dans v tels que [ q1 , q2 ) est un intervalle valide
t une valeur (jusqu'à C++11) une lvalue ou rvalue constante (depuis C++11) de type C::value_type
rv (depuis C++11) une rvalue non constante de type C::value_type
args (depuis C++11) un pack de paramètres de fonction avec le motif Arg&&

C satisfait les exigences de SequenceContainer si toutes les conditions suivantes sont remplies :

  • C satisfait aux exigences de Container .
  • Les déclarations et expressions suivantes sont bien formées et possèdent la sémantique spécifiée :
Opérations de base
(requises pour tous les conteneurs de séquence dans la bibliothèque standard sauf std::array (depuis C++11) )
Déclaration Sémantique [1]
C c ( n, t ) ; Effet Construit le conteneur de séquence contenant n copies de t .
Condition préalable

T est CopyInsertable dans C .

(depuis C++11)
Postcondition std:: distance ( c. begin ( ) , c. end ( ) ) est n .
C c ( i, j ) ; Effet Construit le conteneur de séquence égal, élément par élément, à l'intervalle [ i , j ) .
  • Chaque itérateur dans l'intervalle [ i , j ) est déréférencé exactement une fois.
Précondition

T est EmplaceConstructible dans C à partir de * i .

(depuis C++11)
Postcondition std:: distance ( c. begin ( ) , c. end ( ) ) est std:: distance ( i, j ) .
Expression Type Sémantique
C ( std:: from_range , rg )
(depuis C++23) 		C Effet Construit le conteneur séquentiel égal, élément par élément, à la plage rg .
  • Chaque itérateur dans la plage rg est déréférencé exactement une fois.
Précondition T est EmplaceConstructible dans X à partir de * ranges:: begin ( rg ) .
Postcondition std:: distance ( begin ( ) , end ( ) ) est ranges:: distance ( rg ) .
C ( il )
(depuis C++11) 		C Équivalent à C ( il. begin ( ) , il. end ( ) ) .
v = il
(depuis C++11) 		C& Effet Assigne la plage représentée par il dans v . [2]
Valeur de retour * this
Précondition T est CopyInsertable dans C et CopyAssignable .
Postcondition Les éléments existants de v sont soit détruits soit assignés.
v. emplace ( p, args )
(depuis C++11) 		Iter Effet Insère un objet de type T , construit avec std:: forward < Args > ( args ) ... avant p .
Valeur de retour Un itérateur qui pointe vers le nouvel élément construit à partir de args dans v .
Précondition T est EmplaceConstructible dans C à partir de args .
v. insert ( p, t ) Iter Effet Insère une copie de t avant p .
Valeur de retour Un itérateur qui pointe vers la copie de t insérée dans v .
Condition préalable

T est CopyInsertable dans C .

(depuis C++11)
v. insert ( p, rv )
(depuis C++11) 		Iter Effet Insère une copie de rv avant p , en utilisant potentiellement la sémantique de déplacement.
Valeur de retour Un itérateur qui pointe vers la copie de rv insérée dans v .
Précondition T est MoveInsertable dans C .
v. insert ( p, n, t ) Iter Effet Insère n copies de t avant p .
Valeur de retour Un itérateur qui pointe vers la copie du premier élément inséré dans v , ou p si n est ​ 0 ​ .
Précondition

T est CopyInsertable dans C et CopyAssignable .

(depuis C++11)
v. insert ( p, i, j ) Iter Effet Insère des copies des éléments dans [ i , j ) avant p .
  • Chaque itérateur dans l'intervalle [ i , j ) est déréférencé exactement une fois.
Valeur de retour Un itérateur qui pointe vers la copie du premier élément inséré dans v , ou p si i == j est true .
Précondition
(depuis C++11)
  • i et j ne sont pas dans v .
v. insert_range ( p, rg )
(depuis C++23) 		Iter Effet Insère des copies des éléments de rg avant p .
  • Chaque itérateur dans la plage rg est déréférencé exactement une fois.
Valeur de retour Un itérateur qui pointe vers la copie du premier élément inséré dans v , ou p si rg est vide.
Précondition
v. insert ( p, il )
(depuis C++11) 		Iter Équivalent à v. insert ( p, il. begin ( ) , il. end ( ) ) .
v. erase ( q ) Iter Effet Supprime l'élément pointé par q .
Valeur de retour Un itérateur qui pointe vers l'élément immédiatement suivant q avant l'effacement de l'élément, ou v. end ( ) si aucun élément de ce type n'existe.
v. erase ( q1, q2 ) Iter Effet Supprime les éléments dans [ q1 , q2 ) .
Valeur de retour Un itérateur qui pointe vers l'élément pointé par q2 avant que des éléments ne soient effacés, ou v. end ( ) si aucun tel élément n'existe.
v. clear ( ) void Effet Détruit tous les éléments dans v .
  • Invalide toutes les références, pointeurs et itérateurs se référant aux éléments de v et peut invalider l'itérateur past-the-end.
Postcondition v. empty ( ) est true .
Complexité Linéaire.
v. assign ( i, j ) void Effet Remplace les éléments de v par une copie de [ i , j ) .
  • Invalide toutes les références, pointeurs et itérateurs se référant aux éléments de v .
  • Chaque itérateur dans [ i , j ) est déréférencé exactement une fois.
Précondition
(depuis C++11)
  • i et j ne sont pas dans v .
v. assign_range ( rg )
(depuis C++23) 		void Effet Remplace les éléments dans v par une copie de chaque élément dans rg .
  • Si std:: assignable_from
    < T & , ranges:: range_reference_t < R >>     n'est pas modélisé, le programme est mal formé.
  • Invalide toutes les références, pointeurs et itérateurs se référant aux éléments de v .
  • Chaque itérateur dans la plage rg est déréférencé exactement une fois.
Précondition
v. assign ( il )
(depuis C++11) 		void Équivalent à v. assign ( il. begin ( ) , il. end ( ) ) .
v. assign ( n, t ) void Effet Remplace les éléments dans v par n copies de t .
Précondition

T est CopyInsertable dans C et CopyAssignable .

(depuis C++11)
Opérations supplémentaires [3]
(requises uniquement pour les conteneurs de séquence spécifiés, en omettant std:: )
Expression Type Sémantique
v. front ( ) Ref Conteneurs basic_string , array , vector , inplace_vector , deque , list , forward_list
Valeur de retour * v. begin ( )
cv. front ( ) CRef Conteneurs basic_string , array , vector , inplace_vector , deque , list , forward_list
Valeur de retour * cv. begin ( )
v. back ( ) Ref Conteneurs basic_string , array , vector , inplace_vector , deque , list
Équivalent à auto tmp = v. end ( ) ; -- tmp ; return * tmp ; [4] .
cv. back ( ) CRef Conteneurs basic_string , array , vector , inplace_vector , deque , list
Équivalent à auto tmp = cv. end ( ) ; -- tmp ; return * tmp ; [5] .
v. emplace_front ( args )
(depuis C++11) 		void Conteneurs deque , list , forward_list
Effet Ajoute en tête un objet de type T construit avec std:: forward < Args > ( args ) ... .
Valeur de retour v. front ( )
Précondition T est EmplaceConstructible dans C à partir de args .
v. emplace_back ( args )
(depuis C++11) 		void Conteneurs vector , inplace_vector , deque , list
Effet Ajoute un objet de type T construit avec std:: forward < Args > ( args ) ... .
Valeur de retour v. back ( )
Précondition T est EmplaceConstructible dans C à partir de args .
v. push_front ( t ) void Conteneurs deque , list , forward_list
Effet Ajoute une copie de t au début.
Condition préalable

T est CopyInsertable dans C .

(depuis C++11)
v. push_front ( rv )
(depuis C++11) 		void Conteneurs deque , list , forward_list
Effet Ajoute une copie de rv , en utilisant potentiellement la sémantique de déplacement.
Précondition T est MoveInsertable dans C .
v. prepend_range ( rg )
(depuis C++23) 		void Conteneurs deque , list , forward_list
Effet Insère [6] des copies des éléments de rg avant v. begin ( ) .
  • Chaque itérateur dans la plage rg est déréférencé exactement une fois.
Précondition T est EmplaceConstructible dans C à partir de * ranges:: begin ( rg ) .
v. push_back ( t ) void Conteneurs basic_string , vector , inplace_vector , deque , list
Effet Ajoute une copie de t .
Condition préalable

T est CopyInsertable dans C .

(depuis C++11)
v. push_back ( rv )
(depuis C++11) 		void Conteneurs basic_string , vector , inplace_vector , deque , list
Effet Ajoute une copie de rv , en utilisant potentiellement la sémantique de déplacement.
Précondition T est MoveInsertable dans C .
v. append_range ( rg )
(depuis C++23) 		void Conteneurs vector , inplace_vector , deque , list
Effet Insère [6] des copies des éléments de rg avant v. end ( ) .
  • Chaque itérateur dans la plage rg est déréférencé exactement une fois.
Précondition T est EmplaceConstructible dans C à partir de * ranges:: begin ( rg ) .
v. pop_front ( ) void Conteneurs deque , list , forward_list
Effet Détruit le premier élément.
Condition préalable a. empty ( ) est false .
v. pop_back ( ) void Conteneurs basic_string , vector , inplace_vector , deque , list
Effet Détruit le dernier élément.
Précondition a. empty ( ) est false .
v [ n ] Ref Conteneurs basic_string , array , vector , inplace_vector , deque
Équivalent à return * ( v. begin ( ) + n ) ; .
cv [ n ] CRef Conteneurs basic_string , array , vector , inplace_vector , deque
Équivalent à return * ( cv. begin ( ) + n ) ; .
v. at ( n ) Ref Conteneurs basic_string , array , vector , inplace_vector , deque
Valeur de retour * ( v. begin ( ) + n )
Exceptions Lance std::out_of_range si n >= v. size ( ) est true .
cv. at ( n ) CRef Conteneurs basic_string , array , vector , inplace_vector , deque
Valeur de retour * ( cv. begin ( ) + n )
Exceptions Lance std::out_of_range si n >= cv. size ( ) est true .
Notes
  1. ↑ Pour une expression dont l'effet est équivalent à d'autres opérations, les conditions des expressions à l'intérieur de ces opérations sont héritées en plus des conditions listées dans le tableau.
  2. ↑ std::array prend en charge l'assignation depuis une liste d'initialisation entre accolades , mais pas depuis un std::initializer_list .
  3. ↑ Toutes les opérations ci-dessous sauf prepend_range et append_range (depuis C++23) prennent un temps constant amorti.
  4. ↑ En C++98, tmp était déclaré avec le type C::iterator .
  5. ↑ En C++98, tmp était déclaré avec le type C::const_iterator .
  6. ↑ 6.0 6.1 L'ordre d'insertion, relatif à l'ordre des éléments dans rg , est non-inversé.

De plus, pour chaque conteneur de séquence :

  • Un constructeur template qui prend deux itérateurs d'entrée et les surcharges de fonction membre template de insert , append , assign , replace qui prennent deux itérateurs d'entrée ne participent pas à la résolution de surcharge si l'argument template correspondant ne satisfait pas LegacyInputIterator .
  • Un guide de déduction qui possède soit un paramètre de modèle LegacyInputIterator soit un paramètre de modèle Allocator ne participe pas à la résolution de surcharge si le type qui ne qualifie pas respectivement comme un itérateur d'entrée ou un allocateur est déduit pour ce paramètre.
(depuis C++17)

Bibliothèque standard

Les types de chaînes et conteneurs standards suivants satisfont aux SequenceContainer exigences :

stocke et manipule des séquences de caractères
(modèle de classe)
(C++11)
tableau contigu fixe en place
(modèle de classe)
tableau contigu redimensionnable
(modèle de classe)
(C++26)
tableau contigu en place redimensionnable à capacité fixe
(modèle de classe)
file double face
(modèle de classe)
(C++11)
liste simplement chaînée
(modèle de classe)
liste doublement chaînée
(modèle de classe)

Notes d'utilisation

Conteneur Avantages Inconvénients
std::vector Accès rapide, stockage contigu Insertions/suppressions généralement inefficaces
std:: inplace_vector Accès rapide, stockage contigu sur place Capacité fixe et insertions/suppressions généralement inefficaces
std::array Accès rapide, stockage contigu sur place Nombre fixe d'éléments et pas d'insertion/suppression
std::deque Accès rapide, insertion/suppression efficace au début/à la fin Insertion/suppression inefficace au milieu de la séquence
std::list
std::forward_list 		Insertion/suppression efficace au milieu de la séquence L'accès est généralement en temps linéaire

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement publié Comportement corrigé
LWG 139 C++98 les opérations optionnelles n'étaient pas requises
d'être implémentées pour les conteneurs désignés 		requis avec un temps amorti
LWG 149 C++98 v. insert ( p, t ) retournait Iter tandis que
v. insert ( p, n, t ) et v. insert ( p, n, t )
retournaient void 		tous retournent Iter
LWG 151 C++98 q1 devait être déréférençable [1] il peut être non déréférençable
LWG 355 C++98 appeler v. back ( ) ou v. pop_back ( ) exécuterait
-- v. end ( ) , ce qui est dangereux [2] 		décrémente une copie
de v. end ( ) à la place
LWG 589 C++98 les éléments auxquels i et j se réfèrent
pourraient ne pas être convertibles en C::value_type 		ils sont implicitement
convertibles en C::value_type
LWG 2194 C++11 std::queue , std::priority_queue et
std::stack étaient aussi des SequenceContainer s [3] 		ils ne sont pas des SequenceContainer s
LWG 2231 C++11 l'exigence de complexité de v. clear ( )
était erronément omise en C++11 		complexité réaffirmée comme linéaire
LWG 3927 C++98 operator [ ] n'avait pas d'exigence implicite ajout de l'exigence implicite
  1. ↑ C'est un défaut car il rend le comportement de v. erase ( v. begin ( ) , v. end ( ) ) indéfini si v est un conteneur vide.
  2. ↑ Si le type de v. end ( ) est un type fondamental, -- v. end ( ) est mal formé. C'est dangereux lorsque le type de v est templaté, dans ce cas ce bogue peut être difficile à détecter.
  3. ↑ Ils n'étaient pas documentés comme SequenceContainer s dans C++98.