# `basic_assoc_cntnr` Interface

A basic associative container, specialized for the "map" 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.
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.

-

    Data

Data type.

-

    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

    data_enabled_ms_tag

The mapping-semantics category of the container.

## 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<
        Data>::other::value_type

Data type.

    data_reference

    typename allocator::template rebind<
        Data>::other::reference

Data reference type.

    const_data_reference

    typename allocator::template rebind<
        Data>::other::const_reference

Const data reference type.

    data_pointer

    typename allocator::template rebind<
        Data>::other::pointer

Data pointer type.

    const_data_pointer

    typename allocator::template rebind<
        Data>::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, data_type> >::other::value_type

Data type.

    reference

    typename allocator::rebind<
        std::pair<const key_type, data_type> >::other::reference

Value reference type.

    const_reference

    typename allocator::rebind<
        std::pair<const key_type, data_type> >::other::const_reference

Const value reference type.

    pointer

    typename allocator::rebind<
        std::pair<const key_type, data_type> >::other::pointer

Value pointer type.

    const_pointer

    typename allocator::rebind<
        std::pair<const key_type, data_type> >::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.

## 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.