STD::MULTISET(3cxx)

📦
version 14-20240412 · 23 versions
, in ubuntu noble

std::multiset — part 1 of 4, bestie 💅

Okay so this is the std::multiset<...mpare, _Alloc >(3cxx) manual page, and we're doing it in four parts. This is part 1, and I'm keeping every single detail because that's the whole assignment. No skipping, no vibes-based summarising, periodt.

🌸 NAME 🌸

std::multiset< _Key, _Compare, _Alloc > — a standard container made up of elements, which can be retrieved in logarithmic time. That's the name section, short and iconic.

✨ SYNOPSIS ✨

First things first, you include this:

#include <set>

Then the page gives you the whole cast. Here we go, bestie.

💅 Public Types

These are the type aliases, exactly as written. No cap, this is the whole list:

  • typedef _Alloc allocator_type
  • typedef _Rep_type::const_iterator const_iterator
  • typedef _Alloc_traits::const_pointer const_pointer
  • typedef _Alloc_traits::const_reference const_reference
  • typedef _Rep_type::const_reverse_iterator const_reverse_iterator
  • typedef _Rep_type::difference_type difference_type
  • typedef _Rep_type::const_iterator iterator
  • typedef _Compare key_compare
  • typedef _Key key_type
  • using node_type = typename _Rep_type::node_type
  • typedef _Alloc_traits::pointer pointer
  • typedef _Alloc_traits::reference reference
  • typedef _Rep_type::const_reverse_iterator reverse_iterator
  • typedef _Rep_type::size_type size_type
  • typedef _Compare value_compare
  • typedef _Key value_type

Yes, iterator is _Rep_type::const_iterator. That's what the page says. I'm not editing the source, I'm just adding sparkle. 🦋

🫶 Public Member Functions

Okay, this is the long part. Where the page gives a description, I'm giving it to you in my voice. Where it gives no description, I'm just giving the exact signature and not inventing extra tea. Every overload is here.

  • multiset ()=default — Default constructor creates no elements.
  • template<typename _InputIterator > multiset (_InputIterator __first, _InputIterator __last) — Builds a multiset from a range.
  • template<typename _InputIterator > multiset (_InputIterator __first, _InputIterator __last, const _Compare &__comp, const allocator_type &__a=allocator_type()) — Builds a multiset from a range.
  • template<typename _InputIterator > multiset (_InputIterator __first, _InputIterator __last, const allocator_type &__a) — Allocator-extended range constructor.
  • multiset (const _Compare &__comp, const allocator_type &__a=allocator_type()) — Creates a multiset with no elements.
  • multiset (const allocator_type &__a) — Allocator-extended default constructor.
  • multiset (const multiset &)=default — Multiset copy constructor.
  • multiset (const multiset &__m, const __type_identity_t< allocator_type > &__a) — Allocator-extended copy constructor.
  • multiset (initializer_list< value_type > __l, const _Compare &__comp=_Compare(), const allocator_type &__a=allocator_type()) — Builds a multiset from an initializer_list.
  • multiset (initializer_list< value_type > __l, const allocator_type &__a) — Allocator-extended initialier-list constructor.
  • multiset (multiset &&)=default — Multiset move constructor.
  • multiset (multiset &&__m, const __type_identity_t< allocator_type > &__a) noexcept(is_nothrow_copy_constructible< _Compare >::value &&_Alloc_traits::_S_always_equal()) — Allocator-extended move constructor.
  • ~multiset ()=default
  • iterator begin () const noexcept
  • iterator cbegin () const noexcept
  • iterator cend () const noexcept
  • void clear () noexcept
  • reverse_iterator crbegin () const noexcept
  • reverse_iterator crend () const noexcept
  • template<typename... _Args> iterator emplace (_Args &&... __args) — Builds and inserts an element into the multiset.
  • template<typename... _Args> iterator emplace_hint (const_iterator __pos, _Args &&... __args) — Builds and inserts an element into the multiset.
  • bool empty () const noexcept — Returns true if the set is empty.
  • iterator end () const noexcept
  • size_type erase (const key_type &__x) — Erases elements according to the provided key.
  • _GLIBCXX_ABI_TAG_CXX11 iterator erase (const_iterator __first, const_iterator __last) — Erases a [first,last) range of elements from a multiset.
  • _GLIBCXX_ABI_TAG_CXX11 iterator erase (const_iterator __position) — Erases an element from a multiset.
  • node_type extract (const key_type &__x) — Extract a node.
  • node_type extract (const_iterator __pos) — Extract a node.
  • allocator_type get_allocator () const noexcept — Returns the memory allocation object.
  • template<typename _InputIterator > void insert (_InputIterator __first, _InputIterator __last) — A template function that tries to insert a range of elements.
  • iterator insert (const value_type &__x) — Inserts an element into the multiset.
  • iterator insert (const_iterator __hint, node_type &&__nh) — Re-insert an extracted node.
  • iterator insert (const_iterator __position, const value_type &__x) — Inserts an element into the multiset.
  • iterator insert (const_iterator __position, value_type &&__x)
  • void insert (initializer_list< value_type > __l) — Attempts to insert a list of elements into the multiset.
  • iterator insert (node_type &&__nh) — Re-insert an extracted node.
  • iterator insert (value_type &&__x)
  • key_compare key_comp () const — Returns the comparison object.
  • size_type max_size () const noexcept — Returns the maximum size of the set.
  • template<typename _Compare1 > void merge (multiset< _Key, _Compare1, _Alloc > &&__source)
  • template<typename _Compare1 > void merge (multiset< _Key, _Compare1, _Alloc > &__source)
  • template<typename _Compare1 > void merge (set< _Key, _Compare1, _Alloc > &&__source)
  • template<typename _Compare1 > void merge (set< _Key, _Compare1, _Alloc > &__source)
  • multiset & operator= (const multiset &)=default — Multiset assignment operator.
  • multiset & operator= (initializer_list< value_type > __l) — Multiset list assignment operator.
  • multiset & operator= (multiset &&)=default — Move assignment operator.
  • reverse_iterator rbegin () const noexcept
  • reverse_iterator rend () const noexcept
  • size_type size () const noexcept — Returns the size of the set.
  • void swap (multiset &__x) noexcept(/*conditional */) — Swaps data with another multiset.
  • value_compare value_comp () const — Returns the comparison object.

And then the page has this indented lookup block, and I'm putting it right here because it's still member functions and we are not losing anybody:

  • size_type count (const key_type &__x) const — Finds the number of elements with given key.
  • template<typename _Kt > auto count (const _Kt &__x) const -> decltype(_M_t._M_count_tr(__x)) — Finds the number of elements with given key.
  • bool contains (const key_type &__x) const — Finds whether an element with the given key exists.
  • template<typename _Kt > auto contains (const _Kt &__x) const -> decltype(_M_t._M_find_tr(__x), void(), true) — Finds whether an element with the given key exists.
  • iterator find (const key_type &__x) — Tries to locate an element in a set.
  • const_iterator find (const key_type &__x) const — Tries to locate an element in a set.
  • template<typename _Kt > auto find (const _Kt &__x) -> decltype(iterator{_M_t._M_find_tr(__x)}) — Tries to locate an element in a set.
  • template<typename _Kt > auto find (const _Kt &__x) const -> decltype(const_iterator{_M_t._M_find_tr(__x)}) — Tries to locate an element in a set.
  • iterator lower_bound (const key_type &__x) — Finds the beginning of a subsequence matching given key.
  • const_iterator lower_bound (const key_type &__x) const — Finds the beginning of a subsequence matching given key.
  • template<typename _Kt > auto lower_bound (const _Kt &__x) -> decltype(iterator(_M_t._M_lower_bound_tr(__x))) — Finds the beginning of a subsequence matching given key.
  • template<typename _Kt > auto lower_bound (const _Kt &__x) const -> decltype(iterator(_M_t._M_lower_bound_tr(__x))) — Finds the beginning of a subsequence matching given key.
  • iterator upper_bound (const key_type &__x) — Finds the end of a subsequence matching given key.
  • const_iterator upper_bound (const key_type &__x) const — Finds the end of a subsequence matching given key.
  • template<typename _Kt > auto upper_bound (const _Kt &__x) -> decltype(iterator(_M_t._M_upper_bound_tr(__x))) — Finds the end of a subsequence matching given key.
  • template<typename _Kt > auto upper_bound (const _Kt &__x) const -> decltype(iterator(_M_t._M_upper_bound_tr(__x))) — Finds the end of a subsequence matching given key.
  • std::pair< iterator, iterator > equal_range (const key_type &__x) — Finds a subsequence matching given key.
  • std::pair< const_iterator, const_iterator > equal_range (const key_type &__x) const — Finds a subsequence matching given key.
  • template<typename _Kt > auto equal_range (const _Kt &__x) -> decltype(pair< iterator, iterator >(_M_t._M_equal_range_tr(__x))) — Finds a subsequence matching given key.
  • template<typename _Kt > auto equal_range (const _Kt &__x) const -> decltype(pair< iterator, iterator >(_M_t._M_equal_range_tr(__x))) — Finds a subsequence matching given key.
Yes, that last const template equal_range still says pair< iterator, iterator > in the decltype. I'm copying it exactly, bestie. No "fixing" the source. 💀

👑 Friends

The VIP list, AKA the friend functions. Exact signatures only:

  • template<typename _K1 , typename _C1 , typename _A1 > bool operator< (const multiset< _K1, _C1, _A1 > &, const multiset< _K1, _C1, _A1 > &)
  • template<typename _K1 , typename _C1 , typename _A1 > bool operator== (const multiset< _K1, _C1, _A1 > &, const multiset< _K1, _C1, _A1 > &)
  • template<typename , typename > struct std::_Rb_tree_merge_helper

💖 Detailed Description 💖

The page literally shows this declaration, quote and all:

template<typename _Key, typename _Compare = std::less<_Key>, typename _Alloc = std::allocator<_Key>>
class std::multiset< _Key, _Compare, _Alloc >"A standard container made up of elements, which can be retrieved in logarithmic time.
That dangling quote is literally on the page. I'm preserving it like a museum piece. Museum rules, bestie. 🎀

Since: C++98

Template Parameters

  • _Key — Type of key objects.
  • _Compare — Comparison function object type, defaults to less<_Key>.
  • _Alloc — Allocator type, defaults to allocator<_Key>.

It meets the requirements of a container, a reversible container, and an associative container (using equivalent keys). For a multiset<Key> the key_type and value_type are Key.

Multisets support bidirectional iterators.

The private tree data is declared exactly the same way for set and multiset; the distinction is made entirely in how the tree functions are called (*_unique versus *_equal, same as the standard).

🛠️ Constructor & Destructor Documentation 🛠️

okay so construction time, bestie 🚧 this whole section is literally how you bring a multiset into existence (and how you clean it up). every signature is here, every default, every [inline], [explicit], [noexcept], no cap 💅

🍼 default constructor: multiset () [default]

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset () [default]

Default constructor creates no elements. empty. blank slate. iconic ✨

🎀 comparator + allocator constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (const _Compare & __comp, const allocator_type & __a = allocator_type()) [inline],  [explicit]

Creates a multiset with no elements.

Parameters

  • __comp — Comparator to use.
  • __a — An allocator object.

🦋 range constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _InputIterator > std::multiset< _Key, _Compare, _Alloc >::multiset (_InputIterator __first, _InputIterator __last) [inline]

Builds a multiset from a range.

Parameters

  • __first — An input iterator.
  • __last — An input iterator.

Create a multiset consisting of copies of the elements from [first,last). This is linear in N if the range is already sorted, and NlogN otherwise (where N is distance(__first,__last)).

🌸 range constructor + comparator + allocator

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _InputIterator > std::multiset< _Key, _Compare, _Alloc >::multiset (_InputIterator __first, _InputIterator __last, const _Compare & __comp, const allocator_type & __a = allocator_type()) [inline]

Builds a multiset from a range.

Parameters

  • __first — An input iterator.
  • __last — An input iterator.
  • __comp — A comparison functor.
  • __a — An allocator object.

Create a multiset consisting of copies of the elements from [__first,__last). This is linear in N if the range is already sorted, and NlogN otherwise (where N is distance(__first,__last)).

💖 copy constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (const multiset< _Key, _Compare, _Alloc > &) [default]

Multiset copy constructor. Whether the allocator is copied depends on the allocator traits. yes bestie, the allocator lore is real 🫶

🔥 move constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (multiset< _Key, _Compare, _Alloc > &&) [default]

Multiset move constructor. The newly-created multiset contains the exact contents of the moved instance. The moved instance is a valid, but unspecified multiset.

🎀 initializer_list constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (initializer_list< value_type > __l, const _Compare & __comp = _Compare(), const allocator_type & __a = allocator_type()) [inline]

Builds a multiset from an initializer_list.

Parameters

  • __l — An initializer_list.
  • __comp — A comparison functor.
  • __a — An allocator object.

Create a multiset consisting of copies of the elements from the list. This is linear in N if the list is already sorted, and NlogN otherwise (where N is __l.size()).

🧚 allocator-extended default constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (const allocator_type & __a) [inline],  [explicit]

Allocator-extended default constructor.

🐚 allocator-extended copy constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (const multiset< _Key, _Compare, _Alloc > & __m, const __type_identity_t< allocator_type > & __a) [inline]

Allocator-extended copy constructor.

🌈 allocator-extended move constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (multiset< _Key, _Compare, _Alloc > && __m, const __type_identity_t< allocator_type > & __a) [inline],  [noexcept]

Allocator-extended move constructor.

🍓 allocator-extended initializer-list constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::multiset (initializer_list< value_type > __l, const allocator_type & __a) [inline]

Allocator-extended initialier-list constructor. (yes, “initialier” is literally how it’s written here, bestie, we’re keeping it 💀)

🦋 allocator-extended range constructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _InputIterator > std::multiset< _Key, _Compare, _Alloc >::multiset (_InputIterator __first, _InputIterator __last, const allocator_type & __a) [inline]

Allocator-extended range constructor.

💀 destructor

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> std::multiset< _Key, _Compare, _Alloc >::~multiset () [default]

The dtor only erases the elements, and note that if the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility. read that again bestie, it’s important 👀

✨ Member Function Documentation ✨

okay so now the actual member functions. every overload, every return, every “hint” note, all of it. let’s go 🫶

🌀 begin () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::begin () const [inline],  [noexcept]

Returns a read-only (constant) iterator that points to the first element in the multiset. Iteration is done in ascending order according to the keys.

🎀 cbegin () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::cbegin () const [inline],  [noexcept]

Returns a read-only (constant) iterator that points to the first element in the multiset. Iteration is done in ascending order according to the keys.

🦋 cend () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::cend () const [inline],  [noexcept]

Returns a read-only (constant) iterator that points one past the last element in the multiset. Iteration is done in ascending order according to the keys.

🧹 clear ()

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> void std::multiset< _Key, _Compare, _Alloc >::clear () [inline],  [noexcept]

Erases all elements in a multiset. Note that this function only erases the elements, and that if the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility.

🔍 contains (const _Kt & __x) const — template overload

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::contains (const _Kt & __x) const -> decltype(_M_t._M_find_tr(__x), void(), true) [inline]"

Finds whether an element with the given key exists.

Parameters

  • __x — Key of elements to be located.

Returns

True if there is any element with the specified key.

🔎 contains (const key_type & __x) const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> bool std::multiset< _Key, _Compare, _Alloc >::contains (const key_type & __x) const [inline]

Finds whether an element with the given key exists.

Parameters

  • __x — Key of elements to be located.

Returns

True if there is any element with the specified key.

🧮 count (const _Kt & __x) const — template overload

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::count (const _Kt & __x) const -> decltype(_M_t._M_count_tr(__x)) [inline]"

Finds the number of elements with given key.

Parameters

  • __x — Key of elements to be located.

Returns

Number of elements with specified key.

🔢 count (const key_type & __x) const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> size_type std::multiset< _Key, _Compare, _Alloc >::count (const key_type & __x) const [inline]

Finds the number of elements with given key.

Parameters

  • __x — Key of elements to be located.

Returns

Number of elements with specified key.

🌙 crbegin () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> reverse_iterator std::multiset< _Key, _Compare, _Alloc >::crbegin () const [inline],  [noexcept]

Returns a read-only (constant) reverse iterator that points to the last element in the multiset. Iteration is done in descending order according to the keys.

🌌 crend () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> reverse_iterator std::multiset< _Key, _Compare, _Alloc >::crend () const [inline],  [noexcept]

Returns a read-only (constant) reverse iterator that points to the last element in the multiset. Iteration is done in descending order according to the keys.

🛠️ emplace (_Args &&... __args)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename... _Args> iterator std::multiset< _Key, _Compare, _Alloc >::emplace (_Args &&... __args) [inline]

Builds and inserts an element into the multiset.

Parameters

  • __args — Arguments used to generate the element instance to be inserted.

Returns

An iterator that points to the inserted element.

This function inserts an element into the multiset. Contrary to a std::set the multiset does not rely on unique keys and thus multiple copies of the same element can be inserted.

Insertion requires logarithmic time.

🪄 emplace_hint (const_iterator __pos, _Args &&... __args)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename... _Args> iterator std::multiset< _Key, _Compare, _Alloc >::emplace_hint (const_iterator __pos, _Args &&... __args) [inline]

Builds and inserts an element into the multiset.

Parameters

  • __pos — An iterator that serves as a hint as to where the element should be inserted.
  • __args — Arguments used to generate the element instance to be inserted.

Returns

An iterator that points to the inserted element.

This function inserts an element into the multiset. Contrary to a std::set the multiset does not rely on unique keys and thus multiple copies of the same element can be inserted.

Note that the first parameter is only a hint and can potentially improve the performance of the insertion process. A bad hint would cause no gains in efficiency.

See https://gcc.gnu.org/onlinedocs/libstdc++/manual/associative.html#containers.associative.insert_hints for more on hinting.

Insertion requires logarithmic time (if the hint is not taken).

🫧 empty () const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> bool std::multiset< _Key, _Compare, _Alloc >::empty () const [inline],  [noexcept]

Returns true if the set is empty.

🏁 end() — the finish line, but make it constant

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
iterator std::multiset<_Key, _Compare, _Alloc>::end() const [inline], [noexcept]

Returns a read-only (constant) iterator that points one past the last element in the multiset. Like, it's not on an element, it's the little "you've gone too far" marker after the last one bestie 💅

Iteration is done in ascending order according to the keys. So the whole thing walks up, up, up ⬆️✨

Referenced by std::multiset<_Key, _Compare, _Alloc>::extract().

🔍 equal_range() — the fancy-relational overloads

Four of these bad boys, all living their best life. Same energy, different flavors 🍓

Overload one — the _Kt non-const one:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
template<typename _Kt>
auto std::multiset<_Key, _Compare, _Alloc>::equal_range(const _Kt& __x)
    -> decltype(pair<iterator, iterator>(_M_t._M_equal_range_tr(__x)))
    [inline]

Overload two — the _Kt const one:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
template<typename _Kt>
auto std::multiset<_Key, _Compare, _Alloc>::equal_range(const _Kt& __x) const
    -> decltype(pair<iterator, iterator>(_M_t._M_equal_range_tr(__x)))
    [inline]

Overload three — the key_type one:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
std::pair<iterator, iterator>
std::multiset<_Key, _Compare, _Alloc>::equal_range(const key_type& __x) [inline]

Overload four — the key_type const one:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
std::pair<const_iterator, const_iterator>
std::multiset<_Key, _Compare, _Alloc>::equal_range(const key_type& __x) const
    [inline]

Okay and here's what all four of them actually do: finds a subsequence matching given key. Like, the whole little clique of duplicates that share that key 👯‍♀️

Parameters

  • __x — Key to be located.

Returns

Pair of iterators that possibly points to the subsequence matching given key. Two-for-one deal, no cap 🎀

This function is equivalent to

std::make_pair(c.lower_bound(val),
               c.upper_bound(val))

(but is faster than making the calls separately). So like, same result but it's giving efficiency ✨

This function probably only makes sense for multisets. Because lol, a regular set doesn't have duplicates, so there's no "subsequence" to find — it's giving one-element range energy 💀

🧹 erase() — the three flavors of goodbye

Overload one — bye by key:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
size_type std::multiset<_Key, _Compare, _Alloc>::erase(const key_type& __x) [inline]

Erases elements according to the provided key.

Parameters

  • __x — Key of element to be erased.

Returns

The number of elements erased.

This function erases all elements located by the given key from a multiset. Not one, bestie — all of them, every single duplicate, gone, periodt 🫶

⚠️ Heads up: note that this function only erases the element, and that if the element is itself a pointer, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility. So like… if you leak, that's on you, not on us 🙈

Overload two — bye by range:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
_GLIBCXX_ABI_TAG_CXX11
iterator std::multiset<_Key, _Compare, _Alloc>::erase(const_iterator __first,
                                                      const_iterator __last) [inline]

Erases a [first,last) range of elements from a multiset. Slicing out a whole chunk, iconic ✂️

Parameters

  • __first — Iterator pointing to the start of the range to be erased.
  • __last — Iterator pointing to the end of the range to be erased.

Returns

The iterator last.

This function erases a sequence of elements from a multiset. Note that this function only erases the elements, and that if the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility. Same deal as before — the container does not clean up your pointees for you, ngl that's a you problem 💀

Overload three — bye by position:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
_GLIBCXX_ABI_TAG_CXX11
iterator std::multiset<_Key, _Compare, _Alloc>::erase(const_iterator __position) [inline]

Erases an element from a multiset. Just the one. Single-target elimination 🎯

Parameters

  • __position — An iterator pointing to the element to be erased.

Returns

An iterator pointing to the element immediately following position prior to the element being erased. If no such element exists, end() is returned.

This function erases an element, pointed to by the given iterator, from a multiset. Note that this function only erases the element, and that if the element is itself a pointer, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibility. Yeah yeah, same warning, it's important though 🫶

🪄 extract() — pluck a whole node out

Overload one — by key:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
node_type std::multiset<_Key, _Compare, _Alloc>::extract(const key_type& __x) [inline]

Extract a node.

Overload two — by iterator position:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
node_type std::multiset<_Key, _Compare, _Alloc>::extract(const_iterator __pos) [inline]

Extract a node.

References std::multiset<_Key, _Compare, _Alloc>::end().

Like, you're literally pulling the node out of the tree and holding it in your hand. No copy, no allocation, just vibes 🔥

🔎 find() — where is she

Four overloads, all doing the same scavenger hunt, just const-flavored differently 🦋

Overload one — _Kt:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
template<typename _Kt>
auto std::multiset<_Key, _Compare, _Alloc>::find(const _Kt& __x)
    -> decltype(iterator{_M_t._M_find_tr(__x)})
    [inline]

Overload two — _Kt const:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
template<typename _Kt>
auto std::multiset<_Key, _Compare, _Alloc>::find(const _Kt& __x) const
    -> decltype(const_iterator{_M_t._M_find_tr(__x)})
    [inline]

Overload three — key_type:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
iterator std::multiset<_Key, _Compare, _Alloc>::find(const key_type& __x) [inline]

Overload four — key_type const:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
const_iterator std::multiset<_Key, _Compare, _Alloc>::find(const key_type& __x) const [inline]

All four: tries to locate an element in a set. Shoelace-hunt energy 👟

Parameters

  • __x — Element to be located.

Returns

Iterator pointing to sought-after element, or end() if not found. So if she's not there, you get the past-the-end marker and you know it's a wrap 😭

This function takes a key and tries to locate the element with which the key matches. If successful the function returns an iterator pointing to the sought after element. If unsuccessful it returns the past-the-end (end()) iterator.

Lowkey important: with a multiset, find() gives you one of the matching elements — the doc doesn't promise which one — so if you need all of them, that's an equal_range() situation bestie 🎀

🧾 get_allocator() — who's holding the bag

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
allocator_type std::multiset<_Key, _Compare, _Alloc>::get_allocator() const [inline], [noexcept]

Returns the memory allocation object. That's it. That's the whole thing. Your allocator, back in your hands 💜

🧷 insert() — put it in, put it in

Overload one — the range insert:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
template<typename _InputIterator>
void std::multiset<_Key, _Compare, _Alloc>::insert(_InputIterator __first,
                                                   _InputIterator __last) [inline]

A template function that tries to insert a range of elements. Bulk add, no cap 🫶

Parameters

  • __first — Iterator pointing to the start of the range to be inserted.
  • __last — Iterator pointing to the end of the range.

Complexity similar to that of the range constructor. No new surprises, same cost as the constructor flavor ✨

Overload two — the single value one:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
iterator std::multiset<_Key, _Compare, _Alloc>::insert(const value_type& __x) [inline]

Inserts an element into the multiset.

Parameters

  • __x — Element to be inserted.

Returns

An iterator that points to the inserted element.

This function inserts an element into the multiset. Contrary to a std::set the multiset does not rely on unique keys and thus multiple copies of the same element can be inserted. Duplicates welcome, babe. Not like that other container that's all "nooo only one of each" 💀

Insertion requires logarithmic time.

Referenced by std::multiset<_Key, _Compare, _Alloc>::insert().

Overload three — re-insert an extracted node:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
iterator std::multiset<_Key, _Compare, _Alloc>::insert(const_iterator __hint,
                                                       node_type&& __nh) [inline]

Re-insert an extracted node. You took her out with extract(), now put her back — glow-up-and-return arc 🦋

References std::move().

Overload four — hinted insert:

template<typename _Key, typename _Compare = std::less<_Key>,
         typename _Alloc = std::allocator<_Key>>
iterator std::multiset<_Key, _Compare, _Alloc>::insert(const_iterator __position,
                                                       const value_type& __x) [inline]

Inserts an element into the multiset.

Parameters

  • __position — An iterator that serves as a hint as to where the element should be inserted.
  • __x — Element to be inserted.

Returns

An iterator that points to the inserted element.

This function inserts an element into the multiset. Contrary to a std::set the multiset does not rely on unique keys and thus multiple copies of the same element can be inserted. Yeah, say it again for the people in the back — duplicates are always legal here 🌈

And the hint? It's just a hint, bestie. It's not a command, it's a suggestion, the container will do what it wants 💅

okay so picking up right where we left off with the hint-y insert 😌 —

real talk: the first parameter is only a hint. it can potentially improve the performance of the insertion process, but a bad hint would cause no gains in efficiency. none. zero. 💀

peep the docs at https://gcc.gnu.org/onlinedocs/libstdc++/manual/associative.html#containers.associative.insert_hints for more on hinting, and remember: insertion requires logarithmic time (if the hint is not taken).

🎀 insert — the initializer_list glow-up

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> void std::multiset< _Key, _Compare, _Alloc >::insert (initializer_list< value_type > __l) [inline]

Attempts to insert a whole list of elements into the multiset, bestie. like, all at once ✨

Parameters

  • __l — a std::initializer_list<value_type> of elements to be inserted.

Complexity? similar to that of the range constructor, ngl.

References std::multiset< _Key, _Compare, _Alloc >::insert().

🦋 insert — re-inserting an extracted node

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::insert (node_type && __nh) [inline]

Re-insert an extracted node 👑 — giving that node its main character comeback arc.

References std::move().

💅 key_comp

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> key_compare std::multiset< _Key, _Compare, _Alloc >::key_comp () const [inline]

Returns the comparison object. that's it. that's the function 🫶

🔍 lower_bound — the _Kt transparent overload (non-const)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::lower_bound (const _Kt & __x) -> decltype(iterator(_M_t._M_lower_bound_tr(__x)))
      [inline]"

Finds the beginning of a subsequence matching given key 🔥

Parameters

  • __x — key to be located.

Returns — iterator pointing to first element equal to or greater than key, or end().

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful it returns an iterator pointing to the first element that has a greater value than given key, or end() if no such element exists. lowkey so specific and we love that for it 💖

🔍 lower_bound — the _Kt transparent overload (const)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::lower_bound (const _Kt & __x) const -> decltype(iterator(_M_t._M_lower_bound_tr(__x)))
      [inline]"

Finds the beginning of a subsequence matching given key — const edition, same energy 🌸

Parameters

  • __x — key to be located.

Returns — iterator pointing to first element equal to or greater than key, or end().

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful it returns an iterator pointing to the first element that has a greater value than given key, or end() if no such element exists.

🔍 lower_bound — the key_type overload

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::lower_bound (const key_type & __x) [inline]

Finds the beginning of a subsequence matching given key 🎀

Parameters

  • __x — key to be located.

Returns — iterator pointing to first element equal to or greater than key, or end().

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful it returns an iterator pointing to the first element that has a greater value than given key, or end() if no such element exists.

🔍 lower_bound — the key_type overload, but const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> const_iterator std::multiset< _Key, _Compare, _Alloc >::lower_bound (const key_type & __x) const [inline]

Finds the beginning of a subsequence matching given key. yes, again. four overloads, four moods, they all ate 💅

Parameters

  • __x — key to be located.

Returns — iterator pointing to first element equal to or greater than key, or end().

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful it returns an iterator pointing to the first element that has a greater value than given key, or end() if no such element exists.

📏 max_size

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> size_type std::multiset< _Key, _Compare, _Alloc >::max_size () const [inline],  [noexcept]

Returns the maximum size of the set. the ceiling. the limit. the "how big can she get" 🌈

📝 operator= — copy assignment

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> multiset & std::multiset< _Key, _Compare, _Alloc >::operator= (const multiset< _Key, _Compare, _Alloc > &) [default]

Multiset assignment operator 🫶 whether the allocator is copied depends on the allocator traits — so it's giving "it depends", iykyk.

📝 operator= — the initializer_list one

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> multiset & std::multiset< _Key, _Compare, _Alloc >::operator= (initializer_list< value_type > __l) [inline]

Multiset list assignment operator ✨

Parameters

  • __l — an initializer_list.

This function fills a multiset with copies of the elements in the initializer list __l.

heads up bestie: the assignment completely changes the multiset, and the resulting multiset's size is the same as the number of elements assigned. no leftovers, periodt 💀

📝 operator= — move assignment

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> multiset & std::multiset< _Key, _Compare, _Alloc >::operator= (multiset< _Key, _Compare, _Alloc > &&) [default]

Move assignment operator 🔥 she's moving, she's thriving.

🔄 rbegin

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> reverse_iterator std::multiset< _Key, _Compare, _Alloc >::rbegin () const [inline],  [noexcept]

Returns a read-only (constant) reverse iterator that points to the last element in the multiset. Iteration is done in descending order according to the keys — backwards walk, main character energy 👑

🔄 rend

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> reverse_iterator std::multiset< _Key, _Compare, _Alloc >::rend () const [inline],  [noexcept]

Returns a read-only (constant) reverse iterator that points to the last element in the multiset. Iteration is done in descending order according to the keys. (yes, the wording matches rbegin exactly — the docs said what they said, and we respect it 🎀)

📐 size

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> size_type std::multiset< _Key, _Compare, _Alloc >::size () const [inline],  [noexcept]

Returns the size of the set. how many besties are in the building 🦋

🔁 swap

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> void std::multiset< _Key, _Compare, _Alloc >::swap (multiset< _Key, _Compare, _Alloc > & __x) [inline], [noexcept]

Swaps data with another multiset 💫

Parameters

  • __x — a multiset of the same element and allocator types.

This exchanges the elements between two multisets in constant time. (It is only swapping a pointer, an integer, and an instance of the Compare type (which itself is often stateless and empty), so it should be quite fast.) Note that the global std::swap() function is specialized such that std::swap(s1,s2) will feed to this function. iconic ✨

Whether the allocators are swapped depends on the allocator traits.

🔎 upper_bound — _Kt transparent overload (non-const)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::upper_bound (const _Kt & __x) -> decltype(iterator(_M_t._M_upper_bound_tr(__x)))
      [inline]"

Finds the end of a subsequence matching given key 🌸

Parameters

  • __x — key to be located.

Returns — iterator pointing to the first element greater than key, or end().

🔎 upper_bound — _Kt transparent overload (const)

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> template<typename _Kt > auto std::multiset< _Key, _Compare, _Alloc >::upper_bound (const _Kt & __x) const -> decltype(iterator(_M_t._M_upper_bound_tr(__x)))
      [inline]"

Finds the end of a subsequence matching given key, const flavour 💜

Parameters

  • __x — key to be located.

Returns — iterator pointing to the first element greater than key, or end().

🔎 upper_bound — key_type overload

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> iterator std::multiset< _Key, _Compare, _Alloc >::upper_bound (const key_type & __x) [inline]

Finds the end of a subsequence matching given key 🎀

Parameters

  • __x — key to be located.

Returns — iterator pointing to the first element greater than key, or end().

🔎 upper_bound — key_type overload, const

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> const_iterator std::multiset< _Key, _Compare, _Alloc >::upper_bound (const key_type & __x) const [inline]

Finds the end of a subsequence matching given key. last one, we made it 😭

Parameters

  • __x — key to be located.

Returns — iterator pointing to the first element greater than key, or end().

💖 value_comp

template<typename _Key , typename _Compare  = std::less<_Key>, typename _Alloc  = std::allocator<_Key>> value_compare std::multiset< _Key, _Compare, _Alloc >::value_comp () const [inline]

Returns the comparison object. twin of key_comp, different vibe, same job 🫶

👑 Author 👑

Generated automatically by Doxygen for libstdc++ from the source code. not a human, just a robot doing its little documentation dance 🤖✨

aaaand that's the whole page bestie, we're done, go touch grass 🌱💅 the footer on this one is the libstdc++ std::multiset<...> man page tagged (3cxx) — that's the source/version situation, straight from Doxygen's auto-generated output, so no date drama to report, just vibes. mwah 💋🎀🦋

📦 where this page comes from