bimap.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

In the descriptions of the operations of `bimap`, we adopt the scheme
outlined in the complexity signature section.

[endsect]

[section Instantiation types]

`bimap` is instantiated with the following types:

# LeftCollectionType and RightCollectionType are collection type specifications
optionally tagged, or any type optionally tagged, in which case that
side acts as a set.
# AdditionalParameter_{1/2} can be any ordered subset of:
    * CollectionTypeOfRelation specification
    * Allocator

[endsect]

[section Nested types]

    left_tag, right_tag

[:  Tags for each side of the bimap. If the user has not specified any tag the
    tags default to `member_at::left` and `member_at::right`.
]

    left_key_type, right_key_type

[:  Key type of each side. In a `bimap<A,B> ` `left_key_type` is `A` and
    `right_key_type` is `B`.
    If there are tags, it is better to use: `Bimap::map_by<Tag>::key_type`.
]

    left_data_type, right_data_type

[:  Data type of each side. In a bimap<A,B> left_key_type is B and
    right_key_type is A.
    If there are tags, it is better to use: `Bimap::map_by<Tag>::data_type`.
]

    left_value_type, right_value_type

[:  Value type used for the views.
    If there are tags, it is better to use: `Bimap::map_by<Tag>::value_type`.
]


    left_iterator, right_iterator
    left_const_iterator, right_const_iterator

[:  Iterators of the views.
    If there are tags, it is better to use:
    `Bimap::map_by<Tag>::iterator` and
    `Bimap::map_by<Tag>::const_iterator`
]


    left_map, right_map

[:  Map view type of each side.
    If there are tags, it is better to use:
    `Bimap::map_by<Tag>::type`.
]

[endsect]

[section Constructors, copy and assignment]

    bimap();

* [*Effects:] Constructs an empty `bimap`.
* [*Complexity:] Constant.

    template<typename InputIterator>
    bimap(InputIterator first,InputIterator last);

* [*Requires: ] `InputIterator` is a model of Input Iterator over elements of
type `relation` or a type convertible to `relation`. last is reachable from `first`.
* [*Effects:] Constructs an empty `bimap` and fills it with the elements in the range
`[first,last)`. Insertion of each element may or may not succeed depending on
acceptance by the collection types of the `bimap`.
* [link complexity_signature_explanation
[*Complexity:]] O(m*H(m)), where m is the number of elements in `[first,last)`.


    bimap(const bimap & x);

* [*Effects:] Constructs a copy of x, copying its elements as well as its
internal objects (key extractors, comparison objects, allocator.)
* [*Postconditions:] `*this == x`. The order of the views of the `bimap`
is preserved as well.
* [*Complexity:] O(x.size()*log(x.size()) + C(x.size()))


    ~bimap()

* [*Effects:] Destroys the `bimap` and all the elements contained.
The order in which the elements are destroyed is not specified.
* [*Complexity:] O(n).


    bimap& operator=(const bimap& x);

* [*Effects:] Replaces the elements and internal objects of the `bimap`
with copies from x.
* [*Postconditions:] `*this==x`. The order on the views of the `bimap`
is preserved as well.
* [*Returns: ] `*this`.
* [*Complexity:] O(n + x.size()*log(x.size()) + C(x.size())).
* [*Exception safety:] Strong, provided the copy and assignment operations
of the types of `ctor_args_list` do not throw.

[/
    allocator_type get_allocator() const;

* [*Effects:] Returns a copy of the `allocator_type` object used to construct
the `bimap`.
* [*Complexity:] Constant.
]

[endsect]

[#reference_projection_operations]

[section Projection operations]

Given a `bimap` with views v1 and v2, we say than an v1-iterator
it1 and an v2-iterator it2 are equivalent if:

* `it1 == i1.end()` AND `it2 == i2.end()`,
* OR `it1` and `it2` point to the same element.


    template< class IteratorType >
    left_iterator project_left(IteratorType iter);

    template< class IteratorType >
    left_const_iterator project_left(IteratorType iter) const;

* [*Requires:] `IteratorType` is a bimap view iterator. it is a
valid iterator of some view of `*this` (i.e. does not refer to some other
`bimap`.)
* [*Effects:] Returns a left map view iterator equivalent to `it`.
* [*Complexity:] Constant.
* [*Exception safety:] nothrow.


    template< class IteratorType >
    right_iterator project_right(IteratorType iter);

    template< class IteratorType >
    right_const_iterator project_right(IteratorType iter) const;

* [*Requires:] `IteratorType` is a bimap view iterator. it is a
valid iterator of some view of `*this` (i.e. does not refer to some other
`bimap`.)
* [*Effects:] Returns a right map view iterator equivalent to `it`.
* [*Complexity:] Constant.
* [*Exception safety:] nothrow.


    template< class IteratorType >
    iterator project_up(IteratorType iter);

    template< class IteratorType >
    const_iterator project_up(IteratorType iter) const;

* [*Requires:] `IteratorType` is a bimap view iterator. it is a
valid iterator of some view of `*this` (i.e. does not refer to some other
`bimap`.)
* [*Effects:] Returns a collection of relations view iterator equivalent to `it`.
* [*Complexity:] Constant.
* [*Exception safety:] nothrow.

[endsect]

[#reference_support_for_used_defined_names]

[section Support for user defined names]

    template< class Tag >
    struct map_by;

* `map_by<Tag>::type` yields the type of the map view tagged with `Tag`.
`map_by<Tag>::`['-type name-] is the same as `map_by<Tag>::type::`['-type name-].
* [*Requires: ] `Tag` is a valid user defined name of the bimap.


    template< class Tag >
    map_by<Tag>::type by();

    template< class Tag >
    const map_by<Tag>::type & by() const;


* [*Requires: ] `Tag` is a valid user defined name of the bimap.
* [*Effects:] Returns a reference to the map view tagged with `Tag` held by
`*this`.
* [*Complexity:] Constant.
* [*Exception safety:] nothrow.


    template< class Tag, class IteratorType >
    map_by<Tag>::iterator project(IteratorType iter);

    template< class Tag, class IteratorType >
    map_by<Tag>::const_iterator project(IteratorType iter) const

* [*Requires: ] `Tag` is a valid user defined name of the bimap. `IteratorType`
is a bimap view iterator. it is a valid iterator of some view of `*this`
(i.e. does not refer to some other `bimap`.)
* [*Effects:] Returns a reference to the map view tagged with `Tag` held by
`*this`.
* [*Complexity:] Constant.
* [*Exception safety:] nothrow.


[endsect]

[section Serialization]

A `bimap` can be archived and retrieved by means of __BOOST_SERIALIZATION__.
Boost.Bimap does not expose a public serialisation interface, as this is
provided by Boost.Serialization itself. Both regular and XML archives
are supported.

Each of the set specifications comprising a given `bimap` contributes its
own preconditions as well as guarantees on the retrieved containers. In describing
these, the following concepts are used. A type `T` is ['serializable]
(resp. XML-serializable) if any object of type `T` can be saved to an output
archive (XML archive) and later retrieved from an input archive (XML archive)
associated to the same storage. If `x`' of type `T` is loaded from the serialization
information saved from another object x, we say that x' is a ['restored copy] of x.
Given a __SGI_BINARY_PREDICATE__ `Pred` over `(T, T)`, and objects `p` and `q` of 
type `Pred`, we say that `q` is ['serialization-compatible] with `p` if

* `p(x,y) == q(x`'`,y`'`)`

for every `x` and `y` of type `T` and `x`' and `y`' being restored copies of `x`
and `y`, respectively.

[blurb [*Operation:] saving of a `bimap b` to an output archive
(XML archive) ar.]

* [*Requires:] Value is serializable (XML-serializable). Additionally, each
of the views of b can impose other requirements.
* [*Exception safety:] Strong with respect to `b`. If an exception is thrown, ar
may be left in an inconsistent state.

[blurb [*Operation:] loading of a `bimap` m' from an input archive
(XML archive) ar.]

* [*Requires:] Value is serializable (XML-serializable). Additionally, each of
the views of `b`' can impose other requirements.
* [*Exception safety:] Basic. If an exception is thrown, ar may be left in an
inconsistent state.

[endsect]
[endsect]

[endsect]