multiset<T>

The STL multiset represents an arbitrary collection of elements that can be queried for membership. multiset is useful in situations where you need to keep track of a collection of elements and must rapidly look up whether an element is contained.

The multiset allows for duplicates. For a similar container where duplicates are not allowed, use the set.

By default, the multiset uses operator < to order the elements behind the scenes. To use an alternative comparison function, parametrize the multiset as multiset<T, CompareFunctorType>.

Common multiset<T> Member Functions

Constructor: multiset<T> ()

Constructs a new empty multiset.

multiset<int> myMultiset; // Constructs a new, empty multiset.

Constructs a new multiset. This is the default constructor.

pair<iterator, bool> insert(const T &elem)

void insert(InputIterator start, InputIterator stop)

Insert elements pairs

myMultiset.insert(137); // Insert number 137

myMultiset.insert(myOtherContainer.begin(), myOtherContainer.end()); // Insert elements from another iterator range.

Inserts new elements into the multiset. The first version of insert inserts a single element into the multiset. insert returns a pair<iterator, bool>, where the first field of the pair is an iterator to the element and the second field is a bool that is always true.

The second version of this function inserts a range of elements into the multiset.

iterator find(const T &elem)

const_iterator find(const T &elem) const

Return iterator to element

if(myMultiset.find(137) == myMultiset.end()) // 137 is not contained in the multiset

Returns an iterator to the specified element, if it exists, and the result of the multiset's end function otherwise. Note that there may be other values in the multiset with the same value; to obtain them all, use equal_range.

pair<iterator, iterator> equal_range(const T &value)

pair<const_iterator, const_iterator> equal_range(const T &value) const

Get range of all elements with a value.

pair<multiset<int>::iterator, multiset<int>::iterator> equal = myMultiset.equal_range(137);

Returns two iterators delineating all elements with the specified value. If the value isn't contained in the multiset, the two iterators will be equal.

size_type count(const T &elem) const

Return element frequency

int numCopies = myMultiset.count(137); // Returs number of copies of 137 in the multiset.

Returns the number of instances of the specified element in the multiset.

size_type erase(const T &elem)

void erase(iterator elem)

void erase(iterator start, iterator stop)

Remove elements from the multiset

myMultiset.erase(137); // Remove 137 from the multiset

myMultiset.erase(myItr); // Erase the element pointed at by myItr

myMultiset.erase(myMultiset.begin(), myMultiset.end()); // Remove all elements from the container

Removes elements from the multiset. The first version removes the specified element from the multiset, returning the number of elements removed. The second version removes from the multiset the element pointed at by the specified iterator. The third version removes all elements in the range [start, stop) from the multiset.

bool empty() const

Is container empty?

if(myMultiset.empty()) { ... }

Returns whether the multiset is empty. It's considered good practice to call empty to determine whether the multiset is empty rather than checking whether size() returns zero.

void clear()

Empty container

myMultiset.clear();

Removes all elements from the multiset.

size_type size() const

Get container size

int numElems = myMultiset.size();

Returns the number of elements stored in the multiset.

iterator begin()

const_iterator begin() const

Get start iterator.

for(multiset<int>::iterator itr = myMultiset.begin(); /* ... */)

Returns an iterator to the first element in the multiset. Elements in a multiset are stored in sorted order, so the elements returned by iterating over the multiset will be sorted.

iterator end()

const_iterator end() const

Get stop iterator.

for(/* ... */ itr != myMultiset.end(); /* ... */)

Returns an iterator to the element one past the end of the multiset. This iterator does not point to a valid element, so do not dereference it.

Other multiset<T> Member Functions

Constructor: multiset<T> (InputIterator begin, InputIterator end)

Constructs a pre-initialized multiset

multiset<int> myMultiset(otherContainer.begin(), otherContainer.end()); // Copy elements from the range otherContainer.begin(), otherContainer.end() into this multiset

Constructs a new multiset whose elements are equal to the elements defined in the range [begin, end). These iterators need not come from another multiset.

iterator lower_bound(const T &value)

const_iterator lower_bound(const T &value) const

Get first element greater than or equal to

multiset<int>::iterator itr = myMultiset.lower_bound(137); // Get iterator to first element greater than or equal to 137

Returns an iterator to the first element greater than or equal to the parameter. If no elements are found, lower_bound returns end().

iterator upper_bound(const T &value)

const_iterator upper_bound(const T &value) const

Get first element strictly greater than

multiset<int>::iterator itr = myMultiset.upper_bound(137); // Get iterator to first element strictly greater than 137

Returns an iterator to the first element that compares strictly greater than the parameter.

size_type max_size() const

Get maximum container size

multiset<int>::size_type maxElems = myMultiset.max_size()

Returns the maximum number of elements the multiset can hold, which is usually the number of unique memory addresses divided by the size of the elements stored in the container.

BinaryFunction key_comp() const

Get element comparison function

if(myMultiset.keyComp()(myValue1, myValue2)) // Value myValue1 compares less than myValue2

Returns the multiset's internal comparison function used to compare two elements. You can use this function to compare two elements in the same way as the multiset.

BinaryFunction value_comp() const

Get element comparison function

if(myMultiset.keyComp()(myValue1, myValue2)) // Value myValue1 compares less than myValue2

This function is identical to key_comp.

reverse_iterator begin()

const_reverse_iterator begin() const

Get start reverse iterator

for(multiset<int>::reverse_iterator itr = myMultiset.rbegin(); /* ... */)

Returns a reverse_iterator to the last element of the multiset. reverse_iterators are like regular iterators except that they traverse in the opposite direction. Check for the end-of-container condition of reverse_iterators with rend.

reverse_iterator end()

const_reverse_iterator end() const

Get stop reverse iterator.

for(/* ... */ itr != myMultiset.rend(); /* ... */)

Returns a reverse_iterator to the element one element before the start of the array. Like end, the iterator returned by rend does not actually reference a real element of the multiset and you should take care not to actually dereference it.

void swap(multiset<T> &other)

Exchange two multisetss

myMultiset.swap(myOtherMultiset); // Exchanges the two multisets

Exchanges the contents of this multiset and another multiset.