[sequence.reqmts] (original) (raw)

23 Containers library [containers]

23.2 Requirements [container.requirements]

23.2.4 Sequence containers [sequence.reqmts]

A sequence container organizes a finite set of objects, all of the same type, into a strictly linear arrangement.

The library provides the following basic kinds of sequence containers:vector, inplace_vector,forward_list, list, and deque.

In addition,array and hive are provided as sequence containers which provide limited sequence operations, in array's case because it has a fixed number of elements, and in hive's case because insertion order is unspecified.

The library also provides container adaptors that make it easy to construct abstract data types, such as stacks,queues,flat_maps,flat_multimaps,flat_sets, orflat_multisets, out of the basic sequence container kinds (or out of other program-defined sequence containers).

In this subclause,

X denotes a sequence container class,
a denotes a value of type X containing elements of type T,
u denotes the name of a variable being declared,
A denotes X::allocator_type if the qualified-id X::allocator_type is valid and denotes a type ([temp.deduct]) andallocator<T> if it doesn't,
i and jdenote iterators that meet the Cpp17InputIterator requirements and refer to elements implicitly convertible to value_type,
[i, j) denotes a valid range,
il designates an object of type initializer_list<value_type>,
n denotes a value of type X::size_type,
p denotes a valid constant iterator to a,
q denotes a valid dereferenceable constant iterator to a,
[q1, q2) denotes a valid range of constant iterators in a,
t denotes an lvalue or a const rvalue of X::value_type, and
rv denotes a non-const rvalue of X::value_type.
Args denotes a template parameter pack;
args denotes a function parameter pack with the pattern Args&&.

The complexities of the expressions are sequence dependent.

A type X meets the sequence container requirements if X meets the container requirements and the following statements and expressions are well-formed and have the specified semantics.

Preconditions: T is Cpp17CopyInsertable into X.

Effects: Constructs a sequence container with n copies of t.

Postconditions: distance(u.begin(), u.end()) == n is true.

Preconditions: T is Cpp17EmplaceConstructible into X from *i.

For vector, if the iterator does not meet the Cpp17ForwardIterator requirements ([forward.iterators]),T is also Cpp17MoveInsertable into X.

Effects: Constructs a sequence container equal to the range [i, j).

Each iterator in the range [i, j) is dereferenced exactly once.

Postconditions: distance(u.begin(), u.end()) == distance(i, j) is true.

Preconditions: T is Cpp17EmplaceConstructible into Xfrom *ranges::begin(rg).

Effects: Constructs a sequence container equal to the range rg.

Each iterator in the range rg is dereferenced exactly once.

Recommended practice: If R models ranges::approximately_sized_range andranges::distance(
rg) <= ranges::reserve_hint(rg) is true, an implementation should not perform any reallocation.

Postconditions: distance(begin(), end()) == ranges::distance(rg) is true.

Effects: Equivalent to X(il.begin(), il.end()).

Preconditions: T is Cpp17CopyInsertable into X and_Cpp17CopyAssignable_.

Effects: Assigns the range [il.begin(), il.end()) into a.

All existing elements of a are either assigned to or destroyed.

Preconditions: T is Cpp17EmplaceConstructible into X from args.

For vector, inplace_vector, and deque,T is also Cpp17MoveInsertable into X and_Cpp17MoveAssignable_.

Effects: Inserts an object of type Tconstructed with std::forward<Args>(args)...before p.

[Note 1:

args can directly or indirectly refer to a value in a.

— _end note_]

Returns: An iterator that points to the new element.

Preconditions: T is Cpp17CopyInsertable into X.

For vector, inplace_vector, and deque,T is also Cpp17CopyAssignable.

Effects: Inserts a copy of t before p.

Returns: An iterator that points to the copy of t inserted into a.

Preconditions: T is Cpp17MoveInsertable into X.

For vector, inplace_vector, and deque,T is also Cpp17MoveAssignable.

Effects: Inserts a copy of rv before p.

Returns: An iterator that points to the copy of rv inserted into a.

Preconditions: T is Cpp17CopyInsertable into Xand Cpp17CopyAssignable.

Effects: Inserts n copies of t before p.

Returns: An iterator that points to the copy of the first element inserted into a, orp if n == 0.

Preconditions: T is Cpp17EmplaceConstructible into X from *i.

For vector, inplace_vector, and deque,T is also_Cpp17MoveInsertable_ into X, and T meets the_Cpp17MoveConstructible_,Cpp17MoveAssignable, and_Cpp17Swappable_ ([swappable.requirements]) requirements.

Neither i nor j are iterators into a.

Effects: Inserts copies of elements in [i, j) before p.

Each iterator in the range [i, j) shall be dereferenced exactly once.

Returns: An iterator that points to the copy of the first element inserted into a, orp if i == j.

Preconditions: T is Cpp17EmplaceConstructible into Xfrom *ranges::begin(rg).

rg and a do not overlap.

Effects: Inserts copies of elements in rg before p.

Each iterator in the range rg is dereferenced exactly once.

Returns: An iterator that points to the copy of the first element inserted into a, orp if rg is empty.

Effects: Equivalent to a.insert(p, il.begin(), il.end()).

Preconditions: For vector, inplace_vector, and deque,T is Cpp17MoveAssignable.

Effects: Erases the element pointed to by q.

Returns: An iterator that points to the element immediately following qprior to the element being erased.

If no such element exists, a.end() is returned.

Preconditions: For vector, inplace_vector, and deque,T is Cpp17MoveAssignable.

Effects: Erases the elements in the range [q1, q2).

Returns: An iterator that points to the element pointed to by q2prior to any elements being erased.

If no such element exists, a.end() is returned.

Effects: Destroys all elements in a.

Invalidates all references, pointers, and iterators referring to the elements of a and may invalidate the past-the-end iterator.

Postconditions: a.empty() is true.

Preconditions: T is Cpp17EmplaceConstructible into X from *iand assignable from *i.

For vector, if the iterator does not meet the forward iterator requirements ([forward.iterators]),T is also Cpp17MoveInsertable into X.

Neither i nor j are iterators into a.

Effects: Replaces elements in a with a copy of [i, j).

Invalidates all references, pointers and iterators referring to the elements of a.

For vector and deque, also invalidates the past-the-end iterator.

Each iterator in the range [i, j) is dereferenced exactly once.

Preconditions: T is Cpp17EmplaceConstructible into Xfrom *ranges::begin(rg).

rg and a do not overlap.

Effects: Replaces elements in a with a copy of each element in rg.

Invalidates all references, pointers, and iterators referring to the elements of a.

For vector and deque, also invalidates the past-the-end iterator.

Each iterator in the range rg is dereferenced exactly once.

Recommended practice: If R models ranges::approximately_sized_range andranges::distance(
rg) <= ranges::reserve_hint(rg) is true, an implementation should not perform any reallocation.

Effects: Equivalent to a.assign(il.begin(), il.end()).

Preconditions: T is Cpp17CopyInsertable into Xand Cpp17CopyAssignable.

t is not a reference into a.

Effects: Replaces elements in a with n copies of t.

Invalidates all references, pointers and iterators referring to the elements of a.

For vector and deque, also invalidates the past-the-end iterator.

For every sequence container defined in this Clause and in [strings]:

If the constructortemplate<class InputIterator> X(InputIterator first, InputIterator last,const allocator_type& alloc = allocator_type());is called with a type InputIterator that does not qualify as an input iterator, then the constructor shall not participate in overload resolution.
If the member functions of the forms:template<class InputIterator> return-type F(const_iterator p, InputIterator first, InputIterator last); template<class InputIterator> return-type F(InputIterator first, InputIterator last); template<class InputIterator> return-type F(const_iterator i1, const_iterator i2, InputIterator first, InputIterator last); are called with a type InputIterator that does not qualify as an input iterator, then these functions shall not participate in overload resolution.
A deduction guide for a sequence container shall not participate in overload resolution if it has an InputIterator template parameter and a type that does not qualify as an input iterator is deduced for that parameter, or if it has an Allocator template parameter and a type that does not qualify as an allocator is deduced for that parameter.

The following operations are provided for some types of sequence containers but not others.

Operations other than prepend_range and append_rangeare implemented so as to take amortized constant time.

Result: reference; const_reference for constant a.

Hardened preconditions: a.empty() is false.

Remarks: Required forbasic_string,array,deque,forward_list,inplace_vector,list, andvector.

Result: reference; const_reference for constant a.

Hardened preconditions: a.empty() is false.

Effects: Equivalent to:auto tmp = a.end();--tmp;return *tmp;

Remarks: Required forbasic_string,array,deque,inplace_vector,list, andvector.

Preconditions: T is Cpp17EmplaceConstructible into X from args.

Effects: Prepends an object of type Tconstructed with std::forward<Args>(args)....

Remarks: Required fordeque,forward_list, andlist.

Preconditions: T is Cpp17EmplaceConstructible into X from args.

For vector,T is also Cpp17MoveInsertable into X.

Effects: Appends an object of type Tconstructed with std::forward<Args>(args)....

Remarks: Required fordeque,inplace_vector,list, andvector.

Preconditions: T is Cpp17CopyInsertable into X.

Effects: Prepends a copy of t.

Remarks: Required fordeque,forward_list, andlist.

Preconditions: T is Cpp17MoveInsertable into X.

Effects: Prepends a copy of rv.

Remarks: Required fordeque,forward_list, andlist.

Preconditions: T is Cpp17EmplaceConstructible into Xfrom *ranges::begin(rg).

For deque,T is also Cpp17MoveInsertable into X, andT meets the_Cpp17MoveConstructible_,Cpp17MoveAssignable, and_Cpp17Swappable_ ([swappable.requirements]) requirements.

Effects: Inserts copies of elements in rg before begin().

Each iterator in the range rg is dereferenced exactly once.

[Note 2:

The order of elements in rg is not reversed.

— _end note_]

Remarks: Required fordeque,forward_list, andlist.

Preconditions: T is Cpp17CopyInsertable into X.

Effects: Appends a copy of t.

Remarks: Required forbasic_string,deque,inplace_vector,list, andvector.

Preconditions: T is Cpp17MoveInsertable into X.

Effects: Appends a copy of rv.

Remarks: Required forbasic_string,deque,inplace_vector,list, andvector.

Preconditions: T is Cpp17EmplaceConstructible into Xfrom *ranges::begin(rg).

For vector,T is also_Cpp17MoveInsertable_ into X.

Effects: Inserts copies of elements in rg before end().

Each iterator in the range rg is dereferenced exactly once.

Remarks: Required fordeque,inplace_vector,list, andvector.

Hardened preconditions: a.empty() is false.

Effects: Destroys the first element.

Remarks: Required fordeque,forward_list, andlist.

Hardened preconditions: a.empty() is false.

Effects: Destroys the last element.

Remarks: Required forbasic_string,deque,inplace_vector,list, andvector.

Result: reference; const_reference for constant a.

Hardened preconditions: n < a.size() is true.

Effects: Equivalent to: return *(a.begin() + n);

Remarks: Required forbasic_string,array,deque,inplace_vector, andvector.

Result: reference; const_reference for constant a.

Returns: *(a.begin() + n)

Throws: out_of_range if n >= a.size().

Remarks: Required forbasic_string,array,deque,inplace_vector, andvector.