basic_tree_assoc_cntnr Interface

# `basic_tree_assoc_cntnr` Interface

A basic tree-based associative container.

1. `assoc_cntnr.hpp`
2. Template parameters.
3. Base classes.
4. Public Types and Constants:
   1. General container definitions.
   2. Key-type definitions.
   3. Policy definitions.
   4. Iterator definitions.
5. Public Methods:
   1. Constructors, destructor, and related.
   2. Policy access methods.
   3. Erase methods.
   4. Iteration methods.
   5. Node-Iteration methods.
   6. Split and join methods.

## Template parameters.

Parameter | Description | Default Value
    Key
| Key type. | -
    Data
| Data type. | -
    Cmp_Fn
| Comparison functor. | -
    DS_Tag,
| Data-structure tag. | -
    Node_Updator
| Node updator type. Node Invariants explains this concept. | -
    Allocator
| Allocator type. | -

## Base classes.

Class | Derivation Type
    Node_Updator
| public

## General container definitions.

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

## Key-type definitions.

Type | Definition | Description
    const_key_reference
    typename Allocator::template rebind<
        Key>::other::const_reference
| Const key reference type.

## Policy definitions.

Type | Definition | Description
    cmp_fn
    Cmp_Fn
| Comparison functor type.
    node_updator
    Node_Updator
| Node updator type.

## Iterator definitions.

Type | Definition | Description
    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.
    const_reverse_iterator
    Underlying data-structure's const reverse range-type iterator.
| Const reverse range-type iterator.
    reverse_iterator
    Underlying data-structure's reverse range-type iterator.
| Reverse range-type iterator.
    const_node_iterator
    basic_tree_assoc_cntnr::const_node_iterator
| Const node iterator.
    node_iterator
    basic_tree_assoc_cntnr::node_iterator
| Node iterator.

## Constructors, destructor, and related.

Method | Description
    virtual
      ~basic_tree_assoc_cntnr
      ()
| Destructor.

## Policy access methods.

Method | Description
    cmp_fn &
      get_cmp_fn
      ()
| Access to the `cmp_fn` object.
    const cmp_fn &
      get_cmp_fn
      () const
| Const access to the `cmp_fn` object.
    node_updator &
      get_node_updator
      ()
| Access to the `node_updator` object.
    const node_updator &
      get_node_updator
      () const
| Const access to the `node_updator` object.

## 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_types erased (0 or 1).
    inline iterator
      erase
      (iterator it)
| Erases the value_type corresponding to the `iterator` `it`. Returns the `iterator` corresponding to the next value_type.
    inline reverse_iterator
      erase
      (reverse_iterator it)
| Erases the value_type corresponding to the `reverse_iterator` `it`. Returns the `reverse_iterator` corresponding to the previous value_type.

## Iteration methods.

Method | Description
    inline reverse_iterator
      rbegin
      ()
| Returns a `reverse_iterator` corresponding to the last value_type in the container.
    inline const_reverse_iterator
      rbegin
      () const
| Returns a `const_reverse_iterator` corresponding to the last value_type in the container.
    inline reverse_iterator
      rend
      ()
| Returns a `reverse_iterator` corresponding to the just-before-first value_type in the container.
    inline const_reverse_iterator
      rend
      () const
| Returns a `const_reverse_iterator` corresponding to the just-before-first value_type in the container.

## Node-Iteration methods.

Method | Description
    inline node_iterator
      node_begin
      ()
| Returns a `node_iterator` corresponding to the value_type at the root of the tree.
    inline const_node_iterator
      node_begin
      () const
| Returns a `const_node_iterator` corresponding to the value_type at the root of the tree.
    inline node_iterator
      node_end
      ()
| Returns a `node_iterator` corresponding to a value_type just after a leaf of the tree.
    inline const_node_iterator
      node_end
      () const
| Returns a `const_node_iterator` corresponding to a value_type just after a leaf of the tree.

## Split and join methods.

Method | Description
    void
      join
      (basic_tree_assoc_cntnr &r_other)
| Joins two trees. When this function returns, `r_other` will be empty. When calling this function, `r_other`'s keys must be all larger or all smaller than this object's keys.
    inline void
      split
      (const_key_reference r_key,
        basic_tree_assoc_cntnr &r_other)
| Joins two trees. When this function returns, `r_other` will be empty.