Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

Class template multimap

boost::container::multimap

Synopsis

// In header: <boost/container/container_fwd.hpp>

template<typename Key, typename T, typename Compare = std::less<Key>, 
         typename Allocator = std::allocator<std::pair<const Key, T> > > 
class multimap {
public:
  // construct/copy/destruct
  multimap();
  explicit multimap(const Compare &, 
                    const allocator_type & = allocator_type());
  template<typename InputIterator> 
    multimap(InputIterator, InputIterator, const Compare & = Compare(), 
             const allocator_type & = allocator_type());
  template<typename InputIterator> 
    multimap(ordered_range_t, InputIterator, InputIterator, 
             const Compare & = Compare(), 
             const allocator_type & = allocator_type());
  multimap(const multimap &);
  multimap(multimap &&);
  multimap(const multimap &, const allocator_type &);
  multimap(multimap &&, const allocator_type &);
  multimap& operator=(const multimap &);
  multimap& operator=(multimap &&);

  // public member functions
  allocator_type get_allocator() const;
  stored_allocator_type & get_stored_allocator();
  const stored_allocator_type & get_stored_allocator() const;
  iterator begin();
  const_iterator begin() const;
  iterator end();
  const_iterator end() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  const_iterator cbegin() const;
  const_iterator cend() const;
  const_reverse_iterator crbegin() const;
  const_reverse_iterator crend() const;
  bool empty() const;
  size_type size() const;
  size_type max_size() const;
  template<class... Args> iterator emplace(Args &&...);
  template<class... Args> iterator emplace_hint(const_iterator, Args &&...);
  iterator insert(const value_type &);
  iterator insert(const nonconst_value_type &);
  iterator insert(nonconst_value_type &&);
  iterator insert(movable_value_type &&);
  iterator insert(const_iterator, const value_type &);
  iterator insert(const_iterator, const nonconst_value_type &);
  iterator insert(const_iterator, nonconst_value_type &&);
  iterator insert(const_iterator, movable_value_type &&);
  template<typename InputIterator> void insert(InputIterator, InputIterator);
  iterator erase(const_iterator);
  size_type erase(const key_type &);
  iterator erase(const_iterator, const_iterator);
  void swap(multimap &);
  void clear();
  key_compare key_comp() const;
  value_compare value_comp() const;
  iterator find(const key_type &);
  const_iterator find(const key_type &) const;
  size_type count(const key_type &) const;
  iterator lower_bound(const key_type &);
  const_iterator lower_bound(const key_type &) const;
  iterator upper_bound(const key_type &);
  const_iterator upper_bound(const key_type &) const;
  std::pair< iterator, iterator > equal_range(const key_type &);
  std::pair< const_iterator, const_iterator > 
  equal_range(const key_type &) const;
};

Description

A multimap is a kind of associative container that supports equivalent keys (possibly containing multiple copies of the same key value) and provides for fast retrieval of values of another type T based on the keys. The multimap class supports bidirectional iterators.

A multimap satisfies all of the requirements of a container and of a reversible container and of an associative container. For a map<Key,T> the key_type is Key and the value_type is std::pair<const Key,T>.

Compare is the ordering function for Keys (e.g. std::less<Key>).

Allocator is the allocator to allocate the value_types (e.g. allocator< std::pair<const Key, T> >).

multimap public construct/copy/destruct

  1. multimap();

    Effects: Default constructs an empty multimap.

    Complexity: Constant.

  2. explicit multimap(const Compare & comp, 
                      const allocator_type & a = allocator_type());

    Effects: Constructs an empty multimap using the specified comparison object and allocator.

    Complexity: Constant.

  3. template<typename InputIterator> 
      multimap(InputIterator first, InputIterator last, 
               const Compare & comp = Compare(), 
               const allocator_type & a = allocator_type());

    Effects: Constructs an empty multimap using the specified comparison object and allocator, and inserts elements from the range [first ,last ).

    Complexity: Linear in N if the range [first ,last ) is already sorted using comp and otherwise N logN, where N is last - first.

  4. template<typename InputIterator> 
      multimap(ordered_range_t, InputIterator first, InputIterator last, 
               const Compare & comp = Compare(), 
               const allocator_type & a = allocator_type());

    Effects: Constructs an empty multimap using the specified comparison object and allocator, and inserts elements from the ordered range [first ,last). This function is more efficient than the normal range creation for ordered ranges.

    Requires: [first ,last) must be ordered according to the predicate.

    Complexity: Linear in N.

  5. multimap(const multimap & x);

    Effects: Copy constructs a multimap.

    Complexity: Linear in x.size().

  6. multimap(multimap && x);

    Effects: Move constructs a multimap. Constructs *this using x's resources.

    Complexity: Constant.

    Postcondition: x is emptied.

  7. multimap(const multimap & x, const allocator_type & a);

    Effects: Copy constructs a multimap.

    Complexity: Linear in x.size().

  8. multimap(multimap && x, const allocator_type & a);

    Effects: Move constructs a multimap using the specified allocator. Constructs *this using x's resources. Complexity: Constant if a == x.get_allocator(), linear otherwise.

    Postcondition: x is emptied.

  9. multimap& operator=(const multimap & x);

    Effects: Makes *this a copy of x.

    Complexity: Linear in x.size().

  10. multimap& operator=(multimap && x);

    Effects: this->swap(x.get()).

    Complexity: Constant.

multimap public member functions

  1. allocator_type get_allocator() const;

    Effects: Returns a copy of the Allocator that was passed to the object's constructor.

    Complexity: Constant.

  2. stored_allocator_type & get_stored_allocator();

    Effects: Returns a reference to the internal allocator.

    Throws: Nothing

    Complexity: Constant.

    Note: Non-standard extension.

  3. const stored_allocator_type & get_stored_allocator() const;

    Effects: Returns a reference to the internal allocator.

    Throws: Nothing

    Complexity: Constant.

    Note: Non-standard extension.

  4. iterator begin();

    Effects: Returns an iterator to the first element contained in the container.

    Throws: Nothing.

    Complexity: Constant.

  5. const_iterator begin() const;

    Effects: Returns a const_iterator to the first element contained in the container.

    Throws: Nothing.

    Complexity: Constant.

  6. iterator end();

    Effects: Returns an iterator to the end of the container.

    Throws: Nothing.

    Complexity: Constant.

  7. const_iterator end() const;

    Effects: Returns a const_iterator to the end of the container.

    Throws: Nothing.

    Complexity: Constant.

  8. reverse_iterator rbegin();

    Effects: Returns a reverse_iterator pointing to the beginning of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  9. const_reverse_iterator rbegin() const;

    Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  10. reverse_iterator rend();

    Effects: Returns a reverse_iterator pointing to the end of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  11. const_reverse_iterator rend() const;

    Effects: Returns a const_reverse_iterator pointing to the end of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  12. const_iterator cbegin() const;

    Effects: Returns a const_iterator to the first element contained in the container.

    Throws: Nothing.

    Complexity: Constant.

  13. const_iterator cend() const;

    Effects: Returns a const_iterator to the end of the container.

    Throws: Nothing.

    Complexity: Constant.

  14. const_reverse_iterator crbegin() const;

    Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  15. const_reverse_iterator crend() const;

    Effects: Returns a const_reverse_iterator pointing to the end of the reversed container.

    Throws: Nothing.

    Complexity: Constant.

  16. bool empty() const;

    Effects: Returns true if the container contains no elements.

    Throws: Nothing.

    Complexity: Constant.

  17. size_type size() const;

    Effects: Returns the number of the elements contained in the container.

    Throws: Nothing.

    Complexity: Constant.

  18. size_type max_size() const;

    Effects: Returns the largest possible size of the container.

    Throws: Nothing.

    Complexity: Constant.

  19. template<class... Args> iterator emplace(Args &&... args);

    Effects: Inserts an object of type T constructed with std::forward<Args>(args)... in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  20. template<class... Args> 
      iterator emplace_hint(const_iterator hint, Args &&... args);

    Effects: Inserts an object of type T constructed with std::forward<Args>(args)... in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  21. iterator insert(const value_type & x);

    Effects: Inserts x and returns the iterator pointing to the newly inserted element.

    Complexity: Logarithmic.

  22. iterator insert(const nonconst_value_type & x);

    Effects: Inserts a new value constructed from x and returns the iterator pointing to the newly inserted element.

    Complexity: Logarithmic.

  23. iterator insert(nonconst_value_type && x);

    Effects: Inserts a new value move-constructed from x and returns the iterator pointing to the newly inserted element.

    Complexity: Logarithmic.

  24. iterator insert(movable_value_type && x);

    Effects: Inserts a new value move-constructed from x and returns the iterator pointing to the newly inserted element.

    Complexity: Logarithmic.

  25. iterator insert(const_iterator position, const value_type & x);

    Effects: Inserts a copy of x in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  26. iterator insert(const_iterator position, const nonconst_value_type & x);

    Effects: Inserts a new value constructed from x in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  27. iterator insert(const_iterator position, nonconst_value_type && x);

    Effects: Inserts a new value move constructed from x in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  28. iterator insert(const_iterator position, movable_value_type && x);

    Effects: Inserts a new value move constructed from x in the container. p is a hint pointing to where the insert should start to search.

    Returns: An iterator pointing to the element with key equivalent to the key of x.

    Complexity: Logarithmic in general, but amortized constant if t is inserted right before p.

  29. template<typename InputIterator> 
      void insert(InputIterator first, InputIterator last);

    Requires: first, last are not iterators into *this.

    Effects: inserts each element from the range [first,last) .

    Complexity: At most N log(size()+N) (N is the distance from first to last)

  30. iterator erase(const_iterator position);

    Effects: Erases the element pointed to by position.

    Returns: Returns an iterator pointing to the element immediately following q prior to the element being erased. If no such element exists, returns end().

    Complexity: Amortized constant time

  31. size_type erase(const key_type & x);

    Effects: Erases all elements in the container with key equivalent to x.

    Returns: Returns the number of erased elements.

    Complexity: log(size()) + count(k)

  32. iterator erase(const_iterator first, const_iterator last);

    Effects: Erases all the elements in the range [first, last).

    Returns: Returns last.

    Complexity: log(size())+N where N is the distance from first to last.

  33. void swap(multimap & x);

    Effects: Swaps the contents of *this and x.

    Throws: Nothing.

    Complexity: Constant.

  34. void clear();

    Effects: erase(a.begin(),a.end()).

    Postcondition: size() == 0.

    Complexity: linear in size().

  35. key_compare key_comp() const;

    Effects: Returns the comparison object out of which a was constructed.

    Complexity: Constant.

  36. value_compare value_comp() const;

    Effects: Returns an object of value_compare constructed out of the comparison object.

    Complexity: Constant.

  37. iterator find(const key_type & x);

    Returns: An iterator pointing to an element with the key equivalent to x, or end() if such an element is not found.

    Complexity: Logarithmic.

  38. const_iterator find(const key_type & x) const;

    Returns: Allocator const iterator pointing to an element with the key equivalent to x, or end() if such an element is not found.

    Complexity: Logarithmic.

  39. size_type count(const key_type & x) const;

    Returns: The number of elements with key equivalent to x.

    Complexity: log(size())+count(k)

  40. iterator lower_bound(const key_type & x);

    Returns: An iterator pointing to the first element with key not less than k, or a.end() if such an element is not found.

    Complexity: Logarithmic

  41. const_iterator lower_bound(const key_type & x) const;

    Returns: Allocator const iterator pointing to the first element with key not less than k, or a.end() if such an element is not found.

    Complexity: Logarithmic

  42. iterator upper_bound(const key_type & x);

    Returns: An iterator pointing to the first element with key not less than x, or end() if such an element is not found.

    Complexity: Logarithmic

  43. const_iterator upper_bound(const key_type & x) const;

    Returns: Allocator const iterator pointing to the first element with key not less than x, or end() if such an element is not found.

    Complexity: Logarithmic

  44. std::pair< iterator, iterator > equal_range(const key_type & x);

    Effects: Equivalent to std::make_pair(this->lower_bound(k), this->upper_bound(k)).

    Complexity: Logarithmic

  45. std::pair< const_iterator, const_iterator > 
    equal_range(const key_type & x) const;

    Effects: Equivalent to std::make_pair(this->lower_bound(k), this->upper_bound(k)).

    Complexity: Logarithmic


PrevUpHomeNext