%!TEX root = std.tex

\rSec0[containers]{Containers library}

\rSec1[containers.general]{General}

\pnum

This Clause describes components that \Cpp{} programs may use to

organize collections of information.

\pnum

The following subclauses describe

container requirements,

and components for

sequence containers and

associative containers,

as summarized in

\tref{containers.summary}.

\begin{libsumtab}{Containers library summary}{containers.summary}

\ref{container.requirements} & Requirements & \\ \rowsep

\ref{sequences} & Sequence containers &

\tcode{<array>}, \tcode{<deque>}, \tcode{<forward_list>},

\tcode{<hive>}, \\ & &

\tcode{<inplace_vector>}, \tcode{<list>}, \tcode{<vector>} \\ \rowsep

\ref{associative} & Associative containers &

\tcode{<map>}, \tcode{<set>} \\ \rowsep

\ref{unord} & Unordered associative containers &

\tcode{<unordered_map>}, \tcode{<unordered_set>} \\ \rowsep

\ref{container.adaptors} & Container adaptors &

\tcode{<queue>}, \tcode{<stack>}, \tcode{<flat_map>}, \tcode{<flat_set>} \\ \rowsep

\ref{views} & Views &

\tcode{<span>}, \tcode{<mdspan>} \\

\end{libsumtab}

\rSec1[container.requirements]{Requirements}%

\indextext{requirements!container}

\rSec2[container.requirements.pre]{Preamble}

\pnum

Containers are objects that store other objects.

They control allocation and deallocation of these objects

through constructors, destructors, insert and erase operations.

\pnum

All of the complexity requirements in this Clause are stated solely

in terms of the number of operations on the contained objects.

\begin{example}

The copy constructor of type

\tcode{vector<vector<int>>}

has linear complexity,

even though the complexity of copying each contained

\tcode{vector<int>}

is itself linear.

\end{example}

\pnum

Allocator-aware containers\iref{container.alloc.reqmts}

other than \tcode{basic_string} construct elements using the function

\tcode{allocator_traits<allocator_type>::rebind_traits<U>::\brk{}construct}

and destroy elements using the function

\tcode{allocator_traits<allocator_type>::rebind_traits<U>::\brk{}destroy}\iref{allocator.traits.members},

where \tcode{U} is either \tcode{allocator_type::value_type} or

an internal type used by the container.

These functions are called only for the

container's element type, not for internal types used by the container.

\begin{note}

This

means, for example, that a node-based container would need to construct nodes containing

aligned buffers and call \tcode{construct} to place the element into the buffer.

\end{note}

\rSec2[container.requirements.general]{General containers}

\rSec3[container.intro.reqmts]{Introduction}

\pnum

In \ref{container.requirements.general},

\begin{itemize}

\item

\tcode{X} denotes a container class containing objects of type \tcode{T},

\item

\tcode{a} denotes a value of type \tcode{X},

\item

\tcode{b} and \tcode{c} denote values of type (possibly const) \tcode{X},

\item

\tcode{i} and \tcode{j} denote values of type (possibly const) \tcode{X::iterator},

\item

\tcode{u} denotes an identifier,

\item

\tcode{v} denotes an lvalue of type (possibly const) \tcode{X} or

an rvalue of type \tcode{const X},

\item

\tcode{s} and \tcode{t} denote non-const lvalues of type \tcode{X}, and

\item

\tcode{rv} denotes a non-const rvalue of type \tcode{X}.

\end{itemize}

\pnum

The following exposition-only concept is used in the definition of containers:

\begin{codeblock}

template<class R, class T>

concept @\defexposconcept{container-compatible-range}@ = // \expos

ranges::@\libconcept{input_range}@<R> && @\libconcept{convertible_to}@<ranges::range_reference_t<R>, T>;

\end{codeblock}

\rSec3[container.reqmts]{Container requirements}

% Local command to index names as members of all containers.

\newcommand{\indexcont}[1]{%

\indexlibrarymisc{\idxcode{#1}}{containers}%

\indexlibrarymemberx{array}{#1}%

\indexlibrarymemberx{deque}{#1}%

\indexlibrarymemberx{forward_list}{#1}%

\indexlibrarymemberx{hive}{#1}%

\indexlibrarymemberx{list}{#1}%

\indexlibrarymemberx{vector}{#1}%

\indexlibrarymemberx{map}{#1}%

\indexlibrarymemberx{set}{#1}%

\indexlibrarymemberx{multiset}{#1}%

\indexlibrarymemberx{multimap}{#1}%

\indexlibrarymemberx{unordered_map}{#1}%

\indexlibrarymemberx{unordered_set}{#1}%

\indexlibrarymemberx{unordered_multiset}{#1}%

\indexlibrarymemberx{unordered_multimap}{#1}%

\indexlibrarymemberx{flat_map}{#1}%

\indexlibrarymemberx{flat_set}{#1}%

\indexlibrarymemberx{flat_multiset}{#1}%

\indexlibrarymemberx{flat_multimap}{#1}%

}

\pnum

A type \tcode{X} meets the \defn{container} requirements

if the following types, statements, and expressions are well-formed and

have the specified semantics.

\indexcont{value_type}%

\begin{itemdecl}

typename X::value_type

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{T}

\pnum

\expects

\tcode{T} is \oldconcept{Erasable} from \tcode{X}

(see~\ref{container.alloc.reqmts}, below).

\end{itemdescr}

\indexcont{reference}%

\begin{itemdecl}

typename X::reference

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{T\&}

\end{itemdescr}

\indexcont{const_reference}%

\begin{itemdecl}

typename X::const_reference

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{const T\&}

\end{itemdescr}

\indexcont{iterator}%

\begin{itemdecl}

typename X::iterator

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

A type that meets the forward iterator requirements\iref{forward.iterators}

with value type \tcode{T}.

The type \tcode{X::iterator} is convertible to \tcode{X::const_iterator}.

\end{itemdescr}

\indexcont{const_iterator}%

\begin{itemdecl}

typename X::const_iterator

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

A type that meets the requirements of a constant iterator and

those of a forward iterator with value type \tcode{T}.

\end{itemdescr}

\indexcont{difference_type}%

\begin{itemdecl}

typename X::difference_type

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

A signed integer type,

identical to the difference type of

\tcode{X::iterator} and \tcode{X::const_iterator}.

\end{itemdescr}

\indexcont{size_type}%

\begin{itemdecl}

typename X::size_type

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

An unsigned integer type

that can represent any non-negative value of \tcode{X::difference_type}.

\end{itemdescr}

\begin{itemdecl}

X u;

X u = X();

\end{itemdecl}

\begin{itemdescr}

\pnum

\ensures

\tcode{u.empty()}

\pnum

\complexity

Constant.

\end{itemdescr}

\begin{itemdecl}

X u(v);

X u = v;

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} (see below).

\pnum

\ensures

\tcode{u == v}.

\pnum

\complexity

Linear.

\end{itemdescr}

\begin{itemdecl}

X u(rv);

X u = rv;

\end{itemdecl}

\begin{itemdescr}

\pnum

\ensures

\tcode{u} is equal to the value that \tcode{rv} had before this construction.

\pnum

\complexity

Linear for \tcode{array} and \tcode{inplace_vector} and constant for all other standard containers.

\end{itemdescr}

\indexcont{operator=}%

\begin{itemdecl}

t = v;

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{X\&}.

\pnum

\ensures

\tcode{t == v}.

\pnum

\complexity

Linear.

\end{itemdescr}

\begin{itemdecl}

t = rv

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{X\&}.

\pnum

\effects

All existing elements of \tcode{t} are either move assigned to or destroyed.

\pnum

\ensures

If \tcode{t} and \tcode{rv} do not refer to the same object,

\tcode{t} is equal to the value that \tcode{rv} had before this assignment.

\pnum

\complexity

Linear.

\end{itemdescr}

\begin{itemdecl}

a.~X()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\keyword{void}.

\pnum

\effects

Destroys every element of \tcode{a}; any memory obtained is deallocated.

\pnum

\complexity

Linear.

\end{itemdescr}

\indexcont{begin}%

\begin{itemdecl}

b.begin()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{iterator};

\tcode{const_iterator} for constant \tcode{b}.

\pnum

\returns

An iterator referring to the first element in the container.

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{end}%

\begin{itemdecl}

b.end()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{iterator};

\tcode{const_iterator} for constant \tcode{b}.

\pnum

\returns

An iterator which is the past-the-end value for the container.

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{cbegin}%

\begin{itemdecl}

b.cbegin()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{const_iterator}.

\pnum

\returns

\tcode{const_cast<X const\&>(b).begin()}

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{cend}%

\begin{itemdecl}

b.cend()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{const_iterator}.

\pnum

\returns

\tcode{const_cast<X const\&>(b).end()}

\pnum

\complexity

Constant.

\end{itemdescr}

\begin{itemdecl}

i <=> j

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{strong_ordering}.

\pnum

\constraints

\tcode{X::iterator} meets the random access iterator requirements.

\pnum

\complexity

Constant.

\end{itemdescr}

% hive is excluded here

\indexlibrarymisc{\idxcode{operator==}}{containers}%

\indexlibrarymemberx{array}{operator==}%

\indexlibrarymemberx{deque}{operator==}%

\indexlibrarymemberx{forward_list}{operator==}%

\indexlibrarymemberx{list}{operator==}%

\indexlibrarymemberx{vector}{operator==}%

\indexlibrarymemberx{map}{operator==}%

\indexlibrarymemberx{set}{operator==}%

\indexlibrarymemberx{multiset}{operator==}%

\indexlibrarymemberx{multimap}{operator==}%

\indexlibrarymemberx{unordered_map}{operator==}%

\indexlibrarymemberx{unordered_set}{operator==}%

\indexlibrarymemberx{unordered_multiset}{operator==}%

\indexlibrarymemberx{unordered_multimap}{operator==}%

\indexlibrarymemberx{flat_map}{operator==}%

\indexlibrarymemberx{flat_set}{operator==}%

\indexlibrarymemberx{flat_multiset}{operator==}%

\indexlibrarymemberx{flat_multimap}{operator==}%

\begin{itemdecl}

c == b

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

\tcode{T} meets the \oldconcept{EqualityComparable} requirements.

\pnum

\result

\tcode{bool}.

\pnum

\returns

\tcode{equal(c.begin(), c.end(), b.begin(), b.end())}

\begin{note}

The algorithm \tcode{equal} is defined in \ref{alg.equal}.

\end{note}

\pnum

\complexity

Constant if \tcode{c.size() != b.size()}, linear otherwise.

\pnum

\remarks

\tcode{==} is an equivalence relation.

\end{itemdescr}

% hive is excluded here

\indexlibrarymisc{\idxcode{operator"!=}}{containers}%

\indexlibrarymemberx{array}{operator"!=}%

\indexlibrarymemberx{deque}{operator"!=}%

\indexlibrarymemberx{forward_list}{operator"!=}%

\indexlibrarymemberx{list}{operator"!=}%

\indexlibrarymemberx{vector}{operator"!=}%

\indexlibrarymemberx{map}{operator"!=}%

\indexlibrarymemberx{set}{operator"!=}%

\indexlibrarymemberx{multiset}{operator"!=}%

\indexlibrarymemberx{multimap}{operator"!=}%

\indexlibrarymemberx{unordered_map}{operator"!=}%

\indexlibrarymemberx{unordered_set}{operator"!=}%

\indexlibrarymemberx{unordered_multiset}{operator"!=}%

\indexlibrarymemberx{unordered_multimap}{operator"!=}%

\indexlibrarymemberx{flat_map}{operator"!=}%

\indexlibrarymemberx{flat_set}{operator"!=}%

\indexlibrarymemberx{flat_multiset}{operator"!=}%

\indexlibrarymemberx{flat_multimap}{operator"!=}%

\begin{itemdecl}

c != b

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to \tcode{!(c == b)}.

\end{itemdescr}

\indexcont{swap}%

\begin{itemdecl}

t.swap(s)

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\keyword{void}.

\pnum

\effects

Exchanges the contents of \tcode{t} and \tcode{s}.

\pnum

\complexity

Linear for \tcode{array} and \tcode{inplace_vector}, and

constant for all other standard containers.

\end{itemdescr}

\begin{itemdecl}

swap(t, s)

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to \tcode{t.swap(s)}.

\end{itemdescr}

\indexcont{size}%

\begin{itemdecl}

c.size()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{size_type}.

\pnum

\returns

\tcode{distance(c.begin(), c.end())},

i.e., the number of elements in the container.

\pnum

\complexity

Constant.

\pnum

\remarks

The number of elements is defined by the rules of

constructors, inserts, and erases.

\end{itemdescr}

\indexcont{max_size}%

\begin{itemdecl}

c.max_size()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{size_type}.

\pnum

\returns

\tcode{distance(begin(), end())} for the largest possible container.

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{empty}%

\begin{itemdecl}

c.empty()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{bool}.

\pnum

\returns

\tcode{c.begin() == c.end()}

\pnum

\complexity

Constant.

\pnum

\remarks

If the container is empty, then \tcode{c.empty()} is \tcode{true}.

\end{itemdescr}

\pnum

In the expressions

\begin{codeblock}

i == j

i != j

i < j

i <= j

i >= j

i > j

i <=> j

i - j

\end{codeblock}

where \tcode{i} and \tcode{j} denote objects of a container's \tcode{iterator}

type, either or both may be replaced by an object of the container's

\tcode{const_iterator} type referring to the same element with no change in semantics.

\pnum

Unless otherwise specified, all containers defined in this Clause obtain memory

using an allocator (see~\ref{allocator.requirements}).

\begin{note}

In particular, containers and iterators do not store references

to allocated elements other than through the allocator's pointer type,

i.e., as objects of type \tcode{P} or

\tcode{pointer_traits<P>::template re\-bind<\unspec>},

where \tcode{P} is \tcode{allocator_traits<allocator_type>::pointer}.

\end{note}

Copy constructors for these container types obtain an allocator by calling

\tcode{allocator_traits<allocator_type>::select_on_container_copy_construction}

on the allocator belonging to the container being copied.

Move constructors obtain an allocator by move construction from the allocator belonging to

the container being moved. Such move construction of the allocator shall not exit via an

exception.

All other constructors for these container types take a

\tcode{const allocator_type\&} argument.

\begin{note}

If an invocation of a constructor uses the default value of an optional

allocator argument, then the allocator type must support value-initialization.

\end{note}

A copy of this allocator is used for any memory allocation and element construction

performed, by these constructors and by all member functions,

during the lifetime of each container object

or until the allocator is replaced. The allocator may be replaced only via assignment or

\tcode{swap()}. Allocator replacement is performed by

copy assignment, move assignment, or swapping of the allocator only if

\begin{itemize}

\item \tcode{allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value},

\item \tcode{allocator_traits<allocator_type>::propagate_on_container_move_assignment::value},

or

\item \tcode{allocator_traits<allocator_type>::propagate_on_container_swap::value}

\end{itemize}

is \tcode{true}

within the implementation of the corresponding container operation.

In all container types defined in this Clause, the member \tcode{get_allocator()}

returns a copy of the allocator used to construct the container or, if that allocator

has been replaced, a copy of the most recent replacement.

\pnum

The expression \tcode{a.swap(b)}, for containers \tcode{a} and \tcode{b} of a standard

container type other than \tcode{array} and \tcode{inplace_vector},

shall exchange the values of \tcode{a} and

\tcode{b} without invoking any move, copy, or swap operations on the individual

container elements.

Any \tcode{Compare}, \tcode{Pred}, or \tcode{Hash} types

belonging to \tcode{a} and \tcode{b} shall meet the \oldconcept{Swappable} requirements

and shall be exchanged by calling \tcode{swap}

as described in~\ref{swappable.requirements}. If

\tcode{allocator_traits<allocator_type>::propagate_on_container_swap::value} is

\tcode{true}, then

\tcode{allocator_type} shall meet the \oldconcept{Swap\-pable} requirements and

the allocators of \tcode{a} and \tcode{b} shall also be exchanged

by calling \tcode{swap} as described in~\ref{swappable.requirements}.

Otherwise, the allocators shall not be swapped, and the behavior is

undefined unless \tcode{a.get_allocator() == b.get_allocator()}. Every iterator

referring to an element in one container before the swap shall refer to the same

element in the other container after the swap. It is unspecified whether an iterator

with value \tcode{a.end()} before the swap will have value \tcode{b.end()} after the

swap.

\pnum

Unless otherwise specified (see~\ref{associative.reqmts.except}, \ref{unord.req.except}, \ref{deque.modifiers}, \ref{inplace.vector.modifiers}, and

\ref{vector.modifiers})

all container types defined in this Clause meet

the following additional requirements:

\begin{itemize}

\item

If an exception is thrown by an

\tcode{insert()} or \tcode{emplace()}

function while inserting a single element, that

function has no effects.

\item

If an exception is thrown by a

\tcode{push_back()},

\tcode{push_front()},

\tcode{emplace_back()}, or \tcode{emplace_front()}

function, that function has no effects.

\item

No

\tcode{erase()},

\tcode{clear()},

\tcode{pop_back()}

or

\tcode{pop_front()}

function throws an exception.

\item

No copy constructor or assignment operator of a returned iterator

throws an exception.

\item

No

\tcode{swap()}

function throws an exception.

\item

No

\tcode{swap()}

function invalidates any references,

pointers, or iterators referring to the elements

of the containers being swapped.

\begin{note}

The \tcode{end()} iterator does not refer to any element, so it can be invalidated.

\end{note}

\end{itemize}

\pnum

Unless otherwise specified (either explicitly or by defining a

function in terms of other functions), invoking a container member

function or passing a container as an argument to a library function

shall not invalidate iterators to, or change the values of, objects

within that container.

\pnum

A \defnadj{contiguous}{container}

is a container

whose member types \tcode{iterator} and \tcode{const_iterator}

meet the

\oldconcept{RandomAccessIterator} requirements\iref{random.access.iterators} and

model \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous}.

\pnum

The behavior of certain container member functions and deduction guides

depends on whether types qualify as input iterators or allocators.

The extent to which an implementation determines that a type cannot be an input

iterator is unspecified, except that as a minimum integral types shall not qualify

as input iterators.

Likewise, the extent to which an implementation determines that a type cannot be

an allocator is unspecified, except that as a minimum a type \tcode{A} shall not qualify

as an allocator unless it meets both of the following conditions:

\begin{itemize}

\item The \grammarterm{qualified-id} \tcode{A::value_type}

is valid and denotes a type\iref{temp.deduct}.

\item The expression \tcode{declval<A\&>().allocate(size_t\{\})}

is well-formed when treated as an unevaluated operand.

\end{itemize}

\rSec3[container.rev.reqmts]{Reversible container requirements}

% Local command to index names as members of all containers.

\renewcommand{\indexcont}[1]{%

\indexlibrarymisc{\idxcode{#1}}{reversible containers}%

\indexlibrarymemberx{array}{#1}%

\indexlibrarymemberx{deque}{#1}%

\indexlibrarymemberx{hive}{#1}%

\indexlibrarymemberx{list}{#1}%

\indexlibrarymemberx{vector}{#1}%

\indexlibrarymemberx{map}{#1}%

\indexlibrarymemberx{set}{#1}%

\indexlibrarymemberx{multiset}{#1}%

\indexlibrarymemberx{multimap}{#1}%

\indexlibrarymemberx{unordered_map}{#1}%

\indexlibrarymemberx{unordered_set}{#1}%

\indexlibrarymemberx{unordered_multiset}{#1}%

\indexlibrarymemberx{unordered_multimap}{#1}%

\indexlibrarymemberx{flat_map}{#1}%

\indexlibrarymemberx{flat_set}{#1}%

\indexlibrarymemberx{flat_multiset}{#1}%

\indexlibrarymemberx{flat_multimap}{#1}%

}

\pnum

A type \tcode{X} meets the \defnadj{reversible}{container} requirements if

\tcode{X} meets the container requirements,

the iterator type of \tcode{X} belongs to the

bidirectional or random access iterator categories\iref{iterator.requirements},

and

the following types and expressions are well-formed and have

the specified semantics.

\indexcont{reverse_iterator}%

\begin{itemdecl}

typename X::reverse_iterator

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

The type \tcode{reverse_iterator<X::iterator>},

an iterator type whose value type is \tcode{T}.

\end{itemdescr}

\indexcont{const_reverse_iterator}%

\begin{itemdecl}

typename X::const_reverse_iterator

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

The type \tcode{reverse_iterator<X::const_iterator>},

a constant iterator type whose value type is \tcode{T}.

\end{itemdescr}

\indexcont{rbegin}%

\begin{itemdecl}

a.rbegin()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{reverse_iterator};

\tcode{const_reverse_iterator} for constant \tcode{a}.

\pnum

\returns

\tcode{reverse_iterator(end())}

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{rend}%

\begin{itemdecl}

a.rend()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{reverse_iterator};

\tcode{const_reverse_iterator} for constant \tcode{a}.

\pnum

\returns

\tcode{reverse_iterator(begin())}

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{crbegin}%

\begin{itemdecl}

a.crbegin()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{const_reverse_iterator}.

\pnum

\returns

\tcode{\keyword{const_cast}<X \keyword{const}\&>(a).rbegin()}

\pnum

\complexity

Constant.

\end{itemdescr}

\indexcont{crend}%

\begin{itemdecl}

a.crend()

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{const_reverse_iterator}.

\pnum

\returns

\tcode{\keyword{const_cast}<X \keyword{const}\&>(a).rend()}

\pnum

\complexity

Constant.

\end{itemdescr}

\rSec3[container.opt.reqmts]{Optional container requirements}

\pnum

The following operations are provided

for some types of containers but not others. Those containers for which the

listed operations are provided shall implement the semantics as described

unless otherwise stated.

If the iterators passed to \tcode{lexicographical_compare_three_way}

meet the constexpr iterator requirements\iref{iterator.requirements.general}

then the operations described below

are implemented by constexpr functions.

% Local command to index a name as a member of all containers.

\renewcommand{\indexcont}[1]{%

\indexlibrarymisc{\idxcode{#1}}{optional container requirements}%

\indexlibrarymemberx{array}{#1}%

\indexlibrarymemberx{deque}{#1}%

\indexlibrarymemberx{forward_list}{#1}%

\indexlibrarymemberx{list}{#1}%

\indexlibrarymemberx{vector}{#1}%

\indexlibrarymemberx{map}{#1}%

\indexlibrarymemberx{set}{#1}%

\indexlibrarymemberx{multiset}{#1}%

\indexlibrarymemberx{multimap}{#1}%

\indexlibrarymemberx{flat_map}{#1}%

\indexlibrarymemberx{flat_set}{#1}%

\indexlibrarymemberx{flat_multiset}{#1}%

\indexlibrarymemberx{flat_multimap}{#1}%

\indexlibrarymemberx{basic_string}{#1}%

}

\indexcont{operator<=>}%

\begin{itemdecl}

a <=> b

\end{itemdecl}

\begin{itemdescr}

\pnum

\result

\tcode{\exposid{synth-three-way-result}<X::value_type>}.

\pnum

\expects

Either \tcode{T} models \libconcept{three_way_comparable},

or \tcode{<} is defined for values of type (possibly const) \tcode{T} and

\tcode{<} is a total ordering relationship.

\pnum

\returns

\tcode{lexicographical_compare_three_way(a.begin(), a.end(),

b.begin(), b.end(),\newline \exposidnc{synth-three-way})}

\begin{note}

The algorithm \tcode{lexicographical_compare_three_way}

is defined in \ref{algorithms}.

\end{note}

\pnum

\complexity

Linear.

\end{itemdescr}

\rSec3[container.alloc.reqmts]{Allocator-aware containers}

\pnum

Except for \tcode{array} and \tcode{inplace_vector},

all of the containers defined in \ref{containers},

\ref{stacktrace.basic}, \ref{basic.string}, and \ref{re.results}

meet the additional requirements of an \defnadj{allocator-aware}{container},

as described below.

\pnum

Given an allocator type \tcode{A}

and given a container type \tcode{X} having a \tcode{value_type} identical to \tcode{T}

and an \tcode{allocator_type} identical to \tcode{allocator_traits<A>::rebind_alloc<T>}

and given an lvalue \tcode{m} of type \tcode{A},

a pointer \tcode{p} of type \tcode{T*},

an expression \tcode{v} that denotes

an lvalue of type \tcode{T} or \tcode{const T} or

an rvalue of type \tcode{const T},

and an rvalue \tcode{rv} of type \tcode{T},

the following terms are defined. If \tcode{X}

is not allocator-aware or is a specialization of \tcode{basic_string},

the terms below are defined as if \tcode{A} were

\tcode{allocator<T>} --- no allocator object needs to be created

and user specializations of \tcode{allocator<T>} are not instantiated:

\begin{itemize}

\item

\tcode{T} is \defnx{\oldconcept{DefaultInsertable} into \tcode{X}}

{\oldconceptname{DefaultInsertable} into X@\oldconcept{DefaultInsertable} into \tcode{X}}

means that the following expression is well-formed:

\begin{codeblock}

allocator_traits<A>::construct(m, p)

\end{codeblock}

\item

An element of \tcode{X} is \defn{default-inserted} if it is initialized

by evaluation of the expression

\begin{codeblock}

allocator_traits<A>::construct(m, p)

\end{codeblock}

where \tcode{p} is the address of the uninitialized storage for the element

allocated within \tcode{X}.

\item