# `basic_assoc_cntnr` Interface

A basic associative container specialized for the "multimap" case.

1. `assoc_cntnr.hpp`
2. Template parameters.
3. Public Types and Constants:
   1. General container definitions.
   2. Categories.
   3. Policy definitions.
   4. Key-type definitions.
   5. Data-type definitions.
   6. Value-type definitions.
   7. Iterator definitions.
   8. Mapping-level definitions.
4. Public Methods:
   1. Constructors, destructor, and related.
   2. Information methods.
   3. Insert methods.
   4. Find methods.
   5. Erase methods.
   6. Iteration methods.

## Template parameters.

Parameter | Description | Default Value
    Key
| Key type. | -
    Cntnr
| (Associative) container to which each data is mapped. | -
    DS_Tag
| Data structure tag. | -
    Policy_Tl
| Policy typelist. | -
    Allocator
| Allocator type. | -

## General container definitions.

Type | Definition | Description
    size_type
    typename Allocator::size_type
| Size type.
    difference_type
    typename Allocator::difference_type
| Difference type.

## Categories.

Type | Definition | Description
    ds_category
    DS_Tag
| The underlying data-structure tag of the container. comment =
    ms_category
    compound_data_enabled_ms_tag
| The mapping-semantics category of the container. override_from =

## Policy definitions.

Type | Definition | Description
    allocator
    Allocator
| Allocator type.

## Key-type definitions.

Type | Definition | Description
    key_type
    typename allocator::template rebind<
        Key>::other::value_type
| Key type.
    key_reference
    typename allocator::template rebind<
        Key>::other::reference
| Key reference type.
    const_key_reference
    typename allocator::template rebind<
        Key>::other::const_reference
| Const key reference type.
    key_pointer
    typename allocator::template rebind<
        Key>::other::pointer
| Key pointer type.
    const_key_pointer
    typename allocator::template rebind<
        Key>::other::const_pointer
| Const key pointer type.

## Data-type definitions.

Type | Definition | Description
    data_type
    typename allocator::template rebind<
        Cntnr>::other::value_type
| Data type.
    data_reference
    typename allocator::template rebind<
        Cntnr>::other::reference
| Data reference type.
    const_data_reference
    typename allocator::template rebind<
        Cntnr>::other::const_reference
| Const data reference type.
    data_pointer
    typename allocator::template rebind<
        Cntnr>::other::pointer
| Data pointer type.
    const_data_pointer
    typename allocator::template rebind<
        Cntnr>::other::const_pointer
| Const data pointer type.

## Value-type definitions.

Types pertaining to the domain of the relationships of the table.

This is explained in Data Types, Value Types, Mapped Data Types, and Mapped Value Types and Mapped Data Types and Mapped Value Types.

Type | Definition | Description
    value_type
    typename allocator::rebind<
        std::pair<const key_type, Cntnr>::other::value_type
| Data type.
    reference
    typename allocator::rebind<
        std::pair<const key_type, Cntnr>::other::reference
| Value reference type.
    const_reference
    typename allocator::rebind<
        std::pair<const key_type, Cntnr>::other::const_reference
| Const value reference type.
    pointer
    typename allocator::rebind<
        std::pair<const key_type, Cntnr>::other::pointer
| Value pointer type.
    const_pointer
    typename allocator::rebind<
        std::pair<const key_type, Cntnr>::other::const_pointer
| Const Value pointer type.

## Iterator definitions.

Type | Definition | Description
    const_find_iterator
    Underlying data-structure's const find-type iterator.
| Const find-type iterator.
    find_iterator
    Underlying data-structure's find-type iterator.
| Find-type iterator.
    const_iterator
    Underlying data-structure's const range-type iterator.
| Const range-type iterator.
    iterator
    Underlying data-structure's range-type iterator.
| Range-type iterator.

## Mapping-level definitions.

See Mapping-Semantics.

## Constructors, destructor, and related.

Method | Description
    virtual
      ~basic_assoc_cntnr
      ()
| Destructor.

## Information methods.

Method | Description
    inline size_type
      size
      () const
| Returns the number of distinct `value_type` objects the container object is storing.
    inline size_type
      max_size
      () const
| Returns an upper bound on the number of distinct `value_type` objects this container can store.
    inline bool
      empty
      () const
| Returns whether the container object is not storing any `value_type` objects.
    inline static const_key_reference
      extract_key
      (const_reference r_val)
| Extracts a key from a `value_type`.

## Insert methods.

Method | Description
    inline std::pair<find_iterator, bool>
      insert
      (const_reference r_val)
| Inserts a `value_type` object. If no `value_type` with `r_val`'s key was in the container object, inserts and returns (`find_iterator` object associated with `r_val`, `true`); otherwise just returns (`find_iterator` object associated with `r_val`'s key, `false`).
    inline data_reference
      operator[]
      (const_key_reference r_key)
| Inserts (if necessary) a `value_type` object associated with `r_key`. Returns a `data_reference` associated with `r_key`

## Find methods.

Method | Description
    inline find_iterator
      find
      (const_key_reference r_key)
| Returns the `find_iterator` corresponding to the `value_type` with `r_key` as its key, or the `find_iterator` corresponding to the just-after-last entry if no such `value_type`.
    inline const_find_iterator
      find
      (const_key_reference r_key) const
| Returns the `const_find_iterator` corresponding to the `value_type` with `r_key` as its key, or the `const_find_iterator` corresponding to the just-after-last entry if no such `value_type`.
    inline const_data_reference
      operator[]
      (const_key_reference r_key) const
| Inserts (if necessary) a `value_type` object associated with `r_key`. Returns a `data_reference` associated with `r_key`

## Erase methods.

Method | Description
    inline size_type
      erase
      (const_key_reference r_key)
| Erases the `value_type` associated with `r_key`; returns the number of `value_type`s erased (0 or 1).
    template<
      class Pred>
    inline size_type
      erase_if
      (Pred prd)
| Erases any `value_type` satisfying the predicate `prd` (this is transactional, either all matching `value_type`s are erased, or, if an exception is thrown (for types whose erase can throw an exception) none); returns the number of `value_type`s erased.
    void
      clear
      ()
| Clears the container object.

## Iteration methods.

Method | Description
    inline iterator
      begin
      ()
| Returns an `iterator` corresponding to the first `value_type` in the container.
    inline const_iterator
      begin
      () const
| Returns a `const_iterator` corresponding to the first `value_type` in the container.
    inline iterator
      end
      ()
| Returns an `iterator` corresponding to the just-after_last `value_type` in the container.
    inline const_iterator
      end
      () const
| Returns a `const_iterator` corresponding to the just-after_last `value_type` in the container.