From 486eb4f413ed9ae60f6b725d6e37495cb9f5e742 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sun, 14 Nov 2021 20:05:03 +0100 Subject: [PATCH 1/8] [container.requirements.general] container --- source/containers.tex | 603 ++++++++++++++++++++++++++++-------------- 1 file changed, 404 insertions(+), 199 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index 532888a1d8..7ebb49eeda 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -70,9 +70,7 @@ \end{note} \pnum -In Tables~\ref{tab:container.req}, -\ref{tab:container.rev.req}, and -\ref{tab:container.opt}, +In this subclause, \begin{itemize} \item \tcode{X} denotes a container class containing objects of type \tcode{T}, @@ -88,218 +86,426 @@ \tcode{rv} denotes a non-const rvalue of type \tcode{X}. \end{itemize} -\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. -\tcode{X::value_type} & - \tcode{T} & - & - \expects \tcode{T} is \oldconcept{Erasable} from \tcode{X} (see~\ref{container.requirements.general}, below) & - compile time \\ \rowsep - -\tcode{X::reference} & - \tcode{T\&} & - & - & - compile time \\ \rowsep - -\tcode{X::const_reference} & - \tcode{const T\&} & - & - & - compile time \\ \rowsep - -\tcode{X::iterator} & - iterator type whose value type is \tcode{T} & - & - any iterator category - that meets the forward iterator requirements. - convertible to \tcode{X::const_iterator}. & - compile time \\ \rowsep - -\tcode{X::const_iterator} & - constant iterator type whose value type is \tcode{T} & - & - any iterator category - that meets the forward iterator requirements. & - compile time \\ \rowsep - -\tcode{X::dif\-ference_type} & - signed integer type & - & - is identical to the difference type of \tcode{X::iterator} and \tcode{X::const_iterator} & - compile time \\ \rowsep - -\tcode{X::size_type} & - unsigned integer type & - & - \tcode{size_type} can represent any non-negative value of \tcode{difference_type} & - compile time \\ \rowsep - -\tcode{X u;} & - & - & - \ensures \tcode{u.empty()} & - constant \\ \rowsep +\begin{itemdecl} +typename X::value_type +\end{itemdecl} -\tcode{X()} & - & - & - \ensures \tcode{X().empty()} & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{T} -\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 +\pnum +\expects +\tcode{T} is \oldconcept{Erasable} from \tcode{X} +(see~\ref{container.alloc.reqmts}, below). +\end{itemdescr} -\tcode{a.\~X()} & - \keyword{void} & - & - \effects destroys every element of \tcode{a}; any memory obtained is deallocated. & - linear \\ \rowsep - -\tcode{a.begin()} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} & - & - & - constant \\ \rowsep +\begin{itemdecl} +typename X::reference +\end{itemdecl} -\tcode{a.end()} & - \tcode{iterator}; \tcode{const_iterator} for constant \tcode{a} & - & - & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{T\&} +\end{itemdescr} -\tcode{a.cbegin()} & - \tcode{const_iterator} & - \tcode{const_cast<\brk{}X const\&\brk{}>(a)\brk{}.begin();} & - & - constant \\ \rowsep +\begin{itemdecl} +typename X::const_reference +\end{itemdecl} -\tcode{a.cend()} & - \tcode{const_iterator} & - \tcode{const_cast<\brk{}X const\&\brk{}>(a)\brk{}.end();} & - & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{const T\&} +\end{itemdescr} -\tcode{i <=> j} & - \tcode{strong_ordering} & - & - \constraints \tcode{X::iterator} meets the random access iterator requirements. & - constant \\ \rowsep +\begin{itemdecl} +typename X::iterator +\end{itemdecl} -\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 - -\tcode{a != b} & - convertible to \tcode{bool} & - Equivalent to \tcode{!(a == b)} & - & - linear \\ \rowsep +\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} -\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 - -\tcode{r = a} & - \tcode{X\&} & - & - \ensures \tcode{r == a}. & - linear \\ \rowsep - -\tcode{a.size()} & - \tcode{size_type} & - \tcode{distance(\brk{}a.begin(), a.end())} & - & - constant \\ \rowsep - -\tcode{a.max_size()} & - \tcode{size_type} & - \tcode{distance(\brk{}begin(), end())} - for the largest possible container & - & - constant \\ \rowsep +\begin{itemdecl} +typename X::const_iterator +\end{itemdecl} -\tcode{a.empty()} & - convertible to \tcode{bool} & - \tcode{a.begin() == a.end()} & - & -constant \\ +\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} -\end{libreqtab5} +\begin{itemdecl} +typename X::difference_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A signed integer type, +identical to the difference type of +\tcode{X::iterator} and \tcode{X::const_iterator}. +\end{itemdescr} + +\begin{itemdecl} +typename X::size_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An unsigned integer type +that can represent any non-negative value of \tcode{X::difference_type}. +\end{itemdescr} + +\begin{itemdecl}{} +X u; +X u = X(); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\ensures +\tcode{u.empty()} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +X u(a); +X u = a; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X} (see below). + +\pnum +\ensures +\tcode{u == a} + +\pnum +\complexity +Linear. +\end{itemdescr} + +\begin{itemdecl} +X u(rv); +X u = rv; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\ensures +\tcode{u} is equal to the value that \tcode{rv} had before this construction. + +\pnum +\complexity +Linear for \tcode{array} and constant for all other standard containers. +\end{itemdescr} + +\begin{itemdecl} +a = rv +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An lvalue of type \tcode{X}. + +\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} + +\begin{itemdecl} +a.~X() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +Destroys every element of \tcode{a}; any memory obtained is deallocated. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\begin{itemdecl} +a.begin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{iterator}; +\tcode{const_iterator} for constant \tcode{a}. + +\pnum +\cvalue +An iterator referring to the first element in the container. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.end() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{iterator}; +\tcode{const_iterator} for constant \tcode{a}. + +\pnum +\cvalue +An iterator which is the past-the-end value for the container. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.cbegin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{const_iterator}. + +\pnum +\cvalue +\tcode{const_cast(a).begin()} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.cend() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{const_iterator}. + +\pnum +\cvalue +\tcode{const_cast(a).end()} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +i <=> j +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{strong_ordering}. + +\pnum +\constraints +\tcode{X::iterator} meets the random access iterator requirements. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a == b +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} meets the \oldconcept{EqualityComparable} requirements. + +\pnum +\result +Convertible to \tcode{bool}. + +\pnum +\cvalue +\tcode{equal(a.begin(), a.end(), b.begin(), b.end())} -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}. +The algorithm \tcode{equal} is defined in \ref{alg.equal}. \end{note} \pnum -The member function \tcode{size()} returns the number of elements in the container. +\complexity +Constant if \tcode{a.size() != b.size()}, linear otherwise. + +\pnum +\remarks +\tcode{==} is an equivalence relation. +\end{itemdescr} + +\begin{itemdecl} +a != b +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{!(a == b)}. +\end{itemdescr} + +\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 +Linear for \tcode{array} and constant for all other standard containers. +\end{itemdescr} + +\begin{itemdecl} +swap(a, b) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +Equivalent to \tcode{a.swap(b)}. +\end{itemdescr} + +\begin{itemdecl} +r = a +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An lvalue of type \tcode{X}. + +\pnum +\ensures +\tcode{r == a}. + +\pnum +\complexity +Linear. +\end{itemdescr} + +\begin{itemdecl} +a.size() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \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} + +\begin{itemdecl} +a.max_size() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{size_type}. + +\pnum +\returns +\tcode{distance(begin(), end())} for the largest possible container. + +\complexity +Constant. +\end{itemdescr} +\begin{itemdecl} +a.empty() +\end{itemdecl} + +\begin{itemdescr} \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()}. +\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 @@ -2678,8 +2884,8 @@ % \tcode{X(b)}\br \tcode{X a(b);} & \tcode{X} -& Copy constructor. In addition to the requirements - of \tref{container.req}, copies the +& Copy constructor. In addition to the container requirements\iref{container.requirements.general}, + copies the hash function, predicate, and maximum load factor. & Average case linear in \tcode{b.size()}, worst case quadratic. \\ \rowsep @@ -2687,7 +2893,7 @@ \tcode{a = b} & \tcode{X\&} & Copy assignment operator. In addition to the - requirements of \tref{container.req}, copies + container requirements, copies the hash function, predicate, and maximum load factor. & Average case linear in \tcode{b.size()}, worst case quadratic. \\ \rowsep @@ -4206,8 +4412,7 @@ \end{note} \pnum -A \tcode{forward_list} meets all of the requirements of a container -(\tref{container.req}), except that the \tcode{size()} +A \tcode{forward_list} meets all of the requirements of a container\iref{container.requirements.general}, 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} From 859ffce31e4ff25eae5ab23e4f9ab9e4936580d5 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sun, 14 Nov 2021 20:05:13 +0100 Subject: [PATCH 2/8] [container.requirements.general] reversible container --- source/containers.tex | 148 +++++++++++++++++++++++++++++------------- 1 file changed, 102 insertions(+), 46 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index 7ebb49eeda..eb5852e191 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -585,53 +585,109 @@ swap. \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}. +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. -\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 -\tcode{X::reverse_iterator} & -iterator type whose value type is \tcode{T} & - \tcode{reverse_iterator} & - compile time \\ \rowsep -\tcode{X::const_reverse_iterator} & - constant iterator type whose value type is \tcode{T} & - \tcode{reverse_iterator} & - compile time \\ \rowsep -\tcode{a.rbegin()} & - \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} & - \tcode{reverse_iterator(end())} & - constant \\ \rowsep -\tcode{a.rend()} & - \tcode{reverse_iterator; const_reverse_iterator} for constant \tcode{a} & - \tcode{reverse_iterator(begin())} & - constant \\ \rowsep -\tcode{a.crbegin()} & - \tcode{const_reverse_iterator} & - \tcode{const_cast(a).rbegin()} & - constant \\ \rowsep -\tcode{a.crend()} & - \tcode{const_reverse_iterator} & - \tcode{const_cast(a).rend()} & - constant \\ -\end{libreqtab4a} +\begin{itemdecl} +typename X::reverse_iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +The type \tcode{reverse_iterator}, +an iterator type whose value type is \tcode{T}. +\end{itemdescr} + +\begin{itemdecl} +typename X::const_reverse_iterator +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +The type \tcode{reverse_iterator}, +a constant iterator type whose value type is \tcode{T}. +\end{itemdescr} + +\begin{itemdecl} +a.rbegin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{reverse_iterator}; +\tcode{const_reverse_iterator} for constant \tcode{a}. + +\pnum +\cvalue +\tcode{reverse_iterator(end())} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.rend() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{reverse_iterator}; +\tcode{const_reverse_iterator} for constant \tcode{a}. + +\pnum +\cvalue +\tcode{reverse_iterator(begin())} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.crbegin() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{const_reverse_iterator}. + +\pnum +\cvalue +\tcode{\keyword{const_cast}(a).rbegin()} + +\pnum +\complexity +Constant. +\end{itemdescr} + +\begin{itemdecl} +a.crend() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{const_reverse_iterator}. + +\pnum +\cvalue +\tcode{\keyword{const_cast}(a).rend()} + +\pnum +\complexity +Constant. +\end{itemdescr} \pnum Unless otherwise specified (see~\ref{associative.reqmts.except}, \ref{unord.req.except}, \ref{deque.modifiers}, and From 3ad770b45daf6427232c6a2201498c07f9582337 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Thu, 17 Jun 2021 01:35:28 +0200 Subject: [PATCH 3/8] [container.requirements.general] optional and allocator-aware containers --- source/containers.tex | 353 ++++++++++++++++++++++++++---------------- 1 file changed, 221 insertions(+), 132 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index eb5852e191..0c515ec010 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -749,50 +749,48 @@ model \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous}. \pnum -\tref{container.opt} lists operations that are provided +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 described in -\tref{container.opt} unless otherwise stated. +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 in \tref{container.opt} +then the operations described below are implemented by constexpr functions. -\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 +\begin{itemdecl} +a <=> b +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \tcode{\exposid{synth-three-way-result}}. -\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 +\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 -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}. +\complexity +Linear. +\end{itemdescr} + +\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} @@ -881,16 +879,18 @@ \end{note} \pnum -In \tref{container.alloc.req}, +In this subclause, \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}, +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 @@ -898,108 +898,197 @@ \tcode{m} is a value of type \tcode{A}. \end{itemize} -\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 +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. -\lhdr{Expression} & \chdr{Return type} & -\chdr{Assertion/note} & \rhdr{Complexity} \\ - & & \chdr{pre-/post-condition} & \\ \capsep -\endhead +\begin{itemdecl} +typename X::allocator_type +\end{itemdecl} -\tcode{allocator_type} & - \tcode{A} & - \mandates \tcode{allocator_type::value_type} is the same as \tcode{X::value_type}. & - compile time \\ \rowsep - -\tcode{get_-} \tcode{allocator()} & - \tcode{A} & - & - constant \\ \rowsep - -\tcode{X()}\br -\tcode{X u;} & - & - \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 - -\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 - -\tcode{a.swap(b)} & - \keyword{void} & - \effects exchanges the contents of \tcode{a} and \tcode{b} & - constant \\ \rowsep +\begin{itemdescr} +\pnum +\result +\tcode{A} -\end{libreqtab4a} +\pnum +\expects +\tcode{allocator_type::value_type} is the same as \tcode{X::value_type}. +\end{itemdescr} + +\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 +An lvalue of type \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} + +\begin{itemdecl} +a = rv +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +An lvalue of type \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} + +\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 From 3232d3742a7d9f54a2e08ece98747e36804df889 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Thu, 17 Jun 2021 23:52:05 +0200 Subject: [PATCH 4/8] [sequence.reqmts] sequence container --- source/containers.tex | 1001 +++++++++++++++++++++++++++-------------- 1 file changed, 672 insertions(+), 329 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index 0c515ec010..b878866932 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -1162,8 +1162,7 @@ \end{note} \pnum -In Tables~\ref{tab:container.seq.req} -and \ref{tab:container.seq.opt}, +In this subclause, \begin{itemize} \item \tcode{X} denotes a sequence container class, @@ -1205,200 +1204,385 @@ \pnum The complexities of the expressions are sequence dependent. -\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 +\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. -\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 +\begin{itemdecl} +X u(n, t); +\end{itemdecl} -\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 - -\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 - -\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 +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{X}. -\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 - -\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 - -\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 - -\tcode{a.assign(il)} & - \keyword{void} & - \tcode{a.assign(il.begin(), il.end())}. \\ \rowsep - -\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} - -\pnum -The iterator returned from -\tcode{a.insert(p, t)} -points to the copy of -\tcode{t} -inserted into -\tcode{a}. +\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 -The iterator returned from \tcode{a.insert(p, rv)} points to the copy of \tcode{rv} -inserted into \tcode{a}. +\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 -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 +Constructs a sequence container equal to the range \tcode{[i, j)}. +Each iterator in the range \range{i}{j} is dereferenced exactly once. \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 +\tcode{distance(u.begin(), u.end()) == distance(i, j)} is \tcode{true}. +\end{itemdescr} + +\begin{itemdecl} +X(il) +\end{itemdecl} +\begin{itemdescr} \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. +\effects +Equivalent to \tcode{X(il.begin(), il.end())}. +\end{itemdescr} +\begin{itemdecl} +a = il +\end{itemdecl} + +\begin{itemdescr} \pnum -The iterator returned from \tcode{a.emplace(p, args)} points to the new element -constructed from \tcode{args} into \tcode{a}. +\result +An lvalue of type \tcode{X}. \pnum -The iterator returned from -\tcode{a.erase(q)} -points to the element immediately following -\tcode{q} +\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} + +\begin{itemdecl} +a.emplace(p, args) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \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} + +\begin{itemdecl} +a.insert(p, t) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \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 +A prvalue of type \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 +A prvalue of type \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 +A prvalue of type \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 +\result +\tcode{iterator} + +\pnum +\effects +Equivalent to \tcode{a.insert(p, il.begin(), il.end())}. + +\pnum +\returns +\begin{removedblock} +An iterator +that points to the copy of the first element inserted into \tcode{a}, or +\tcode{p} if \tcode{il} is empty. +\end{removedblock} +\end{itemdescr} + +\begin{itemdecl} +a.erase(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +A prvalue of type \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. +If no such element exists, \tcode{a.end()} is returned. +\end{itemdescr} + +\begin{itemdecl} +a.erase(q1, q2) +\end{itemdecl} +\begin{itemdescr} \pnum -The iterator returned by -\tcode{a.erase(q1, q2)} -points to the element pointed to by -\tcode{q2} +\result +A prvalue of type \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. +If no such element exists, \tcode{a.end()} is returned. +\end{itemdescr} + +\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} + +\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 +\result +\keyword{void} + +\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}: @@ -1438,165 +1622,324 @@ \end{itemize} \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. +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{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 +\begin{itemdecl} +a.front() +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\result +\tcode{reference; const_reference} for constant \tcode{a}. -\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 +\pnum +\returns +\tcode{*a.begin()} -\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 +\pnum +\remarks +Required for +\tcode{basic_string}, +\tcode{array}, +\tcode{deque}, +\tcode{forward_list}, +\tcode{list}, and +\tcode{vector}. +\end{itemdescr} -\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 +\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}. -\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()}. +\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} From e07093f5e49e69d2bd013068821a2f714af0956e Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sat, 19 Jun 2021 09:22:56 +0200 Subject: [PATCH 5/8] [associative.reqmts.general] associative containers --- source/containers.tex | 1497 ++++++++++++++++++++++++++++++----------- 1 file changed, 1089 insertions(+), 408 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index b878866932..36cb6140c3 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -2342,20 +2342,7 @@ \end{note} \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} - -\pnum -In \tref{container.assoc.req}, +In this subclause, \begin{itemize} \item \tcode{X} denotes an associative container class, @@ -2430,6 +2417,23 @@ 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 \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} + % Local command to index names as members of all ordered containers. \newcommand{\indexordmem}[1]{% \indexlibrary{\idxcode{#1}!ordered associative containers}% @@ -2439,436 +2443,1113 @@ \indexlibrary{\idxcode{multimap}!\idxcode{#1}}% } -\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 - \indexordmem{key_type}% -\tcode{X::key_type} & - \tcode{Key} & - & - compile time \\ \rowsep +\begin{itemdecl} +typename X::key_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key}. +\end{itemdescr} \indexordmem{mapped_type}% -\tcode{X::mapped_type} (\tcode{map} and \tcode{multimap} only) & - \tcode{T} & - & - compile time \\ \rowsep +\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}% -\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 +\begin{itemdecl} +typename X::value_type +\end{itemdecl} -\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 +\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}% -\tcode{X::key_compare} & - \tcode{Compare} & - \expects \tcode{key_compare} is \oldconcept{CopyConstructible}. & - compile time \\ \rowsep +\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}% -\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 +\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}% -\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{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}% -\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 +\begin{itemdecl} +\tcode{X(c)} +\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 +\effects +Constructs an empty container. +Uses a copy of \tcode{c} as a comparison object. -\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 +\complexity +Constant. +\end{itemdescr} -\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 +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X u = X(); +X u; +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\expects +\tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements. -\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 +\pnum +\effects +Constructs an empty container. +Uses \tcode{Compare()} as a comparison object. -\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 +\pnum +\complexity +Constant. +\end{itemdescr} -\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 +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(i, j, c) +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\expects +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. -\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 +\pnum +\effects +Constructs an empty container and +inserts elements from the range \range{i}{j} into it; +uses \tcode{c} as a comparison object. -\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 +\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} -\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 +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(i, j) +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\expects +\tcode{key_compare} meets the \oldconcept{DefaultConstructible} requirements. +\tcode{value_type} is +\oldconcept{EmplaceConstructible} into \tcode{X} from \tcode{*i}. -\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 +\pnum +\effects +Constructs an empty container and +inserts elements from the range \range{i}{j} into it; +uses \tcode{Compare()} as a comparison object. -\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 +\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} -\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 +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(il, c) +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end(), c)}. +\end{itemdescr} -\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 +\indexlibraryctor{set}% +\indexlibraryctor{map}% +\indexlibraryctor{multiset}% +\indexlibraryctor{multimap}% +\begin{itemdecl} +X(il) +\end{itemdecl} -\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 +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{X(il.begin(), il.end())}. +\end{itemdescr} -\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} +\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 +\result +\keyword{void} + +\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 +\result +\keyword{void} + +\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();} + +\pnum +\complexity +Logarithmic. +\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();} + +\pnum +\complexity +Logarithmic. +\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 From b87c163611ff5ed9040f09e6828943fd1a5269fd Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sun, 20 Jun 2021 21:22:29 +0200 Subject: [PATCH 6/8] [unord.req.general] unordered associative containers --- source/containers.tex | 2066 ++++++++++++++++++++++++++++------------- 1 file changed, 1446 insertions(+), 620 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index 36cb6140c3..7b8b3906e1 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -3758,19 +3758,6 @@ \tcode{unordered_multimap}, rehashing preserves the relative ordering of equivalent elements. -\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} - \pnum \indextext{unordered associative containers}% \indextext{unordered associative containers!requirements}% @@ -3778,7 +3765,7 @@ \indextext{unordered associative containers!unique keys}% \indextext{unordered associative containers!equivalent keys}% \indextext{requirements!container}% -In \tref{container.hash.req}, +In this subclause, \begin{itemize} \item \tcode{X} denotes an unordered associative container class, @@ -3851,6 +3838,24 @@ \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 \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} + % Local command to index names as members of all unordered containers. \newcommand{\indexunordmem}[1]{% \indexlibrary{\idxcode{#1}!unordered associative containers}% @@ -3860,633 +3865,1454 @@ \indexlibrary{\idxcode{unordered_multimap}!\idxcode{#1}}% } -\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 +\begin{itemdecl} +typename X::key_type +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{Key}. +\end{itemdescr} \indexunordmem{mapped_type}% -\tcode{X::mapped_type} (\tcode{unordered_map} and \tcode{unordered_multimap} only) & - \tcode{T} & - & - compile time \\ \rowsep +\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}% -\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 +\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. -\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 +\expects +\tcode{value_type} is \oldconcept{Erasable} from \tcode{X}. +\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 -% +\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}% -\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 -% +\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}% -\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 -% +\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}% -\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 -% +\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}% -\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{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}% -\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 container requirements\iref{container.requirements.general}, - 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 - container requirements, copies - the hash function, predicate, and maximum load factor. -& Average case linear in \tcode{b.size()}, worst case quadratic. -\\ \rowsep -% -\tcode{a = il} -& \tcode{X\&} -& \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 -% +\begin{itemdecl} +X(n, hf, eq) +\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 +\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. -\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 +\complexity +\bigoh{\tcode{n}} +\end{itemdescr} -\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 +\begin{itemdecl} +X(n, hf) +\end{itemdecl} -\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{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 +\result +\keyword{void} + +\pnum +\effects +Equivalent to \tcode{a.insert(il.begin(), il.end())}. +\end{itemdescr} + +\indexunordmem{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 +\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 +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_uniq.size()}}. +\end{itemdescr} + +\indexunordmem{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. + +\pnum +\ensures +\tcode{nh} is empty. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a_eq.size()}}. +\end{itemdescr} + +\indexunordmem{insert}% +\begin{itemdecl} +a.insert(q, 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 iterator \tcode{q} is a hint pointing to where the search should start. +Implementations are permitted to ignore the hint. + +\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 +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{extract}% +\begin{itemdecl} +a.extract(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +Removes an 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 +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{extract}% +\begin{itemdecl} +a_tran.extract(kx) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +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} +a.extract(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{node_type} + +\pnum +\effects +Removes the element pointed to by \tcode{q}. + +\returns +A \tcode{node_type} owning that element. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{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 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}. + +\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} +a.erase(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\effects +Erases all elements with key equivalent to \tcode{k}. + +\pnum +\returns +The number of elements erased. + +\pnum +\complexity +Average case \bigoh{\tcode{a.count(k)}}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{erase}% +\begin{itemdecl} +a_tran.erase(kx) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\effects +Erases all elements with key equivalent to \tcode{kx}. + +\pnum +\returns +The number of elements erased. + +\pnum +\complexity +Average case \bigoh{\tcode{a_tran.count(kx)}}, +worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} + +\indexunordmem{erase}% +\begin{itemdecl} +a.erase(q) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +Erases the element pointed to by \tcode{q}. + +\pnum +\returns +The iterator immediately following \tcode{q} prior to the erasure. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{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 +The iterator immediately following \tcode{r} prior to the erasure. + +\pnum +\complexity +Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{erase}% +\begin{itemdecl} +a.erase(q1, q2) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator} + +\pnum +\effects +Erases all elements in the range \tcode{[q1, q2)}. + +\pnum +\returns +The iterator immediately following the erased elements prior to the erasure. + +\pnum +\complexity +Average case linear in \tcode{distance(q1, q2)}, +worst case \bigoh{\tcode{a.size()}}. +\end{itemdescr} + +\indexunordmem{clear}% +\begin{itemdecl} +a.clear() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +Erases all elements in the container. + +\pnum +\ensures +\tcode{a.empty()} is \tcode{true}. + +\pnum +\complexity +Linear in \tcode{a.size()}. +\end{itemdescr} + +\indexunordmem{find}% +\begin{itemdecl} +b.find(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{iterator}; \tcode{const_iterator} for const \tcode{b}. + +\pnum +\returns +An iterator pointing to an element with key equivalent to \tcode{k}, or +\tcode{b.end()} if no such element exists. + +\pnum +\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 +\result +\tcode{iterator}; \tcode{const_iterator} for const \tcode{a_tran}. + +\pnum +\returns +An iterator pointing to an element with key equivalent to \tcode{ke}, or +\tcode{a_tran.end()} if no such element exists. + +\pnum +\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 +\result +\tcode{size_type} + +\pnum +\returns +The number of elements with key equivalent to \tcode{k}. + +\pnum +\complexity +Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}. +\end{itemdescr} + +\indexunordmem{count}% +\begin{itemdecl} +a_tran.count(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\returns +The number of elements with key equivalent to \tcode{ke}. + +\pnum +\complexity +Average case \bigoh{\tcode{a_tran.count(ke)}}, +worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} + +\indexunordmem{contains}% +\begin{itemdecl} +b.contains(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{bool} + +\pnum +\effects +Equivalent to \tcode{b.find(k) != b.end()}. +\end{itemdescr} + +\indexunordmem{contains}% +\begin{itemdecl} +a_tran.contains(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{bool} + +\pnum +\effects +Equivalent to \tcode{a_tran.find(ke) != a_tran.end()}. +\end{itemdescr} + +\indexunordmem{equal_range}% +\begin{itemdecl} +b.equal_range(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for const \tcode{b}. + +\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. + +\pnum +\complexity +Average case \bigoh{\tcode{b.count(k)}}, worst case \bigoh{\tcode{b.size()}}. +\end{itemdescr} + +\indexunordmem{equal_range}% +\begin{itemdecl} +a_tran.equal_range(ke) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{pair}; +\tcode{pair} for const \tcode{a_tran}. + +\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. + +\pnum +\complexity +Average case \bigoh{\tcode{a_tran.count(ke)}}, +worst case \bigoh{\tcode{a_tran.size()}}. +\end{itemdescr} + +\indexunordmem{bucket_count}% +\begin{itemdecl} +b.bucket_count() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\returns +The number of buckets that \tcode{b} contains. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{max_bucket_count}% +\begin{itemdecl} +b.max_bucket_count() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\returns +An upper bound on the number of buckets that \tcode{b} can ever contain. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{bucket}% +\begin{itemdecl} +b.bucket(k) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\expects +\tcode{b.bucket_count() > 0}. + +\pnum +\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())}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{bucket_size}% +\begin{itemdecl} +b.bucket_size(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{size_type} + +\pnum +\expects +\tcode{n} shall be in the range \tcode{[0, b.bucket_count())}. + +\pnum +\returns +The number of elements in the $\tcode{n}^\text{th}$ bucket. + +\pnum +\complexity +\bigoh{\tcode{b.bucket_size(n)}} +\end{itemdescr} + +\indexunordmem{begin}% +\begin{itemdecl} +b.begin(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{local_iterator}; \tcode{const_local_iterator} for const \tcode{b}. + +\pnum +\expects +\tcode{n} is 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.begin(n) == b.end(n)}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{end}% +\begin{itemdecl} +b.end(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{local_iterator}; \tcode{const_local_iterator} for const \tcode{b}. + +\pnum +\expects +\tcode{n} is in the range \tcode{[0, b.bucket_count())}. + +\pnum +\returns +An iterator which is the past-the-end value for the bucket. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{cbegin}% +\begin{itemdecl} +b.cbegin(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{const_local_iterator} + +\pnum +\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 +\result +\tcode{const_local_iterator} + +\pnum +\expects +\tcode{n} is in the range \tcode{[0, b.bucket_count())}. + +\pnum +\returns +An iterator which is the past-the-end value for the bucket. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{load_factor}% +\begin{itemdecl} +b.load_factor() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{float} + +\pnum +\returns +The average number of elements per bucket. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{max_load_factor}% +\begin{itemdecl} +b.max_load_factor() +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\tcode{float} + +\pnum +\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. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{max_load_factor}% +\begin{itemdecl} +a.max_load_factor(z) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\expects +\tcode{z} is positive. +May change the container's maximum load factor, using \tcode{z} as a hint. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexunordmem{rehash}% +\begin{itemdecl} +a.rehash(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\ensures +\tcode{a.bucket_count() >= a.size() / a.max_load_factor()} and +\tcode{a.bucket_count() >= n}.% + +\pnum +\complexity +Average case linear in \tcode{a.size()}, worst case quadratic. +\end{itemdescr} + +\indexunordmem{reserve}% +\begin{itemdecl} +a.reserve(n) +\end{itemdecl} + +\begin{itemdescr} +\pnum +\result +\keyword{void} + +\pnum +\effects +Equivalent to \tcode{a.rehash(ceil(n / a.max_load_factor()))}. + +\pnum +\complexity +Average case linear in \tcode{a.size()}, worst case quadratic. +\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 From 4884f6aa243e1eac6626d0afc62ab704cb5d526c Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sat, 26 Jun 2021 08:37:13 +0200 Subject: [PATCH 7/8] [lib] Fix cross-references to container requirements tables --- source/containers.tex | 146 ++++++++++++++++++++++++++---------------- source/strings.tex | 2 +- source/utilities.tex | 8 +-- 3 files changed, 95 insertions(+), 61 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index 7b8b3906e1..b0f0e55736 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,8 +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 this subclause, +In subclause \ref{container.gen.reqmts}, \begin{itemize} \item \tcode{X} denotes a container class containing objects of type \tcode{T}, @@ -86,6 +90,8 @@ \tcode{rv} denotes a non-const rvalue of type \tcode{X}. \end{itemize} +\rSec3[container.reqmts]{Containers} + \pnum A type \tcode{X} meets the \defn{container} requirements if the following types, statements, and expressions are well-formed and @@ -584,6 +590,8 @@ with value \tcode{a.end()} before the swap will have value \tcode{b.end()} after the swap. +\rSec3[container.rev.reqmts]{Reversible container requirements} + \pnum A type \tcode{X} meets the \defnadj{reversible}{container} requirements if \tcode{X} meets the container requirements, @@ -748,6 +756,8 @@ \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 @@ -787,6 +797,8 @@ 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}, @@ -1993,7 +2005,7 @@ 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}. + // 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 @@ -2425,7 +2437,7 @@ have the specified semantics, 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} +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} @@ -3846,7 +3858,7 @@ 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 \tref{container.alloc.req} +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} @@ -5676,8 +5688,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}. @@ -5991,11 +6005,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 @@ -6407,13 +6422,15 @@ \end{note} \pnum -A \tcode{forward_list} meets all of the requirements of a container\iref{container.requirements.general}, 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. @@ -7207,12 +7224,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 @@ -7919,11 +7937,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 @@ -8798,10 +8817,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} @@ -9345,11 +9365,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} @@ -9666,10 +9686,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} @@ -9944,10 +9965,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. @@ -10375,7 +10397,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 @@ -10967,9 +10993,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 @@ -11343,7 +11371,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 @@ -11664,9 +11696,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/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}% diff --git a/source/utilities.tex b/source/utilities.tex index a680c2cd23..e3a9c7b4fe 100644 --- a/source/utilities.tex +++ b/source/utilities.tex @@ -22981,10 +22981,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 From e95cd5966d66e531fb6d2926b5637bf6b66e0b9a Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Sun, 27 Jun 2021 11:26:39 +0200 Subject: [PATCH 8/8] [container.requirements] Omit redundant specification where "Effects: Equivalent to" wording is used. --- source/containers.tex | 60 ------------------------------------------- 1 file changed, 60 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index b0f0e55736..643b23f7bd 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -423,10 +423,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.swap(b)}. @@ -1438,21 +1434,9 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\tcode{iterator} - \pnum \effects Equivalent to \tcode{a.insert(p, il.begin(), il.end())}. - -\pnum -\returns -\begin{removedblock} -An iterator -that points to the copy of the first element inserted into \tcode{a}, or -\tcode{p} if \tcode{il} is empty. -\end{removedblock} \end{itemdescr} \begin{itemdecl} @@ -1563,10 +1547,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.assign(il.begin(), il.end())}. @@ -1667,10 +1647,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\tcode{reference; const_reference} for constant \tcode{a}. - \pnum \effects Equivalent to: @@ -2948,10 +2924,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.insert(il.begin(), il.end())}. @@ -3305,10 +3277,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.erase(a.begin(), a.end())}. @@ -3415,10 +3383,6 @@ \pnum \effects Equivalent to: \tcode{return b.find(k) != b.end();} - -\pnum -\complexity -Logarithmic. \end{itemdescr} \indexordmem{contains}% @@ -3434,10 +3398,6 @@ \pnum \effects Equivalent to: \tcode{return a_tran.find(ke) != a_tran.end();} - -\pnum -\complexity -Logarithmic. \end{itemdescr} \indexordmem{lower_bound}% @@ -4533,10 +4493,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.insert(il.begin(), il.end())}. @@ -4977,10 +4933,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\tcode{bool} - \pnum \effects Equivalent to \tcode{b.find(k) != b.end()}. @@ -4992,10 +4944,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\tcode{bool} - \pnum \effects Equivalent to \tcode{a_tran.find(ke) != a_tran.end()}. @@ -5312,17 +5260,9 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\result -\keyword{void} - \pnum \effects Equivalent to \tcode{a.rehash(ceil(n / a.max_load_factor()))}. - -\pnum -\complexity -Average case linear in \tcode{a.size()}, worst case quadratic. \end{itemdescr} \pnum