cppannotations/annotations/yo/containers/multiset.yo

Like the tt(set), the ti(multiset) class implements a
    hi(sorted collection of value) sorted collection of values. Before
using tt(multiset) containers the header file tthi(set) must be included.

    The main difference between the tt(set) and the tt(multiset) is that the
multiset supports multiple entries of the same value, whereas the set contains
unique values.

The tt(set) and the tt(multiset) have the same set of member functions.  Refer
to section ref(SET) for an overview of the tt(multiset) member functions.
Some member functions, however, behave slightly different than their
counterparts of the tt(set) container. Those members are mentioned here.
    itemization(
        ithtq(count)(size_t count(value))(returns the number of
entries in the multiset associated with the given tt(value).)
        ithtq(erase)(... erase())(erases elements from the set:)
            itemization(
            itt(size_t erase(value)) erases all elements having the given
tt(value). The number of erased elements is returned.
            itt(void erase(pos)) erases the element pointed to by the iterator
tt(pos). Other elements possibly having the same values are not erased.
            itt(void erase(first, beyond)) erases all elements indicated by
the iterator range rangett(first, beyond).
            )

        ithtq(equal_range)
    (pair<multiset::iterator, multiset::iterator> equal_range(value))
        (returns a pair of iterators, being respectively the return values of
tt(lower_bound) and tt(upper_bound), introduced below.  The function provides
a simple means to determine all elements in the tt(multiset) that have the
same tt(values).)
        ithtq(find)(multiset::iterator find(value))(returns an
iterator pointing to the first element having the specified value. If the
element isn't available, tt(end) is returned. The iterator could be
incremented to visit all elements having the given tt(value) until it is
either tt(end), or the iterator doesn't point to `tt(value)' anymore.)
        ithtq(insert)(... insert())(this member function normally succeeds and
returns a emi(multiset::iterator) rather than a tt(pair<multiset::iterator,
bool>) as returned with the tt(set) container. The returned iterator points to
the newly added element.)
    )
    Although the functions tt(lower_bound) and tt(upper_bound) act identically
in the tt(set) and tt(multiset) containers, their operation in a tt(multiset)
deserves some additional attention. With a tt(multiset) container
tt(lower_bound) and tt(upper_bound) produce the same result for non-existing
keys: they both return the first element having a key exceeding the provided
key.

    Here is an example showing the use of various member functions of a
multiset:
    verbinclude(-a examples/multiset.cc)