From 018c69ebe551d96d89b83004901e41ff5ac23590 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Tue, 18 Feb 2025 14:00:27 +0100 Subject: [PATCH 1/6] P0447R28 Introduction of std::hive to the standard library --- source/compatibility.tex | 1 + source/containers.tex | 1162 +++++++++++++++++++++++++++++++++++++- source/lib-intro.tex | 1 + source/support.tex | 1 + 4 files changed, 1159 insertions(+), 6 deletions(-) diff --git a/source/compatibility.tex b/source/compatibility.tex index 181b6744f0..fe9d4ce861 100644 --- a/source/compatibility.tex +++ b/source/compatibility.tex @@ -218,6 +218,7 @@ \libheaderrefx{contracts}{support.contract}, \libheaderref{debugging}, \libheaderrefx{hazard_pointer}{hazard.pointer.syn}, +\libheaderref{hive}, \libheaderrefx{inplace_vector}{inplace.vector.syn}, \libheaderref{linalg}, \libheaderref{rcu}, diff --git a/source/containers.tex b/source/containers.tex index 84445a88fa..da3f987392 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -20,8 +20,8 @@ \ref{container.requirements} & Requirements & \\ \rowsep \ref{sequences} & Sequence containers & \tcode{}, \tcode{}, \tcode{}, - \tcode{}, \\ & & - \tcode{}, \tcode{} \\ \rowsep + \tcode{}, \\ & & + \tcode{}, \tcode{}, \tcode{} \\ \rowsep \ref{associative} & Associative containers & \tcode{}, \tcode{} \\ \rowsep \ref{unord} & Unordered associative containers & @@ -112,6 +112,7 @@ \indexlibrarymemberx{array}{#1}% \indexlibrarymemberx{deque}{#1}% \indexlibrarymemberx{forward_list}{#1}% +\indexlibrarymemberx{hive}{#1}% \indexlibrarymemberx{list}{#1}% \indexlibrarymemberx{vector}{#1}% \indexlibrarymemberx{map}{#1}% @@ -426,7 +427,25 @@ Constant. \end{itemdescr} -\indexcont{operator==}% +% hive is excluded here +\indexlibrarymisc{\idxcode{operator==}}{containers}% +\indexlibrarymemberx{array}{operator==}% +\indexlibrarymemberx{deque}{operator==}% +\indexlibrarymemberx{forward_list}{operator==}% +\indexlibrarymemberx{list}{operator==}% +\indexlibrarymemberx{vector}{operator==}% +\indexlibrarymemberx{map}{operator==}% +\indexlibrarymemberx{set}{operator==}% +\indexlibrarymemberx{multiset}{operator==}% +\indexlibrarymemberx{multimap}{operator==}% +\indexlibrarymemberx{unordered_map}{operator==}% +\indexlibrarymemberx{unordered_set}{operator==}% +\indexlibrarymemberx{unordered_multiset}{operator==}% +\indexlibrarymemberx{unordered_multimap}{operator==}% +\indexlibrarymemberx{flat_map}{operator==}% +\indexlibrarymemberx{flat_set}{operator==}% +\indexlibrarymemberx{flat_multiset}{operator==}% +\indexlibrarymemberx{flat_multimap}{operator==}% \begin{itemdecl} c == b \end{itemdecl} @@ -457,7 +476,25 @@ \tcode{==} is an equivalence relation. \end{itemdescr} -\indexcont{operator"!=}% +% hive is excluded here +\indexlibrarymisc{\idxcode{operator"!=}}{containers}% +\indexlibrarymemberx{array}{operator"!=}% +\indexlibrarymemberx{deque}{operator"!=}% +\indexlibrarymemberx{forward_list}{operator"!=}% +\indexlibrarymemberx{list}{operator"!=}% +\indexlibrarymemberx{vector}{operator"!=}% +\indexlibrarymemberx{map}{operator"!=}% +\indexlibrarymemberx{set}{operator"!=}% +\indexlibrarymemberx{multiset}{operator"!=}% +\indexlibrarymemberx{multimap}{operator"!=}% +\indexlibrarymemberx{unordered_map}{operator"!=}% +\indexlibrarymemberx{unordered_set}{operator"!=}% +\indexlibrarymemberx{unordered_multiset}{operator"!=}% +\indexlibrarymemberx{unordered_multimap}{operator"!=}% +\indexlibrarymemberx{flat_map}{operator"!=}% +\indexlibrarymemberx{flat_set}{operator"!=}% +\indexlibrarymemberx{flat_multiset}{operator"!=}% +\indexlibrarymemberx{flat_multimap}{operator"!=}% \begin{itemdecl} c != b \end{itemdecl} @@ -727,6 +764,7 @@ \indexlibrarymisc{\idxcode{#1}}{reversible containers}% \indexlibrarymemberx{array}{#1}% \indexlibrarymemberx{deque}{#1}% +\indexlibrarymemberx{hive}{#1}% \indexlibrarymemberx{list}{#1}% \indexlibrarymemberx{vector}{#1}% \indexlibrarymemberx{map}{#1}% @@ -1038,6 +1076,7 @@ \indexlibrarymisc{\idxcode{#1}}{allocator-aware containers}% \indexlibrarymemberx{deque}{#1}% \indexlibrarymemberx{forward_list}{#1}% +\indexlibrarymemberx{hive}{#1}% \indexlibrarymemberx{list}{#1}% \indexlibrarymemberx{vector}{#1}% \indexlibrarymemberx{map}{#1}% @@ -1279,8 +1318,11 @@ \tcode{vector}, \tcode{inplace_vector}, \tcode{forward_list}, \tcode{list}, and \tcode{deque}. In addition, -\tcode{array} is provided as a sequence container which provides limited sequence operations -because it has a fixed number of elements. The library also provides container adaptors that +\tcode{array} and \tcode{hive} are provided as sequence containers +which provide limited sequence operations, +in \tcode{array}'s case because it has a fixed number of elements, and +in \tcode{hive}'s case because insertion order is unspecified. +The library also provides container adaptors that make it easy to construct abstract data types, such as \tcode{stack}s, \tcode{queue}s, @@ -7842,6 +7884,1114 @@ Equivalent to: \tcode{return c.remove_if(pred);} \end{itemdescr} +\rSec2[hive.syn]{Header \tcode{} synopsis} + +\indexheader{hive}% +\begin{codeblock} + +#include // see \ref{initializer.list.syn} +#include // see \ref{compare.syn} + +namespace std { + struct @\libglobal{hive_limits}@ { + size_t @\libmember{min}{hive_limits}@; + size_t @\libmember{max}{hive_limits}@; + constexpr hive_limits(size_t minimum, size_t maximum) noexcept + : min(minimum), max(maximum) {} + }; + + // \ref {hive}, class template \tcode{hive} + template> class hive; + + template + void swap(hive& x, hive& y) + noexcept(noexcept(x.swap(y))); + + template + typename hive::size_type + erase(hive& c, const U& value); + + template + typename hive::size_type + erase_if(hive& c, Predicate pred); + + namespace pmr { + template + using hive = std::hive>; + } +} +\end{codeblock} + +\rSec2[hive]{Class template \tcode{hive}} + +\rSec3[hive.overview]{Overview} + +\pnum +A \tcode{hive} is a type of sequence container +that provides constant-time insertion and erasure operations. +Storage is automatically managed in multiple memory blocks, +referred to as \defnx{element blocks}{element block}. +Insertion position is determined by the container, and +may re-use the memory locations of erased elements. + +\pnum +Element blocks which contain elements are referred to +as \defnadjx{active}{blocks}{block}, +those which do not are referred to as \defnadjx{reserved}{blocks}{block}. +Active blocks which become empty of elements are +either deallocated or become reserved blocks. +Reserved blocks become active blocks when they are used to store elements. +A user can create additional reserved blocks by calling \tcode{reserve}. + +\pnum +Erasures use unspecified techniques of constant time complexity +to identify the memory locations of erased elements, +which are subsequently skipped during iteration, +as opposed to relocating subsequent elements during erasure. + +\pnum +Active block capacities have +an \impldef{growth factor of \tcode{hive} active block capacities} growth factor +(which need not be integral), +for example a new active block's capacity could be equal to +the summed capacities of the pre-existing active blocks. + +\pnum +Limits can be placed on +both the minimum and maximum element capacities of element blocks, +both by users and implementations. +\begin{itemize} +\item +The minimum limit shall be no larger than the maximum limit. +\item +When limits are not specified by a user during construction, +the implementation's default limits are used. +\item +The default limits of an implementation are not guaranteed to be the same as +the minimum and maximum possible capacities +for an implementation's element blocks. +\begin{note} +To allow latitude for +both implementation-specific and user-directed optimization. +\end{note} +The latter are defined as hard limits. +The maximum hard limit shall be no larger than +\tcode{std::allocator_traits::max_size()}. +\item +If user-specified limits are not within hard limits, or +if the specified minimum limit is greater than the specified maximum limit, +the behavior is undefined. +\item +An element block is said to be \defnx{within the bounds}{element block!bounds} +of a pair of minimum/maximum limits +when its capacity is greater-or-equal-to the minimum limit and +less-than-or-equal-to the maximum limit. +\end{itemize} + +\pnum +A \tcode{hive} conforms to +the requirements for containers\iref{container.reqmts}, +with the exception of operators \tcode{==} and \tcode{!=}. +A \tcode{hive} also meets the requirements +of a reversible container\iref{container.rev.reqmts}, +of an allocator-aware container\iref{container.alloc.reqmts}, and +some of the requirements of a sequence container, +including several of +the optional sequence container requirements\iref{sequence.reqmts}. +Descriptions are provided here only for operations on \tcode{hive} +that are not described in that table or for operations +where there is additional semantic information. + +\pnum +The iterators of \tcode{hive} meet +the \oldconcept{BidirectionalIterator} requirements +but also model \tcode{\libconcept{three_way_comparable}}. + +\begin{codeblock} +namespace std { + template> + class @\libglobal{hive}@ { + public: + // types + using value_type = T; + using allocator_type = Allocator; + using pointer = typename allocator_traits::pointer; + using const_pointer = typename allocator_traits::const_pointer; + using reference = value_type&; + using const_reference = const value_type&; + using size_type = @\impdef@; // see \ref{container.requirements} + using difference_type = @\impdef@; // see \ref{container.requirements} + using iterator = @\impdef@; // see \ref{container.requirements} + using const_iterator = @\impdef@; // see \ref{container.requirements} + using reverse_iterator = std::reverse_iterator; // see \ref{container.requirements} + using const_reverse_iterator = std::reverse_iterator; // see \ref{container.requirements} + + // \ref{hive.cons}, construct/copy/destroy + constexpr hive() noexcept(noexcept(Allocator())) : hive(Allocator()) {} + constexpr explicit hive(const Allocator&) noexcept; + constexpr explicit hive(hive_limits block_limits) : hive(block_limits, Allocator()) {} + constexpr hive(hive_limits block_limits, const Allocator&); + explicit hive(size_type n, const Allocator& = Allocator()); + hive(size_type n, hive_limits block_limits, const Allocator& = Allocator()); + hive(size_type n, const T& value, const Allocator& = Allocator()); + hive(size_type n, const T& value, hive_limits block_limits, const Allocator& = Allocator()); + template + hive(InputIterator first, InputIterator last, const Allocator& = Allocator()); + template + hive(InputIterator first, InputIterator last, hive_limits block_limits, + const Allocator& = Allocator()); + template<@\exposconcept{container-compatible-range}@ R> + hive(from_range_t, R&& rg, const Allocator& = Allocator()); + template<@\exposconcept{container-compatible-range}@ R> + hive(from_range_t, R&& rg, hive_limits block_limits, const Allocator& = Allocator()); + hive(const hive& x); + hive(hive&&) noexcept; + hive(const hive& x, const type_identity_t& alloc); + hive(hive&&, const type_identity_t& alloc); + hive(initializer_list il, const Allocator& = Allocator()); + hive(initializer_list il, hive_limits block_limits, const Allocator& = Allocator()); + ~hive(); + + hive& operator=(const hive& x); + hive& operator=(hive&& x) + noexcept(allocator_traits::propagate_on_container_move_assignment::value || + allocator_traits::is_always_equal::value); + hive& operator=(initializer_list); + template + void assign(InputIterator first, InputIterator last); + template<@\exposconcept{container-compatible-range}@ R> + void assign_range(R&& rg); + void assign(size_type n, const T& t); + void assign(initializer_list); + allocator_type get_allocator() const noexcept; + + // iterators + iterator begin() noexcept; + const_iterator begin() const noexcept; + iterator end() noexcept; + const_iterator end() const noexcept; + reverse_iterator rbegin() noexcept; + const_reverse_iterator rbegin() const noexcept; + reverse_iterator rend() noexcept; + const_reverse_iterator rend() const noexcept; + const_iterator cbegin() const noexcept; + const_iterator cend() const noexcept; + const_reverse_iterator crbegin() const noexcept; + const_reverse_iterator crend() const noexcept; + + // \ref{hive.capacity}, capacity + bool empty() const noexcept; + size_type size() const noexcept; + size_type max_size() const noexcept; + size_type capacity() const noexcept; + void reserve(size_type n); + void shrink_to_fit(); + void trim_capacity() noexcept; + void trim_capacity(size_type n) noexcept; + constexpr hive_limits block_capacity_limits() const noexcept; + static constexpr hive_limits block_capacity_default_limits() noexcept; + static constexpr hive_limits block_capacity_hard_limits() noexcept; + void reshape(hive_limits block_limits); + + // \ref{hive.modifiers}, modifiers + template iterator emplace(Args&&... args); + template iterator emplace_hint(const_iterator hint, Args&&... args); + iterator insert(const T& x); + iterator insert(T&& x); + iterator insert(const_iterator hint, const T& x); + iterator insert(const_iterator hint, T&& x); + void insert(initializer_list il); + template<@\exposconcept{container-compatible-range}@ R> + void insert_range(R&& rg); + template + void insert(InputIterator first, InputIterator last); + void insert(size_type n, const T& x); + + iterator erase(const_iterator position); + iterator erase(const_iterator first, const_iterator last); + void swap(hive&) + noexcept(allocator_traits::propagate_on_container_swap::value || + allocator_traits::is_always_equal::value); + void clear() noexcept; + + // \ref{hive.operations}, hive operations + void splice(hive& x); + void splice(hive&& x); + template> + size_type unique(BinaryPredicate binary_pred = BinaryPredicate()); + + template> + void sort(Compare comp = Compare()); + + iterator get_iterator(const_pointer p) noexcept; + const_iterator get_iterator(const_pointer p) const noexcept; + + private: + hive_limits @\exposid{current-limits}@ = @\impdef@; // \expos + }; + + template> + hive(InputIterator, InputIterator, Allocator = Allocator()) + -> hive<@\exposid{iter-value-type}@, Allocator>; + + template> + hive(InputIterator, InputIterator, hive_limits block_limits, Allocator = Allocator()) + -> hive<@\exposid{iter-value-type}@, block_limits, Allocator>; + + template>> + hive(from_range_t, R&&, Allocator = Allocator()) + -> hive, Allocator>; + + template>> + hive(from_range_t, R&&, hive_limits block_limits, Allocator = Allocator()) + -> hive, block_limits, Allocator>; +} +\end{codeblock} + +\rSec3[hive.cons]{Constructors, copy, and assignment} + +\indexlibraryctor{hive}% +\begin{itemdecl} +constexpr explicit hive(const Allocator&) noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs an empty \tcode{hive}, using the specified allocator. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +constexpr hive(hive_limits block_limits, const Allocator&); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs an empty \tcode{hive}, using the specified allocator. +Initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +explicit hive(size_type n, const Allocator& = Allocator()); +hive(size_type n, hive_limits block_limits, const Allocator& = Allocator()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{DefaultInsertable} into \tcode{hive}. + +\pnum +\effects +Constructs a \tcode{hive} with \tcode{n} default-inserted elements, +using the specified allocator. +If the second overload is called, +also initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Linear in \tcode{n}. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +hive(size_type n, const T& value, const Allocator& = Allocator()); +hive(size_type n, const T& value, hive_limits block_limits, const Allocator& = Allocator()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{hive}. + +\pnum +\effects +Constructs a \tcode{hive} with \tcode{n} copies of \tcode{value}, +using the specified allocator. +If the second overload is called, +also initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Linear in \tcode{n}. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +template + hive(InputIterator first, InputIterator last, const Allocator& = Allocator()); +template + hive(InputIterator first, InputIterator last, hive_limits block_limits, + const Allocator& = Allocator()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs a \tcode{hive} equal to the range \range{first}{last}, +using the specified allocator. +If the second overload is called, +also initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Linear in \tcode{distance(first, last)}. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +template<@\exposconcept{container-compatible-range}@ R> + hive(from_range_t, R&& rg, const Allocator& = Allocator()); +template<@\exposconcept{container-compatible-range}@ R> + hive(from_range_t, R&& rg, hive_limits block_limits, const Allocator& = Allocator()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Constructs a \tcode{hive} object with the elements of the range \tcode{rg}, +using the specified allocator. +If the second overload is called, +also initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Linear in \tcode{ranges::distance(rg)}. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +hive(const hive& x); +hive(const hive& x, const type_identity_t& alloc); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{hive}. + +\pnum +\effects +Constructs a \tcode{hive} object with the elements of \tcode{x}. +If the second overload is called, uses \tcode{alloc}. +Initializes \exposid{current-limits} with \tcode{x.\exposid{current-limits}}. + +\pnum +\complexity +Linear in \tcode{x.size()}. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +hive(hive&& x); +hive(hive&& x, const type_identity_t& alloc); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +For the second overload, +when \tcode{allocator_traits::is_always_equal::value} is \tcode{false}, +\tcode{T} meets the \oldconcept{MoveInsertable} requirements. + +\pnum +\effects +When the first overload is called, or +the second overload is called and +\tcode{alloc == x.get_allocator()} is \tcode{true}, +\exposid{current-limits} is set to \tcode{x.\exposid{current-limits}} and +each element block is moved from \tcode{x} into \tcode{*this}. +Pointers and references to the elements of \tcode{x} now refer to +those same elements but as members of \tcode{*this}. +Iterators referring to the elements of \tcode{x} +will continue to refer to their elements, +but they now behave as iterators into \tcode{*this}. + +If the second overload is called and +\tcode{alloc == x.get_allocator()} is \tcode{false}, +each element in \tcode{x} is moved into \tcode{*this}. +References, pointers and iterators referring to the elements of \tcode{x}, as well as the past-the-end iterator of \tcode{x}, are invalidated. + +\pnum +\ensures +\tcode{x.empty()} is \tcode{true}. + +\pnum +\complexity +If the second overload is called and +\tcode{alloc == x.get_allocator()} is \tcode{false}, linear in \tcode{x.size()}. +Otherwise constant. +\end{itemdescr} + +\indexlibraryctor{hive}% +\begin{itemdecl} +hive(initializer_list il, const Allocator& = Allocator()); +hive(initializer_list il, hive_limits block_limits, const Allocator& = Allocator()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{hive}. + +\pnum +\effects +Constructs a \tcode{hive} object with the elements of \tcode{il}, +using the specified allocator. +If the second overload is called, +also initializes \exposid{current-limits} with \tcode{block_limits}. + +\pnum +\complexity +Linear in \tcode{il.size()}. +\end{itemdescr} + +\indexlibrarymember{operator=}{hive}% +\begin{itemdecl} +hive& operator=(const hive& x); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{hive} and +\oldconcept{CopyAssignable}. + +\pnum +\effects +All elements in \tcode{*this} are either copy-assigned to, or destroyed. +All elements in \tcode{x} are copied into \tcode{*this}. +\begin{note} +\exposid{current-limits} is unchanged. +\end{note} + +\pnum +\complexity +Linear in \tcode{size() + x.size()}. +\end{itemdescr} + +\indexlibrarymember{operator=}{hive}% +\begin{itemdecl} +hive& operator=(hive&& x) + noexcept(allocator_traits::propagate_on_container_move_assignment::value || + allocator_traits::is_always_equal::value); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +When +\begin{codeblock} +(allocator_traits::propagate_on_container_move_assignment::value || + allocator_traits::is_always_equal::value) +\end{codeblock} +is \tcode{false}, +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{hive} and +\oldconcept{MoveAssignable}. + +\pnum +\effects +Each element in \tcode{*this} is either move-assigned to, or destroyed. +When +\begin{codeblock} +(allocator_traits::propagate_on_container_move_assignment::value || + get_allocator() == x.get_allocator()) +\end{codeblock} +is \tcode{true}, +\exposid{current-limits} is set to \tcode{x.\exposid{current-limits}} and +each element block is moved from \tcode{x} into \tcode{*this}. +Pointers and references to the elements of \tcode{x} +now refer to those same elements but as members of \tcode{*this}. +Iterators referring to the elements of \tcode{x} +will continue to refer to their elements, +but they now behave as iterators into \tcode{*this}, not into \tcode{x}. + +When +\begin{codeblock} +(allocator_traits::propagate_on_container_move_assignment::value || + get_allocator() == x.get_allocator()) +\end{codeblock} +is \tcode{false}, +each element in \tcode{x} is moved into \tcode{*this}. +References, pointers and iterators referring to the elements of \tcode{x}, +as well as the past-the-end iterator of \tcode{x}, are invalidated. + +\pnum +\ensures +\tcode{x.empty()} is \tcode{true}. + +\pnum +\complexity +Linear in \tcode{size()}. +If +\begin{codeblock} +(allocator_traits::propagate_on_container_move_assignment::value || + get_allocator() == x.get_allocator()) +\end{codeblock} +is \tcode{true}, also linear in \tcode{x.size()}. +\end{itemdescr} + +\rSec3[hive.capacity]{Capacity} + +\indexlibrarymember{capacity}{hive}% +\begin{itemdecl} +size_type capacity() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +The total number of elements that \tcode{*this} can hold +without requiring allocation of more element blocks. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibrarymember{reserve}{hive}% +\begin{itemdecl} +void reserve(size_type n); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +If \tcode{n <= capacity()} is \tcode{true}, there are no effects. +Otherwise increases \tcode{capacity()} by allocating reserved blocks. + +\pnum +\ensures +\tcode{capacity() >= n} is \tcode{true}. + +\pnum +\throws +\tcode{length_error} if \tcode{n > max_size()}, +as well as any exceptions thrown by the allocator. + +\pnum +\complexity +It does not change the size of the sequence and +takes at most linear time in the number of reserved blocks allocated. + +\pnum +\remarks +All references, pointers, and iterators referring to elements in \tcode{*this}, +as well as the past-the-end iterator, remain valid. +\end{itemdescr} + +\indexlibrarymember{shrink_to_fit}{hive}% +\begin{itemdecl} +void shrink_to_fit(); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{hive}. + +\pnum +\effects +\tcode{shrink_to_fit} is a non-binding request +to reduce \tcode{capacity()} to be closer to \tcode{size()}. +\begin{note} +The request is non-binding +to allow latitude for implementation-specific optimizations. +\end{note} +It does not increase \tcode{capacity()}, but may reduce \tcode{capacity()}. +It may reallocate elements. +If \tcode{capacity()} is already equal to \tcode{size()}, there are no effects. +If an exception is thrown during allocation of a new element block, +\tcode{capacity()} may be reduced and reallocation may occur. +Otherwise if an exception is thrown, the effects are unspecified. + +\pnum +\complexity +If reallocation happens, linear in the size of the sequence. + +\pnum +\remarks +If reallocation happens, +the order of the elements in \tcode{*this} may change and +all references, pointers, and iterators +referring to the elements in \tcode{*this}, +as well as the past-the-end iterator, are invalidated. +\end{itemdescr} + +\indexlibrarymember{trim_capacity}{hive}% +\begin{itemdecl} +void trim_capacity() noexcept; +void trim_capacity(size_type n) noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +For the first overload, all reserved blocks are deallocated, and +\tcode{capacity()} is reduced accordingly. +For the second overload, \tcode{capacity()} is reduced to no less than \tcode{n}. + +\pnum +\complexity +Linear in the number of reserved blocks deallocated. + +\pnum +\remarks +All references, pointers, and iterators referring to elements in \tcode{*this}, +as well as the past-the-end iterator, remain valid. +\end{itemdescr} + +\indexlibrarymember{block_capacity_limits}{hive}% +\begin{itemdecl} +constexpr hive_limits block_capacity_limits() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\exposid{current-limits}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibrarymember{block_capacity_default_limits}{hive}% +\begin{itemdecl} +static constexpr hive_limits block_capacity_default_limits() noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +A \tcode{hive_limits} struct +with the \tcode{min} and \tcode{max} members set to +the implementation's default limits. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibrarymember{block_capacity_hard_limits}{hive}% +\begin{itemdecl} +static constexpr hive_limits block_capacity_hard_limits() noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +A \tcode{hive_limits} struct +with the \tcode{min} and \tcode{max} members set to +the implementation's hard limits. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\indexlibrarymember{reshape}{hive}% +\begin{itemdecl} +void reshape(hive_limits block_limits); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{hive}. + +\pnum +\effects +For any active blocks not within the bounds of \tcode{block_limits}, +the elements within those active blocks are reallocated +to new or existing element blocks which are within the bounds. +Any element blocks not within the bounds of \tcode{block_limits} +are deallocated. +If an exception is thrown during allocation of a new element block, +\tcode{capacity()} may be reduced, +reallocation may occur, and +\exposid{current-limits} may be assigned +a value other than \tcode{block_limits}. +Otherwise \tcode{block_limits} is assigned to \exposid{current-limits}. +If any other exception is thrown the effects are unspecified. + +\pnum +\ensures +\tcode{size()} is unchanged. + +\pnum +\complexity +Linear in the number of element blocks in \tcode{*this}. +If reallocation happens, also linear in the number of elements reallocated. + +\pnum +\remarks +This operation may change \tcode{capacity()}. +If reallocation happens, the order of the elements in \tcode{*this} may change. +Reallocation invalidates all references, pointers, and iterators +referring to the elements in \tcode{*this}, +as well as the past-the-end iterator. +\begin{note} +If no reallocation happens, they remain valid. +\end{note} +\end{itemdescr} + +\rSec3[hive.modifiers]{Modifiers} + +\indexlibrarymember{emplace}{hive}% +\begin{itemdecl} +template iterator emplace(Args&&... args); +template iterator emplace_hint(const_iterator hint, Args&&... args); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceConstructible} into \tcode{hive} from \tcode{args}. + +\pnum +\effects +Inserts an object of type \tcode{T} +constructed with \tcode{std::forward(args)...}. +The \tcode{hint} parameter is ignored. +If an exception is thrown, there are no effects. +\begin{note} +\tcode{args} can directly or indirectly refer to a value in \tcode{*this}. +\end{note} + +\pnum +\returns +An iterator that points to the new element. + +\pnum +\complexity +Constant. Exactly one object of type \tcode{T} is constructed. + +\pnum +\remarks +Invalidates the past-the-end iterator. +\end{itemdescr} + +\indexlibrarymember{insert}{hive}% +\begin{itemdecl} +iterator insert(const T& x); +iterator insert(const_iterator hint, const T& x); +iterator insert(T&& x); +iterator insert(const_iterator hint, T&& x); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: \tcode{return emplace(std::forward(x));} +\begin{note} +The \tcode{hint} parameter is ignored. +\end{note} +\end{itemdescr} + +\indexlibrarymember{insert}{hive}% +\begin{itemdecl} +void insert(initializer_list rg); +template<@\exposconcept{container-compatible-range}@ R> + void insert_range(R&& rg); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{EmplaceInsertable} into \tcode{hive} +from \tcode{*ranges::begin(rg)}. +\tcode{rg} and \tcode{*this} do not overlap. + +\pnum +\effects +Inserts copies of elements in \tcode{rg}. +Each iterator in the range \tcode{rg} is dereferenced exactly once. + +\pnum +\complexity +Linear in the number of elements inserted. +Exactly one object of type \tcode{T} is constructed for each element inserted. + +\pnum +\remarks +If an element is inserted, invalidates the past-the-end iterator. +\end{itemdescr} + +\indexlibrarymember{insert}{hive}% +\begin{itemdecl} +void insert(size_type n, const T& x); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{CopyInsertable} into \tcode{hive}. + +\pnum +\effects +Inserts n copies of x. + +\pnum +\complexity +Linear in \tcode{n}. +Exactly one object of type \tcode{T} is constructed for each element inserted. + +\pnum +\remarks +If an element is inserted, invalidates the past-the-end iterator. +\end{itemdescr} + +\indexlibrarymember{insert}{hive}% +\begin{itemdecl} +template + void insert(InputIterator first, InputIterator last); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to \tcode{insert_range(ranges::subrange(first, last))}. +\end{itemdescr} + +\indexlibrarymember{erase}{hive}% +\begin{itemdecl} +iterator erase(const_iterator position); +iterator erase(const_iterator first, const_iterator last); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\complexity +Linear in the number of elements erased. +Additionally, if any active blocks become empty of elements +as a result of the function call, +at worst linear in the number of element blocks. + +\pnum +\remarks +Invalidates references, pointers and iterators +referring to the erased elements. +An erase operation that erases the last element in \tcode{*this} +also invalidates the past-the-end iterator. +\end{itemdescr} + +\indexlibrarymember{swap}{hive}% +\begin{itemdecl} +void swap(hive& x) + noexcept(allocator_traits::propagate_on_container_swap::value || + allocator_traits::is_always_equal::value); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Exchanges the contents, \tcode{capacity()}, and \exposid{current-limits} +of \tcode{*this} with that of \tcode{x}. + +\pnum +\complexity +Constant. +\end{itemdescr} + +\rSec3[hive.operations]{Operations} + +In this subclause, +arguments for a template parameter +named \tcode{Predicate} or \tcode{BinaryPredicate} +shall meet the corresponding requirements in \ref{algorithms.requirements}. +The semantics of \tcode{i + n} and \tcode{i - n}, +where \tcode{i} is an iterator into the \tcode{hive} and \tcode{n} is an integer, +are the same as those of \tcode{next(i, n)} and \tcode{prev(i, n)}, respectively. +For \tcode{sort}, the definitions and requirements in \ref{alg.sorting} apply. + +\indexlibrarymember{splice}{hive}% +\begin{itemdecl} +void splice(hive& x); +void splice(hive&& x); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{get_allocator() == x.get_allocator()} is \tcode{true}. + +\pnum +\effects +If \tcode{addressof(x) == this} is \tcode{true}, +the behavior is erroneous and there are no effects. +Otherwise, inserts the contents of \tcode{x} into \tcode{*this} and +\tcode{x} becomes empty. +Pointers and references to the moved elements of \tcode{x} +now refer to those same elements but as members of \tcode{*this}. +Iterators referring to the moved elements continue to refer to their elements, +but they now behave as iterators into \tcode{*this,} not into \tcode{x}. + +\pnum +\throws +\tcode{length_error} if any of \tcode{x}'s active blocks +are not within the bounds of \exposid{current-limits}. + +\pnum +\complexity +Linear in the sum of +all element blocks in \tcode{x} plus all element blocks in \tcode{*this}. + +\pnum +\remarks +Reserved blocks in \tcode{x} are not transferred into \tcode{*this}. +If \tcode{addressof(x) == this} is \tcode{false}, +invalidates the past-the-end iterator for both \tcode{x} and \tcode{*this}. +\end{itemdescr} + +\indexlibrarymember{unique}{hive}% +\begin{itemdecl} +template> + size_type unique(BinaryPredicate binary_pred = BinaryPredicate()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{binary_pred} is an equivalence relation. + +\pnum +\effects +Erases all but the first element +from every consecutive group of equivalent elements. +That is, for a nonempty \tcode{hive}, +erases all elements referred to by the iterator \tcode{i} +in the range \range{begin() + 1}{end()} +for which \tcode{binary_pred(*i, *(i - 1))} is \tcode{true}. + +\pnum +\returns +The number of elements erased. + +\pnum +\throws +Nothing unless an exception is thrown by the predicate. + +\pnum +\complexity +If \tcode{empty()} is \tcode{false}, +exactly \tcode{size() - 1} applications of the corresponding predicate, +otherwise no applications of the predicate. + +\pnum +\remarks +Invalidates references, pointers, and iterators +referring to the erased elements. +If the last element in \tcode{*this} is erased, +also invalidates the past-the-end iterator. +\end{itemdescr} + +\indexlibrarymember{sort}{hive}% +\begin{itemdecl} +template> + void sort(Compare comp = Compare()); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{T} is \oldconcept{MoveInsertable} into \tcode{hive}, +\oldconcept{MoveAssignable}, and \oldconcept{Swappable}. + +\pnum +\effects +Sorts \tcode{*this} according to the \tcode{comp} function object. +If an exception is thrown, +the order of the elements in \tcode{*this} is unspecified. + +\pnum +\complexity +\bigoh{N \log N} comparisons, where $N$ is \tcode{size()}. + +\pnum +\remarks +May allocate. +References, pointers, and iterators referring to elements in \tcode{*this}, +as well as the past-the-end iterator, may be invalidated. +\begin{note} +Not required to be stable\ref{algorithm.stable}. +\end{note} +\end{itemdescr} + +\indexlibrarymember{get_iterator}{hive}% +\begin{itemdecl} +iterator get_iterator(const_pointer p) noexcept; +const_iterator get_iterator(const_pointer p) const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{p} points to an element in \tcode{*this}. + +\pnum +\returns +An \tcode{iterator} or \tcode{const_iterator} +pointing to the same element as \tcode{p}. + +\pnum +\complexity +Linear in the number of active blocks in \tcode{*this}. +\end{itemdescr} + +\rSec3[hive.erasure]{Erasure} + +\indexlibrarymember{erase}{hive}% +\begin{itemdecl} +template + typename hive::size_type + erase(hive& c, const U& value); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: +\begin{codeblock} +return erase_if(c, [&](auto& elem) { return elem == value; }); +\end{codeblock} +\end{itemdescr} + +\indexlibrarymember{erase_if}{hive}% +\begin{itemdecl} +template + typename hive::size_type + erase_if(hive& c, Predicate pred); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: +\begin{codeblock} +auto original_size = c.size(); +for (auto i = c.begin(), last = c.end(); i != last; ) { + if (pred(*i)) { + i = c.erase(i); + } else { + ++i; + } +} +return original_size - c.size(); +\end{codeblock} +\end{itemdescr} + \rSec2[list.syn]{Header \tcode{} synopsis} \indexheader{list}% diff --git a/source/lib-intro.tex b/source/lib-intro.tex index 5dabc1bcd7..61fcbded40 100644 --- a/source/lib-intro.tex +++ b/source/lib-intro.tex @@ -1230,6 +1230,7 @@ \tcode{} \\ \tcode{} \\ \tcode{} \\ +\tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ diff --git a/source/support.tex b/source/support.tex index b9971694ec..33885de0ac 100644 --- a/source/support.tex +++ b/source/support.tex @@ -700,6 +700,7 @@ #define @\defnlibxname{cpp_lib_hardware_interference_size}@ 201703L // freestanding, also in \libheader{new} #define @\defnlibxname{cpp_lib_has_unique_object_representations}@ 201606L // freestanding, also in \libheader{type_traits} #define @\defnlibxname{cpp_lib_hazard_pointer}@ 202306L // also in \libheader{hazard_pointer} +#define @\defnlibxname{cpp_lib_hive}@ 202502L // also in \libheader{hive} #define @\defnlibxname{cpp_lib_hypot}@ 201603L // also in \libheader{cmath} #define @\defnlibxname{cpp_lib_incomplete_container_elements}@ 201505L // also in \libheader{forward_list}, \libheader{list}, \libheader{vector} From ff6f4a01980264b39aeb836db650d8f1cf80e515 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Wed, 19 Feb 2025 00:16:55 +0100 Subject: [PATCH 2/6] [hive.overview] Replace complex noexcept expression with 'see below' --- source/containers.tex | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index da3f987392..b23121eee6 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -8053,9 +8053,7 @@ ~hive(); hive& operator=(const hive& x); - hive& operator=(hive&& x) - noexcept(allocator_traits::propagate_on_container_move_assignment::value || - allocator_traits::is_always_equal::value); + hive& operator=(hive&& x) noexcept(@\seebelow@); hive& operator=(initializer_list); template void assign(InputIterator first, InputIterator last); @@ -8109,9 +8107,7 @@ iterator erase(const_iterator position); iterator erase(const_iterator first, const_iterator last); - void swap(hive&) - noexcept(allocator_traits::propagate_on_container_swap::value || - allocator_traits::is_always_equal::value); + void swap(hive&) noexcept(@\seebelow@); void clear() noexcept; // \ref{hive.operations}, hive operations From 596982efbcb24e0d2b88457399aff9cd80c5c198 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20K=C3=B6ppe?= Date: Sat, 15 Mar 2025 17:09:21 +0000 Subject: [PATCH 3/6] [hive.overview] Add/fix missing subject "insertion" --- source/containers.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/containers.tex b/source/containers.tex index b23121eee6..f0a9ac65ba 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -7931,7 +7931,7 @@ that provides constant-time insertion and erasure operations. Storage is automatically managed in multiple memory blocks, referred to as \defnx{element blocks}{element block}. -Insertion position is determined by the container, and +Insertion position is determined by the container, and insertion may re-use the memory locations of erased elements. \pnum From e1c18ba08107002925ecc6e5714e837ad6365c22 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Wed, 19 Feb 2025 08:23:12 +0100 Subject: [PATCH 4/6] [hive.cons] Fix condition in move-assignment complexity --- source/containers.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/containers.tex b/source/containers.tex index f0a9ac65ba..d648e9876b 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -8435,7 +8435,7 @@ (allocator_traits::propagate_on_container_move_assignment::value || get_allocator() == x.get_allocator()) \end{codeblock} -is \tcode{true}, also linear in \tcode{x.size()}. +is \tcode{false}, also linear in \tcode{x.size()}. \end{itemdescr} \rSec3[hive.capacity]{Capacity} From d4358a8b58b65fe6d11c547e6098fee9ce31c356 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Thu, 20 Feb 2025 23:12:03 +0100 Subject: [PATCH 5/6] [hive.syn] Fix typos in deduction guides --- source/containers.tex | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index d648e9876b..b05f4c5397 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -8126,21 +8126,21 @@ hive_limits @\exposid{current-limits}@ = @\impdef@; // \expos }; - template> + template>> hive(InputIterator, InputIterator, Allocator = Allocator()) -> hive<@\exposid{iter-value-type}@, Allocator>; - template> - hive(InputIterator, InputIterator, hive_limits block_limits, Allocator = Allocator()) - -> hive<@\exposid{iter-value-type}@, block_limits, Allocator>; + template>> + hive(InputIterator, InputIterator, hive_limits, Allocator = Allocator()) + -> hive<@\exposid{iter-value-type}@, Allocator>; template>> hive(from_range_t, R&&, Allocator = Allocator()) -> hive, Allocator>; template>> - hive(from_range_t, R&&, hive_limits block_limits, Allocator = Allocator()) - -> hive, block_limits, Allocator>; + hive(from_range_t, R&&, hive_limits, Allocator = Allocator()) + -> hive, Allocator>; } \end{codeblock} From f0ca5bc685c4816965efa3bb9858803b2352201f Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Wed, 26 Feb 2025 00:02:18 +0100 Subject: [PATCH 6/6] [hive.overview] Drop reference to optional sequence container requirements std::hive does not provide any of those operations. --- source/containers.tex | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/source/containers.tex b/source/containers.tex index b05f4c5397..a90ee6c011 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -7995,9 +7995,7 @@ A \tcode{hive} also meets the requirements of a reversible container\iref{container.rev.reqmts}, of an allocator-aware container\iref{container.alloc.reqmts}, and -some of the requirements of a sequence container, -including several of -the optional sequence container requirements\iref{sequence.reqmts}. +some of the requirements of a sequence container\iref{sequence.reqmts}. Descriptions are provided here only for operations on \tcode{hive} that are not described in that table or for operations where there is additional semantic information.