containers.tex

%!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
Table~\ref{tab:containers.lib.summary}.

\begin{libsumtab}{Containers library summary}{tab:containers.lib.summary}
\ref{container.requirements} & Requirements                     &                           \\ \rowsep
\ref{sequences}              & Sequence containers              & \tcode{<array>}         \\
                             &                                  & \tcode{<deque>}         \\
                             &                                  & \tcode{<forward_list>}  \\
                             &                                  & \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>}         \\ \rowsep
\end{libsumtab}

\rSec1[container.requirements]{Container requirements}%
\indextext{requirements!container}

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

\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.
\enterexample
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.
\exitexample

\pnum
For the components affected by this subclause that declare an \tcode{allocator_type},
objects stored in these components shall be constructed using the
\tcode{allocator_traits<allocator_type>::rebind_traits<U>::construct} function
and destroyed using the
\tcode{allocator_traits<allocator_type>::rebind_traits<U>::destroy}
function~(\ref{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. \enternote This
means, for example, that a node-based container might need to construct nodes containing
aligned buffers and call \tcode{construct} to place the element into the buffer.
\exitnote

\pnum
In Tables~\ref{tab:containers.container.requirements},
\ref{tab:containers.reversible.requirements}, and
\ref{tab:containers.optional.operations}
\tcode{X} denotes a container class containing objects of type
\tcode{T}, \tcode{a} and \tcode{b}
denote values of type \tcode{X}, \tcode{u}
denotes an identifier, \tcode{r} denotes
a non-const value of type \tcode{X}, and \tcode{rv}
denotes a non-const rvalue of type \tcode{X}.

\begin{libreqtab5}
{Container requirements}
{tab:containers.container.requirements}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{semantics}    &   \chdr{pre-/post-condition}   &      \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{semantics}    &   \chdr{pre-/post-condition}   &      \\ \capsep
\endhead

\tcode{X::value_type}       &
 \tcode{T}                  &
                            &
 \requires\ \tcode{T} is \tcode{Erasable} from \tcode{X} (see~\ref{container.requirements.general}, below) &
 compile time               \\ \rowsep

\tcode{X::reference}        &
 \tcode{T\&}                &
                            &
                            &
 compile time               \\ \rowsep

\tcode{X::const_reference} &
 \tcode{const T\&}          &
                            &
                            &
 compile time               \\ \rowsep

\tcode{X::iterator}         &
 iterator type whose value type is \tcode{T} &
                            &
 any iterator category
 that meets the forward iterator requirements.
 convertible to \tcode{X::const_iterator}. &
 compile time               \\ \rowsep

\tcode{X::const_iterator}  &
 constant iterator type whose value type is \tcode{T} &
                            &
 any iterator category
 that meets the forward iterator requirements. &
 compile time               \\ \rowsep

\tcode{X::dif\-ference_type}    &
 signed integer type           &
                                &
 is identical to the difference type of \tcode{X::iterator} and \tcode{X::const_iterator} &
 compile time               \\ \rowsep

\tcode{X::size_type}        &
 unsigned integer type     &
                            &
 \tcode{size_type} can represent any non-negative value of \tcode{difference_type} &
 compile time                \\ \rowsep

\tcode{X u;}                &
                            &
                            &
 post: \tcode{u.empty()}    &
 constant                   \\ \rowsep

\tcode{X()}                 &
                            &
                            &
 post: \tcode{X().empty()}  &
 constant                   \\ \rowsep

\tcode{X(a)}                &
                            &
                            &
 \requires \tcode{T} is \tcode{CopyInsertable}
 into \tcode{X} (see below).\br post: \tcode{a == X(a)}.         &
 linear                     \\ \rowsep

\tcode{X u(a)}\br
\tcode{X u = a;}            &
                            &
                            &
 \requires \tcode{T} is \tcode{CopyInsertable}
 into \tcode{X} (see below).\br
 post: \tcode{u == a}       &
 linear                     \\ \rowsep

\tcode{X u(rv)}\br
\tcode{X u = rv}            &
                            &
                            &
  post: \tcode{u} shall be equal to the value that \tcode{rv} had before this construction
                            &
  (Note B)                  \\ \rowsep

\tcode{a = rv}              &
  \tcode{X\&}               &
  All existing elements of \tcode{a} are either move assigned to or destroyed   &
  \tcode{a} shall be equal to the value that \tcode{rv}
  had before this assignment   &
   linear                     \\ \rowsep

\tcode{(\&a)->\~X()}    &
 \tcode{void}               &
                            &
 the destructor is applied to every element of \tcode{a}; any memory obtained is deallocated. &
 linear                     \\ \rowsep

\tcode{a.begin()}           &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} &
                            &
                            &
 constant                   \\ \rowsep

\tcode{a.end()}             &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} &
                            &
                            &
 constant                   \\ \rowsep

\tcode{a.cbegin()}          &
 \tcode{const_iterator}     &
 \tcode{const_cast<X const\&>(a).begin();} &
                            &
 constant                   \\ \rowsep

\tcode{a.cend()}            &
 \tcode{const_iterator}     &
 \tcode{const_cast<X const\&>(a).end();} &
                            &
 constant                   \\ \rowsep

\tcode{a == b}                  &
 convertible to \tcode{bool}    &
 \tcode{==} is an equivalence relation.

 \tcode{equal(a.begin(),}
 \tcode{a.end(), b.begin(),}
 \tcode{b.end())}                                   &
 \requires\ \tcode{T} is \tcode{EqualityComparable} &
 Constant if \tcode{a.size() != b.size()},
 linear otherwise                                   \\ \rowsep

\tcode{a != b}                      &
 convertible to \tcode{bool}        &
 Equivalent to: \tcode{!(a == b)}   &
                                    &
 linear                             \\ \rowsep

\tcode{a.swap(b)}          &
 \tcode{void}               &
                            &
 exchanges the contents of \tcode{a} and \tcode{b}          &
 (Note A)                   \\ \rowsep

\tcode{swap(a, b)}          &
  \tcode{void}              &
  \tcode{a.swap(b)}         &
                            &
  (Note A)                  \\ \rowsep

\tcode{r = a}               &
 \tcode{X\&}                &
                            &
 post: \tcode{r == a}.      &
 linear                     \\ \rowsep

\tcode{a.size()}                &
 \tcode{size_type}             &
 \tcode{distance(a.begin(),}
 \tcode{a.end())}  &
                                &
 constant                       \\ \rowsep

\tcode{a.max_size()}        &
 \tcode{size_type}         &
 \tcode{distance(begin(),}
 \tcode{end())}
 for the largest possible container &
                            &
 constant                   \\ \rowsep

\tcode{a.empty()}               &
 convertible to \tcode{bool}    &
 \tcode{a.begin() ==}
 \tcode{a.end()}          &
                                &
constant                        \\

\end{libreqtab5}

Notes: the algorithm
\tcode{equal()}
is defined in Clause~\ref{algorithms}.
Those entries marked ``(Note A)'' or ``(Note B)''
have linear complexity for \tcode{array} and have constant complexity
for all other standard containers.

\pnum
The member function \tcode{size()} returns the number of elements in the container.
The number of elements is defined by the rules of
constructors, inserts, and erases.

\pnum
\tcode{begin()}
returns an iterator referring to the first element in the container.
\tcode{end()}
returns an iterator which is the past-the-end value for the container.
If the container is empty, then
\tcode{begin() == end()};

\pnum
In the expressions
\begin{codeblock}
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}).
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.
\enternote If an invocation of a constructor uses the default value of an optional
allocator argument, then the \tcode{Allocator} type must support value initialization.
\exitnote
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
\tcode{allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value},
\tcode{allocator_traits<allocator_type>::propagate_on_container_move_assignment::value},
or \tcode{alloca\-tor_traits<allocator_type>::propagate_on_container_swap::value} is 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}, shall exchange the values of \tcode{a} and
\tcode{b} without invoking any move, copy, or swap operations on the individual
container elements.
Lvalues of any \tcode{Compare}, \tcode{Pred}, or \tcode{Hash} types
belonging to \tcode{a} and \tcode{b} shall be swappable
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
lvalues of type \tcode{allocator_type} shall be swappable 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
If the iterator type of a container belongs to the bidirectional or
random access iterator categories~(\ref{iterator.requirements}),
the container is called
\term{reversible}
and satisfies the additional requirements
in Table~\ref{tab:containers.reversible.requirements}.

\begin{libreqtab4a}
{Reversible container requirements}
{tab:containers.reversible.requirements}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{pre-/post-condition}   &      \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}       &   \chdr{Return type}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{pre-/post-condition}   &      \\ \capsep
\endhead
\tcode{X::reverse_iterator}            &
iterator type whose value type is \tcode{T}    &
 \tcode{reverse_iterator<iterator>}   &
 compile time                           \\ \rowsep
\tcode{X::const_reverse_iterator}         &
 constant iterator type whose value type is \tcode{T}  &
 \tcode{reverse_iterator<const_iterator>}    &
 compile time                               \\ \rowsep
\tcode{a.rbegin()}                  &
 \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} &
 \tcode{reverse_iterator(end())}   &
 constant                           \\ \rowsep
\tcode{a.rend()}                     &
 \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} &
 \tcode{reverse_iterator(begin())}    &
 constant                           \\ \rowsep
\tcode{a.crbegin()}         &
 \tcode{const_reverse_iterator}     &
 \tcode{const_cast<X const\&>(a).rbegin()} &
 constant                   \\ \rowsep
\tcode{a.crend()}         &
 \tcode{const_reverse_iterator}     &
 \tcode{const_cast<X const\&>(a).rend()} &
 constant                   \\ \rowsep
\end{libreqtab4a}

\pnum
Unless otherwise specified (see~\ref{associative.reqmts.except}, \ref{unord.req.except}, \ref{deque.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. \enternote The \tcode{end()} iterator does not refer to any element, so it may be invalidated. \exitnote
\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
\indextext{container!contiguous}%
A \defn{contiguous container}
is a container that supports random access iterators~(\ref{random.access.iterators})
and whose member types \tcode{iterator} and \tcode{const_iterator}
are contiguous iterators~(\ref{iterator.requirements.general}).

\pnum
Table~\ref{tab:containers.optional.operations} lists operations that are provided
for some types of containers but not others. Those containers for which the
listed operations are provided shall implement the semantics described in
Table~\ref{tab:containers.optional.operations} unless otherwise stated.

\begin{libreqtab5}
{Optional container operations}
{tab:containers.optional.operations}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{semantics}    &   \chdr{pre-/post-condition}   &      \\ \capsep
\endfirsthead
\continuedcaption\\
\topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{semantics}    &   \chdr{pre-/post-condition}   &      \\ \capsep
\endhead

\tcode{a < b}                   &
 convertible to \tcode{bool}    &
 \tcode{lexicographical_compare( a.begin(), a.end(), b.begin(), b.end())} &
 pre: \tcode{<} is defined for values of \tcode{T}. \tcode{<} is a total ordering relationship.    &
 linear                     \\ \rowsep

\tcode{a > b}                   &
 convertible to \tcode{bool}    &
 \tcode{b < a}                  &
                                &
 linear                         \\ \rowsep

\tcode{a <= b}                  &
 convertible to \tcode{bool}    &
 \tcode{!(a > b)}               &
                                &
 linear                         \\ \rowsep

\tcode{a >= b}                  &
 convertible to \tcode{bool}    &
 \tcode{!(a < b)}               &
                                &
 linear                         \\
\end{libreqtab5}

Note: the algorithm
\tcode{lexicographical_compare()}
is defined in Clause~\ref{algorithms}.

\pnum
All of the containers defined in this Clause and in~(\ref{basic.string}) except \tcode{array}
meet the additional requirements of an allocator-aware container, as described in
Table~\ref{tab:containers.allocatoraware}.

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} of type (possibly \tcode{const}) \tcode{T},
and an rvalue \tcode{rv} of type \tcode{T},
the following terms are defined. If \tcode{X}
is not allocator-aware, the terms below are defined as if \tcode{A} were
\tcode{std::allocator<T>} --- no allocator object needs to be created
and user specializations of \tcode{std::allocator<T>} are not instantiated:

\begin{itemize}
\item
\tcode{T} is \defnx{\tcode{DefaultInsertable} into \tcode{X}}
{DefaultInsertable into X@\tcode{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
\tcode{T} is \defnx{\tcode{MoveInsertable} into \tcode{X}}
{MoveInsertable into X@\tcode{MoveInsertable} into \tcode{X}}
means that the following expression
is well-formed:
\begin{codeblock}
allocator_traits<A>::construct(m, p, rv)
\end{codeblock}
and its evaluation causes the following postcondition to hold: The value
of \tcode{*p} is equivalent to the value of \tcode{rv} before the evaluation.
\enternote \tcode{rv} remains a valid object. Its state is unspecified \exitnote

\item
\tcode{T} is \defnx{\tcode{CopyInsertable} into \tcode{X}}
{CopyInsertable into X@\tcode{CopyInsertable} into \tcode{X}}
means that, in addition to \tcode{T} being \tcode{MoveInsertable} into
\tcode{X}, the following expression is well-formed:
\begin{codeblock}
allocator_traits<A>::construct(m, p, v)
\end{codeblock}
and its evaluation causes the following postcondition to hold:
The value of \tcode{v} is unchanged and is equivalent to \tcode{*p}.

\item
\tcode{T} is
\defnx{\tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}}
{EmplaceConstructible into X from args@\tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}},
for zero
or more arguments \tcode{args}, means that the following expression is well-formed:
\begin{codeblock}
allocator_traits<A>::construct(m, p, args)
\end{codeblock}

\item
\tcode{T} is
\defnx{\tcode{Erasable} from \tcode{X}}
{Erasable from X@\tcode{Erasable} from \tcode{X}}
means that the following expression is well-formed:
\begin{codeblock}
allocator_traits<A>::destroy(m, p)
\end{codeblock}
\end{itemize}

\enternote
A container calls \tcode{allocator_traits<A>::construct(m, p, args)}
to construct an element at \tcode{p} using \tcode{args},
with \tcode{m == get_allocator()}.
The default \tcode{construct} in \tcode{std::allocator} will
call \tcode{::new((void*)p) T(args)},
but specialized allocators may choose a different definition.
\exitnote

\pnum
In Table~\ref{tab:containers.allocatoraware}, \tcode{X} denotes an allocator-aware container class
with a \tcode{value_type} of \tcode{T} using allocator of type \tcode{A}, \tcode{u} denotes a
variable,
\tcode{a} and \tcode{b} denote non-const lvalues of type \tcode{X},
\tcode{t} denotes an lvalue or a const rvalue of type \tcode{X}, \tcode{rv} denotes a
non-const rvalue of type \tcode{X}, and \tcode{m} is a value of type \tcode{A}.

\begin{libreqtab4a}
{Allocator-aware container requirements}
{tab:containers.allocatoraware}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{pre-/post-condition}   &      \\ \capsep
\endfirsthead
\continuedcaption\\
\hline

\lhdr{Expression}       &   \chdr{Return type}  &
\chdr{Assertion/note}   &   \rhdr{Complexity}   \\
    &   &   \chdr{pre-/post-condition}   &      \\ \capsep
\endhead

\tcode{allocator_type}		&
  \tcode{A}								&
  \requires \tcode{allocator_type::value_type} is the same as \tcode{X::value_type}.					&
  compile time										\\ \rowsep

\tcode{get_-} \tcode{allocator()}	&
  \tcode{A}								&
																				&
  constant												\\ \rowsep

\tcode{X()}\br
\tcode{X u;}							&
													&
  \requires\ \tcode{A} is \tcode{DefaultConstructible}.\br
  post: \tcode{u.empty()} returns \tcode{true},
  \tcode{u.get_allocator() == A()} &
  constant												\\ \rowsep

\tcode{X(m)}							&
																				&
post: \tcode{u.empty()} returns \tcode{true}, &
constant												\\
\tcode{X u(m);}					&
																				&
\tcode{u.get_allocator() == m} &
																				\\ \rowsep

\tcode{X(t, m)}\br
\tcode{X u(t, m);}				&
                          &
\requires\ \tcode{T} is \tcode{CopyInsertable} into \tcode{X}.\br
post: \tcode{u == t}, \tcode{u.get_allocator() == m} &
linear													\\ \rowsep

\tcode{X(rv)}\br
\tcode{X u(rv)}
           &
           &
  \requires move construction of \tcode{A} shall not exit via an exception.\br
  post: \tcode{u} shall have the same elements as \tcode{rv} had before this
  construction; the value of \tcode{u.get_allocator()} shall be the same as the
  value of \tcode{rv.get_allocator()} before this construction. &
  constant                            \\ \rowsep

\tcode{X(rv, m)}\br
\tcode{X u(rv, m);}			&
												&
  \requires\ \tcode{T} is
  \tcode{MoveInsertable} into \tcode{X}.\br
  post: \tcode{u} shall have the same elements,
  or copies of the elements, that \tcode{rv} had before
  this construction, \tcode{u.get_allocator() == m}												&
  constant if \tcode{m ==} \tcode{rv.get_allocator()}, otherwise linear	\\ \rowsep

\tcode{a = t}             &
  \tcode{X\&}             &
  \requires\ \tcode{T} is
  \tcode{CopyInsertable} into \tcode{X}
  and \tcode{CopyAssignable}.\br
  post: \tcode{a == t}    &
  linear                  \\ \rowsep

\tcode{a = rv}          &
  \tcode{X\&}           &
  \requires\ If \tcode{allocator_-}\br
  \tcode{traits<allocator_type>}\br
  \tcode{::propagate_on_container_-}\br
  \tcode{move_assignment::value} is\br
  \tcode{false}, \tcode{T} is
  \tcode{MoveInsertable} into \tcode{X} and
  \tcode{MoveAssignable}. All existing elements of \tcode{a}
  are either move assigned to or destroyed.\br
  post: \tcode{a} shall be equal to the value that \tcode{rv} had before
  this assignment.      &
  linear                \\ \rowsep

\tcode{a.swap(b)}       &
  \tcode{void}          &
  exchanges the contents of \tcode{a} and \tcode{b} &
  constant      \\ \rowsep

\end{libreqtab4a}

\rSec2[container.requirements.dataraces]{Container data races}

\pnum
For purposes of avoiding data races~(\ref{res.on.data.races}), implementations shall
consider the following functions to be \tcode{const}: \tcode{begin}, \tcode{end},
\tcode{rbegin}, \tcode{rend}, \tcode{front}, \tcode{back}, \tcode{data}, \tcode{find},
\tcode{lower_bound}, \tcode{upper_bound}, \tcode{equal_range}, \tcode{at} and, except in
associative or unordered associative containers, \tcode{operator[]}.

\pnum
Notwithstanding~(\ref{res.on.data.races}), implementations are required to avoid data
races when the contents of the contained object in different elements in the same
container, excepting \tcode{vector<bool>}, are modified concurrently.

\pnum
\enternote For a \tcode{vector<int> x} with a size greater than one, \tcode{x[1] = 5}
and \tcode{*x.begin() = 10} can be executed concurrently without a data race, but
\tcode{x[0] = 5} and \tcode{*x.begin() = 10} executed concurrently may result in a data
race.
As an exception to the general rule, for a \tcode{vector<bool> y}, \tcode{y[0] = true}
may race with \tcode{y[1] = true}.
\exitnote

\rSec2[sequence.reqmts]{Sequence containers}

\pnum
A sequence container organizes a finite set of objects, all of the same type, into a strictly
linear arrangement. The library provides four basic kinds of sequence containers:
\tcode{vector}, \tcode{forward_list}, \tcode{list}, and \tcode{deque}. In addition,
\tcode{array} is provided as a sequence container which provides limited sequence operations
because it has a fixed number of elements. The library also provides container adaptors that
make it easy to construct abstract data types, such as \tcode{stack}s or \tcode{queue}s, out of
the basic sequence container kinds (or out of other kinds of sequence containers that the user
might define).

\pnum
The sequence containers
offer the programmer different complexity trade-offs and should be used
accordingly.
\tcode{vector} or \tcode{array}
is the type of sequence container that should be used by default.
\tcode{list} or \tcode{forward_list}
should be used when there are frequent insertions and deletions from the
middle of the sequence.
\tcode{deque}
is the data structure of choice
when most insertions and deletions take place at the beginning or at the
end of the sequence.

\pnum
In Tables~\ref{tab:containers.sequence.requirements}
and \ref{tab:containers.sequence.optional},
\tcode{X} denotes a sequence container class,
\tcode{a} denotes a value of type \tcode{X} containing elements of type \tcode{T},
\tcode{u} denotes the name of a variable being declared,
\tcode{A} denotes \tcode{X::allocator_type} if
the \grammarterm{qualified-id} \tcode{X::allocator_type} is valid and denotes a
type~(\ref{temp.deduct}) and
\tcode{std::allocator<T>} if it doesn't,
\tcode{i} and \tcode{j}
denote iterators satisfying input iterator requirements
and refer to elements implicitly convertible to \tcode{value_type},
\tcode{[i, j)}
denotes a valid range,
\tcode{il} designates an object of type \tcode{initializer_list<value_type>},
\tcode{n}
denotes a value of type \tcode{X::size_type},
\tcode{p} denotes a valid const iterator to
\tcode{a}, \tcode{q}
denotes a valid dereferenceable const iterator to
\tcode{a}, \tcode{[q1, q2)}
denotes a valid range of const iterators in
\tcode{a}, \tcode{t}
denotes an lvalue or a const rvalue of
\tcode{X::value_type}, and \tcode{rv} denotes
a non-const rvalue of \tcode{X::value_type}.
\tcode{Args} denotes a template parameter pack;
\tcode{args} denotes a function parameter pack with the pattern \tcode{Args\&\&}.

\pnum
The complexities of the expressions are sequence dependent.

\begin{libreqtab3}
{Sequence container requirements (in addition to container)}
{tab:containers.sequence.requirements}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \rhdr{Assertion/note}       \\
                        &                       &   \rhdr{pre-/post-condition}   \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}       &   \chdr{Return type}  &   \rhdr{Assertion/note}       \\
                        &                       &   \rhdr{pre-/post-condition}   \\ \capsep
\endhead
\tcode{X(n, t)}\br
\tcode{X u(n, t)}   &
                &
 \requires\ \tcode{T} shall be
 \tcode{CopyInsertable} into \tcode{X}.\br
 post: \tcode{distance(begin(), end()) == n}\br
 Constructs a sequence container with \tcode{n} copies of \tcode{t}  \\ \rowsep

\tcode{X(i, j)}\br
\tcode{X u(i, j)}   &
                    &
 \requires\ \tcode{T} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.
 For \tcode{vector}, if the iterator does
 not meet the forward iterator requirements~(\ref{forward.iterators}), \tcode{T}
 shall also be
 \tcode{MoveInsertable} into \tcode{X}.
 Each iterator in the range \range{i}{j} shall be dereferenced exactly once.\br
 post: \tcode{distance(begin(), end()) ==}
 \tcode{distance(i, j)}\br
 Constructs a sequence container equal to the range \tcode{[i, j)}    \\ \rowsep

\tcode{X(il);}      &
                    &
  Equivalent to \tcode{X(il.begin(), il.end())} \\ \rowsep

\tcode{a = il;}     &
  \tcode{X\&}               &
  \requires\ \tcode{T} is
  \tcode{CopyInsertable} into \tcode{X}
  and \tcode{CopyAssignable}.
  Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. All existing
  elements of \tcode{a} are either assigned to or destroyed.\br
  \returns\ \tcode{*this}.
  \\ \rowsep

\tcode{a.emplace(p, args);}  &
 \tcode{iterator}            &
 \requires\ \tcode{T} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}. For \tcode{vector} and \tcode{deque},
 T is also
 \tcode{MoveInsertable} into \tcode{X} and \tcode{MoveAssignable}.
 \effects\ Inserts an object of type \tcode{T} constructed with
 \tcode{std::forward<Args>(args)...} before \tcode{p}.   \\ \rowsep

\tcode{a.insert(p,t)}   &
 \tcode{iterator}       &
 \requires\ \tcode{T} shall be
 \tcode{CopyInsertable} into \tcode{X}. For \tcode{vector} and \tcode{deque},
 \tcode{T} shall also be \tcode{CopyAssignable}.\br
 \effects\ Inserts a copy of \tcode{t} before \tcode{p}. \\ \rowsep

\tcode{a.insert(p,rv)}   &
 \tcode{iterator}       &
 \requires\ \tcode{T} shall be
 \tcode{MoveInsertable} into \tcode{X}. For \tcode{vector} and \tcode{deque},
  \tcode{T} shall also be \tcode{MoveAssignable}.\br
 \effects\ Inserts a copy of \tcode{rv} before \tcode{p}. \\ \rowsep

\tcode{a.insert(p,n,t)}     &
 \tcode{iterator}               &
 \requires\ \tcode{T} shall be
 \tcode{CopyInsertable} into \tcode{X}
 and \tcode{CopyAssignable}.\br
 Inserts \tcode{n} copies of \tcode{t} before \tcode{p}. \\ \rowsep

\tcode{a.insert(p,i,j)}    &
 \tcode{iterator}           &
 \requires\ \tcode{T} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.
 For \tcode{vector} and \tcode{deque}, \tcode{T} shall also be
 \tcode{MoveInsertable} into \tcode{X}, \tcode{MoveConstructible}, \tcode{MoveAssignable},
 and swappable~(\ref{swappable.requirements}).
 Each iterator in the range \range{i}{j} shall be dereferenced exactly once.\br
 pre: \tcode{i} and \tcode{j} are not iterators into \tcode{a}.\br
 Inserts copies of elements in \tcode{[i, j)} before \tcode{p}  \\ \rowsep

\tcode{a.insert(p, il);}  &
  \tcode{iterator}            &
  \tcode{a.insert(p, il.begin(), il.end())}.  \\ \rowsep

\tcode{a.erase(q)}  &
 \tcode{iterator}   &
 \requires\ For \tcode{vector} and \tcode{deque},
 \tcode{T} shall be \tcode{MoveAssignable}.\br
 \effects\ Erases the element pointed to by \tcode{q} \\ \rowsep

\tcode{a.erase(q1,q2)}  &
 \tcode{iterator}   &
 \requires\ For \tcode{vector} and \tcode{deque},
 \tcode{T} shall be \tcode{MoveAssignable}.\br
 \effects\ Erases the elements in the range \tcode{[q1, q2)}.  \\ \rowsep

\tcode{a.clear()}   &
 \tcode{void}       &
 Destroys all elements in \tcode{a}. Invalidates all references, pointers, and
 iterators referring to the elements of \tcode{a} and may invalidate the past-the-end iterator.\br
 post: \tcode{a.empty()} returns \tcode{true}.\br
 \complexity Linear.      \\ \rowsep

\tcode{a.assign(i,j)}   &
 \tcode{void}           &
 \requires\ \tcode{T} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}
 and assignable from \tcode{*i}. For \tcode{vector}, if the iterator does not
 meet the forward iterator requirements~(\ref{forward.iterators}), \tcode{T}
 shall also be
 \tcode{MoveInsertable} into \tcode{X}.\br
 Each iterator in the range \range{i}{j} shall be dereferenced exactly once.\br
 pre: \tcode{i}, \tcode{j} are not iterators into \tcode{a}.\br
 Replaces elements in \tcode{a} with a copy of \tcode{[i, j)}. \\ \rowsep

\tcode{a.assign(il)}    &
  \tcode{void}          &
  \tcode{a.assign(il.begin(), il.end())}. \\ \rowsep

\tcode{a.assign(n,t)}   &
 \tcode{void}           &
 \requires\ \tcode{T} shall be
 \tcode{CopyInsertable} into \tcode{X}
 and \tcode{CopyAssignable}.\br
 pre: \tcode{t} is not a reference into \tcode{a}.\br
 Replaces elements in \tcode{a} with \tcode{n} copies of \tcode{t}.   \\
\end{libreqtab3}

\pnum
\tcode{iterator}
and
\tcode{const_iterator}
types for sequence containers shall be at least of the forward iterator category.

\pnum
The iterator returned from
\tcode{a.insert(p, t)}
points to the copy of
\tcode{t}
inserted into
\tcode{a}.

\pnum
The iterator returned from \tcode{a.insert(p, rv)} points to the copy of \tcode{rv}
inserted into \tcode{a}.

\pnum
The iterator returned from \tcode{a.insert(p, n, t)} points to the copy of the first
element inserted into \tcode{a}, or \tcode{p} if \tcode{n == 0}.

\pnum
The iterator returned from \tcode{a.insert(p, i, j)} points to the copy of the first
element inserted into \tcode{a}, or \tcode{p} if \tcode{i == j}.

\pnum
The iterator returned from \tcode{a.insert(p, il)} points to the copy of the first
element inserted into \tcode{a}, or \tcode{p} if \tcode{il} is empty.

\pnum
The iterator returned from \tcode{a.emplace(p, args)} points to the new element
constructed from \tcode{args} into \tcode{a}.

\pnum
The iterator returned from
\tcode{a.erase(q)}
points to the element immediately following
\tcode{q}
prior to the element being erased.
If no such element exists,
\tcode{a.end()}
is returned.

\pnum
The iterator returned by
\tcode{a.erase(q1,q2)}
points to the element pointed to by
\tcode{q2}
prior to any elements being erased.
If no such element exists,
\tcode{a.end()}
is returned.

\pnum
For every sequence container defined in this Clause and in Clause~\ref{strings}:

\begin{itemize}
\item If the constructor

\begin{codeblock}
template <class InputIterator>
X(InputIterator first, InputIterator last,
  const allocator_type& alloc = allocator_type())
\end{codeblock}

is called with a type \tcode{InputIterator} that does not qualify as an input
iterator, then the constructor
shall not participate in overload resolution.

\item If the member functions of the forms:

\begin{codeblock}
template <class InputIterator>          // such as insert()
  rt fx1(const_iterator p, InputIterator first, InputIterator last);

template <class InputIterator>          // such as append(), assign()
  rt fx2(InputIterator first, InputIterator last);

template <class InputIterator>          // such as replace()
  rt fx3(const_iterator i1, const_iterator i2, InputIterator first, InputIterator last);
\end{codeblock}

are called with a type \tcode{InputIterator} that does not qualify as an input
iterator, then these functions
shall not participate in overload resolution.
\end{itemize}

\pnum
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.

\pnum
Table~\ref{tab:containers.sequence.optional} lists operations
that are provided for some types of
sequence containers but not others.
An implementation shall provide
these operations for all container types shown in the ``container''
column, and shall implement them so as to take amortized constant
time.

\begin{libreqtab4a}
{Optional sequence container operations}
{tab:containers.sequence.optional}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational semantics}       &   \rhdr{Container}    \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Operational semantics}       &   \rhdr{Container}    \\ \capsep
\endhead

\tcode{a.front()}       &
 \tcode{reference; const_reference} for constant \tcode{a}    &
 \tcode{*a.begin()}     &
 \tcode{basic_string},
 \tcode{array},
 \tcode{deque},
 \tcode{forward_list},
 \tcode{list},
 \tcode{vector}
 \\ \rowsep

\tcode{a.back()}        &
 \tcode{reference; const_reference} for constant \tcode{a}    &
 \tcode{\{ auto tmp = a.end();}\br
 \tcode{    \dcr tmp;}\br
 \tcode{    return *tmp; \}}    &
 \tcode{basic_string},
 \tcode{array},
 \tcode{deque},
 \tcode{list},
 \tcode{vector}
 \\ \rowsep

\tcode{a.emplace_-} \tcode{front(args)}      &
 \tcode{void}                &
 Prepends an object of type \tcode{T} constructed with \tcode{std::forward<Args>(args)...}.\br
 \requires\ \tcode{T} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}. &
 \tcode{deque},
 \tcode{forward_list},
 \tcode{list}
 \\ \rowsep

\tcode{a.emplace_-} \tcode{back(args)}      &
 \tcode{void}                &
 Appends an object of type \tcode{T} constructed with \tcode{std::forward<Args>(args)...}.\br
 \requires\ \tcode{T} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}. For \tcode{vector}, \tcode{T}
 shall also be
 \tcode{MoveInsertable} into \tcode{X}.
 &
 \tcode{deque},
 \tcode{list},
 \tcode{vector}
 \\ \rowsep

\tcode{a.push_front(t)} &
  \tcode{void}          &
  Prepends a copy of \tcode{t}.\br
  \requires\ \tcode{T} shall be
  \tcode{CopyInsertable} into \tcode{X}.
    &
  \tcode{deque},
  \tcode{forward_list},
  \tcode{list}
  \\ \rowsep

\tcode{a.push_front(rv)} &
  \tcode{void}          &
  Prepends a copy of \tcode{rv}.\br
  \requires\ \tcode{T} shall be
  \tcode{MoveInsertable} into \tcode{X}.
    &
  \tcode{deque},
  \tcode{forward_list},
  \tcode{list}
  \\ \rowsep

\tcode{a.push_back(t)} &
  \tcode{void}          &
  Appends a copy of \tcode{t}.\br
  \requires\ \tcode{T} shall be
  \tcode{CopyInsertable} into \tcode{X}.
    &
  \tcode{basic_string},
  \tcode{deque},
  \tcode{list},
  \tcode{vector}
  \\ \rowsep

\tcode{a.push_back(rv)} &
  \tcode{void}          &
  Appends a copy of \tcode{rv}.\br
  \requires\ \tcode{T} shall be
  \tcode{MoveInsertable} into \tcode{X}.
    &
  \tcode{basic_string},
  \tcode{deque},
  \tcode{list},
  \tcode{vector}
  \\ \rowsep

\tcode{a.pop_front()}      &
 \tcode{void}               &
 Destroys the first element.\br
 \requires\ \tcode{a.empty()} shall be \tcode{false}. &
 \tcode{deque},
 \tcode{forward_list},
 \tcode{list}
 \\ \rowsep

\tcode{a.pop_back()}       &
 \tcode{void}               &
 Destroys the last element.\br
 \requires\ \tcode{a.empty()} shall be \tcode{false}. &
 \tcode{basic_string},
 \tcode{deque},
 \tcode{list},
 \tcode{vector}
 \\ \rowsep

\tcode{a[n]}                &
 \tcode{reference; const_reference} for constant \tcode{a}    &
 \tcode{*(a.begin() + n)}   &
 \tcode{basic_string},
 \tcode{array},
 \tcode{deque},
 \tcode{vector}
 \\ \rowsep

\tcode{a.at(n)}             &
 \tcode{reference; const_reference} for constant \tcode{a}    &
 \tcode{*(a.begin() + n)}   &
 \tcode{basic_string},
 \tcode{array},
 \tcode{deque},
 \tcode{vector}
 \\

\end{libreqtab4a}

\pnum
The member function
\tcode{at()}
provides bounds-checked access to container elements.
\tcode{at()}
throws
\tcode{out_of_range}
if
\tcode{n >= a.size()}.

\rSec2[associative.reqmts]{Associative containers}

\pnum
Associative containers provide fast retrieval of data based on keys.
The library provides four basic kinds of associative containers:
\tcode{set},
\tcode{multiset},
\tcode{map}
and
\tcode{multimap}.

\pnum
Each associative container is parameterized on
\tcode{Key}
and an ordering relation
\tcode{Compare}
that induces a strict weak ordering~(\ref{alg.sorting}) on
elements of
\tcode{Key}.
In addition,
\tcode{map}
and
\tcode{multimap}
associate an arbitrary \term{mapped type}
\tcode{T}
with the
\tcode{Key}.
The object of type
\tcode{Compare}
is called the
\term{comparison object}
of a container.

\pnum
The phrase ``equivalence of keys'' means the equivalence relation imposed by the
comparison and
\textit{not}
the
\tcode{operator==}
on keys.
That is, two keys
\tcode{k1}
and
\tcode{k2}
are considered to be equivalent if for the
comparison object
\tcode{comp},
\tcode{comp(k1, k2) == false \&\& comp(k2, k1) == false}.
For any two keys
\tcode{k1}
and
\tcode{k2}
in the same container, calling
\tcode{comp(k1, k2)}
shall always return the same value.

\pnum
An associative container supports \term{unique keys} if it may contain at
most one element for each key. Otherwise, it supports \term{equivalent keys}.
The \tcode{set} and \tcode{map} classes support unique keys; the \tcode{multiset}
and \tcode{multimap} classes support equivalent keys.
For \tcode{multiset} and \tcode{multimap},
\tcode{insert}, \tcode{emplace}, and \tcode{erase} preserve the relative ordering
of equivalent elements.

\pnum
For \tcode{set} and \tcode{multiset} the value type is the same as the key type.
For \tcode{map} and \tcode{multimap} it is equal to \tcode{pair<const Key, T>}.

\pnum
\tcode{iterator}
of an associative container is of the bidirectional iterator category.
For associative containers where the value type is the same as the key type, both
\tcode{iterator}
and
\tcode{const_iterator}
are constant iterators. It is unspecified whether or not
\tcode{iterator}
and
\tcode{const_iterator}
are the same type.
\enternote \tcode{iterator} and \tcode{const_iterator} have identical semantics in this case, and \tcode{iterator} is convertible to \tcode{const_iterator}. Users can avoid violating the one-definition rule by always using \tcode{const_iterator} in their function parameter lists. \exitnote

\pnum
The associative containers meet all the requirements of Allocator-aware
containers~(\ref{container.requirements.general}), except that for
\tcode{map} and \tcode{multimap}, the requirements placed on \tcode{value_type}
in Table~\ref{tab:containers.container.requirements} apply instead to \tcode{key_type}
and \tcode{mapped_type}. \enternote For example, in some cases \tcode{key_type} and \tcode{mapped_type}
are required to be \tcode{CopyAssignable} even though the associated
\tcode{value_type}, \tcode{pair<const key_type, mapped_type>}, is not
\tcode{CopyAssignable}. \exitnote

\pnum
In Table~\ref{tab:containers.associative.requirements},
\tcode{X} denotes an associative container class,
\tcode{a} denotes a value of type \tcode{X},
\tcode{u} denotes the name of a variable being declared,
\tcode{a_uniq} denotes a value of type \tcode{X}
when \tcode{X} supports unique keys,
\tcode{a_eq} denotes a value of type \tcode{X}
when \tcode{X} supports multiple keys,
\tcode{a_tran} denotes a value of type \tcode{X} when the \grammarterm{qualified-id}
\tcode{X::key_compare::is_transparent} is valid
and denotes a type~(\ref{temp.deduct}),
\tcode{i} and \tcode{j}
satisfy input iterator requirements and refer to elements
implicitly convertible to
\tcode{value_type}, \range{i}{j}
denotes a valid range,
\tcode{p} denotes a valid const iterator to \tcode{a},
\tcode{q} denotes a valid dereferenceable const iterator to \tcode{a},
\tcode{r} denotes a valid dereferenceable iterator to \tcode{a},
\tcode{[q1, q2)} denotes a valid range of const iterators in \tcode{a},
\tcode{il} designates an object of type \tcode{initializer_list<value_type>},
\tcode{t} denotes a value of type \tcode{X::value_type},
\tcode{k} denotes a value of type \tcode{X::key_type}
and \tcode{c} denotes a value of type \tcode{X::key_compare};
\tcode{kl} is a value such that \tcode{a} is partitioned~(\ref{alg.sorting})
with respect to \tcode{c(r, kl)}, with \tcode{r} the key value of \tcode{e}
and \tcode{e} in \tcode{a};
\tcode{ku} is a value such that \tcode{a} is partitioned with respect to
\tcode{!c(ku, r)};
\tcode{ke} is a value such that \tcode{a} is partitioned with respect to
\tcode{c(r, ke)} and \tcode{!c(ke, r)}, with \tcode{c(r, ke)} implying
\tcode{!c(ke, r)}.
\tcode{A} denotes the storage allocator used by \tcode{X}, if any, or \tcode{std::allocator<X::value_type>} otherwise, and \tcode{m} denotes an allocator of a type convertible to \tcode{A}.

\begin{libreqtab4b}
{Associative container requirements (in addition to container)}
{tab:containers.associative.requirements}
\\ \topline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Assertion/note}       &   \rhdr{Complexity}   \\
                        &                       &   \chdr{pre-/post-condition}   &                       \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}       &   \chdr{Return type}  &   \chdr{Assertion/note}       &   \rhdr{Complexity}   \\
                        &                       &   \chdr{pre-/post-condition}   &                       \\ \capsep
\endhead

\tcode{X::key_type}     &
 \tcode{Key}            &
                        &
  compile time \\ \rowsep

\tcode{mapped_type} (\tcode{map} and \tcode{multimap} only) &
  \tcode{T}             &
                        &
  compile time          \\ \rowsep

\tcode{X::value_type} (\tcode{set} and \tcode{multiset} only) &
 \tcode{Key}            &
  \requires\ \tcode{value_type} is \tcode{Erasable} from \tcode{X} &
  compile time \\ \rowsep

\tcode{X::value_type} (\tcode{map} and \tcode{multimap} only) &
 \tcode{pair<const Key, T>}            &
  \requires\ \tcode{value_type} is \tcode{Erasable} from \tcode{X} &
  compile time \\ \rowsep

\tcode{X::key_compare}  &
  \tcode{Compare}       &
  defaults to \tcode{less<key_type>} &
  compile time   \\ \rowsep

\tcode{X::value_compare}           &
 a binary predicate type           &
 is the same as \tcode{key_compare} for \tcode{set} and
 \tcode{multiset}; is an ordering relation on pairs induced by the
 first component (i.e., \tcode{Key}) for \tcode{map} and \tcode{multimap}. &
 compile time                       \\ \rowsep

\tcode{X(c)}\br
\tcode{X u(c);}                         &
                                        &
  \requires\ \tcode{key_compare} is \tcode{CopyConstructible}.\br
  \effects\ Constructs an empty container.
  Uses a copy of \tcode{c} as a comparison object.  &
 constant                               \\ \rowsep

\tcode{X()}\br\tcode{X u;}                      &
                                                &
  \requires\ \tcode{key_compare} is \tcode{DefaultConstructible}.\br
  \effects\ Constructs an empty container.
  Uses \tcode{Compare()} as a comparison object  &
  constant                                       \\ \rowsep

\tcode{X(i,j,c)}\br
\tcode{X~u(i,j,c);}     &
                        &
  \requires\ \tcode{key_compare} is \tcode{CopyConstructible}.
  \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
  \effects\ Constructs an empty container and inserts elements from the
  range \tcode{[i, j)} into it; uses \tcode{c} as a comparison object. &
  $N \log N$ in general ($N$ has the value \tcode{distance(i, j)});
  linear if \tcode{[i, j)} is sorted with \tcode{value_comp()} \\ \rowsep

\tcode{X(i,j)} \tcode{X~u(i,j);}    &
                                    &
  \requires\ \tcode{key_compare} is \tcode{DefaultConstructible}.
  \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
  \effects\ Same as above, but uses \tcode{Compare()} as a comparison object  &
  same as above                      \\ \rowsep

\tcode{X(il);}            &
                          &
  Same as \tcode{X(il.begin(), il.end())}.  &
  Same as \tcode{X(il.begin(), il.end())}.  \\ \rowsep

\tcode{X(il,c);}          &
                          &
  Same as \tcode{X(il.begin(), il.end(), c)}.  &
  Same as \tcode{X(il.begin(), il.end(), c)}.  \\ \rowsep

\tcode{a = il}     &
  \tcode{X\&}               &
  \requires\ \tcode{value_type} is
  \tcode{CopyInsertable} into \tcode{X}
  and \tcode{CopyAssignable}.\br
  \effects Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. All
  existing elements of \tcode{a} are either assigned to or destroyed. &
  $N \log N$ in general (where $N$ has the value \tcode{il.size() + a.size()});
  linear if \range{il.begin()}{il.end()} is sorted with \tcode{value_comp()}.
  \\ \rowsep

\tcode{a.key_comp()}       &
 \tcode{X::key_compare}    &
 returns the comparison object out of which \tcode{a} was constructed. &
 constant                   \\ \rowsep

\tcode{a.value_comp()}     &
 \tcode{X::value_compare}  &
 returns an object of \tcode{value_compare} constructed out of the comparison object &
 constant                   \\ \rowsep

\tcode{a_uniq.} \tcode{emplace(args)} &
 \tcode{pair<iterator,} \tcode{bool>} &
  \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br
  \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with
  \tcode{std::forward<Args>(args)...} if and only if there is no
  element in the container with key equivalent to the key of \tcode{t}.
  The \tcode{bool} component of the returned
  pair is true if and only if the insertion takes place, and the iterator
  component of the pair points to the element with key equivalent to the
  key of \tcode{t}.  &
  logarithmic \\ \rowsep

\tcode{a_eq.} \tcode{emplace(args)}  &
 \tcode{iterator}    &
 \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br
 \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with
 \tcode{std::forward<Args>(args)...} and returns the iterator pointing
 to the newly inserted element.
 If a range containing elements equivalent to \tcode{t} exists in \tcode{a_eq},
 \tcode{t} is inserted at the end of that range. &
 logarithmic    \\ \rowsep

\tcode{a.emplace_hint(p, args)}  &
 \tcode{iterator}    &
 equivalent to \tcode{a.emplace(} \tcode{std::forward<Args>(args)...)}.
 Return value is an iterator pointing to the element with the key equivalent
 to the newly inserted element.
 The element is inserted as close as possible to the position just prior
 to \tcode{p}.  &
 logarithmic in general, but amortized constant if the element
 is inserted right before \tcode{p}    \\ \rowsep

\tcode{a_uniq.} \tcode{insert(t)}      &
  \tcode{pair<iterator, bool>}   &
  \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
  \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
  \tcode{CopyInsertable} into \tcode{X}.\br
  \effects\ Inserts \tcode{t} if and only if there is no element in the container
  with key equivalent to the key of \tcode{t}. The \tcode{bool} component of
  the returned pair is true if and only if the insertion
  takes place, and the \tcode{iterator}
  component of the pair points to the element with key
  equivalent to the key of \tcode{t}.    &
  logarithmic                    \\ \rowsep

\tcode{a_eq.insert(t)}        &
  \tcode{iterator}               &
  \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
  \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
  \tcode{CopyInsertable} into \tcode{X}.\br
  \effects\ Inserts \tcode{t} and returns the iterator pointing
  to the newly inserted element.
  If a range containing elements equivalent to
  \tcode{t} exists in \tcode{a_eq}, \tcode{t}
  is inserted at the end of that range. &
  logarithmic                    \\ \rowsep

\tcode{a.insert(}\br
  \tcode{p, t)}                         &
  \tcode{iterator}               &
  \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
  \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
  \tcode{CopyInsertable} into \tcode{X}.\br
  \effects\ Inserts \tcode{t} if and only if there is no element with key
  equivalent to the key of \tcode{t} in containers with unique keys;
  always inserts \tcode{t} in containers with equivalent keys. Always
  returns the iterator pointing to the element with key equivalent to
  the key of \tcode{t}. \tcode{t} is inserted as close as possible to the position
  just prior to \tcode{p}.&
  logarithmic in general, but amortized constant if \tcode{t}
  is inserted right before \tcode{p}. \\ \rowsep

\tcode{a.insert(}\br
  \tcode{i, j)}          &
  \tcode{void}                   &
  \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
  pre: \tcode{i}, \tcode{j} are not iterators into \tcode{a}.
  inserts each element from the range \range{i}{j} if and only if there
  is no element with key equivalent to the key of that element in containers
  with unique keys; always inserts that element in containers with equivalent keys.  &
  $N\log (\tcode{a.size()} + N)$ ($N$ has the value \tcode{distance(i, j)}) \\ \rowsep

\tcode{a.insert(il)}           &
  \tcode{void}                  &
  Equivalent to \tcode{a.insert(il.begin(), il.end())}. &
                                          \\ \rowsep

\tcode{a.erase(k)}              &
 \tcode{size_type}             &
 erases all elements in the container with key equivalent to
 \tcode{k}. returns the number of erased elements.  &
 $\log (\tcode{a.size()}) + \tcode{a.count(k)}$       \\ \rowsep

\tcode{a.erase(q)}              &
 \tcode{iterator}               &
 erases the element pointed to by \tcode{q}. Returns an iterator pointing to
 the element immediately following \tcode{q} prior to the element being erased.
 If no such element exists, returns \tcode{a.end()}.     &
 amortized constant             \\ \rowsep

\tcode{a.erase(r)}              &
 \tcode{iterator}               &
 erases the element pointed to by \tcode{r}. Returns an iterator pointing to
 the element immediately following \tcode{r} prior to the element being erased.
 If no such element exists, returns \tcode{a.end()}.     &
 amortized constant             \\ \rowsep

\tcode{a.erase(}\br
 \tcode{q1, q2)}  &
 \tcode{iterator}        &
 erases all the elements in the range \range{q1}{q2}. Returns an iterator pointing to
 the element pointed to by q2 prior to any elements being erased. If no such element
 exists, \tcode{a.end()} is returned.  &
 $\log (\tcode{a.size()}) + N$ where $N$ has the value \tcode{distance(q1, q2)}.    \\ \rowsep

\tcode{a.clear()}       &
 \tcode{void}           &
 \tcode{a.erase(a.begin(),a.end())}\br
 post: \tcode{a.empty()} returns \tcode{true}  &
 linear in \tcode{a.size()}.  \\ \rowsep

\tcode{a.find(k)}       &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a}.  &
 returns an iterator pointing to an element with the key equivalent
 to \tcode{k}, or \tcode{a.end()} if such an element is not found    &
 logarithmic            \\ \rowsep

\tcode{a_tran.}\br
 \tcode{find(ke)}       &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}.  &
 returns an iterator pointing to an element with key \tcode{r} such that
 \tcode{!c(r, ke) \&\& !c(ke, r)}, or \tcode{a_tran.end()} if such an element
 is not found    &
 logarithmic            \\ \rowsep

\tcode{a.count(k)}        &
 \tcode{size_type}        &
 returns the number of elements with key equivalent to \tcode{k}    &
 $\log (\tcode{a.size()}) + \tcode{a.count(k)}$   \\ \rowsep

\tcode{a_tran.}\br
 \tcode{count(ke)}        &
 \tcode{size_type}        &
 returns the number of elements with key \tcode{r} such that
 \tcode{!c(r, ke) \&\& !c(ke, r)}    &
 $\log (\tcode{a_tran.size()}) + \tcode{a_tran.count(ke)}$   \\ \rowsep

\tcode{a.lower_bound(k)}   &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a}.  &
 returns an iterator pointing to the first element with
 key not less than \tcode{k},
 or \tcode{a.end()} if such an element is not found.   &
 logarithmic            \\ \rowsep

\tcode{a_tran.}\br
 \tcode{lower_bound(kl)}   &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}.  &
 returns an iterator pointing to the first element with
 key \tcode{r} such that \tcode{!c(r, kl)},
 or \tcode{a_tran.end()} if such an element is not found.   &
 logarithmic            \\ \rowsep

\tcode{a.upper_bound(k)}       &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a}.  &
 returns an iterator pointing to the first element with
 key greater than \tcode{k},
 or \tcode{a.end()} if such an element is not found.   &
 logarithmic                    \\ \rowsep

\tcode{a_tran.}\br
 \tcode{upper_bound(ku)}       &
 \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}.  &
 returns an iterator pointing to the first element with
 key \tcode{r} such that \tcode{c(ku, r)},
 or \tcode{a_tran.end()} if such an element is not found.   &
 logarithmic                    \\ \rowsep

\tcode{a.equal_range(k)}       &
 \tcode{pair<iterator, iterator>};
 \tcode{pair<const_iterator, const_iterator>} for constant \tcode{a}.     &
 equivalent to \tcode{make_pair(a.lower_bound(k), a.upper_bound(k))}.    &
 logarithmic                    \\ \rowsep

\tcode{a_tran.}\br
 \tcode{equal_range(ke)}       &
 \tcode{pair<iterator, iterator>};
 \tcode{pair<const_iterator, const_iterator>} for constant \tcode{a_tran}.     &
 equivalent to \tcode{make_pair(}\br
 \tcode{a_tran.lower_bound(ke), a_tran.upper_bound(ke))}.    &
 logarithmic                    \\
\end{libreqtab4b}

\pnum
The \tcode{insert} and \tcode{emplace} members shall not affect the validity of
iterators and references to the container,
and the \tcode{erase} members shall invalidate only iterators and
references to the erased elements.

\pnum
The fundamental property of iterators of associative containers is that they iterate through the containers
in the non-descending order of keys where non-descending is defined by the comparison that was used to
construct them.
For any two dereferenceable iterators
\tcode{i}
and
\tcode{j}
such that distance from
\tcode{i}
to
\tcode{j}
is positive,

\begin{codeblock}
value_comp(*j, *i) == false
\end{codeblock}

\pnum
For associative containers with unique keys the stronger condition holds,

\begin{codeblock}
value_comp(*i, *j) != false.
\end{codeblock}

\pnum
When an associative container is constructed by passing a comparison object the
container shall not store a pointer or reference to the passed object,
even if that object is passed by reference.
When an associative container is copied, either through a copy constructor
or an assignment operator,
the target container shall then use the comparison object from the container
being copied,
as if that comparison object had been passed to the target container in
its constructor.

\pnum
The member function templates \tcode{find}, \tcode{count}, \tcode{lower_bound},
\tcode{upper_bound}, and \tcode{equal_range} shall not participate in overload
resolution unless the \grammarterm{qualified-id} \tcode{Compare::is_transparent} is valid
and denotes a type~(\ref{temp.deduct}).

\indextext{associative containers!exception safety}%
\indextext{associative containers!requirements}%
\rSec3[associative.reqmts.except]{Exception safety guarantees}

\pnum
For associative containers, no \tcode{clear()} function throws an exception.
\tcode{erase(k)} does not throw an exception unless that exception is thrown
by the container's \tcode{Compare} object (if any).

\pnum
For associative containers, if an exception is thrown by any operation from
within an \tcode{insert} or \tcode{emplace} function inserting a single element, the
insertion has no effect.

\pnum
For associative containers, no \tcode{swap} function throws an exception unless
that exception is thrown by the
swap of the container's \tcode{Compare} object (if any).

\indextext{unordered associative containers|(}
\indextext{associative containers!unordered|see{unordered associative containers}}
\indextext{hash tables|see{unordered associative containers}}
\rSec2[unord.req]{Unordered associative containers}

\pnum
\indextext{unordered associative containers!complexity}%
Unordered associative containers provide an ability for fast retrieval
of data based on keys.  The worst-case complexity for most operations
is linear, but the average case is much faster.  The library provides
four unordered associative containers: \tcode{unordered_set},
\tcode{unordered_map}, \tcode{unordered_multiset}, and
\tcode{unordered_multimap}.

\pnum
\indextext{unordered associative containers!lack of comparison operators}%
\indextext{unordered associative containers!requirements}%
\indextext{requirements!container!not required for unordered associated containers}%
Unordered associative containers conform to the requirements for
Containers~(\ref{container.requirements}), except that
the expressions
\tcode{a == b} and \tcode{a != b} have different semantics than for the other
container types.

\pnum
Each unordered associative container is parameterized by \tcode{Key},
by a function object type \tcode{Hash} that meets the \tcode{Hash}
requirements~(\ref{hash.requirements}) and acts as a hash function for
argument values of type \tcode{Key}, and by a binary predicate \tcode{Pred}
that induces an equivalence relation on values of type \tcode{Key}.
Additionally, \tcode{unordered_map} and \tcode{unordered_multimap} associate
an arbitrary \textit{mapped type} \tcode{T} with the \tcode{Key}.

\pnum
\indextext{unordered associative containers!hash function}%
\indextext{hash function}%
The container's object of type \tcode{Hash} --- denoted by
\tcode{hash} --- is called the \term{hash function} of the
container. The container's object of type \tcode{Pred} ---
denoted by \tcode{pred} --- is called the
\term{key equality predicate} of the container.

\pnum
\indextext{unordered associative containers!equality function}%
Two values \tcode{k1} and \tcode{k2} of type \tcode{Key} are
considered equivalent if the container's
key equality predicate returns
\tcode{true} when passed those values.  If \tcode{k1} and
\tcode{k2} are equivalent, the container's hash function shall
return the same value for both.
\enternote Thus, when an unordered associative container is instantiated with
a non-default \tcode{Pred} parameter it usually needs a non-default \tcode{Hash}
parameter as well. \exitnote
For any two keys \tcode{k1} and \tcode{k2} in the same container,
calling \tcode{pred(k1, k2)} shall always return the same value.
For any key \tcode{k} in a container, calling \tcode{hash(k)}
shall always return the same value.

\pnum
\indextext{unordered associative containers!unique keys}%
\indextext{unordered associative containers!equivalent keys}%
An unordered associative container supports \textit{unique keys} if it
may contain at most one element for each key.  Otherwise, it supports
\textit{equivalent keys}.  \tcode{unordered_set} and \tcode{unordered_map}
support unique keys. \tcode{unordered_multiset} and \tcode{unordered_multimap}
support equivalent keys.  In containers that support equivalent keys,
elements with equivalent keys are adjacent to each other
in the iteration order of the container. Thus, although the absolute order
of elements in an unordered container is not specified, its elements are
grouped into \defn{equivalent-key group}{s} such that all elements of each
group have equivalent keys. Mutating operations on unordered containers shall
preserve the relative order of elements within each equivalent-key group
unless otherwise specified.

\pnum
For \tcode{unordered_set} and \tcode{unordered_multiset} the value type is
the same as the key type.  For \tcode{unordered_map} and
\tcode{unordered_multimap} it is \tcode{std::pair<const Key,
T>}.

\pnum
For unordered containers where the value type is the same as the key
type, both \tcode{iterator} and \tcode{const_iterator} are constant
iterators. It is unspecified whether or not \tcode{iterator} and
\tcode{const_iterator} are the same type.
\enternote \tcode{iterator} and \tcode{const_iterator} have identical
semantics in this case, and \tcode{iterator} is convertible to
\tcode{const_iterator}. Users can avoid violating the one-definition rule
by always using \tcode{const_iterator} in their function parameter lists.
\exitnote

\pnum
\indextext{buckets}%
\indextext{hash code}%
The elements of an unordered associative container are organized into
\textit{buckets}.  Keys with the same hash code appear in the same
bucket.  The number of buckets is automatically increased as elements
are added to an unordered associative container, so that the average
number of elements per bucket is kept below a bound.  Rehashing
invalidates iterators, changes ordering between elements, and changes
which buckets elements appear in, but does not invalidate pointers or
references to elements. For \tcode{unordered_multiset} and
\tcode{unordered_multimap}, rehashing preserves the relative ordering of
equivalent elements.

\pnum
The unordered associative containers meet all the requirements of Allocator-aware
containers~(\ref{container.requirements.general}), except that for
\tcode{unordered_map} and \tcode{unordered_multimap}, the requirements placed on \tcode{value_type}
in Table~\ref{tab:containers.container.requirements} apply instead to \tcode{key_type}
and \tcode{mapped_type}. \enternote For example, \tcode{key_type} and \tcode{mapped_type}
are sometimes required to be \tcode{CopyAssignable} even though the associated
\tcode{value_type}, \tcode{pair<const key_type, mapped_type>}, is not
\tcode{CopyAssignable}. \exitnote

\pnum
\indextext{unordered associative containers}%
\indextext{unordered associative containers!requirements}%
\indextext{requirements!unordered associative container}%
\indextext{unordered associative containers!unique keys}%
\indextext{unordered associative containers!equivalent keys}%
\indextext{requirements!container}%
In Table~\ref{tab:HashRequirements}:
\tcode{X} denotes an unordered associative container class,
\tcode{a} denotes a value of type \tcode{X},
\tcode{b} denotes a possibly const value of type \tcode{X},
\tcode{a_uniq} denotes a value of type \tcode{X} when \tcode{X} supports unique keys,
\tcode{a_eq} denotes a value of type \tcode{X} when \tcode{X} supports equivalent keys,
\tcode{i} and \tcode{j} denote input iterators that refer to \tcode{value_type},
\tcode{[i, j)} denotes a valid range,
\tcode{p} and \tcode{q2} denote valid const iterators to \tcode{a},
\tcode{q} and \tcode{q1} denote valid dereferenceable const iterators to \tcode{a},
\tcode{r} denotes a valid dereferenceable iterator to \tcode{a},
\tcode{[q1, q2)} denotes a valid range in \tcode{a},
\tcode{il} denotes a value of type \tcode{initializer_list<value_type>},
\tcode{t} denotes a value of type \tcode{X::value_type},
\tcode{k} denotes a value of type \tcode{key_type},
\tcode{hf} denotes a possibly const value of type \tcode{hasher},
\tcode{eq} denotes a possibly const value of type \tcode{key_equal},
\tcode{n} denotes a value of type \tcode{size_type},
and \tcode{z} denotes a value of type \tcode{float}.

\begin{libreqtab4d}
  {Unordered associative container requirements (in addition to container)}
  {tab:HashRequirements}
\\ \topline
\lhdr{Expression} & \chdr{Return type}
& \chdr{Assertion/note pre-/post-condition}
& \rhdr{Complexity} \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression} & \chdr{Return type} & \chdr{Assertion/note pre-/post-condition} & \rhdr{Complexity} \\ \capsep
\endhead
%%
\tcode{X::key_type}   &
\indextext{unordered associative containers!\idxcode{key_type}}%
\indextext{\idxcode{key_type}!unordered associative containers}%
  \tcode{Key}         &
                      &
  compile time        \\ \rowsep

\tcode{X::mapped_type} (\tcode{unordered_map} and \tcode{unordered_multimap} only)  &
  \tcode{T}             &
                        &
  compile time          \\ \rowsep

\tcode{X::value_type} (\tcode{unordered_set} and \tcode{unordered_multiset} only) &
 \tcode{Key}            &
  \requires\ \tcode{value_type} is \tcode{Erasable} from \tcode{X} &
  compile time \\ \rowsep

\tcode{X::value_type} (\tcode{unordered_map} and \tcode{unordered_multimap} only) &
 \tcode{pair<const Key, T>}            &
  \requires\ \tcode{value_type} is \tcode{Erasable} from \tcode{X} &
  compile time \\ \rowsep

\tcode{X::hasher}
&   \tcode{Hash}
&   \tcode{Hash} shall be a unary function object type such that the expression
    \tcode{hf(k)} has type \tcode{std::size_t}.%
    \indextext{unordered associative containers!\idxcode{hasher}}%
    \indextext{\idxcode{hasher}!unordered associative containers}%
&   compile time
\\ \rowsep
%
\tcode{X::key_equal}
&   \tcode{Pred}
&   \tcode{Pred} shall be a binary predicate that takes two arguments
    of type \tcode{Key}.  \tcode{Pred} is an equivalence relation.%
    \indextext{unordered associative containers!\idxcode{key_equal}}%
    \indextext{\idxcode{key_equal}!unordered associative containers}%
&   compile time
\\ \rowsep
%
\tcode{X::local_iterator}
&   An iterator type whose category, value type,
    difference type, and pointer and reference types are the same as
    \tcode{X::iterator}'s. \indextext{\idxcode{local_iterator}}
&   A \tcode{local_iterator} object may be used to iterate through a
    single bucket, but may not be used to iterate across
    buckets.%
    \indextext{unordered associative containers!\idxcode{local_iterator}}%
    \indextext{\idxcode{local_iterator}!unordered associative containers}%
&   compile time
\\ \rowsep
%
\tcode{X::const_local_iterator}
&   An iterator type whose category, value type,
    difference type, and pointer and reference types are the same as
    \tcode{X::const_iterator}'s. \indextext{\idxcode{const_local_iterator}}
&   A \tcode{const_local_iterator} object may be used to iterate through a
    single bucket, but may not be used to iterate across
    buckets.%
    \indextext{unordered associative containers!\idxcode{const_local_iterator}}%
    \indextext{\idxcode{const_local_iterator}!unordered associative containers}%
&   compile time
\\ \rowsep
%
\tcode{X(n, hf, eq)}\br \tcode{X a(n, hf, eq)}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{CopyConstructible}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hf} as the hash function and \tcode{eq} as the key
equality predicate.
&   \bigoh{\tcode{n}}
\\ \rowsep
%
\tcode{X(n, hf)}\br \tcode{X a(n, hf)}
&   X
&   \requires\ \tcode{hasher} is \tcode{CopyConstructible} and \tcode{key_equal}
    is \tcode{DefaultConstructible}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hf} as the hash function and \tcode{key_equal()} as the key
equality predicate.
&   \bigoh{\tcode{n}}
\\ \rowsep
%
\tcode{X(n)}\br \tcode{X a(n)}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{DefaultConstructible}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hasher()} as the hash function and \tcode{key_equal()}
as the key equality predicate.
&   \bigoh{\tcode{n}}
\\ \rowsep
%
\tcode{X()}\br \tcode{X a}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{DefaultConstructible}.\br
    \effects\ Constructs an empty container with an unspecified number of
  buckets, using \tcode{hasher()} as the hash function and
  \tcode{key_equal()} as the key equality predicate.
&   constant
\\ \rowsep
%
\tcode{X(i, j, n, hf, eq)}\br \tcode{X a(i, j, n, hf, eq)}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{CopyConstructible}.
    \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hf} as the hash function and \tcode{eq} as the key
equality predicate, and inserts elements from \tcode{[i, j)} into it.
&   Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case
\bigoh{N^2}
\\ \rowsep
%
\tcode{X(i, j, n, hf)}\br \tcode{X a(i, j, n, hf)}
&   X
&   \requires\ \tcode{hasher} is \tcode{CopyConstructible} and \tcode{key_equal}
    is \tcode{DefaultConstructible}.
    \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hf} as the hash function and \tcode{key_equal()} as the key
equality predicate, and inserts elements from \tcode{[i, j)} into it.
&   Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case
\bigoh{N^2}
\\ \rowsep
%
\tcode{X(i, j, n)}\br \tcode{X a(i, j, n)}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{DefaultConstructible}.
    \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
    \effects\ Constructs an empty container with at least \tcode{n} buckets,
using \tcode{hasher()} as the hash function and \tcode{key_equal()}
as the key equality predicate, and inserts elements from \tcode{[i, j)}
into it.
&   Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case
\bigoh{N^2}
\\ \rowsep
%
\tcode{X(i, j)}\br \tcode{X a(i, j)}
&   X
&   \requires\ \tcode{hasher} and \tcode{key_equal} are \tcode{DefaultConstructible}.
    \tcode{value_type} is \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
    \effects\ Constructs an empty container with an unspecified number of
buckets, using \tcode{hasher()} as the hash function and
\tcode{key_equal()} as the key equality predicate, and inserts elements
from \tcode{[i, j)} into it.
&   Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case
\bigoh{N^2}
\\ \rowsep
%
\tcode{X(il)}
&   \tcode{X}
&   Same as \tcode{X(il.begin(), il.end())}.
&   Same as \tcode{X(il.begin(),} \tcode{il.end())}.
\\ \rowsep
%
\tcode{X(il, n)}
&   \tcode{X}
&   Same as \tcode{X(il.begin(), il.end(), n)}.
&   Same as \tcode{X(il.begin(),} \tcode{il.end(), n)}.
\\ \rowsep
%
\tcode{X(il, n, hf)}
&   \tcode{X}
&   Same as \tcode{X(il.begin(), il.end(), n, hf)}.
&   Same as \tcode{X(il.begin(),} \tcode{il.end(), n, hf)}.
\\ \rowsep
%
\tcode{X(il, n, hf, eq)}
&   \tcode{X}
&   Same as \tcode{X(il.begin(), il.end(), n, hf, eq)}.
&   Same as \tcode{X(il.begin(),} \tcode{il.end(), n, hf, eq)}.
\\ \rowsep
%
\tcode{X(b)}\br \tcode{X a(b)}
&   \tcode{X}
&   Copy constructor.  In addition to the requirements
    of Table~\ref{tab:containers.container.requirements}, copies the
  hash function, predicate, and maximum load factor.
&   Average case linear in \tcode{b.size()}, worst case quadratic.
\\ \rowsep
%
\tcode{a = b}
&   \tcode{X\&}
&   Copy assignment operator.  In addition to the
    requirements of Table~\ref{tab:containers.container.requirements}, copies
  the hash function, predicate, and maximum load factor.
&   Average case linear in \tcode{b.size()}, worst case quadratic.
\\ \rowsep
%
\tcode{a = il}
&   \tcode{X\&}
&   \requires\ \tcode{value_type} is
\tcode{CopyInsertable} into \tcode{X}
and \tcode{CopyAssignable}.\br
    \effects\ Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. All
    existing elements of \tcode{a} are either assigned to or destroyed.
&   Same as \tcode{a = X(il).}
\\ \rowsep
%
\tcode{b.hash_function()}
&   \tcode{hasher}
&   Returns \tcode{b}'s hash function.%
    \indextext{unordered associative containers!\idxcode{hash_function}}%
    \indextext{\idxcode{hash_function}!unordered associative containers}%
&   constant
\\ \rowsep
%
\tcode{b.key_eq()}
&   \tcode{key_equal}
&   Returns \tcode{b}'s key equality predicate.%
    \indextext{unordered associative containers!\idxcode{key_eq}}%
    \indextext{\idxcode{key_eq}!unordered associative containers}%
&   constant
\\ \rowsep
%

\tcode{a_uniq.} \tcode{emplace(args)} &
  \tcode{pair<iterator,} \tcode{bool>} &
  \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br
  \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with
  \tcode{std::forward<Args>(args)...} if and only if there is no
  element in the container with key equivalent to the key of \tcode{t}.
  The \tcode{bool} component of the returned
  pair is true if and only if the insertion takes place, and the iterator
  component of the pair points to the element with key equivalent to the
  key of \tcode{t}.  &
  Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.}\br\tcode{size()}}.
\\ \rowsep

\tcode{a_eq.}\tcode{emplace(args)}  &
  \tcode{iterator}    &
  \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br
  \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with
  \tcode{std::forward<Args>(args)...} and returns the iterator pointing
  to the newly inserted element.    &
  Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.}\br\tcode{size()}}.
\\ \rowsep

\tcode{a.emplace_hint(p, args)}  &
  \tcode{iterator}    &
  \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br
  \effects\ Equivalent to \tcode{a.emplace(} \tcode{std::forward<Args>(args)...)}.
  Return value is an iterator pointing to the element with the key equivalent
  to the newly inserted element. The \tcode{const_iterator} \tcode{p}
  is a hint pointing to where the search should start. Implementations are
  permitted to ignore the hint. &
  Average case \bigoh{1}, worst case \bigoh{\tcode{a.} \tcode{size()}}.
\\ \rowsep

\tcode{a_uniq.insert(t)}
&   \tcode{pair<iterator, bool>}
&   \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
    \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
    \tcode{CopyInsertable} into \tcode{X}.\br
    \effects\ Inserts \tcode{t} if and only if there is no element in the container
    with key equivalent to the key of \tcode{t}.  The \tcode{bool}
    component of the returned pair indicates whether the insertion
    takes place, and the \tcode{iterator} component points to the element
    with key equivalent to the key of \tcode{t}.%
    \indextext{unordered associative containers!\idxcode{insert}}%
    \indextext{\idxcode{insert}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.}\br\tcode{size()}}.
\\ \rowsep
%
\tcode{a_eq.insert(t)}
&   \tcode{iterator}
&   \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
    \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
    \tcode{CopyInsertable} into \tcode{X}.\br
    \effects\ Inserts \tcode{t}, and returns an iterator pointing to the newly
    inserted element.
    \indextext{unordered associative containers!\idxcode{insert}}%
    \indextext{\idxcode{insert}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.}\br\tcode{size()}}.
\\ \rowsep
%
\tcode{a.insert(q, t)}
&   \tcode{iterator}
&   \requires\ If \tcode{t} is a non-const rvalue expression, \tcode{value_type} shall be
    \tcode{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} shall be
    \tcode{CopyInsertable} into \tcode{X}.\br
    \effects\ Equivalent to a.insert(t).  Return value is an iterator pointing
to the element with the key equivalent to that of \tcode{t}.  The
iterator \tcode{q} is a hint pointing to where the search should
start.  Implementations are permitted to ignore the hint.%
    \indextext{unordered associative containers!\idxcode{insert}}%
    \indextext{\idxcode{insert}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}.
\\ \rowsep
%
\tcode{a.insert(i, j)}
&   \tcode{void}
&   \requires\ \tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{X} from \tcode{*i}.\br
    Pre: \tcode{i} and \tcode{j} are not iterators in \tcode{a}.
    Equivalent to \tcode{a.insert(t)} for each element in \tcode{[i,j)}.%
    \indextext{unordered associative containers!\idxcode{insert}}%
    \indextext{\idxcode{insert}!unordered associative containers}%
&   Average case \bigoh{N}, where $N$ is \tcode{distance(i, j)}.  Worst
    case $\bigoh{N(\tcode{a.size()} + 1)}$.
\\ \rowsep
%
\tcode{a.insert(il)}
&   \tcode{void}
&   Same as \tcode{a.insert(il.begin(), il.end())}.
&   Same as \tcode{a.insert(} \tcode{il.begin(),} \tcode{il.end())}.
\\ \rowsep
%
\tcode{a.erase(k)}
&   \tcode{size_type}
&   Erases all elements with key equivalent to \tcode{k}.  Returns
the number of elements erased.
&   Average case \bigoh{\tcode{a.count(k)}}.  Worst case
    \bigoh{\tcode{a.size()}}.
\\ \rowsep
%
\tcode{a.erase(q)}
&   \tcode{iterator}
&   Erases the element pointed to by \tcode{q}. Returns the
    iterator immediately following \tcode{q} prior to the erasure.
    \indextext{unordered associative containers!\idxcode{erase}}%
    \indextext{\idxcode{erase}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}.
\\ \rowsep
%
\tcode{a.erase(r)}
&   \tcode{iterator}
&   Erases the element pointed to by \tcode{r}. Returns the
    iterator immediately following \tcode{r} prior to the erasure.
    \indextext{unordered associative containers!\idxcode{erase}}%
    \indextext{\idxcode{erase}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}.
\\ \rowsep
%
\tcode{a.erase(q1, q2)}
&   \tcode{iterator}
&   Erases all elements in the range \tcode{[q1, q2)}. Returns
    the iterator immediately following the erased elements prior to the
    erasure.%
    \indextext{unordered associative containers!\idxcode{erase}}%
    \indextext{\idxcode{erase}!unordered associative containers}%
&   Average case linear in \tcode{distance(q1, q2)},
    worst case \bigoh{\tcode{a.size()}}.
\\ \rowsep
%
\tcode{a.clear()}
& \tcode{void}
& Erases all elements in the container.
   Post: \tcode{a.empty()} returns \tcode{true}%
    \indextext{unordered associative containers!\idxcode{clear}}%
    \indextext{\idxcode{clear}!unordered associative containers}%
& Linear.
\\ \rowsep
%
\tcode{b.find(k)}
&   \tcode{iterator}; \br \tcode{const_iterator} for const \tcode{b}.
&   Returns an iterator pointing to an element with key equivalent to
    \tcode{k}, or \tcode{b.end()} if no such element exists.%
    \indextext{unordered associative containers!\idxcode{find}}%
    \indextext{\idxcode{find}!unordered associative containers}%
&   Average case \bigoh{1}, worst case \bigoh{\tcode{b.size()}}.
\\ \rowsep
%
\tcode{b.count(k)}
&   \tcode{size_type}
&   Returns the number of elements with key equivalent to \tcode{k}.%
    \indextext{unordered associative containers!\idxcode{count}}%
    \indextext{\idxcode{count}!unordered associative containers}%
&   Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}.
\\ \rowsep
%
\tcode{b.equal_range(k)}
&   \tcode{pair<iterator, iterator>}; \br
    \tcode{pair<const_iterator, const_iterator>} for const \tcode{b}.
&   Returns a range containing all elements with keys equivalent to
    \tcode{k}.  Returns \tcode{make_pair(b.end(), b.end())} if
    no such elements exist.%
    \indextext{unordered associative containers!\idxcode{equal_range}}%
    \indextext{\idxcode{equal_range}!unordered associative containers}%
&   Average case \bigoh{\tcode{b.count(k)}}.  Worst case
    \bigoh{\tcode{b.size()}}.
\\ \rowsep
%
\tcode{b.bucket_count()}
&   \tcode{size_type}
&   Returns the number of buckets that \tcode{b} contains.%
    \indextext{unordered associative containers!\idxcode{bucket_count}}%
    \indextext{\idxcode{bucket_count}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.max_bucket_count()}
&   \tcode{size_type}
&   Returns an upper bound on the number of buckets that \tcode{b} might
    ever contain.%
    \indextext{unordered associative containers!\idxcode{max_bucket_count}}%
    \indextext{\idxcode{max_bucket_count}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.bucket(k)}
& \tcode{size_type}
&
  Pre: \tcode{b.bucket_count() > 0}.\br
    Returns the index of the bucket in which elements with keys equivalent
    to \tcode{k} would be found, if any such element existed.
    Post: the return value shall be in the range \tcode{[0, b.bucket_count())}.%
    \indextext{unordered associative containers!\idxcode{bucket}}%
    \indextext{\idxcode{bucket}!unordered associative containers}%
& Constant
\\ \rowsep
%
\tcode{b.bucket_size(n)}
&   \tcode{size_type}
&   Pre: \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.
    Returns the number of elements in the $\texttt{n}^{\textrm{ th}}$ bucket.%
    \indextext{unordered associative containers!\idxcode{bucket_size}}%
    \indextext{\idxcode{bucket_size}!unordered associative containers}%
&   \bigoh{\tcode{b.bucket_}\-\tcode{size(n)}}
\\ \rowsep
%
\tcode{b.begin(n)}
&   \tcode{local_iterator}; \br
    \tcode{const_local_iterator} for const \tcode{b}.
&   Pre: \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.
    \tcode{b.begin(n)} returns an iterator referring to the
    first element in the bucket. If the bucket is empty, then
    \tcode{b.begin(n) == b.end(n)}.%
    \indextext{unordered associative containers!\idxcode{begin}}%
    \indextext{\idxcode{begin}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.end(n)}
&   \tcode{local_iterator}; \br
    \tcode{const_local_iterator} for const \tcode{b}.
&   Pre: \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.
    \tcode{b.end(n)} returns an iterator which is the past-the-end
    value for the bucket.%
    \indextext{unordered associative containers!\idxcode{end}}%
    \indextext{\idxcode{end}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.cbegin(n)}
&   \tcode{const_local_iterator}
&   Pre: \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.
    Note: \tcode{[b.cbegin(n), b.cend(n))} is a valid range containing
    all of the elements in the $\texttt{n}^{\textrm{ th}}$ bucket.%
    \indextext{unordered associative containers!\idxcode{cbegin}}%
    \indextext{\idxcode{cbegin}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.cend(n)}
&   \tcode{const_local_iterator}
&   Pre: \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.%
    \indextext{unordered associative containers!\idxcode{cend}}%
    \indextext{\idxcode{cend}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.load_factor()}
&   \tcode{float}
&   Returns the average number of elements per bucket.%
    \indextext{unordered associative containers!\idxcode{load_factor}}%
    \indextext{\idxcode{load_factor}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{b.max_load_factor()}
&   \tcode{float}
&   Returns a positive number that the container attempts to keep the load factor
    less than or equal to. The container automatically increases the
    number of buckets as necessary to keep the load factor below this
    number.%
    \indextext{unordered associative containers!\idxcode{max_load_factor}}%
    \indextext{\idxcode{max_load_factor}!unordered associative containers}%
&   Constant
\\ \rowsep
%
\tcode{a.max_load_factor(z)}
&   \tcode{void}
&   Pre: \tcode{z} shall be positive.
    May change the container's maximum load factor, using \tcode{z} as a hint.%
& Constant
\\ \rowsep
%
\tcode{a.rehash(n)}
& \tcode{void}
& Post: \tcode{a.bucket_count() >= a.size() / a.max_load_factor()} and
        \tcode{a.bucket_count() >= n}.%
    \indextext{unordered associative containers!\idxcode{rehash}}%
    \indextext{\idxcode{rehash}!unordered associative containers}%
& Average case linear in \tcode{a.size()}, worst case quadratic.
\\ \rowsep

\tcode{a.reserve(n)}  &
  \tcode{void}        &
  Same as \tcode{a.rehash(ceil(n /} \tcode{a.max_load_factor()))}.  &
  Average case linear in \tcode{a.size()}, worst case quadratic. \\

\end{libreqtab4d}
\pnum
Two unordered containers \tcode{a} and \tcode{b} compare equal if
\tcode{a.size() == b.size()} and, for every equivalent-key group
\range{Ea1}{Ea2} obtained from \tcode{a.equal_range(Ea1)}, there exists an
equivalent-key group \range{Eb1}{Eb2} obtained from \tcode{b.equal_range(Ea1)},
such that
\tcode{is_permutation(Ea1, Ea2, Eb1, Eb2)} returns \tcode{true}. For
\tcode{unordered_set} and \tcode{unordered_map}, the complexity of
\tcode{operator==} (i.e., the number of calls to the \tcode{==} operator
of the \tcode{value_type}, to the predicate returned by \tcode{key_equal()},
and to the hasher returned by \tcode{hash_function()}) is proportional to
$N$ in the average case and to $N^2$ in the worst case, where $N$ is
a.size(). For \tcode{unordered_multiset} and \tcode{unordered_multimap},
the complexity of \tcode{operator==} is proportional to $\sum E_i^2$
in the average case and to $N^2$ in the worst case, where $N$ is \tcode{a.size()},
and $E_i$ is the size of the $i^{th}$ equivalent-key group in \tcode{a}.
However, if the respective elements of each corresponding pair of
equivalent-key groups $Ea_i$ and $Eb_i$ are arranged in the same order
(as is commonly the case, e.g., if \tcode{a} and \tcode{b} are unmodified copies
of the same container), then the average-case complexity for
\tcode{unordered_multiset} and \tcode{unordered_multimap} becomes
proportional to $N$ (but worst-case complexity remains \bigoh{N^2}, e.g., for
a pathologically bad hash function). The behavior of a program that uses
\tcode{operator==} or \tcode{operator!=} on unordered containers is undefined
unless the \tcode{Hash} and \tcode{Pred} function objects respectively have
the same behavior for both containers and the equality comparison operator
for \tcode{Key} is a refinement\footnote{Equality comparison is a refinement
of partitioning if no two objects that
compare equal fall into different partitions.}
of the partition into equivalent-key groups produced by \tcode{Pred}.

\pnum
\indextext{unordered associative containers!iterators}%
The iterator types \tcode{iterator} and \tcode{const_iterator} of
an unordered associative container are of at least the forward iterator
category.  For unordered associative containers where the key type and
value type are the same, both \tcode{iterator} and
\tcode{const_iterator} are const iterators.

\pnum
\indextext{unordered associative containers!iterator invalidation}%
The \tcode{insert} and \tcode{emplace} members shall not affect the validity of references to
container elements, but may invalidate all iterators to the
container.  The \tcode{erase} members shall invalidate only iterators and
references to the erased elements, and preserve the relative order of the
elements that are not erased.

\pnum
\indextext{unordered associative containers!iterator invalidation}%
\indextext{unordered associative containers!requirements}%
The \tcode{insert} and \tcode{emplace} members shall not affect the validity of iterators if
\tcode{(N+n) <= z * B}, where \tcode{N} is the number of elements in
the container prior to the insert operation, \tcode{n} is the
number of elements inserted, \tcode{B} is the container's bucket count, and
\tcode{z} is the container's maximum load factor.

\rSec3[unord.req.except]{Exception safety guarantees}

\pnum
\indextext{unordered associative containers!exception safety}%
\indextext{unordered associative containers!requirements}%
For unordered associative containers, no \tcode{clear()} function
throws an exception. \tcode{erase(k)} does not throw an
exception unless that exception is thrown by the container's \tcode{Hash} or
\tcode{Pred} object (if any).

\pnum
For unordered associative containers, if an exception is thrown by any
operation other than the container's hash function from within an
\tcode{insert} or \tcode{emplace} function inserting a single element,
the insertion has no effect.

\pnum
For unordered associative containers, no \tcode{swap} function throws
an exception unless that exception is thrown by the swap of the container's
Hash or Pred object (if any).

\pnum
\indextext{unordered associative containers!exception safety}%
\indextext{unordered associative containers!requirements}%
For unordered associative containers, if an exception is thrown
from within a \tcode{rehash()} function other than by the container's hash
function or comparison function, the \tcode{rehash()} function has no effect.

\rSec1[sequences]{Sequence containers}

\rSec2[sequences.general]{In general}

\pnum
The headers \tcode{<array>}, \tcode{<deque>}, \tcode{<forward_list>},
\tcode{<list>}, and \tcode{<vector>} define class templates that meet the
requirements for sequence containers.

\rSec2[array.syn]{Header \tcode{<array>} synopsis}

\indexlibrary{\idxhdr{array}}%
\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{array}, class template array:
  template <class T, size_t N> struct array;
  template <class T, size_t N>
    bool operator==(const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    bool operator!=(const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    bool operator< (const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    bool operator> (const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    bool operator<=(const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    bool operator>=(const array<T, N>& x, const array<T, N>& y);
  template <class T, size_t N>
    void swap(array<T, N>& x, array<T, N>& y) noexcept(noexcept(x.swap(y)));

  template <class T> class tuple_size;
  template <size_t I, class T> class tuple_element;
  template <class T, size_t N>
    struct tuple_size<array<T, N>>;
  template <size_t I, class T, size_t N>
    struct tuple_element<I, array<T, N>>;
  template <size_t I, class T, size_t N>
    constexpr T& get(array<T, N>&) noexcept;
  template <size_t I, class T, size_t N>
    constexpr T&& get(array<T, N>&&) noexcept;
  template <size_t I, class T, size_t N>
    constexpr const T& get(const array<T, N>&) noexcept;
  template <size_t I, class T, size_t N>
    constexpr const T&& get(const array<T, N>&&) noexcept;
}
\end{codeblock}

\rSec2[deque.syn]{Header \tcode{<deque>} synopsis}

\indexlibrary{\idxhdr{deque}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{deque}, class template deque:
  template <class T, class Allocator = allocator<T>> class deque;
  template <class T, class Allocator>
    bool operator==(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    void swap(deque<T, Allocator>& x, deque<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[forward_list.syn]{Header \tcode{<forward_list>} synopsis}

\indexlibrary{\idxhdr{forward_list}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{forwardlist}, class template forward_list:
  template <class T, class Allocator = allocator<T>> class forward_list;
  template <class T, class Allocator>
    bool operator==(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    void swap(forward_list<T, Allocator>& x, forward_list<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[list.syn]{Header \tcode{<list>} synopsis}

\indexlibrary{\idxhdr{list}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{list}, class template list:
  template <class T, class Allocator = allocator<T>> class list;
  template <class T, class Allocator>
    bool operator==(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    void swap(list<T, Allocator>& x, list<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[vector.syn]{Header \tcode{<vector>} synopsis}

\indexlibrary{\idxhdr{vector}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{vector}, class template vector:
  template <class T, class Allocator = allocator<T>> class vector;
  template <class T, class Allocator>
    bool operator==(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    void swap(vector<T, Allocator>& x, vector<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));

  // \ref{vector.bool}, class vector<bool>
  template <class Allocator> class vector<bool, Allocator>;

  // hash support
  template <class T> struct hash;
  template <class Allocator> struct hash<vector<bool, Allocator>>;
}
\end{codeblock}

\rSec2[array]{Class template \tcode{array}}
\indexlibrary{\idxcode{array}}%

\rSec3[array.overview]{Class template \tcode{array} overview}

\pnum
\indextext{\idxcode{array}!contiguous storage}%
The header \tcode{<array>} defines a class template for storing fixed-size
sequences of objects.
An \tcode{array} is a contiguous container~(\ref{container.requirements.general}).
An instance of \tcode{array<T, N>} stores \tcode{N} elements of type \tcode{T},
so that \tcode{size() == N} is an invariant.

\pnum
\indextext{\idxcode{array}!initialization}%
\indextext{\idxcode{array}!as aggregate}%
An \tcode{array} is an aggregate~(\ref{dcl.init.aggr}) that can be
initialized with the syntax
\begin{codeblock}
array<T, N> a = { @\textit{initializer-list}@ };
\end{codeblock}

where \textit{initializer-list} is a comma-separated list of up
to \tcode{N} elements whose types are convertible to \tcode{T}.

\pnum
\indextext{requirements!container}%
An \tcode{array} satisfies all of the requirements of a container and
of a reversible container~(\ref{container.requirements}), except that a default
constructed \tcode{array} object is not empty and that \tcode{swap} does not have constant
complexity. An \tcode{array} satisfies some of the requirements of a sequence
container~(\ref{sequence.reqmts}).
Descriptions are provided here
only for operations on \tcode{array} that are not described in
one of these tables and
for operations where there is additional semantic information.

\indexlibrary{\idxcode{array}}%
\indexlibrary{\idxcode{array}!\idxcode{begin}}%
\indexlibrary{\idxcode{begin}!\idxcode{array}}%
\indexlibrary{\idxcode{array}!\idxcode{end}}%
\indexlibrary{\idxcode{end}!\idxcode{array}}%
\indexlibrary{\idxcode{array}!\idxcode{size}}%
\indexlibrary{\idxcode{size}!\idxcode{array}}%
\indexlibrary{\idxcode{array}!\idxcode{max_size}}%
\indexlibrary{\idxcode{max_size}!\idxcode{array}}%
\begin{codeblock}
namespace std {
  template <class T, size_t N>
  struct array {
    //  types:
    typedef T&                                    reference;
    typedef const T&                              const_reference;
    typedef @\impdefx{type of \tcode{array::iterator}}\itcorr[-1]@                iterator;
    typedef @\impdefx{type of \tcode{array::const_iterator}}\itcorr[-1]@                const_iterator;
    typedef size_t                                size_type;
    typedef ptrdiff_t                             difference_type;
    typedef T                                     value_type;
    typedef T*                                    pointer;
    typedef const T*                              const_pointer;
    typedef std::reverse_iterator<iterator>       reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;

    T       elems[N];           // \expos

    // no explicit construct/copy/destroy for aggregate type

    void fill(const T& u);
    void swap(array&) noexcept(noexcept(swap(declval<T&>(), declval<T&>())));

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    constexpr bool      empty() const noexcept;
    constexpr size_type size() const noexcept;
    constexpr size_type max_size() const noexcept;

    // element access:
    reference                 operator[](size_type n);
    constexpr const_reference operator[](size_type n) const;
    reference                 at(size_type n);
    constexpr const_reference at(size_type n) const;
    reference                 front();
    constexpr const_reference front() const;
    reference                 back();
    constexpr const_reference back() const;

    T *       data() noexcept;
    const T * data() const noexcept;
  };
}
\end{codeblock}

\pnum
\enternote The member variable \tcode{elems} is shown for exposition only,
to emphasize that \tcode{array} is a class aggregate.  The name \tcode{elems}
is not part of \tcode{array}'s interface. \exitnote

\rSec3[array.cons]{\tcode{array} constructors, copy, and assignment}

\pnum
\indextext{\idxcode{array}!initialization}%
\indextext{requirements!container}%
The conditions for an aggregate~(\ref{dcl.init.aggr}) shall be
met. Class \tcode{array} relies on the implicitly-declared special
member functions~(\ref{class.ctor}, \ref{class.dtor}, and \ref{class.copy}) to
conform to the container requirements table in~\ref{container.requirements}.
In addition to the requirements specified in the container requirements table,
the implicit move constructor and move assignment operator for \tcode{array}
require that \tcode{T} be \tcode{MoveConstructible} or \tcode{MoveAssignable},
respectively.

\rSec3[array.special]{\tcode{array} specialized algorithms}

\indexlibrary{\idxcode{array}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{array}}%
\begin{itemdecl}
template <class T, size_t N>
  void swap(array<T, N>& x, array<T, N>& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}

\pnum
\complexity Linear in \tcode{N}.
\end{itemdescr}

\rSec3[array.size]{\tcode{array::size}}

\indexlibrary{\idxcode{array}!\idxcode{size}}%
\indexlibrary{\idxcode{size}!\idxcode{array}}%
\begin{itemdecl}
template <class T, size_t N> constexpr size_type array<T, N>::size() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns \tcode{N}
\end{itemdescr}

\rSec3[array.data]{\tcode{array::data}}
\indexlibrary{\idxcode{array}!\idxcode{data}}%
\indexlibrary{\idxcode{data}!\idxcode{array}}%
\begin{itemdecl}
T* data() noexcept;
const T* data() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum \returns \tcode{elems}.
\end{itemdescr}

\rSec3[array.fill]{\tcode{array::fill}}

\indexlibrary{\idxcode{array}!\idxcode{fill}}%
\indexlibrary{\idxcode{fill}!\idxcode{array}}%
\begin{itemdecl}
void fill(const T& u);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{fill_n(begin(), N, u)}
\end{itemdescr}

\rSec3[array.swap]{\tcode{array::swap}}

\indexlibrary{\idxcode{array}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{array}}%
\begin{itemdecl}
void swap(array& y) noexcept(noexcept(swap(declval<T&>(), declval<T&>())));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{swap_ranges(begin(), end(), y.begin())}

\pnum
\throws Nothing unless one of the element-wise swap calls throws an exception.

\pnum
\realnote Unlike the \tcode{swap} function for other containers, \tcode{array::swap}
takes linear time, may exit via an exception, and does not cause iterators to
become associated with the other container.
\end{itemdescr}

\rSec3[array.zero]{Zero sized arrays}

\indextext{\idxcode{array}!zero sized}%
\pnum\tcode{array} shall provide support for the special case \tcode{N == 0}.

\pnum In the case that \tcode{N == 0}, \tcode{begin() == end() ==} unique value.
The return value of \tcode{data()} is unspecified.

\pnum
The effect of calling \tcode{front()} or \tcode{back()} for a zero-sized array is
undefined.

\pnum
Member function \tcode{swap()} shall have a \grammarterm{noexcept-specification}
which is equivalent to \tcode{noexcept(true)}.

\rSec3[array.tuple]{Tuple interface to class template \tcode{array}}
\indexlibrary{\idxcode{array}}%
\indexlibrary{\idxcode{tuple}}%
\indextext{\idxcode{array}!tuple interface to}%
\indexlibrary{\idxcode{tuple_size}}%
\begin{itemdecl}
template <class T, size_t N>
  struct tuple_size<array<T, N>> : integral_constant<size_t, N> { };
\end{itemdecl}

\indexlibrary{\idxcode{tuple_element}}%
\begin{itemdecl}
tuple_element<I, array<T, N>>::type
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{I < N}. The program is ill-formed if \tcode{I} is out of bounds.

\pnum
\cvalue  The type T.
\end{itemdescr}

\indexlibrary{\idxcode{array}!\idxcode{get}}%
\indexlibrary{\idxcode{get}!\idxcode{array}}%
\begin{itemdecl}
template <size_t I, class T, size_t N>
  constexpr T& get(array<T, N>& a) noexcept;
template <size_t I, class T, size_t N>
  constexpr T&& get(array<T, N>&& a) noexcept;
template <size_t I, class T, size_t N>
  constexpr const T& get(const array<T, N>& a) noexcept;
template <size_t I, class T, size_t N>
  constexpr const T&& get(const array<T, N>&& a) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{I < N}. The program is ill-formed if \tcode{I} is out of bounds.

\pnum
\returns A reference to the \tcode{I}th element of \tcode{a},
where indexing is zero-based.
\end{itemdescr}

\rSec2[deque]{Class template \tcode{deque}}

\rSec3[deque.overview]{Class template \tcode{deque} overview}

\pnum
A
\indexlibrary{\idxcode{deque}}%
\tcode{deque}
is a sequence container that, like a
\tcode{vector}~(\ref{vector}), supports random access iterators.
In addition, it supports constant time insert and erase operations at the beginning or the end;
insert and erase in the middle take linear time.
That is, a deque is especially optimized for pushing and popping elements at the beginning and end.
As with vectors, storage management is handled automatically.

\pnum
A
\tcode{deque}
satisfies all of the requirements of a container, of a reversible container
(given in tables in~\ref{container.requirements}), of a sequence container,
including the optional sequence container requirements~(\ref{sequence.reqmts}), and of an allocator-aware container (Table~\ref{tab:containers.allocatoraware}).
Descriptions are provided here only for operations on
\tcode{deque}
that are not described in one of these tables
or for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class T, class Allocator = allocator<T>>
  class deque {
  public:
    // types:
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef T                                                   value_type;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    // \ref{deque.cons}, construct/copy/destroy:
    deque() : deque(Allocator()) { }
    explicit deque(const Allocator&);
    explicit deque(size_type n, const Allocator& = Allocator());
    deque(size_type n, const T& value, const Allocator& = Allocator());
    template <class InputIterator>
      deque(InputIterator first, InputIterator last, const Allocator& = Allocator());
    deque(const deque& x);
    deque(deque&&);
    deque(const deque&, const Allocator&);
    deque(deque&&, const Allocator&);
    deque(initializer_list<T>, const Allocator& = Allocator());

    ~deque();
    deque& operator=(const deque& x);
    deque& operator=(deque&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);
    deque& operator=(initializer_list<T>);
    template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
    void assign(size_type n, const T& t);
    void assign(initializer_list<T>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;
    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // \ref{deque.capacity}, capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;
    void      resize(size_type sz);
    void      resize(size_type sz, const T& c);
    void      shrink_to_fit();

    // element access:
    reference       operator[](size_type n);
    const_reference operator[](size_type n) const;
    reference       at(size_type n);
    const_reference at(size_type n) const;
    reference       front();
    const_reference front() const;
    reference       back();
    const_reference back() const;

    // \ref{deque.modifiers}, modifiers:
    template <class... Args> void emplace_front(Args&&... args);
    template <class... Args> void emplace_back(Args&&... args);
    template <class... Args> iterator emplace(const_iterator position, Args&&... args);

    void push_front(const T& x);
    void push_front(T&& x);
    void push_back(const T& x);
    void push_back(T&& x);

    iterator insert(const_iterator position, const T& x);
    iterator insert(const_iterator position, T&& x);
    iterator insert(const_iterator position, size_type n, const T& x);
    template <class InputIterator>
      iterator insert(const_iterator position, InputIterator first, InputIterator last);
    iterator insert(const_iterator position, initializer_list<T>);

    void pop_front();
    void pop_back();

    iterator erase(const_iterator position);
    iterator erase(const_iterator first, const_iterator last);
    void     swap(deque&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);
    void     clear() noexcept;
  };

  template <class T, class Allocator>
    bool operator==(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);

  // \ref{deque.special}, specialized algorithms:
  template <class T, class Allocator>
    void swap(deque<T, Allocator>& x, deque<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec3[deque.cons]{\tcode{deque} constructors, copy, and assignment}

\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\begin{itemdecl}
explicit deque(const Allocator&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{deque},
using the specified allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\begin{itemdecl}
explicit deque(size_type n, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{deque} with
\tcode{n} default-inserted elements using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{DefaultInsertable} into \tcode{*this}.

\pnum
\complexity Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\begin{itemdecl}
deque(size_type n, const T& value, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a
\tcode{deque}
with \tcode{n} copies of \tcode{value},
using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{CopyInsertable} into \tcode{*this}.

\pnum
\complexity
Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{deque}}%
\begin{itemdecl}
template <class InputIterator>
  deque(InputIterator first, InputIterator last, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a
\tcode{deque}
equal to the range
\range{first}{last},
using the specified allocator.

\pnum
\complexity Linear in \tcode{distance(first, last)}.
\end{itemdescr}

\rSec3[deque.capacity]{\tcode{deque} capacity}

\indexlibrary{\idxcode{resize}!\tcode{deque}}%
\begin{itemdecl}
void resize(size_type sz);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < size()}, erases the last \tcode{size() - sz} elements
from the sequence. Otherwise,
appends \tcode{sz - size()} default-inserted elements to the sequence.

\pnum
\requires \tcode{T} shall be \tcode{MoveInsertable} and \tcode{DefaultInsertable} into \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\tcode{deque}}%
\begin{itemdecl}
void resize(size_type sz, const T& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < size()}, erases the last \tcode{size() - sz} elements
from the sequence. Otherwise,
appends \tcode{sz - size()} copies of \tcode{c} to the sequence.

\pnum
\requires \tcode{T} shall be
\tcode{CopyInsertable} into \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{shrink_to_fit}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{shrink_to_fit}}%
\begin{itemdecl}
void shrink_to_fit();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{T} shall be \tcode{MoveInsertable} into \tcode{*this}.

\pnum
\complexity Linear in the size of the sequence.

\pnum
\remarks \tcode{shrink_to_fit} is a non-binding request to reduce memory use
but does not change the size of the sequence. \enternote The request is non-binding to allow latitude for implementation-specific optimizations. \exitnote
\end{itemdescr}

\rSec3[deque.modifiers]{\tcode{deque} modifiers}

\indexlibrary{\idxcode{insert}!\tcode{deque}}%
\indexlibrary{insert@\tcode{push_front}!\tcode{deque}}%
\indexlibrary{insert@\tcode{push_back}!\tcode{deque}}%
\indexlibrary{insert@\tcode{emplace}!\tcode{deque}}%
\begin{itemdecl}
iterator insert(const_iterator position, const T& x);
iterator insert(const_iterator position, T&& x);
iterator insert(const_iterator position, size_type n, const T& x);
template <class InputIterator>
  iterator insert(const_iterator position,
                  InputIterator first, InputIterator last);
iterator insert(const_iterator position, initializer_list<T>);

template <class... Args> void emplace_front(Args&&... args);
template <class... Args> void emplace_back(Args&&... args);
template <class... Args> iterator emplace(const_iterator position, Args&&... args);
void push_front(const T& x);
void push_front(T&& x);
void push_back(const T& x);
void push_back(T&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
An insertion in the middle of the deque invalidates all the iterators and
references to elements of the deque.
An insertion at either end of the
deque invalidates all the iterators to the deque, but has no effect on
the validity of references to elements of the deque.

\pnum
\notes
If an exception is thrown other than by the
copy constructor, move constructor,
assignment operator, or move assignment operator of
\tcode{T}
there are no effects.
If an exception is thrown while inserting a single element at either end,
there are no effects.
Otherwise, if an exception is thrown by the move constructor of a
non-\tcode{CopyInsertable}
\tcode{T}, the effects are unspecified.

\pnum
\complexity
The complexity is linear in the number of elements inserted plus the lesser
of the distances to the beginning and end of the deque.
Inserting a single element either at the beginning or end of a deque always takes constant time
and causes a single call to a constructor of
\tcode{T}.
\end{itemdescr}

\indexlibrary{\idxcode{erase}!\tcode{deque}}%
\begin{itemdecl}
iterator erase(const_iterator position);
iterator erase(const_iterator first, const_iterator last);
void pop_front();
void pop_back();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
An erase operation that erases the last element of a deque invalidates only the past-the-end iterator
and all iterators and references to the erased elements. An erase operation that erases the first
element of a deque but not the last element invalidates only iterators
and references to the erased elements. An erase operation
that erases neither the first element nor the last element of a deque invalidates the past-the-end
iterator and all iterators and references to all the elements of the deque.
\enternote \tcode{pop_front} and \tcode{pop_back} are erase operations. \exitnote

\pnum
\complexity
The number of calls to the destructor of \tcode{T} is the same as the
number of elements erased, but the number of calls to the assignment operator of \tcode{T} is
no more than the lesser of the number of elements before the erased elements and the number of elements after the erased elements.

\pnum
\throws
Nothing unless an exception is thrown by the copy constructor, move constructor,
assignment operator, or move assignment operator of
\tcode{T}.
\end{itemdescr}

\rSec3[deque.special]{\tcode{deque} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{deque}}%
\indexlibrary{\idxcode{deque}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Allocator>
  void swap(deque<T, Allocator>& x, deque<T, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[forwardlist]{Class template \tcode{forward_list}}

\rSec3[forwardlist.overview]{Class template \tcode{forward_list} overview}

\pnum
A \tcode{forward_list} is a container that supports forward iterators and allows
constant time insert and erase operations anywhere within the sequence, with storage
management handled automatically. Fast random access to list elements is not supported.
\enternote It is intended that \tcode{forward_list} have zero space or time overhead
relative to a hand-written C-style singly linked list. Features that would conflict with
that goal have been omitted.\exitnote

\pnum
A \tcode{forward_list} satisfies all of the requirements of a container
(Table~\ref{tab:containers.container.requirements}), except that the \tcode{size()}
member function is not provided and \tcode{operator==} has linear complexity.
A \tcode{forward_list} also satisfies all of the requirements for an allocator-aware
container (Table~\ref{tab:containers.allocatoraware}). In addition, a \tcode{forward_list}
provides the \tcode{assign} member functions
(Table~\ref{tab:containers.sequence.requirements}) and several of the optional
container requirements (Table~\ref{tab:containers.sequence.optional}).
Descriptions are provided here only for operations on
\tcode{forward_list} that are not described in that table or for operations where there
is additional semantic information.

\pnum
\enternote Modifying any list requires access to the element preceding the first element
of interest, but in a \tcode{forward_list} there is no constant-time way to access a
preceding element. For this reason, ranges that are modified, such as those supplied to
\tcode{erase} and \tcode{splice}, must be open at the beginning. \exitnote

\begin{codeblock}
namespace std {
  template <class T, class Allocator = allocator<T>>
  class forward_list {
  public:
    // types:
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef T                                                   value_type;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;

    // \ref{forwardlist.cons}, construct/copy/destroy:
    forward_list() : forward_list(Allocator()) { }
    explicit forward_list(const Allocator&);
    explicit forward_list(size_type n, const Allocator& = Allocator());
    forward_list(size_type n, const T& value,
                 const Allocator& = Allocator());
    template <class InputIterator>
      forward_list(InputIterator first, InputIterator last,
                   const Allocator& = Allocator());
    forward_list(const forward_list& x);
    forward_list(forward_list&& x);
    forward_list(const forward_list& x, const Allocator&);
    forward_list(forward_list&& x, const Allocator&);
    forward_list(initializer_list<T>, const Allocator& = Allocator());
    ~forward_list();
    forward_list& operator=(const forward_list& x);
    forward_list& operator=(forward_list&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);
    forward_list& operator=(initializer_list<T>);
    template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
    void assign(size_type n, const T& t);
    void assign(initializer_list<T>);
    allocator_type get_allocator() const noexcept;

    // \ref{forwardlist.iter}, iterators:
    iterator before_begin() noexcept;
    const_iterator before_begin() const noexcept;
    iterator begin() noexcept;
    const_iterator begin() const noexcept;
    iterator end() noexcept;
    const_iterator end() const noexcept;

    const_iterator cbegin() const noexcept;
    const_iterator cbefore_begin() const noexcept;
    const_iterator cend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type max_size() const noexcept;

    // \ref{forwardlist.access}, element access:
    reference front();
    const_reference front() const;

    // \ref{forwardlist.modifiers}, modifiers:
    template <class... Args> void emplace_front(Args&&... args);
    void push_front(const T& x);
    void push_front(T&& x);
    void pop_front();

    template <class... Args> iterator emplace_after(const_iterator position, Args&&... args);
    iterator insert_after(const_iterator position, const T& x);
    iterator insert_after(const_iterator position, T&& x);

    iterator insert_after(const_iterator position, size_type n, const T& x);
    template <class InputIterator>
      iterator insert_after(const_iterator position, InputIterator first, InputIterator last);
    iterator insert_after(const_iterator position, initializer_list<T> il);

    iterator erase_after(const_iterator position);
    iterator erase_after(const_iterator position, const_iterator last);
    void swap(forward_list&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);

    void resize(size_type sz);
    void resize(size_type sz, const value_type& c);
    void clear() noexcept;

    // \ref{forwardlist.ops}, forward_list operations:
    void splice_after(const_iterator position, forward_list& x);
    void splice_after(const_iterator position, forward_list&& x);
    void splice_after(const_iterator position, forward_list& x,
                      const_iterator i);
    void splice_after(const_iterator position, forward_list&& x,
                      const_iterator i);
    void splice_after(const_iterator position, forward_list& x,
                      const_iterator first, const_iterator last);
    void splice_after(const_iterator position, forward_list&& x,
                      const_iterator first, const_iterator last);

    void remove(const T& value);
    template <class Predicate> void remove_if(Predicate pred);

    void unique();
    template <class BinaryPredicate> void unique(BinaryPredicate binary_pred);

    void merge(forward_list& x);
    void merge(forward_list&& x);
    template <class Compare> void merge(forward_list& x, Compare comp);
    template <class Compare> void merge(forward_list&& x, Compare comp);

    void sort();
    template <class Compare> void sort(Compare comp);

    void reverse() noexcept;
  };

  template <class T, class Allocator>
    bool operator==(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);

  // \ref{forwardlist.spec}, specialized algorithms:
  template <class T, class Allocator>
    void swap(forward_list<T, Allocator>& x, forward_list<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\pnum
An incomplete type \tcode{T} may be used when instantiating \tcode{forward_list}
if the allocator satisfies the
allocator completeness requirements~\ref{allocator.requirements.completeness}.
\tcode{T} shall be complete before any member of the resulting specialization
of \tcode{forward_list} is referenced.

\rSec3[forwardlist.cons]{\tcode{forward_list} constructors, copy, assignment}

\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\begin{itemdecl}
explicit forward_list(const Allocator&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{forward_list} object using the specified allocator.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\begin{itemdecl}
explicit forward_list(size_type n, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{forward_list} object with \tcode{n}
default-inserted elements using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{DefaultInsertable} into \tcode{*this}.

\pnum
\complexity Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\begin{itemdecl}
forward_list(size_type n, const T& value, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{forward_list} object with \tcode{n} copies of \tcode{value} using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{CopyInsertable} into \tcode{*this}.

\pnum
\complexity Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{forward_list}}%
\begin{itemdecl}
template <class InputIterator>
  forward_list(InputIterator first, InputIterator last, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{forward_list} object equal to the range \range{first}{last}.

\pnum
\complexity Linear in \tcode{distance(first, last)}.
\end{itemdescr}

\rSec3[forwardlist.iter]{\tcode{forward_list} iterators}

\indexlibrary{\idxcode{before_begin}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{before_begin}}%
\indexlibrary{\idxcode{cbefore_begin}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{cbefore_begin}}%
\begin{itemdecl}
iterator before_begin() noexcept;
const_iterator before_begin() const noexcept;
const_iterator cbefore_begin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns A non-dereferenceable iterator that, when incremented, is equal to the iterator
returned by \tcode{begin()}.

\pnum
\effects \tcode{cbefore_begin()} is equivalent to
\tcode{const_cast<forward_list const\&>(*this).before_begin()}.

\pnum
\remarks \tcode{before_begin() == end()} shall equal \tcode{false}.
\end{itemdescr}

\rSec3[forwardlist.access]{\tcode{forward_list} element access}

\indexlibrary{\idxcode{front}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{front}}%
\begin{itemdecl}
reference front();
const_reference front() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{*begin()}
\end{itemdescr}

\rSec3[forwardlist.modifiers]{\tcode{forward_list} modifiers}

\pnum
None of the overloads of \tcode{insert_after} shall affect the validity of iterators and
references, and \tcode{erase_after} shall invalidate only iterators and references to
the erased elements. If an exception is thrown during \tcode{insert_after} there shall
be no effect. Inserting \tcode{n} elements into a \tcode{forward_list} is linear in
\tcode{n}, and the number of calls to the copy or move constructor of \tcode{T} is
exactly equal to \tcode{n}. Erasing \tcode{n} elements from a \tcode{forward_list} is
linear in \tcode{n} and the number of calls to the destructor of type \tcode{T} is
exactly equal to \tcode{n}.

\indexlibrary{\idxcode{emplace_front}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{emplace_front}}%
\begin{itemdecl}
template <class... Args> void emplace_front(Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Inserts an object of type \tcode{value_type} constructed with
\tcode{value_type(std::forward<Args>(\brk{}args)...)} at the beginning of the list.
\end{itemdescr}

\indexlibrary{\idxcode{push_front}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{push_front}}%
\begin{itemdecl}
void push_front(const T& x);
void push_front(T&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Inserts a copy of \tcode{x} at the beginning of the list.
\end{itemdescr}


\indexlibrary{\idxcode{pop}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{pop}}%
\begin{itemdecl}
void pop_front();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{erase_after(before_begin())}
\end{itemdescr}

\indexlibrary{\idxcode{insert_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{insert_after}}%
\begin{itemdecl}
iterator insert_after(const_iterator position, const T& x);
iterator insert_after(const_iterator position, T&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.

\pnum
\effects Inserts a copy of \tcode{x} after \tcode{position}.

\pnum
\returns An iterator pointing to the copy of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{insert_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{insert_after}}%
\begin{itemdecl}
iterator insert_after(const_iterator position, size_type n, const T& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.

\pnum
\effects Inserts \tcode{n} copies of \tcode{x} after \tcode{position}.

\pnum
\returns
An iterator pointing to the last inserted copy of \tcode{x} or \tcode{position} if \tcode{n == 0}.
\end{itemdescr}

\indexlibrary{\idxcode{insert_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{insert_after}}%
\begin{itemdecl}
template <class InputIterator>
  iterator insert_after(const_iterator position, InputIterator first, InputIterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.
\tcode{first} and \tcode{last} are not iterators in \tcode{*this}.

\pnum
\effects Inserts copies of elements in \range{first}{last} after \tcode{position}.

\pnum
\returns
An iterator pointing to the last inserted element or \tcode{position} if \tcode{first == last}.
\end{itemdescr}

\indexlibrary{\idxcode{insert_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{insert_after}}%
\begin{itemdecl}
iterator insert_after(const_iterator position, initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{insert_after(p, il.begin(), il.end())}.

\pnum
\returns
An iterator pointing to the last inserted element or \tcode{position} if \tcode{il} is empty.
\end{itemdescr}


\indexlibrary{\idxcode{emplace_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{emplace_after}}%
\begin{itemdecl}
template <class... Args>
  iterator emplace_after(const_iterator position, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.

\pnum
\effects Inserts an object of type \tcode{value_type} constructed with
\tcode{value_type(std::forward<Args>(\brk{}args)...)} after \tcode{position}.

\pnum
\returns An iterator pointing to the new object.
\end{itemdescr}

\indexlibrary{\idxcode{erase_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{erase_after}}%
\begin{itemdecl}
iterator erase_after(const_iterator position);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The iterator following \tcode{position} is dereferenceable.

\pnum
\effects Erases the element pointed to by the iterator following \tcode{position}.

\pnum
\returns An iterator pointing to the element following the one that was
erased, or \tcode{end()} if no such element exists.

\pnum
\throws Nothing.
\end{itemdescr}

\indexlibrary{\idxcode{erased}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{erased}}%
\begin{itemdecl}
iterator erase_after(const_iterator position, const_iterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires All iterators in the range \orange{position}{last} are dereferenceable.

\pnum
\effects Erases the elements in the range \orange{position}{last}.

\pnum
\returns \tcode{last}.

\pnum
\throws Nothing.
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{resize}}%
\begin{itemdecl}
void resize(size_type sz);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < distance(begin(), end())}, erases the last \tcode{distance(begin(),
end()) - sz} elements from the list. Otherwise, inserts \tcode{sz - distance(begin(), end())} default-inserted
elements at the end of the list.

\pnum
\requires \tcode{T} shall be \tcode{DefaultInsertable} into \tcode{*this}.
\end{itemdescr}

\begin{itemdecl}
void resize(size_type sz, const value_type& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < distance(begin(), end())}, erases the last \tcode{distance(begin(),
end()) - sz} elements from the list. Otherwise, inserts \tcode{sz - distance(begin(), end())}  
elements at the end of the list such that each new element, \tcode{e}, is initialized
by a method equivalent to calling
\tcode{allocator_traits<allocator_type>::construct(get_allocator(), std::addressof(e), c)}.

\pnum
\requires \tcode{T} shall be \tcode{CopyInsertable} into \tcode{*this}.
\end{itemdescr}


\indexlibrary{\idxcode{clear}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{clear}}%
\begin{itemdecl}
void clear() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Erases all elements in the range \range{begin()}{end()}.

\pnum
\remarks Does not invalidate past-the-end iterators.
\end{itemdescr}

\rSec3[forwardlist.ops]{\tcode{forward_list} operations}

\indexlibrary{\idxcode{splice_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{splice_after}}%
\begin{itemdecl}
void splice_after(const_iterator position, forward_list& x);
void splice_after(const_iterator position, forward_list&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.
\tcode{get_allocator() == x.get_allocator()}.
\tcode{\&x != this}.

\pnum
\effects Inserts the contents of \tcode{x} after
\tcode{position}, and \tcode{x} becomes empty. Pointers and references to the moved
elements of \tcode{x} now refer to those same elements but as members of \tcode{*this}.
Iterators referring to the moved elements will continue to refer to their elements, but
they now behave as iterators into \tcode{*this}, not into \tcode{x}.

\pnum
\throws Nothing.

\pnum
\complexity \bigoh{\tcode{distance(x.begin(), x.end())}}
\end{itemdescr}

\indexlibrary{\idxcode{splice_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{splice_after}}%
\begin{itemdecl}
void splice_after(const_iterator position, forward_list& x, const_iterator i);
void splice_after(const_iterator position, forward_list&& x, const_iterator i);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a dereferenceable
iterator in the range \range{begin()}{end()}.
The iterator following \tcode{i} is a dereferenceable iterator in \tcode{x}.
\tcode{get_allocator() == x.get_allocator()}.

\pnum
\effects Inserts the element following \tcode{i} into \tcode{*this}, following
\tcode{position}, and removes it from \tcode{x}.
The result is unchanged if \tcode{position == i} or \tcode{position == ++i}. Pointers
and references to \tcode{*++i} continue to refer to the same element but as a member of
\tcode{*this}. Iterators to \tcode{*++i} continue to refer to
the same element, but now behave as iterators into \tcode{*this}, not into \tcode{x}.

\pnum
\throws Nothing.

\pnum
\complexity \bigoh{1}
\end{itemdescr}

\indexlibrary{\idxcode{splice_after}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{splice_after}}%
\begin{itemdecl}
void splice_after(const_iterator position, forward_list& x,
                  const_iterator first, const_iterator last);
void splice_after(const_iterator position, forward_list&& x,
                  const_iterator first, const_iterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{position} is \tcode{before_begin()} or is a
dereferenceable iterator in the range \range{begin()}{end()}. \orange{first}{last} is a
valid range in \tcode{x}, and all iterators in the range \orange{first}{last} are
dereferenceable. \tcode{position} is not an iterator in the range \orange{first}{last}.
\tcode{get_allocator() == x.get_allocator()}.

\pnum
\effects Inserts elements in the range \orange{first}{last} after \tcode{position} and
removes the elements from \tcode{x}. Pointers and references to the moved elements of
\tcode{x} now refer to those same elements but as members of \tcode{*this}. Iterators
referring to the moved elements will continue to refer to their elements, but they now
behave as iterators into \tcode{*this}, not into \tcode{x}.

\pnum
\complexity \bigoh{\tcode{distance(first, last)}}
\end{itemdescr}

\indexlibrary{\idxcode{remove}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{remove}}%
\indexlibrary{\idxcode{remove_if}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{remove_if}}%
\begin{itemdecl}
void remove(const T& value);
template <class Predicate> void remove_if(Predicate pred);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Erases all the elements in the list referred by a list iterator \tcode{i} for
which the following conditions hold: \tcode{*i == value} (for \tcode{remove()}),
\tcode{pred(*i)} is true (for \tcode{remove_if()}).
Invalidates only the iterators and references to the erased elements.

\pnum
\throws Nothing unless an exception is thrown by the equality comparison or the
predicate.

\pnum
\remarks Stable~(\ref{algorithm.stable}).

\pnum
\complexity Exactly \tcode{distance(begin(), end())} applications of the corresponding
predicate.
\end{itemdescr}

\indexlibrary{\idxcode{unique}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{unique}}%
\begin{itemdecl}
void unique();
template <class BinaryPredicate> void unique(BinaryPredicate pred);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Erases all but the first element from every consecutive
group of equal elements referred to by the iterator \tcode{i} in the range \range{first +
1}{last} for which \tcode{*i == *(i-1)} (for the version with no arguments) or \tcode{pred(*i,
*(i - 1))} (for the version with a predicate argument) holds.
Invalidates only the iterators and references to the erased elements.

\pnum
\throws Nothing unless an exception is thrown by the equality comparison or the predicate.

\pnum
\complexity If the range \range{first}{last} is not empty, exactly \tcode{(last - first) - 1} applications of the corresponding predicate, otherwise no applications of the predicate.
\end{itemdescr}

\indexlibrary{\idxcode{merge}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{merge}}%
\begin{itemdecl}
void merge(forward_list& x);
void merge(forward_list&& x);
template <class Compare> void merge(forward_list& x, Compare comp);
template <class Compare> void merge(forward_list&& x, Compare comp);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{comp} defines a strict weak ordering~(\ref{alg.sorting}), and \tcode{*this}
and \tcode{x} are both sorted according to this ordering.
\tcode{get_allocator() == x.get_allocator()}.

\pnum
\effects Merges the two sorted ranges \tcode{[begin(), end())} and
\tcode{[x.begin(), x.end())}. \tcode{x} is empty after the merge. If an
exception is thrown other than by a comparison there are no effects.
Pointers and references to the moved elements of \tcode{x} now refer to those same elements
but as members of \tcode{*this}. Iterators referring to the moved elements will continue to
refer to their elements, but they now behave as iterators into \tcode{*this}, not into
\tcode{x}.

\pnum
\remarks Stable~(\ref{algorithm.stable}). The behavior is undefined if
\tcode{this->get_allocator() != x.get_allocator()}.

\pnum
\complexity At most \tcode{distance(begin(),
end()) + distance(x.begin(), x.end()) - 1} comparisons.
\end{itemdescr}

\indexlibrary{\idxcode{sort}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{sort}}%
\begin{itemdecl}
void sort();
template <class Compare> void sort(Compare comp);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{operator<} (for the version with no arguments) or \tcode{comp} (for the
version with a comparison argument) defines a strict weak ordering~(\ref{alg.sorting}).

\pnum
\effects Sorts the list according to the \tcode{operator<} or the \tcode{comp} function object.
If an exception is thrown the order of the elements in \tcode{*this} is unspecified.
Does not affect the validity of iterators and references.

\pnum
\remarks Stable~(\ref{algorithm.stable}).

\pnum
\complexity Approximately $N \log N$ comparisons, where $N$ is \tcode{distance(begin(), end())}.
\end{itemdescr}

\indexlibrary{\idxcode{reverse}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{reverse}}%
\begin{itemdecl}
void reverse() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Reverses the order of the elements in the list.
Does not affect the validity of iterators and references.

\pnum
\complexity Linear time.
\end{itemdescr}

\rSec3[forwardlist.spec]{\tcode{forward_list} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{forward_list}}%
\indexlibrary{\idxcode{forward_list}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Allocator>
  void swap(forward_list<T, Allocator>& x, forward_list<T, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}
\end{itemdescr}

\rSec2[list]{Class template \tcode{list}}

\rSec3[list.overview]{Class template \tcode{list} overview}

\pnum
\indexlibrary{\idxcode{list}}%
A
\tcode{list}
is a sequence container that supports
bidirectional iterators and allows constant time insert and erase
operations anywhere within the sequence, with storage management handled
automatically. Unlike vectors~(\ref{vector}) and deques~(\ref{deque}),
fast random access to list elements is not supported, but many
algorithms only need sequential access anyway.

\pnum
A \tcode{list} satisfies all of the requirements of a container, of
a reversible container (given in two tables in
\ref{container.requirements}), of a sequence container,
including most of the optional sequence container
requirements~(\ref{sequence.reqmts}), and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}).
The exceptions are the
\tcode{operator[]}
and
\tcode{at}
member functions, which are not provided.\footnote{These member functions
are only provided by containers whose iterators
are random access iterators.
}
Descriptions are provided here only for operations on
\tcode{list}
that are not described in one of these tables
or for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class T, class Allocator = allocator<T>>
  class list {
  public:
    // types:
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef T                                                   value_type;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    // \ref{list.cons}, construct/copy/destroy:
    list() : list(Allocator()) { }
    explicit list(const Allocator&);
    explicit list(size_type n, const Allocator& = Allocator());
    list(size_type n, const T& value, const Allocator& = Allocator());
    template <class InputIterator>
      list(InputIterator first, InputIterator last, const Allocator& = Allocator());
    list(const list& x);
    list(list&& x);
    list(const list&, const Allocator&);
    list(list&&, const Allocator&);
    list(initializer_list<T>, const Allocator& = Allocator());
    ~list();
    list& operator=(const list& x);
    list& operator=(list&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);
    list& operator=(initializer_list<T>);
    template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
    void assign(size_type n, const T& t);
    void assign(initializer_list<T>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;
    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // \ref{list.capacity}, capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;
    void      resize(size_type sz);
    void      resize(size_type sz, const T& c);

    // element access:
    reference       front();
    const_reference front() const;
    reference       back();
    const_reference back() const;

    // \ref{list.modifiers}, modifiers:
    template <class... Args> void emplace_front(Args&&... args);
    void pop_front();
    template <class... Args> void emplace_back(Args&&... args);
    void push_front(const T& x);
    void push_front(T&& x);
    void push_back(const T& x);
    void push_back(T&& x);
    void pop_back();

    template <class... Args> iterator emplace(const_iterator position, Args&&... args);
    iterator insert(const_iterator position, const T& x);
    iterator insert(const_iterator position, T&& x);
    iterator insert(const_iterator position, size_type n, const T& x);
    template <class InputIterator>
      iterator insert(const_iterator position, InputIterator first,
                      InputIterator last);
    iterator insert(const_iterator position, initializer_list<T> il);

    iterator erase(const_iterator position);
    iterator erase(const_iterator position, const_iterator last);
    void     swap(list&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value);
    void     clear() noexcept;

    // \ref{list.ops}, list operations:
    void splice(const_iterator position, list& x);
    void splice(const_iterator position, list&& x);
    void splice(const_iterator position, list& x, const_iterator i);
    void splice(const_iterator position, list&& x, const_iterator i);
    void splice(const_iterator position, list& x,
                const_iterator first, const_iterator last);
    void splice(const_iterator position, list&& x,
                const_iterator first, const_iterator last);

    void remove(const T& value);
    template <class Predicate> void remove_if(Predicate pred);

    void unique();
    template <class BinaryPredicate>
      void unique(BinaryPredicate binary_pred);

    void merge(list& x);
    void merge(list&& x);
    template <class Compare> void merge(list& x, Compare comp);
    template <class Compare> void merge(list&& x, Compare comp);

    void sort();
    template <class Compare> void sort(Compare comp);

    void reverse() noexcept;
  };

  template <class T, class Allocator>
    bool operator==(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const list<T, Allocator>& x, const list<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const list<T, Allocator>& x, const list<T, Allocator>& y);

  // \ref{list.special}, specialized algorithms:
  template <class T, class Allocator>
    void swap(list<T, Allocator>& x, list<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\pnum
An incomplete type \tcode{T} may be used when instantiating \tcode{list}
if the allocator satisfies the
allocator completeness requirements~\ref{allocator.requirements.completeness}.
\tcode{T} shall be complete before any member of the resulting specialization
of \tcode{list} is referenced.

\rSec3[list.cons]{\tcode{list} constructors, copy, and assignment}

\indexlibrary{\idxcode{list}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{list}}%
\begin{itemdecl}
explicit list(const Allocator&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty list, using the specified allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{list}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{list}}%
\begin{itemdecl}
explicit list(size_type n, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{list} with
\tcode{n} default-inserted elements using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{DefaultInsertable} into \tcode{*this}.

\pnum
\complexity
Linear in
\tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{list}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{list}}%
\begin{itemdecl}
list(size_type n, const T& value, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a
\tcode{list}
with
\tcode{n}
copies of
\tcode{value},
using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{CopyInsertable} into \tcode{*this}.

\pnum
\complexity
Linear in
\tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{list}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{list}}%
\begin{itemdecl}
template <class InputIterator>
  list(InputIterator first, InputIterator last, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a
\tcode{list}
equal to the range
\range{first}{last}.

\pnum
\complexity
Linear in
\tcode{distance(first, last)}.
\end{itemdescr}

\rSec3[list.capacity]{\tcode{list} capacity}

\indexlibrary{\idxcode{resize}!\tcode{list}}%
\begin{itemdecl}
void resize(size_type sz);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{size() < sz},
appends \tcode{sz - size()} default-inserted elements to the
sequence.
If \tcode{sz <= size()}, equivalent to

\begin{codeblock}
list<T>::iterator it = begin();
advance(it, sz);
erase(it, end());
\end{codeblock}


\pnum
\requires \tcode{T} shall be
\tcode{DefaultInsertable} into \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\tcode{list}}%
\begin{itemdecl}
void resize(size_type sz, const T& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
if (sz > size())
  insert(end(), sz-size(), c);
else if (sz < size()) {
  iterator i = begin();
  advance(i, sz);
  erase(i, end());
}
else
  ;                 // do nothing
\end{codeblock}

\pnum
\requires \tcode{T} shall be \tcode{CopyInsertable} into \tcode{*this}.
\end{itemdescr}

\rSec3[list.modifiers]{\tcode{list} modifiers}

\indexlibrary{\idxcode{insert}!\tcode{list}}%
\begin{itemdecl}
iterator insert(const_iterator position, const T& x);
iterator insert(const_iterator position, T&& x);
iterator insert(const_iterator position, size_type n, const T& x);
template <class InputIterator>
  iterator insert(const_iterator position, InputIterator first,
                  InputIterator last);
iterator insert(const_iterator position, initializer_list<T>);

template <class... Args> void emplace_front(Args&&... args);
template <class... Args> void emplace_back(Args&&... args);
template <class... Args> iterator emplace(const_iterator position, Args&&... args);
void push_front(const T& x);
void push_front(T&& x);
void push_back(const T& x);
void push_back(T&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
Does not affect the validity of iterators and references.
If an exception is thrown there are no effects.

\pnum
\complexity
Insertion of a single element into a list takes constant time and
exactly one call to a constructor of
\tcode{T}. Insertion of multiple elements into a list is linear in the
number of elements inserted, and the number of calls to the copy
constructor or move constructor of \tcode{T} is exactly equal
to the number of elements inserted.
\end{itemdescr}

\indexlibrary{\idxcode{erase}!\tcode{list}}%
\begin{itemdecl}
iterator erase(const_iterator position);
iterator erase(const_iterator first, const_iterator last);

void pop_front();
void pop_back();
void clear() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Invalidates only the iterators and references to the erased elements.

\pnum
\throws Nothing.

\pnum
\complexity
Erasing a single element is a constant time operation with a single call to the destructor of
\tcode{T}.
Erasing a range in a list is linear time in the
size of the range and the number of calls to the destructor of type
\tcode{T}
is exactly equal to the size of the range.
\end{itemdescr}

\rSec3[list.ops]{\tcode{list} operations}

\pnum
Since lists allow fast insertion and erasing from the middle of a list, certain
operations are provided specifically for them.\footnote{As specified
in~\ref{allocator.requirements}, the requirements in this Clause apply only to
lists whose allocators compare equal.}

\pnum
\tcode{list} provides three splice operations that destructively move elements from one list to
another. The behavior of splice operations is undefined if \tcode{get_allocator() !=
x.get_allocator()}.

\indexlibrary{\idxcode{splice}!\tcode{list}}%
\begin{itemdecl}
void splice(const_iterator position, list& x);
void splice(const_iterator position, list&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{\&x != this}.

\pnum
\effects
Inserts the contents of
\tcode{x}
before
\tcode{position}
and
\tcode{x}
becomes empty.
Pointers and references to the moved elements of
\tcode{x}
now refer to those same elements but as members of
\tcode{*this}.
Iterators referring to the moved elements will continue to refer to their
elements, but they now behave as iterators into
\tcode{*this},
not into
\tcode{x}.

\pnum
\throws Nothing.

\pnum
\complexity
Constant time.
\end{itemdescr}

\indexlibrary{\idxcode{splice}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{splice}}%
\begin{itemdecl}
void splice(const_iterator position, list& x, const_iterator i);
void splice(const_iterator position, list&& x, const_iterator i);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Inserts an element pointed to by
\tcode{i}
from list
\tcode{x}
before \tcode{position} and removes the element from
\tcode{x}.
The result is unchanged if
\tcode{position == i}
or
\tcode{position == ++i}.
Pointers and references to
\tcode{*i}
continue to refer to this same element but as a member of
\tcode{*this}.
Iterators
to
\tcode{*i}
(including
\tcode{i}
itself) continue to refer to the same element, but now behave as iterators into
\tcode{*this},
not into
\tcode{x}.

\pnum
\requires
\tcode{i}
is a valid dereferenceable iterator of
\tcode{x}.

\pnum
\throws Nothing.

\pnum
\complexity
Constant time.
\end{itemdescr}

\indexlibrary{\idxcode{splice}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{splice}}%
\begin{itemdecl}
void splice(const_iterator position, list& x, const_iterator first,
            const_iterator last);
void splice(const_iterator position, list&& x, const_iterator first,
            const_iterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Inserts elements in the range
\range{first}{last}
before
\tcode{position}
and removes the elements from
\tcode{x}.

\pnum
\requires
\tcode{[first, last)}
is a valid range in
\tcode{x}.
The result is undefined if
\tcode{position}
is an iterator in the range
\range{first}{last}.
Pointers and references to the moved elements of
\tcode{x}
now refer to those same elements but as members of
\tcode{*this}.
Iterators referring to the moved elements will continue to refer to their
elements, but they now behave as iterators into
\tcode{*this},
not into
\tcode{x}.

\pnum
\throws Nothing.

\pnum
\complexity
Constant time if
\tcode{\&x == this};
otherwise, linear time.
\end{itemdescr}

\indexlibrary{\idxcode{remove}!\tcode{list}}%
\begin{itemdecl}
void remove(const T& value);
template <class Predicate> void remove_if(Predicate pred);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Erases all the elements in the list referred by a list iterator \tcode{i} for which the
following conditions hold: \tcode{*i == value, pred(*i) != false}.
Invalidates only the iterators and references to the erased elements.

\pnum
\throws
Nothing unless an exception is thrown by
\tcode{*i == value}
or
\tcode{pred(*i) != false}.

\pnum
\remarks Stable~(\ref{algorithm.stable}).

\pnum
\complexity
Exactly
\tcode{size()}
applications of the corresponding predicate.
\end{itemdescr}

\indexlibrary{\idxcode{unique}!\tcode{list}}%
\begin{itemdecl}
void unique();
template <class BinaryPredicate> void unique(BinaryPredicate binary_pred);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Erases all but the first element from every
consecutive group of equal elements referred to by the iterator \tcode{i} in the range
\range{first + 1}{last} for which \tcode{*i == *(i-1)} (for the version of
\tcode{unique} with no arguments) or \tcode{pred(*i, *(i - 1))} (for the version of
\tcode{unique} with a predicate argument) holds.
Invalidates only the iterators and references to the erased elements.

\pnum
\throws
Nothing unless an exception is thrown by
\tcode{*i == *(i-1)}
or
\tcode{pred(*i, *(i - 1))}

\pnum
\complexity
If the range
\tcode{[first, last)}
is not empty, exactly
\tcode{(last - first) - 1}
applications of the corresponding predicate,
otherwise no applications of the predicate.
\end{itemdescr}

\indexlibrary{\idxcode{merge}!\tcode{list}}%
\begin{itemdecl}
void merge(list& x);
void merge(list&& x);
template <class Compare> void merge(list& x, Compare comp);
template <class Compare> void merge(list&& x, Compare comp);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{comp} shall define a strict weak ordering~(\ref{alg.sorting}), and both the list and the argument list shall be
sorted according to this ordering.

\pnum
\effects
If \tcode{(\&x == this)} does nothing; otherwise, merges the two sorted ranges \tcode{[begin(),
end())} and \tcode{[x.\brk{}begin(), x.end())}. The result is a range in which the elements
will be sorted in non-decreasing order according to the ordering defined by \tcode{comp}; that
is, for every iterator \tcode{i}, in the range other than the first, the condition
\tcode{comp(*i, *(i - 1))} will be false.
Pointers and references to the moved elements of \tcode{x} now refer to those same elements
but as members of \tcode{*this}. Iterators referring to the moved elements will continue to
refer to their elements, but they now behave as iterators into \tcode{*this}, not into
\tcode{x}.

\pnum
\remarks Stable~(\ref{algorithm.stable}). If \tcode{(\&x != this)} the range \tcode{[x.begin(), x.end())}
is empty after the merge.
No elements are copied by this operation. The behavior is undefined if
\tcode{this->get_allocator() != x.get_allocator()}.

\pnum
\complexity
At most
\tcode{size() + x.size() - 1}
applications of \tcode{comp} if
\tcode{(\&x != this)};
otherwise, no applications of \tcode{comp} are performed.
If an exception is thrown other than by a comparison there are no effects.
\end{itemdescr}

\indexlibrary{\idxcode{reverse}!\tcode{list}}%
\begin{itemdecl}
void reverse() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Reverses the order of the elements in the list.
Does not affect the validity of iterators and references.

\pnum
\complexity
Linear time.
\end{itemdescr}

\indexlibrary{\idxcode{sort}!\tcode{list}}%
\begin{itemdecl}
void sort();
template <class Compare> void sort(Compare comp);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{operator<}
(for the first
version)
or
\tcode{comp}
(for the second version)
shall define a strict weak ordering~(\ref{alg.sorting}).

\pnum
\effects
Sorts the list according to the \tcode{operator<} or a \tcode{Compare} function object.
Does not affect the validity of iterators and references.

\pnum
\remarks Stable~(\ref{algorithm.stable}).

\pnum
\complexity
Approximately
$N \log(N)$
comparisons, where
\tcode{N == size()}.
\end{itemdescr}

\rSec3[list.special]{\tcode{list} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{list}}%
\indexlibrary{\idxcode{list}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Allocator>
  void swap(list<T, Allocator>& x, list<T, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[vector]{Class template \tcode{vector}}

\rSec3[vector.overview]{Class template \tcode{vector} overview}

\pnum
\indexlibrary{\idxcode{vector}}%
A
\tcode{vector}
is a sequence container that supports
(amortized) constant time insert and erase operations at the end;
insert and erase in the middle take linear time.
Storage management is handled automatically, though hints can be given
to improve efficiency.

\pnum
A \tcode{vector} satisfies all of the requirements of a container and of a
reversible container (given in two tables in~\ref{container.requirements}), of a
sequence container, including most of the optional sequence container
requirements~(\ref{sequence.reqmts}), of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}),
and, for an element type other than \tcode{bool},
of a contiguous container~(\ref{container.requirements.general}).
The exceptions are the
\tcode{push_front}, \tcode{pop_front}, and \tcode{emplace_front} member functions, which are not
provided. Descriptions are provided here only for operations on \tcode{vector}
that are not described in one of these tables or for operations where there is
additional semantic information.

\begin{codeblock}
namespace std {
  template <class T, class Allocator = allocator<T>>
  class vector {
  public:
    // types:
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef T                                                   value_type;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    // \ref{vector.cons}, construct/copy/destroy:
    vector() noexcept(noexcept(Allocator())) : vector(Allocator()) { }
    explicit vector(const Allocator&) noexcept;
    explicit vector(size_type n, const Allocator& = Allocator());
    vector(size_type n, const T& value, const Allocator& = Allocator());
    template <class InputIterator>
      vector(InputIterator first, InputIterator last, const Allocator& = Allocator());
    vector(const vector& x);
    vector(vector&&) noexcept;
    vector(const vector&, const Allocator&);
    vector(vector&&, const Allocator&);
    vector(initializer_list<T>, const Allocator& = Allocator());
    ~vector();
    vector& operator=(const vector& x);
    vector& operator=(vector&& x)
      noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
               allocator_traits<Allocator>::is_always_equal::value);
    vector& operator=(initializer_list<T>);
    template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
    void assign(size_type n, const T& u);
    void assign(initializer_list<T>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;
    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // \ref{vector.capacity}, capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;
    size_type capacity() const noexcept;
    void      resize(size_type sz);
    void      resize(size_type sz, const T& c);
    void      reserve(size_type n);
    void      shrink_to_fit();

    // element access:
    reference       operator[](size_type n);
    const_reference operator[](size_type n) const;
    const_reference at(size_type n) const;
    reference       at(size_type n);
    reference       front();
    const_reference front() const;
    reference       back();
    const_reference back() const;

    // \ref{vector.data}, data access
    T*       data() noexcept;
    const T* data() const noexcept;

    // \ref{vector.modifiers}, modifiers:
    template <class... Args> void emplace_back(Args&&... args);
    void push_back(const T& x);
    void push_back(T&& x);
    void pop_back();

    template <class... Args> iterator emplace(const_iterator position, Args&&... args);
    iterator insert(const_iterator position, const T& x);
    iterator insert(const_iterator position, T&& x);
    iterator insert(const_iterator position, size_type n, const T& x);
    template <class InputIterator>
      iterator insert(const_iterator position, InputIterator first, InputIterator last);
    iterator insert(const_iterator position, initializer_list<T> il);
    iterator erase(const_iterator position);
    iterator erase(const_iterator first, const_iterator last);
    void     swap(vector&)
      noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
               allocator_traits<Allocator>::is_always_equal::value);
    void     clear() noexcept;
  };

  template <class T, class Allocator>
    bool operator==(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator< (const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator!=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator> (const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator>=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
  template <class T, class Allocator>
    bool operator<=(const vector<T, Allocator>& x, const vector<T, Allocator>& y);

  // \ref{vector.special}, specialized algorithms:
  template <class T, class Allocator>
    void swap(vector<T, Allocator>& x, vector<T, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}%
\indexlibrary{\idxcode{vector}!\tcode{operator==}}%
\indexlibrary{\idxcode{vector}!\tcode{operator<}}

\pnum
An incomplete type \tcode{T} may be used when instantiating \tcode{vector}
if the allocator satisfies the
allocator completeness requirements~\ref{allocator.requirements.completeness}.
\tcode{T} shall be complete before any member of the resulting specialization
of \tcode{vector} is referenced.

\rSec3[vector.cons]{\tcode{vector} constructors, copy, and assignment}

\indexlibrary{\idxcode{vector}!\tcode{vector}}
\begin{itemdecl}
explicit vector(const Allocator&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{vector}, using the
specified allocator.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{vector}!\tcode{vector}}
\begin{itemdecl}
explicit vector(size_type n, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{vector} with \tcode{n}
default-inserted elements using the specified allocator.

\pnum
\requires \tcode{T} shall be \tcode{DefaultInsertable} into \tcode{*this}.

\pnum
\complexity Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{vector}!\tcode{vector}}
\begin{itemdecl}
vector(size_type n, const T& value,
       const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a \tcode{vector} with \tcode{n}
copies of \tcode{value}, using the specified allocator.

\pnum
\requires \tcode{T} shall be
\tcode{CopyInsertable} into \tcode{*this}.

\pnum
\complexity Linear in \tcode{n}.
\end{itemdescr}

\indexlibrary{\idxcode{vector}!\tcode{vector}}
\begin{itemdecl}
template <class InputIterator>
  vector(InputIterator first, InputIterator last,
         const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects Constructs a \tcode{vector} equal to the
range \range{first}{last}, using the specified allocator.

\pnum
\complexity
Makes only $N$
calls to the copy constructor of
\tcode{T}
(where $N$
is the distance between
\tcode{first}
and
\tcode{last})
and no reallocations if iterators first and last are of forward, bidirectional, or random access categories.
It makes order
\tcode{N}
calls to the copy constructor of
\tcode{T}
and order
$\log(N)$
reallocations if they are just input iterators.
\end{itemdescr}

\rSec3[vector.capacity]{\tcode{vector} capacity}

\indexlibrary{\idxcode{capacity}!\idxcode{vector}}%
\begin{itemdecl}
size_type capacity() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The total number of elements that the vector can hold
without requiring reallocation.
\end{itemdescr}

\indexlibrary{\idxcode{reserve}!\idxcode{vector}}%
\begin{itemdecl}
void reserve(size_type n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{T} shall be \tcode{MoveInsertable} into \tcode{*this}.

\pnum
\effects
A directive that informs a
\tcode{vector}
of a planned change in size, so that it can manage the storage allocation accordingly.
After
\tcode{reserve()},
\tcode{capacity()}
is greater or equal to the argument of
\tcode{reserve}
if reallocation happens; and equal to the previous value of
\tcode{capacity()}
otherwise.
Reallocation happens at this point if and only if the current capacity is less than the
argument of
\tcode{reserve()}. If an exception is thrown
other than by the move constructor of a non-\tcode{CopyInsertable} type,
there are no effects.

\pnum
\complexity
It does not change the size of the sequence and takes at most linear
time in the size of the sequence.

\pnum
\throws
\tcode{length_error} if \tcode{n >
max_size()}.\footnote{\tcode{reserve()} uses \tcode{Allocator::allocate()} which
may throw an appropriate exception.}

\pnum
\notes
Reallocation invalidates all the references, pointers, and iterators
referring to the elements in the sequence.
No reallocation shall take place during insertions that happen
after a call to
\tcode{reserve()}
until the time when an insertion would make the size of the vector
greater than the value of
\tcode{capacity()}.
\end{itemdescr}

\indexlibrary{\idxcode{shrink_to_fit}!\idxcode{vector}}%
\begin{itemdecl}
void shrink_to_fit();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{T} shall be \tcode{MoveInsertable} into \tcode{*this}.

\pnum
\complexity Linear in the size of the sequence.

\pnum
\notes \tcode{shrink_to_fit} is a non-binding request to reduce \tcode{capacity()} to \tcode{size()}. \enternote The request is non-binding to allow latitude for implementation-specific optimizations. \exitnote
If an exception is thrown other than by the move constructor of a non-\tcode{CopyInsertable} \tcode{T} there are no effects.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{vector}}%
\begin{itemdecl}
void swap(vector& x)
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
           allocator_traits<Allocator>::is_always_equal::value);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Exchanges the contents and
\tcode{capacity()}
of
\tcode{*this}
with that of \tcode{x}.

\pnum
\complexity
Constant time.
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\idxcode{vector}}%
\begin{itemdecl}
void resize(size_type sz);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < size()}, erases the last \tcode{size() - sz} elements
from the sequence. Otherwise,
appends \tcode{sz - size()} default-inserted elements to the sequence.

\pnum
\requires \tcode{T} shall be
\tcode{MoveInsertable} and \tcode{DefaultInsertable} into \tcode{*this}.

\pnum
\notes If an exception is thrown other than by the move constructor of a non-\tcode{CopyInsertable}
\tcode{T} there are no effects.
\end{itemdescr}

\indexlibrary{\idxcode{resize}!\idxcode{vector}}%
\begin{itemdecl}
void resize(size_type sz, const T& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects If \tcode{sz < size()}, erases the last \tcode{size() - sz} elements
from the sequence. Otherwise,
appends \tcode{sz - size()} copies of \tcode{c} to the sequence.

\pnum
\requires \tcode{T} shall be
\tcode{CopyInsertable} into \tcode{*this}.

\pnum
\notes If an exception is thrown there are no effects.
\end{itemdescr}

\rSec3[vector.data]{\tcode{vector} data}

\indexlibrary{\idxcode{data}!\idxcode{vector}}%
\begin{itemdecl}
T*         data() noexcept;
const T*   data() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer such that \range{data()}{data() + size()} is a valid range. For a
non-empty vector, \tcode{data()} \tcode{==} \tcode{\&front()}.

\pnum
\complexity
Constant time.
\end{itemdescr}

\rSec3[vector.modifiers]{\tcode{vector} modifiers}

\indexlibrary{\idxcode{insert}!\idxcode{vector}}%
\begin{itemdecl}
iterator insert(const_iterator position, const T& x);
iterator insert(const_iterator position, T&& x);
iterator insert(const_iterator position, size_type n, const T& x);
template <class InputIterator>
  iterator insert(const_iterator position, InputIterator first, InputIterator last);
iterator insert(const_iterator position, initializer_list<T>);

template <class... Args> void emplace_back(Args&&... args);
template <class... Args> iterator emplace(const_iterator position, Args&&... args);
void push_back(const T& x);
void push_back(T&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
Causes reallocation if the new size is greater than the old capacity.
If no reallocation happens, all the iterators and references before the insertion point remain valid.
If an exception is thrown other than by
the copy constructor, move constructor,
assignment operator, or move assignment operator of
\tcode{T} or by any \tcode{InputIterator} operation
there are no effects.
If an exception is thrown while inserting a single element at the end and
\tcode{T} is \tcode{CopyInsertable} or \tcode{is_nothrow_move_constructible<T>::value}
is \tcode{true}, there are no effects.
Otherwise, if an exception is thrown by the move constructor of a non-\tcode{CopyInsertable}
\tcode{T}, the effects are unspecified.

\pnum
\complexity
The complexity is linear in the number of elements inserted plus the distance
to the end of the vector.
\end{itemdescr}

\indexlibrary{\idxcode{erase}!\idxcode{vector}}%
\begin{itemdecl}
iterator erase(const_iterator position);
iterator erase(const_iterator first, const_iterator last);
void pop_back();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Invalidates iterators and references at or after the point of the erase.

\pnum
\complexity
The destructor of \tcode{T} is called the number of times equal to the
number of the elements erased, but the assignment operator
of \tcode{T} is called the number of times equal to the number of
elements in the vector after the erased elements.

\pnum
\throws
Nothing unless an exception is thrown by the
copy constructor, move constructor,
assignment operator, or move assignment operator of
\tcode{T}.
\end{itemdescr}

\rSec3[vector.special]{\tcode{vector} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{vector}}%
\indexlibrary{\idxcode{vector}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Allocator>
  void swap(vector<T, Allocator>& x, vector<T, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[vector.bool]{Class \tcode{vector<bool>}}

\pnum
\indexlibrary{\idxcode{vector<bool>}}%
To optimize space allocation, a specialization of vector for
\tcode{bool}
elements is provided:

\begin{codeblock}
namespace std {
  template <class Allocator>
  class vector<bool, Allocator> {
  public:
    // types:
    typedef bool                                  const_reference;
    typedef @\impdefnc@                iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                difference_type; // see \ref{container.requirements}
    typedef bool                                  value_type;
    typedef Allocator                             allocator_type;
    typedef @\impdefnc@                pointer;
    typedef @\impdefnc@                const_pointer;
    typedef std::reverse_iterator<iterator>       reverse_iterator;
    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;

    // bit reference:
    class reference {
      friend class vector;
      reference() noexcept;
    public:
      ~reference();
      operator bool() const noexcept;
      reference& operator=(const bool x) noexcept;
      reference& operator=(const reference& x) noexcept;
      void flip() noexcept;     // flips the bit
    };

    // construct/copy/destroy:
    vector() : vector(Allocator()) { }
    explicit vector(const Allocator&);
    explicit vector(size_type n, const Allocator& = Allocator());
    vector(size_type n, const bool& value,
           const Allocator& = Allocator());
    template <class InputIterator>
      vector(InputIterator first, InputIterator last,
             const Allocator& = Allocator());
    vector(const vector<bool, Allocator>& x);
    vector(vector<bool, Allocator>&& x);
    vector(const vector&, const Allocator&);
    vector(vector&&, const Allocator&);
    vector(initializer_list<bool>, const Allocator& = Allocator()));
   ~vector();
    vector<bool, Allocator>& operator=(const vector<bool, Allocator>& x);
    vector<bool, Allocator>& operator=(vector<bool, Allocator>&& x);
    vector& operator=(initializer_list<bool>);
    template <class InputIterator>
      void assign(InputIterator first, InputIterator last);
    void assign(size_type n, const bool& t);
    void assign(initializer_list<bool>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;
    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;
    size_type capacity() const noexcept;
    void      resize(size_type sz, bool c = false);
    void      reserve(size_type n);
    void      shrink_to_fit();

    // element access:
    reference       operator[](size_type n);
    const_reference operator[](size_type n) const;
    const_reference at(size_type n) const;
    reference       at(size_type n);
    reference       front();
    const_reference front() const;
    reference       back();
    const_reference back() const;

    // modifiers:
    template <class... Args> void emplace_back(Args&&... args);
    void push_back(const bool& x);
    void pop_back();
    template <class... Args> iterator emplace(const_iterator position, Args&&... args);
    iterator insert(const_iterator position, const bool& x);
    iterator insert(const_iterator position, size_type n, const bool& x);
    template <class InputIterator>
      iterator insert(const_iterator position,
                      InputIterator first, InputIterator last);
    iterator insert(const_iterator position, initializer_list<bool> il);

    iterator erase(const_iterator position);
    iterator erase(const_iterator first, const_iterator last);
    void swap(vector<bool, Allocator>&);
    static void swap(reference x, reference y) noexcept;
    void flip() noexcept;       // flips all bits
    void clear() noexcept;
  };
}
\end{codeblock}%

\pnum
Unless described below, all operations have the same requirements and
semantics as the primary \tcode{vector} template, except that operations
dealing with the \tcode{bool} value type map to bit values in the
container storage and
\tcode{allocator_traits::construct}~(\ref{allocator.traits.members})
is not used to construct these values.

\pnum
There is no requirement that the data be stored as a contiguous allocation
of \tcode{bool} values. A space-optimized representation of bits is
recommended instead.

\pnum
\tcode{reference}
is a class that simulates the behavior of references of a single bit in
\tcode{vector<bool>}. The conversion operator returns \tcode{true}
when the bit is set, and \tcode{false} otherwise. The assignment operator
sets the bit when the argument is (convertible to) \tcode{true} and
clears it otherwise. \tcode{flip} reverses the state of the bit.

\indexlibrary{\idxcode{flip}!\idxcode{vector<bool>}}%
\indexlibrary{\idxcode{vector<bool>}!\idxcode{flip}}%
\begin{itemdecl}
void flip() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Replaces each element in the container with its complement.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{vector<bool>}}%
\indexlibrary{\idxcode{vector<bool>}!\idxcode{swap}}%
\begin{itemdecl}
static void swap(reference x, reference y) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects exchanges the contents of \tcode{x} and \tcode{y} as if by

\begin{codeblock}
bool b = x;
x = y;
y = b;
\end{codeblock}

\end{itemdescr}

\begin{itemdecl}
template <class Allocator> struct hash<vector<bool, Allocator>>;
\end{itemdecl}

\begin{itemdescr}
\pnum
The template specialization shall meet the requirements of class template
\tcode{hash}~(\ref{unord.hash}).
\end{itemdescr}

\rSec1[associative]{Associative containers}

\rSec2[associative.general]{In general}

\pnum
The header \tcode{<map>} defines the class templates \tcode{map} and
\tcode{multimap}; the header \tcode{<set>} defines the class templates
\tcode{set} and \tcode{multiset}.

\rSec2[associative.map.syn]{Header \tcode{<map>} synopsis}

\indexlibrary{\idxhdr{map}}%
\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{map}, class template map:
  template <class Key, class T, class Compare = less<Key>,
            class Allocator = allocator<pair<const Key, T>>>
    class map;
  template <class Key, class T, class Compare, class Allocator>
    bool operator==(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator< (const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator!=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator> (const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator>=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator<=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    void swap(map<Key, T, Compare, Allocator>& x,
              map<Key, T, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));

  // \ref{multimap}, class template multimap:
  template <class Key, class T, class Compare = less<Key>,
            class Allocator = allocator<pair<const Key, T>>>
    class multimap;
  template <class Key, class T, class Compare, class Allocator>
    bool operator==(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator< (const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator!=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator> (const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator>=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator<=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    void swap(multimap<Key, T, Compare, Allocator>& x,
              multimap<Key, T, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[associative.set.syn]{Header \tcode{<set>} synopsis}%
\indexlibrary{\idxhdr{set}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{set}, class template set:
  template <class Key, class Compare = less<Key>,
            class Allocator = allocator<Key>>
    class set;
  template <class Key, class Compare, class Allocator>
    bool operator==(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator< (const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator!=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator> (const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator>=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator<=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    void swap(set<Key, Compare, Allocator>& x,
              set<Key, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));

  // \ref{set}, class template multiset:
  template <class Key, class Compare = less<Key>,
            class Allocator = allocator<Key>>
    class multiset;
  template <class Key, class Compare, class Allocator>
    bool operator==(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator< (const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator!=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator> (const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator>=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator<=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    void swap(multiset<Key, Compare, Allocator>& x,
              multiset<Key, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[map]{Class template \tcode{map}}

\rSec3[map.overview]{Class template \tcode{map} overview}

\indexlibrary{\idxcode{map}}%
\pnum
A \tcode{map} is an associative container that
supports unique keys (contains at most one of each key value) and
provides for fast retrieval of values of another type \tcode{T} based
on the keys. The \tcode{map} class supports bidirectional iterators.

\pnum
A
\tcode{map}
satisfies all of the requirements of a container, of a reversible container~(\ref{container.requirements}), of
an associative container~(\ref{associative.reqmts}), and of an allocator-aware container (Table~\ref{tab:containers.allocatoraware}).
A
\tcode{map}
also provides most operations described in~(\ref{associative.reqmts})
for unique keys.
This means that a
\tcode{map}
supports the
\tcode{a_uniq}
operations in~(\ref{associative.reqmts})
but not the
\tcode{a_eq}
operations.
For a
\tcode{map<Key,T>}
the
\tcode{key_type}
is
\tcode{Key}
and the
\tcode{value_type}
is
\tcode{pair<const Key,T>}.
Descriptions are provided here only for operations on
\tcode{map}
that are not described in one of those tables
or for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class Key, class T, class Compare = less<Key>,
            class Allocator = allocator<pair<const Key, T>>>
  class map {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef T                                                   mapped_type;
    typedef pair<const Key, T>                                  value_type;
    typedef Compare                                             key_compare;
    typedef Allocator                                           allocator_type;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    class value_compare {
    friend class map;
    protected:
      Compare comp;
      value_compare(Compare c) : comp(c) {}
    public:
      typedef bool result_type;
      typedef value_type first_argument_type;
      typedef value_type second_argument_type;
      bool operator()(const value_type& x, const value_type& y) const {
        return comp(x.first, y.first);
      }
    };

    // \ref{map.cons}, construct/copy/destroy:
    map() : map(Compare()) { }
    explicit map(const Compare& comp, const Allocator& = Allocator());
    template <class InputIterator>
      map(InputIterator first, InputIterator last,
          const Compare& comp = Compare(), const Allocator& = Allocator());
    map(const map& x);
    map(map&& x);
    explicit map(const Allocator&);
    map(const map&, const Allocator&);
    map(map&&, const Allocator&);
    map(initializer_list<value_type>,
      const Compare& = Compare(),
      const Allocator& = Allocator());
    template <class InputIterator>
      map(InputIterator first, InputIterator last, const Allocator& a)
        : map(first, last, Compare(), a) { }
    map(initializer_list<value_type> il, const Allocator& a)
      : map(il, Compare(), a) { }
    ~map();
    map& operator=(const map& x);
    map& operator=(map&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Compare>::value);
    map& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // \ref{map.access}, element access:
    T& operator[](const key_type& x);
    T& operator[](key_type&& x);
    T&       at(const key_type& x);
    const T& at(const key_type& x) const;

    // \ref{map.modifiers}, modifiers:
    template <class... Args> pair<iterator, bool> emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    pair<iterator, bool> insert(const value_type& x);
    pair<iterator, bool> insert(value_type&& x);
    template <class P> pair<iterator, bool> insert(P&& x);
    iterator insert(const_iterator position, const value_type& x);
    iterator insert(const_iterator position, value_type&& x);
    template <class P>
      iterator insert(const_iterator position, P&&);
    template <class InputIterator>
      void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    template <class... Args>
      pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
    template <class... Args>
      pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
    template <class... Args>
      iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
    template <class... Args>
      iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
    template <class M>
      pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
    template <class M>
      pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
    template <class M>
      iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
    template <class M>
      iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& x);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(map&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Compare&>(), declval<Compare&>())));
    void      clear() noexcept;

    // observers:
    key_compare key_comp() const;
    value_compare value_comp() const;

    // map operations:
    iterator       find(const key_type& x);
    const_iterator find(const key_type& x) const;
    template <class K> iterator       find(const K& x);
    template <class K> const_iterator find(const K& x) const;

    size_type      count(const key_type& x) const;
    template <class K> size_type count(const K& x) const;

    iterator       lower_bound(const key_type& x);
    const_iterator lower_bound(const key_type& x) const;
    template <class K> iterator       lower_bound(const K& x);
    template <class K> const_iterator lower_bound(const K& x) const;

    iterator       upper_bound(const key_type& x);
    const_iterator upper_bound(const key_type& x) const;
    template <class K> iterator       upper_bound(const K& x);
    template <class K> const_iterator upper_bound(const K& x) const;

    pair<iterator, iterator>               equal_range(const key_type& x);
    pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
    template <class K>
      pair<iterator, iterator>             equal_range(const K& x);
    template <class K>
      pair<const_iterator, const_iterator> equal_range(const K& x) const;
  };

  template <class Key, class T, class Compare, class Allocator>
    bool operator==(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator< (const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator!=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator> (const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator>=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator<=(const map<Key, T, Compare, Allocator>& x,
                    const map<Key, T, Compare, Allocator>& y);

  // \ref{map.special}, specialized algorithms:
  template <class Key, class T, class Compare, class Allocator>
    void swap(map<Key, T, Compare, Allocator>& x,
              map<Key, T, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}


\rSec3[map.cons]{\tcode{map} constructors, copy, and assignment}%
\indexlibrary{\idxcode{map}!\idxcode{operator==}}%
\indexlibrary{\idxcode{map}!\idxcode{operator<}}

\indexlibrary{\idxcode{map}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{map}}%
\begin{itemdecl}
explicit map(const Compare& comp, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{map}
using the specified comparison object and allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{map}!constructor}%
\begin{itemdecl}
template <class InputIterator>
  map(InputIterator first, InputIterator last,
      const Compare& comp = Compare(), const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{map}
using the specified comparison object and allocator,
and inserts elements from the range
\range{first}{last}.

\pnum
\complexity
Linear in $N$ if the range
\range{first}{last}
is already sorted using \tcode{comp}
and otherwise $N \log{N}$, where $N$
is \tcode{last} - \tcode{first}.
\end{itemdescr}

\rSec3[map.access]{\tcode{map} element access}

\indexlibrary{\idxcode{operator[]}!\idxcode{map}}%
\begin{itemdecl}
T& operator[](const key_type& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{return try_emplace(x).first->second;}
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{map}}%
\begin{itemdecl}
T& operator[](key_type&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{return try_emplace(move(x)).first->second;}
\end{itemdescr}

\indexlibrary{\idxcode{at}!\idxcode{map}}%
\begin{itemdecl}
T&       at(const key_type& x);
const T& at(const key_type& x) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A reference to the \tcode{mapped_type} corresponding to \tcode{x} in \tcode{*this}.

\pnum
\throws
An exception object of type \tcode{out_of_range} if
no such element is present.

\pnum
\complexity Logarithmic.
\end{itemdescr}

\rSec3[map.modifiers]{\tcode{map} modifiers}

\indexlibrary{\idxcode{insert}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{insert}}%
\begin{itemdecl}
template <class P> pair<iterator, bool> insert(P&& x);
template <class P> iterator insert(const_iterator position, P&& x);
template <class InputIterator>
  void insert(InputIterator first, InputIterator last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The first form is equivalent to 
\tcode{return emplace(std::forward<P>(x))}. The second form is
equivalent to \tcode{return emplace_hint(position, std::forward<P>(x))}.

\pnum
\remarks
These signatures shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is
\tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{try_emplace}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{try_emplace}}%
\begin{itemdecl}
template <class... Args> pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
template <class... Args> iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{map}
from \tcode{piecewise_construct}, \tcode{forward_as_tuple(k)},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\effects
If the map already contains an element
whose key is equivalent to \tcode{k},
there is no effect.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{piecewise_construct}, \tcode{forward_as_tuple(k)},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{try_emplace}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{try_emplace}}%
\begin{itemdecl}
template <class... Args> pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
template <class... Args> iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{map}
from \tcode{piecewise_construct}, \tcode{forward_as_tuple(move(k))},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\effects
If the map already contains an element
whose key is equivalent to \tcode{k},
there is no effect.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{piecewise_construct}, \tcode{forward_as_tuple(move(k))},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{insert_or_assign}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{insert_or_assign}}%
\begin{itemdecl}
template <class M> pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
template <class M> iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{is_assignable<mapped_type\&, M\&\&>::value} shall be \tcode{true}.
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{map}
from \tcode{k}, \tcode{forward<M>(obj)}.

\pnum
\effects
If the map already contains an element \tcode{e}
whose key is equivalent to \tcode{k},
assigns \tcode{forward<M>(obj)} to \tcode{e.second}.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{k}, \tcode{forward<M>(obj)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{insert_or_assign}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{insert_or_assign}}%
\begin{itemdecl}
template <class M> pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
template <class M> iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{is_assignable<mapped_type\&, M\&\&>::value} shall be \tcode{true}.
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{map}
from \tcode{move(k)}, \tcode{forward<M>(obj)}.

\pnum
\effects
If the map already contains an element \tcode{e}
whose key is equivalent to \tcode{k},
assigns \tcode{forward<M>(obj)} to \tcode{e.second}.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{move(k)}, \tcode{forward<M>(obj)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\rSec3[map.special]{\tcode{map} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{map}}%
\indexlibrary{\idxcode{map}!\idxcode{swap}}%
\begin{itemdecl}
template <class Key, class T, class Compare, class Allocator>
  void swap(map<Key, T, Compare, Allocator>& x,
            map<Key, T, Compare, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[multimap]{Class template \tcode{multimap}}

\rSec3[multimap.overview]{Class template \tcode{multimap} overview}

\pnum
\indexlibrary{\idxcode{multimap}}%
A
\tcode{multimap}
is an associative container that supports equivalent keys (possibly containing multiple copies of
the same key value) and provides for fast retrieval of values of another type
\tcode{T}
based on the keys.
The
\tcode{multimap}
class
supports bidirectional iterators.

\pnum
A
\tcode{multimap} satisfies all of the requirements of a container and of a
reversible container~(\ref{container.requirements}), of an associative
container~(\ref{associative.reqmts}), and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}).
A
\tcode{multimap}
also provides most operations described in~(\ref{associative.reqmts})
for equal keys.
This means that a
\tcode{multimap}
supports the
\tcode{a_eq}
operations in~(\ref{associative.reqmts})
but not the
\tcode{a_uniq}
operations.
For a
\tcode{multimap<Key,T>}
the
\tcode{key_type}
is
\tcode{Key}
and the
\tcode{value_type}
is
\tcode{pair<const Key,T>}.
Descriptions are provided here only for operations on
\tcode{multimap}
that are not described in one of those tables
or for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class Key, class T, class Compare = less<Key>,
            class Allocator = allocator<pair<const Key, T>>>
  class multimap {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef T                                                   mapped_type;
    typedef pair<const Key,T>                                   value_type;
    typedef Compare                                             key_compare;
    typedef Allocator                                           allocator_type;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    class value_compare {
    friend class multimap;
    protected:
      Compare comp;
      value_compare(Compare c) : comp(c) { }
    public:
      typedef bool result_type;
      typedef value_type first_argument_type;
      typedef value_type second_argument_type;
      bool operator()(const value_type& x, const value_type& y) const {
        return comp(x.first, y.first);
      }
    };

    // \ref{multimap.cons}, construct/copy/destroy:
    multimap() : multimap(Compare()) { }
    explicit multimap(const Compare& comp, const Allocator& = Allocator());
    template <class InputIterator>
      multimap(InputIterator first, InputIterator last,
               const Compare& comp = Compare(),
               const Allocator& = Allocator());
    multimap(const multimap& x);
    multimap(multimap&& x);
    explicit multimap(const Allocator&);
    multimap(const multimap&, const Allocator&);
    multimap(multimap&&, const Allocator&);
    multimap(initializer_list<value_type>,
      const Compare& = Compare(),
      const Allocator& = Allocator());
    template <class InputIterator>
      multimap(InputIterator first, InputIterator last, const Allocator& a)
        : multimap(first, last, Compare(), a) { }
    multimap(initializer_list<value_type> il, const Allocator& a)
      : multimap(il, Compare(), a) { }
    ~multimap();
    multimap& operator=(const multimap& x);
    multimap& operator=(multimap&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Compare>::value);
    multimap& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // \ref{multimap.modifiers}, modifiers:
    template <class... Args> iterator emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    iterator insert(const value_type& x);
    iterator insert(value_type&& x);
    template <class P> iterator insert(P&& x);
    iterator insert(const_iterator position, const value_type& x);
    iterator insert(const_iterator position, value_type&& x);
    template <class P> iterator insert(const_iterator position, P&& x);
    template <class InputIterator>
      void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& x);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(multimap&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Compare&>(), declval<Compare&>())));
    void      clear() noexcept;

    // observers:
    key_compare key_comp() const;
    value_compare value_comp() const;

    // map operations:
    iterator       find(const key_type& x);
    const_iterator find(const key_type& x) const;
    template <class K> iterator       find(const K& x);
    template <class K> const_iterator find(const K& x) const;

    size_type      count(const key_type& x) const;
    template <class K> size_type count(const K& x) const;

    iterator       lower_bound(const key_type& x);
    const_iterator lower_bound(const key_type& x) const;
    template <class K> iterator       lower_bound(const K& x);
    template <class K> const_iterator lower_bound(const K& x) const;

    iterator       upper_bound(const key_type& x);
    const_iterator upper_bound(const key_type& x) const;
    template <class K> iterator       upper_bound(const K& x);
    template <class K> const_iterator upper_bound(const K& x) const;

    pair<iterator, iterator>               equal_range(const key_type& x);
    pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
    template <class K>
      pair<iterator, iterator>             equal_range(const K& x);
    template <class K>
      pair<const_iterator, const_iterator> equal_range(const K& x) const;
  };

  template <class Key, class T, class Compare, class Allocator>
    bool operator==(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator< (const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator!=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator> (const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator>=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);
  template <class Key, class T, class Compare, class Allocator>
    bool operator<=(const multimap<Key, T, Compare, Allocator>& x,
                    const multimap<Key, T, Compare, Allocator>& y);

  // \ref{multimap.special}, specialized algorithms:
  template <class Key, class T, class Compare, class Allocator>
    void swap(multimap<Key, T, Compare, Allocator>& x,
              multimap<Key, T, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}%
\indexlibrary{\idxcode{multimap}!\idxcode{operator==}}%
\indexlibrary{\idxcode{multimap}!\idxcode{operator<}}

\rSec3[multimap.cons]{\tcode{multimap} constructors}

\indexlibrary{\idxcode{multimap}!\idxcode{multimap}}%
\indexlibrary{\idxcode{multimap}!\idxcode{multimap}}%
\begin{itemdecl}
explicit multimap(const Compare& comp, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{multimap}
using the specified comparison object and allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{multimap}!\idxcode{multimap}}%
\indexlibrary{\idxcode{multimap}!\idxcode{multimap}}%
\begin{itemdecl}
template <class InputIterator>
  multimap(InputIterator first, InputIterator last,
           const Compare& comp = Compare(),
           const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{multimap}
using the specified comparison object and allocator,
and inserts elements from the range
\range{first}{last}.

\pnum
\complexity
Linear in $N$ if the range
\range{first}{last}
is already sorted using \tcode{comp}
and otherwise $N \log{N}$,
where $N$ is
\tcode{last - first}.
\end{itemdescr}

\rSec3[multimap.modifiers]{\tcode{multimap} modifiers}

\indexlibrary{\idxcode{insert}!\idxcode{multimap}}%
\indexlibrary{\idxcode{multimap}!\idxcode{insert}}%
\begin{itemdecl}
template <class P> iterator insert(P&& x);
template <class P> iterator insert(const_iterator position, P&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The first form is equivalent to 
\tcode{return emplace(std::forward<P>(x))}. The second form is
equivalent to \tcode{return emplace_hint(position, std::forward<P>(x))}.

\pnum
\remarks
These signatures shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is
\tcode{true}.
\end{itemdescr}

\rSec3[multimap.special]{\tcode{multimap} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{multimap}}%
\indexlibrary{\idxcode{multimap}!\idxcode{swap}}%
\begin{itemdecl}
template <class Key, class T, class Compare, class Allocator>
  void swap(multimap<Key, T, Compare, Allocator>& x,
            multimap<Key, T, Compare, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[set]{Class template \tcode{set}}

\rSec3[set.overview]{Class template \tcode{set} overview}

\pnum
\indexlibrary{\idxcode{set}}%
A
\tcode{set}
is an associative container that supports unique keys (contains at most one of each key value) and
provides for fast retrieval of the keys themselves.
The
\tcode{set} class
supports bidirectional iterators.

\pnum
A \tcode{set} satisfies all of the requirements of a container, of a reversible
container~(\ref{container.requirements}), of an associative
container~(\ref{associative.reqmts}), and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}).
A
\tcode{set}
also provides most operations described in~(\ref{associative.reqmts})
for unique keys.
This means that a
\tcode{set}
supports the
\tcode{a_uniq}
operations in~(\ref{associative.reqmts})
but not the
\tcode{a_eq}
operations.
For a
\tcode{set<Key>}
both the
\tcode{key_type}
and
\tcode{value_type}
are
\tcode{Key}.
Descriptions are provided here only for operations on
\tcode{set}
that are not described in one of these tables
and for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class Key, class Compare = less<Key>,
            class Allocator = allocator<Key>>
  class set {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef Key                                                 value_type;
    typedef Compare                                             key_compare;
    typedef Compare                                             value_compare;
    typedef Allocator                                           allocator_type;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    // \ref{set.cons}, construct/copy/destroy:
    set() : set(Compare()) { }
    explicit set(const Compare& comp, const Allocator& = Allocator());
    template <class InputIterator>
      set(InputIterator first, InputIterator last,
          const Compare& comp = Compare(), const Allocator& = Allocator());
    set(const set& x);
    set(set&& x);
    explicit set(const Allocator&);
    set(const set&, const Allocator&);
    set(set&&, const Allocator&);
    set(initializer_list<value_type>, const Compare& = Compare(),
        const Allocator& = Allocator());
    template <class InputIterator>
      set(InputIterator first, InputIterator last, const Allocator& a)
        : set(first, last, Compare(), a) { }
    set(initializer_list<value_type> il, const Allocator& a)
      : set(il, Compare(), a) { }
    ~set();
    set& operator=(const set& x);
    set& operator=(set&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Compare>::value);
    set& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // modifiers:
    template <class... Args> pair<iterator, bool> emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    pair<iterator,bool> insert(const value_type& x);
    pair<iterator,bool> insert(value_type&& x);
    iterator insert(const_iterator position, const value_type& x);
    iterator insert(const_iterator position, value_type&& x);
    template <class InputIterator>
      void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& x);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(set&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Compare&>(), declval<Compare&>())));
    void      clear() noexcept;

    // observers:
    key_compare key_comp() const;
    value_compare value_comp() const;

    // set operations:
    iterator       find(const key_type& x);
    const_iterator find(const key_type& x) const;
    template <class K> iterator       find(const K& x);
    template <class K> const_iterator find(const K& x) const;

    size_type      count(const key_type& x) const;
    template <class K> size_type count(const K& x) const;

    iterator       lower_bound(const key_type& x);
    const_iterator lower_bound(const key_type& x) const;
    template <class K> iterator       lower_bound(const K& x);
    template <class K> const_iterator lower_bound(const K& x) const;

    iterator       upper_bound(const key_type& x);
    const_iterator upper_bound(const key_type& x) const;
    template <class K> iterator       upper_bound(const K& x);
    template <class K> const_iterator upper_bound(const K& x) const;

    pair<iterator, iterator>               equal_range(const key_type& x);
    pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
    template <class K>
      pair<iterator, iterator>             equal_range(const K& x);
    template <class K>
      pair<const_iterator, const_iterator> equal_range(const K& x) const;
  };

  template <class Key, class Compare, class Allocator>
    bool operator==(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator< (const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator!=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator> (const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator>=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator<=(const set<Key, Compare, Allocator>& x,
                    const set<Key, Compare, Allocator>& y);

  // \ref{set.special}, specialized algorithms:
  template <class Key, class Compare, class Allocator>
    void swap(set<Key, Compare, Allocator>& x,
              set<Key, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}%
\indexlibrary{\idxcode{set}!\idxcode{operator==}}%
\indexlibrary{\idxcode{set}!\idxcode{operator<}}

\rSec3[set.cons]{\tcode{set} constructors, copy, and assignment}

\indexlibrary{\idxcode{set}!\idxcode{set}}%
\indexlibrary{\idxcode{set}!\idxcode{set}}%
\begin{itemdecl}
explicit set(const Compare& comp, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty set using the specified comparison objects and allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{set}!\idxcode{set}}%
\indexlibrary{\idxcode{set}!\idxcode{set}}%
\begin{itemdecl}
template <class InputIterator>
  set(InputIterator first, InputIterator last,
      const Compare& comp = Compare(), const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{set}
using the specified comparison object and allocator,
and inserts elements from the range
\range{first}{last}.

\pnum
\complexity
Linear in $N$ if the range
\range{first}{last}
is already sorted using \tcode{comp}
and otherwise $N \log{N}$,
where $N$ is
\tcode{last - first}.
\end{itemdescr}

\rSec3[set.special]{\tcode{set} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{set}}%
\indexlibrary{\idxcode{set}!\idxcode{swap}}%
\begin{itemdecl}
template <class Key, class Compare, class Allocator>
  void swap(set<Key, Compare, Allocator>& x,
            set<Key, Compare, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec2[multiset]{Class template \tcode{multiset}}

\rSec3[multiset.overview]{Class template \tcode{multiset} overview}

\pnum
\indexlibrary{\idxcode{multiset}}%
A
\tcode{multiset}
is an associative container that supports equivalent keys (possibly contains multiple copies of
the same key value) and provides for fast retrieval of the keys themselves.
The
\tcode{multiset} class
supports bidirectional iterators.

\pnum
A \tcode{multiset} satisfies all of the requirements of a container, of a
reversible container~(\ref{container.requirements}), of an associative
container~(\ref{associative.reqmts}), and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}).
\tcode{multiset}
also provides most operations described in~(\ref{associative.reqmts})
for duplicate keys.
This means that a
\tcode{multiset}
supports the
\tcode{a_eq}
operations in~(\ref{associative.reqmts})
but not the
\tcode{a_uniq}
operations.
For a
\tcode{multiset<Key>}
both the
\tcode{key_type}
and
\tcode{value_type}
are
\tcode{Key}.
Descriptions are provided here only for operations on
\tcode{multiset}
that are not described in one of these tables
and for operations where there is additional semantic information.

\begin{codeblock}
namespace std {
  template <class Key, class Compare = less<Key>,
            class Allocator = allocator<Key>>
  class multiset {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef Key                                                 value_type;
    typedef Compare                                             key_compare;
    typedef Compare                                             value_compare;
    typedef Allocator                                           allocator_type;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              iterator;        // see \ref{container.requirements}
    typedef @\impdefnc@                              const_iterator;  // see \ref{container.requirements}
    typedef @\impdefnc@                              size_type;       // see \ref{container.requirements}
    typedef @\impdefnc@                              difference_type; // see \ref{container.requirements}
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef std::reverse_iterator<iterator>                     reverse_iterator;
    typedef std::reverse_iterator<const_iterator>               const_reverse_iterator;

    // \ref{multiset.cons}, construct/copy/destroy:
    multiset() : multiset(Compare()) { }
    explicit multiset(const Compare& comp, const Allocator& = Allocator());
    template <class InputIterator>
      multiset(InputIterator first, InputIterator last,
               const Compare& comp = Compare(), const Allocator& = Allocator());
    multiset(const multiset& x);
    multiset(multiset&& x);
    explicit multiset(const Allocator&);
    multiset(const multiset&, const Allocator&);
    multiset(multiset&&, const Allocator&);
    multiset(initializer_list<value_type>, const Compare& = Compare(),
             const Allocator& = Allocator());
    template <class InputIterator>
      multiset(InputIterator first, InputIterator last, const Allocator& a)
        : multiset(first, last, Compare(), a) { }
    multiset(initializer_list<value_type> il, const Allocator& a)
      : multiset(il, Compare(), a) { }
    ~multiset();
    multiset& operator=(const multiset& x);
    multiset& operator=(multiset&& x)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Compare>::value);
    multiset& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator               begin() noexcept;
    const_iterator         begin() const noexcept;
    iterator               end() noexcept;
    const_iterator         end() const noexcept;

    reverse_iterator       rbegin() noexcept;
    const_reverse_iterator rbegin() const noexcept;
    reverse_iterator       rend() noexcept;
    const_reverse_iterator rend() const noexcept;

    const_iterator         cbegin() const noexcept;
    const_iterator         cend() const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // modifiers:
    template <class... Args> iterator emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    iterator insert(const value_type& x);
    iterator insert(value_type&& x);
    iterator insert(const_iterator position, const value_type& x);
    iterator insert(const_iterator position, value_type&& x);
    template <class InputIterator>
      void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& x);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(multiset&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Compare&>(), declval<Compare&>())));
    void      clear() noexcept;

    // observers:
    key_compare key_comp() const;
    value_compare value_comp() const;

    // set operations:
    iterator       find(const key_type& x);
    const_iterator find(const key_type& x) const;
    template <class K> iterator       find(const K& x);
    template <class K> const_iterator find(const K& x) const;

    size_type      count(const key_type& x) const;
    template <class K> size_type count(const K& x) const;

    iterator       lower_bound(const key_type& x);
    const_iterator lower_bound(const key_type& x) const;
    template <class K> iterator       lower_bound(const K& x);
    template <class K> const_iterator lower_bound(const K& x) const;

    iterator       upper_bound(const key_type& x);
    const_iterator upper_bound(const key_type& x) const;
    template <class K> iterator       upper_bound(const K& x);
    template <class K> const_iterator upper_bound(const K& x) const;

    pair<iterator, iterator>               equal_range(const key_type& x);
    pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
    template <class K>
      pair<iterator, iterator>             equal_range(const K& x);
    template <class K>
      pair<const_iterator, const_iterator> equal_range(const K& x) const;
  };

  template <class Key, class Compare, class Allocator>
    bool operator==(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator< (const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator!=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator> (const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator>=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);
  template <class Key, class Compare, class Allocator>
    bool operator<=(const multiset<Key, Compare, Allocator>& x,
                    const multiset<Key, Compare, Allocator>& y);

  // \ref{multiset.special}, specialized algorithms:
  template <class Key, class Compare, class Allocator>
    void swap(multiset<Key, Compare, Allocator>& x,
              multiset<Key, Compare, Allocator>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}%
\indexlibrary{\idxcode{multiset}!\idxcode{operator==}}%
\indexlibrary{\idxcode{multiset}!\idxcode{operator<}}

\rSec3[multiset.cons]{\tcode{multiset} constructors}

\indexlibrary{\idxcode{multiset}!\idxcode{multiset}}%
\indexlibrary{\idxcode{multiset}!\idxcode{multiset}}%
\begin{itemdecl}
explicit multiset(const Compare& comp, const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty set using the specified comparison object and allocator.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibrary{\idxcode{multiset}!\idxcode{multiset}}%
\indexlibrary{\idxcode{multiset}!\idxcode{multiset}}%
\begin{itemdecl}
template <class InputIterator>
  multiset(InputIterator first, InputIterator last,
           const Compare& comp = Compare(), const Allocator& = Allocator());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an empty
\tcode{multiset}
using the specified comparison object and allocator,
and inserts elements from the range
\range{first}{last}.

\pnum
\complexity
Linear in $N$
if the range
\range{first}{last}
is already sorted using \tcode{comp} and otherwise $N \log{N}$,
where $N$ is
\tcode{last - first}.
\end{itemdescr}

\rSec3[multiset.special]{\tcode{multiset} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{multiset}}%
\indexlibrary{\idxcode{multiset}!\idxcode{swap}}%
\begin{itemdecl}
template <class Key, class Compare, class Allocator>
  void swap(multiset<Key, Compare, Allocator>& x,
            multiset<Key, Compare, Allocator>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
x.swap(y);
\end{codeblock}
\end{itemdescr}

\rSec1[unord]{Unordered associative containers}

\rSec2[unord.general]{In general}

\pnum
The header \tcode{<unordered_map>} defines the class templates
\tcode{unordered_map} and
\tcode{unordered_multimap}; the header \tcode{<unordered_set>} defines the class templates
\tcode{unordered_set} and \tcode{unordered_multiset}.

\rSec2[unord.map.syn]{Header \tcode{<unordered_map>} synopsis}%
\indexlibrary{\idxhdr{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_multimap}}%
\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{unord.map}, class template unordered_map:
  template <class Key,
            class T,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Alloc = std::allocator<std::pair<const Key, T>>>
    class unordered_map;

  // \ref{unord.multimap}, class template unordered_multimap:
  template <class Key,
            class T,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Alloc = std::allocator<std::pair<const Key, T>>>
    class unordered_multimap;

  template <class Key, class T, class Hash, class Pred, class Alloc>
    void swap(unordered_map<Key, T, Hash, Pred, Alloc>& x,
              unordered_map<Key, T, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));

  template <class Key, class T, class Hash, class Pred, class Alloc>
    void swap(unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
              unordered_multimap<Key, T, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));

  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_map<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_map<Key, T, Hash, Pred, Alloc>& b);
  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_map<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_map<Key, T, Hash, Pred, Alloc>& b);
  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);
  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);
}
\end{codeblock}

\rSec2[unord.set.syn]{Header \tcode{<unordered_set>} synopsis}%
\indexlibrary{\idxhdr{unordered_set}}%
\indexlibrary{\idxcode{unordered_set}}%
\indexlibrary{\idxcode{unordered_multiset}}%
\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{unord.set}, class template unordered_set:
  template <class Key,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Alloc = std::allocator<Key>>
    class unordered_set;

  // \ref{unord.multiset}, class template unordered_multiset:
  template <class Key,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Alloc = std::allocator<Key>>
    class unordered_multiset;

  template <class Key, class Hash, class Pred, class Alloc>
    void swap(unordered_set<Key, Hash, Pred, Alloc>& x,
              unordered_set<Key, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));

  template <class Key, class Hash, class Pred, class Alloc>
    void swap(unordered_multiset<Key, Hash, Pred, Alloc>& x,
              unordered_multiset<Key, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));

  template <class Key, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_set<Key, Hash, Pred, Alloc>& a,
                    const unordered_set<Key, Hash, Pred, Alloc>& b);
  template <class Key, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_set<Key, Hash, Pred, Alloc>& a,
                    const unordered_set<Key, Hash, Pred, Alloc>& b);
  template <class Key, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                    const unordered_multiset<Key, Hash, Pred, Alloc>& b);
  template <class Key, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                    const unordered_multiset<Key, Hash, Pred, Alloc>& b);
}
\end{codeblock}

\rSec2[unord.map]{Class template \tcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}}

\rSec3[unord.map.overview]{Class template \tcode{unordered_map} overview}

\pnum
\indextext{\idxcode{unordered_map}!unique keys}%
\indextext{unordered associative containers!unique keys}%
An \tcode{unordered_map} is an unordered associative container that
supports unique keys (an \tcode{unordered_map} contains at most one of each
key value) and that associates values of another type
\tcode{mapped_type} with the keys.
The \tcode{unordered_map} class
supports forward iterators.

\pnum
An \tcode{unordered_map} satisfies all of the requirements of a container, of an unordered associative container, and of an allocator-aware container (Table~\ref{tab:containers.allocatoraware}). It provides the operations described in the preceding requirements table for unique keys; that is, an \tcode{unordered_map} supports the \tcode{a_uniq} operations in that table, not the \tcode{a_eq} operations. For an \tcode{unordered_map<Key, T>} the \tcode{key type} is \tcode{Key}, the mapped type is \tcode{T}, and the value type is \tcode{std::pair<const Key, T>}.

\pnum
This section only describes operations on \tcode{unordered_map} that
are not described in one of the requirement tables, or for which there
is additional semantic information.

\indexlibrary{\idxcode{unordered_map}}%
\begin{codeblock}
namespace std {
  template <class Key,
            class T,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Allocator = std::allocator<std::pair<const Key, T>>>
  class unordered_map {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef std::pair<const Key, T>                             value_type;
    typedef T                                                   mapped_type;
    typedef Hash                                                hasher;
    typedef Pred                                                key_equal;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              size_type;
    typedef @\impdefnc@                              difference_type;

    typedef @\impdefnc@                              iterator;
    typedef @\impdefnc@                              const_iterator;
    typedef @\impdefnc@                              local_iterator;
    typedef @\impdefnc@                              const_local_iterator;

    // \ref{unord.map.cnstr}, construct/copy/destroy:
    unordered_map();
    explicit unordered_map(size_type n,
                           const hasher& hf = hasher(),
                           const key_equal& eql = key_equal(),
                           const allocator_type& a = allocator_type());
    template <class InputIterator>
      unordered_map(InputIterator f, InputIterator l,
                    size_type n = @\seebelow@,
                    const hasher& hf = hasher(),
                    const key_equal& eql = key_equal(),
                    const allocator_type& a = allocator_type());
    unordered_map(const unordered_map&);
    unordered_map(unordered_map&&);
    explicit unordered_map(const Allocator&);
    unordered_map(const unordered_map&, const Allocator&);
    unordered_map(unordered_map&&, const Allocator&);
    unordered_map(initializer_list<value_type> il,
                  size_type n = @\seebelow@,
                  const hasher& hf = hasher(),
                  const key_equal& eql = key_equal(),
                  const allocator_type& a = allocator_type());
    unordered_map(size_type n, const allocator_type& a)
      : unordered_map(n, hasher(), key_equal(), a) { }
    unordered_map(size_type n, const hasher& hf, const allocator_type& a)
      : unordered_map(n, hf, key_equal(), a) { }
    template <class InputIterator>
      unordered_map(InputIterator f, InputIterator l, size_type n, const allocator_type& a)
        : unordered_map(f, l, n, hasher(), key_equal(), a) { }
    template <class InputIterator>
      unordered_map(InputIterator f, InputIterator l, size_type n, const hasher& hf,
                    const allocator_type& a)
        : unordered_map(f, l, n, hf, key_equal(), a) { }
    unordered_map(initializer_list<value_type> il, size_type n, const allocator_type& a)
      : unordered_map(il, n, hasher(), key_equal(), a) { }
    unordered_map(initializer_list<value_type> il, size_type n, const hasher& hf,
                  const allocator_type& a)
      : unordered_map(il, n, hf, key_equal(), a) { }
    ~unordered_map();
    unordered_map& operator=(const unordered_map&);
    unordered_map& operator=(unordered_map&&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Hash>::value &&
               is_nothrow_move_assignable<Pred>::value);
    unordered_map& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // \ref{unord.map.modifiers}, modifiers:
    template <class... Args> pair<iterator, bool> emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    pair<iterator, bool> insert(const value_type& obj);
    pair<iterator, bool> insert(value_type&& obj);
    template <class P> pair<iterator, bool> insert(P&& obj);
    iterator       insert(const_iterator hint, const value_type& obj);
    iterator       insert(const_iterator hint, value_type&& obj);
    template <class P> iterator insert(const_iterator hint, P&& obj);
    template <class InputIterator> void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    template <class... Args>
      pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
    template <class... Args>
      pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
    template <class... Args>
      iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
    template <class... Args>
      iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
    template <class M>
      pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
    template <class M>
      pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
    template <class M>
      iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
    template <class M>
      iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& k);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(unordered_map&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Hash&>(), declval<Hash&>())) &&
               noexcept(swap(declval<Pred&>(), declval<Pred&>())));
    void      clear() noexcept;

    // observers:
    hasher hash_function() const;
    key_equal key_eq() const;

    // map operations:
    iterator       find(const key_type& k);
    const_iterator find(const key_type& k) const;
    size_type      count(const key_type& k) const;
    std::pair<iterator, iterator>             equal_range(const key_type& k);
    std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;

    // \ref{unord.map.elem} element access:
    mapped_type& operator[](const key_type& k);
    mapped_type& operator[](key_type&& k);
    mapped_type& at(const key_type& k);
    const mapped_type& at(const key_type& k) const;

    // bucket interface:
    size_type bucket_count() const noexcept;
    size_type max_bucket_count() const noexcept;
    size_type bucket_size(size_type n) const;
    size_type bucket(const key_type& k) const;
    local_iterator begin(size_type n);
    const_local_iterator begin(size_type n) const;
    local_iterator end(size_type n);
    const_local_iterator end(size_type n) const;
    const_local_iterator cbegin(size_type n) const;
    const_local_iterator cend(size_type n) const;

    // hash policy:
    float load_factor() const noexcept;
    float max_load_factor() const noexcept;
    void max_load_factor(float z);
    void rehash(size_type n);
    void reserve(size_type n);
  };

  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_map<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_map<Key, T, Hash, Pred, Alloc>& b);
  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_map<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_map<Key, T, Hash, Pred, Alloc>& b);

  // \ref{unord.map.swap}, swap:
  template <class Key, class T, class Hash, class Pred, class Alloc>
    void swap(unordered_map<Key, T, Hash, Pred, Alloc>& x,
              unordered_map<Key, T, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec3[unord.map.cnstr]{\tcode{unordered_map} constructors}

\indexlibrary{\idxcode{unordered_map}!\idxcode{unordered_map}}%
\begin{itemdecl}
unordered_map() : unordered_map(size_type(@\seebelow@)) { }
explicit unordered_map(size_type n,
                       const hasher& hf = hasher(),
                       const key_equal& eql = key_equal(),
                       const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_map} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets.  For the default constructor,
the number of buckets is \impldef{default number of buckets in
\tcode{unordered_map}}.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_map}!\idxcode{unordered_map}}%
\begin{itemdecl}
template <class InputIterator>
  unordered_map(InputIterator f, InputIterator l,
                size_type n = @\seebelow@,
                const hasher& hf = hasher(),
                const key_equal& eql = key_equal(),
                const allocator_type& a = allocator_type());
unordered_map(initializer_list<value_type> il,
              size_type n = @\seebelow@,
              const hasher& hf = hasher(),
              const key_equal& eql = key_equal(),
              const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_map} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets. If \tcode{n} is not
provided, the number of buckets is \impldef{default number of buckets in
\tcode{unordered_map}}. Then
inserts elements from the range \range{f}{l}
for the first form, or from the range
\range{il.begin()}{il.end()} for the second form.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Average case linear, worst case quadratic.
\end{itemdescr}

\rSec3[unord.map.elem]{\tcode{unordered_map} element access}

\indexlibrary{\idxcode{unordered_map}!\idxcode{operator[]}}%
\indexlibrary{\idxcode{operator[]}!\idxcode{unordered_map}}%
\indextext{\idxcode{unordered_map}!element access}%
\begin{itemdecl}
mapped_type& operator[](const key_type& k);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{return try_emplace(k).first->second;}
\end{itemdescr}

\indexlibrary{\idxcode{unordered_map}!\idxcode{operator[]}}%
\indexlibrary{\idxcode{operator[]}!\idxcode{unordered_map}}%
\indextext{\idxcode{unordered_map}!element access}%
\begin{itemdecl}
mapped_type& operator[](key_type&& k);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{return try_emplace(move(k)).first->second;}
\end{itemdescr}

\indexlibrary{\idxcode{unordered_map}!\idxcode{at}}%
\indexlibrary{\idxcode{at}!\idxcode{unordered_map}}%
\indextext{\idxcode{unordered_map}!element access}%
\begin{itemdecl}
mapped_type& at(const key_type& k);
const mapped_type& at(const key_type& k) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns A reference to \tcode{x.second}, where \tcode{x} is the (unique) element whose key is equivalent to \tcode{k}.

\pnum
\throws An exception object of type \tcode{out_of_range} if no such element is present.
\end{itemdescr}

\rSec3[unord.map.modifiers]{\tcode{unordered_map} modifiers}

\indexlibrary{\idxcode{unordered_map}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{unordered_map}}%
\begin{itemdecl}
template <class P>
  pair<iterator, bool> insert(P&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{return emplace(std::forward<P>(obj))}. 

\pnum
\remarks This signature shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is \tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_map}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{unordered_map}}%
\begin{itemdecl}
template <class P>
  iterator insert(const_iterator hint, P&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to 
\tcode{return emplace_hint(hint, std::forward<P>(obj))}.

\pnum
\remarks This signature shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is \tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{try_emplace}!\idxcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}!\idxcode{try_emplace}}%
\begin{itemdecl}
template <class... Args> pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
template <class... Args> iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{unordered_map}
from \tcode{piecewise_construct}, \tcode{forward_as_tuple(k)},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\effects
If the map already contains an element
whose key is equivalent to \tcode{k},
there is no effect.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{piecewise_construct}, \tcode{forward_as_tuple(k)},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{try_emplace}!\idxcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}!\idxcode{try_emplace}}%
\begin{itemdecl}
template <class... Args> pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
template <class... Args> iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{unordered_map}
from \tcode{piecewise_construct}, \tcode{forward_as_tuple(move(k))},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\effects
If the map already contains an element
whose key is equivalent to \tcode{k},
there is no effect.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{piecewise_construct}, \tcode{forward_as_tuple(move(k))},
\tcode{forward_as_tuple(forward<Args>(args)...)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{insert_or_assign}!\idxcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}!\idxcode{insert_or_assign}}%
\begin{itemdecl}
template <class M> pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
template <class M> iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{is_assignable<mapped_type\&, M\&\&>::value} shall be \tcode{true}.
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{unordered_map}
from \tcode{k}, \tcode{forward<M>(obj)}.

\pnum
\effects
If the map already contains an element \tcode{e}
whose key is equivalent to \tcode{k},
assigns \tcode{forward<M>(obj)} to \tcode{e.second}.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{k}, \tcode{forward<M>(obj)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\indexlibrary{\idxcode{insert_or_assign}!\idxcode{unordered_map}}%
\indexlibrary{\idxcode{unordered_map}!\idxcode{insert_or_assign}}%
\begin{itemdecl}
template <class M> pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
template <class M> iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{is_assignable<mapped_type\&, M\&\&>::value} shall be \tcode{true}.
\tcode{value_type} shall be \tcode{EmplaceConstructible} into \tcode{unordered_map}
from \tcode{move(k)}, \tcode{forward<M>(obj)}.

\pnum
\effects
If the map already contains an element \tcode{e}
whose key is equivalent to \tcode{k},
assigns \tcode{forward<M>(obj)} to \tcode{e.second}.
Otherwise inserts an object of type \tcode{value_type}
constructed with \tcode{move(k)}, \tcode{forward<M>(obj)}.

\pnum
\returns
In the first overload,
the \tcode{bool} component of the returned pair is \tcode{true}
if and only if the insertion took place.
The returned iterator points to the map element
whose key is equivalent to \tcode{k}.

\pnum
\complexity
The same as \tcode{emplace} and \tcode{emplace_hint},
respectively.
\end{itemdescr}

\rSec3[unord.map.swap]{\tcode{unordered_map} swap}

\indexlibrary{\idxcode{unordered_map}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{unordered_map}}%
\begin{itemdecl}
template <class Key, class T, class Hash, class Pred, class Alloc>
  void swap(unordered_map<Key, T, Hash, Pred, Alloc>& x,
            unordered_map<Key, T, Hash, Pred, Alloc>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[unord.multimap]{Class template \tcode{unordered_multimap}}%
\indexlibrary{\idxcode{unordered_multimap}}

\rSec3[unord.multimap.overview]{Class template \tcode{unordered_multimap} overview}

\pnum
\indextext{\idxcode{unordered_multimap}!equivalent keys}%
\indextext{unordered associative containers!equivalent keys}%
An \tcode{unordered_multimap} is an unordered associative container
that supports equivalent keys (an instance of \tcode{unordered_multimap} may contain
multiple copies of each key value) and that associates values of
another type \tcode{mapped_type} with the keys.
The \tcode{unordered_multimap} class
supports forward iterators.

\pnum
An \tcode{unordered_multimap} satisfies all of the requirements of a container, of an
unordered associative container, and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}). It provides the operations described in the
preceding requirements table for equivalent keys; that is, an \tcode{unordered_multimap}
supports the \tcode{a_eq} operations in that table, not the \tcode{a_uniq} operations.
For an \tcode{unordered_multimap<Key, T>} the \tcode{key type} is \tcode{Key}, the
mapped type is \tcode{T}, and the value type is \tcode{std::pair<const Key, T>}.

\pnum
This section only describes operations on \tcode{unordered_multimap}
that are not described in one of the requirement tables, or for which
there is additional semantic information.

\indexlibrary{\idxcode{unordered_multimap}}%
\begin{codeblock}
namespace std {
  template <class Key,
            class T,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Allocator = std::allocator<std::pair<const Key, T>>>
  class unordered_multimap {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef std::pair<const Key, T>                             value_type;
    typedef T                                                   mapped_type;
    typedef Hash                                                hasher;
    typedef Pred                                                key_equal;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              size_type;
    typedef @\impdefnc@                              difference_type;

    typedef @\impdefnc@                              iterator;
    typedef @\impdefnc@                              const_iterator;
    typedef @\impdefnc@                              local_iterator;
    typedef @\impdefnc@                              const_local_iterator;

    // \ref{unord.multimap.cnstr}, construct/copy/destroy:
    unordered_multimap();
    explicit unordered_multimap(size_type n,
                                const hasher& hf = hasher(),
                                const key_equal& eql = key_equal(),
                                const allocator_type& a = allocator_type());
    template <class InputIterator>
      unordered_multimap(InputIterator f, InputIterator l,
                         size_type n = @\seebelow@,
                         const hasher& hf = hasher(),
                         const key_equal& eql = key_equal(),
                         const allocator_type& a = allocator_type());
    unordered_multimap(const unordered_multimap&);
    unordered_multimap(unordered_multimap&&);
    explicit unordered_multimap(const Allocator&);
    unordered_multimap(const unordered_multimap&, const Allocator&);
    unordered_multimap(unordered_multimap&&, const Allocator&);
    unordered_multimap(initializer_list<value_type> il,
                       size_type n = @\seebelow@,
                       const hasher& hf = hasher(),
                       const key_equal& eql = key_equal(),
                       const allocator_type& a = allocator_type());
    unordered_multimap(size_type n, const allocator_type& a)
      : unordered_multimap(n, hasher(), key_equal(), a) { }
    unordered_multimap(size_type n, const hasher& hf, const allocator_type& a)
      : unordered_multimap(n, hf, key_equal(), a) { }
    template <class InputIterator>
      unordered_multimap(InputIterator f, InputIterator l, size_type n, const allocator_type& a)
        : unordered_multimap(f, l, n, hasher(), key_equal(), a) { }
    template <class InputIterator>
      unordered_multimap(InputIterator f, InputIterator l, size_type n, const hasher& hf, 
                         const allocator_type& a)
        : unordered_multimap(f, l, n, hf, key_equal(), a) { }
    unordered_multimap(initializer_list<value_type> il, size_type n, const allocator_type& a)
      : unordered_multimap(il, n, hasher(), key_equal(), a) { }
    unordered_multimap(initializer_list<value_type> il, size_type n, const hasher& hf, 
                       const allocator_type& a)
      : unordered_multimap(il, n, hf, key_equal(), a) { }
    ~unordered_multimap();
    unordered_multimap& operator=(const unordered_multimap&);
    unordered_multimap& operator=(unordered_multimap&&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Hash>::value &&
               is_nothrow_move_assignable<Pred>::value);
    unordered_multimap& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // \ref{unord.multimap.modifiers}, modifiers:
    template <class... Args> iterator emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    iterator insert(const value_type& obj);
    iterator insert(value_type&& obj);
    template <class P> iterator insert(P&& obj);
    iterator insert(const_iterator hint, const value_type& obj);
    iterator insert(const_iterator hint, value_type&& obj);
    template <class P> iterator insert(const_iterator hint, P&& obj);
    template <class InputIterator> void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& k);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(unordered_multimap&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Hash&>(), declval<Hash&>())) &&
               noexcept(swap(declval<Pred&>(), declval<Pred&>())));
    void      clear() noexcept;

    // observers:
    hasher hash_function() const;
    key_equal key_eq() const;

    // map operations:
    iterator       find(const key_type& k);
    const_iterator find(const key_type& k) const;
    size_type      count(const key_type& k) const;
    std::pair<iterator, iterator>             equal_range(const key_type& k);
    std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;

    // bucket interface:
    size_type bucket_count() const noexcept;
    size_type max_bucket_count() const noexcept;
    size_type bucket_size(size_type n) const;
    size_type bucket(const key_type& k) const;
    local_iterator begin(size_type n);
    const_local_iterator begin(size_type n) const;
    local_iterator end(size_type n);
    const_local_iterator end(size_type n) const;
    const_local_iterator cbegin(size_type n) const;
    const_local_iterator cend(size_type n) const;

    // hash policy
    float load_factor() const noexcept;
    float max_load_factor() const noexcept;
    void max_load_factor(float z);
    void rehash(size_type n);
    void reserve(size_type n);
  };

  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);
  template <class Key, class T, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                    const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);

  // \ref{unord.multimap.swap}, swap:
  template <class Key, class T, class Hash, class Pred, class Alloc>
    void swap(unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
              unordered_multimap<Key, T, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));

}
\end{codeblock}

\rSec3[unord.multimap.cnstr]{\tcode{unordered_multimap} constructors}

\indexlibrary{\idxcode{unordered_multimap}!\idxcode{unordered_multimap}}%
\begin{itemdecl}
unordered_multimap() : unordered_multimap(size_type(@\seebelow@)) { }
explicit unordered_multimap(size_type n,
                            const hasher& hf = hasher(),
                            const key_equal& eql = key_equal(),
                            const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_multimap} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets.  For the default constructor,
the number of buckets is \impldef{default number of buckets in
\tcode{unordered_multimap}}.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_multimap}!\idxcode{unordered_multimap}}%
\begin{itemdecl}
template <class InputIterator>
  unordered_multimap(InputIterator f, InputIterator l,
                     size_type n = @\seebelow@,
                     const hasher& hf = hasher(),
                     const key_equal& eql = key_equal(),
                     const allocator_type& a = allocator_type());
unordered_multimap(initializer_list<value_type> il,
                   size_type n = @\seebelow@,
                   const hasher& hf = hasher(),
                   const key_equal& eql = key_equal(),
                   const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_multimap} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets. If \tcode{n} is not
provided, the number of buckets is \impldef{default number of buckets in
\tcode{unordered_multimap}}. Then
inserts elements from the range \range{f}{l}
for the first form, or from the range 
\range{il.begin()}{il.end()} for the second form.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Average case linear, worst case quadratic.
\end{itemdescr}

\rSec3[unord.multimap.modifiers]{\tcode{unordered_multimap} modifiers}

\indexlibrary{\idxcode{unordered_multimap}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{unordered_multimap}}%
\begin{itemdecl}
template <class P>
  iterator insert(P&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to \tcode{return emplace(std::forward<P>(obj))}. 

\pnum
\remarks This signature shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is \tcode{true}.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_multimap}!\idxcode{insert}}%
\indexlibrary{\idxcode{insert}!\idxcode{unordered_multimap}}%
\begin{itemdecl}
template <class P>
  iterator insert(const_iterator hint, P&& obj);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Equivalent to 
\tcode{return emplace_hint(hint, std::forward<P>(obj))}.

\pnum
\remarks This signature shall not participate in overload resolution
unless \tcode{std::is_constructible<value_type, P\&\&>::value} is \tcode{true}.
\end{itemdescr}

\rSec3[unord.multimap.swap]{\tcode{unordered_multimap} swap}

\indexlibrary{\idxcode{unordered_multimap}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{unordered_multimap}}%
\begin{itemdecl}
template <class Key, class T, class Hash, class Pred, class Alloc>
  void swap(unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
            unordered_multimap<Key, T, Hash, Pred, Alloc>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}


\begin{itemdescr}
\pnum\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[unord.set]{Class template \tcode{unordered_set}}%
\indexlibrary{\idxcode{unordered_set}}

\rSec3[unord.set.overview]{Class template \tcode{unordered_set} overview}

\pnum
\indextext{\idxcode{unordered_set}!unique keys}%
\indextext{unordered associative containers!unique keys}%
An \tcode{unordered_set} is an unordered associative container that
supports unique keys (an \tcode{unordered_set} contains at most one of each
key value) and in which the elements' keys are the elements
themselves.
The \tcode{unordered_set} class
supports forward iterators.

\pnum
An \tcode{unordered_set} satisfies all of the requirements of a container, of an unordered associative container, and of an allocator-aware container (Table~\ref{tab:containers.allocatoraware}). It provides the operations described in the preceding requirements table for unique keys; that is, an \tcode{unordered_set} supports the \tcode{a_uniq} operations in that table, not the \tcode{a_eq} operations. For an \tcode{unordered_set<Key>} the \tcode{key type} and the value type are both \tcode{Key}. The \tcode{iterator} and \tcode{const_iterator} types are both const iterator types. It is unspecified whether they are the same type.

\pnum
This section only describes operations on \tcode{unordered_set} that
are not described in one of the requirement tables, or for which there
is additional semantic information.

\indexlibrary{\idxcode{unordered_set}}%
\begin{codeblock}
namespace std {
  template <class Key,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Allocator = std::allocator<Key>>
  class unordered_set {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef Key                                                 value_type;
    typedef Hash                                                hasher;
    typedef Pred                                                key_equal;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              size_type;
    typedef @\impdefnc@                              difference_type;

    typedef @\impdefnc@                              iterator;
    typedef @\impdefnc@                              const_iterator;
    typedef @\impdefnc@                              local_iterator;
    typedef @\impdefnc@                              const_local_iterator;

    // \ref{unord.set.cnstr}, construct/copy/destroy:
    unordered_set();
    explicit unordered_set(size_type n,
                           const hasher& hf = hasher(),
                           const key_equal& eql = key_equal(),
                           const allocator_type& a = allocator_type());
    template <class InputIterator>
      unordered_set(InputIterator f, InputIterator l,
                    size_type n = @\seebelow@,
                    const hasher& hf = hasher(),
                    const key_equal& eql = key_equal(),
                    const allocator_type& a = allocator_type());
    unordered_set(const unordered_set&);
    unordered_set(unordered_set&&);
    explicit unordered_set(const Allocator&);
    unordered_set(const unordered_set&, const Allocator&);
    unordered_set(unordered_set&&, const Allocator&);
    unordered_set(initializer_list<value_type> il,
                  size_type n = @\seebelow@,
                  const hasher& hf = hasher(),
                  const key_equal& eql = key_equal(),
                  const allocator_type& a = allocator_type());
    unordered_set(size_type n, const allocator_type& a)
      : unordered_set(n, hasher(), key_equal(), a) { }
    unordered_set(size_type n, const hasher& hf, const allocator_type& a)
      : unordered_set(n, hf, key_equal(), a) { }
    template <class InputIterator>
      unordered_set(InputIterator f, InputIterator l, size_type n, const allocator_type& a)
        : unordered_set(f, l, n, hasher(), key_equal(), a) { }
    template <class InputIterator>
      unordered_set(InputIterator f, InputIterator l, size_type n, const hasher& hf,
                    const allocator_type& a)
      : unordered_set(f, l, n, hf, key_equal(), a) { }
    unordered_set(initializer_list<value_type> il, size_type n, const allocator_type& a)
      : unordered_set(il, n, hasher(), key_equal(), a) { }
    unordered_set(initializer_list<value_type> il, size_type n, const hasher& hf,
                  const allocator_type& a)
      : unordered_set(il, n, hf, key_equal(), a) { }
    ~unordered_set();
    unordered_set& operator=(const unordered_set&);
    unordered_set& operator=(unordered_set&&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Hash>::value &&
               is_nothrow_move_assignable<Pred>::value);
    unordered_set& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // modifiers:
    template <class... Args> pair<iterator, bool> emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    pair<iterator, bool> insert(const value_type& obj);
    pair<iterator, bool> insert(value_type&& obj);
    iterator insert(const_iterator hint, const value_type& obj);
    iterator insert(const_iterator hint, value_type&& obj);
    template <class InputIterator> void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& k);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(unordered_set&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Hash&>(), declval<Hash&>())) &&
               noexcept(swap(declval<Pred&>(), declval<Pred&>())));
    void      clear() noexcept;

    // observers:
    hasher hash_function() const;
    key_equal key_eq() const;

    // set operations:
    iterator       find(const key_type& k);
    const_iterator find(const key_type& k) const;
    size_type      count(const key_type& k) const;
    std::pair<iterator, iterator>             equal_range(const key_type& k);
    std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;

    // bucket interface:
    size_type bucket_count() const noexcept;
    size_type max_bucket_count() const noexcept;
    size_type bucket_size(size_type n) const;
    size_type bucket(const key_type& k) const;
    local_iterator begin(size_type n);
    const_local_iterator begin(size_type n) const;
    local_iterator end(size_type n);
    const_local_iterator end(size_type n) const;
    const_local_iterator cbegin(size_type n) const;
    const_local_iterator cend(size_type n) const;

    // hash policy:
    float load_factor() const noexcept;
    float max_load_factor() const noexcept;
    void max_load_factor(float z);
    void rehash(size_type n);
    void reserve(size_type n);
  };

  template <class Key, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_set<Key, Hash, Pred, Alloc>& a,
                    const unordered_set<Key, Hash, Pred, Alloc>& b);
  template <class Key, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_set<Key, Hash, Pred, Alloc>& a,
                    const unordered_set<Key, Hash, Pred, Alloc>& b);

  // \ref{unord.set.swap}, swap:
  template <class Key, class Hash, class Pred, class Alloc>
    void swap(unordered_set<Key, Hash, Pred, Alloc>& x,
              unordered_set<Key, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec3[unord.set.cnstr]{\tcode{unordered_set} constructors}

\indexlibrary{\idxcode{unordered_set}!\idxcode{unordered_set}}%
\begin{itemdecl}
unordered_set() : unordered_set(size_type(@\seebelow@)) { }
explicit unordered_set(size_type n,
                       const hasher& hf = hasher(),
                       const key_equal& eql = key_equal(),
                       const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_set} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets.  For the default constructor,
the number of buckets is \impldef{default number of buckets in
\tcode{unordered_set}}.  \tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_set}!\idxcode{unordered_set}}%
\begin{itemdecl}
template <class InputIterator>
  unordered_set(InputIterator f, InputIterator l,
                size_type n = @\seebelow@,
                const hasher& hf = hasher(),
                const key_equal& eql = key_equal(),
                const allocator_type& a = allocator_type());
unordered_set(initializer_list<value_type> il,
              size_type n = @\seebelow@,
              const hasher& hf = hasher(),
              const key_equal& eql = key_equal(),
              const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_set} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets. If \tcode{n} is not
provided, the number of buckets is \impldef{default number of buckets in
\tcode{unordered_set}}. Then
inserts elements from the range \range{f}{l}
for the first form, or from the range 
\range{il.begin()}{il.end()} for the second form.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Average case linear, worst case quadratic.
\end{itemdescr}

\rSec3[unord.set.swap]{\tcode{unordered_set} swap}

\indexlibrary{\idxcode{unordered_set}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{unordered_set}}%
\begin{itemdecl}
template <class Key, class Hash, class Pred, class Alloc>
  void swap(unordered_set<Key, Hash, Pred, Alloc>& x,
            unordered_set<Key, Hash, Pred, Alloc>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[unord.multiset]{Class template \tcode{unordered_multiset}}%
\indexlibrary{\idxcode{unordered_multiset}}

\rSec3[unord.multiset.overview]{Class template \tcode{unordered_multiset} overview}

\pnum
\indextext{\idxcode{unordered_multiset}!equivalent keys}%
\indextext{unordered associative containers!equivalent keys}%
An \tcode{unordered_multiset} is an unordered associative container
that supports equivalent keys (an instance of \tcode{unordered_multiset} may contain
multiple copies of the same key value) and in which each element's key
is the element itself.
The \tcode{unordered_multiset} class
supports forward iterators.

\pnum
An \tcode{unordered_multiset} satisfies all of the requirements of a container, of an
unordered associative container, and of an allocator-aware container
(Table~\ref{tab:containers.allocatoraware}). It provides the operations described in the
preceding requirements table for equivalent keys; that is, an \tcode{unordered_multiset}
supports the \tcode{a_eq} operations in that table, not the \tcode{a_uniq} operations.
For an \tcode{unordered_multiset<Key>} the \tcode{key type} and the value type are
both \tcode{Key}. The \tcode{iterator} and \tcode{const_iterator} types are both const
iterator types. It is unspecified whether they are the same type.

\pnum
This section only describes operations on \tcode{unordered_multiset} that
are not described in one of the requirement tables, or for which there
is additional semantic information.

\indexlibrary{\idxcode{unordered_multiset}}%
\begin{codeblock}
namespace std {
  template <class Key,
            class Hash = hash<Key>,
            class Pred = std::equal_to<Key>,
            class Allocator = std::allocator<Key>>
  class unordered_multiset {
  public:
    // types:
    typedef Key                                                 key_type;
    typedef Key                                                 value_type;
    typedef Hash                                                hasher;
    typedef Pred                                                key_equal;
    typedef Allocator                                           allocator_type;
    typedef typename allocator_traits<Allocator>::pointer       pointer;
    typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
    typedef value_type&                                         reference;
    typedef const value_type&                                   const_reference;
    typedef @\impdefnc@                              size_type;
    typedef @\impdefnc@                              difference_type;

    typedef @\impdefnc@                              iterator;
    typedef @\impdefnc@                              const_iterator;
    typedef @\impdefnc@                              local_iterator;
    typedef @\impdefnc@                              const_local_iterator;

    // \ref{unord.multiset.cnstr}, construct/copy/destroy:
    unordered_multiset();
    explicit unordered_multiset(size_type n,
                                const hasher& hf = hasher(),
                                const key_equal& eql = key_equal(),
                                const allocator_type& a = allocator_type());
    template <class InputIterator>
      unordered_multiset(InputIterator f, InputIterator l,
                         size_type n = @\seebelow@,
                         const hasher& hf = hasher(),
                         const key_equal& eql = key_equal(),
                         const allocator_type& a = allocator_type());
    unordered_multiset(const unordered_multiset&);
    unordered_multiset(unordered_multiset&&);
    explicit unordered_multiset(const Allocator&);
    unordered_multiset(const unordered_multiset&, const Allocator&);
    unordered_multiset(unordered_multiset&&, const Allocator&);
    unordered_multiset(initializer_list<value_type> il,
                       size_type n = @\seebelow@,
                       const hasher& hf = hasher(),
                       const key_equal& eql = key_equal(),
                       const allocator_type& a = allocator_type());
    unordered_multiset(size_type n, const allocator_type& a)
      : unordered_multiset(n, hasher(), key_equal(), a) { }
    unordered_multiset(size_type n, const hasher& hf, const allocator_type& a)
      : unordered_multiset(n, hf, key_equal(), a) { }
    template <class InputIterator>
      unordered_multiset(InputIterator f, InputIterator l, size_type n, const allocator_type& a)
        : unordered_multiset(f, l, n, hasher(), key_equal(), a) { }
    template <class InputIterator>
      unordered_multiset(InputIterator f, InputIterator l, size_type n, const hasher& hf, 
                         const allocator_type& a)
      : unordered_multiset(f, l, n, hf, key_equal(), a) { }
    unordered_multiset(initializer_list<value_type> il, size_type n, const allocator_type& a)
      : unordered_multiset(il, n, hasher(), key_equal(), a) { }
    unordered_multiset(initializer_list<value_type> il, size_type n, const hasher& hf, 
                       const allocator_type& a)
      : unordered_multiset(il, n, hf, key_equal(), a) { }
    ~unordered_multiset();
    unordered_multiset& operator=(const unordered_multiset&);
    unordered_multiset& operator=(unordered_multiset&&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               is_nothrow_move_assignable<Hash>::value &&
               is_nothrow_move_assignable<Pred>::value);
    unordered_multiset& operator=(initializer_list<value_type>);
    allocator_type get_allocator() const noexcept;

    // iterators:
    iterator       begin() noexcept;
    const_iterator begin() const noexcept;
    iterator       end() noexcept;
    const_iterator end() const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend() const noexcept;

    // capacity:
    bool      empty() const noexcept;
    size_type size() const noexcept;
    size_type max_size() const noexcept;

    // modifiers:
    template <class... Args> iterator emplace(Args&&... args);
    template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
    iterator insert(const value_type& obj);
    iterator insert(value_type&& obj);
    iterator insert(const_iterator hint, const value_type& obj);
    iterator insert(const_iterator hint, value_type&& obj);
    template <class InputIterator> void insert(InputIterator first, InputIterator last);
    void insert(initializer_list<value_type>);

    iterator  erase(iterator position);
    iterator  erase(const_iterator position);
    size_type erase(const key_type& k);
    iterator  erase(const_iterator first, const_iterator last);
    void      swap(unordered_multiset&)
      noexcept(allocator_traits<Allocator>::is_always_equal::value &&
               noexcept(swap(declval<Hash&>(), declval<Hash&>())) &&
               noexcept(swap(declval<Pred&>(), declval<Pred&>())));
    void      clear() noexcept;

    // observers:
    hasher hash_function() const;
    key_equal key_eq() const;

    // set operations:
    iterator       find(const key_type& k);
    const_iterator find(const key_type& k) const;
    size_type      count(const key_type& k) const;
    std::pair<iterator, iterator>             equal_range(const key_type& k);
    std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;

    // bucket interface:
    size_type bucket_count() const noexcept;
    size_type max_bucket_count() const noexcept;
    size_type bucket_size(size_type n) const;
    size_type bucket(const key_type& k) const;
    local_iterator begin(size_type n);
    const_local_iterator begin(size_type n) const;
    local_iterator end(size_type n);
    const_local_iterator end(size_type n) const;
    const_local_iterator cbegin(size_type n) const;
    const_local_iterator cend(size_type n) const;

    // hash policy:
    float load_factor() const noexcept;
    float max_load_factor() const noexcept;
    void max_load_factor(float z);
    void rehash(size_type n);
    void reserve(size_type n);
  };

  template <class Key, class Hash, class Pred, class Alloc>
    bool operator==(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                    const unordered_multiset<Key, Hash, Pred, Alloc>& b);
  template <class Key, class Hash, class Pred, class Alloc>
    bool operator!=(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                    const unordered_multiset<Key, Hash, Pred, Alloc>& b);

  // \ref{unord.multiset.swap}, swap:
  template <class Key, class Hash, class Pred, class Alloc>
    void swap(unordered_multiset<Key, Hash, Pred, Alloc>& x,
              unordered_multiset<Key, Hash, Pred, Alloc>& y)
      noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec3[unord.multiset.cnstr]{\tcode{unordered_multiset} constructors}

\indexlibrary{\idxcode{unordered_multiset}!\idxcode{unordered_multiset}}%
\begin{itemdecl}
unordered_multiset() : unordered_multiset(size_type(@\seebelow@)) { }
explicit unordered_multiset(size_type n,
                            const hasher& hf = hasher(),
                            const key_equal& eql = key_equal(),
                            const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs an empty \tcode{unordered_multiset} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets.  For the default constructor,
the number of buckets is \impldef{default number of buckets in
\tcode{unordered_multiset}}.
\tcode{max_load_factor()} returns 1.0.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{unordered_multiset}!\idxcode{unordered_multiset}}%
\begin{itemdecl}
template <class InputIterator>
  unordered_multiset(InputIterator f, InputIterator l,
                     size_type n = @\seebelow@,
                     const hasher& hf = hasher(),
                     const key_equal& eql = key_equal(),
                     const allocator_type& a = allocator_type());
unordered_multiset(initializer_list<value_type> il,
                   size_type n = @\seebelow@,
                   const hasher& hf = hasher(),
                   const key_equal& eql = key_equal(),
                   const allocator_type& a = allocator_type());
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
Constructs an empty \tcode{unordered_multiset} using the
specified hash function, key equality function, and allocator, and
using at least \tcode{n} buckets. If \tcode{n} is not
provided, the number of buckets is \impldef{default number of buckets in
\tcode{unordered_multiset}}. Then
inserts elements from the range \range{f}{l}
for the first form, or from the range
\range{il.begin()}{il.end()} for the second form.
\tcode{max_load_factor()} returns 1.0.

\pnum\complexity Average case linear, worst case quadratic.
\end{itemdescr}

\rSec3[unord.multiset.swap]{\tcode{unordered_multiset} swap}

\indexlibrary{\idxcode{unordered_multiset}!\idxcode{swap}}%
\indexlibrary{\idxcode{swap}!\idxcode{unordered_multiset}}%
\begin{itemdecl}
template <class Key, class Hash, class Pred, class Alloc>
  void swap(unordered_multiset<Key, Hash, Pred, Alloc>& x,
            unordered_multiset<Key, Hash, Pred, Alloc>& y)
    noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum\effects \tcode{x.swap(y);}
\end{itemdescr}

\indextext{unordered associative containers|)}

\rSec1[container.adaptors]{Container adaptors}

\rSec2[container.adaptors.general]{In general}

\pnum
The headers \tcode{<queue>} and \tcode{<stack>} define the container adaptors
\tcode{queue}, \tcode{priority_queue}, and \tcode{stack}.

\pnum
The container adaptors each take a \tcode{Container} template parameter, and each constructor takes
a \tcode{Container} reference argument. This container is copied into the \tcode{Container} member
of each adaptor. If the container takes an allocator, then a compatible allocator may be passed in
to the adaptor's constructor. Otherwise, normal copy or move construction is used for the container
argument.

\pnum
For container adaptors, no \tcode{swap} function throws an exception unless that
exception is thrown by the swap of the adaptor's \tcode{Container} or
\tcode{Compare} object (if any).

\rSec2[queue.syn]{Header \tcode{<queue>} synopsis}%
\indexlibrary{\idxhdr{queue}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  template <class T, class Container = deque<T>> class queue;
  template <class T, class Container = vector<T>,
            class Compare = less<typename Container::value_type>>
    class priority_queue;

  template <class T, class Container>
    bool operator==(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator< (const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator!=(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator> (const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator>=(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator<=(const queue<T, Container>& x, const queue<T, Container>& y);

  template <class T, class Container>
    void swap(queue<T, Container>& x, queue<T, Container>& y) noexcept(noexcept(x.swap(y)));
  template <class T, class Container, class Compare>
    void swap(priority_queue<T, Container, Compare>& x,
              priority_queue<T, Container, Compare>& y) noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[stack.syn]{Header \tcode{<stack>} synopsis}%
\indexlibrary{\idxhdr{stack}}

\begin{codeblock}
#include <initializer_list>

namespace std {
  template <class T, class Container = deque<T>> class stack;
  template <class T, class Container>
    bool operator==(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator< (const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator!=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator> (const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator>=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator<=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    void swap(stack<T, Container>& x, stack<T, Container>& y) noexcept(noexcept(x.swap(y)));
}
\end{codeblock}

\rSec2[queue]{Class template \tcode{queue}}

\rSec3[queue.defn]{\tcode{queue} definition}

\pnum
\indexlibrary{\idxcode{queue}}%
Any sequence container supporting operations
\tcode{front()},
\tcode{back()},
\tcode{push_back()}
and
\tcode{pop_front()}
can be used to instantiate
\tcode{queue}.
In particular,
\tcode{list}~(\ref{list})
and
\tcode{deque}~(\ref{deque})
can be used.

\begin{codeblock}
namespace std {
  template <class T, class Container = deque<T>>
  class queue {
  public:
    typedef typename Container::value_type            value_type;
    typedef typename Container::reference             reference;
    typedef typename Container::const_reference       const_reference;
    typedef typename Container::size_type             size_type;
    typedef          Container                        container_type;

  protected:
    Container c;

  public:
    explicit queue(const Container&);
    explicit queue(Container&& = Container());
    template <class Alloc> explicit queue(const Alloc&);
    template <class Alloc> queue(const Container&, const Alloc&);
    template <class Alloc> queue(Container&&, const Alloc&);
    template <class Alloc> queue(const queue&, const Alloc&);
    template <class Alloc> queue(queue&&, const Alloc&);

    bool              empty() const     { return c.empty(); }
    size_type         size()  const     { return c.size(); }
    reference         front()           { return c.front(); }
    const_reference   front() const     { return c.front(); }
    reference         back()            { return c.back(); }
    const_reference   back() const      { return c.back(); }
    void push(const value_type& x)      { c.push_back(x); }
    void push(value_type&& x)           { c.push_back(std::move(x)); }
    template <class... Args>
      void emplace(Args&&... args)      { c.emplace_back(std::forward<Args>(args)...); }
    void pop()                          { c.pop_front(); }
    void swap(queue& q) noexcept(noexcept(swap(c, q.c)))
      { using std::swap; swap(c, q.c); }
  };

  template <class T, class Container>
    bool operator==(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator< (const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator!=(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator> (const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator>=(const queue<T, Container>& x, const queue<T, Container>& y);
  template <class T, class Container>
    bool operator<=(const queue<T, Container>& x, const queue<T, Container>& y);

  template <class T, class Container>
    void swap(queue<T, Container>& x, queue<T, Container>& y) noexcept(noexcept(x.swap(y)));

  template <class T, class Container, class Alloc>
    struct uses_allocator<queue<T, Container>, Alloc>
      : uses_allocator<Container, Alloc>::type { };
}
\end{codeblock}

\rSec3[queue.cons]{\tcode{queue} constructors}

\begin{itemdecl}
explicit queue(const Container& cont);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{cont}.
\end{itemdescr}

\begin{itemdecl}
explicit queue(Container&& cont = Container());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(cont)}.
\end{itemdescr}

\rSec3[queue.cons.alloc]{\tcode{queue} constructors with allocators}

\pnum
If \tcode{uses_allocator<container_type, Alloc>::value} is \tcode{false}
the constructors in this subclause shall not participate in overload resolution.

\begin{itemdecl}
template <class Alloc> explicit queue(const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{a}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> queue(const container_type& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{cont} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> queue(container_type&& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(cont)} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> queue(const queue& q, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{q.c} as the first argument and \tcode{a} as the
second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> queue(queue&& q, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(q.c)} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\rSec3[queue.ops]{\tcode{queue} operators}

\indexlibrary{\idxcode{operator==}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator==(const queue<T, Container>& x, const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c == y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator!=(const queue<T, Container>& x,  const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c != y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator<}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator< (const queue<T, Container>& x, const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c < y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator<=}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator<=(const queue<T, Container>& x, const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c <= y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator> (const queue<T, Container>& x, const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c > y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>=}!\idxcode{queue}}%
\begin{itemdecl}
template <class T, class Container>
    bool operator>=(const queue<T, Container>& x,
                    const queue<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c >= y.c}.
\end{itemdescr}

\rSec3[queue.special]{\tcode{queue} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{queue}}%
\indexlibrary{\idxcode{queue}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Container>
  void swap(queue<T, Container>& x, queue<T, Container>& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[priority.queue]{Class template \tcode{priority_queue}}

\pnum
\indexlibrary{\idxcode{priority_queue}}%
Any sequence container with random access iterator and supporting operations
\tcode{front()},
\tcode{push_back()}
and
\tcode{pop_back()}
can be used to instantiate
\tcode{priority_queue}.
In particular,
\tcode{vector}~(\ref{vector})
and
\tcode{deque}~(\ref{deque})
can be used.
Instantiating
\tcode{priority_queue}
also involves supplying a function or function object for making
priority comparisons; the library assumes that the function or function
object defines a strict weak ordering~(\ref{alg.sorting}).

\begin{codeblock}
namespace std {
  template <class T, class Container = vector<T>,
    class Compare = less<typename Container::value_type>>
  class priority_queue {
  public:
    typedef typename Container::value_type            value_type;
    typedef typename Container::reference             reference;
    typedef typename Container::const_reference       const_reference;
    typedef typename Container::size_type             size_type;
    typedef          Container                        container_type;

  protected:
    Container c;
    Compare comp;

  public:
    priority_queue(const Compare& x, const Container&);
    explicit priority_queue(const Compare& x = Compare(), Container&& = Container());
    template <class InputIterator>
      priority_queue(InputIterator first, InputIterator last,
             const Compare& x, const Container&);
    template <class InputIterator>
      priority_queue(InputIterator first, InputIterator last,
             const Compare& x = Compare(), Container&& = Container());
    template <class Alloc> explicit priority_queue(const Alloc&);
    template <class Alloc> priority_queue(const Compare&, const Alloc&);
    template <class Alloc> priority_queue(const Compare&, const Container&, const Alloc&);
    template <class Alloc> priority_queue(const Compare&, Container&&, const Alloc&);
    template <class Alloc> priority_queue(const priority_queue&, const Alloc&);
    template <class Alloc> priority_queue(priority_queue&&, const Alloc&);

    bool      empty() const       { return c.empty(); }
    size_type size()  const       { return c.size(); }
    const_reference   top() const { return c.front(); }
    void push(const value_type& x);
    void push(value_type&& x);
    template <class... Args> void emplace(Args&&... args);
    void pop();
    void swap(priority_queue& q) noexcept(noexcept(swap(c, q.c)) &&
                                          noexcept(swap(comp, q.comp)))
      { using std::swap; swap(c, q.c); swap(comp, q.comp); }
  };

  // no equality is provided

  template <class T, class Container, class Compare>
    void swap(priority_queue<T, Container, Compare>& x,
              priority_queue<T, Container, Compare>& y) noexcept(noexcept(x.swap(y)));

  template <class T, class Container, class Compare, class Alloc>
    struct uses_allocator<priority_queue<T, Container, Compare>, Alloc>
      : uses_allocator<Container, Alloc>::type { };
}
\end{codeblock}

\rSec3[priqueue.cons]{\tcode{priority_queue} constructors}

\indexlibrary{\idxcode{priority_queue}!\idxcode{priority_queue}}%
\begin{itemdecl}
priority_queue(const Compare& x, const Container& y);
explicit priority_queue(const Compare& x = Compare(), Container&& y = Container());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{x} shall define a strict weak ordering~(\ref{alg.sorting}).

\pnum
\effects
Initializes
\tcode{comp} with
\tcode{x} and
\tcode{c} with
\tcode{y} (copy constructing or move constructing as appropriate);
calls
\tcode{make_heap(c.begin(), c.end(), comp)}.
\end{itemdescr}

\indexlibrary{\idxcode{priority_queue}!\idxcode{priority_queue}}%
\begin{itemdecl}
template <class InputIterator>
  priority_queue(InputIterator first, InputIterator last,
                 const Compare& x,
                 const Container& y);
template <class InputIterator>
  priority_queue(InputIterator first, InputIterator last,
                 const Compare& x = Compare(),
                 Container&& y = Container());
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{x} shall define a strict weak ordering~(\ref{alg.sorting}).

\pnum
\effects
Initializes
\tcode{comp} with
\tcode{x} and
\tcode{c} with
\tcode{y} (copy constructing or move constructing as appropriate);
calls
\tcode{c.insert(c.end(), first, last)};
and finally calls
\tcode{make_heap(c.begin(), c.end(), comp)}.
\end{itemdescr}

\rSec3[priqueue.cons.alloc]{\tcode{priority_queue} constructors with allocators}

\pnum
If \tcode{uses_allocator<container_type, Alloc>::value} is \tcode{false}
the constructors in this subclause shall not participate in overload resolution.

\begin{itemdecl}
template <class Alloc> explicit priority_queue(const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{a} and value-initializes \tcode{comp}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> priority_queue(const Compare& compare, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{a} and initializes \tcode{comp} with \tcode{compare}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc>
  priority_queue(const Compare& compare, const Container& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{cont} as the first argument and \tcode{a} as the second
argument, and initializes \tcode{comp} with \tcode{compare}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc>
  priority_queue(const Compare& compare, Container&& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(cont)} as the first argument and \tcode{a}
as the second argument, and initializes \tcode{comp} with \tcode{compare}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> priority_queue(const priority_queue& q, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{q.c} as the first argument and \tcode{a} as
the second argument, and initializes \tcode{comp} with \tcode{q.comp}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> priority_queue(priority_queue&& q, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(q.c)} as the first argument and \tcode{a}
as the second argument, and initializes \tcode{comp} with \tcode{std::move(q.comp)}.
\end{itemdescr}

\rSec3[priqueue.members]{\tcode{priority_queue} members}

\indexlibrary{\idxcode{push}!\tcode{priority_queue}}%
\begin{itemdecl}
void push(const value_type& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
c.push_back(x);
push_heap(c.begin(), c.end(), comp);
\end{codeblock}
\end{itemdescr}

\indexlibrary{\idxcode{push}!\tcode{priority_queue}}%
\begin{itemdecl}
void push(value_type&& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
c.push_back(std::move(x));
push_heap(c.begin(), c.end(), comp);
\end{codeblock}
\end{itemdescr}

\indexlibrary{\idxcode{emplace}!\idxcode{priority_queue}}%
\indexlibrary{\idxcode{priority_queue}!\idxcode{emplace}}%
\begin{itemdecl}
template <class... Args> void emplace(Args&&... args)
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
c.emplace_back(std::forward<Args>(args)...);
push_heap(c.begin(), c.end(), comp);
\end{codeblock}
\end{itemdescr}


\indexlibrary{\idxcode{pop}!\tcode{priority_queue}}%
\begin{itemdecl}
void pop();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\begin{codeblock}
pop_heap(c.begin(), c.end(), comp);
c.pop_back();
\end{codeblock}
\end{itemdescr}

\rSec3[priqueue.special]{\tcode{priority_queue} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{priority_queue}}%
\indexlibrary{\idxcode{priority_queue}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Container, class Compare>
  void swap(priority_queue<T, Container, Compare>& x,
            priority_queue<T, Container, Compare>& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[stack]{Class template \tcode{stack}}

\pnum
\indexlibrary{\idxcode{stack}}%
Any sequence container supporting operations
\tcode{back()},
\tcode{push_back()}
and
\tcode{pop_back()}
can be used to instantiate
\tcode{stack}.
In particular,
\tcode{vector}~(\ref{vector}),
\tcode{list}~(\ref{list})
and
\tcode{deque}~(\ref{deque})
can be used.

\rSec3[stack.defn]{\tcode{stack} definition}

\begin{codeblock}
namespace std {
  template <class T, class Container = deque<T>>
  class stack {
  public:
    typedef typename Container::value_type            value_type;
    typedef typename Container::reference             reference;
    typedef typename Container::const_reference       const_reference;
    typedef typename Container::size_type             size_type;
    typedef          Container                        container_type;

  protected:
    Container c;

  public:
    explicit stack(const Container&);
    explicit stack(Container&& = Container());
    template <class Alloc> explicit stack(const Alloc&);
    template <class Alloc> stack(const Container&, const Alloc&);
    template <class Alloc> stack(Container&&, const Alloc&);
    template <class Alloc> stack(const stack&, const Alloc&);
    template <class Alloc> stack(stack&&, const Alloc&);

    bool      empty() const             { return c.empty(); }
    size_type size()  const             { return c.size(); }
    reference         top()             { return c.back(); }
    const_reference   top() const       { return c.back(); }
    void push(const value_type& x)      { c.push_back(x); }
    void push(value_type&& x)           { c.push_back(std::move(x)); }
    template <class... Args>
      void emplace(Args&&... args)      { c.emplace_back(std::forward<Args>(args)...); }
    void pop()                          { c.pop_back(); }
    void swap(stack& s) noexcept(noexcept(swap(c, s.c)))
      { using std::swap; swap(c, s.c); }
  };

  template <class T, class Container>
    bool operator==(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator< (const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator!=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator> (const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator>=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    bool operator<=(const stack<T, Container>& x, const stack<T, Container>& y);
  template <class T, class Container>
    void swap(stack<T, Container>& x, stack<T, Container>& y) noexcept(noexcept(x.swap(y)));

  template <class T, class Container, class Alloc>
    struct uses_allocator<stack<T, Container>, Alloc>
      : uses_allocator<Container, Alloc>::type { };
}
\end{codeblock}

\rSec3[stack.cons]{\tcode{stack} constructors}

\begin{itemdecl}
explicit stack(const Container& cont);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Initializes \tcode{c} with \tcode{cont}.
\end{itemdescr}

\begin{itemdecl}
explicit stack(Container&& cont = Container());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Initializes \tcode{c} with \tcode{std::move(cont)}.
\end{itemdescr}

\rSec3[stack.cons.alloc]{\tcode{stack} constructors with allocators}

\pnum
If \tcode{uses_allocator<container_type, Alloc>::value} is \tcode{false}
the constructors in this subclause shall not participate in overload resolution.

\begin{itemdecl}
template <class Alloc> explicit stack(const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{a}.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> stack(const container_type& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{cont} as the first argument and \tcode{a} as the
second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> stack(container_type&& cont, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(cont)} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> stack(const stack& s, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{s.c} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\begin{itemdecl}
template <class Alloc> stack(stack&& s, const Alloc& a);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects\ Initializes \tcode{c} with \tcode{std::move(s.c)} as the first argument and \tcode{a}
as the second argument.
\end{itemdescr}

\rSec3[stack.ops]{\tcode{stack} operators}

\indexlibrary{\idxcode{operator==}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator==(const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c == y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator!=(const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c != y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator<}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator< (const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c < y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator<=}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator<=(const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c <= y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
  bool operator> (const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c > y.c}.
\end{itemdescr}

\indexlibrary{\idxcode{operator>=}!\idxcode{stack}}%
\begin{itemdecl}
template <class T, class Container>
    bool operator>=(const stack<T, Container>& x, const stack<T, Container>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.c >= y.c}.
\end{itemdescr}

\rSec3[stack.special]{\tcode{stack} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{stack}}%
\indexlibrary{\idxcode{stack}!\idxcode{swap}}%
\begin{itemdecl}
template <class T, class Container>
  void swap(stack<T, Container>& x, stack<T, Container>& y) noexcept(noexcept(x.swap(y)));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}