bslstl_multimap_cpp03.h

Go to the documentation of this file.

/// @file bslstl_multimap_cpp03.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslstl_multimap_cpp03.h                                            -*-C++-*-
 
// Automatically generated file.  **DO NOT EDIT**
 
#ifndef INCLUDED_BSLSTL_MULTIMAP_CPP03
#define INCLUDED_BSLSTL_MULTIMAP_CPP03
 
/// @defgroup bslstl_multimap_cpp03 bslstl_multimap_cpp03
/// @brief  Provide C++03 implementation for bslstl_multimap.h
/// @addtogroup bsl
/// @{
/// @addtogroup bslstl
/// @{
/// @addtogroup bslstl_multimap_cpp03
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslstl_multimap_cpp03-purpose"> Purpose</a>
/// * <a href="#bslstl_multimap_cpp03-classes"> Classes </a>
/// * <a href="#bslstl_multimap_cpp03-description"> Description </a>
///
/// # Purpose {#bslstl_multimap_cpp03-purpose}
/// Provide C++03 implementation for bslstl_multimap.h
///
/// # Classes {#bslstl_multimap_cpp03-classes}
/// See bslstl_multimap.h for list of classes
///
/// @see  bslstl_multimap
///
/// # Description {#bslstl_multimap_cpp03-description}
///  This component is the C++03 translation of a C++11 component,
/// generated by the 'sim_cpp11_features.pl' program.  If the original header
/// contains any specially delimited regions of C++11 code, then this generated
/// file contains the C++03 equivalent, i.e., with variadic templates expanded
/// and rvalue-references replaced by 'bslmf::MovableRef' objects.  The header
/// code in this file is designed to be '#include'd into the original header
/// when compiling with a C++03 compiler.  If there are no specially delimited
/// regions of C++11 code, then this header contains no code and is not
/// '#include'd in the original header.
///
/// Generated on Sun Sep  1 05:39:10 2024
/// Command line: sim_cpp11_features.pl bslstl_multimap.h
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslstl
 * @{
 */
/** @addtogroup bslstl_multimap_cpp03
 * @{
 */
 
#ifdef COMPILING_BSLSTL_MULTIMAP_H
 
namespace bsl {
 
                             // ==============
                             // class multimap
                             // ==============
 
/// This class template implements a value-semantic container type holding
/// an ordered sequence of key-value pairs having possibly duplicate keys
/// that provide a mapping from keys (of the template parameter type, `KEY`)
/// to their associated values (of another template parameter type,
/// `VALUE`).
///
/// This class:
/// * supports a complete set of *value-semantic* operations
///   - except for BDEX serialization
/// * is *exception-neutral*
/// * is *alias-safe*
/// * is `const` *thread-safe*
/// For terminology see @ref bsldoc_glossary .
///
/// See @ref bslstl_multimap_cpp03 
template <class KEY,
          class VALUE,
          class COMPARATOR = std::less<KEY>,
          class ALLOCATOR  = allocator<pair<const KEY, VALUE> > >
class multimap {
 
    // PRIVATE TYPES
 
    /// This typedef is an alias for the type of key-value pair objects
    /// maintained by this multimap.
    typedef pair<const KEY, VALUE>                             ValueType;
 
    /// This typedef is an alias for the comparator used internally by this
    /// multimap.
    typedef BloombergLP::bslstl::MapComparator<KEY, VALUE, COMPARATOR>
                                                               Comparator;
 
    /// This typedef is an alias for the type of nodes held by the tree (of
    /// nodes) used to implement this multimap.
    typedef BloombergLP::bslstl::TreeNode<ValueType>           Node;
 
    /// This typedef is an alias for the factory type used to create and
    /// destroy `Node` objects.
    typedef BloombergLP::bslstl::TreeNodePool<ValueType, ALLOCATOR>
                                                               NodeFactory;
 
    /// This typedef is an alias for the allocator traits type associated
    /// with this container.
    typedef typename bsl::allocator_traits<ALLOCATOR>          AllocatorTraits;
 
    /// This typedef is a convenient alias for the utility associated with
    /// movable references.
    typedef BloombergLP::bslmf::MovableRefUtil                 MoveUtil;
 
    /// This class is a wrapper around the comparator and allocator data
    /// members.  It takes advantage of the empty-base optimization (EBO) so
    /// that if the comparator is stateless, it takes up no space.
    ///
    /// TBD: This class should eventually be replaced by the use of a
    /// general EBO-enabled component that provides a `pair`-like interface
    /// or a `tuple`.
    ///
    /// See @ref bslstl_multimap_cpp03 
    class DataWrapper : public Comparator {
 
        // DATA
        NodeFactory d_pool;  // pool of 'Node' objects
 
      private:
        // NOT IMPLEMENTED
        DataWrapper(const DataWrapper&);
        DataWrapper& operator=(const DataWrapper&);
 
      public:
        // CREATORS
 
        /// Create a data wrapper using a copy of the specified `comparator`
        /// to order key-value pairs and a copy of the specified
        /// `basicAllocator` to supply memory.
        DataWrapper(const COMPARATOR& comparator,
                    const ALLOCATOR&  basicAllocator);
 
        /// Create a data wrapper initialized to the contents of the `pool`
        /// associated with the specified `original` data wrapper.  The
        /// comparator and allocator associated with `original` are
        /// propagated to the new data wrapper.  `original` is left in a
        /// valid but unspecified state.
        DataWrapper(
              BloombergLP::bslmf::MovableRef<DataWrapper> original);// IMPLICIT
 
        // MANIPULATORS
 
        /// Return a reference providing modifiable access to the node
        /// factory associated with this data wrapper.
        NodeFactory& nodeFactory();
 
        // ACCESSORS
 
        /// Return a reference providing non-modifiable access to the node
        /// factory associated with this data wrapper.
        const NodeFactory& nodeFactory() const;
    };
 
    // DATA
    DataWrapper                       d_compAndAlloc;
                                               // comparator and pool of 'Node'
                                               // objects
 
    BloombergLP::bslalg::RbTreeAnchor d_tree;  // balanced tree of 'Node'
                                               // objects
 
  public:
    // PUBLIC TYPES
    typedef KEY                                        key_type;
    typedef VALUE                                      mapped_type;
    typedef pair<const KEY, VALUE>                     value_type;
    typedef COMPARATOR                                 key_compare;
    typedef ALLOCATOR                                  allocator_type;
    typedef value_type&                                reference;
    typedef const value_type&                          const_reference;
 
    typedef typename AllocatorTraits::size_type        size_type;
    typedef typename AllocatorTraits::difference_type  difference_type;
    typedef typename AllocatorTraits::pointer          pointer;
    typedef typename AllocatorTraits::const_pointer    const_pointer;
 
    typedef BloombergLP::bslstl::TreeIterator<value_type,
                                              Node,
                                              difference_type> iterator;
 
    typedef BloombergLP::bslstl::TreeIterator<const value_type,
                                              Node,
                                              difference_type> const_iterator;
 
    typedef bsl::reverse_iterator<iterator>            reverse_iterator;
    typedef bsl::reverse_iterator<const_iterator>      const_reverse_iterator;
 
    /// This nested class defines a mechanism for comparing two objects of
    /// `value_type` by adapting an object of (template parameter) type
    /// `COMPARATOR`, which compares two objects of (template parameter)
    /// type `KEY` .  Note that this class exactly matches its definition in
    /// the C++11 standard [23.4.4.1]; otherwise, we would have implemented
    /// it as a separate component-local class.
    ///
    /// See @ref bslstl_multimap_cpp03 
    class value_compare {
 
        // FRIENDS
        friend class multimap;
 
      protected:
        // PROTECTED DATA
        COMPARATOR comp;  // we would not have elected to make this data
                          // member 'protected'
 
        // PROTECTED CREATORS
 
        /// Create a @ref value_compare  object that uses the specified
        /// `comparator`.
        value_compare(COMPARATOR comparator);                       // IMPLICIT
 
      public:
        // PUBLIC TYPES
 
        /// This `typedef` is an alias for the result type of a call to the
        /// overload of `operator()` (the comparison function) provided by a
        /// `multimap::value_compare` object.
        typedef bool result_type;
 
        /// This `typedef` is an alias for the type of the first parameter
        /// of the overload of `operator()` (the comparison function)
        /// provided by a `multimap::value_compare` object.
        typedef value_type first_argument_type;
 
        /// This `typedef` is an alias for the type of the second parameter
        /// of the overload of `operator()` (the comparison function)
        /// provided by a `multimap::value_compare` object.
        typedef value_type second_argument_type;
 
        // CREATORS
         value_compare(const value_compare& original) = default;
            // Create a @ref value_compare  object having the same value as the
            // specified 'original' object.
 
         ~value_compare() = default;
            // Destroy this object.
 
        // MANIPULATORS
         value_compare& operator=(const value_compare& rhs) = default;
            // Assign to this object the value of the specified 'rhs' object,
            // and return a reference providing modifiable access to this
            // object.
 
        // ACCESSORS
 
        /// Return `true` if the specified `x` object is ordered before the
        /// specified `y` object, as determined by the comparator supplied
        /// at construction, and `false` otherwise.
        bool operator()(const value_type& x, const value_type& y) const;
    };
 
  private:
    // PRIVATE CLASS METHODS
 
    /// Return an address providing modifiable access to the specified
    /// `node`.  The behavior is undefined unless `node` is the address of a
    /// `Node` object.
    static Node *toNode(BloombergLP::bslalg::RbTreeNode *node);
 
    /// Return an address providing non-modifiable access to the specified
    /// `node`.  The behavior is undefined unless `node` is the address of a
    /// `Node` object.
    static const Node *toNode(const BloombergLP::bslalg::RbTreeNode *node);
 
    // PRIVATE MANIPULATORS
 
    /// Return a reference providing modifiable access to the comparator for
    /// this multimap.
    Comparator& comparator();
 
    /// Return a reference providing modifiable access to the node allocator
    /// for this multimap.
    NodeFactory& nodeFactory();
 
    /// Efficiently exchange the value, comparator, and allocator of this
    /// object with the value, comparator, and allocator of the specified
    /// `other` object.  This method provides the no-throw exception-safety
    /// guarantee, *unless* swapping the (user-supplied) comparator or
    /// allocator objects can throw.
    void quickSwapExchangeAllocators(multimap& other);
 
    /// Efficiently exchange the value and comparator of this object with
    /// the value and comparator of the specified `other` object.  This
    /// method provides the no-throw exception-safety guarantee, *unless*
    /// swapping the (user-supplied) comparator objects can throw.  The
    /// behavior is undefined unless this object was created with the same
    /// allocator as `other`.
    void quickSwapRetainAllocators(multimap& other);
 
    // PRIVATE ACCESSORS
 
    /// Return a reference providing non-modifiable access to the comparator
    /// for this multimap.
    const Comparator& comparator() const;
 
    /// Return a reference providing non-modifiable access to the node
    /// allocator for this multimap.
    const NodeFactory& nodeFactory() const;
 
  public:
    // CREATORS
 
    multimap();
    /// Create an empty multimap.  Optionally specify a `comparator` used to
    /// order key-value pairs contained in this object.  If `comparator` is
    /// not supplied, a default-constructed object of the (template
    /// parameter) type `COMPARATOR` is used.  Optionally specify a
    /// `basicAllocator` used to supply memory.  If `basicAllocator` is not
    /// supplied, a default-constructed object of the (template parameter)
    /// type `ALLOCATOR` is used.  If the type `ALLOCATOR` is
    /// `bsl::allocator` (the default), then `basicAllocator`, if supplied,
    /// shall be convertible to `bslma::Allocator *`.  If the type
    /// `ALLOCATOR` is `bsl::allocator` and `basicAllocator` is not
    /// supplied, the currently installed default allocator is used.
    explicit multimap(const COMPARATOR& comparator,
                      const ALLOCATOR&  basicAllocator = ALLOCATOR())
    : d_compAndAlloc(comparator, basicAllocator)
    , d_tree()
    {
        // The implementation is placed here in the class definition to work
        // around an AIX compiler bug, where the constructor can fail to
        // compile because it is unable to find the definition of the default
        // argument.  This occurs when a parameterized class wraps around the
        // container and the comparator is defined after the new class.
    }
 
    /// Create an empty multimap that uses the specified `basicAllocator` to
    /// supply memory.  Use a default-constructed object of the (template
    /// parameter) type `COMPARATOR` to order the key-value pairs contained
    /// in this multimap.  Note that a `bslma::Allocator *` can be supplied
    /// for `basicAllocator` if the (template parameter) `ALLOCATOR` is
    /// `bsl::allocator` (the default).
    explicit multimap(const ALLOCATOR& basicAllocator);
 
    /// Create a multimap having the same value as the specified `original`
    /// object.  Use a copy of `original.key_comp()` to order the key-value
    /// pairs contained in this multimap.  Use the allocator returned by
    /// 'bsl::allocator_traits<ALLOCATOR>::
    /// select_on_container_copy_construction(original.get_allocator())' to
    /// allocate memory.  This method requires that the (template parameter)
    /// types `KEY` and `VALUE` both be `copy-insertable` into this multimap
    /// (see {Requirements on `KEY` and `VALUE`}).
    multimap(const multimap& original);
 
    /// Create a multimap having the same value as the specified `original`
    /// object by moving (in constant time) the contents of `original` to
    /// the new multimap.  Use a copy of `original.key_comp()` to order the
    /// key-value pairs contained in this multimap.  The allocator
    /// associated with `original` is propagated for use in the
    /// newly-created multimap.  `original` is left in a valid but
    /// unspecified state.
    multimap(BloombergLP::bslmf::MovableRef<multimap> original);    // IMPLICIT
 
    /// Create a multimap having the same value as the specified `original`
    /// object that uses the specified `basicAllocator` to supply memory.
    /// Use a copy of `original.key_comp()` to order the key-value pairs
    /// contained in this multimap.  This method requires that the (template
    /// parameter) types `KEY` and `VALUE` both be `copy-insertable` into
    /// this multimap (see {Requirements on `KEY` and `VALUE`}).  Note that
    /// a `bslma::Allocator *` can be supplied for `basicAllocator` if the
    /// (template parameter) `ALLOCATOR` is `bsl::allocator` (the default).
    multimap(const multimap&                                original,
             const typename type_identity<ALLOCATOR>::type& basicAllocator);
 
    /// Create a multimap having the same value as the specified `original`
    /// object that uses the specified `basicAllocator` to supply memory.
    /// The contents of `original` are moved (in constant time) to the new
    /// multimap if `basicAllocator == original.get_allocator()`, and are
    /// move-inserted (in linear time) using `basicAllocator` otherwise.
    /// `original` is left in a valid but unspecified state.  Use a copy of
    /// `original.key_comp()` to order the key-value pairs contained in this
    /// multimap.  This method requires that the (template parameter) types
    /// `KEY` and `VALUE` both be `move-insertable` into this multimap (see
    /// {Requirements on `KEY` and `VALUE`}).  Note that a 'bslma::Allocator
    /// *` can be supplied for `basicAllocator' if the (template parameter)
    /// `ALLOCATOR` is `bsl::allocator` (the default).
    multimap(BloombergLP::bslmf::MovableRef<multimap>       original,
             const typename type_identity<ALLOCATOR>::type& basicAllocator);
 
    /// Create a multimap, and insert each `value_type` object in the
    /// sequence starting at the specified `first` element, and ending
    /// immediately before the specified `last` element.  Optionally specify
    /// a `comparator` used to order key-value pairs contained in this
    /// object.  If `comparator` is not supplied, a default-constructed
    /// object of the (template parameter) type `COMPARATOR` is used.
    /// Optionally specify a `basicAllocator` used to supply memory.  If
    /// `basicAllocator` is not supplied, a default-constructed object of
    /// the (template parameter) type `ALLOCATOR` is used.  If the type
    /// `ALLOCATOR` is `bsl::allocator` (the default), then
    /// `basicAllocator`, if supplied, shall be convertible to
    /// `bslma::Allocator *`.  If the type `ALLOCATOR` is `bsl::allocator`
    /// and `basicAllocator` is not supplied, the currently installed
    /// default allocator is used.  If the sequence `first` to `last` is
    /// ordered according to `comparator`, then this operation has `O[N]`
    /// complexity, where `N` is the number of elements between `first` and
    /// `last`; otherwise, this operation has `O[N * log(N)]` complexity.
    /// The (template parameter) type `INPUT_ITERATOR` shall meet the
    /// requirements of an input iterator defined in the C++11 standard
    /// [24.2.3] providing access to values of a type convertible to
    /// `value_type`, and `value_type` must be `emplace-constructible` from
    /// `*i` into this multimap, where `i` is a dereferenceable iterator in
    /// the range `[first .. last)` (see {Requirements on `KEY` and
    /// `VALUE`}).  The behavior is undefined unless `first` and `last`
    /// refer to a sequence of valid values where `first` is at a position
    /// at or before `last`.
    template <class INPUT_ITERATOR>
    multimap(INPUT_ITERATOR    first,
             INPUT_ITERATOR    last,
             const COMPARATOR& comparator     = COMPARATOR(),
             const ALLOCATOR&  basicAllocator = ALLOCATOR());
    template <class INPUT_ITERATOR>
    multimap(INPUT_ITERATOR    first,
             INPUT_ITERATOR    last,
             const ALLOCATOR&  basicAllocator);
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
    multimap(std::initializer_list<value_type> values,
             const COMPARATOR&                 comparator     = COMPARATOR(),
             const ALLOCATOR&                  basicAllocator = ALLOCATOR());
    /// Create a multimap and insert each `value_type` object in the
    /// specified `values` initializer list.  Optionally specify a
    /// `comparator` used to order keys contained in this object.  If
    /// `comparator` is not supplied, a default-constructed object of the
    /// (template parameter) type `COMPARATOR` is used.  Optionally specify
    /// a `basicAllocator` used to supply memory.  If `basicAllocator` is
    /// not supplied, a default-constructed object of the (template
    /// parameter) type `ALLOCATOR` is used.  If the type `ALLOCATOR` is
    /// `bsl::allocator` (the default), then `basicAllocator`, if supplied,
    /// shall be convertible to `bslma::Allocator *`.  If the type
    /// `ALLOCATOR` is `bsl::allocator` and `basicAllocator` is not
    /// supplied, the currently installed default allocator is used.  If
    /// `values` is ordered according to `comparator`, then this operation
    /// has `O[N]` complexity, where `N` is the number of elements in
    /// `values`; otherwise, this operation has `O[N * log(N)]` complexity.
    /// This method requires that the (template parameter) types `KEY` and
    /// `VALUE` both be `copy-insertable` into this multimap (see
    /// {Requirements on `KEY` and `VALUE`}).
    multimap(std::initializer_list<value_type> values,
             const ALLOCATOR&                  basicAllocator);
#endif
 
    /// Destroy this object.
    ~multimap();
 
    // MANIPULATORS
 
    /// Assign to this object the value and comparator of the specified
    /// `rhs` object, propagate to this object the allocator of `rhs` if the
    /// `ALLOCATOR` type has trait `propagate_on_container_copy_assignment`,
    /// and return a reference providing modifiable access to this object.
    /// If an exception is thrown, `*this` is left in a valid but
    /// unspecified state.  This method requires that the (template
    /// parameter) types `KEY` and `VALUE` both be `copy-assignable` and
    /// `copy-insertable` into this multimap (see {Requirements on `KEY` and
    /// `VALUE`}).
    multimap& operator=(const multimap& rhs);
 
    multimap& operator=(BloombergLP::bslmf::MovableRef<multimap> rhs)
        BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(
                           AllocatorTraits::is_always_equal::value &&
                           std::is_nothrow_move_assignable<COMPARATOR>::value);
        // Assign to this object the value and comparator of the specified
        // 'rhs' object, propagate to this object the allocator of 'rhs' if the
        // 'ALLOCATOR' type has trait 'propagate_on_container_move_assignment',
        // and return a reference providing modifiable access to this object.
        // The contents of 'rhs' are moved (in constant time) to this multimap
        // if 'get_allocator() == rhs.get_allocator()' (after accounting for
        // the aforementioned trait); otherwise, all elements in this multimap
        // are either destroyed or move-assigned to and each additional element
        // in 'rhs' is move-inserted into this multimap.  'rhs' is left in a
        // valid but unspecified state, and if an exception is thrown, '*this'
        // is left in a valid but unspecified state.  This method requires that
        // the (template parameter) types 'KEY' and 'VALUE' both be
        // 'move-assignable' and 'move-insertable' into this multimap (see
        // {Requirements on 'KEY' and 'VALUE'}).
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
    /// Assign to this object the value resulting from first clearing this
    /// multimap and then inserting each `value_type` object in the
    /// specified `values` initializer list, and return a reference
    /// providing modifiable access to this object.  This method requires
    /// that the (template parameter) types `KEY` and `VALUE` both be
    /// `copy-insertable` into this multimap (see {Requirements on `KEY` and
    /// `VALUE`}).
    multimap& operator=(std::initializer_list<value_type> values);
#endif
 
    /// Return an iterator providing modifiable access to the first
    /// `value_type` object in the ordered sequence of `value_type` objects
    /// maintained by this multimap, or the `end` iterator if this multimap
    /// is empty.
    iterator begin() BSLS_KEYWORD_NOEXCEPT;
 
    /// Return an iterator providing modifiable access to the past-the-end
    /// element in the ordered sequence of `value_type` objects maintained
    /// by this multimap.
    iterator end() BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing modifiable access to the last
    /// `value_type` object in the ordered sequence of `value_type` objects
    /// maintained by this multimap, or `rend` if this multimap is empty.
    reverse_iterator rbegin() BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing modifiable access to the
    /// prior-to-the-beginning element in the ordered sequence of
    /// `value_type` objects maintained by this multimap.
    reverse_iterator rend() BSLS_KEYWORD_NOEXCEPT;
 
    /// Insert the specified `value` into this multimap.  If a range
    /// containing elements equivalent to `value` already exists, insert the
    /// `value` at the end of that range.  Return an iterator referring to
    /// the newly inserted `value_type` object.  This method requires that
    /// the (template parameter) types `KEY` and `VALUE` both be
    /// `copy-insertable` into this multimap (see {Requirements on `KEY` and
    /// `VALUE`}).
    iterator insert(const value_type& value);
 
#if defined(BSLS_PLATFORM_CMP_SUN) && BSLS_PLATFORM_CMP_VERSION < 0x5130
    template <class ALT_VALUE_TYPE>
    iterator
#elif !defined(BSLS_COMPILERFEATURES_SUPPORT_TRAITS_HEADER)
    template <class ALT_VALUE_TYPE>
    typename enable_if<is_convertible<ALT_VALUE_TYPE, value_type>::value,
                       iterator>::type
#else
    /// Insert into this multimap a `value_type` object created from the
    /// specified `value`.  If a range containing elements equivalent to
    /// `value_type` object already exists, insert the `value_type` object
    /// at the end of that range.  Return an iterator referring to the newly
    /// inserted `value_type` object.  This method requires that the
    /// (template parameter) types `KEY` and `VALUE` both be
    /// `move-insertable` into this multimap (see {Requirements on `KEY` and
    /// `VALUE`}), and the `value_type` be constructible from the (template
    /// parameter) `ALT_VALUE_TYPE`.
    template <class ALT_VALUE_TYPE>
    typename enable_if<std::is_constructible<value_type,
                                             ALT_VALUE_TYPE&&>::value,
                       iterator>::type
#endif
    insert(BSLS_COMPILERFEATURES_FORWARD_REF(ALT_VALUE_TYPE) value)
    {
        // Note that some compilers fail when this method is defined
        // out-of-line.
 
        return emplace(BSLS_COMPILERFEATURES_FORWARD(ALT_VALUE_TYPE, value));
    }
 
    /// Insert the specified `value` into this multimap (in amortized
    /// constant time if the specified `hint` is a valid immediate successor
    /// to the key of `value`).  Return an iterator referring to the newly
    /// inserted `value_type` object.  If `hint` is not a valid immediate
    /// successor to the key of `value`, this operation has `O[log(N)]`
    /// complexity, where `N` is the size of this multimap.  This method
    /// requires that the (template parameter) types `KEY` and `VALUE` both
    /// be `copy-insertable` into this multimap (see {Requirements on `KEY`
    /// and `VALUE`}).  The behavior is undefined unless `hint` is an
    /// iterator in the range `[begin() .. end()]` (both endpoints
    /// included).
    iterator insert(const_iterator hint, const value_type& value);
 
#if defined(BSLS_PLATFORM_CMP_SUN) && BSLS_PLATFORM_CMP_VERSION < 0x5130
    template <class ALT_VALUE_TYPE>
    iterator
#elif !defined(BSLS_COMPILERFEATURES_SUPPORT_TRAITS_HEADER)
    template <class ALT_VALUE_TYPE>
    typename enable_if<is_convertible<ALT_VALUE_TYPE, value_type>::value,
                       iterator>::type
#else
    /// Insert into this multimap a `value_type` object created from the
    /// specified `value` (in amortized constant time if the specified
    /// `hint` is a valid immediate successor to the object created from
    /// `value`).  Return an iterator referring to the newly inserted
    /// `value_type` object in this multimap.  If `hint` is not a valid
    /// immediate successor to the object created from `value`, this
    /// operation has `O[log(N)]` complexity, where `N` is the size of this
    /// multimap.  This method requires that the (template parameter) types
    /// `KEY` and `VALUE` both be `move-insertable` into this multimap (see
    /// {Requirements on `KEY` and `VALUE`}), and the `value_type` be
    /// constructible from the (template parameter) `ALT_VALUE_TYPE`.  The
    /// behavior is undefined unless `hint` is an iterator in the range
    /// `[begin() .. end()]` (both endpoints included).
    template <class ALT_VALUE_TYPE>
    typename enable_if<std::is_constructible<value_type,
                                             ALT_VALUE_TYPE&&>::value,
                       iterator>::type
#endif
    insert(const_iterator                                    hint,
           BSLS_COMPILERFEATURES_FORWARD_REF(ALT_VALUE_TYPE) value)
    {
        // Note that some compilers fail when this method is defined
        // out-of-line.
 
        return emplace_hint(hint,
                        BSLS_COMPILERFEATURES_FORWARD(ALT_VALUE_TYPE, value));
    }
 
    /// Insert into this multimap the value of each `value_type` object in
    /// the range starting at the specified `first` iterator and ending
    /// immediately before the specified `last` iterator.  The (template
    /// parameter) type `INPUT_ITERATOR` shall meet the requirements of an
    /// input iterator defined in the C++11 standard [24.2.3] providing
    /// access to values of a type convertible to `value_type`, and
    /// `value_type` must be `emplace-constructible` from `*i` into this
    /// multimap, where `i` is a dereferenceable iterator in the range
    /// `[first .. last)` (see {Requirements on `KEY` and `VALUE`}).  The
    /// behavior is undefined unless `first` and `last` refer to a sequence
    /// of valid values where `first` is at a position at or before `last`.
    template <class INPUT_ITERATOR>
    void insert(INPUT_ITERATOR first, INPUT_ITERATOR last);
 
#if defined(BSLS_PLATFORM_CMP_SUN) && BSLS_PLATFORM_CMP_VERSION < 0x5130
    void insert(const_iterator first, const_iterator last);
        // This method is provided only on Sun to work around a bug in the Sun
        // Studio 12.3 compiler, which prevents us from disabling (at compile
        // time) the overload of 'insert' taking a 'const_iterator' and a
        // forwarding reference if the second argument is not convertible to
        // the value type associated with the map.  Without such a check, in
        // certain cases, the same compiler complains of ambiguity between
        // the 'insert' method taking two input iterators and the 'insert'
        // method taking a 'const_iterator' and a forwarding reference; such
        // an ambiguity is resolved by providing this method, which is
        // equivalent to the 'insert' method (above) taking two input iterators
        // of template parameter type.
#endif
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
    /// Insert into this multimap the value of each `value_type` object in
    /// the specified `values` initializer list.  This method requires that
    /// the (template parameter) types `KEY` and `VALUE` both be
    /// `copy-insertable` into this multimap (see {Requirements on `KEY` and
    /// `VALUE`}).
    void insert(std::initializer_list<value_type> values);
#endif
 
#if BSLS_COMPILERFEATURES_SIMULATE_VARIADIC_TEMPLATES
// {{{ BEGIN GENERATED CODE
// Command line: sim_cpp11_features.pl bslstl_multimap.h
#ifndef BSLSTL_MULTIMAP_VARIADIC_LIMIT
#define BSLSTL_MULTIMAP_VARIADIC_LIMIT 2
#endif
#ifndef BSLSTL_MULTIMAP_VARIADIC_LIMIT_A
#define BSLSTL_MULTIMAP_VARIADIC_LIMIT_A BSLSTL_MULTIMAP_VARIADIC_LIMIT
#endif
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 0
    iterator emplace();
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 0
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 1
    template <class Args_1>
    iterator emplace(BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1);
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 1
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 2
    template <class Args_1,
              class Args_2>
    iterator emplace(BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1,
                     BSLS_COMPILERFEATURES_FORWARD_REF(Args_2) args_2);
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 2
 
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 0
    iterator emplace_hint(const_iterator hint);
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 0
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 1
    template <class Args_1>
    iterator emplace_hint(const_iterator hint,
                             BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1);
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 1
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 2
    template <class Args_1,
              class Args_2>
    iterator emplace_hint(const_iterator hint,
                             BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1,
                             BSLS_COMPILERFEATURES_FORWARD_REF(Args_2) args_2);
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_A >= 2
 
#else
// The generated code below is a workaround for the absence of perfect
// forwarding in some compilers.
 
    template <class... Args>
    iterator emplace(BSLS_COMPILERFEATURES_FORWARD_REF(Args)... args);
 
    template <class... Args>
    iterator emplace_hint(const_iterator hint,
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args)... args);
// }}} END GENERATED CODE
#endif
 
    iterator erase(const_iterator position);
    /// Remove from this multimap the `value_type` object at the specified
    /// `position`, and return an iterator referring to the element
    /// immediately following the removed element, or to the past-the-end
    /// position if the removed element was the last element in the sequence
    /// of elements maintained by this multimap.   This method invalidates
    /// only iterators and references to the removed element and previously
    /// saved values of the `end()` iterator.  The behavior is undefined
    /// unless `position` refers to a `value_type` object in this multimap.
    iterator erase(iterator position);
 
    /// Remove from this multimap all `value_type` objects whose keys are
    /// equivalent to the specified `key`, if such entries exist, and return
    /// the number of erased objects; otherwise, if there is no `value_type`
    /// objects having an equivalent key, return 0 with no other effect.
    /// This method invalidates only iterators and references to the removed
    /// element and previously saved values of the `end()` iterator.
    size_type erase(const key_type& key);
 
    iterator erase(const_iterator first, const_iterator last);
    /// Remove from this multimap the `value_type` objects starting at the
    /// specified `first` position up to, but including the specified `last`
    /// position, and return `last`.   This method invalidates only
    /// iterators and references to the removed element and previously saved
    /// values of the `end()` iterator.  The behavior is undefined unless
    /// `first` and `last` either refer to elements in this multimap or are
    /// the `end` iterator, and the `first` position is at or before the
    /// `last` position in the ordered sequence provided by this container.
 
    void swap(multimap& other) BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(
                                 AllocatorTraits::is_always_equal::value &&
                                 bsl::is_nothrow_swappable<COMPARATOR>::value);
        // Exchange the value and comparator of this object with those of the
        // specified 'other' object; also exchange the allocator of this object
        // with that of 'other' if the (template parameter) type 'ALLOCATOR'
        // has the 'propagate_on_container_swap' trait, and do not modify
        // either allocator otherwise.  This method provides the no-throw
        // exception-safety guarantee if and only if the (template parameter)
        // type 'COMPARATOR' provides a no-throw swap operation, and provides
        // the basic exception-safety guarantee otherwise; if an exception is
        // thrown, both objects are left in valid but unspecified states.  This
        // operation has 'O[1]' complexity if either this object was created
        // with the same allocator as 'other' or 'ALLOCATOR' has the
        // 'propagate_on_container_swap' trait; otherwise, it has 'O[n + m]'
        // complexity, where 'n' and 'm' are the number of elements in this
        // object and 'other', respectively.  Note that this method's support
        // for swapping objects created with different allocators when
        // 'ALLOCATOR' does not have the 'propagate_on_container_swap' trait is
        // a departure from the C++ Standard.
 
    /// Remove all entries from this multimap.  Note that the multimap is
    /// empty after this call, but allocated memory may be retained for
    /// future use.
    void clear() BSLS_KEYWORD_NOEXCEPT;
 
    // Turn off complaints about necessarily class-defined methods.
    // BDE_VERIFY pragma: push
    // BDE_VERIFY pragma: -CD01
 
    /// Return an iterator providing modifiable access to the first
    /// `value_type` object in this multimap whose key is equivalent to the
    /// specified `key`, if such an entry exists, and the past-the-end
    /// (`end`) iterator otherwise.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    iterator find(const key_type& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::find(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing modifiable access to the first
    /// `value_type` object in this multimap whose key is equivalent to the
    /// specified `key`, if such an entry exists, and the past-the-end
    /// (`end`) iterator otherwise.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        iterator>::type
    find(const LOOKUP_KEY& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::find(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing modifiable access to the first (i.e.,
    /// ordered least) `value_type` object in this multimap whose key is
    /// greater-than or equal-to the specified `key`, and the past-the-end
    /// iterator if this multimap does not contain a `value_type` object
    /// whose key is greater-than or equal-to `key`.  Note that this
    /// function returns the *first* position before which a `value_type`
    /// object having an equivalent key could be inserted into the ordered
    /// sequence maintained by this multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    iterator lower_bound(const key_type& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::lowerBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing modifiable access to the first (i.e.,
    /// ordered least) `value_type` object in this multimap whose key is
    /// greater-than or equal-to the specified `key`, and the past-the-end
    /// iterator if this multimap does not contain a `value_type` object
    /// whose key is greater-than or equal-to `key`.  Note that this
    /// function returns the *first* position before which a `value_type`
    /// object having an equivalent key could be inserted into the ordered
    /// sequence maintained by this multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        iterator>::type
    lower_bound(const LOOKUP_KEY& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::lowerBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing modifiable access to the first (i.e.,
    /// ordered least) `value_type` object in this multimap whose key is
    /// greater than the specified `key`, and the past-the-end iterator if
    /// this multimap does not contain a `value_type` object whose key is
    /// greater-than `key`.  Note that this function returns the *last*
    /// position before which a `value_type` object having an equivalent key
    /// could be inserted into the ordered sequence maintained by this
    /// multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    iterator upper_bound(const key_type& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::upperBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing modifiable access to the first (i.e.,
    /// ordered least) `value_type` object in this multimap whose key is
    /// greater than the specified `key`, and the past-the-end iterator if
    /// this multimap does not contain a `value_type` object whose key is
    /// greater-than `key`.  Note that this function returns the *last*
    /// position before which a `value_type` object having an equivalent key
    /// could be inserted into the ordered sequence maintained by this
    /// multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        iterator>::type
    upper_bound(const LOOKUP_KEY& key)
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::upperBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return a pair of iterators providing modifiable access to the
    /// sequence of `value_type` objects in this multimap whose keys are
    /// equivalent to the specified `key`, where the first iterator is
    /// positioned at the start of the sequence and the second is positioned
    /// one past the end of the sequence.  The first returned iterator will
    /// be `lower_bound(key)`, the second returned iterator will be
    /// `upper_bound(key)`, and, if this multimap contains no `value_type`
    /// object with an equivalent key, then the two returned iterators will
    /// have the same value.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    bsl::pair<iterator,iterator> equal_range(const key_type& key)
    {
        iterator startIt = lower_bound(key);
        iterator endIt   = startIt;
        if (endIt != end() && !comparator()(key, *endIt.node())) {
            endIt = upper_bound(key);
        }
        return bsl::pair<iterator, iterator>(startIt, endIt);
    }
 
    /// Return a pair of iterators providing modifiable access to the
    /// sequence of `value_type` objects in this multimap whose keys are
    /// equivalent to the specified `key`, where the first iterator is
    /// positioned at the start of the sequence and the second is positioned
    /// one past the end of the sequence.  The first returned iterator will
    /// be `lower_bound(key)`, the second returned iterator will be
    /// `upper_bound(key)`, and, if this multimap contains no `value_type`
    /// object with an equivalent key, then the two returned iterators will
    /// have the same value.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        pair<iterator, iterator> >::type
    equal_range(const LOOKUP_KEY& key)
    {
        iterator startIt = lower_bound(key);
        iterator endIt   = startIt;
        if (endIt != end() && !comparator()(key, *endIt.node())) {
            endIt = upper_bound(key);
        }
        return pair<iterator, iterator>(startIt, endIt);
    }
 
    // BDE_VERIFY pragma: pop
 
    // ACCESSORS
 
    /// Return (a copy of) the allocator used for memory allocation by this
    /// multimap.
    allocator_type get_allocator() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return an iterator providing non-modifiable access to the first
    /// `value_type` object in the ordered sequence of `value_type` objects
    /// maintained by this multimap, or the `end` iterator if this multimap
    /// is empty.
    const_iterator begin() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return an iterator providing non-modifiable access to the
    /// past-the-end element in the ordered sequence of `value_type` objects
    /// maintained by this multimap.
    const_iterator end() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing non-modifiable access to the
    /// last `value_type` object in the ordered sequence of `value_type`
    /// objects maintained by this multimap, or `rend` if this multimap is
    /// empty.
    const_reverse_iterator rbegin() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing non-modifiable access to the
    /// prior-to-the-beginning element in the ordered sequence of
    /// `value_type` objects maintained by this multimap.
    const_reverse_iterator rend() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return an iterator providing non-modifiable access to the first
    /// `value_type` object in the ordered sequence of `value_type` objects
    /// maintained by this multimap, or the `cend` iterator if this multimap
    /// is empty.
    const_iterator cbegin() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return an iterator providing non-modifiable access to the
    /// past-the-end element in the ordered sequence of `value_type` objects
    /// maintained by this multimap.
    const_iterator cend() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing non-modifiable access to the
    /// last `value_type` object in the ordered sequence of `value_type`
    /// objects maintained by this multimap, or `rend` if this multimap is
    /// empty.
    const_reverse_iterator crbegin() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a reverse iterator providing non-modifiable access to the
    /// prior-to-the-beginning element in the ordered sequence of
    /// `value_type` objects maintained by this multimap.
    const_reverse_iterator crend() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return `true` if this multimap contains an element whose key is
    /// equivalent to the specified `key`.
    bool contains(const key_type &key) const;
 
    /// Return `true` if this multimap contains an element whose key is
    /// equivalent to the specified `key`.
    ///
    /// Note: implemented inline due to Sun CC compilation error
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        bool>::type
    contains(const LOOKUP_KEY& key) const
    {
        return find(key) != end();
    }
 
    /// Return `true` if this multimap contains no elements, and `false`
    /// otherwise.
    bool empty() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return the number of elements in this multimap.
    size_type size() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return a theoretical upper bound on the largest number of elements
    /// that this multimap could possibly hold.  Note that there is no
    /// guarantee that the multimap can successfully grow to the returned
    /// size, or even close to that size without running out of resources.
    size_type max_size() const BSLS_KEYWORD_NOEXCEPT;
 
    /// Return the key-comparison functor (or function pointer) used by this
    /// multimap; if a comparator was supplied at construction, return its
    /// value, otherwise return a default constructed @ref key_compare  object.
    /// Note that this comparator compares objects of type `KEY`, which is
    /// the key part of the `value_type` objects contained in this multimap.
    key_compare key_comp() const;
 
    /// Return a functor for comparing two `value_type` objects by comparing
    /// their respective keys using `key_comp()`.   Note that this
    /// comparator compares objects of type `value_type` (i.e., 'pair<const
    /// KEY, VALUE>').
    value_compare value_comp() const;
 
    // Turn off complaints about necessarily class-defined methods.
    // BDE_VERIFY pragma: push
    // BDE_VERIFY pragma: -CD01
 
    /// Return an iterator providing non-modifiable access to the first
    /// `value_type` object having the specified `key` in the ordered
    /// sequence maintained by this multimap, if such an object exists, and
    /// the past-the-end (`end`) iterator otherwise.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    const_iterator find(const key_type& key) const
    {
        return const_iterator(BloombergLP::bslalg::RbTreeUtil::find(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing non-modifiable access to the first
    /// `value_type` object having the specified `key` in the ordered
    /// sequence maintained by this multimap, if such an object exists, and
    /// the past-the-end (`end`) iterator otherwise.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        const_iterator>::type
    find(const LOOKUP_KEY& key) const
    {
        return const_iterator(BloombergLP::bslalg::RbTreeUtil::find(
            d_tree, this->comparator(), key));
    }
 
    /// Return the number of `value_type` objects within this multimap whose
    /// keys are equivalent to the specified `key`.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    size_type count(const key_type& key) const
    {
        int            count = 0;
        const_iterator it    = lower_bound(key);
 
        while (it != end() && !comparator()(key, *it.node())) {
            ++it;
            ++count;
        }
        return count;
    }
 
    /// Return the number of `value_type` objects within this multimap whose
    /// keys are equivalent to the specified `key`.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        size_type>::type
    count(const LOOKUP_KEY& key) const
    {
        int            count = 0;
        const_iterator it    = lower_bound(key);
 
        while (it != end() && !comparator()(key, *it.node())) {
            ++it;
            ++count;
        }
        return count;
    }
 
    /// Return an iterator providing non-modifiable access to the first
    /// (i.e., ordered least) `value_type` object in this multimap whose key
    /// is greater-than or equal-to the specified `key`, and the
    /// past-the-end iterator if this multimap does not contain a
    /// `value_type` object whose key is greater-than or equal-to `key`.
    /// Note that this function returns the *first* position before which a
    /// `value_type` object having an equivalent key could be inserted into
    /// the ordered sequence maintained by this multimap, while preserving
    /// its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    const_iterator lower_bound(const key_type& key) const
    {
        return iterator(BloombergLP::bslalg::RbTreeUtil::lowerBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing non-modifiable access to the first
    /// (i.e., ordered least) `value_type` object in this multimap whose key
    /// is greater-than or equal-to the specified `key`, and the
    /// past-the-end iterator if this multimap does not contain a
    /// `value_type` object whose key is greater-than or equal-to `key`.
    /// Note that this function returns the *first* position before which a
    /// `value_type` object having an equivalent key could be inserted into
    /// the ordered sequence maintained by this multimap, while preserving
    /// its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        const_iterator>::type
    lower_bound(const LOOKUP_KEY& key) const
    {
        return const_iterator(BloombergLP::bslalg::RbTreeUtil::lowerBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing non-modifiable access to the first
    /// (i.e., ordered least) `value_type` object in this multimap whose key
    /// is greater than the specified `key`, and the past-the-end iterator
    /// if this multimap does not contain a `value_type` object whose key is
    /// greater-than `key`.  Note that this function returns the *last*
    /// position before which a `value_type` object having an equivalent key
    /// could be inserted into the ordered sequence maintained by this
    /// multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    const_iterator upper_bound(const key_type& key) const
    {
        return const_iterator(BloombergLP::bslalg::RbTreeUtil::upperBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return an iterator providing non-modifiable access to the first
    /// (i.e., ordered least) `value_type` object in this multimap whose key
    /// is greater than the specified `key`, and the past-the-end iterator
    /// if this multimap does not contain a `value_type` object whose key is
    /// greater-than `key`.  Note that this function returns the *last*
    /// position before which a `value_type` object having an equivalent key
    /// could be inserted into the ordered sequence maintained by this
    /// multimap, while preserving its ordering.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        const_iterator>::type
    upper_bound(const LOOKUP_KEY& key) const
    {
        return const_iterator(BloombergLP::bslalg::RbTreeUtil::upperBound(
            d_tree, this->comparator(), key));
    }
 
    /// Return a pair of iterators providing non-modifiable access to the
    /// sequence of `value_type` objects in this multimap whose keys are
    /// equivalent to the specified `key`, where the first iterator is
    /// positioned at the start of the sequence and the second iterator is
    /// positioned one past the end of the sequence.  The first returned
    /// iterator will be `lower_bound(key)`, the second returned iterator
    /// will be `upper_bound(key)`, and, if this multimap contains no
    /// `value_type` objects having keys equivalent to `key`, then the two
    /// returned iterators will have the same value.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    pair<const_iterator, const_iterator> equal_range(const key_type& key) const
    {
        const_iterator startIt = lower_bound(key);
        const_iterator endIt   = startIt;
        if (endIt != end() && !comparator()(key, *endIt.node())) {
            endIt = upper_bound(key);
        }
        return bsl::pair<const_iterator, const_iterator>(startIt, endIt);
    }
 
    /// Return a pair of iterators providing non-modifiable access to the
    /// sequence of `value_type` objects in this multimap whose keys are
    /// equivalent to the specified `key`, where the first iterator is
    /// positioned at the start of the sequence and the second iterator is
    /// positioned one past the end of the sequence.  The first returned
    /// iterator will be `lower_bound(key)`, the second returned iterator
    /// will be `upper_bound(key)`, and, if this multimap contains no
    /// `value_type` objects having keys equivalent to `key`, then the two
    /// returned iterators will have the same value.
    ///
    /// Note: implemented inline due to Sun CC compilation error.
    template <class LOOKUP_KEY>
    typename bsl::enable_if<
        BloombergLP::bslmf::IsTransparentPredicate<COMPARATOR,
                                                   LOOKUP_KEY>::value,
        pair<const_iterator, const_iterator> >::type
    equal_range(const LOOKUP_KEY& key) const
    {
        const_iterator startIt = lower_bound(key);
        const_iterator endIt   = startIt;
        if (endIt != end() && !comparator()(key, *endIt.node())) {
            endIt = upper_bound(key);
        }
        return pair<const_iterator, const_iterator>(startIt, endIt);
    }
 
    // BDE_VERIFY pragma: pop
};
 
#ifdef BSLS_COMPILERFEATURES_SUPPORT_CTAD
// CLASS TEMPLATE DEDUCTION GUIDES
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the iterators supplied to the constructor of `multimap`.  Deduce the
/// template parameters `COMPARATOR` and `ALLOCATOR` from the other
/// parameters passed to the constructor.  This deduction guide does not
/// participate unless the supplied allocator meets the requirements of a
/// standard allocator.
template <
    class INPUT_ITERATOR,
    class KEY = BloombergLP::bslstl::IteratorUtil::IterKey_t<INPUT_ITERATOR>,
    class VALUE =
               BloombergLP::bslstl::IteratorUtil::IterMapped_t<INPUT_ITERATOR>,
    class COMPARATOR = std::less<KEY>,
    class ALLOCATOR = bsl::allocator<
             BloombergLP::bslstl::IteratorUtil::IterToAlloc_t<INPUT_ITERATOR>>,
    class = bsl::enable_if_t<!bsl::IsStdAllocator_v<COMPARATOR>>,
    class = bsl::enable_if_t<bsl::IsStdAllocator_v<ALLOCATOR>>
    >
multimap(INPUT_ITERATOR,
    INPUT_ITERATOR,
    COMPARATOR = COMPARATOR(),
    ALLOCATOR = ALLOCATOR())
-> multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the iterators supplied to the constructor of `multimap`.  Deduce the
/// template parameter `COMPARATOR` from the other parameter passed to the
/// constructor.  This deduction guide does not participate unless the
/// supplied allocator is convertible to
/// `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
template <
    class INPUT_ITERATOR,
    class COMPARATOR,
    class ALLOC,
    class KEY = BloombergLP::bslstl::IteratorUtil::IterKey_t<INPUT_ITERATOR>,
    class VALUE =
               BloombergLP::bslstl::IteratorUtil::IterMapped_t<INPUT_ITERATOR>,
    class DEFAULT_ALLOCATOR = bsl::allocator<pair<const KEY, VALUE>>,
    class = bsl::enable_if_t<bsl::is_convertible_v<ALLOC *, DEFAULT_ALLOCATOR>>
    >
multimap(INPUT_ITERATOR, INPUT_ITERATOR, COMPARATOR, ALLOC *)
-> multimap<KEY, VALUE, COMPARATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the iterators supplied to the constructor of `multimap`.  This
/// deduction guide does not participate unless the supplied allocator meets
/// the requirements of a standard allocator.
template <
    class INPUT_ITERATOR,
    class ALLOCATOR,
    class KEY = BloombergLP::bslstl::IteratorUtil::IterKey_t<INPUT_ITERATOR>,
    class VALUE =
               BloombergLP::bslstl::IteratorUtil::IterMapped_t<INPUT_ITERATOR>,
    class = bsl::enable_if_t<bsl::IsStdAllocator_v<ALLOCATOR>>
    >
multimap(INPUT_ITERATOR, INPUT_ITERATOR, ALLOCATOR)
-> multimap<KEY, VALUE, std::less<KEY>, ALLOCATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the iterators supplied to the constructor of `multimap`.  This
/// deduction guide does not participate unless the supplied allocator is
/// convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
template <
    class INPUT_ITERATOR,
    class ALLOC,
    class KEY = BloombergLP::bslstl::IteratorUtil::IterKey_t<INPUT_ITERATOR>,
    class VALUE =
               BloombergLP::bslstl::IteratorUtil::IterMapped_t<INPUT_ITERATOR>,
    class DEFAULT_ALLOCATOR = bsl::allocator<pair<const KEY, VALUE>>,
    class = bsl::enable_if_t<bsl::is_convertible_v<ALLOC *, DEFAULT_ALLOCATOR>>
    >
multimap(INPUT_ITERATOR, INPUT_ITERATOR, ALLOC *)
-> multimap<KEY, VALUE>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the initializer_list supplied to the constructor of `multimap`.
/// Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the
/// other parameters passed to the constructor.  This deduction guide does
/// not participate unless the supplied allocator meets the requirements of
/// a standard allocator.
template <
    class KEY,
    class VALUE,
    class COMPARATOR = std::less<KEY>,
    class ALLOCATOR = bsl::allocator<bsl::pair<const KEY, VALUE>>,
    class = bsl::enable_if_t<!bsl::IsStdAllocator_v<COMPARATOR>>,
    class = bsl::enable_if_t<bsl::IsStdAllocator_v<ALLOCATOR>>
    >
multimap(std::initializer_list<pair<const KEY, VALUE>>,
         COMPARATOR = COMPARATOR(),
         ALLOCATOR = ALLOCATOR())
-> multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the initializer_list supplied to the constructor of `multimap`.
/// Deduce the template parameter `COMPARATOR` from the other parameters
/// passed to the constructor.  This deduction guide does not participate
/// unless the supplied allocator is convertible to
/// `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
template <
    class KEY,
    class VALUE,
    class COMPARATOR,
    class ALLOC,
    class DEFAULT_ALLOCATOR = bsl::allocator<bsl::pair<const KEY, VALUE>>,
    class = bsl::enable_if_t<bsl::is_convertible_v<ALLOC *, DEFAULT_ALLOCATOR>>
    >
multimap(std::initializer_list<pair<const KEY, VALUE>>, COMPARATOR, ALLOC *)
-> multimap<KEY, VALUE, COMPARATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the initializer_list supplied to the constructor of `multimap`.
/// Deduce the template parameter `ALLOCATOR` from the other parameter
/// passed to the constructor.  This deduction guide does not participate
/// unless the supplied allocator meets the requirements of a standard
/// allocator.
template <
    class KEY,
    class VALUE,
    class ALLOCATOR,
    class = bsl::enable_if_t<bsl::IsStdAllocator_v<ALLOCATOR>>
    >
multimap(std::initializer_list<pair<const KEY, VALUE>>, ALLOCATOR)
-> multimap<KEY, VALUE, std::less<KEY>, ALLOCATOR>;
 
/// Deduce the template parameters `KEY` and `VALUE` from the `value_type`
/// of the initializer_list supplied to the constructor of `multimap`.  This
/// deduction guide does not participate unless the supplied allocator is
/// convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
template <
    class KEY,
    class VALUE,
    class ALLOC,
    class DEFAULT_ALLOCATOR = bsl::allocator<bsl::pair<const KEY, VALUE>>,
    class = bsl::enable_if_t<bsl::is_convertible_v<ALLOC *, DEFAULT_ALLOCATOR>>
    >
multimap(std::initializer_list<pair<const KEY, VALUE>>, ALLOC *)
-> multimap<KEY, VALUE>;
#endif
 
// FREE OPERATORS
 
/// Return `true` if the specified `lhs` and `rhs` objects have the same
/// value, and `false` otherwise.  Two `multimap` objects `lhs` and `rhs`
/// have the same value if they have the same number of key-value pairs, and
/// each element in the ordered sequence of key-value pairs of `lhs` has the
/// same value as the corresponding element in the ordered sequence of
/// key-value pairs of `rhs`.  This method requires that the (template
/// parameter) types `KEY` and `VALUE` both be `equality-comparable` (see
/// {Requirements on `KEY` and `VALUE`}).
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator==(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
 
#ifndef BSLS_COMPILERFEATURES_SUPPORT_THREE_WAY_COMPARISON
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator!=(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
    // Return 'true' if the specified 'lhs' and 'rhs' objects do not have the
    // same value, and 'false' otherwise.  Two 'multimap' objects 'lhs' and
    // 'rhs' do not have the same value if they do not have the same number of
    // key-value pairs, or some element in the ordered sequence of key-value
    // pairs of 'lhs' does not have the same value as the corresponding element
    // in the ordered sequence of key-value pairs of 'rhs'.  This method
    // requires that the (template parameter) types 'KEY' and 'VALUE' both be
    // 'equality-comparable' (see {Requirements on 'KEY' and 'VALUE'}).
#endif
 
#ifdef BSLALG_SYNTHTHREEWAYUTIL_AVAILABLE
 
/// Perform a lexicographic three-way comparison of the specified `lhs` and
/// the specified `rhs` maps by using the comparison operators of
/// `bsl::pair<const KEY, VALUE>` on each element; return the result of that
/// comparison.
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
BloombergLP::bslalg::SynthThreeWayUtil::Result<pair<const KEY, VALUE>>
operator<=>(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
            const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
 
#else
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator<(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
               const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
    // Return 'true' if the value of the specified 'lhs' multimap is
    // lexicographically less than that of the specified 'rhs' multimap, and
    // 'false' otherwise.  Given iterators 'i' and 'j' over the respective
    // sequences '[lhs.begin() .. lhs.end())' and '[rhs.begin() .. rhs.end())',
    // the value of multimap 'lhs' is lexicographically less than that of
    // multimap 'rhs' if 'true == *i < *j' for the first pair of corresponding
    // iterator positions where '*i < *j' and '*j < *i' are not both 'false'.
    // If no such corresponding iterator position exists, the value of 'lhs' is
    // lexicographically less than that of 'rhs' if 'lhs.size() < rhs.size()'.
    // This method requires that 'operator<', inducing a total order, be
    // defined for 'value_type'.
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator>(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
               const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
    // Return 'true' if the value of the specified 'lhs' multimap is
    // lexicographically greater than that of the specified 'rhs' multimap, and
    // 'false' otherwise.  The value of multimap 'lhs' is lexicographically
    // greater than that of multimap 'rhs' if 'rhs' is lexicographically less
    // than 'lhs' (see 'operator<').  This method requires that 'operator<',
    // inducing a total order, be defined for 'value_type'.  Note that this
    // operator returns 'rhs < lhs'.
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator<=(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
    // Return 'true' if the value of the specified 'lhs' multimap is
    // lexicographically less than or equal to that of the specified 'rhs'
    // multimap, and 'false' otherwise.  The value of multimap 'lhs' is
    // lexicographically less than or equal to that of multimap 'rhs' if 'rhs'
    // is not lexicographically less than 'lhs' (see 'operator<').  This method
    // requires that 'operator<', inducing a total order, be defined for
    // 'value_type'.  Note that this operator returns '!(rhs < lhs)'.
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
bool operator>=(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs);
    // Return 'true' if the value of the specified 'lhs' multimap is
    // lexicographically greater than or equal to that of the specified 'rhs'
    // multimap, and 'false' otherwise.  The value of multimap 'lhs' is
    // lexicographically greater than or equal to that of multimap 'rhs' if
    // 'lhs' is not lexicographically less than 'rhs' (see 'operator<').  This
    // method requires that 'operator<', inducing a total order, be defined for
    // 'value_type'.  Note that this operator returns '!(lhs < rhs)'.
 
#endif  // BSLALG_SYNTHTHREEWAYUTIL_AVAILABLE
 
// FREE FUNCTIONS
 
/// Exchange the value and comparator of the specified `a` object with those
/// of the specified `b` object; also exchange the allocator of `a` with
/// that of `b` if the (template parameter) type `ALLOCATOR` has the
/// `propagate_on_container_swap` trait, and do not modify either allocator
/// otherwise.  This function provides the no-throw exception-safety
/// guarantee if and only if the (template parameter) type `COMPARATOR`
/// provides a no-throw swap operation, and provides the basic
/// exception-safety guarantee otherwise; if an exception is thrown, both
/// objects are left in valid but unspecified states.  This operation has
/// `O[1]` complexity if either `a` was created with the same allocator as
/// `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait;
/// otherwise, it has `O[n + m]` complexity, where `n` and `m` are the
/// number of elements in `a` and `b`, respectively.  Note that this
/// function's support for swapping objects created with different
/// allocators when `ALLOCATOR` does not have the
/// `propagate_on_container_swap` trait is a departure from the C++
/// Standard.
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
void swap(multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& a,
          multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& b)
             BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(false);
 
// ============================================================================
//                      INLINE FUNCTION DEFINITIONS
// ============================================================================
 
                             // -----------------
                             // class DataWrapper
                             // -----------------
 
// CREATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::DataWrapper::DataWrapper(
                                              const COMPARATOR& comparator,
                                              const ALLOCATOR&  basicAllocator)
: ::bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::Comparator(comparator)
, d_pool(basicAllocator)
{
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::DataWrapper::DataWrapper(
                          BloombergLP::bslmf::MovableRef<DataWrapper> original)
: ::bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::Comparator(
                                    MoveUtil::access(original).keyComparator())
, d_pool(MoveUtil::move(MoveUtil::access(original).d_pool))
{
}
 
// MANIPULATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::NodeFactory&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::DataWrapper::nodeFactory()
{
    return d_pool;
}
 
// ACCESSORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
const typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::NodeFactory&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::DataWrapper::nodeFactory() const
{
    return d_pool;
}
 
                             // -----------------------------
                             // class multimap::value_compare
                             // -----------------------------
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::value_compare::value_compare(
                                                         COMPARATOR comparator)
: comp(comparator)
{
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::value_compare::operator()(
                                                     const value_type& x,
                                                     const value_type& y) const
{
    return comp(x.first, y.first);
}
 
                             // --------------
                             // class multimap
                             // --------------
 
// PRIVATE MANIPULATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::Comparator&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::comparator()
{
    return d_compAndAlloc;
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::NodeFactory&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::nodeFactory()
{
    return d_compAndAlloc.nodeFactory();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::quickSwapExchangeAllocators(
                                                               multimap& other)
{
    BloombergLP::bslalg::RbTreeUtil::swap(&d_tree, &other.d_tree);
    nodeFactory().swapExchangeAllocators(other.nodeFactory());
 
    // 'DataWrapper' contains a 'NodeFactory' object and inherits from
    // 'Comparator'.  If the empty-base-class optimization has been applied to
    // 'Comparator', then we must not call 'swap' on it because
    // 'sizeof(Comparator) > 0' and, therefore, we will incorrectly swap bytes
    // of the 'NodeFactory' members!
 
    if (sizeof(NodeFactory) != sizeof(DataWrapper)) {
        comparator().swap(other.comparator());
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::quickSwapRetainAllocators(
                                                               multimap& other)
{
    BloombergLP::bslalg::RbTreeUtil::swap(&d_tree, &other.d_tree);
    nodeFactory().swapRetainAllocators(other.nodeFactory());
 
    // See 'quickSwapExchangeAllocators' (above).
 
    if (sizeof(NodeFactory) != sizeof(DataWrapper)) {
        comparator().swap(other.comparator());
    }
}
 
// PRIVATE ACCESSORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
const typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::Comparator&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::comparator() const
{
    return d_compAndAlloc;
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
const typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::NodeFactory&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::nodeFactory() const
{
    return d_compAndAlloc.nodeFactory();
}
 
// CREATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap()
: d_compAndAlloc(COMPARATOR(), ALLOCATOR())
, d_tree()
{
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                                               const ALLOCATOR& basicAllocator)
: d_compAndAlloc(COMPARATOR(), basicAllocator)
, d_tree()
{
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(const multimap& original)
: d_compAndAlloc(original.comparator().keyComparator(),
                 AllocatorTraits::select_on_container_copy_construction(
                                           original.nodeFactory().allocator()))
, d_tree()
{
    if (0 < original.size()) {
        nodeFactory().reserveNodes(original.size());
        BloombergLP::bslalg::RbTreeUtil::copyTree(&d_tree,
                                                  original.d_tree,
                                                  &nodeFactory());
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                             BloombergLP::bslmf::MovableRef<multimap> original)
: d_compAndAlloc(MoveUtil::move(MoveUtil::access(original).d_compAndAlloc))
, d_tree()
{
    multimap& lvalue = original;
    BloombergLP::bslalg::RbTreeUtil::swap(&d_tree, &lvalue.d_tree);
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                 const multimap&                                original,
                 const typename type_identity<ALLOCATOR>::type& basicAllocator)
: d_compAndAlloc(original.comparator().keyComparator(), basicAllocator)
, d_tree()
{
    if (0 < original.size()) {
        nodeFactory().reserveNodes(original.size());
        BloombergLP::bslalg::RbTreeUtil::copyTree(&d_tree,
                                                  original.d_tree,
                                                  &nodeFactory());
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                 BloombergLP::bslmf::MovableRef<multimap> original,
                 const typename type_identity<ALLOCATOR>::type& basicAllocator)
: d_compAndAlloc(MoveUtil::access(original).comparator().keyComparator(),
                 basicAllocator)
, d_tree()
{
    multimap& lvalue = original;
 
    if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(
              nodeFactory().allocator() == lvalue.nodeFactory().allocator())) {
        d_compAndAlloc.nodeFactory().adopt(
                          MoveUtil::move(lvalue.d_compAndAlloc.nodeFactory()));
        BloombergLP::bslalg::RbTreeUtil::swap(&d_tree, &lvalue.d_tree);
    }
    else {
        if (0 < lvalue.size()) {
            nodeFactory().reserveNodes(lvalue.size());
            BloombergLP::bslalg::RbTreeUtil::moveTree(&d_tree,
                                                      &lvalue.d_tree,
                                                      &nodeFactory(),
                                                      &lvalue.nodeFactory());
        }
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class INPUT_ITERATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                                              INPUT_ITERATOR    first,
                                              INPUT_ITERATOR    last,
                                              const COMPARATOR& comparator,
                                              const ALLOCATOR&  basicAllocator)
: d_compAndAlloc(comparator, basicAllocator)
, d_tree()
{
    if (first != last) {
 
        size_type numElements =
                BloombergLP::bslstl::IteratorUtil::insertDistance(first, last);
 
        if (0 < numElements) {
            nodeFactory().reserveNodes(numElements);
        }
 
        BloombergLP::bslalg::RbTreeUtilTreeProctor<NodeFactory> proctor(
                                                               &d_tree,
                                                               &nodeFactory());
 
        // The following loop guarantees amortized linear time to insert an
        // ordered sequence of values (as required by the standard).   If the
        // values are in sorted order, we are guaranteed the next node can be
        // inserted as the right child of the previous node, and can call
        // 'insertAt'.
 
        insert(*first);
        BloombergLP::bslalg::RbTreeNode *prevNode = d_tree.rootNode();
        while (++first != last) {
            // The values are not in order, so insert them normally.
 
            const value_type& value = *first;
            if (this->comparator()(value.first, *prevNode)) {
                insert(value);
                insert(++first, last);
                break;
            }
            BloombergLP::bslalg::RbTreeNode *node =
                nodeFactory().emplaceIntoNewNode(value);
            BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                                      prevNode,
                                                      false,
                                                      node);
            prevNode = node;
        }
        proctor.release();
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class INPUT_ITERATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                                              INPUT_ITERATOR    first,
                                              INPUT_ITERATOR    last,
                                              const ALLOCATOR&  basicAllocator)
: d_compAndAlloc(COMPARATOR(), basicAllocator)
, d_tree()
{
    if (first != last) {
 
        size_type numElements =
                BloombergLP::bslstl::IteratorUtil::insertDistance(first, last);
 
        if (0 < numElements) {
            nodeFactory().reserveNodes(numElements);
        }
 
        BloombergLP::bslalg::RbTreeUtilTreeProctor<NodeFactory> proctor(
                                                               &d_tree,
                                                               &nodeFactory());
 
        // The following loop guarantees amortized linear time to insert an
        // ordered sequence of values (as required by the standard).   If the
        // values are in sorted order, we are guaranteed the next node can be
        // inserted as the right child of the previous node, and can call
        // 'insertAt'.
 
        insert(*first);
        BloombergLP::bslalg::RbTreeNode *prevNode = d_tree.rootNode();
        while (++first != last) {
            // The values are not in order, so insert them normally.
 
            const value_type& value = *first;
            if (this->comparator()(value.first, *prevNode)) {
                insert(value);
                insert(++first, last);
                break;
            }
            BloombergLP::bslalg::RbTreeNode *node =
                nodeFactory().emplaceIntoNewNode(value);
            BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                                      prevNode,
                                                      false,
                                                      node);
            prevNode = node;
        }
        proctor.release();
    }
}
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                              std::initializer_list<value_type> values,
                              const COMPARATOR&                 comparator,
                              const ALLOCATOR&                  basicAllocator)
: multimap(values.begin(), values.end(), comparator, basicAllocator)
{
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::multimap(
                              std::initializer_list<value_type> values,
                              const ALLOCATOR&                  basicAllocator)
: multimap(values.begin(), values.end(), COMPARATOR(), basicAllocator)
{
}
#endif
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::~multimap()
{
    clear();
}
 
// MANIPULATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::operator=(const multimap& rhs)
{
    if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(this != &rhs)) {
        if (AllocatorTraits::propagate_on_container_copy_assignment::value) {
            multimap other(rhs, rhs.nodeFactory().allocator());
            quickSwapExchangeAllocators(other);
        }
        else {
            multimap other(rhs, nodeFactory().allocator());
            quickSwapRetainAllocators(other);
        }
    }
    return *this;
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::operator=(
                                  BloombergLP::bslmf::MovableRef<multimap> rhs)
    BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(
                            AllocatorTraits::is_always_equal::value &&
                            std::is_nothrow_move_assignable<COMPARATOR>::value)
{
    multimap& lvalue = rhs;
 
    if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(this != &lvalue)) {
        if (nodeFactory().allocator() == lvalue.nodeFactory().allocator()) {
            multimap other(MoveUtil::move(lvalue));
            quickSwapRetainAllocators(other);
        }
        else if (
              AllocatorTraits::propagate_on_container_move_assignment::value) {
            multimap other(MoveUtil::move(lvalue));
            quickSwapExchangeAllocators(other);
        }
        else {
            multimap other(MoveUtil::move(lvalue), nodeFactory().allocator());
            quickSwapRetainAllocators(other);
        }
    }
    return *this;
}
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>&
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::operator=(
                                      std::initializer_list<value_type> values)
{
    clear();
    insert(values.begin(), values.end());
    return *this;
}
#endif
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::begin() BSLS_KEYWORD_NOEXCEPT
{
    return iterator(d_tree.firstNode());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::end() BSLS_KEYWORD_NOEXCEPT
{
    return iterator(d_tree.sentinel());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::rbegin() BSLS_KEYWORD_NOEXCEPT
{
    return reverse_iterator(end());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::rend() BSLS_KEYWORD_NOEXCEPT
{
    return reverse_iterator(begin());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::insert(const value_type& value)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(&leftChild,
                                                            &d_tree,
                                                            this->comparator(),
                                                            value.first);
 
    BloombergLP::bslalg::RbTreeNode *node =
        nodeFactory().emplaceIntoNewNode(value);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class INPUT_ITERATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::insert(INPUT_ITERATOR first,
                                                         INPUT_ITERATOR last)
{
    ///Implementation Notes
    ///--------------------
    // First, consume currently held free nodes.  Tf those nodes are
    // insufficient *and* one can calculate the remaining number of elements,
    // then reserve exactly that many free nodes.  There is no more than one
    // call to 'reserveNodes' per invocation of this method, hence the use of
    // 'BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY'.
 
    const bool canCalculateInsertDistance =
             is_convertible<typename
                            iterator_traits<INPUT_ITERATOR>::iterator_category,
                            forward_iterator_tag>::value;
 
    while (first != last) {
        if (canCalculateInsertDistance
        && BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(
                                              !nodeFactory().hasFreeNodes())) {
            const size_type numElements =
                BloombergLP::bslstl::IteratorUtil::insertDistance(first, last);
 
            nodeFactory().reserveNodes(numElements);
        }
        insert(*first);
        ++first;
    }
}
 
#if defined(BSLS_PLATFORM_CMP_SUN) && BSLS_PLATFORM_CMP_VERSION < 0x5130
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::insert(const_iterator first,
                                                         const_iterator last)
{
    while (first != last) {
        insert(*first);
        ++first;
    }
}
#endif
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::insert(const_iterator    hint,
                                                    const value_type& value)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *hintNode =
                const_cast<BloombergLP::bslalg::RbTreeNode *>(hint.node());
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(&leftChild,
                                                            &d_tree,
                                                            this->comparator(),
                                                            value.first,
                                                            hintNode);
 
    BloombergLP::bslalg::RbTreeNode *node =
        nodeFactory().emplaceIntoNewNode(value);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
 
#if defined(BSLS_COMPILERFEATURES_SUPPORT_GENERALIZED_INITIALIZERS)
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::insert(
                                      std::initializer_list<value_type> values)
{
    insert(values.begin(), values.end());
}
#endif
 
#if BSLS_COMPILERFEATURES_SIMULATE_VARIADIC_TEMPLATES
// {{{ BEGIN GENERATED CODE
// Command line: sim_cpp11_features.pl bslstl_multimap.h
#ifndef BSLSTL_MULTIMAP_VARIADIC_LIMIT
#define BSLSTL_MULTIMAP_VARIADIC_LIMIT 2
#endif
#ifndef BSLSTL_MULTIMAP_VARIADIC_LIMIT_B
#define BSLSTL_MULTIMAP_VARIADIC_LIMIT_B BSLSTL_MULTIMAP_VARIADIC_LIMIT
#endif
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 0
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace(
                               )
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        );
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                               &leftChild,
                               &d_tree,
                               this->comparator(),
                               static_cast<const Node *>(node)->value().first);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 0
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 1
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class Args_1>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace(
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args_1, args_1));
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                               &leftChild,
                               &d_tree,
                               this->comparator(),
                               static_cast<const Node *>(node)->value().first);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 1
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 2
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class Args_1,
          class Args_2>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace(
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1,
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_2) args_2)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args_1, args_1),
        BSLS_COMPILERFEATURES_FORWARD(Args_2, args_2));
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                               &leftChild,
                               &d_tree,
                               this->comparator(),
                               static_cast<const Node *>(node)->value().first);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 2
 
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 0
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace_hint(const_iterator hint)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        );
 
    BloombergLP::bslalg::RbTreeNode *hintNode =
                    const_cast<BloombergLP::bslalg::RbTreeNode *>(hint.node());
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                                &leftChild,
                                &d_tree,
                                this->comparator(),
                                static_cast<const Node *>(node)->value().first,
                                hintNode);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 0
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 1
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class Args_1>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace_hint(const_iterator hint,
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args_1, args_1));
 
    BloombergLP::bslalg::RbTreeNode *hintNode =
                    const_cast<BloombergLP::bslalg::RbTreeNode *>(hint.node());
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                                &leftChild,
                                &d_tree,
                                this->comparator(),
                                static_cast<const Node *>(node)->value().first,
                                hintNode);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 1
 
#if BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 2
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class Args_1,
          class Args_2>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace_hint(const_iterator hint,
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_1) args_1,
                              BSLS_COMPILERFEATURES_FORWARD_REF(Args_2) args_2)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args_1, args_1),
        BSLS_COMPILERFEATURES_FORWARD(Args_2, args_2));
 
    BloombergLP::bslalg::RbTreeNode *hintNode =
                    const_cast<BloombergLP::bslalg::RbTreeNode *>(hint.node());
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                                &leftChild,
                                &d_tree,
                                this->comparator(),
                                static_cast<const Node *>(node)->value().first,
                                hintNode);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
#endif  // BSLSTL_MULTIMAP_VARIADIC_LIMIT_B >= 2
 
#else
// The generated code below is a workaround for the absence of perfect
// forwarding in some compilers.
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class... Args>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace(
                               BSLS_COMPILERFEATURES_FORWARD_REF(Args)... args)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args, args)...);
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                               &leftChild,
                               &d_tree,
                               this->comparator(),
                               static_cast<const Node *>(node)->value().first);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
template <class... Args>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::emplace_hint(const_iterator hint,
                               BSLS_COMPILERFEATURES_FORWARD_REF(Args)... args)
{
    bool leftChild;
 
    BloombergLP::bslalg::RbTreeNode *node = nodeFactory().emplaceIntoNewNode(
        BSLS_COMPILERFEATURES_FORWARD(Args, args)...);
 
    BloombergLP::bslalg::RbTreeNode *hintNode =
                    const_cast<BloombergLP::bslalg::RbTreeNode *>(hint.node());
 
    BloombergLP::bslalg::RbTreeNode *insertLocation =
        BloombergLP::bslalg::RbTreeUtil::findInsertLocation(
                                &leftChild,
                                &d_tree,
                                this->comparator(),
                                static_cast<const Node *>(node)->value().first,
                                hintNode);
 
    BloombergLP::bslalg::RbTreeUtil::insertAt(&d_tree,
                                              insertLocation,
                                              leftChild,
                                              node);
    return iterator(node);
}
 
// }}} END GENERATED CODE
#endif
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::erase(const_iterator position)
{
    BSLS_ASSERT_SAFE(position != end());
 
    BloombergLP::bslalg::RbTreeNode *node =
                const_cast<BloombergLP::bslalg::RbTreeNode *>(position.node());
    BloombergLP::bslalg::RbTreeNode *result =
                                   BloombergLP::bslalg::RbTreeUtil::next(node);
    BloombergLP::bslalg::RbTreeUtil::remove(&d_tree, node);
    nodeFactory().deleteNode(node);
    return iterator(result);
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::erase(iterator position)
{
    return erase(const_iterator(position));
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::size_type
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::erase(const key_type& key)
{
    size_type      count = 0;
    const_iterator first = find(key);
 
    if (first != end()) {
        const_iterator last = upper_bound(key);
        while (first != last) {
            first = erase(first);
            ++count;
        }
    }
    return count;
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::erase(const_iterator first,
                                                   const_iterator last)
{
    while (first != last) {
        first = erase(first);
    }
    return iterator(last.node());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::swap(multimap& other)
    BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(
                                  AllocatorTraits::is_always_equal::value &&
                                  bsl::is_nothrow_swappable<COMPARATOR>::value)
{
    if (AllocatorTraits::propagate_on_container_swap::value) {
        quickSwapExchangeAllocators(other);
    }
    else {
        // C++11 behavior for member 'swap': undefined for unequal allocators.
        // BSLS_ASSERT(allocator() == other.allocator());
 
        if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(
               nodeFactory().allocator() == other.nodeFactory().allocator())) {
            quickSwapRetainAllocators(other);
        }
        else {
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;
 
            multimap toOtherCopy(MoveUtil::move(*this),
                                 other.nodeFactory().allocator());
            multimap toThisCopy( MoveUtil::move(other),
                                 nodeFactory().allocator());
 
            this->quickSwapRetainAllocators(toThisCopy);
            other.quickSwapRetainAllocators(toOtherCopy);
        }
    }
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::clear() BSLS_KEYWORD_NOEXCEPT
{
    BSLS_ASSERT_SAFE(d_tree.firstNode());
 
    if (d_tree.rootNode()) {
        BSLS_ASSERT_SAFE(0 < d_tree.numNodes());
        BSLS_ASSERT_SAFE(d_tree.firstNode() != d_tree.sentinel());
 
        BloombergLP::bslalg::RbTreeUtil::deleteTree(&d_tree, &nodeFactory());
    }
#if defined(BSLS_ASSERT_SAFE_IS_USED)
    else {
        BSLS_ASSERT_SAFE(0 == d_tree.numNodes());
        BSLS_ASSERT_SAFE(d_tree.firstNode() == d_tree.sentinel());
    }
#endif
}
 
// ACCESSORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::allocator_type
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::get_allocator() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return nodeFactory().allocator();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::begin() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return cbegin();
}
 
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::end() const BSLS_KEYWORD_NOEXCEPT
{
    return cend();
}
 
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::rbegin() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return crbegin();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::rend() const BSLS_KEYWORD_NOEXCEPT
{
    return crend();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::cbegin() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return const_iterator(d_tree.firstNode());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::cend() const BSLS_KEYWORD_NOEXCEPT
{
    return const_iterator(d_tree.sentinel());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::crbegin() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return const_reverse_iterator(end());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::const_reverse_iterator
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::crend() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return const_reverse_iterator(begin());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::contains(
                                                     const key_type& key) const
{
    return find(key) != end();
}
 
// capacity:
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::empty() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return 0 == d_tree.numNodes();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::size_type
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::size() const BSLS_KEYWORD_NOEXCEPT
{
    return d_tree.numNodes();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::size_type
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::max_size() const
                                                          BSLS_KEYWORD_NOEXCEPT
{
    return AllocatorTraits::max_size(get_allocator());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::key_compare
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::key_comp() const
{
    return comparator().keyComparator();
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
typename multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::value_compare
multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>::value_comp() const
{
    return value_compare(key_comp());
}
 
}  // close namespace bsl
 
// FREE OPERATORS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator==(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return BloombergLP::bslalg::RangeCompare::equal(lhs.begin(),
                                                    lhs.end(),
                                                    lhs.size(),
                                                    rhs.begin(),
                                                    rhs.end(),
                                                    rhs.size());
}
 
#ifndef BSLS_COMPILERFEATURES_SUPPORT_THREE_WAY_COMPARISON
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator!=(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return !(lhs == rhs);
}
#endif
 
#ifdef BSLALG_SYNTHTHREEWAYUTIL_AVAILABLE
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
BloombergLP::bslalg::SynthThreeWayUtil::Result<bsl::pair<const KEY, VALUE>>
bsl::operator<=>(const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                 const multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return bsl::lexicographical_compare_three_way(
                              lhs.begin(),
                              lhs.end(),
                              rhs.begin(),
                              rhs.end(),
                              BloombergLP::bslalg::SynthThreeWayUtil::compare);
}
 
#else
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator<(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return 0 > BloombergLP::bslalg::RangeCompare::lexicographical(lhs.begin(),
                                                                  lhs.end(),
                                                                  lhs.size(),
                                                                  rhs.begin(),
                                                                  rhs.end(),
                                                                  rhs.size());
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator>(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return rhs < lhs;
}
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator<=(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return !(rhs < lhs);
}
 
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
bool bsl::operator>=(
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& lhs,
                   const bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& rhs)
{
    return !(lhs < rhs);
}
 
#endif  // BSLALG_SYNTHTHREEWAYUTIL_AVAILABLE
 
// FREE FUNCTIONS
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
inline
void bsl::swap(bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& a,
               bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>& b)
                                     BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(false)
{
    a.swap(b);
}
 
// ============================================================================
//                                TYPE TRAITS
// ============================================================================
 
// Type traits for STL *ordered* containers:
//: o An ordered container defines STL iterators.
//: o An ordered container uses 'bslma' allocators if the (template parameter)
//:   type 'ALLOCATOR' is convertible from 'bslma::Allocator *'.
 
 
 
namespace bslalg {
 
template <class KEY, class VALUE, class COMPARATOR, class ALLOCATOR>
struct HasStlIterators<bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR> >
    : bsl::true_type
{
};
 
}  // close namespace bslalg
 
namespace bslma {
 
template <class KEY,   class VALUE, class COMPARATOR, class ALLOCATOR>
struct UsesBslmaAllocator<bsl::multimap<KEY, VALUE, COMPARATOR, ALLOCATOR> >
    : bsl::is_convertible<Allocator*, ALLOCATOR>
{};
 
}  // close namespace bslma
 
 
 
#else // if ! defined(DEFINED_BSLSTL_MULTIMAP_H)
# error Not valid except when included from bslstl_multimap.h
#endif // ! defined(COMPILING_BSLSTL_MULTIMAP_H)
 
#endif // ! defined(INCLUDED_BSLSTL_MULTIMAP_CPP03)
 
// ----------------------------------------------------------------------------
// Copyright 2019 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */