Namespaces
Variants

C++ named requirements: SequenceContainer

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

Un SequenceContainer es un Container que almacena objetos del mismo tipo en una disposición lineal.

Contenidos

Requisitos

Dados los siguientes tipos y valores:

Tipo Definición
C una clase contenedora de secuencia
T el tipo de elemento de C
A el tipo de asignador de C :
R (desde C++23) un tipo que modela container-compatible-range  <T>
Args (desde C++11) un paquete de parámetros de plantilla
Iter C::iterator
Ref C::reference
CRef C::const_reference
Valor Definición
v un valor de tipo C
cv un valor de tipo const C
i , j LegacyInputIterator s tales que [ i , j ) es un rango válido y que los iteradores se refieren a elementos implícitamente convertibles a C::value_type
rg (desde C++23) un valor de tipo R
il (desde C++11) un valor de tipo std:: initializer_list < C :: value_type >
n un valor de tipo C::size_type
p un iterador constante válido en v
q un iterador constante desreferenciable válido en v
q1 , q2 iteradores constantes en v tales que [ q1 , q2 ) es un rango válido
t un valor (hasta C++11) un lvalue o const rvalue (desde C++11) de tipo C::value_type
rv (desde C++11) un rvalue no constante de tipo C::value_type
args (desde C++11) un paquete de parámetros de función con el patrón Arg&&

C satisface los requisitos de SequenceContainer si se cumplen todas las siguientes condiciones:

  • C cumple con los requisitos de Container .
  • Las siguientes declaraciones y expresiones están bien formadas y tienen la semántica especificada:
Operaciones básicas
(requeridas para todos los contenedores de secuencia en la biblioteca estándar excepto std::array (desde C++11) )
Declaración Semántica [1]
C c ( n, t ) ; Efecto Construye el contenedor de secuencia que contiene n copias de t .
Condición previa

T es CopyInsertable en C .

(desde C++11)
Postcondición std:: distance ( c. begin ( ) , c. end ( ) ) es n .
C c ( i, j ) ; Efecto Construye el contenedor de secuencias igual, elemento por elemento, al rango [ i , j ) .
  • Cada iterador en el rango [ i , j ) es desreferenciado exactamente una vez.
Precondición

T es EmplaceConstructible en C desde * i .

(desde C++11)
Postcondición std:: distance ( c. begin ( ) , c. end ( ) ) es std:: distance ( i, j ) .
Expresión Tipo Semántica
C ( std:: from_range , rg )
(desde C++23) 		C Efecto Construye el contenedor de secuencias igual, elemento por elemento, al rango rg .
  • Cada iterador en el rango rg es desreferenciado exactamente una vez.
Condición previa T es EmplaceConstructible en X desde * ranges:: begin ( rg ) .
Postcondición std:: distance ( begin ( ) , end ( ) ) es ranges:: distance ( rg ) .
C ( il )
(desde C++11) 		C Equivalente a C ( il. begin ( ) , il. end ( ) ) .
v = il
(desde C++11) 		C& Efecto Asigna el rango representado por il a v . [2]
Valor de retorno * this
Condición previa T es CopyInsertable en C y CopyAssignable .
Postcondición Los elementos existentes de v son destruidos o asignados.
v. emplace ( p, args )
(desde C++11) 		Iter Efecto Inserta un objeto de tipo T , construido con std:: forward < Args > ( args ) ... antes de p .
Valor de retorno Un iterador que apunta al nuevo elemento construido a partir de args en v .
Condición previa T es EmplaceConstructible en C desde args .
v. insert ( p, t ) Iter Efecto Inserta una copia de t antes de p .
Valor de retorno Un iterador que apunta a la copia de t insertada en v .
Condición previa

T es CopyInsertable en C .

(desde C++11)
v. insert ( p, rv )
(desde C++11) 		Iter Efecto Inserta una copia de rv antes de p , posiblemente utilizando semántica de movimiento.
Valor de retorno Un iterador que apunta a la copia de rv insertada en v .
Condición previa T es MoveInsertable en C .
v. insert ( p, n, t ) Iter Efecto Inserta n copias de t antes de p .
Valor de retorno Un iterador que apunta a la copia del primer elemento insertado en v , o p si n es ​ 0 ​ .
Condición previa

T es CopyInsertable en C y CopyAssignable .

(desde C++11)
v. insert ( p, i, j ) Iter Efecto Inserta copias de los elementos en [ i , j ) antes de p .
  • Cada iterador en el rango [ i , j ) es desreferenciado exactamente una vez.
Valor de retorno Un iterador que apunta a la copia del primer elemento insertado en v , o p si i == j es true .
Precondición
(desde C++11)
  • i y j no están en v .
v. insert_range ( p, rg )
(desde C++23) 		Iter Efecto Inserta copias de elementos en rg antes de p .
  • Cada iterador en el rango rg es desreferenciado exactamente una vez.
Valor de retorno Un iterador que apunta a la copia del primer elemento insertado en v , o p si rg está vacío.
Precondición
v. insert ( p, il )
(desde C++11) 		Iter Equivalente a v. insert ( p, il. begin ( ) , il. end ( ) ) .
v. erase ( q ) Iter Efecto Elimina el elemento apuntado por q .
Valor de retorno Un iterador que apunta al elemento inmediatamente posterior a q antes de borrar el elemento, o v. end ( ) si no existe tal elemento.
v. erase ( q1, q2 ) Iter Efecto Elimina elementos en [ q1 , q2 ) .
Valor de retorno Un iterador que apunta al elemento señalado por q2 antes de que se borrara cualquier elemento, o v. end ( ) si no existe tal elemento.
v. clear ( ) void Efecto Destruye todos los elementos en v .
  • Invalida todas las referencias, punteros e iteradores que referencian a los elementos de v y puede invalidar el iterador past-the-end.
Postcondición v. empty ( ) es true .
Complejidad Lineal.
v. assign ( i, j ) void Efecto Reemplaza los elementos en v con una copia de [ i , j ) .
  • Invalida todas las referencias, punteros e iteradores que apunten a los elementos de v .
  • Cada iterador en [ i , j ) es desreferenciado exactamente una vez.
Precondición
(desde C++11)
  • i y j no están en v .
v. assign_range ( rg )
(desde C++23) 		void Efecto Reemplaza los elementos en v con una copia de cada elemento en rg .
  • Si std:: assignable_from
    < T & , ranges:: range_reference_t < R >>     no se cumple, el programa está mal formado.
  • Invalida todas las referencias, punteros e iteradores que apunten a los elementos de v .
  • Cada iterador en el rango rg se desreferencia exactamente una vez.
Precondición
v. assign ( il )
(desde C++11) 		void Equivalente a v. assign ( il. begin ( ) , il. end ( ) ) .
v. assign ( n, t ) void Efecto Reemplaza los elementos en v con n copias de t .
Condición previa

T es CopyInsertable en C y CopyAssignable .

(desde C++11)
Operaciones adicionales [3]
(solo requeridas para contenedores de secuencia específicos, omitiendo std:: )
Expresión Tipo Semántica
v. front ( ) Ref Contenedores basic_string , array , vector , inplace_vector , deque , list , forward_list
Valor de retorno * v. begin ( )
cv. front ( ) CRef Contenedores basic_string , array , vector , inplace_vector , deque , list , forward_list
Valor de retorno * cv. begin ( )
v. back ( ) Ref Contenedores basic_string , array , vector , inplace_vector , deque , list
Equivalente a auto tmp = v. end ( ) ; -- tmp ; return * tmp ; [4] .
cv. back ( ) CRef Contenedores basic_string , array , vector , inplace_vector , deque , list
Equivalente a auto tmp = cv. end ( ) ; -- tmp ; return * tmp ; [5] .
v. emplace_front ( args )
(desde C++11) 		void Contenedores deque , list , forward_list
Efecto Antepone un objeto de tipo T construido con std:: forward < Args > ( args ) ... .
Valor de retorno v. front ( )
Condición previa T es EmplaceConstructible en C desde args .
v. emplace_back ( args )
(desde C++11) 		void Contenedores vector , inplace_vector , deque , list
Efecto Añade un objeto de tipo T construido con std:: forward < Args > ( args ) ... .
Valor de retorno v. back ( )
Condición previa T es EmplaceConstructible en C desde args .
v. push_front ( t ) void Contenedores deque , list , forward_list
Effect Antepone una copia de t .
Condición previa

T es CopyInsertable en C .

(desde C++11)
v. push_front ( rv )
(desde C++11) 		void Contenedores deque , list , forward_list
Effect Antepone una copia de rv , posiblemente utilizando semánticas de movimiento.
Condición previa T es MoveInsertable en C .
v. prepend_range ( rg )
(desde C++23) 		void Contenedores deque , list , forward_list
Efecto Inserta [6] copias de elementos en rg antes de v. begin ( ) .
  • Cada iterador en el rango rg es desreferenciado exactamente una vez.
Condición previa T es EmplaceConstructible en C desde * ranges:: begin ( rg ) .
v. push_back ( t ) void Contenedores basic_string , vector , inplace_vector , deque , list
Effect Añade una copia de t .
Condición previa

T es CopyInsertable en C .

(desde C++11)
v. push_back ( rv )
(desde C++11) 		void Contenedores basic_string , vector , inplace_vector , deque , list
Effect Añade una copia de rv , posiblemente utilizando semántica de movimiento.
Condición previa T es MoveInsertable en C .
v. append_range ( rg )
(desde C++23) 		void Contenedores vector , inplace_vector , deque , list
Efecto Inserta [6] copias de elementos en rg antes de v. end ( ) .
  • Cada iterador en el rango rg es desreferenciado exactamente una vez.
Condición previa T es EmplaceConstructible en C desde * ranges:: begin ( rg ) .
v. pop_front ( ) void Contenedores deque , list , forward_list
Effect Destruye el primer elemento.
Precondición a. empty ( ) es false .
v. pop_back ( ) void Contenedores basic_string , vector , inplace_vector , deque , list
Effect Destruye el último elemento.
Condición previa a. empty ( ) es false .
v [ n ] Ref Contenedores basic_string , array , vector , inplace_vector , deque
Equivalente a return * ( v. begin ( ) + n ) ; .
cv [ n ] CRef Contenedores basic_string , array , vector , inplace_vector , deque
Equivalente a return * ( cv. begin ( ) + n ) ; .
v. at ( n ) Ref Contenedores basic_string , array , vector , inplace_vector , deque
Valor de retorno * ( v. begin ( ) + n )
Excepciones Lanza std::out_of_range si n >= v. size ( ) es true .
cv. at ( n ) CRef Contenedores basic_string , array , vector , inplace_vector , deque
Valor de retorno * ( cv. begin ( ) + n )
Excepciones Lanza std::out_of_range si n >= cv. size ( ) es true .
Notas
  1. ↑ Para una expresión cuyo efecto es equivalente a otras operaciones, las condiciones de las expresiones dentro de esas operaciones se heredan además de las condiciones listadas en la tabla.
  2. ↑ std::array soporta asignación desde una lista de inicialización entre llaves , pero no desde un std::initializer_list .
  3. ↑ Todas las operaciones siguientes excepto prepend_range y append_range (desde C++23) toman tiempo constante amortizado.
  4. ↑ En C++98, tmp se declaraba con tipo C::iterator .
  5. ↑ En C++98, tmp se declaraba con tipo C::const_iterator .
  6. ↑ 6.0 6.1 El orden de inserción, relativo al orden de elementos en rg , es no inverso.

Además, para cada contenedor de secuencia:

  • Una plantilla de constructor que toma dos iteradores de entrada y las sobrecargas de la función miembro plantilla de insert , append , assign , replace que toman dos iteradores de entrada no participan en la resolución de sobrecarga si el argumento de plantilla correspondiente no satisface LegacyInputIterator .
  • Una guía de deducción que tiene ya sea un LegacyInputIterator o un parámetro de plantilla Allocator no participa en la resolución de sobrecarga si el tipo que no califica como iterador de entrada o como asignador respectivamente es deducido para ese parámetro.
(desde C++17)

Biblioteca estándar

Los siguientes tipos de cadena y contenedores de la biblioteca estándar satisfacen los SequenceContainer requisitos:

almacena y manipula secuencias de caracteres
(plantilla de clase)
(C++11)
array contiguo in situ de tamaño fijo
(plantilla de clase)
array contiguo redimensionable
(plantilla de clase)
(C++26)
array contiguo in situ redimensionable con capacidad fija
(plantilla de clase)
cola de doble extremo
(plantilla de clase)
(C++11)
lista simplemente enlazada
(plantilla de clase)
lista doblemente enlazada
(plantilla de clase)

Notas de uso

Contenedor Ventajas Desventajas
std::vector Acceso rápido, almacenamiento contiguo Inserciones/eliminaciones mayormente ineficientes
std:: inplace_vector Acceso rápido, almacenamiento contiguo in situ Capacidad fija e inserciones/eliminaciones mayormente ineficientes
std::array Acceso rápido, almacenamiento contiguo in situ Número fijo de elementos y sin inserción/eliminación
std::deque Acceso rápido, inserción/eliminación eficiente al principio/final Inserción/eliminación ineficiente en medio de la secuencia
std::list
std::forward_list 		Inserción/eliminación eficiente en medio de la secuencia El acceso es mayormente de tiempo lineal

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares de C++ publicados anteriormente.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 139 C++98 las operaciones opcionales no eran requeridas
para ser implementadas en los contenedores designados 		requerido con tiempo amortizado
LWG 149 C++98 v. insert ( p, t ) retornaba Iter mientras que
v. insert ( p, n, t ) y v. insert ( p, n, t )
retornaban void 		todos retornan Iter
LWG 151 C++98 q1 debía ser dereferenciable [1] puede ser no dereferenciable
LWG 355 C++98 llamar v. back ( ) o v. pop_back ( ) ejecutaría
-- v. end ( ) , lo cual es peligroso [2] 		decrementa una copia
de v. end ( ) en su lugar
LWG 589 C++98 los elementos a los que i y j se refieren
podrían no ser convertibles a C::value_type 		son implícitamente
convertibles a C::value_type
LWG 2194 C++11 std::queue , std::priority_queue y
std::stack también eran SequenceContainer s [3] 		no son SequenceContainer s
LWG 2231 C++11 el requisito de complejidad de v. clear ( )
fue omitido erróneamente en C++11 		complejidad reafirmada como lineal
LWG 3927 C++98 operator [ ] no tenía requisito implícito añadido el requisito implícito
  1. ↑ Es un defecto porque hace que el comportamiento de v. erase ( v. begin ( ) , v. end ( ) ) sea indefinido si v es un contenedor vacío.
  2. ↑ Si el tipo de v. end ( ) es un tipo fundamental, -- v. end ( ) es incorrecto. Es peligroso cuando el tipo de v está parametrizado, en este caso este error puede ser difícil de encontrar.
  3. ↑ No estaban documentados como SequenceContainer s en C++98.