diff --git a/source/containers.tex b/source/containers.tex index c8abbf38f6..dd8d197967 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -31,10 +31,10 @@ \end{libsumtab} -\rSec1[container.requirements]{Container requirements}% +\rSec1[container.requirements]{Requirements}% \indextext{requirements!container} -\rSec2[container.requirements.general]{General container requirements} +\rSec2[container.requirements.pre]{Preamble} \pnum Containers are objects that store other objects. @@ -54,7 +54,7 @@ \end{example} \pnum -Allocator-aware containers (\tref{container.alloc.req}) +Allocator-aware containers\iref{container.alloc.reqmts} other than \tcode{basic_string} construct elements using the function \tcode{allocator_traits::rebind_traits::\brk{}construct} and destroy elements using the function @@ -69,10 +69,12 @@ aligned buffers and call \tcode{construct} to place the element into the buffer. \end{note} +\rSec2[container.gen.reqmts]{General containers} + +\rSec3[container.requirements.general]{General} + \pnum -In Tables~\ref{tab:container.req}, -\ref{tab:container.rev.req}, and -\ref{tab:container.opt}, +In subclause \ref{container.gen.reqmts}, \begin{itemize} \item \tcode{X} denotes a container class containing objects of type \tcode{T}, @@ -88,6 +90,8 @@ \tcode{rv} denotes a non-const rvalue of type \tcode{X}. \end{itemize} +\rSec3[container.reqmts]{Containers} + % Local command to index names as members of all containers. \newcommand{\indexcont}[1]{% \indexlibrarymisc{#1}{containers}% @@ -106,3109 +110,5262 @@ \indexlibrarymemberx{unordered_multimap}{#1}% } -\begin{libreqtab5} -{Container requirements} -{container.req} -\\ \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 +\pnum +A type \tcode{X} meets the \defn{container} requirements +if the following types, statements, and expressions are well-formed and +have the specified semantics. \indexcont{value_type}% -\tcode{X::value_type} & - \tcode{T} & - & - \expects \tcode{T} is \oldconcept{Erasable} from \tcode{X} (see~\ref{container.requirements.general}, below) & - compile time \\ \rowsep +\begin{itemdecl} +typename X::value_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{T} + +\pnum +\expects +\tcode{T} is \oldconcept{Erasable} from \tcode{X} +(see~\ref{container.alloc.reqmts}, below). +\end{itemdescr} \indexcont{reference}% -\tcode{X::reference} & - \tcode{T\&} & - & - & - compile time \\ \rowsep +\begin{itemdecl} +typename X::reference +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{T\&} +\end{itemdescr} \indexcont{const_reference}% -\tcode{X::const_reference} & - \tcode{const T\&} & - & - & - compile time \\ \rowsep +\begin{itemdecl} +typename X::const_reference +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{const T\&} +\end{itemdescr} \indexcont{iterator}% -\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 +\begin{itemdecl} +typename X::iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A type that meets the forward iterator requirements\iref{forward.iterators} +with value type \tcode{T}. +The type \tcode{X::iterator} is convertible to \tcode{X::const_iterator}. +\end{itemdescr} \indexcont{const_iterator}% -\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 +\begin{itemdecl} +typename X::const_iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A type that meets the requirements of a constant iterator and +those of a forward iterator with value type \tcode{T}. +\end{itemdescr} \indexcont{difference_type}% -\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 +\begin{itemdecl} +typename X::difference_type +\end{itemdecl} -\indexcont{size_type}% -\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;} & - & - & - \ensures \tcode{u.empty()} & - constant \\ \rowsep - -\tcode{X()} & - & - & - \ensures \tcode{X().empty()} & - constant \\ \rowsep - -\tcode{X(a)} & - & - & - \expects \tcode{T} is \oldconcept{CopyInsertable} - into \tcode{X} (see below).\br \ensures \tcode{a == X(a)}. & - linear \\ \rowsep - -\tcode{X u(a);}\br -\tcode{X u = a;} & - & - & - \expects \tcode{T} is \oldconcept{CopyInsertable} - into \tcode{X} (see below).\br - \ensures \tcode{u == a} & - linear \\ \rowsep - -\tcode{X u(rv);}\br -\tcode{X u = rv;} & - & - & - \ensures \tcode{u} is 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 & - \ensures If \tcode{a} and \tcode{rv} do not refer to the same object, - \tcode{a} is equal to the value that \tcode{rv} - had before this assignment. & - linear \\ \rowsep - -\tcode{a.\~X()} & - \keyword{void} & - & - \effects destroys every element of \tcode{a}; any memory obtained is deallocated. & - linear \\ \rowsep +\begin{itemdescr} +\pnum +\result +A signed integer type, +identical to the difference type of +\tcode{X::iterator} and \tcode{X::const_iterator}. +\end{itemdescr} -\indexcont{begin}% -\tcode{a.begin()} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} & - & - & - constant \\ \rowsep +\indexcont{size_type}% +\begin{itemdecl} +typename X::size_type +\end{itemdecl} -\indexcont{end}% -\tcode{a.end()} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} & - & - & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +An unsigned integer type +that can represent any non-negative value of \tcode{X::difference_type}. +\end{itemdescr} -\indexcont{cbegin}% -\tcode{a.cbegin()} & - \tcode{const_iterator} & - \tcode{const_cast<\brk{}X const\&\brk{}>(a)\brk{}.begin();} & - & - constant \\ \rowsep +\begin{itemdecl}{} +X u; +X u = X(); +\end{itemdecl} -\indexcont{cend}% -\tcode{a.cend()} & - \tcode{const_iterator} & - \tcode{const_cast<\brk{}X const\&\brk{}>(a)\brk{}.end();} & - & - constant \\ \rowsep - -\tcode{i <=> j} & - \tcode{strong_ordering} & - & - \constraints \tcode{X::iterator} meets the random access iterator requirements. & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\ensures +\tcode{u.empty()} -\indexcont{operator==}% -\tcode{a == b} & - convertible to \tcode{bool} & - \tcode{==} is an equivalence relation. - \tcode{equal(\brk{}a.begin(), a.end(), b.begin(), b.end())} & - \expects \tcode{T} meets the \oldconcept{\-Equal\-ity\-Compar\-a\-ble} requirements & - Constant if \tcode{a.size() != b.size()}, - linear otherwise \\ \rowsep +\pnum +\complexity +Constant. +\end{itemdescr} -\indexcont{operator!=}% -\tcode{a != b} & - convertible to \tcode{bool} & - Equivalent to \tcode{!(a == b)} & - & - linear \\ \rowsep +\begin{itemdecl} +X u(a); +X u = a; +\end{itemdecl} -\indexcont{swap}% -\tcode{a.swap(b)} & - \keyword{void} & - & - \effects exchanges the contents of \tcode{a} and \tcode{b} & - (Note A) \\ \rowsep - -\tcode{swap(a, b)} & - \keyword{void} & - Equivalent to \tcode{a.swap(b)} & - & - (Note A) \\ \rowsep +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} (see below). -\indexcont{operator=}% -\tcode{r = a} & - \tcode{X\&} & - & - \ensures \tcode{r == a}. & - linear \\ \rowsep +\pnum +\ensures +\tcode{u == a} -\indexcont{size}% -\tcode{a.size()} & - \tcode{size_type} & - \tcode{distance(\brk{}a.begin(), a.end())} & - & - constant \\ \rowsep +\pnum +\complexity +Linear. +\end{itemdescr} -\indexcont{max_size}% -\tcode{a.max_size()} & - \tcode{size_type} & - \tcode{distance(\brk{}begin(), end())} - for the largest possible container & - & - constant \\ \rowsep +\begin{itemdecl} +X u(rv); +X u = rv; +\end{itemdecl} -\indexcont{empty}% -\tcode{a.empty()} & - convertible to \tcode{bool} & - \tcode{a.begin() == a.end()} & - & -constant \\ +\begin{itemdescr} +\pnum +\ensures +\tcode{u} is equal to the value that \tcode{rv} had before this construction. -\end{libreqtab5} +\pnum +\complexity +Linear for \tcode{array} and constant for all other standard containers. +\end{itemdescr} -Those entries marked ``(Note A)'' or ``(Note B)'' -have linear complexity for \tcode{array} and have constant complexity -for all other standard containers. -\begin{note} -The algorithm \tcode{equal} is defined in \ref{algorithms}. -\end{note} +\begin{itemdecl} +a = rv +\end{itemdecl} +\begin{itemdescr} \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. +\result +\tcode{X\&}. \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()}. +\effects +All existing elements of \tcode{a} are either move assigned to or destroyed. \pnum -In the expressions -\begin{codeblock} -i == j -i != j -i < j -i <= j -i >= j -i > j -i <=> j -i - j -\end{codeblock} -where \tcode{i} and \tcode{j} denote objects of a container's \tcode{iterator} -type, either or both may be replaced by an object of the container's -\tcode{const_iterator} type referring to the same element with no change in semantics. +\ensures +If \tcode{a} and \tcode{rv} do not refer to the same object, +\tcode{a} is equal to the value that \tcode{rv} had before this assignment. \pnum -Unless otherwise specified, all containers defined in this Clause obtain memory -using an allocator (see~\ref{allocator.requirements}). -\begin{note} -In particular, containers and iterators do not store references -to allocated elements other than through the allocator's pointer type, -i.e., as objects of type \tcode{P} or -\tcode{pointer_traits

::template re\-bind<\unspec>}, -where \tcode{P} is \tcode{allocator_traits::pointer}. -\end{note} -Copy constructors for these container types obtain an allocator by calling -\tcode{allocator_traits::select_on_container_copy_construction} -on the allocator belonging to the container being copied. -Move constructors obtain an allocator by move construction from the allocator belonging to -the container being moved. Such move construction of the allocator shall not exit via an -exception. -All other constructors for these container types take a -\tcode{const allocator_type\&} argument. -\begin{note} -If an invocation of a constructor uses the default value of an optional -allocator argument, then the allocator type must support value-initialization. -\end{note} -A copy of this allocator is used for any memory allocation and element construction -performed, by these constructors and by all member functions, -during the lifetime of each container object -or until the allocator is replaced. The allocator may be replaced only via assignment or -\tcode{swap()}. Allocator replacement is performed by -copy assignment, move assignment, or swapping of the allocator only if -\begin{itemize} -\item \tcode{allocator_traits::propagate_on_container_copy_assignment::value}, -\item \tcode{allocator_traits::propagate_on_container_move_assignment::value}, -or -\item \tcode{allocator_traits::propagate_on_container_swap::value} -\end{itemize} -is \tcode{true} -within the implementation of the corresponding container operation. -In all container types defined in this Clause, the member \tcode{get_allocator()} -returns a copy of the allocator used to construct the container or, if that allocator -has been replaced, a copy of the most recent replacement. +\complexity +Linear. +\end{itemdescr} + +\begin{itemdecl} +a.~X() +\end{itemdecl} +\begin{itemdescr} \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::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. +\result +\keyword{void} \pnum -\indextext{reversible container|see{container, reversible}}% -If the iterator type of a container belongs to the bidirectional or -random access iterator categories\iref{iterator.requirements}, -the container is called -\defnx{reversible}{container!reversible} -and meets the additional requirements -in \tref{container.rev.req}. +\effects +Destroys every element of \tcode{a}; any memory obtained is deallocated. -% Local command to index names as members of all containers. -\renewcommand{\indexcont}[1]{% -\indexlibrarymisc{#1}{reversible containers}% -\indexlibrarymemberx{array}{#1}% -\indexlibrarymemberx{deque}{#1}% -\indexlibrarymemberx{list}{#1}% -\indexlibrarymemberx{vector}{#1}% -\indexlibrarymemberx{map}{#1}% -\indexlibrarymemberx{set}{#1}% -\indexlibrarymemberx{multiset}{#1}% -\indexlibrarymemberx{multimap}{#1}% -\indexlibrarymemberx{unordered_map}{#1}% -\indexlibrarymemberx{unordered_set}{#1}% -\indexlibrarymemberx{unordered_multiset}{#1}% -\indexlibrarymemberx{unordered_multimap}{#1}% -} +\pnum +\complexity +Linear. +\end{itemdescr} -\begin{libreqtab4a} -{Reversible container requirements} -{container.rev.req} -\\ \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 -\indexcont{reverse_iterator}% -\tcode{X::reverse_iterator} & -iterator type whose value type is \tcode{T} & - \tcode{reverse_iterator} & - compile time \\ \rowsep -\indexcont{const_reverse_iterator}% -\tcode{X::const_reverse_iterator} & - constant iterator type whose value type is \tcode{T} & - \tcode{reverse_iterator} & - compile time \\ \rowsep -\indexcont{rbegin}% -\tcode{a.rbegin()} & - \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} & - \tcode{reverse_iterator(end())} & - constant \\ \rowsep -\indexcont{rend}% -\tcode{a.rend()} & - \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} & - \tcode{reverse_iterator(begin())} & - constant \\ \rowsep -\indexcont{crbegin}% -\tcode{a.crbegin()} & - \tcode{const_reverse_iterator} & - \tcode{const_cast(a).rbegin()} & - constant \\ \rowsep -\indexcont{crend}% -\tcode{a.crend()} & - \tcode{const_reverse_iterator} & - \tcode{const_cast(a).rend()} & - constant \\ -\end{libreqtab4a} +\indexcont{begin}% +\begin{itemdecl} +a.begin() +\end{itemdecl} +\begin{itemdescr} \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. -\begin{note} -The \tcode{end()} iterator does not refer to any element, so it can be invalidated. -\end{note} -\end{itemize} +\result +\tcode{iterator}; +\tcode{const_iterator} for constant \tcode{a}. \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. +\cvalue +An iterator referring to the first element in the container. \pnum -A \defnadj{contiguous}{container} -is a container -whose member types \tcode{iterator} and \tcode{const_iterator} -meet the -\oldconcept{RandomAccessIterator} requirements\iref{random.access.iterators} and -model \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous}. +\complexity +Constant. +\end{itemdescr} + +\indexcont{end}% +\begin{itemdecl} +a.end() +\end{itemdecl} +\begin{itemdescr} \pnum -\tref{container.opt} 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 -\tref{container.opt} unless otherwise stated. -If the iterators passed to \tcode{lexicographical_compare_three_way} -meet the constexpr iterator requirements\iref{iterator.requirements.general} -then the operations described in \tref{container.opt} -are implemented by constexpr functions. +\result +\tcode{iterator}; +\tcode{const_iterator} for constant \tcode{a}. -\begin{libreqtab5} -{Optional container operations} -{container.opt} -\\ \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} & - \tcode{\placeholdernc{synth-three-\brk{}way-result}\brk{}} & - \tcode{lexicographical_compare_three_way(a.begin(), a.end(), - b.begin(), b.end(), \placeholdernc{synth-three-way})} & - \expects - Either \tcode{<=>} is defined for values of type (possibly const) \tcode{T}, - or \tcode{<} is defined for values of type (possibly const) \tcode{T} and - \tcode{<} is a total ordering relationship. & - linear \\ -\end{libreqtab5} +\pnum +\cvalue +An iterator which is the past-the-end value for the container. -\begin{note} -The algorithm \tcode{lexicographical_compare_three_way} -is defined in \ref{algorithms}. -\end{note} +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexcont{cbegin}% +\begin{itemdecl} +a.cbegin() +\end{itemdecl} +\begin{itemdescr} \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 -\tref{container.alloc.req}. +\result +\tcode{const_iterator}. \pnum -Given an allocator type \tcode{A} -and given a container type \tcode{X} having a \tcode{value_type} identical to \tcode{T} -and an \tcode{allocator_type} identical to \tcode{allocator_traits::rebind_alloc} -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 \keyword{const}) \tcode{T}, -and an rvalue \tcode{rv} of type \tcode{T}, -the following terms are defined. If \tcode{X} -is not allocator-aware or is a specialization of \tcode{basic_string}, -the terms below are defined as if \tcode{A} were -\tcode{allocator} --- no allocator object needs to be created -and user specializations of \tcode{allocator} are not instantiated: +\cvalue +\tcode{const_cast(a).begin()} -\begin{itemize} -\item -\tcode{T} is \defnx{\oldconcept{DefaultInsertable} into \tcode{X}} -{\oldconceptname{DefaultInsertable} into X@\oldconcept{DefaultInsertable} into \tcode{X}} -means that the following expression is well-formed: -\begin{codeblock} -allocator_traits::construct(m, p) -\end{codeblock} +\pnum +\complexity +Constant. +\end{itemdescr} -\item -An element of \tcode{X} is \defn{default-inserted} if it is initialized -by evaluation of the expression -\begin{codeblock} -allocator_traits::construct(m, p) -\end{codeblock} -where \tcode{p} is the address of the uninitialized storage for the element -allocated within \tcode{X}. +\indexcont{cend}% +\begin{itemdecl} +a.cend() +\end{itemdecl} -\item -\tcode{T} is \defnx{\oldconcept{MoveInsertable} into \tcode{X}} -{\oldconceptname{MoveInsertable} into X@\oldconcept{MoveInsertable} into \tcode{X}} -means that the following expression -is well-formed: -\begin{codeblock} -allocator_traits::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. -\begin{note} -\tcode{rv} remains a valid object. Its state is unspecified -\end{note} +\begin{itemdescr} +\pnum +\result +\tcode{const_iterator}. -\item -\tcode{T} is \defnx{\oldconcept{CopyInsertable} into \tcode{X}} -{\oldconceptname{CopyInsertable} into X@\oldconcept{CopyInsertable} into \tcode{X}} -means that, in addition to \tcode{T} being \oldconcept{MoveInsertable} into -\tcode{X}, the following expression is well-formed: -\begin{codeblock} -allocator_traits::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}. +\pnum +\cvalue +\tcode{const_cast(a).end()} -\item -\tcode{T} is -\defnx{\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}} -{\oldconceptname{EmplaceConstructible} into X from args@\oldconcept{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::construct(m, p, args) -\end{codeblock} +\pnum +\complexity +Constant. +\end{itemdescr} -\item -\tcode{T} is -\defnx{\oldconcept{Erasable} from \tcode{X}} -{\oldconceptname{Erasable} from X@\oldconcept{Erasable} from \tcode{X}} -means that the following expression is well-formed: -\begin{codeblock} -allocator_traits::destroy(m, p) -\end{codeblock} -\end{itemize} +\begin{itemdecl} +i <=> j +\end{itemdecl} -\begin{note} -A container calls \tcode{allocator_traits::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{allocator} will -call \tcode{::new((void*)p) T(args)}, -but specialized allocators can choose a different definition. -\end{note} +\begin{itemdescr} +\pnum +\result +\tcode{strong_ordering}. \pnum -In \tref{container.alloc.req}, -\begin{itemize} -\item -\tcode{X} denotes an allocator-aware container class -with a \tcode{value_type} of \tcode{T} using allocator of type \tcode{A}, -\item -\tcode{u} denotes a variable, -\item -\tcode{a} and \tcode{b} denote non-const lvalues of type \tcode{X}, -\item -\tcode{t} denotes an lvalue or a const rvalue of type \tcode{X}, -\item -\tcode{rv} denotes a non-const rvalue of type \tcode{X}, and -\item -\tcode{m} is a value of type \tcode{A}. -\end{itemize} +\constraints +\tcode{X::iterator} meets the random access iterator requirements. -% Local command to index names as members of all containers. -\renewcommand{\indexcont}[1]{% -\indexlibrarymisc{#1}{allocator-aware containers}% -\indexlibrarymemberx{deque}{#1}% -\indexlibrarymemberx{forward_list}{#1}% -\indexlibrarymemberx{list}{#1}% -\indexlibrarymemberx{vector}{#1}% -\indexlibrarymemberx{map}{#1}% -\indexlibrarymemberx{set}{#1}% -\indexlibrarymemberx{multiset}{#1}% -\indexlibrarymemberx{multimap}{#1}% -\indexlibrarymemberx{unordered_map}{#1}% -\indexlibrarymemberx{unordered_set}{#1}% -\indexlibrarymemberx{unordered_multiset}{#1}% -\indexlibrarymemberx{unordered_multimap}{#1}% -} +\pnum +\complexity +Constant. +\end{itemdescr} -\begin{libreqtab4a} -{Allocator-aware container requirements} -{container.alloc.req} -\\ \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 +\indexcont{operator==}% +\begin{itemdecl} +a == b +\end{itemdecl} -\indexcont{allocator_type}% -\tcode{allocator_type} & - \tcode{A} & - \mandates \tcode{allocator_type::value_type} is the same as \tcode{X::value_type}. & - compile time \\ \rowsep +\begin{itemdescr} +\pnum +\expects +\tcode{T} meets the \oldconcept{EqualityComparable} requirements. -\indexcont{get_allocator}% -\tcode{get_-} \tcode{allocator()} & - \tcode{A} & - & - constant \\ \rowsep - -\tcode{X()}\br -\tcode{X u;} & - & - \expects \tcode{A} meets the \oldconcept{DefaultConstructible} requirements.\br - \ensures \tcode{u.empty()} returns \tcode{true}, - \tcode{u.get_allocator() == A()} & - constant \\ \rowsep - -\tcode{X(m)} & - & - \ensures - \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);} & - & - \expects - \tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}.\br - \ensures - \tcode{u == t}, \tcode{u.get_allocator() == m} & - linear \\ \rowsep - -\tcode{X(rv)}\br -\tcode{X u(rv);} - & - & - \ensures \tcode{u} has the same elements as \tcode{rv} had before this - construction; the value of \tcode{u.get_allocator()} is 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);} & - & - \expects \tcode{T} is - \oldconcept{MoveInsertable} into \tcode{X}.\br - \ensures \tcode{u} has 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\&} & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X} - and \oldconcept{CopyAssignable}.\br - \ensures \tcode{a == t} & - linear \\ \rowsep +\pnum +\result +Convertible to \tcode{bool}. -\indexcont{operator=}% -\tcode{a = rv} & - \tcode{X\&} & - \expects If \tcode{allocator_-}\br - \tcode{traits}\br - \tcode{::propagate_on_container_-}\br - \tcode{move_assignment::value} is\br - \tcode{false}, \tcode{T} is - \oldconcept{MoveInsertable} into \tcode{X} and - \oldconcept{MoveAssignable}.\br - \effects All existing elements of \tcode{a} - are either move assigned to or destroyed.\br - \ensures If \tcode{a} and \tcode{rv} do not refer to the same object, - \tcode{a} is equal to the value that \tcode{rv} had before - this assignment. & - linear \\ \rowsep +\pnum +\cvalue +\tcode{equal(a.begin(), a.end(), b.begin(), b.end())} -\indexcont{swap}% -\tcode{a.swap(b)} & - \keyword{void} & - \effects exchanges the contents of \tcode{a} and \tcode{b} & - constant \\ \rowsep +\begin{note} +The algorithm \tcode{equal} is defined in \ref{alg.equal}. +\end{note} -\end{libreqtab4a} +\pnum +\complexity +Constant if \tcode{a.size() != b.size()}, linear otherwise. \pnum -The behavior of certain container member functions and deduction guides -depends on whether types qualify as input iterators or allocators. -The extent to which an implementation determines that a type cannot be an input -iterator is unspecified, except that as a minimum integral types shall not qualify -as input iterators. -Likewise, the extent to which an implementation determines that a type cannot be -an allocator is unspecified, except that as a minimum a type \tcode{A} shall not qualify -as an allocator unless it meets both of the following conditions: +\remarks +\tcode{==} is an equivalence relation. +\end{itemdescr} -\begin{itemize} -\item The \grammarterm{qualified-id} \tcode{A::value_type} -is valid and denotes a type\iref{temp.deduct}. +\indexcont{operator!=}% +\begin{itemdecl} +a != b +\end{itemdecl} -\item The expression \tcode{declval().allocate(size_t\{\})} -is well-formed when treated as an unevaluated operand. -\end{itemize} +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{!(a == b)}. +\end{itemdescr} -\rSec2[container.requirements.dataraces]{Container data races} +\indexcont{swap}% +\begin{itemdecl} +a.swap(b) +\end{itemdecl} +\begin{itemdescr} \pnum -For purposes of avoiding data races\iref{res.on.data.races}, implementations shall -consider the following functions to be \keyword{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[]}. +\result +\keyword{void} \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}, are modified concurrently. +\effects +Exchanges the contents of \tcode{a} and \tcode{b}. \pnum -\begin{note} -For a \tcode{vector 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 can result in a data -race. -As an exception to the general rule, for a \tcode{vector y}, \tcode{y[0] = true} -can race with \tcode{y[1] = true}. -\end{note} +\complexity +Linear for \tcode{array} and constant for all other standard containers. +\end{itemdescr} -\rSec2[sequence.reqmts]{Sequence containers} +\begin{itemdecl} +swap(a, b) +\end{itemdecl} +\begin{itemdescr} \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 defines). +\effects +Equivalent to \tcode{a.swap(b)}. +\end{itemdescr} + +\indexcont{operator=}% +\begin{itemdecl} +r = a +\end{itemdecl} +\begin{itemdescr} \pnum -\begin{note} -The sequence containers -offer the programmer different complexity trade-offs. -\tcode{vector} -is appropriate in most circumstances. -\tcode{array} -has a fixed size known during translation. -\tcode{list} or \tcode{forward_list} -support frequent insertions and deletions from the -middle of the sequence. -\tcode{deque} -supports efficient insertions and deletions taking place at the beginning or at the -end of the sequence. -When choosing a container, remember \tcode{vector} is best; -leave a comment to explain if you choose from the rest! -\end{note} +\result +\tcode{X\&}. \pnum -In Tables~\ref{tab:container.seq.req} -and \ref{tab:container.seq.opt}, +\ensures +\tcode{r == a}. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\indexcont{size}% +\begin{itemdecl} +a.size() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type}. + +\pnum +\cvalue +\tcode{distance(a.begin(), a.end())}, +i.e. the number of elements in the container. + +\pnum +\complexity +Constant. + +\pnum +\remarks +The number of elements is defined by the rules of +constructors, inserts, and erases. +\end{itemdescr} + +\indexcont{max_size}% +\begin{itemdecl} +a.max_size() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type}. + +\pnum +\returns +\tcode{distance(begin(), end())} for the largest possible container. + +\complexity +Constant. +\end{itemdescr} + +\indexcont{empty}% +\begin{itemdecl} +a.empty() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +Convertible to \tcode{bool}. + +\pnum +\cvalue +\tcode{a.begin() == a.end()} + +\pnum +\complexity +Constant. + +\pnum +\remarks +If the container is empty, then \tcode{a.empty()} is true. +\end{itemdescr} + +\pnum +In the expressions +\begin{codeblock} +i == j +i != j +i < j +i <= j +i >= j +i > j +i <=> j +i - j +\end{codeblock} +where \tcode{i} and \tcode{j} denote objects of a container's \tcode{iterator} +type, either or both may be replaced by an object of the container's +\tcode{const_iterator} type referring to the same element with no change in semantics. + +\pnum +Unless otherwise specified, all containers defined in this Clause obtain memory +using an allocator (see~\ref{allocator.requirements}). +\begin{note} +In particular, containers and iterators do not store references +to allocated elements other than through the allocator's pointer type, +i.e., as objects of type \tcode{P} or +\tcode{pointer_traits

::template re\-bind<\unspec>}, +where \tcode{P} is \tcode{allocator_traits::pointer}. +\end{note} +Copy constructors for these container types obtain an allocator by calling +\tcode{allocator_traits::select_on_container_copy_construction} +on the allocator belonging to the container being copied. +Move constructors obtain an allocator by move construction from the allocator belonging to +the container being moved. Such move construction of the allocator shall not exit via an +exception. +All other constructors for these container types take a +\tcode{const allocator_type\&} argument. +\begin{note} +If an invocation of a constructor uses the default value of an optional +allocator argument, then the allocator type must support value-initialization. +\end{note} +A copy of this allocator is used for any memory allocation and element construction +performed, by these constructors and by all member functions, +during the lifetime of each container object +or until the allocator is replaced. The allocator may be replaced only via assignment or +\tcode{swap()}. Allocator replacement is performed by +copy assignment, move assignment, or swapping of the allocator only if \begin{itemize} -\item -\tcode{X} denotes a sequence container class, -\item -\tcode{a} denotes a value of type \tcode{X} containing elements of type \tcode{T}, -\item -\tcode{u} denotes the name of a variable being declared, -\item -\tcode{A} denotes \tcode{X::allocator_type} if -the \grammarterm{qualified-id} \tcode{X::allocator_type} is valid and denotes a -type\iref{temp.deduct} and -\tcode{allocator} if it doesn't, -\item -\tcode{i} and \tcode{j} -denote iterators that meet the \oldconcept{InputIterator} requirements -and refer to elements implicitly convertible to \tcode{value_type}, -\item -\tcode{[i, j)} denotes a valid range, -\item -\tcode{il} designates an object of type \tcode{initializer_list}, -\item -\tcode{n} denotes a value of type \tcode{X::size_type}, -\item -\tcode{p} denotes a valid constant iterator to \tcode{a}, -\item -\tcode{q} denotes a valid dereferenceable constant iterator to \tcode{a}, -\item -\tcode{[q1, q2)} denotes a valid range of constant iterators in \tcode{a}, -\item -\tcode{t} denotes an lvalue or a const rvalue of \tcode{X::value_type}, and -\item -\tcode{rv} denotes a non-const rvalue of \tcode{X::value_type}. -\item -\tcode{Args} denotes a template parameter pack; -\item -\tcode{args} denotes a function parameter pack with the pattern \tcode{Args\&\&}. +\item \tcode{allocator_traits::propagate_on_container_copy_assignment::value}, +\item \tcode{allocator_traits::propagate_on_container_move_assignment::value}, +or +\item \tcode{allocator_traits::propagate_on_container_swap::value} \end{itemize} +is \tcode{true} +within the implementation of the corresponding container operation. +In all container types defined in this Clause, the member \tcode{get_allocator()} +returns a copy of the allocator used to construct the container or, if that allocator +has been replaced, a copy of the most recent replacement. \pnum -The complexities of the expressions are sequence dependent. +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::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. + +\rSec3[container.rev.reqmts]{Reversible container requirements} % Local command to index names as members of all containers. \renewcommand{\indexcont}[1]{% -\indexlibrarymisc{#1}{sequence containers}% +\indexlibrarymisc{#1}{reversible containers}% +\indexlibrarymemberx{array}{#1}% \indexlibrarymemberx{deque}{#1}% -\indexlibrarymemberx{forward_list}{#1}% \indexlibrarymemberx{list}{#1}% \indexlibrarymemberx{vector}{#1}% +\indexlibrarymemberx{map}{#1}% +\indexlibrarymemberx{set}{#1}% +\indexlibrarymemberx{multiset}{#1}% +\indexlibrarymemberx{multimap}{#1}% +\indexlibrarymemberx{unordered_map}{#1}% +\indexlibrarymemberx{unordered_set}{#1}% +\indexlibrarymemberx{unordered_multiset}{#1}% +\indexlibrarymemberx{unordered_multimap}{#1}% } -\begin{libreqtab3} -{Sequence container requirements (in addition to container)} -{container.seq.req} -\\ \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);} & - & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X}.\br - \ensures \tcode{distance(begin(), end()) == n}\br - \effects Constructs a sequence container with \tcode{n} copies of \tcode{t} \\ \rowsep - -\tcode{X(i, j)}\br -\tcode{X u(i, j);} & - & - \expects \tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. - For \tcode{vector}, if the iterator does - not meet the \oldconcept{\-Forward\-Iterator} requirements\iref{forward.iterators}, \tcode{T} - is also - \oldconcept{MoveInsertable} into \tcode{X}.\br - \ensures \tcode{distance(begin(), end()) ==} - \tcode{distance(i, j)}\br - \effects Constructs a sequence container equal to the range \tcode{[i, j)}. - Each iterator in the range \range{i}{j} is dereferenced exactly once. \\ \rowsep - -\tcode{X(il)} & - & - Equivalent to \tcode{X(il.begin(), il.end())} \\ \rowsep - -\tcode{a = il} & - \tcode{X\&} & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X} - and \oldconcept{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.\br - \returns\ \tcode{*this}. - \\ \rowsep +\pnum +A type \tcode{X} meets the \defnadj{reversible}{container} requirements if +\tcode{X} meets the container requirements, +the iterator type of \tcode{X} belongs to the +bidirectional or random access iterator categories\iref{iterator.requirements}, +and +the following types and expressions are well-formed and have +the specified semantics. -\indexcont{emplace}% -\tcode{a.emplace(p, args)} & - \tcode{iterator} & - \expects \tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. For \tcode{vector} and \tcode{deque}, - \tcode{T} is also - \oldconcept{MoveInsertable} into \tcode{X} and \oldconcept{MoveAssignable}.\br - \effects Inserts an object of type \tcode{T} constructed with - \tcode{std::forward<\brk{}Args\brk{}>(\brk{}args)...} before \tcode{p}. - \begin{tailnote} -\tcode{args} can directly or indirectly refer to - a value in \tcode{a}. -\end{tailnote} - \\ \rowsep +\indexcont{reverse_iterator}% +\begin{itemdecl} +typename X::reverse_iterator +\end{itemdecl} -\indexcont{insert}% -\tcode{a.insert(p,t)} & - \tcode{iterator} & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X}. For \tcode{vector} and \tcode{deque}, - \tcode{T} is also \oldconcept{CopyAssignable}.\br - \effects\ Inserts a copy of \tcode{t} before \tcode{p}. \\ \rowsep - -\tcode{a.insert(p,rv)} & - \tcode{iterator} & - \expects \tcode{T} is - \oldconcept{MoveInsertable} into \tcode{X}. For \tcode{vector} and \tcode{deque}, - \tcode{T} is also \oldconcept{MoveAssignable}.\br - \effects\ Inserts a copy of \tcode{rv} before \tcode{p}. \\ \rowsep - -\tcode{a.insert(p,n,t)} & - \tcode{iterator} & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X} - and \oldconcept{CopyAssignable}.\br - \effects Inserts \tcode{n} copies of \tcode{t} before \tcode{p}. \\ \rowsep - -\tcode{a.insert(p,i,j)} & - \tcode{iterator} & - \expects \tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. - For \tcode{vector} and \tcode{deque}, \tcode{T} is also - \oldconcept{MoveInsertable} into \tcode{X}, \oldconcept{MoveConstructible}, \oldconcept{MoveAssignable}, - and swappable\iref{swappable.requirements}. - Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}.\br - \effects Inserts copies of elements in \tcode{[i, j)} before \tcode{p}. - Each iterator in the range \range{i}{j} shall be dereferenced exactly once. \\ \rowsep - -\tcode{a.insert(p, il)} & - \tcode{iterator} & - \tcode{a.insert(p, il.begin(), il.end())}. \\ \rowsep +\begin{itemdescr} +\pnum +\result +The type \tcode{reverse_iterator}, +an iterator type whose value type is \tcode{T}. +\end{itemdescr} -\indexcont{erase}% -\tcode{a.erase(q)} & - \tcode{iterator} & - \expects For \tcode{vector} and \tcode{deque}, - \tcode{T} is \oldconcept{MoveAssignable}.\br - \effects\ Erases the element pointed to by \tcode{q}. \\ \rowsep - -\tcode{a.erase(q1,q2)} & - \tcode{iterator} & - \expects For \tcode{vector} and \tcode{deque}, - \tcode{T} is \oldconcept{MoveAssignable}.\br - \effects\ Erases the elements in the range \tcode{[q1, q2)}. \\ \rowsep +\indexcont{const_reverse_iterator}% +\begin{itemdecl} +typename X::const_reverse_iterator +\end{itemdecl} -\indexcont{clear}% -\tcode{a.clear()} & - \keyword{void} & - \effects 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 - \ensures \tcode{a.empty()} is \tcode{true}.\br - \complexity Linear. \\ \rowsep +\begin{itemdescr} +\pnum +\result +The type \tcode{reverse_iterator}, +a constant iterator type whose value type is \tcode{T}. +\end{itemdescr} -\indexcont{assign}% -\tcode{a.assign(i,j)} & - \keyword{void} & - \expects \tcode{T} is \oldconcept{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\iref{forward.iterators}, \tcode{T} - is also - \oldconcept{MoveInsertable} into \tcode{X}. - Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}.\br - \effects - Replaces elements in \tcode{a} with a copy of \tcode{[i, j)}. - Invalidates all references, pointers and iterators - referring to the elements of \tcode{a}. - For \tcode{vector} and \tcode{deque}, - also invalidates the past-the-end iterator. - Each iterator in the range \range{i}{j} shall be dereferenced exactly once. \\ \rowsep +\indexcont{rbegin}% +\begin{itemdecl} +a.rbegin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reverse_iterator}; +\tcode{const_reverse_iterator} for constant \tcode{a}. + +\pnum +\cvalue +\tcode{reverse_iterator(end())} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexcont{rend}% +\begin{itemdecl} +a.rend() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reverse_iterator}; +\tcode{const_reverse_iterator} for constant \tcode{a}. + +\pnum +\cvalue +\tcode{reverse_iterator(begin())} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexcont{crbegin}% +\begin{itemdecl} +a.crbegin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{const_reverse_iterator}. + +\pnum +\cvalue +\tcode{\keyword{const_cast}(a).rbegin()} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexcont{crend}% +\begin{itemdecl} +a.crend() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{const_reverse_iterator}. + +\pnum +\cvalue +\tcode{\keyword{const_cast}(a).rend()} + +\pnum +\complexity +Constant. +\end{itemdescr} -\tcode{a.assign(il)} & - \keyword{void} & - \tcode{a.assign(il.begin(), il.end())}. \\ \rowsep +\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. +\begin{note} +The \tcode{end()} iterator does not refer to any element, so it can be invalidated. +\end{note} +\end{itemize} + +\pnum +Unless otherwise specified (either explicitly or by defining a +function in terms of other functions), invoking a container member +function or passing a container as an argument to a library function +shall not invalidate iterators to, or change the values of, objects +within that container. + +\pnum +A \defnadj{contiguous}{container} +is a container +whose member types \tcode{iterator} and \tcode{const_iterator} +meet the +\oldconcept{RandomAccessIterator} requirements\iref{random.access.iterators} and +model \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous}. + +\rSec3[container.opt.reqmts]{Optional container requirements} + +\pnum +The following operations are provided +for some types of containers but not others. Those containers for which the +listed operations are provided shall implement the semantics as described +unless otherwise stated. +If the iterators passed to \tcode{lexicographical_compare_three_way} +meet the constexpr iterator requirements\iref{iterator.requirements.general} +then the operations described below +are implemented by constexpr functions. + +\begin{itemdecl} +a <=> b +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{\exposid{synth-three-way-result}}. + +\pnum +\expects +Either \tcode{<=>} is defined for values of type (possibly const) \tcode{T}, +or \tcode{<} is defined for values of type (possibly const) \tcode{T} and +\tcode{<} is a total ordering relationship. + +\pnum +\cvalue +\tcode{lexicographical_compare_three_way(a.begin(), a.end(), +b.begin(), b.end(),\newline \exposidnc{synth-three-way})} +\begin{note} +The algorithm \tcode{lexicographical_compare_three_way} +is defined in \ref{algorithms}. +\end{note} + +\pnum +\complexity +Linear. +\end{itemdescr} + +\rSec3[container.alloc.reqmts]{Allocator-aware containers} + +\pnum +All of the containers defined in \ref{containers} and in~\ref{basic.string} except \tcode{array} +meet the additional requirements of an \defnadj{allocator-aware}{container}, +as described below. + +\pnum +Given an allocator type \tcode{A} +and given a container type \tcode{X} having a \tcode{value_type} identical to \tcode{T} +and an \tcode{allocator_type} identical to \tcode{allocator_traits::rebind_alloc} +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 \keyword{const}) \tcode{T}, +and an rvalue \tcode{rv} of type \tcode{T}, +the following terms are defined. If \tcode{X} +is not allocator-aware or is a specialization of \tcode{basic_string}, +the terms below are defined as if \tcode{A} were +\tcode{allocator} --- no allocator object needs to be created +and user specializations of \tcode{allocator} are not instantiated: + +\begin{itemize} +\item +\tcode{T} is \defnx{\oldconcept{DefaultInsertable} into \tcode{X}} +{\oldconceptname{DefaultInsertable} into X@\oldconcept{DefaultInsertable} into \tcode{X}} +means that the following expression is well-formed: +\begin{codeblock} +allocator_traits::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::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{\oldconcept{MoveInsertable} into \tcode{X}} +{\oldconceptname{MoveInsertable} into X@\oldconcept{MoveInsertable} into \tcode{X}} +means that the following expression +is well-formed: +\begin{codeblock} +allocator_traits::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. +\begin{note} +\tcode{rv} remains a valid object. Its state is unspecified +\end{note} + +\item +\tcode{T} is \defnx{\oldconcept{CopyInsertable} into \tcode{X}} +{\oldconceptname{CopyInsertable} into X@\oldconcept{CopyInsertable} into \tcode{X}} +means that, in addition to \tcode{T} being \oldconcept{MoveInsertable} into +\tcode{X}, the following expression is well-formed: +\begin{codeblock} +allocator_traits::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{\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}} +{\oldconceptname{EmplaceConstructible} into X from args@\oldconcept{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::construct(m, p, args) +\end{codeblock} + +\item +\tcode{T} is +\defnx{\oldconcept{Erasable} from \tcode{X}} +{\oldconceptname{Erasable} from X@\oldconcept{Erasable} from \tcode{X}} +means that the following expression is well-formed: +\begin{codeblock} +allocator_traits::destroy(m, p) +\end{codeblock} +\end{itemize} + +\begin{note} +A container calls \tcode{allocator_traits::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{allocator} will +call \tcode{::new((void*)p) T(args)}, +but specialized allocators can choose a different definition. +\end{note} + +\pnum +In this subclause, +\begin{itemize} +\item +\tcode{X} denotes an allocator-aware container class +with a \tcode{value_type} of \tcode{T} using an allocator of type \tcode{A}, +\item +\tcode{u} denotes a variable, +\item +\tcode{a} and \tcode{b} denote non-const lvalues of type \tcode{X}, +\item +\tcode{c} denotes an lvalue of type \tcode{\keyword{const} X}, +\item +\tcode{t} denotes an lvalue or a const rvalue of type \tcode{X}, +\item +\tcode{rv} denotes a non-const rvalue of type \tcode{X}, and +\item +\tcode{m} is a value of type \tcode{A}. +\end{itemize} + +% Local command to index names as members of all containers. +\renewcommand{\indexcont}[1]{% +\indexlibrarymisc{#1}{allocator-aware containers}% +\indexlibrarymemberx{deque}{#1}% +\indexlibrarymemberx{forward_list}{#1}% +\indexlibrarymemberx{list}{#1}% +\indexlibrarymemberx{vector}{#1}% +\indexlibrarymemberx{map}{#1}% +\indexlibrarymemberx{set}{#1}% +\indexlibrarymemberx{multiset}{#1}% +\indexlibrarymemberx{multimap}{#1}% +\indexlibrarymemberx{unordered_map}{#1}% +\indexlibrarymemberx{unordered_set}{#1}% +\indexlibrarymemberx{unordered_multiset}{#1}% +\indexlibrarymemberx{unordered_multimap}{#1}% +} + +A type \tcode{X} meets the allocator-aware container requirements +if \tcode{X} meets the container requirements and +the following types, statements, and expressions are well-formed and have +the specified semantics. + +\indexcont{allocator_type}% +\begin{itemdecl} +typename X::allocator_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{A} + +\pnum +\expects +\tcode{allocator_type::value_type} is the same as \tcode{X::value_type}. +\end{itemdescr} + +\indexcont{get_allocator}% +\begin{itemdecl} +c.get_allocator() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{A} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X u; +X u = X(); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{A} meets the \oldconcept{DefaultConstructible} requirements. + +\pnum +\ensures +\tcode{u.empty()} returns \tcode{true}, \tcode{u.get_allocator() == A()}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X u(m); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\ensures +\tcode{u.empty()} returns \tcode{true}, \tcode{u.get_allocator() == m}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X u(t, m); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\ensures +\tcode{u == t}, \tcode{u.get_allocator() == m} + +\pnum +\complexity +Linear. +\end{itemdescr} + +\begin{itemdecl} +X u(rv); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\ensures +\tcode{u} has the same elements as \tcode{rv} had before this construction; +the value of \tcode{u.get_allocator()} is the same as +the value of \tcode{rv.get_allocator()} before this construction. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X u(rv, m); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{X}. + +\pnum +\ensures +\tcode{u} has the same elements, or copies of the elements, +that \tcode{rv} had before this construction, +\tcode{u.get_allocator() == m}. + +\pnum +\complexity +Constant if \tcode{m == rv.get_allocator()}, otherwise linear. +\end{itemdescr} + +\begin{itemdecl} +a = t +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&}. + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} and +\oldconcept{CopyAssignable}. + +\pnum +\ensures +\tcode{a == t} is \tcode{true}. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\indexcont{operator=}% +\begin{itemdecl} +a = rv +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&}. + +\pnum +\expects +If +\tcode{allocator_traits::propagate_on_container_move_assign\-ment::value} +is \tcode{false}, +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{X} and +\oldconcept{MoveAssignable}. + +\pnum +\effects +All existing elements of \tcode{a} are either move assigned to or destroyed. + +\pnum +\ensures +If \tcode{a} and \tcode{rv} do not refer to the same object, +\tcode{a} is equal to the value that \tcode{rv} had before this assignment. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\indexcont{swap}% +\begin{itemdecl} +a.swap(b) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +Exchanges the contents of \tcode{a} and \tcode{b}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\pnum +The behavior of certain container member functions and deduction guides +depends on whether types qualify as input iterators or allocators. +The extent to which an implementation determines that a type cannot be an input +iterator is unspecified, except that as a minimum integral types shall not qualify +as input iterators. +Likewise, the extent to which an implementation determines that a type cannot be +an allocator is unspecified, except that as a minimum a type \tcode{A} shall not qualify +as an allocator unless it meets both of the following conditions: + +\begin{itemize} +\item The \grammarterm{qualified-id} \tcode{A::value_type} +is valid and denotes a type\iref{temp.deduct}. + +\item The expression \tcode{declval().allocate(size_t\{\})} +is well-formed when treated as an unevaluated operand. +\end{itemize} + +\rSec2[container.requirements.dataraces]{Container data races} + +\pnum +For purposes of avoiding data races\iref{res.on.data.races}, implementations shall +consider the following functions to be \keyword{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}, are modified concurrently. + +\pnum +\begin{note} +For a \tcode{vector 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 can result in a data +race. +As an exception to the general rule, for a \tcode{vector y}, \tcode{y[0] = true} +can race with \tcode{y[1] = true}. +\end{note} + +\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 defines). + +\pnum +\begin{note} +The sequence containers +offer the programmer different complexity trade-offs. +\tcode{vector} +is appropriate in most circumstances. +\tcode{array} +has a fixed size known during translation. +\tcode{list} or \tcode{forward_list} +support frequent insertions and deletions from the +middle of the sequence. +\tcode{deque} +supports efficient insertions and deletions taking place at the beginning or at the +end of the sequence. +When choosing a container, remember \tcode{vector} is best; +leave a comment to explain if you choose from the rest! +\end{note} + +\pnum +In this subclause, +\begin{itemize} +\item +\tcode{X} denotes a sequence container class, +\item +\tcode{a} denotes a value of type \tcode{X} containing elements of type \tcode{T}, +\item +\tcode{u} denotes the name of a variable being declared, +\item +\tcode{A} denotes \tcode{X::allocator_type} if +the \grammarterm{qualified-id} \tcode{X::allocator_type} is valid and denotes a +type\iref{temp.deduct} and +\tcode{allocator} if it doesn't, +\item +\tcode{i} and \tcode{j} +denote iterators that meet the \oldconcept{InputIterator} requirements +and refer to elements implicitly convertible to \tcode{value_type}, +\item +\tcode{[i, j)} denotes a valid range, +\item +\tcode{il} designates an object of type \tcode{initializer_list}, +\item +\tcode{n} denotes a value of type \tcode{X::size_type}, +\item +\tcode{p} denotes a valid constant iterator to \tcode{a}, +\item +\tcode{q} denotes a valid dereferenceable constant iterator to \tcode{a}, +\item +\tcode{[q1, q2)} denotes a valid range of constant iterators in \tcode{a}, +\item +\tcode{t} denotes an lvalue or a const rvalue of \tcode{X::value_type}, and +\item +\tcode{rv} denotes a non-const rvalue of \tcode{X::value_type}. +\item +\tcode{Args} denotes a template parameter pack; +\item +\tcode{args} denotes a function parameter pack with the pattern \tcode{Args\&\&}. +\end{itemize} + +\pnum +The complexities of the expressions are sequence dependent. + +% Local command to index names as members of all containers. +\renewcommand{\indexcont}[1]{% +\indexlibrarymisc{#1}{sequence containers}% +\indexlibrarymemberx{deque}{#1}% +\indexlibrarymemberx{forward_list}{#1}% +\indexlibrarymemberx{list}{#1}% +\indexlibrarymemberx{vector}{#1}% +} + +\pnum +A type \tcode{X} meets the \defnadj{sequence}{container} requirements +if \tcode{X} meets the container requirements and +the following statements and expressions are well-formed and have +the specified semantics. + +\begin{itemdecl} +X u(n, t); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Constructs a sequence container with \tcode{n} copies of \tcode{t}. + +\pnum +\ensures +\tcode{distance(u.begin(), u.end()) == n} is \tcode{true}. +\end{itemdescr} + +\begin{itemdecl} +X u(i, j); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. +For \tcode{vector}, +if the iterator does not meet +the \oldconcept{ForwardIterator} requirements\iref{forward.iterators}, +\tcode{T} is also \oldconcept{MoveInsertable} into \tcode{X}. + +\pnum +\effects +Constructs a sequence container equal to the range \tcode{[i, j)}. +Each iterator in the range \range{i}{j} is dereferenced exactly once. + +\pnum +\ensures +\tcode{distance(u.begin(), u.end()) == distance(i, j)} is \tcode{true}. +\end{itemdescr} + +\begin{itemdecl} +X(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end())}. +\end{itemdescr} + +\begin{itemdecl} +a = il +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&}. + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} and +\oldconcept{CopyAssignable}. + +\pnum +\effects +Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. +All existing elements of \tcode{a} are either assigned to or destroyed. + +\pnum +\returns +\tcode{*this}. +\end{itemdescr} + +\indexcont{emplace}% +\begin{itemdecl} +a.emplace(p, args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. +For \tcode{vector} and \tcode{deque}, +\tcode{T} is also \oldconcept{MoveInsertable} into \tcode{X} and +\oldconcept{MoveAssignable}. + +\pnum +\effects +Inserts an object of type \tcode{T} +constructed with \tcode{std::forward(args)...} +before \tcode{p}. +\begin{note} +\tcode{args} can directly or indirectly refer to a value in \tcode{a}. +\end{note} + +\pnum +\returns +An iterator that points to +the new element constructed from \tcode{args} into \tcode{a}. +\end{itemdescr} + +\indexcont{insert}% +\begin{itemdecl} +a.insert(p, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. +For \tcode{vector} and \tcode{deque}, +\tcode{T} is also \oldconcept{CopyAssignable}. + +\pnum +\effects +Inserts a copy of \tcode{t} before \tcode{p}. + +\pnum +\returns +An iterator that points to the copy of \tcode{t} inserted into \tcode{a}. +\end{itemdescr} + +\begin{itemdecl} +a.insert(p, rv) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{X}. +For \tcode{vector} and \tcode{deque}, +\tcode{T} is also \oldconcept{MoveAssignable}. + +\pnum +\effects +Inserts a copy of \tcode{rv} before \tcode{p}. + +\pnum +\returns +An iterator that points to the copy of \tcode{rv} inserted into \tcode{a}. +\end{itemdescr} + +\begin{itemdecl} +a.insert(p, n, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} +and \oldconcept{CopyAssignable}. + +\pnum +\effects +Inserts \tcode{n} copies of \tcode{t} before \tcode{p}. + +\pnum +\returns +An iterator +that points to the copy of the first element inserted into \tcode{a}, or +\tcode{p} if \tcode{n == 0}. +\end{itemdescr} + +\begin{itemdecl} +a.insert(p, i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. +For \tcode{vector} and \tcode{deque}, +\tcode{T} is also +\oldconcept{MoveInsertable} into \tcode{X}, +\oldconcept{MoveConstructible}, +\oldconcept{MoveAssignable}, and +swappable\iref{swappable.requirements}. +Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}. + +\pnum +\effects +Inserts copies of elements in \tcode{[i, j)} before \tcode{p}. +Each iterator in the range \range{i}{j} shall be dereferenced exactly once. + +\pnum +\returns +An iterator +that points to the copy of the first element inserted into \tcode{a}, or +\tcode{p} if \tcode{i == j}. +\end{itemdescr} + +\begin{itemdecl} +a.insert(p, il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.insert(p, il.begin(), il.end())}. +\end{itemdescr} + +\indexcont{erase}% +\begin{itemdecl} +a.erase(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +For \tcode{vector} and \tcode{deque}, +\tcode{T} is \oldconcept{MoveAssignable}. + +\pnum +\effects +Erases the element pointed to by \tcode{q}. + +\pnum +\returns +An iterator that points to the element immediately following \tcode{q} +prior to the element being erased. +If no such element exists, \tcode{a.end()} is returned. +\end{itemdescr} + +\begin{itemdecl} +a.erase(q1, q2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}. + +\pnum +\expects +For \tcode{vector} and \tcode{deque}, \tcode{T} is \oldconcept{MoveAssignable}. + +\pnum +\effects +Erases the elements in the range \tcode{[q1, q2)}. + +\pnum +\returns +An iterator that 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. +\end{itemdescr} + +\indexcont{clear}% +\begin{itemdecl} +a.clear() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +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. + +\pnum +\ensures +\tcode{a.empty()} is \tcode{true}. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\indexcont{assign}% +\begin{itemdecl} +a.assign(i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{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\iref{forward.iterators}, +\tcode{T} is also \oldconcept{MoveInsertable} into \tcode{X}. +Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}. + +\pnum +\effects +Replaces elements in \tcode{a} with a copy of \tcode{[i, j)}. +Invalidates all references, pointers and iterators +referring to the elements of \tcode{a}. +For \tcode{vector} and \tcode{deque}, +also invalidates the past-the-end iterator. +Each iterator in the range \range{i}{j} shall be dereferenced exactly once. +\end{itemdescr} + +\begin{itemdecl} +a.assign(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.assign(il.begin(), il.end())}. +\end{itemdescr} + +\begin{itemdecl} +a.assign(n, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} +and \oldconcept{CopyAssignable}. +\tcode{t} is not a reference into \tcode{a}. + +\pnum +\effects +Replaces elements in \tcode{a} with \tcode{n} copies of \tcode{t}. +Invalidates all references, pointers and iterators +referring to the elements of \tcode{a}. +For \tcode{vector} and \tcode{deque}, +also invalidates the past-the-end iterator. +\end{itemdescr} + +\pnum +For every sequence container defined in this Clause and in \ref{strings}: +\begin{itemize} +\item If the constructor +\begin{codeblock} +template + 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 + @\placeholdernc{return-type}@ @\placeholdernc{F}@(const_iterator p, + InputIterator first, InputIterator last); // such as \tcode{insert} + +template + @\placeholdernc{return-type}@ @\placeholdernc{F}@(InputIterator first, InputIterator last); // such as \tcode{append}, \tcode{assign} + +template + @\placeholdernc{return-type}@ @\placeholdernc{F}@(const_iterator i1, const_iterator i2, + InputIterator first, InputIterator last); // such as \tcode{replace} +\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. + +\item A deduction guide for a sequence container shall not participate in overload resolution +if it has an \tcode{InputIterator} template parameter and a type that does not +qualify as an input iterator is deduced for that parameter, +or if it has an \tcode{Allocator} template parameter and a type that does not +qualify as an allocator is deduced for that parameter. +\end{itemize} + +\pnum +The following operations are provided for +some types of sequence containers but not others. +An implementation shall implement them so as to take amortized constant time. + +\begin{itemdecl} +a.front() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference; const_reference} for constant \tcode{a}. + +\pnum +\returns +\tcode{*a.begin()} + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{array}, +\tcode{deque}, +\tcode{forward_list}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.back() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference; const_reference} for constant \tcode{a}. + +\pnum +\effects +Equivalent to: +\begin{codeblock} +auto tmp = a.end(); +--tmp; +return *tmp; +\end{codeblock} + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{array}, +\tcode{deque}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.emplace_front(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference} + +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Prepends an object of type \tcode{T} +constructed with \tcode{std::forward(args)...}. + +\pnum +\returns +\tcode{a.front()}. + +\pnum +\remarks +Required for +\tcode{deque}, +\tcode{forward_list}, and +\tcode{list}. +\end{itemdescr} + +\begin{itemdecl} +a.emplace_back(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference} + +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. +For \tcode{vector}, +\tcode{T} is also \oldconcept{MoveIn\-sert\-able} into \tcode{X}. + +\pnum +\effects +Appends an object of type \tcode{T} +constructed with \tcode{std::forward(args)...}. + +\pnum +\returns +\tcode{a.back()}. + +\pnum +\remarks +Required for +\tcode{deque}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.push_front(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Prepends a copy of \tcode{t}. + +\pnum +\remarks +Required for +\tcode{deque}, +\tcode{forward_list}, and +\tcode{list}. +\end{itemdescr} + +\begin{itemdecl} +a.push_front(rv) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{X}. + +\pnum +\effects +Prepends a copy of \tcode{rv}. + +\pnum +\remarks +Required for +\tcode{deque}, +\tcode{forward_list}, and +\tcode{list}. +\end{itemdescr} + +\begin{itemdecl} +a.push_back(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Appends a copy of \tcode{t}. + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{deque}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.push_back(rv) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{X}. + +\pnum +\effects +Appends a copy of \tcode{rv}. + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{deque}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.pop_front() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{a.empty()} is \tcode{false}. + +\pnum +\effects +Destroys the first element. + +\pnum +\remarks +Required for +\tcode{deque}, +\tcode{forward_list}, and +\tcode{list}. +\end{itemdescr} + +\begin{itemdecl} +a.pop_back() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{a.empty()} is \tcode{false}. + +\pnum +\effects +Destroys the last element. + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{deque}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a[n] +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference; const_reference} for constant \tcode{a} + +\pnum +\returns +\tcode{*(a.begin() + n)} + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{array}, +\tcode{deque}, and +\tcode{vector}. +\end{itemdescr} + +\begin{itemdecl} +a.at(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{reference; const_reference} for constant \tcode{a} + +\pnum +\returns +\tcode{*(a.begin() + n)} + +\pnum +\throws +\tcode{out_of_range} if \tcode{n >= a.size()}. + +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{array}, +\tcode{deque}, and +\tcode{vector}. +\end{itemdescr} + +\rSec2[container.node]{Node handles} + +\rSec3[container.node.overview]{Overview} + +\pnum +A \defn{node handle} is an object that accepts ownership of a single element +from an associative container\iref{associative.reqmts} or an unordered +associative container\iref{unord.req}. It may be used to transfer that +ownership to another container with compatible nodes. Containers with +compatible nodes have the same node handle type. Elements may be transferred in +either direction between container types in the same row of +\tref{container.node.compat}. + +\begin{floattable}{Container types with compatible nodes}{container.node.compat} +{ll} +\topline +\tcode{map} & \tcode{map} \\ +\rowsep +\tcode{map} & \tcode{multimap} \\ +\rowsep +\tcode{set} & \tcode{set} \\ +\rowsep +\tcode{set} & \tcode{multiset} \\ +\rowsep +\tcode{unordered_map} & \tcode{unordered_map} \\ +\rowsep +\tcode{unordered_map} & \tcode{unordered_multimap} \\ +\rowsep +\tcode{unordered_set} & \tcode{unordered_set} \\ +\rowsep +\tcode{unordered_set} & \tcode{unordered_multiset} \\ +\end{floattable} + +\pnum +If a node handle is not empty, then it contains an allocator that is equal to +the allocator of the container when the element was extracted. If a node handle +is empty, it contains no allocator. + +\pnum +Class \exposid{node-handle} is for exposition only. + +\pnum +If a user-defined specialization of \tcode{pair} exists for +\tcode{pair} or \tcode{pair}, where \tcode{Key} is the +container's \tcode{key_type} and \tcode{T} is the container's +\tcode{mapped_type}, the behavior of operations involving node handles is +undefined. + +\begin{codeblock} +template<@\unspecnc@> +class @\placeholder{node-handle}@ { +public: + // These type declarations are described in \ref{associative.reqmts} and \ref{unord.req}. + using value_type = @\seebelownc{}@; // not present for map containers + using key_type = @\seebelownc{}@; // not present for set containers + using mapped_type = @\seebelownc{}@; // not present for set containers + using allocator_type = @\seebelownc{}@; + +private: + using container_node_type = @\unspecnc@; // \expos + using ator_traits = allocator_traits; // \expos + + typename ator_traits::template + rebind_traits::pointer ptr_; // \expos + optional alloc_; // \expos + +public: + // \ref{container.node.cons}, constructors, copy, and assignment + constexpr @\placeholdernc{node-handle}@() noexcept : ptr_(), alloc_() {} + @\placeholdernc{node-handle}@(@\placeholdernc{node-handle}@&&) noexcept; + @\placeholdernc{node-handle}@& operator=(@\placeholdernc{node-handle}@&&); + + // \ref{container.node.dtor}, destructor + ~@\placeholdernc{node-handle}@(); + + // \ref{container.node.observers}, observers + value_type& value() const; // not present for map containers + key_type& key() const; // not present for set containers + mapped_type& mapped() const; // not present for set containers + + allocator_type get_allocator() const; + explicit operator bool() const noexcept; + [[nodiscard]] bool empty() const noexcept; + + // \ref{container.node.modifiers}, modifiers + void swap(@\placeholdernc{node-handle}@&) + noexcept(ator_traits::propagate_on_container_swap::value || + ator_traits::is_always_equal::value); + + friend void swap(@\placeholdernc{node-handle}@& x, @\placeholdernc{node-handle}@& y) noexcept(noexcept(x.swap(y))) { + x.swap(y); + } +}; +\end{codeblock} + +\rSec3[container.node.cons]{Constructors, copy, and assignment} + +\begin{itemdecl} +@\placeholdernc{node-handle}@(@\placeholdernc{node-handle}@&& nh) noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs a \exposid{node-handle} object initializing +\tcode{ptr_} with \tcode{nh.ptr_}. Move constructs \tcode{alloc_} with +\tcode{nh.alloc_}. Assigns \keyword{nullptr} to \tcode{nh.ptr_} and assigns +\tcode{nullopt} to \tcode{nh.alloc_}. +\end{itemdescr} + +\begin{itemdecl} +@\placeholdernc{node-handle}@& operator=(@\placeholdernc{node-handle}@&& nh); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +Either \tcode{!alloc_}, or +\tcode{ator_traits::propagate_on_container_move_assignment::\-value} +is \tcode{true}, or \tcode{alloc_ == nh.alloc_}. + +\pnum +\effects +\begin{itemize} +\item +If \tcode{ptr_ != nullptr}, destroys the \tcode{value_type} +subobject in the \tcode{container_node_type} object pointed to by \tcode{ptr_} +by calling \tcode{ator_traits::destroy}, then deallocates \tcode{ptr_} by +calling \tcode{ator_traits::template rebind_traits::deallocate}. +\item +Assigns \tcode{nh.ptr_} to \tcode{ptr_}. +\item +If \tcode{!alloc\textunderscore} or \tcode{ator_traits::propagate_on_container_move_assignment::value} +is \tcode{true}, \linebreak +move assigns \tcode{nh.alloc_} to \tcode{alloc_}. +\item +Assigns +\keyword{nullptr} to \tcode{nh.ptr_} and assigns \tcode{nullopt} to +\tcode{nh.alloc_}. +\end{itemize} + +\pnum +\returns +\tcode{*this}. + +\pnum +\throws +Nothing. +\end{itemdescr} + +\rSec3[container.node.dtor]{Destructor} + +\begin{itemdecl} +~@\placeholdernc{node-handle}@(); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +If \tcode{ptr_ != nullptr}, destroys the \tcode{value_type} subobject +in the \tcode{container_node_type} object pointed to by \tcode{ptr_} by calling +\tcode{ator_traits::destroy}, then deallocates \tcode{ptr_} by calling +\tcode{ator_traits::template rebind_traits::deallocate}. +\end{itemdescr} + +\rSec3[container.node.observers]{Observers} + +\begin{itemdecl} +value_type& value() const; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{empty() == false}. + +\pnum +\returns +A reference to the \tcode{value_type} subobject in the +\tcode{container_node_type} object pointed to by \tcode{ptr_}. + +\pnum +\throws +Nothing. +\end{itemdescr} + +\begin{itemdecl} +key_type& key() const; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{empty() == false}. + +\pnum +\returns +A non-const reference to the \tcode{key_type} member of the +\tcode{value_type} subobject in the \tcode{contain\-er_node_type} object +pointed to by \tcode{ptr_}. + +\pnum +\throws +Nothing. + +\pnum +\remarks +Modifying the key through the returned reference is permitted. +\end{itemdescr} + +\begin{itemdecl} +mapped_type& mapped() const; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{empty() == false}. + +\pnum +\returns +A reference to the \tcode{mapped_type} member of the +\tcode{value_type} subobject in the \tcode{container_node_type} object +pointed to by \tcode{ptr_}. + +\pnum +\throws +Nothing. +\end{itemdescr} + + +\begin{itemdecl} +allocator_type get_allocator() const; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{empty() == false}. + +\pnum +\returns +\tcode{*alloc_}. + +\pnum +\throws +Nothing. +\end{itemdescr} + +\begin{itemdecl} +explicit operator bool() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{ptr_ != nullptr}. +\end{itemdescr} + +\begin{itemdecl} +[[nodiscard]] bool empty() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{ptr_ == nullptr}. +\end{itemdescr} + +\rSec3[container.node.modifiers]{Modifiers} + +\begin{itemdecl} +void swap(@\placeholdernc{node-handle}@& nh) + noexcept(ator_traits::propagate_on_container_swap::value || + ator_traits::is_always_equal::value); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{!alloc_}, or \tcode{!nh.alloc_}, or +\tcode{ator_traits::propagate_on_container_swap::value} is \tcode{true}, +or \tcode{alloc_ == nh.alloc_}. + +\pnum +\effects +Calls \tcode{swap(ptr_, nh.ptr_)}. If \tcode{!alloc_}, or +\tcode{!nh.alloc_}, or \tcode{ator_traits::propagate_on_container_swap::value} +is \tcode{true} calls \tcode{swap(alloc_, nh.alloc_)}. +\end{itemdescr} + +\rSec2[container.insert.return]{Insert return type} + +\pnum +The associative containers with unique keys and the unordered containers with unique keys +have a member function \tcode{insert} that returns a nested type \tcode{insert_return_type}. +That return type is a specialization of the template specified in this subclause. + +\begin{codeblock} +template +struct @\placeholder{insert-return-type}@ +{ + Iterator position; + bool inserted; + NodeType node; +}; +\end{codeblock} + +\pnum +The name \exposid{insert-return-type} is exposition only. +\exposid{insert-return-type} has the template parameters, +data members, and special members specified above. +It has no base classes or members other than those specified. + +\rSec2[associative.reqmts]{Associative containers} + +\rSec3[associative.reqmts.general]{General} + +\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\iref{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 object. +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}. +\begin{note} +This is not necessarily the same as the result of \tcode{k1 == k2}. +\end{note} +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}. + +\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. +\begin{note} +\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. +\end{note} + +\pnum +In this subclause, +\begin{itemize} +\item +\tcode{X} denotes an associative container class, +\item +\tcode{a} denotes a value of type \tcode{X}, +\item +\tcode{a2} denotes a value of a type with nodes compatible with type +\tcode{X} (\tref{container.node.compat}), +\item +\tcode{b} denotes a possibly \keyword{const} value of type \tcode{X}, +\item +\tcode{u} denotes the name of a variable being declared, +\item +\tcode{a_uniq} denotes a value of type \tcode{X} +when \tcode{X} supports unique keys, +\item +\tcode{a_eq} denotes a value of type \tcode{X} +when \tcode{X} supports multiple keys, +\item +\tcode{a_tran} denotes a possibly \keyword{const} value of type \tcode{X} +when the \grammarterm{qualified-id} +\tcode{X::key_compare::is_transpa\-rent} is valid +and denotes a type\iref{temp.deduct}, +\item +\tcode{i} and \tcode{j} +meet the \oldconcept{InputIterator} requirements and refer to elements +implicitly convertible to +\tcode{value_type}, +\item +\range{i}{j} denotes a valid range, +\item +\tcode{p} denotes a valid constant iterator to \tcode{a}, +\item +\tcode{q} denotes a valid dereferenceable constant iterator to \tcode{a}, +\item +\tcode{r} denotes a valid dereferenceable iterator to \tcode{a}, +\item +\tcode{[q1, q2)} denotes a valid range of constant iterators in \tcode{a}, +\item +\tcode{il} designates an object of type \tcode{initializer_list}, +\item +\tcode{t} denotes a value of type \tcode{X::value_type}, +\item +\tcode{k} denotes a value of type \tcode{X::key_type}, and +\item +\tcode{c} denotes a possibly \keyword{const} value of type \tcode{X::key_compare}; +\item +\tcode{kl} is a value such that \tcode{a} is partitioned\iref{alg.sorting} +with respect to \tcode{c(x, kl)}, +with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; +\item +\tcode{ku} is a value such that \tcode{a} is partitioned with respect to +\tcode{!c(ku, x)}, +with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; +\item +\tcode{ke} is a value such that \tcode{a} is partitioned with respect to +\tcode{c(x, ke)} and \tcode{!c(ke, x)}, with \tcode{c(x, ke)} implying +\tcode{!c(ke, x)} and +with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; +\item +\tcode{kx} is a value such that +\begin{itemize} +\item +\tcode{a} is partitioned with respect to \tcode{c(x, kx)} and \tcode{!c(kx, x)}, +with \tcode{c(x, kx)} implying \tcode{!c(kx, x)} and +with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}, and +\item +\tcode{kx} is not convertible to +either \tcode{iterator} or \tcode{const_iterator}; and +\end{itemize} +\item +\tcode{A} denotes the storage allocator used by \tcode{X}, if any, or \tcode{allocator} otherwise, +\item +\tcode{m} denotes an allocator of a type convertible to \tcode{A}, +and \tcode{nh} denotes a non-const rvalue of type \tcode{X::node_type}. +\end{itemize} + +\pnum +A type \tcode{X} meets the \defnadj{associative}{container} requirements +if \tcode{X} meets all the requirements of an allocator-aware +container\iref{container.requirements.general} and +the following types, statements, and expressions are well-formed and +have the specified semantics, +except that for +\tcode{map} and \tcode{multimap}, the requirements placed on \tcode{value_type} +in \ref{container.alloc.reqmts} apply instead to \tcode{key_type} +and \tcode{mapped_type}. +\begin{note} +For example, in some cases \tcode{key_type} and \tcode{mapped_type} +are required to be \oldconcept{CopyAssignable} even though the associated +\tcode{value_type}, \tcode{pair}, is not +\oldconcept{CopyAssignable}. +\end{note} + +% Local command to index names as members of all ordered containers. +\newcommand{\indexordmem}[1]{% +\indexlibrary{\idxcode{#1}!ordered associative containers}% +\indexlibrary{\idxcode{set}!\idxcode{#1}}% +\indexlibrary{\idxcode{map}!\idxcode{#1}}% +\indexlibrary{\idxcode{multiset}!\idxcode{#1}}% +\indexlibrary{\idxcode{multimap}!\idxcode{#1}}% +} + +\indexordmem{key_type}% +\begin{itemdecl} +typename X::key_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key}. +\end{itemdescr} + +\indexordmem{mapped_type}% +\begin{itemdecl} +typename X::mapped_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{T}. + +\pnum +\remarks +For \tcode{map} and \tcode{multimap} only. +\end{itemdescr} + +\indexordmem{value_type}% +\begin{itemdecl} +typename X::value_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key} for \tcode{set} and \tcode{multiset} only; +\tcode{pair} for \tcode{map} and \tcode{multimap} only. + +\pnum +\expects +\tcode{X::value_type} is \oldconcept{Erasable} from \tcode{X}. +\end{itemdescr} + +\indexordmem{key_compare}% +\begin{itemdecl} +typename X::key_compare +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Compare}. + +\pnum +\expects +\tcode{key_compare} is \oldconcept{CopyConstructible}. +\end{itemdescr} + +\indexordmem{value_compare}% +\begin{itemdecl} +typename X::value_compare +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A binary predicate type. +It 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}. +\end{itemdescr} + +\indexordmem{node_type}% +\begin{itemdecl} +typename X::node_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A specialization of +the \exposid{node-handle} class template\iref{container.node}, +such that the public nested types are +the same types as the corresponding types in \tcode{X}. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(c) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs an empty container. +Uses a copy of \tcode{c} as a comparison object. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X u = X(); +X u; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements. + +\pnum +\effects +Constructs an empty container. +Uses \tcode{Compare()} as a comparison object. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(i, j, c) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\effects +Constructs an empty container and +inserts elements from the range \range{i}{j} into it; +uses \tcode{c} as a comparison object. + +\pnum +\complexity +$N \log N$ in general, where $N$ has the value \tcode{distance(i, j)}; +linear if \range{i}{j} is sorted with \tcode{value_comp()}. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements. +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\effects +Constructs an empty container and +inserts elements from the range \range{i}{j} into it; +uses \tcode{Compare()} as a comparison object. + +\pnum +\complexity +$N \log N$ in general, where $N$ has the value \tcode{distance(i, j)}; +linear if \range{i}{j} is sorted with \tcode{value_comp()}. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(il, c) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end(), c)}. +\end{itemdescr} + +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end())}. +\end{itemdescr} + +\begin{itemdecl} +a = il +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&} + +\pnum +\expects +\tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X} +and \oldconcept{CopyAssignable}. + +\pnum +\effects +Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. +All existing elements of \tcode{a} are either assigned to or destroyed. + +\pnum +\complexity +$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()}. +\end{itemdescr} + +\indexordmem{key_comp}% +\begin{itemdecl} +b.key_comp() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::key_compare} + +\pnum +\returns +The comparison object out of which \tcode{b} was constructed. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexordmem{value_comp}% +\begin{itemdecl} +b.value_comp() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::value_compare} + +\pnum +\returns +An object of \tcode{value_compare} constructed out of the comparison object. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexordmem{emplace}% +\begin{itemdecl} +a_uniq.emplace(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Inserts a \tcode{value_type} object \tcode{t} +constructed with \tcode{std::forward(args)...} +if and only if there is no element in the container +with key equivalent to the key of \tcode{t}. + +\pnum +\returns +The \tcode{bool} component of the returned pair is \tcode{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}. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{emplace}% +\begin{itemdecl} +a_eq.emplace(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Inserts a \tcode{value_type} object \tcode{t} +constructed with \tcode{std::forward(args)...}. +If a range containing elements equivalent to \tcode{t} exists in \tcode{a_eq}, +\tcode{t} is inserted at the end of that range. + +\pnum +\returns +An iterator pointing to the newly inserted element. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{emplace_hint}% +\begin{itemdecl} +a.emplace_hint(p, args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +Equivalent to \tcode{a.emplace(std::forward(args)...)}, +except that the element is inserted as close as possible to +the position just prior to \tcode{p}. + +\pnum +\returns +An iterator pointing to the element +with the key equivalent to the newly inserted element. + +\pnum +\complexity +Logarithmic in general, but +amortized constant if the element is inserted right before \tcode{p}. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a_uniq.insert(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Inserts \tcode{t} if and only if there is no element in the container +with key equivalent to the key of \tcode{t}. + +\pnum +\returns +The \tcode{bool} component of the returned pair is \tcode{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}. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a_eq.insert(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\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. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a.insert(p, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\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. +\tcode{t} is inserted as close as possible to +the position just prior to \tcode{p}. + +\pnum +\returns +An iterator pointing to the element with key equivalent to the key of \tcode{t}. + +\pnum +\complexity +Logarithmic in general, but +amortized constant if \tcode{t} is inserted right before \tcode{p}. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a.insert(i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. +Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}. + +\pnum +\effects +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. + +\pnum +\complexity +$N \log (\tcode{a.size()} + N)$, where $N$ has the value \tcode{distance(i, j)}. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a.insert(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.insert(il.begin(), il.end())}. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a_uniq.insert(nh) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{insert_return_type} + +\pnum +\expects +\tcode{nh} is empty or +\tcode{a_uniq.get_allocator() == nh.get_allocator()} is \tcode{true}. + +\pnum +\effects +If \tcode{nh} is empty, has no effect. +Otherwise, inserts the element owned by \tcode{nh} if and only if +there is no element in the container with a key equivalent to \tcode{nh.key()}. + +\pnum +\returns +If \tcode{nh} is empty, \tcode{inserted} is \tcode{false}, +\tcode{position} is \tcode{end()}, and \tcode{node} is empty. +Otherwise if the insertion took place, \tcode{inserted} is \tcode{true}, +\tcode{position} points to the inserted element, and \tcode{node} is empty; +if the insertion failed, \tcode{inserted} is \tcode{false}, +\tcode{node} has the previous value of \tcode{nh}, and +\tcode{position} points to an element with a key equivalent to \tcode{nh.key()}. + +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a_eq.insert(nh) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +\tcode{nh} is empty or +\tcode{a_eq.get_allocator() == nh.get_allocator()} is \tcode{true}. + +\pnum +\effects +If \tcode{nh} is empty, has no effect and returns \tcode{a_eq.end()}. +Otherwise, inserts the element owned by \tcode{nh} and +returns an iterator pointing to the newly inserted element. +If a range containing elements with keys equivalent to \tcode{nh.key()} +exists in \tcode{a_eq}, +the element is inserted at the end of that range. + +\pnum +\ensures +\tcode{nh} is empty. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{insert}% +\begin{itemdecl} +a.insert(p, nh) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +\tcode{nh} is empty or +\tcode{a.get_allocator() == nh.get_allocator()} is \tcode{true}. + +\pnum +\effects +If \tcode{nh} is empty, has no effect and returns \tcode{a.end()}. +Otherwise, inserts the element owned by \tcode{nh} if and only if +there is no element with key equivalent to \tcode{nh.key()} +in containers with unique keys; +always inserts the element owned by \tcode{nh} +in containers with equivalent keys. +The element is inserted as close as possible to +the position just prior to \tcode{p}. + +\pnum +\ensures +\tcode{nh} is empty if insertion succeeds, unchanged if insertion fails. + +\pnum +\returns +An iterator pointing to the element with key equivalent to \tcode{nh.key()}. + +\pnum +\complexity +Logarithmic in general, but +amortized constant if the element is inserted right before \tcode{p}. +\end{itemdescr} + + +\indexordmem{extract}% +\begin{itemdecl} +a.extract(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +Removes the first element in the container with key equivalent to \tcode{k}. + +\pnum +\returns +A \tcode{node_type} owning the element if found, +otherwise an empty \tcode{node_type}. + +\pnum +\complexity +$\log (\tcode{a.size()})$ +\end{itemdescr} + +\indexordmem{extract}% +\begin{itemdecl} +a_tran.extract(kx) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +Removes the first element in the container with key \tcode{r} +such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}. + +\pnum +\returns +A \tcode{node_type} owning the element if found, +otherwise an empty \tcode{node_type}. + +\pnum +\complexity +$\log(\tcode{a_tran.size()})$ +\end{itemdescr} + +\indexordmem{extract}% +\begin{itemdecl} +a.extract(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +Removes the element pointed to by \tcode{q}. + +\pnum +\returns +A \tcode{node_type} owning that element. + +\pnum +\complexity +Amortized constant. +\end{itemdescr} + +\indexordmem{merge}% +\begin{itemdecl} +a.merge(a2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{a.get_allocator() == a2.get_allocator()}. + +\pnum +\effects +Attempts to extract each element in \tcode{a2} and insert it into \tcode{a} +using the comparison object of \tcode{a}. +In containers with unique keys, +if there is an element in \tcode{a} with key equivalent to +the key of an element from \tcode{a2}, +then that element is not extracted from \tcode{a2}. + +\pnum +\ensures +Pointers and references to the transferred elements of \tcode{a2} +refer to those same elements but as members of \tcode{a}. +Iterators referring to the transferred elements +will continue to refer to their elements, +but they now behave as iterators into \tcode{a}, not into \tcode{a2}. + +\pnum +\throws +Nothing unless the comparison object throws. + +\pnum +\complexity +$N \log(\tcode{a.size()+} N)$, where $N$ has the value \tcode{a2.size()}. +\end{itemdescr} + +\indexordmem{erase}% +\begin{itemdecl} +a.erase(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\effects +Erases all elements in the container with key equivalent to \tcode{k}. + +\pnum +\returns +The number of erased elements. + +\pnum +\complexity +$\log (\tcode{a.size()}) + \tcode{a.count(k)}$ +\end{itemdescr} + +\indexordmem{erase}% +\begin{itemdecl} +a_tran.erase(kx) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\effects +Erases all elements in the container with key \tcode{r} +such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}. + +\pnum +\returns +The number of erased elements. + +\pnum +\complexity +$\log(\tcode{a_tran.size())} + \tcode{a_tran.count(kx)}$ +\end{itemdescr} + +\indexordmem{erase}% +\begin{itemdecl} +a.erase(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +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()}. + +\pnum +\complexity +Amortized constant. +\end{itemdescr} + +\indexordmem{erase}% +\begin{itemdecl} +a.erase(r) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +Erases the element pointed to by \tcode{r}. + +\pnum +\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()}. + +\pnum +\complexity +Amortized constant. +\end{itemdescr} + +\indexordmem{erase}% +\begin{itemdecl} +a.erase(q1, q2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +Erases all the elements in the range \range{q1}{q2}. + +\pnum +\returns +An iterator pointing 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 +\complexity +$\log(\tcode{a.size()}) + N$, where $N$ has the value \tcode{distance(q1, q2)}. +\end{itemdescr} + +\indexordmem{clear}% +\begin{itemdecl} +a.clear() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.erase(a.begin(), a.end())}. + +\pnum +\ensures +\tcode{a.empty()} is \tcode{true}. + +\pnum +\complexity +Linear in \tcode{a.size()}. +\end{itemdescr} + +\indexordmem{find}% +\begin{itemdecl} +b.find(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. + +\pnum +\returns +An iterator pointing to an element with the key equivalent to \tcode{k}, or +\tcode{b.end()} if such an element is not found. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{find}% +\begin{itemdecl} +a_tran.find(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}. + +\pnum +\returns +An iterator pointing to an element with key \tcode{r} +such that \tcode{!c(r, ke) \&\& !c(ke, r)} is \tcode{true}, or +\tcode{a_tran.end()} if such an element is not found. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{count}% +\begin{itemdecl} +b.count(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\returns +The number of elements with key equivalent to \tcode{k}. + +\pnum +\complexity +$\log (\tcode{b.size()}) + \tcode{b.count(k)}$ +\end{itemdescr} + +\indexordmem{count}% +\begin{itemdecl} +a_tran.count(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\returns +The number of elements with key \tcode{r} +such that \tcode{!c(r, ke) \&\& !c(ke, r)}. + +\pnum +\complexity +$\log (\tcode{a_tran.size()}) + \tcode{a_tran.count(ke)}$ +\end{itemdescr} + +\indexordmem{contains}% +\begin{itemdecl} +b.contains(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{bool} + +\pnum +\effects +Equivalent to: \tcode{return b.find(k) != b.end();} +\end{itemdescr} + +\indexordmem{contains}% +\begin{itemdecl} +a_tran.contains(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{bool} + +\pnum +\effects +Equivalent to: \tcode{return a_tran.find(ke) != a_tran.end();} +\end{itemdescr} + +\indexordmem{lower_bound}% +\begin{itemdecl} +b.lower_bound(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. + +\pnum +\returns +An iterator pointing to the first element with key not less than \tcode{k}, +or \tcode{b.end()} if such an element is not found. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{lower_bound}% +\begin{itemdecl} +a_tran.lower_bound(kl) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}. + +\pnum +\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. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{upper_bound}% +\begin{itemdecl} +b.upper_bound(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. + +\pnum +\returns +An iterator pointing to the first element with key greater than \tcode{k}, +or \tcode{b.end()} if such an element is not found. + +\pnum +\complexity +Logarithmic, +\end{itemdescr} + +\indexordmem{upper_bound}% +\begin{itemdecl} +a_tran.upper_bound(ku) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for constant \tcode{a_tran}. + +\pnum +\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. + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{equal_range}% +\begin{itemdecl} +b.equal_range(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for constant \tcode{b}. + +\pnum +\effects +Equivalent to: \tcode{return make_pair(b.lower_bound(k), b.upper_bound(k));} + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\indexordmem{equal_range}% +\begin{itemdecl} +a_tran.equal_range(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for constant \tcode{a_tran}. + +\pnum +\effects +Equivalent to: +\tcode{return make_pair(a_tran.lower_bound(ke), a_tran.upper_bound(ke));} + +\pnum +\complexity +Logarithmic. +\end{itemdescr} + +\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 \tcode{extract} members invalidate only iterators to the removed element; +pointers and references to the removed element remain valid. However, accessing +the element through such pointers and references while the element is owned by +a \tcode{node_type} is undefined behavior. References and pointers to an element +obtained while it is owned by a \tcode{node_type} are invalidated if the element +is successfully inserted. + +\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, the following condition holds: + +\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, through either 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{contains}, +\tcode{lower_bound}, \tcode{upper_bound}, \tcode{equal_range}, +\tcode{erase}, and \tcode{extract} +shall not participate in overload resolution unless +the \grammarterm{qualified-id} \tcode{Compare::is_transparent} is valid +and denotes a type\iref{temp.deduct}. +Additionally, the member function templates \tcode{extract} and \tcode{erase} +shall not participate in overload resolution if +\tcode{is_convertible_v || is_convertible_v} +is \tcode{true}, +where \tcode{K} is the type substituted as the first template argument. + +\pnum +A deduction guide for an associative container shall not participate in overload resolution +if any of the following are true: +\begin{itemize} +\item It has an \tcode{InputIterator} template parameter +and a type that does not qualify as an input iterator is deduced for that parameter. + +\item It has an \tcode{Allocator} template parameter +and a type that does not qualify as an allocator is deduced for that parameter. + +\item It has a \tcode{Compare} template parameter +and a type that qualifies as an allocator is deduced for that parameter. +\end{itemize} + +\rSec3[associative.reqmts.except]{Exception safety guarantees}% +\indextext{associative containers!exception safety}% +\indextext{associative containers!requirements}% + +\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). + +\rSec2[unord.req]{Unordered associative containers}% +\indextext{associative containers!unordered|see{unordered associative containers}} +\indextext{hash tables|see{unordered associative containers}} + +\rSec3[unord.req.general]{General} + +\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 functions}% +\indextext{unordered associative containers!requirements}% +\indextext{requirements!container!not required for unordered associated containers}% +Unordered associative containers conform to the requirements for +Containers\iref{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 \oldconcept{Hash} +requirements\iref{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} are +considered equivalent if the container's +key equality predicate +\tcode{pred(k1, k2)} is valid and 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. +\begin{note} +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. +\end{note} +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 \defnx{equivalent-key groups}{equivalent-key group} 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{pair}. + +\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. +\begin{note} +\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. +\end{note} + +\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 +\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 this subclause, +\begin{itemize} +\item +\tcode{X} denotes an unordered associative container class, +\item +\tcode{a} denotes a value of type \tcode{X}, +\item +\tcode{a2} denotes a value of a type with nodes compatible + with type \tcode{X} (\tref{container.node.compat}), +\item +\tcode{b} denotes a possibly const value of type \tcode{X}, +\item +\tcode{a_uniq} denotes a value of type \tcode{X} + when \tcode{X} supports unique keys, +\item +\tcode{a_eq} denotes a value of type \tcode{X} + when \tcode{X} supports equivalent keys, +\item +\tcode{a_tran} denotes a possibly const value of type \tcode{X} + when the \grammarterm{qualified-id}s + \tcode{X::key_equal::is_transparent} and + \tcode{X::hasher::is_transparent} + are both valid and denote types\iref{temp.deduct}, +\item +\tcode{i} and \tcode{j} denote input iterators + that refer to \tcode{value_type}, +\item +\tcode{[i, j)} denotes a valid range, +\item +\tcode{p} and \tcode{q2} denote valid constant iterators to \tcode{a}, +\item +\tcode{q} and \tcode{q1} denote + valid dereferenceable constant iterators to \tcode{a}, +\item +\tcode{r} denotes a valid dereferenceable iterator to \tcode{a}, +\item +\tcode{[q1, q2)} denotes a valid range in \tcode{a}, +\item +\tcode{il} denotes a value of type \tcode{initializer_list}, +\item +\tcode{t} denotes a value of type \tcode{X::value_type}, +\item +\tcode{k} denotes a value of type \tcode{key_type}, +\item +\tcode{hf} denotes a possibly const value of type \tcode{hasher}, +\item +\tcode{eq} denotes a possibly const value of type \tcode{key_equal}, +\item +\tcode{ke} is a value such that + \begin{itemize} + \item \tcode{eq(r1, ke) == eq(ke, r1)}, + \item \tcode{hf(r1) == hf(ke)} if \tcode{eq(r1, ke)} is \tcode{true}, and + \item \tcode{(eq(r1, ke) \&\& eq(r1, r2)) == eq(r2, ke)}, + \end{itemize} + where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran}, +\item +\tcode{kx} is a value such that + \begin{itemize} + \item \tcode{eq(r1, kx) == eq(kx, r1)}, + \item \tcode{hf(r1) == hf(kx)} if \tcode{eq(r1, kx)} is \tcode{true}, + \item \tcode{(eq(r1, kx) \&\& eq(r1, r2)) == eq(r2, kx)}, and + \item \tcode{kx} is not convertible to + either \tcode{iterator} or \tcode{const_iterator}, + \end{itemize} + where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran}, +\item +\tcode{n} denotes a value of type \tcode{size_type}, +\item +\tcode{z} denotes a value of type \tcode{float}, and +\item +\tcode{nh} denotes a non-const rvalue of type \tcode{X::node_type}. +\end{itemize} + +\pnum +A type \tcode{X} meets +the \defnadj{unordered associative}{container} requirements +if \tcode{X} meets all the requirements of +an allocator-aware container\iref{container.requirements.general} and +the following types, statements, and expressions are well-formed and +have the specified semantics, +except that for \tcode{unordered_map} and \tcode{unordered_multimap}, +the requirements placed on \tcode{value_type} in \ref{container.alloc.reqmts} +apply instead to \tcode{key_type} and \tcode{mapped_type}. +\begin{note} +For example, \tcode{key_type} and \tcode{mapped_type} +are sometimes required to be \oldconcept{CopyAssignable} +even though the associated \tcode{value_type}, +\tcode{pair}, +is not \oldconcept{CopyAssignable}. +\end{note} + +% Local command to index names as members of all unordered containers. +\newcommand{\indexunordmem}[1]{% +\indexlibrary{\idxcode{#1}!unordered associative containers}% +\indexlibrary{\idxcode{unordered_set}!\idxcode{#1}}% +\indexlibrary{\idxcode{unordered_map}!\idxcode{#1}}% +\indexlibrary{\idxcode{unordered_multiset}!\idxcode{#1}}% +\indexlibrary{\idxcode{unordered_multimap}!\idxcode{#1}}% +} + +\indexunordmem{key_type}% +\begin{itemdecl} +typename X::key_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key}. +\end{itemdescr} + +\indexunordmem{mapped_type}% +\begin{itemdecl} +typename X::mapped_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{T}. + +\pnum +\remarks +For \tcode{unordered_map} and \tcode{unordered_multimap} only. +\end{itemdescr} + +\indexunordmem{value_type}% +\begin{itemdecl} +typename X::value_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key} for \tcode{unordered_set} and \tcode{unordered_multiset} only; +\tcode{pair} +for \tcode{unordered_map} and \tcode{unordered_multimap} only. + +\pnum +\expects +\tcode{value_type} is \oldconcept{Erasable} from \tcode{X}. +\end{itemdescr} + +\indexunordmem{hasher}% +\begin{itemdecl} +typename X::hasher +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Hash}. + +\pnum +\expects +\tcode{Hash} is a unary function object type +such that the expression \tcode{hf(k)} has type \tcode{size_t}. +\end{itemdescr} + +\indexunordmem{key_equal}% +\begin{itemdecl} +typename X::key_equal +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Pred}. + +\pnum +\expects +\tcode{Pred} meets the \oldconcept{CopyConstructible} requirements. +\tcode{Pred} is a binary predicate that takes two arguments of type \tcode{Key}. +\tcode{Pred} is an equivalence relation. +\end{itemdescr} + +\indexunordmem{local_iterator}% +\begin{itemdecl} +typename X::local_iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An iterator type +whose category, value type, difference type, and pointer and reference types +are the same as \tcode{X::iterator}'s. +\begin{note} +A \tcode{local_iterator} object can be used to iterate through a single bucket, +but cannot be used to iterate across buckets. +\end{note} +\end{itemdescr} + +\indexunordmem{const_local_iterator}% +\begin{itemdecl} +typename X::const_local_iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An iterator type +whose category, value type, difference type, and pointer and reference types +are the same as \tcode{X::const_iterator}'s. +\begin{note} +A \tcode{const_local_iterator} object can be used to iterate +through a single bucket, +but cannot be used to iterate across buckets. +\end{note} +\end{itemdescr} + +\indexunordmem{node_type}% +\begin{itemdecl} +typename X::node_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A specialization of a \exposid{node-handle} class template\iref{container.node}, +such that the public nested types are the same types +as the corresponding types in \tcode{X}. +\end{itemdescr} + +\indexlibraryctor{unordered_set}% +\indexlibraryctor{unordered_map}% +\indexlibraryctor{unordered_multiset}% +\indexlibraryctor{unordered_multimap}% +\begin{itemdecl} +X(n, hf, eq) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\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. + +\pnum +\complexity +\bigoh{\tcode{n}} +\end{itemdescr} + +\begin{itemdecl} +X(n, hf) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{key_equal} meets the \oldconcept{DefaultConstructible} requirements. + +\pnum +\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. + +\pnum +\complexity +\bigoh{\tcode{n}} +\end{itemdescr} + +\begin{itemdecl} +X(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{hasher} and \tcode{key_equal} +meet the \oldconcept{DefaultConstructible} requirements. + +\pnum +\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. + +\pnum +\complexity +\bigoh{\tcode{n}} +\end{itemdescr} + +\begin{itemdecl} +X a = X(); +X a; +\end{itemdecl} + +\begin{itemdescr} +\expects +\tcode{hasher} and \tcode{key_equal} meet +the \oldconcept{DefaultConstructible} requirements. + +\pnum +\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. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X(i, j, n, hf, eq) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\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 \range{i}{j} into it. + +\pnum +\complexity +Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case \bigoh{N^2}. +\end{itemdescr} + +\begin{itemdecl} +X(i, j, n, hf) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{key_equal} meets the \oldconcept{DefaultConstructible} requirements. +\tcode{value_type} is +\oldconcept{\-EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\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 \range{i}{j} into it. + +\pnum +\complexity +Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case \bigoh{N^2}. +\end{itemdescr} + +\begin{itemdecl} +X(i, j, n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{hasher} and \tcode{key_equal} meet +the \oldconcept{DefaultConstructible} requirements. +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\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 \range{i}{j} into it. + +\pnum +\complexity +Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case \bigoh{N^2}. +\end{itemdescr} + +\begin{itemdecl} +X(i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{hasher} and \tcode{key_equal} meet +the \oldconcept{DefaultConstructible} requirements. +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. + +\pnum +\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 \range{i}{j} into it. + +\pnum +\complexity +Average case \bigoh{N} ($N$ is \tcode{distance(i, j)}), worst case \bigoh{N^2}. +\end{itemdescr} + +\begin{itemdecl} +X(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end())}. +\end{itemdescr} + +\begin{itemdecl} +X(il, n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end(), n)}. +\end{itemdescr} + +\begin{itemdecl} +X(il, n, hf) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end(), n, hf)}. +\end{itemdescr} + +\begin{itemdecl} +X(il, n, hf, eq) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end(), n, hf, eq)}. +\end{itemdescr} + +\begin{itemdecl} +X(b) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +In addition to the container requirements\iref{container.requirements.general}, +copies the hash function, predicate, and maximum load factor. + +\pnum +\complexity +Average case linear in \tcode{b.size()}, worst case quadratic. +\end{itemdescr} + +\begin{itemdecl} +a = b +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&} + +\pnum +\effects +In addition to the container requirements, +copies the hash function, predicate, and maximum load factor. + +\pnum +\complexity +Average case linear in \tcode{b.size()}, worst case quadratic. +\end{itemdescr} + +\begin{itemdecl} +a = il +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X\&} + +\pnum +\expects +\tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X} +and \oldconcept{CopyAssignable}. + +\pnum +\effects +Assigns the range \range{il.begin()}{il.end()} into \tcode{a}. +All existing elements of \tcode{a} are either assigned to or destroyed. + +\pnum +\complexity +Average case linear in \tcode{il.size()}, worst case quadratic. +\end{itemdescr} + +\indexunordmem{hash_function}% +\begin{itemdecl} +b.hash_function() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{hasher} + +\pnum +\returns +\tcode{b}'s hash function. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{key_eq}% +\begin{itemdecl} +b.key_eq() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{key_equal} + +\pnum +\returns +\tcode{b}'s key equality predicate. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{emplace}% +\begin{itemdecl} +a_uniq.emplace(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Inserts a \tcode{value_type} object \tcode{t} +constructed with \tcode{std::forward(args)...} if and only if +there is no element in the container +with key equivalent to the key of \tcode{t}. + +\pnum +\returns +The \tcode{bool} component of the returned pair is \tcode{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}. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.size()}}. +\end{itemdescr} + +\indexunordmem{emplace}% +\begin{itemdecl} +a_eq.emplace(args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Inserts a \tcode{value_type} object \tcode{t} +constructed with \tcode{std::forward(args)...} and + +\pnum +\returns +An iterator pointing to the newly inserted element. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.size()}}. +\end{itemdescr} + +\indexunordmem{emplace_hint}% +\begin{itemdecl} +a.emplace_hint(p, args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. + +\pnum +\effects +Equivalent to \tcode{a.emplace(std::forward(args)...)}. + +\pnum +\returns +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. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a_uniq.insert(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Inserts \tcode{t} if and only if there is no element in the container +with key equivalent to the key of \tcode{t}. + +\pnum +\returns +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}. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.size()}}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a_eq.insert(t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Inserts \tcode{t}. + +\pnum +\returns +An iterator pointing to the newly inserted element. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.size()}}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a.insert(p, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\expects +If \tcode{t} is a non-const rvalue, +\tcode{value_type} is \oldconcept{MoveInsertable} into \tcode{X}; +otherwise, \tcode{value_type} is \oldconcept{CopyInsertable} into \tcode{X}. + +\pnum +\effects +Equivalent to \tcode{a.insert(t)}. +The iterator \tcode{p} is a hint pointing to where the search should start. +Implementations are permitted to ignore the hint. + +\pnum +\returns +An iterator pointing to +the element with the key equivalent to that of \tcode{t}. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a.insert(i, j) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. +Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}. + +\pnum +\effects +Equivalent to \tcode{a.insert(t)} for each element in \tcode{[i,j)}. + +\pnum +\complexity +Average case \bigoh{N}, where $N$ is \tcode{distance(i, j)}, +worst case \bigoh{N(\tcode{a.size()} + 1)}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a.insert(il) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.insert(il.begin(), il.end())}. +\end{itemdescr} -\tcode{a.assign(n,t)} & - \keyword{void} & - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X} - and \oldconcept{CopyAssignable}. - \tcode{t} is not a reference into \tcode{a}.\br - \effects Replaces elements in \tcode{a} with \tcode{n} copies of \tcode{t}. - Invalidates all references, pointers and iterators - referring to the elements of \tcode{a}. - For \tcode{vector} and \tcode{deque}, - also invalidates the past-the-end iterator. \\ -\end{libreqtab3} +\indexunordmem{insert}% +\begin{itemdecl} +a_uniq.insert(nh) +\end{itemdecl} +\begin{itemdescr} \pnum -The iterator returned from -\tcode{a.insert(p, t)} -points to the copy of -\tcode{t} -inserted into -\tcode{a}. +\result +\tcode{insert_return_type} \pnum -The iterator returned from \tcode{a.insert(p, rv)} points to the copy of \tcode{rv} -inserted into \tcode{a}. +\expects +\tcode{nh} is empty or +\tcode{a_uniq.get_allocator() == nh.get_allocator()} is \tcode{true}. \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}. +\effects +If \tcode{nh} is empty, has no effect. +Otherwise, inserts the element owned by \tcode{nh} if and only if +there is no element in the container with a key equivalent to \tcode{nh.key()}. \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}. +\ensures +If \tcode{nh} is empty, \tcode{inserted} is \tcode{false}, +\tcode{position} is \tcode{end()}, and \tcode{node} is empty. +Otherwise if the insertion took place, \tcode{inserted} is \tcode{true}, +\tcode{position} points to the inserted element, and \tcode{node} is empty; +if the insertion failed, \tcode{inserted} is \tcode{false}, +\tcode{node} has the previous value of \tcode{nh}, and \tcode{position} +points to an element with a key equivalent to \tcode{nh.key()}. \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. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.size()}}. +\end{itemdescr} -\pnum -The iterator returned from \tcode{a.emplace(p, args)} points to the new element -constructed from \tcode{args} into \tcode{a}. +\indexunordmem{insert}% +\begin{itemdecl} +a_eq.insert(nh) +\end{itemdecl} +\begin{itemdescr} \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. +\result +\tcode{iterator} \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. +\expects +\tcode{nh} is empty or +\tcode{a_eq.get_allocator() == nh.get_allocator()} is \tcode{true}. \pnum -For every sequence container defined in this Clause and in \ref{strings}: -\begin{itemize} -\item If the constructor -\begin{codeblock} -template - 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 - @\placeholdernc{return-type}@ @\placeholdernc{F}@(const_iterator p, - InputIterator first, InputIterator last); // such as \tcode{insert} - -template - @\placeholdernc{return-type}@ @\placeholdernc{F}@(InputIterator first, InputIterator last); // such as \tcode{append}, \tcode{assign} - -template - @\placeholdernc{return-type}@ @\placeholdernc{F}@(const_iterator i1, const_iterator i2, - InputIterator first, InputIterator last); // such as \tcode{replace} -\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. - -\item A deduction guide for a sequence container shall not participate in overload resolution -if it has an \tcode{InputIterator} template parameter and a type that does not -qualify as an input iterator is deduced for that parameter, -or if it has an \tcode{Allocator} template parameter and a type that does not -qualify as an allocator is deduced for that parameter. -\end{itemize} +\effects +If \tcode{nh} is empty, has no effect and returns \tcode{a_eq.end()}. +Otherwise, inserts the element owned by \tcode{nh} and +returns an iterator pointing to the newly inserted element. \pnum -\tref{container.seq.opt} 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} -{container.seq.opt} -\\ \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{ --tmp;}\br - \tcode{ return *tmp; \}} & - \tcode{basic_string}, - \tcode{array}, - \tcode{deque}, - \tcode{list}, - \tcode{vector} - \\ \rowsep - -\tcode{a.emplace_\-front(args)} & - \tcode{reference} & - \effects Prepends an object of type \tcode{T} constructed with \tcode{std::forward<\brk{}Args\brk{}>(\brk{}args)...}.\br - \expects \tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \returns \tcode{a.front()}. & - \tcode{deque}, - \tcode{forward_list}, - \tcode{list} - \\ \rowsep - -\tcode{a.emplace_\-back(args)} & - \tcode{reference} & - \effects Appends an object of type \tcode{T} constructed with \tcode{std::forward<\brk{}Args\brk{}>(\brk{}args)...}.\br - \expects \tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}. For \tcode{vector}, \tcode{T} - is also - \oldconcept{MoveInsertable} into \tcode{X}. - \returns \tcode{a.back()}. & - \tcode{deque}, - \tcode{list}, - \tcode{vector} - \\ \rowsep - -\tcode{a.push_front(t)} & - \keyword{void} & - \effects Prepends a copy of \tcode{t}.\br - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X}. - & - \tcode{deque}, - \tcode{forward_list}, - \tcode{list} - \\ \rowsep - -\tcode{a.push_front(rv)} & - \keyword{void} & - \effects Prepends a copy of \tcode{rv}.\br - \expects \tcode{T} is - \oldconcept{MoveInsertable} into \tcode{X}. - & - \tcode{deque}, - \tcode{forward_list}, - \tcode{list} - \\ \rowsep - -\tcode{a.push_back(t)} & - \keyword{void} & - \effects Appends a copy of \tcode{t}.\br - \expects \tcode{T} is - \oldconcept{CopyInsertable} into \tcode{X}. - & - \tcode{basic_string}, - \tcode{deque}, - \tcode{list}, - \tcode{vector} - \\ \rowsep - -\tcode{a.push_back(rv)} & - \keyword{void} & - \effects Appends a copy of \tcode{rv}.\br - \expects \tcode{T} is - \oldconcept{MoveInsertable} into \tcode{X}. - & - \tcode{basic_string}, - \tcode{deque}, - \tcode{list}, - \tcode{vector} - \\ \rowsep - -\tcode{a.pop_front()} & - \keyword{void} & - \effects Destroys the first element.\br - \expects \tcode{a.empty()} is \tcode{false}. & - \tcode{deque}, - \tcode{forward_list}, - \tcode{list} - \\ \rowsep - -\tcode{a.pop_back()} & - \keyword{void} & - \effects Destroys the last element.\br - \expects \tcode{a.empty()} is \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[container.node]{Node handles} - -\rSec3[container.node.overview]{Overview} +\ensures +\tcode{nh} is empty. \pnum -A \defn{node handle} is an object that accepts ownership of a single element -from an associative container\iref{associative.reqmts} or an unordered -associative container\iref{unord.req}. It may be used to transfer that -ownership to another container with compatible nodes. Containers with -compatible nodes have the same node handle type. Elements may be transferred in -either direction between container types in the same row of -\tref{container.node.compat}. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.size()}}. +\end{itemdescr} -\begin{floattable}{Container types with compatible nodes}{container.node.compat} -{ll} -\topline -\tcode{map} & \tcode{map} \\ -\rowsep -\tcode{map} & \tcode{multimap} \\ -\rowsep -\tcode{set} & \tcode{set} \\ -\rowsep -\tcode{set} & \tcode{multiset} \\ -\rowsep -\tcode{unordered_map} & \tcode{unordered_map} \\ -\rowsep -\tcode{unordered_map} & \tcode{unordered_multimap} \\ -\rowsep -\tcode{unordered_set} & \tcode{unordered_set} \\ -\rowsep -\tcode{unordered_set} & \tcode{unordered_multiset} \\ -\end{floattable} +\indexunordmem{insert}% +\begin{itemdecl} +a.insert(q, nh) +\end{itemdecl} +\begin{itemdescr} \pnum -If a node handle is not empty, then it contains an allocator that is equal to -the allocator of the container when the element was extracted. If a node handle -is empty, it contains no allocator. +\result +\tcode{iterator} \pnum -Class \exposid{node-handle} is for exposition only. +\expects +\tcode{nh} is empty or +\tcode{a.get_allocator() == nh.get_allocator()} is \tcode{true}. \pnum -If a user-defined specialization of \tcode{pair} exists for -\tcode{pair} or \tcode{pair}, where \tcode{Key} is the -container's \tcode{key_type} and \tcode{T} is the container's -\tcode{mapped_type}, the behavior of operations involving node handles is -undefined. - -\begin{codeblock} -template<@\unspecnc@> -class @\placeholder{node-handle}@ { -public: - // These type declarations are described in Tables \ref{tab:container.assoc.req} and \ref{tab:container.hash.req}. - using value_type = @\seebelownc{}@; // not present for map containers - using key_type = @\seebelownc{}@; // not present for set containers - using mapped_type = @\seebelownc{}@; // not present for set containers - using allocator_type = @\seebelownc{}@; - -private: - using container_node_type = @\unspecnc@; // \expos - using ator_traits = allocator_traits; // \expos +\effects +If \tcode{nh} is empty, has no effect and returns \tcode{a.end()}. +Otherwise, inserts the element owned by \tcode{nh} if and only if +there is no element with key equivalent to \tcode{nh.key()} +in containers with unique keys; +always inserts the element owned by \tcode{nh} +in containers with equivalent keys. +The iterator \tcode{q} is a hint pointing to where the search should start. +Implementations are permitted to ignore the hint. - typename ator_traits::template - rebind_traits::pointer ptr_; // \expos - optional alloc_; // \expos +\ensures +\tcode{nh} is empty if insertion succeeds, unchanged if insertion fails. -public: - // \ref{container.node.cons}, constructors, copy, and assignment - constexpr @\placeholdernc{node-handle}@() noexcept : ptr_(), alloc_() {} - @\placeholdernc{node-handle}@(@\placeholdernc{node-handle}@&&) noexcept; - @\placeholdernc{node-handle}@& operator=(@\placeholdernc{node-handle}@&&); +\pnum +\returns +An iterator pointing to the element with key equivalent to \tcode{nh.key()}. - // \ref{container.node.dtor}, destructor - ~@\placeholdernc{node-handle}@(); +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} - // \ref{container.node.observers}, observers - value_type& value() const; // not present for map containers - key_type& key() const; // not present for set containers - mapped_type& mapped() const; // not present for set containers +\indexunordmem{extract}% +\begin{itemdecl} +a.extract(k) +\end{itemdecl} - allocator_type get_allocator() const; - explicit operator bool() const noexcept; - [[nodiscard]] bool empty() const noexcept; +\begin{itemdescr} +\pnum +\result +\tcode{node_type} - // \ref{container.node.modifiers}, modifiers - void swap(@\placeholdernc{node-handle}@&) - noexcept(ator_traits::propagate_on_container_swap::value || - ator_traits::is_always_equal::value); +\pnum +\effects +Removes an element in the container with key equivalent to \tcode{k}. - friend void swap(@\placeholdernc{node-handle}@& x, @\placeholdernc{node-handle}@& y) noexcept(noexcept(x.swap(y))) { - x.swap(y); - } -}; -\end{codeblock} +\pnum +\returns +A \tcode{node_type} owning the element if found, +otherwise an empty \tcode{node_type}. -\rSec3[container.node.cons]{Constructors, copy, and assignment} +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} +\indexunordmem{extract}% \begin{itemdecl} -@\placeholdernc{node-handle}@(@\placeholdernc{node-handle}@&& nh) noexcept; +a_tran.extract(kx) \end{itemdecl} \begin{itemdescr} +\pnum +\result +\tcode{node_type} + \pnum \effects -Constructs a \exposid{node-handle} object initializing -\tcode{ptr_} with \tcode{nh.ptr_}. Move constructs \tcode{alloc_} with -\tcode{nh.alloc_}. Assigns \keyword{nullptr} to \tcode{nh.ptr_} and assigns -\tcode{nullopt} to \tcode{nh.alloc_}. +Removes an element in the container with key equivalent to \tcode{kx}. + +\pnum +\returns +A \tcode{node_type} owning the element if found, +otherwise an empty \tcode{node_type}. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_tran.size()}}. \end{itemdescr} +\indexunordmem{extract}% \begin{itemdecl} -@\placeholdernc{node-handle}@& operator=(@\placeholdernc{node-handle}@&& nh); +a.extract(q) \end{itemdecl} \begin{itemdescr} \pnum -\expects -Either \tcode{!alloc_}, or -\tcode{ator_traits::propagate_on_container_move_assignment::\-value} -is \tcode{true}, or \tcode{alloc_ == nh.alloc_}. +\result +\tcode{node_type} \pnum \effects -\begin{itemize} -\item -If \tcode{ptr_ != nullptr}, destroys the \tcode{value_type} -subobject in the \tcode{container_node_type} object pointed to by \tcode{ptr_} -by calling \tcode{ator_traits::destroy}, then deallocates \tcode{ptr_} by -calling \tcode{ator_traits::template rebind_traits::deallocate}. -\item -Assigns \tcode{nh.ptr_} to \tcode{ptr_}. -\item -If \tcode{!alloc\textunderscore} or \tcode{ator_traits::propagate_on_container_move_assignment::value} -is \tcode{true}, \linebreak -move assigns \tcode{nh.alloc_} to \tcode{alloc_}. -\item -Assigns -\keyword{nullptr} to \tcode{nh.ptr_} and assigns \tcode{nullopt} to -\tcode{nh.alloc_}. -\end{itemize} +Removes the element pointed to by \tcode{q}. -\pnum \returns -\tcode{*this}. +A \tcode{node_type} owning that element. \pnum -\throws -Nothing. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \end{itemdescr} -\rSec3[container.node.dtor]{Destructor} - +\indexunordmem{merge}% \begin{itemdecl} -~@\placeholdernc{node-handle}@(); +a.merge(a2) \end{itemdecl} \begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{a.get_allocator() == a2.get_allocator()}. + \pnum \effects -If \tcode{ptr_ != nullptr}, destroys the \tcode{value_type} subobject -in the \tcode{container_node_type} object pointed to by \tcode{ptr_} by calling -\tcode{ator_traits::destroy}, then deallocates \tcode{ptr_} by calling -\tcode{ator_traits::template rebind_traits::deallocate}. -\end{itemdescr} +Attempts to extract each element in \tcode{a2} and insert it into \tcode{a} +using the hash function and key equality predicate of \tcode{a}. +In containers with unique keys, if there is an element in \tcode{a} +with key equivalent to the key of an element from \tcode{a2}, +then that element is not extracted from \tcode{a2}. -\rSec3[container.node.observers]{Observers} +\pnum +\ensures +Pointers and references to the transferred elements of \tcode{a2} refer to +those same elements but as members of \tcode{a}. +Iterators referring to the transferred elements and +all iterators referring to \tcode{a} will be invalidated, +but iterators to elements remaining in \tcode{a2} will remain valid. + +\pnum +\complexity +Average case \bigoh{N}, where $N$ is \tcode{a2.size()}, +worst case \bigoh{N\tcode{*a.size() + N}}. +\end{itemdescr} +\indexunordmem{erase}% \begin{itemdecl} -value_type& value() const; +a.erase(k) \end{itemdecl} \begin{itemdescr} \pnum -\expects -\tcode{empty() == false}. +\result +\tcode{size_type} + +\pnum +\effects +Erases all elements with key equivalent to \tcode{k}. \pnum \returns -A reference to the \tcode{value_type} subobject in the -\tcode{container_node_type} object pointed to by \tcode{ptr_}. +The number of elements erased. \pnum -\throws -Nothing. +\complexity +Average case \bigoh{\tcode{a.count(k)}}, worst case \bigoh{\tcode{a.size()}}. \end{itemdescr} +\indexunordmem{erase}% \begin{itemdecl} -key_type& key() const; +a_tran.erase(kx) \end{itemdecl} \begin{itemdescr} \pnum -\expects -\tcode{empty() == false}. +\result +\tcode{size_type} \pnum -\returns -A non-const reference to the \tcode{key_type} member of the -\tcode{value_type} subobject in the \tcode{contain\-er_node_type} object -pointed to by \tcode{ptr_}. +\effects +Erases all elements with key equivalent to \tcode{kx}. \pnum -\throws -Nothing. +\returns +The number of elements erased. \pnum -\remarks -Modifying the key through the returned reference is permitted. +\complexity +Average case \bigoh{\tcode{a_tran.count(kx)}}, +worst case \bigoh{\tcode{a_tran.size()}}. \end{itemdescr} +\indexunordmem{erase}% \begin{itemdecl} -mapped_type& mapped() const; +a.erase(q) \end{itemdecl} \begin{itemdescr} \pnum -\expects -\tcode{empty() == false}. +\result +\tcode{iterator} + +\pnum +\effects +Erases the element pointed to by \tcode{q}. \pnum \returns -A reference to the \tcode{mapped_type} member of the -\tcode{value_type} subobject in the \tcode{container_node_type} object -pointed to by \tcode{ptr_}. +The iterator immediately following \tcode{q} prior to the erasure. \pnum -\throws -Nothing. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \end{itemdescr} - +\indexunordmem{erase}% \begin{itemdecl} -allocator_type get_allocator() const; +a.erase(r) \end{itemdecl} \begin{itemdescr} \pnum -\expects -\tcode{empty() == false}. +\result +\tcode{iterator} + +\pnum +\effects +Erases the element pointed to by \tcode{r}. \pnum \returns -\tcode{*alloc_}. +The iterator immediately following \tcode{r} prior to the erasure. \pnum -\throws -Nothing. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \end{itemdescr} +\indexunordmem{erase}% \begin{itemdecl} -explicit operator bool() const noexcept; +a.erase(q1, q2) \end{itemdecl} \begin{itemdescr} \pnum -\returns -\tcode{ptr_ != nullptr}. -\end{itemdescr} +\result +\tcode{iterator} -\begin{itemdecl} -[[nodiscard]] bool empty() const noexcept; -\end{itemdecl} +\pnum +\effects +Erases all elements in the range \tcode{[q1, q2)}. -\begin{itemdescr} \pnum \returns -\tcode{ptr_ == nullptr}. -\end{itemdescr} +The iterator immediately following the erased elements prior to the erasure. -\rSec3[container.node.modifiers]{Modifiers} +\pnum +\complexity +Average case linear in \tcode{distance(q1, q2)}, +worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} +\indexunordmem{clear}% \begin{itemdecl} -void swap(@\placeholdernc{node-handle}@& nh) - noexcept(ator_traits::propagate_on_container_swap::value || - ator_traits::is_always_equal::value); +a.clear() \end{itemdecl} \begin{itemdescr} \pnum -\expects -\tcode{!alloc_}, or \tcode{!nh.alloc_}, or -\tcode{ator_traits::propagate_on_container_swap::value} is \tcode{true}, -or \tcode{alloc_ == nh.alloc_}. +\result +\keyword{void} \pnum \effects -Calls \tcode{swap(ptr_, nh.ptr_)}. If \tcode{!alloc_}, or -\tcode{!nh.alloc_}, or \tcode{ator_traits::propagate_on_container_swap::value} -is \tcode{true} calls \tcode{swap(alloc_, nh.alloc_)}. -\end{itemdescr} - -\rSec2[container.insert.return]{Insert return type} +Erases all elements in the container. \pnum -The associative containers with unique keys and the unordered containers with unique keys -have a member function \tcode{insert} that returns a nested type \tcode{insert_return_type}. -That return type is a specialization of the template specified in this subclause. - -\begin{codeblock} -template -struct @\placeholder{insert-return-type}@ -{ - Iterator position; - bool inserted; - NodeType node; -}; -\end{codeblock} +\ensures +\tcode{a.empty()} is \tcode{true}. \pnum -The name \exposid{insert-return-type} is exposition only. -\exposid{insert-return-type} has the template parameters, -data members, and special members specified above. -It has no base classes or members other than those specified. - -\rSec2[associative.reqmts]{Associative containers} +\complexity +Linear in \tcode{a.size()}. +\end{itemdescr} -\rSec3[associative.reqmts.general]{General} +\indexunordmem{find}% +\begin{itemdecl} +b.find(k) +\end{itemdecl} +\begin{itemdescr} \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}. +\result +\tcode{iterator}; \tcode{const_iterator} for const \tcode{b}. \pnum -Each associative container is parameterized on -\tcode{Key} -and an ordering relation -\tcode{Compare} -that induces a strict weak ordering\iref{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. +\returns +An iterator pointing to an element with key equivalent to \tcode{k}, or +\tcode{b.end()} if no such element exists. \pnum -The phrase ``equivalence of keys'' means the equivalence relation imposed by the -comparison object. -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}. -\begin{note} -This is not necessarily the same as the result of \tcode{k1 == k2}. -\end{note} -For any two keys -\tcode{k1} -and -\tcode{k2} -in the same container, calling -\tcode{comp(k1, k2)} -shall always return the same value. +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{b.size()}}. +\end{itemdescr} +\indexunordmem{find}% +\begin{itemdecl} +a_tran.find(ke) +\end{itemdecl} + +\begin{itemdescr} \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. +\result +\tcode{iterator}; \tcode{const_iterator} for const \tcode{a_tran}. \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}. +\returns +An iterator pointing to an element with key equivalent to \tcode{ke}, or +\tcode{a_tran.end()} if no such element exists. \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. -\begin{note} -\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. -\end{note} +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} + +\indexunordmem{count}% +\begin{itemdecl} +b.count(k) +\end{itemdecl} +\begin{itemdescr} \pnum -The associative containers meet all the requirements of Allocator-aware -containers\iref{container.requirements.general}, except that for -\tcode{map} and \tcode{multimap}, the requirements placed on \tcode{value_type} -in \tref{container.alloc.req} apply instead to \tcode{key_type} -and \tcode{mapped_type}. -\begin{note} -For example, in some cases \tcode{key_type} and \tcode{mapped_type} -are required to be \oldconcept{CopyAssignable} even though the associated -\tcode{value_type}, \tcode{pair}, is not -\oldconcept{CopyAssignable}. -\end{note} +\result +\tcode{size_type} \pnum -In \tref{container.assoc.req}, -\begin{itemize} -\item -\tcode{X} denotes an associative container class, -\item -\tcode{a} denotes a value of type \tcode{X}, -\item -\tcode{a2} denotes a value of a type with nodes compatible with type -\tcode{X} (\tref{container.node.compat}), -\item -\tcode{b} denotes a possibly \keyword{const} value of type \tcode{X}, -\item -\tcode{u} denotes the name of a variable being declared, -\item -\tcode{a_uniq} denotes a value of type \tcode{X} -when \tcode{X} supports unique keys, -\item -\tcode{a_eq} denotes a value of type \tcode{X} -when \tcode{X} supports multiple keys, -\item -\tcode{a_tran} denotes a possibly \keyword{const} value of type \tcode{X} -when the \grammarterm{qualified-id} -\tcode{X::key_compare::is_transpa\-rent} is valid -and denotes a type\iref{temp.deduct}, -\item -\tcode{i} and \tcode{j} -meet the \oldconcept{InputIterator} requirements and refer to elements -implicitly convertible to -\tcode{value_type}, -\item -\range{i}{j} denotes a valid range, -\item -\tcode{p} denotes a valid constant iterator to \tcode{a}, -\item -\tcode{q} denotes a valid dereferenceable constant iterator to \tcode{a}, -\item -\tcode{r} denotes a valid dereferenceable iterator to \tcode{a}, -\item -\tcode{[q1, q2)} denotes a valid range of constant iterators in \tcode{a}, -\item -\tcode{il} designates an object of type \tcode{initializer_list}, -\item -\tcode{t} denotes a value of type \tcode{X::value_type}, -\item -\tcode{k} denotes a value of type \tcode{X::key_type}, and -\item -\tcode{c} denotes a possibly \keyword{const} value of type \tcode{X::key_compare}; -\item -\tcode{kl} is a value such that \tcode{a} is partitioned\iref{alg.sorting} -with respect to \tcode{c(x, kl)}, -with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; -\item -\tcode{ku} is a value such that \tcode{a} is partitioned with respect to -\tcode{!c(ku, x)}, -with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; -\item -\tcode{ke} is a value such that \tcode{a} is partitioned with respect to -\tcode{c(x, ke)} and \tcode{!c(ke, x)}, with \tcode{c(x, ke)} implying -\tcode{!c(ke, x)} and -with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}; -\item -\tcode{kx} is a value such that -\begin{itemize} -\item -\tcode{a} is partitioned with respect to \tcode{c(x, kx)} and \tcode{!c(kx, x)}, -with \tcode{c(x, kx)} implying \tcode{!c(kx, x)} and -with \tcode{x} the key value of \tcode{e} and \tcode{e} in \tcode{a}, and -\item -\tcode{kx} is not convertible to -either \tcode{iterator} or \tcode{const_iterator}; and -\end{itemize} -\item -\tcode{A} denotes the storage allocator used by \tcode{X}, if any, or \tcode{allocator} otherwise, -\item -\tcode{m} denotes an allocator of a type convertible to \tcode{A}, -and \tcode{nh} denotes a non-const rvalue of type \tcode{X::node_type}. -\end{itemize} +\returns +The number of elements with key equivalent to \tcode{k}. -% Local command to index names as members of all ordered containers. -\newcommand{\indexordmem}[1]{% -\indexlibrary{\idxcode{#1}!ordered associative containers}% -\indexlibrary{\idxcode{set}!\idxcode{#1}}% -\indexlibrary{\idxcode{map}!\idxcode{#1}}% -\indexlibrary{\idxcode{multiset}!\idxcode{#1}}% -\indexlibrary{\idxcode{multimap}!\idxcode{#1}}% -} +\pnum +\complexity +Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}. +\end{itemdescr} -\begin{libreqtab4b} -{Associative container requirements (in addition to container)} -{container.assoc.req} -\\ \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 +\indexunordmem{count}% +\begin{itemdecl} +a_tran.count(ke) +\end{itemdecl} -\indexordmem{key_type}% -\tcode{X::key_type} & - \tcode{Key} & - & - compile time \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{size_type} -\indexordmem{mapped_type}% -\tcode{X::mapped_type} (\tcode{map} and \tcode{multimap} only) & - \tcode{T} & - & - compile time \\ \rowsep +\pnum +\returns +The number of elements with key equivalent to \tcode{ke}. -\indexordmem{value_type}% -\tcode{X::value_type} (\tcode{set} and \tcode{multiset} only) & - \tcode{Key} & - \expects \tcode{value_type} is \oldconcept{Erasable} from \tcode{X} & - compile time \\ \rowsep +\pnum +\complexity +Average case \bigoh{\tcode{a_tran.count(ke)}}, +worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} -\tcode{X::value_type} (\tcode{map} and \tcode{multimap} only) & - \tcode{pair} & - \expects \tcode{value_type} is \oldconcept{Erasable} from \tcode{X} & - compile time \\ \rowsep +\indexunordmem{contains}% +\begin{itemdecl} +b.contains(k) +\end{itemdecl} -\indexordmem{key_compare}% -\tcode{X::key_compare} & - \tcode{Compare} & - \expects \tcode{key_compare} is \oldconcept{CopyConstructible}. & - compile time \\ \rowsep +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{b.find(k) != b.end()}. +\end{itemdescr} -\indexordmem{value_compare}% -\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 +\indexunordmem{contains}% +\begin{itemdecl} +a_tran.contains(ke) +\end{itemdecl} -\indexordmem{node_type}% -\tcode{X::node_type} & - A specialization of a \exposid{node-handle} - class template, such that the public nested types are - the same types as the corresponding types in \tcode{X}. & - see~\ref{container.node} & - compile time \\ \rowsep +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a_tran.find(ke) != a_tran.end()}. +\end{itemdescr} -\indexlibraryctor{set}% -\indexlibraryctor{map}% -\indexlibraryctor{multiset}% -\indexlibraryctor{multimap}% -\tcode{X(c)}\br -\tcode{X u(c);} & - & - \effects\ Constructs an empty container. - Uses a copy of \tcode{c} as a comparison object. & - constant \\ \rowsep - -\tcode{X()}\br\tcode{X u;} & - & - \expects \tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements.\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);} & - & - \expects \tcode{value_type} is \oldconcept{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, where $N$ has the value \tcode{distance(i, j)}; - linear if \tcode{[i, j)} is sorted with \tcode{value_comp()} \\ \rowsep - -\tcode{X(i,j)}\br\tcode{X~u(i,j);} & - & - \expects \tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements. - \tcode{value_type} is \oldconcept{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\&} & - \expects \tcode{value_type} is - \oldconcept{CopyInsertable} into \tcode{X} - and \oldconcept{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 +\indexunordmem{equal_range}% +\begin{itemdecl} +b.equal_range(k) +\end{itemdecl} -\indexordmem{key_comp}% -\tcode{b.key_comp()} & - \tcode{X::key_compare} & - \returns the comparison object out of which \tcode{b} was constructed. & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for const \tcode{b}. -\indexordmem{value_comp}% -\tcode{b.value_comp()} & - \tcode{X::value_compare} & - \returns an object of \tcode{value_compare} constructed out of the comparison object & - constant \\ \rowsep +\pnum +\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. -\indexordmem{emplace}% -\tcode{a_uniq.\brk{}emplace(\brk{}args)} & - \tcode{pair<\brk{}iterator, bool>} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with - \tcode{std::forward<\brk{}Args\brk{}>(\brk{}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 \tcode{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.\brk{}emplace(\brk{}args)} & - \tcode{iterator} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with - \tcode{std::forward<\brk{}Args\brk{}>(\brk{}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 +\pnum +\complexity +Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}. +\end{itemdescr} -\indexordmem{emplace_hint}% -\tcode{a.emplace_\-hint(\brk{}p, args)} & - \tcode{iterator} & - \effects - Equivalent to \tcode{a.emplace(} \tcode{std::forward<\brk{}Args\brk{}>(\brk{}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 +\indexunordmem{equal_range}% +\begin{itemdecl} +a_tran.equal_range(ke) +\end{itemdecl} -\indexordmem{insert}% -\tcode{a_uniq.\brk{}insert(\brk{}t)} & - \tcode{pair<\brk{}iterator, bool>} & - \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{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 \tcode{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.\brk{}insert(\brk{}t)} & - \tcode{iterator} & - \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{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.\brk{}insert(\brk{}p, t)} & - \tcode{iterator} & - \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{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.\brk{}insert(\brk{}i, j)} & - \keyword{void} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. - Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}.\br - \effects 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)$, where $N$ has the value \tcode{distance(i, j)} \\ \rowsep - -\tcode{a.\brk{}insert(\brk{}il)} & - \keyword{void} & - \effects - Equivalent to \tcode{a.insert(il.begin(), il.end())} & - \\ \rowsep - -\tcode{a_uniq.\brk{}insert(\brk{}nh)} & - \tcode{insert_return_type} & - \expects \tcode{nh} is empty or - \tcode{a_uniq.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect. Otherwise, inserts the - element owned by \tcode{nh} if and only if there is no element in the - container with a key equivalent to \tcode{nh.key()}.\br - \ensures If \tcode{nh} is empty, \tcode{inserted} is \tcode{false}, - \tcode{position} is \tcode{end()}, and \tcode{node} is empty. - Otherwise if the insertion took place, \tcode{inserted} is \tcode{true}, - \tcode{position} points to the inserted element, and \tcode{node} is empty; - if the insertion failed, \tcode{inserted} is \tcode{false}, - \tcode{node} has the previous value of \tcode{nh}, and \tcode{position} - points to an element with a key equivalent to \tcode{nh.key()}. & - logarithmic \\ \rowsep - -\tcode{a_eq.\brk{}insert(\brk{}nh)} & - \tcode{iterator} & - \expects \tcode{nh} is empty or - \tcode{a_eq.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect and returns \tcode{a_eq.end()}. - Otherwise, inserts the element owned by \tcode{nh} and returns an iterator - pointing to the newly inserted element. If a range containing elements with - keys equivalent to \tcode{nh.key()} exists in \tcode{a_eq}, the element is - inserted at the end of that range.\br - \ensures \tcode{nh} is empty. & - logarithmic \\ \rowsep - -\tcode{a.\brk{}insert(\brk{}p, nh)} & - \tcode{iterator} & - \expects \tcode{nh} is empty or - \tcode{a.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect and returns \tcode{a.end()}. - Otherwise, inserts the element owned by \tcode{nh} if and only if there - is no element with key equivalent to \tcode{nh.key()} in containers with - unique keys; always inserts the element owned by \tcode{nh} in containers - with equivalent keys. Always returns the iterator pointing to the element - with key equivalent to \tcode{nh.key()}. The element is inserted as close - as possible to the position just prior to \tcode{p}.\br - \ensures \tcode{nh} is empty if insertion succeeds, unchanged if insertion fails. & - logarithmic in general, but amortized constant if the element is inserted right - before \tcode{p}. \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for const \tcode{a_tran}. -\indexordmem{extract}% -\tcode{a.\brk{}extract(\brk{}k)} & - \tcode{node_type} & - \effects Removes the first element in the container with key equivalent to \tcode{k}.\br - \returns A \tcode{node_type} owning the element if found, otherwise an empty - \tcode{node_type}. & - $\log (\tcode{a.size()})$ \\ \rowsep - -\tcode{a_tran.\brk{}extract(\brk{}kx)} & - \tcode{node_type} & - \effects Removes the first element in the container with key \tcode{r} - such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}.\br - \returns A \tcode{node_type} owning the element if found, - otherwise an empty \tcode{node_type}. & - $\log(\tcode{a_tran.size()})$ \\ \rowsep - -\tcode{a.\brk{}extract(\brk{}q)} & - \tcode{node_type} & - \effects Removes the element pointed to by \tcode{q}.\br - \returns A \tcode{node_type} owning that element. & - amortized constant \\ \rowsep +\pnum +\returns +A range containing all elements with keys equivalent to \tcode{ke}. +Returns \tcode{make_pair(a_tran.end(), a_tran.end())} if no such elements exist. -\indexordmem{merge}% -\tcode{a.merge(a2)} & - \keyword{void} & - \expects \tcode{a.get_allocator() == a2.get_allocator()}.\br - \effects Attempts to extract each element in \tcode{a2} and insert it into \tcode{a} - using the comparison object of \tcode{a}. In containers with unique keys, - if there is an element in \tcode{a} with key equivalent to the key of an - element from \tcode{a2}, then that element is not extracted from \tcode{a2}.\br - \ensures Pointers and references to the transferred elements of \tcode{a2} - refer to those same elements but as members of \tcode{a}. Iterators referring - to the transferred elements will continue to refer to their elements, but - they now behave as iterators into \tcode{a}, not into \tcode{a2}.\br - \throws Nothing unless the comparison object throws. & - $N \log(\tcode{a.size()+} N)$, where $N$ has the value \tcode{a2.size()}. \\ \rowsep +\pnum +\complexity +Average case \bigoh{\tcode{a_tran.count(ke)}}, +worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} -\indexordmem{erase}% -\tcode{a.erase(k)} & - \tcode{size_type} & - \effects Erases all elements in the container with key equivalent to - \tcode{k}.\br - \returns The number of erased elements. & - $\log (\tcode{a.size()}) + \tcode{a.count(k)}$ \\ \rowsep - -\tcode{a_tran.\brk{}erase(kx)} & - \tcode{size_type} & - \effects Erases all elements in the container with key \tcode{r} - such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}.\br - \returns The number of erased elements. & - $\log(\tcode{a_tran.size())} + \tcode{a_tran.count(kx)}$ \\ \rowsep - -\tcode{a.erase(q)} & - \tcode{iterator} & - \effects Erases the element pointed to by \tcode{q}.\br - \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} & - \effects Erases the element pointed to by \tcode{r}.\br - \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} & - \effects Erases all the elements in the range \range{q1}{q2}.\br - \returns An iterator pointing to - the element pointed to by \tcode{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 +\indexunordmem{bucket_count}% +\begin{itemdecl} +b.bucket_count() +\end{itemdecl} -\indexordmem{clear}% -\tcode{a.clear()} & - \keyword{void} & - \effects Equivalent to \tcode{a.erase(a.begin(), a.end())}.\br - \ensures \tcode{a.empty()} is \tcode{true}. & - linear in \tcode{a.size()}. \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{size_type} -\indexordmem{find}% -\tcode{b.find(k)} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. & - \returns An iterator pointing to an element with the key equivalent - to \tcode{k}, or \tcode{b.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 +\pnum +\returns +The number of buckets that \tcode{b} contains. -\indexordmem{count}% -\tcode{b.count(k)} & - \tcode{size_type} & - \returns The number of elements with key equivalent to \tcode{k}. & - $\log (\tcode{b.size()}) + \tcode{b.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 +\pnum +\complexity +Constant. +\end{itemdescr} -\indexordmem{contains}% -\tcode{b.}\br - \tcode{contains(k)} & - \tcode{bool} & - \effects Equivalent to: \tcode{return b.find(k) != b.end();} & - logarithmic \\ \rowsep - -\tcode{a_tran.}\br - \tcode{con\-tains(ke)} & - \tcode{bool} & - \effects Equivalent to: \tcode{return a_tran.find(ke) != a_tran.end();} & - logarithmic \\ \rowsep +\indexunordmem{max_bucket_count}% +\begin{itemdecl} +b.max_bucket_count() +\end{itemdecl} -\indexordmem{lower_bound}% -\tcode{b.lower_bound(k)} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. & - \returns An iterator pointing to the first element with - key not less than \tcode{k}, - or \tcode{b.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 +\begin{itemdescr} +\pnum +\result +\tcode{size_type} -\indexordmem{upper_bound}% -\tcode{b.upper_bound(k)} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{b}. & - \returns An iterator pointing to the first element with - key greater than \tcode{k}, - or \tcode{b.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 +\pnum +\returns +An upper bound on the number of buckets that \tcode{b} can ever contain. -\indexordmem{equal_range}% -\tcode{b.equal_range(k)} & - \tcode{pair<\brk{}iterator, iterator>}; - \tcode{pair<\brk{}const_iterator, const_iterator>} for constant \tcode{b}. & - \effects Equivalent to: \tcode{return make_pair(b.lower_bound(k), b.upper_bound(k));} & - logarithmic \\ \rowsep - -\tcode{a_tran.}\br - \tcode{equal_range(ke)} & - \tcode{pair<\brk{}iterator, iterator>}; - \tcode{pair<\brk{}const_iterator, const_iterator>} for constant \tcode{a_tran}. & - \effects Equivalent to: \tcode{return make_pair(}\br - \tcode{a_tran.lower_bound(ke), a_tran.upper_bound(ke));} & - logarithmic \\ -\end{libreqtab4b} +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{bucket}% +\begin{itemdecl} +b.bucket(k) +\end{itemdecl} +\begin{itemdescr} \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. +\result +\tcode{size_type} \pnum -The \tcode{extract} members invalidate only iterators to the removed element; -pointers and references to the removed element remain valid. However, accessing -the element through such pointers and references while the element is owned by -a \tcode{node_type} is undefined behavior. References and pointers to an element -obtained while it is owned by a \tcode{node_type} are invalidated if the element -is successfully inserted. +\expects +\tcode{b.bucket_count() > 0}. \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, the following condition holds: +\returns +The index of the bucket +in which elements with keys equivalent to \tcode{k} would be found, +if any such element existed. +The return value is in the range \tcode{[0, b.bucket_count())}. -\begin{codeblock} -value_comp(*j, *i) == false -\end{codeblock} +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{bucket_size}% +\begin{itemdecl} +b.bucket_size(n) +\end{itemdecl} +\begin{itemdescr} \pnum -For associative containers with unique keys the stronger condition holds: +\result +\tcode{size_type} -\begin{codeblock} -value_comp(*i, *j) != false -\end{codeblock} +\pnum +\expects +\tcode{n} shall be in the range \tcode{[0, b.bucket_count())}. \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, through either 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. +\returns +The number of elements in the $\tcode{n}^\text{th}$ bucket. \pnum -The member function templates -\tcode{find}, \tcode{count}, \tcode{contains}, -\tcode{lower_bound}, \tcode{upper_bound}, \tcode{equal_range}, -\tcode{erase}, and \tcode{extract} -shall not participate in overload resolution unless -the \grammarterm{qualified-id} \tcode{Compare::is_transparent} is valid -and denotes a type\iref{temp.deduct}. -Additionally, the member function templates \tcode{extract} and \tcode{erase} -shall not participate in overload resolution if -\tcode{is_convertible_v || is_convertible_v} -is \tcode{true}, -where \tcode{K} is the type substituted as the first template argument. +\complexity +\bigoh{\tcode{b.bucket_size(n)}} +\end{itemdescr} + +\indexunordmem{begin}% +\begin{itemdecl} +b.begin(n) +\end{itemdecl} +\begin{itemdescr} \pnum -A deduction guide for an associative container shall not participate in overload resolution -if any of the following are true: -\begin{itemize} -\item It has an \tcode{InputIterator} template parameter -and a type that does not qualify as an input iterator is deduced for that parameter. +\result +\tcode{local_iterator}; \tcode{const_local_iterator} for const \tcode{b}. -\item It has an \tcode{Allocator} template parameter -and a type that does not qualify as an allocator is deduced for that parameter. +\pnum +\expects +\tcode{n} is in the range \tcode{[0, b.bucket_count())}. -\item It has a \tcode{Compare} template parameter -and a type that qualifies as an allocator is deduced for that parameter. -\end{itemize} +\pnum +\returns +An iterator referring to the first element in the bucket. +If the bucket is empty, then \tcode{b.begin(n) == b.end(n)}. -\rSec3[associative.reqmts.except]{Exception safety guarantees}% -\indextext{associative containers!exception safety}% -\indextext{associative containers!requirements}% +\pnum +\complexity +Constant. +\end{itemdescr} +\indexunordmem{end}% +\begin{itemdecl} +b.end(n) +\end{itemdecl} + +\begin{itemdescr} \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). +\result +\tcode{local_iterator}; \tcode{const_local_iterator} for const \tcode{b}. \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. +\expects +\tcode{n} is in the range \tcode{[0, b.bucket_count())}. \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). +\returns +An iterator which is the past-the-end value for the bucket. -\rSec2[unord.req]{Unordered associative containers}% -\indextext{associative containers!unordered|see{unordered associative containers}} -\indextext{hash tables|see{unordered associative containers}} +\pnum +\complexity +Constant. +\end{itemdescr} -\rSec3[unord.req.general]{General} +\indexunordmem{cbegin}% +\begin{itemdecl} +b.cbegin(n) +\end{itemdecl} +\begin{itemdescr} \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}. +\result +\tcode{const_local_iterator} \pnum -\indextext{unordered associative containers!lack of comparison functions}% -\indextext{unordered associative containers!requirements}% -\indextext{requirements!container!not required for unordered associated containers}% -Unordered associative containers conform to the requirements for -Containers\iref{container.requirements}, except that -the expressions -\tcode{a == b} and \tcode{a != b} have different semantics than for the other -container types. +\expects +\tcode{n} shall be in the range \tcode{[0, b.bucket_count())}. + +\pnum +\returns +An iterator referring to the first element in the bucket. +If the bucket is empty, then \tcode{b.cbegin(n) == b.cend(n)}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{cend}% +\begin{itemdecl} +b.cend(n) +\end{itemdecl} +\begin{itemdescr} \pnum -Each unordered associative container is parameterized by \tcode{Key}, -by a function object type \tcode{Hash} that meets the \oldconcept{Hash} -requirements\iref{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}. +\result +\tcode{const_local_iterator} \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. +\expects +\tcode{n} is in the range \tcode{[0, b.bucket_count())}. \pnum -\indextext{unordered associative containers!equality function}% -Two values \tcode{k1} and \tcode{k2} are -considered equivalent if the container's -key equality predicate -\tcode{pred(k1, k2)} is valid and 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. -\begin{note} -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. -\end{note} -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. +\returns +An iterator which is the past-the-end value for the bucket. \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 \defnx{equivalent-key groups}{equivalent-key group} 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. +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{load_factor}% +\begin{itemdecl} +b.load_factor() +\end{itemdecl} +\begin{itemdescr} \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{pair}. +\result +\tcode{float} \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. -\begin{note} -\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. -\end{note} +\returns +The average number of elements per bucket. \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. +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{max_load_factor}% +\begin{itemdecl} +b.max_load_factor() +\end{itemdecl} +\begin{itemdescr} \pnum -The unordered associative containers meet all the requirements of Allocator-aware -containers\iref{container.requirements.general}, except that for -\tcode{unordered_map} and \tcode{unordered_multimap}, the requirements placed on \tcode{value_type} -in \tref{container.alloc.req} apply instead to \tcode{key_type} -and \tcode{mapped_type}. -\begin{note} -For example, \tcode{key_type} and \tcode{mapped_type} -are sometimes required to be \oldconcept{CopyAssignable} even though the associated -\tcode{value_type}, \tcode{pair}, is not -\oldconcept{CopyAssignable}. -\end{note} +\result +\tcode{float} \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 \tref{container.hash.req}, -\begin{itemize} -\item -\tcode{X} denotes an unordered associative container class, -\item -\tcode{a} denotes a value of type \tcode{X}, -\item -\tcode{a2} denotes a value of a type with nodes compatible - with type \tcode{X} (\tref{container.node.compat}), -\item -\tcode{b} denotes a possibly const value of type \tcode{X}, -\item -\tcode{a_uniq} denotes a value of type \tcode{X} - when \tcode{X} supports unique keys, -\item -\tcode{a_eq} denotes a value of type \tcode{X} - when \tcode{X} supports equivalent keys, -\item -\tcode{a_tran} denotes a possibly const value of type \tcode{X} - when the \grammarterm{qualified-id}s - \tcode{X::key_equal::is_transparent} and - \tcode{X::hasher::is_transparent} - are both valid and denote types\iref{temp.deduct}, -\item -\tcode{i} and \tcode{j} denote input iterators - that refer to \tcode{value_type}, -\item -\tcode{[i, j)} denotes a valid range, -\item -\tcode{p} and \tcode{q2} denote valid constant iterators to \tcode{a}, -\item -\tcode{q} and \tcode{q1} denote - valid dereferenceable constant iterators to \tcode{a}, -\item -\tcode{r} denotes a valid dereferenceable iterator to \tcode{a}, -\item -\tcode{[q1, q2)} denotes a valid range in \tcode{a}, -\item -\tcode{il} denotes a value of type \tcode{initializer_list}, -\item -\tcode{t} denotes a value of type \tcode{X::value_type}, -\item -\tcode{k} denotes a value of type \tcode{key_type}, -\item -\tcode{hf} denotes a possibly const value of type \tcode{hasher}, -\item -\tcode{eq} denotes a possibly const value of type \tcode{key_equal}, -\item -\tcode{ke} is a value such that - \begin{itemize} - \item \tcode{eq(r1, ke) == eq(ke, r1)}, - \item \tcode{hf(r1) == hf(ke)} if \tcode{eq(r1, ke)} is \tcode{true}, and - \item \tcode{(eq(r1, ke) \&\& eq(r1, r2)) == eq(r2, ke)}, - \end{itemize} - where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran}, -\item -\tcode{kx} is a value such that - \begin{itemize} - \item \tcode{eq(r1, kx) == eq(kx, r1)}, - \item \tcode{hf(r1) == hf(kx)} if \tcode{eq(r1, kx)} is \tcode{true}, - \item \tcode{(eq(r1, kx) \&\& eq(r1, r2)) == eq(r2, kx)}, and - \item \tcode{kx} is not convertible to - either \tcode{iterator} or \tcode{const_iterator}, - \end{itemize} - where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran}, -\item -\tcode{n} denotes a value of type \tcode{size_type}, -\item -\tcode{z} denotes a value of type \tcode{float}, and -\item -\tcode{nh} denotes a non-const rvalue of type \tcode{X::node_type}. -\end{itemize} +\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. -% Local command to index names as members of all unordered containers. -\newcommand{\indexunordmem}[1]{% -\indexlibrary{\idxcode{#1}!unordered associative containers}% -\indexlibrary{\idxcode{unordered_set}!\idxcode{#1}}% -\indexlibrary{\idxcode{unordered_map}!\idxcode{#1}}% -\indexlibrary{\idxcode{unordered_multiset}!\idxcode{#1}}% -\indexlibrary{\idxcode{unordered_multimap}!\idxcode{#1}}% -} +\pnum +\complexity +Constant. +\end{itemdescr} -\begin{libreqtab4d} - {Unordered associative container requirements (in addition to container)} - {container.hash.req} -\\ \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 -%% -\indexunordmem{key_type}% -\tcode{X::key_type} & - \tcode{Key} & - & - compile time \\ \rowsep +\indexunordmem{max_load_factor}% +\begin{itemdecl} +a.max_load_factor(z) +\end{itemdecl} -\indexunordmem{mapped_type}% -\tcode{X::mapped_type} (\tcode{unordered_map} and \tcode{unordered_multimap} only) & - \tcode{T} & - & - compile time \\ \rowsep +\begin{itemdescr} +\pnum +\result +\keyword{void} -\indexunordmem{value_type}% -\tcode{X::value_type} (\tcode{unordered_set} and \tcode{unordered_multiset} only) & - \tcode{Key} & - \expects \tcode{value_type} is \oldconcept{Erasable} from \tcode{X} & - compile time \\ \rowsep +\pnum +\expects +\tcode{z} is positive. +May change the container's maximum load factor, using \tcode{z} as a hint. -\tcode{X::value_type} (\tcode{unordered_map} and \tcode{unordered_multimap} only) & - \tcode{pair} & - \expects \tcode{value_type} is \oldconcept{Erasable} from \tcode{X} & - compile time \\ \rowsep +\pnum +\complexity +Constant. +\end{itemdescr} -\indexunordmem{hasher}% -\tcode{X::hasher} -& \tcode{Hash} -& \expects \tcode{Hash} is a unary function object type such that the expression - \tcode{hf(k)} has type \tcode{size_t}.% -& compile time -\\ \rowsep -% -\indexunordmem{key_equal}% -\tcode{X::key_equal} -& \tcode{Pred} -& \expects \tcode{Pred} meets the \oldconcept{CopyConstructible} requirements.\br - \tcode{Pred} is a binary predicate that takes two arguments - of type \tcode{Key}. \tcode{Pred} is an equivalence relation.% -& compile time -\\ \rowsep -% -\indexunordmem{local_iterator}% -\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.% -& compile time -\\ \rowsep -% -\indexunordmem{const_local_iterator}% -\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.% -& compile time -\\ \rowsep -% -\indexunordmem{node_type}% -\tcode{X::node_type} & - a specialization of a \exposid{node-handle} - class template, such that the public nested types are - the same types as the corresponding types in \tcode{X}. & - see~\ref{container.node} & - compile time \\ \rowsep -% -\indexlibraryctor{unordered_set}% -\indexlibraryctor{unordered_map}% -\indexlibraryctor{unordered_multiset}% -\indexlibraryctor{unordered_multimap}% -\tcode{X(n, hf, eq)}\br \tcode{X a(n, hf, eq);} -& \tcode{X} -& \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);} -& \tcode{X} -& \expects \tcode{key_equal} meets the \oldconcept{DefaultConstructible} requirements.\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);} -& \tcode{X} -& \expects \tcode{hasher} and \tcode{key_equal} meet the \oldconcept{DefaultConstructible} requirements.\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;} -& \tcode{X} -& \expects \tcode{hasher} and \tcode{key_equal} meet the \oldconcept{DefaultConstructible} requirements.\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);} -& \tcode{X} -& \expects \tcode{value_type} is \oldconcept{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);} -& \tcode{X} -& \expects \tcode{key_equal} meets the \oldconcept{DefaultConstructible} requirements. - \tcode{value_type} is \oldconcept{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);} -& \tcode{X} -& \expects \tcode{hasher} and \tcode{key_equal} meet the \oldconcept{DefaultConstructible} requirements. - \tcode{value_type} is \oldconcept{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);} -& \tcode{X} -& \expects \tcode{hasher} and \tcode{key_equal} meet the \oldconcept{DefaultConstructible} requirements. - \tcode{value_type} is \oldconcept{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 \tref{container.req}, 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 \tref{container.req}, 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\&} -& \expects \tcode{value_type} is -\oldconcept{CopyInsertable} into \tcode{X} -and \oldconcept{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 -% -\indexunordmem{hash_function}% -\tcode{b.hash_function()} -& \tcode{hasher} -& \returns \tcode{b}'s hash function.% -& constant -\\ \rowsep -% -\indexunordmem{key_eq}% -\tcode{b.key_eq()} -& \tcode{key_equal} -& \returns \tcode{b}'s key equality predicate.% -& constant -\\ \rowsep -% +\indexunordmem{rehash}% +\begin{itemdecl} +a.rehash(n) +\end{itemdecl} -\indexunordmem{emplace}% -\tcode{a_uniq.} \tcode{emplace(args)} & - \tcode{pair} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with - \tcode{std::forward<\brk{}Args\brk{}>(\brk{}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 \tcode{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} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \effects\ Inserts a \tcode{value_type} object \tcode{t} constructed with - \tcode{std::forward<\brk{}Args>(\brk{}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 +\begin{itemdescr} +\pnum +\result +\keyword{void} -\indexunordmem{emplace_hint}% -\tcode{a.emplace_hint(p, args)} & - \tcode{iterator} & - \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{args}.\br - \effects\ Equivalent to \tcode{a.emplace(} \tcode{std::forward<\brk{}Args>(\brk{}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 +\pnum +\ensures +\tcode{a.bucket_count() >= a.size() / a.max_load_factor()} and +\tcode{a.bucket_count() >= n}.% -\indexunordmem{insert}% -\tcode{a_uniq.insert(t)} -& \tcode{pair} -& \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{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}.% -& Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.}\br\tcode{size()}}. -\\ \rowsep -% -\tcode{a_eq.insert(t)} -& \tcode{iterator} -& \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{CopyInsertable} into \tcode{X}.\br - \effects\ Inserts \tcode{t}, and returns an iterator pointing to the newly - inserted element. -& Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.}\br\tcode{size()}}. -\\ \rowsep -% -\tcode{a.insert(p, t)} -& \tcode{iterator} -& \expects If \tcode{t} is a non-const rvalue, \tcode{value_type} is - \oldconcept{MoveInsertable} into \tcode{X}; otherwise, \tcode{value_type} is - \oldconcept{CopyInsertable} into \tcode{X}.\br - \effects Equivalent to \tcode{a.insert(t)}. Return value is an iterator pointing -to the element with the key equivalent to that of \tcode{t}. The -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.size()}}. -\\ \rowsep -% -\tcode{a.insert(i, j)} -& \keyword{void} -& \expects \tcode{value_type} is \oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. - Neither \tcode{i} nor \tcode{j} are iterators into \tcode{a}.\br - \effects Equivalent to \tcode{a.insert(t)} for each element in \tcode{[i,j)}.% -& Average case \bigoh{N}, where $N$ is \tcode{distance(i, j)}, - worst case \bigoh{N(\tcode{a.size()}\brk{}+\brk{}1)}. -\\ \rowsep -% -\tcode{a.insert(il)} -& \keyword{void} -& Same as \tcode{a.insert(il.begin(), il.end())}. -& Same as \tcode{a.insert(} \tcode{il.begin(),} \tcode{il.end())}. -\\ \rowsep -% -\tcode{a_uniq.}\br - \tcode{insert(nh)} & - \tcode{insert_return_type} & - \expects \tcode{nh} is empty or - \tcode{a_uniq.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect. Otherwise, inserts the - element owned by \tcode{nh} if and only if there is no element in the - container with a key equivalent to \tcode{nh.key()}.\br - \ensures If \tcode{nh} is empty, \tcode{inserted} is \tcode{false}, - \tcode{position} is \tcode{end()}, and \tcode{node} is empty. - Otherwise if the insertion took place, \tcode{inserted} is \tcode{true}, - \tcode{position} points to the inserted element, and \tcode{node} is empty; - if the insertion failed, \tcode{inserted} is \tcode{false}, - \tcode{node} has the previous value of \tcode{nh}, and \tcode{position} - points to an element with a key equivalent to \tcode{nh.key()}. & - Average case \bigoh{1}, worst case \bigoh{\brk{}\tcode{a_uniq.}\brk{}\tcode{size()}}. \\ \rowsep -% -\tcode{a_eq.}\br - \tcode{insert(nh)} & - \tcode{iterator} & - \expects \tcode{nh} is empty or - \tcode{a_eq.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect and returns \tcode{a_eq.end()}. - Otherwise, inserts the element owned by \tcode{nh} and returns an iterator - pointing to the newly inserted element.\br - \ensures \tcode{nh} is empty. & - Average case \bigoh{1}, worst case \bigoh{\brk{}\tcode{a_eq.}\brk{}\tcode{size()}}. \\ \rowsep -% -\tcode{a.insert(q, nh)} & - \tcode{iterator} & - \expects \tcode{nh} is empty or - \tcode{a.get_allocator() == nh.get_allocator()}.\br - \effects If \tcode{nh} is empty, has no effect and returns \tcode{a.end()}. - Otherwise, inserts the element owned by \tcode{nh} if and only if there - is no element with key equivalent to \tcode{nh.key()} in containers with - unique keys; always inserts the element owned by \tcode{nh} in containers - with equivalent keys. Always returns the iterator pointing to the element - with key equivalent to \tcode{nh.key()}. The iterator \tcode{q} is a hint - pointing to where the search should start. Implementations are permitted - to ignore the hint.\br - \ensures \tcode{nh} is empty if insertion succeeds, unchanged if insertion fails. & - Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \\ \rowsep -% -\indexunordmem{extract}% -\tcode{a.extract(k)} & - \tcode{node_type} & - \effects Removes an element in the container with key equivalent to \tcode{k}.\br - \returns A \tcode{node_type} owning the element if found, otherwise an empty - \tcode{node_type}. & - Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \\ \rowsep -% -\tcode{a_tran.\brk{}extract(kx)} & - \tcode{node_type} & - \effects Removes an element in the container with key equivalent to \tcode{kx}.\br - \returns A \tcode{node_type} owning the element if found, - otherwise an empty \tcode{node_type}. & - Average case \bigoh{1}, worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. \\ \rowsep -% -\tcode{a.extract(q)} & - \tcode{node_type} & - \effects Removes the element pointed to by \tcode{q}.\br - \returns A \tcode{node_type} owning that element. & - Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. \\ \rowsep -% -\indexunordmem{merge}% -\tcode{a.merge(a2)} & - \keyword{void} & - \expects \tcode{a.get_allocator() == a2.get_allocator()}.\br - Attempts to extract each element in \tcode{a2} and insert it into \tcode{a} - using the hash function and key equality predicate of \tcode{a}. - In containers with unique keys, if there is an element in \tcode{a} with - key equivalent to the key of an element from \tcode{a2}, then that - element is not extracted from \tcode{a2}.\par - \ensures Pointers and references to the transferred elements of \tcode{a2} - refer to those same elements but as members of \tcode{a}. Iterators referring - to the transferred elements and all iterators referring to \tcode{a} will - be invalidated, but iterators to elements remaining in \tcode{a2} will - remain valid. & - Average case \bigoh{N}, where $N$ is \tcode{a2.size()}, - worst case \bigoh{N\tcode{*a.size()}\br\tcode{+} N}. \\ \rowsep -% -\indexunordmem{erase}% -\tcode{a.erase(k)} -& \tcode{size_type} -& \effects Erases all elements with key equivalent to \tcode{k}.\br - \returns The number of elements erased. -& Average case \bigoh{\tcode{a.count(k)}}, worst case - \bigoh{\tcode{a.size()}}. -\\ \rowsep -% -\tcode{a_tran.\brk{}erase(kx)} -& \tcode{size_type} -& \effects Erases all elements with key equivalent to \tcode{kx}.\br - \returns The number of elements erased. -& Average case \bigoh{\tcode{a_tran.}\br{}\tcode{count(kx)}}, worst case - \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. -\\ \rowsep -% -\tcode{a.erase(q)} -& \tcode{iterator} -& \effects Erases the element pointed to by \tcode{q}.\br - \returns The iterator immediately following \tcode{q} prior to the erasure. -& Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. -\\ \rowsep -% -\tcode{a.erase(r)} -& \tcode{iterator} -& \effects Erases the element pointed to by \tcode{r}.\br - \returns The iterator immediately following \tcode{r} prior to the erasure. -& Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. -\\ \rowsep -% -\tcode{a.erase(q1, q2)} -& \tcode{iterator} -& \effects Erases all elements in the range \tcode{[q1, q2)}.\br - \returns The iterator immediately following the erased elements prior to the - erasure. -& Average case linear in \tcode{distance(q1, q2)}, - worst case \bigoh{\tcode{a.size()}}. -\\ \rowsep -% -\indexunordmem{clear}% -\tcode{a.clear()} -& \keyword{void} -& \effects Erases all elements in the container.\br - \ensures \tcode{a.empty()} is \tcode{true}% -& Linear in \tcode{a.size()}. -\\ \rowsep -% -\indexunordmem{find}% -\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. -& Average case \bigoh{1}, worst case \bigoh{\tcode{b.size()}}. -\\ \rowsep -% -\tcode{a_tran.find(ke)} -& \tcode{iterator}; \br \tcode{const_iterator} for const \tcode{a_tran}. -& \returns An iterator pointing to an element with key equivalent to - \tcode{ke}, or \tcode{a_tran.end()} if no such element exists. -& Average case \bigoh{1}, - worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. % avoid overfull -\\ \rowsep -% -\indexunordmem{count}% -\tcode{b.count(k)} -& \tcode{size_type} -& \returns The number of elements with key equivalent to \tcode{k}.% -& Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}. -\\ \rowsep -% -\tcode{a_tran.count(ke)} -& \tcode{size_type} -& \returns The number of elements with key equivalent to \tcode{ke}.% -& Average case - \bigoh{\tcode{a_tran.}\br{}\tcode{count(ke)}}, % avoid overfull - worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. % avoid overfull -\\ \rowsep -% -\indexunordmem{contains}% -\tcode{b.contains(k)} -& \tcode{bool} -& \effects Equivalent to \tcode{b.find(k) != b.end()}% -& Average case \bigoh{1}, worst case \bigoh{\tcode{b.size()}}. -\\ \rowsep -% -\tcode{a_tran.contains(ke)} -& \tcode{bool} -& \effects Equivalent to \tcode{a_tran.find(ke) != a_tran.end()}% -& Average case \bigoh{1}, - worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. % avoid overfull -\\ \rowsep -% -\indexunordmem{equal_range}% -\tcode{b.equal_range(k)} -& \tcode{pair}; \br - \tcode{pair} 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.% -& Average case \bigoh{\tcode{b.count(k)}}, worst case - \bigoh{\tcode{b.size()}}. -\\ \rowsep -% -\tcode{a_tran.equal_range(ke)} -& \tcode{pair}; \br - \tcode{pair} for const \tcode{a_tran}. -& \returns A range containing all elements with keys equivalent to - \tcode{ke}. Returns \tcode{make_pair(a_tran.end(), a_tran.end())} if - no such elements exist.% -& Average case - \bigoh{\tcode{a_tran.}\br{}\tcode{count(ke)}}, % avoid overfull - worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}. % avoid overfull -\\ \rowsep -% -\indexunordmem{bucket_count}% -\tcode{b.bucket_count()} -& \tcode{size_type} -& \returns The number of buckets that \tcode{b} contains.% -& Constant -\\ \rowsep -% -\indexunordmem{max_bucket_count}% -\tcode{b.max_bucket_count()} -& \tcode{size_type} -& \returns An upper bound on the number of buckets that \tcode{b} can - ever contain.% -& Constant -\\ \rowsep -% -\indexunordmem{bucket}% -\tcode{b.bucket(k)} -& \tcode{size_type} -& - \expects \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.\br - \ensures The return value is in the range \tcode{[0, b.bucket_count())}.% -& Constant -\\ \rowsep -% -\indexunordmem{bucket_size}% -\tcode{b.bucket_size(n)} -& \tcode{size_type} -& \expects \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}. - \returns The number of elements in the $\tcode{n}^\text{th}$ bucket.% -& \bigoh{\tcode{b.bucket_}\-\tcode{size(n)}} -\\ \rowsep -% -\indexunordmem{begin}% -\tcode{b.begin(n)} -& \tcode{local_iterator}; \br - \tcode{const_local_iterator} for const \tcode{b}. -& \expects \tcode{n} is in the range \tcode{[0, b.bucket_count())}.\br - \returns An iterator referring to the - first element in the bucket. If the bucket is empty, then - \tcode{b.begin(n) == b.end(n)}.% -& Constant -\\ \rowsep -% -\indexunordmem{end}% -\tcode{b.end(n)} -& \tcode{local_iterator}; \br - \tcode{const_local_iterator} for const \tcode{b}. -& \expects \tcode{n} is in the range \tcode{[0, b.bucket_count())}.\br - \returns An iterator which is the past-the-end - value for the bucket.% -& Constant -\\ \rowsep -% -\indexunordmem{cbegin}% -\tcode{b.cbegin(n)} -& \tcode{const_local_iterator} -& \expects \tcode{n} shall be in the range \tcode{[0, b.bucket_count())}.\br - \returns An iterator referring to the - first element in the bucket. If the bucket is empty, then - \tcode{b.cbegin(n) == b.cend(n)}.% -& Constant -\\ \rowsep -% -\indexunordmem{cend}% -\tcode{b.cend(n)} -& \tcode{const_local_iterator} -& \expects \tcode{n} is in the range \tcode{[0, b.bucket_count())}.\br - \returns An iterator which is the past-the-end - value for the bucket.% -& Constant -\\ \rowsep -% -\indexunordmem{load_factor}% -\tcode{b.load_factor()} -& \tcode{float} -& \returns The average number of elements per bucket.% -& Constant -\\ \rowsep -% -\indexunordmem{max_load_factor}% -\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.% -& Constant -\\ \rowsep -% -\tcode{a.max_load_factor(z)} -& \keyword{void} -& \expects \tcode{z} is positive. - May change the container's maximum load factor, using \tcode{z} as a hint.% -& Constant -\\ \rowsep -% -\indexunordmem{rehash}% -\tcode{a.rehash(n)} -& \keyword{void} -& \ensures \tcode{a.bucket_count() >= a.size() / a.max_load_factor()} and - \tcode{a.bucket_count() >= n}.% -& Average case linear in \tcode{a.size()}, worst case quadratic. -\\ \rowsep +\pnum +\complexity +Average case linear in \tcode{a.size()}, worst case quadratic. +\end{itemdescr} \indexunordmem{reserve}% -\tcode{a.reserve(n)} & - \keyword{void} & - Same as \tcode{a.rehash(ceil(n /} \tcode{a.max_load_factor()))}. & - Average case linear in \tcode{a.size()}, worst case quadratic. \\ +\begin{itemdecl} +a.reserve(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{a.rehash(ceil(n / a.max_load_factor()))}. +\end{itemdescr} -\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 @@ -3572,8 +5729,10 @@ \pnum \indextext{requirements!container}% -An \tcode{array} meets all of the requirements of a container and -of a reversible container\iref{container.requirements}, except that a default +An \tcode{array} meets all of the requirements +of a container\iref{container.reqmts} and +of a reversible container\iref{container.rev.reqmts}, +except that a default constructed \tcode{array} object is not empty and that \tcode{swap} does not have constant complexity. An \tcode{array} meets some of the requirements of a sequence container\iref{sequence.reqmts}. @@ -3887,11 +6046,12 @@ Storage management is handled automatically. \pnum -A -\tcode{deque} -meets 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\iref{sequence.reqmts}, and of an allocator-aware container (\tref{container.alloc.req}). +A \tcode{deque} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of a sequence container, +including the optional sequence container requirements\iref{sequence.reqmts}. Descriptions are provided here only for operations on \tcode{deque} that are not described in one of these tables @@ -4303,14 +6463,15 @@ \end{note} \pnum -A \tcode{forward_list} meets all of the requirements of a container -(\tref{container.req}), except that the \tcode{size()} -member function is not provided and \tcode{operator==} has linear complexity. -A \tcode{forward_list} also meets all of the requirements for an allocator-aware -container (\tref{container.alloc.req}). In addition, a \tcode{forward_list} -provides the \tcode{assign} member functions -(\tref{container.seq.req}) and several of the optional -container requirements (\tref{container.seq.opt}). +A \tcode{forward_list} meets all of the requirements +of a container\iref{container.reqmts}, +except that the \tcode{size()} member function is not provided and +\tcode{operator==} has linear complexity, +A \tcode{forward_list} also meets all of the requirements +for an allocator-aware container\iref{container.alloc.reqmts}. +In addition, a \tcode{forward_list} +provides the \tcode{assign} member functions and +several of the optional sequence container requirements\iref{sequence.reqmts}. 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. @@ -5104,12 +7265,13 @@ algorithms only need sequential access anyway. \pnum -A \tcode{list} meets all of the requirements of a container, of -a reversible container (given in two tables in -\ref{container.requirements}), of a sequence container, +A \tcode{list} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of a sequence container, including most of the optional sequence container -requirements\iref{sequence.reqmts}, and of an allocator-aware container -(\tref{container.alloc.req}). +requirements\iref{sequence.reqmts}. The exceptions are the \tcode{operator[]} and @@ -5816,11 +7978,12 @@ to improve efficiency. \pnum -A \tcode{vector} meets 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\iref{sequence.reqmts}, of an allocator-aware container -(\tref{container.alloc.req}), +A \tcode{vector} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, +of a sequence container, including most of the optional sequence container +requirements\iref{sequence.reqmts}, and, for an element type other than \tcode{bool}, of a contiguous container\iref{container.requirements.general}. The exceptions are the @@ -6695,10 +8858,11 @@ on the keys. The \tcode{map} class supports bidirectional iterators. \pnum -A -\tcode{map} -meets all of the requirements of a container, of a reversible container\iref{container.requirements}, of -an associative container\iref{associative.reqmts}, and of an allocator-aware container (\tref{container.alloc.req}). +A \tcode{map} meets all of the requirements of +a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}. and +of an associative container\iref{associative.reqmts}. A \tcode{map} also provides most operations described in~\ref{associative.reqmts} @@ -7242,11 +9406,11 @@ supports bidirectional iterators. \pnum -A -\tcode{multimap} meets all of the requirements of a container and of a -reversible container\iref{container.requirements}, of an associative -container\iref{associative.reqmts}, and of an allocator-aware container -(\tref{container.alloc.req}). +A \tcode{multimap} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of an associative container\iref{associative.reqmts}. A \tcode{multimap} also provides most operations described in~\ref{associative.reqmts} @@ -7563,10 +9727,11 @@ supports bidirectional iterators. \pnum -A \tcode{set} meets all of the requirements of a container, of a reversible -container\iref{container.requirements}, of an associative -container\iref{associative.reqmts}, and of an allocator-aware container -(\tref{container.alloc.req}). +A \tcode{set} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}. and +of an associative container\iref{associative.reqmts}. A \tcode{set} also provides most operations described in~\ref{associative.reqmts} @@ -7841,10 +10006,11 @@ supports bidirectional iterators. \pnum -A \tcode{multiset} meets all of the requirements of a container, of a -reversible container\iref{container.requirements}, of an associative -container\iref{associative.reqmts}, and of an allocator-aware container -(\tref{container.alloc.req}). +A \tcode{multiset} meets all of the requirements +of a container\iref{container.reqmts}, +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, +of an associative container\iref{associative.reqmts}. \tcode{multiset} also provides most operations described in~\ref{associative.reqmts} for duplicate keys. @@ -8272,7 +10438,11 @@ supports forward iterators. \pnum -An \tcode{unordered_map} meets all of the requirements of a container, of an unordered associative container, and of an allocator-aware container (\tref{container.alloc.req}). 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} the \tcode{key type} is \tcode{Key}, the mapped type is \tcode{T}, and the value type is \tcode{pair}. +An \tcode{unordered_map} meets all of the requirements +of a container\iref{container.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of an unordered associative container\iref{unord.req}. +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} the \tcode{key type} is \tcode{Key}, the mapped type is \tcode{T}, and the value type is \tcode{pair}. \pnum Subclause~\ref{unord.map} only describes operations on \tcode{unordered_map} that @@ -8864,9 +11034,11 @@ supports forward iterators. \pnum -An \tcode{unordered_multimap} meets all of the requirements of a container, of an -unordered associative container, and of an allocator-aware container -(\tref{container.alloc.req}). It provides the operations described in the +An \tcode{unordered_multimap} meets all of the requirements +of a container\iref{container.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of an unordered associative container\iref{unord.req}. +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} the \tcode{key type} is \tcode{Key}, the @@ -9240,7 +11412,11 @@ supports forward iterators. \pnum -An \tcode{unordered_set} meets all of the requirements of a container, of an unordered associative container, and of an allocator-aware container (\tref{container.alloc.req}). 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} the \tcode{key type} and the value type are both \tcode{Key}. The \tcode{iterator} and \tcode{const_iterator} types are both constant iterator types. It is unspecified whether they are the same type. +An \tcode{unordered_set} meets all of the requirements +of a container\iref{container.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, +of an unordered associative container\iref{unord.req}. +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} the \tcode{key type} and the value type are both \tcode{Key}. The \tcode{iterator} and \tcode{const_iterator} types are both constant iterator types. It is unspecified whether they are the same type. \pnum Subclause~\ref{unord.set} only describes operations on \tcode{unordered_set} that @@ -9561,9 +11737,11 @@ supports forward iterators. \pnum -An \tcode{unordered_multiset} meets all of the requirements of a container, of an -unordered associative container, and of an allocator-aware container -(\tref{container.alloc.req}). It provides the operations described in the +An \tcode{unordered_multiset} meets all of the requirements +of a container\iref{container.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of an unordered associative container\iref{unord.req}. +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} the \tcode{key type} and the value type are diff --git a/source/diagnostics.tex b/source/diagnostics.tex index d145ced062..76ffd019eb 100644 --- a/source/diagnostics.tex +++ b/source/diagnostics.tex @@ -1991,10 +1991,10 @@ \pnum The class template \tcode{basic_stacktrace} satisfies -the requirements of -an allocator-aware container (\tref{container.alloc.req}), -a sequence container\iref{sequence.reqmts}, and -a reversible container\iref{container.requirements.general} +the requirements +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +of a sequence container\iref{sequence.reqmts}, except that \begin{itemize} \item diff --git a/source/lib-intro.tex b/source/lib-intro.tex index 7cf1ca4e43..8b91715a40 100644 --- a/source/lib-intro.tex +++ b/source/lib-intro.tex @@ -349,6 +349,15 @@ the conditions (sometimes termed observable results) established by the function. +\item +\result +for a \grammarterm{typename-specifier}, a description of the named type; +for an \grammarterm{expression}, +a description of the type of the expression; +the expression is an lvalue if the type is an lvalue reference type, +an xvalue if the type is an rvalue reference type, and +a prvalue otherwise. + \item \returns a description of the value(s) returned by the function. diff --git a/source/macros.tex b/source/macros.tex index 46011ec26a..89ee44f07a 100644 --- a/source/macros.tex +++ b/source/macros.tex @@ -339,6 +339,7 @@ \newcommand{\sync}{\Fundesc{Synchronization}} \newcommand{\implimits}{\Fundesc{Implementation limits}} \newcommand{\replaceable}{\Fundesc{Replaceable}} +\newcommand{\result}{\Fundesc{Result}} \newcommand{\returntype}{\Fundesc{Return type}} \newcommand{\cvalue}{\Fundesc{Value}} \newcommand{\ctype}{\Fundesc{Type}} diff --git a/source/regex.tex b/source/regex.tex index 0cf5800101..9800293c79 100644 --- a/source/regex.tex +++ b/source/regex.tex @@ -63,130 +63,283 @@ \indextext{requirements!regular expression traits}% \indextext{regular expression!requirements}% \indextext{locale}% -In \tref{re.req} \tcode{X} denotes a traits class -defining types and functions for the character container -type \tcode{charT}; \tcode{u} is an object of -type \tcode{X}; \tcode{v} is an object of type \tcode{const -X}; \tcode{p} is a value of type \tcode{const charT*}; \tcode{I1} -and \tcode{I2} are input iterators\iref{input.iterators}; +In the following requirements, +\begin{itemize} +\item +\tcode{X} denotes a traits class defining types and functions +for the character container type \tcode{charT}; +\item +\tcode{u} is an object of type \tcode{X}; +\item +\tcode{v} is an object of type \tcode{const X}; +\item +\tcode{p} is a value of type \tcode{const charT*}; +\item +\tcode{I1} and \tcode{I2} are input iterators\iref{input.iterators}; +\item \tcode{F1} and \tcode{F2} are forward iterators\iref{forward.iterators}; +\item \tcode{c} is a value of type \tcode{const charT}; +\item \tcode{s} is an object of type \tcode{X::string_type}; +\item \tcode{cs} is an object of type \tcode{const X::string_type}; +\item \tcode{b} is a value of type \tcode{bool}; +\item \tcode{I} is a value of type \tcode{int}; -\tcode{cl} is an object of type \tcode{X::char_class_type}, -and \tcode{loc} is an object of type \tcode{X::locale_type}. - -\begin{libreqtab3} - {Regular expression traits class requirements} - {re.req} -\\ \topline -\lhdr{Expression} & \chdr{Return type} & \rhdr{Assertion/note pre-/post-condition } \\ \capsep -\endfirsthead -\continuedcaption\\ -\hline -\lhdr{Expression} & \chdr{Return type} & \rhdr{Assertion/note pre-/post-condition } \\ \capsep -\endhead -%% +\item +\tcode{cl} is an object of type \tcode{X::char_class_type}; and +\item +\tcode{loc} is an object of type \tcode{X::locale_type}. +\end{itemize} + +\pnum +A traits class \tcode{X} meets the regular expression traits requirements +if the following types and expressions are well-formed and have the specified +semantics. + +\begin{itemdecl} +typename X::char_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{charT}, +the character container type used in the implementation of class +template \tcode{basic_regex}. +\end{itemdescr} + +\begin{itemdecl} +typename X::string_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{basic_string} +\end{itemdescr} + +\begin{itemdecl} +typename X::locale_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A copy constructible type +that represents the locale used by the traits class. +\end{itemdescr} + +\begin{itemdecl} +typename X::char_class_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A bitmask type\iref{bitmask.types} +representing a particular character classification. +\end{itemdescr} + +\begin{itemdecl} +X::length(p) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_t} + +\pnum +\returns +The smallest \tcode{i} such that \tcode{p[i] == 0}. + +\pnum +\complexity +Linear in \tcode{i}. +\end{itemdescr} + +\begin{itemdecl} +v.translate(c) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result \tcode{X::char_type} - & \tcode{charT} - & The character container type used in the implementation of class - template \tcode{basic_regex}. - \\ \rowsep + +\pnum +\returns +A character such that for any character \tcode{d} +that is to be considered equivalent to \tcode{c} +then \tcode{v.translate(c) == v.translate(d)}. +\end{itemdescr} + +\begin{itemdecl} +v.translate_nocase(c) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::char_type} + +\pnum +\returns +For all characters \tcode{C} that are to be considered equivalent to \tcode{c} +when comparisons are to be performed without regard to case, +then \tcode{v.translate_nocase(c) == v.translate_nocase(C)}. +\end{itemdescr} + +\begin{itemdecl} +v.transform(F1, F2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result \tcode{X::string_type} - & \tcode{basic_string} - & - \\ \rowsep -\tcode{X::locale_type} - & A copy constructible type - & A type that represents the locale used by the traits class. \indextext{locale} - \\ \rowsep + +\pnum +\returns +A sort key for the character sequence designated by +the iterator range \range{F1}{F2} such that +if the character sequence \range{G1}{G2} sorts before +the character sequence \range{H1}{H2} +then \tcode{v.transform(G1, G2) < v.transform(H1, H2)}. +\end{itemdescr} + +\begin{itemdecl} +v.transform_primary(F1, F2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\indextext{regular expression traits!\idxcode{transform_primary}}% +\indextext{transform_primary@\tcode{transform_primary}!regular expression traits}% +\result +\tcode{X::string_type} + +\pnum +\returns +A sort key for the character sequence designated by +the iterator range \range{F1}{F2} such that +if the character sequence \range{G1}{G2} sorts before +the character sequence \range{H1}{H2} +when character case is not considered +then \tcode{v.transform_primary(G1, G2) < v.transform_primary(H1, H2)}. +\end{itemdescr} + +\begin{itemdecl} +v.lookup_collatename(F1, F2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::string_type} + +\pnum +\returns +A sequence of characters that represents the collating element +consisting of the character sequence designated by +the iterator range \range{F1}{F2}. +Returns an empty string +if the character sequence is not a valid collating element. +\end{itemdescr} + +\begin{itemdecl} +v.lookup_classname(F1, F2, b) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result \tcode{X::char_class_type} - & A bitmask type\iref{bitmask.types}. - & A bitmask type representing a particular character classification. - \\ \rowsep -\tcode{X::length(p)} - & \tcode{size_t} - & Yields the smallest \tcode{i} such that \tcode{p[i] == 0}. Complexity is - linear in \tcode{i}. - \\ \rowsep -\tcode{v.translate(c)} - & \tcode{X::char_type} - & Returns a character such that for any character \tcode{d} that is to - be considered equivalent to \tcode{c} then \tcode{v.translate(c) == v.translate(d)}. - \\ \rowsep -\tcode{v.translate_nocase(c)} - & \tcode{X::char_type} - & For all characters \tcode{C} that are to be considered equivalent - to \tcode{c} when comparisons are to be performed without regard to - case, then \tcode{v.translate_nocase(c) == v.translate_nocase(C)}. - \\ \rowsep -\tcode{v.transform(F1, F2)} - & \tcode{X::string_type} - & Returns a sort key for the character sequence designated by the - iterator range \range{F1}{F2} such that if the character sequence - \range{G1}{G2} sorts before the character sequence \range{H1}{H2} - then \tcode{v.transform(G1, G2) < v.transform(H1, H2)}. - \\ \rowsep -\tcode{v.transform_primary(F1, F2)} - & \tcode{X::string_type} - & Returns a sort key for the character sequence designated by the - iterator range \range{F1}{F2} such that if the character sequence - \range{G1}{G2} sorts before the character sequence \range{H1}{H2} - when character case is not considered - then \tcode{v.transform_primary(G1, G2) < v.transform_primary(H1, H2)}. - \indextext{regular expression traits!\idxcode{transform_primary}}% - \indextext{transform_primary@\tcode{transform_primary}!regular expression traits}% - \\ \rowsep -\tcode{v.lookup_collatename(F1, F2)} - & \tcode{X::string_type} - & Returns a sequence of characters that represents the collating element - consisting of the character sequence designated by the iterator range - \range{F1}{F2}. Returns an empty string if the character sequence is not - a valid collating element. - \\ \rowsep -\tcode{v.lookup_classname(F1, F2, b)} - & \tcode{X::char_class_type} - & Converts the character sequence designated by the iterator range - \range{F1}{F2} into a value of a bitmask type that can - subsequently be passed to \tcode{isctype}. Values returned from - \tcode{lookup_classname} can be bitwise \logop{OR}'ed together; the - resulting value represents membership in either of the - corresponding character classes. - If \tcode{b} is \tcode{true}, the returned bitmask is suitable for - matching characters without regard to their case. - Returns \tcode{0} if the character - sequence is not the name of a character class recognized by - \tcode{X}. The value returned shall be independent of the case of - the characters in the sequence. - \\ \rowsep -\tcode{v.isctype(c, cl)} - & \tcode{bool} - & Returns \tcode{true} if character \tcode{c} is a member of - one of the character classes designated by \tcode{cl}, - \tcode{false} otherwise. - \\ \rowsep -\tcode{v.value(c, I)} - & \tcode{int} - & Returns the value represented by the digit \textit{c} in base - \textit{I} if the character \textit{c} is a valid digit in base \textit{I}; - otherwise returns \tcode{-1}. -\begin{tailnote} -The value of \textit{I} will only - be 8, 10, or 16. -\end{tailnote} - \\ \rowsep -\tcode{u.imbue(loc)} - & \tcode{X::locale_type} - & Imbues \tcode{u} with the locale \tcode{loc} and returns the previous locale - used by \tcode{u} if any. \indextext{locale}% - \\ \rowsep -\tcode{v.getloc()} - & \tcode{X::locale_type} - & Returns the current locale used by \tcode{v}, if any. \indextext{locale}% - \\ -\end{libreqtab3} + +\pnum +\returns +Converts the character sequence designated by the iterator range +\range{F1}{F2} into a value of a bitmask type that can +subsequently be passed to \tcode{isctype}. +Values returned from \tcode{lookup_classname} can be bitwise \logop{OR}'ed together; +the resulting value represents membership +in either of the corresponding character classes. +If \tcode{b} is \tcode{true}, the returned bitmask is suitable for +matching characters without regard to their case. +Returns \tcode{0} +if the character sequence is not the name of +a character class recognized by \tcode{X}. +The value returned shall be independent of +the case of the characters in the sequence. +\end{itemdescr} + +\begin{itemdecl} +v.isctype(c, cl) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{bool} + +\pnum +\returns +Returns \tcode{true} if character \tcode{c} is a member of +one of the character classes designated by \tcode{cl}, +\tcode{false} otherwise. +\end{itemdescr} + +\begin{itemdecl} +v.value(c, I) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{int} + +\pnum +\returns +Returns the value represented by the digit \textit{c} in base +\textit{I} if the character \textit{c} is a valid digit in base \textit{I}; +otherwise returns \tcode{-1}. +\begin{note} +The value of \textit{I} will only be 8, 10, or 16. +\end{note} +\end{itemdescr} + +\begin{itemdecl} +u.imbue(loc) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::locale_type} + +\indextext{locale}% +\pnum +\effects +Imbues \tcode{u} with the locale \tcode{loc} and +returns the previous locale used by \tcode{u} if any. +\end{itemdescr} + +\begin{itemdecl} +v.getloc() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{X::locale_type} + +\pnum +\returns +Returns the current locale used by \tcode{v}, if any. \indextext{locale}% +\end{itemdescr} \pnum \begin{note} diff --git a/source/strings.tex b/source/strings.tex index ee30bed8c1..b54fb590de 100644 --- a/source/strings.tex +++ b/source/strings.tex @@ -1317,7 +1317,7 @@ \pnum \effects Constructs a string from the values in the range \range{begin}{end}, -as indicated in \tref{container.seq.req}. +as specified in \ref{sequence.reqmts}. \end{itemdescr} \indexlibraryctor{basic_string}%