vector_of.qbk

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

[endsect]

[section Instantiation types]

`vector_of` views are instantiated internally to `bimap` and specified
by means of the collection type specifiers and the bimap itself.
Instantiations are dependent on the following types:

* `Value` from `vector_of`,
* `Allocator` from `bimap`,

[endsect]

[section Constructors, copy and assignment]

As explained in the views concepts section,
views do not have public constructors or destructors.
Assignment, on the other hand, is provided.

    this_type & operator=(const this_type & x);

* [*Effects: ] `a=b;`
where a and b are the `bimap` objects to which `*this` and
`x` belong, respectively.
* [*Returns: ] `*this`.


[#reference_vector_of_assign_iterator_iterator]

    template< class InputIterator >
    void assign(InputIterator first, InputIterator last);

* [*Requires: ] `InputIterator` is a model of __SGI_INPUT_ITERATOR__ over elements
of type `value_type` or a type convertible to `value_type`. `first` and `last` are
not iterators into any view of the `bimap` to which this
view belongs. `last` is reachable from `first`.
* [*Effects: ] `clear(); insert(end(),first,last);`


[#reference_vector_of_assign_size_value]

    void assign(size_type n, const value_type & value);

* [*Effects: ] `clear(); for(size_type i = 0; i < n; ++n) push_back(v);`

[endsect]

[section Capacity operations]

[#reference_vector_of_capacity]

    size_type capacity() const;

* [*Returns:] The total number of elements `c` such that, when `size() < c`,
back insertions happen in constant time (the general case as described by
i(n) is ['amortized] constant time.) 
* [*Note:] Validity of iterators and references to elements is preserved
in all insertions, regardless of the capacity status.


[#reference_vector_of_reserve_size]

    void reserve(size_type m);

* [*Effects:] If the previous value of `capacity()` was greater than or equal
to `m`, nothing is done; otherwise, the internal capacity is changed so that
`capacity()>=m`.
* [*Complexity:] If the capacity is not changed, constant; otherwise O(n).
* [*Exception safety:] If the capacity is not changed, nothrow; otherwise, strong.


[#reference_vector_of_resize_size_value]

    void resize(size_type n, const value_type & x = value_type());

* [*Effects: ] `if( n > size() ) insert(end(), n-size(), x);`
`else if( n<size() ) erase(begin()+n,end());`
* [*Note:] If an expansion is requested, the size of the view is not guaranteed
to be n after this operation (other views may ban insertions.)


[endsect]

[section Modifiers]

[#reference_vector_of_push_front_value]

    std::pair<iterator,bool> push_front(const value_type & x);

* [*Effects:] Inserts x at the beginning of the sequence if no other view
of the `bimap` bans the insertion.
* [*Returns:] The return value is a pair `p`. `p.second` is `true` if and only if
insertion took place. On successful insertion, `p.first` points to the element
inserted; otherwise, `p.first` points to an element that caused the insertion
to be banned. Note that more than one element can be causing insertion not
to be allowed.
* [link vector_of_complexity_signature [*Complexity:]] O(n+I(n)).
* [*Exception safety:] Strong.


[#reference_vector_of_push_back_value]

    std::pair<iterator,bool> push_back(const value_type & x);

* [*Effects:] Inserts `x` at the end of the sequence if no other view of
the `bimap` bans the insertion.
* [*Returns:] The return value is a pair `p`. `p.second` is `true` if and only
if insertion took place. On successful insertion, `p.first` points to the
element inserted; otherwise, `p.first` points to an element that caused
the insertion to be banned. Note that more than one element can be
causing insertion not to be allowed.
* [link vector_of_complexity_signature [*Complexity:]] O(I(n)).
* [*Exception safety:] Strong.


[#reference_vector_of_insert_iterator_value]

    std::pair<iterator,bool> insert(iterator position, const value_type & x);

* [*Requires: ] `position` is a valid iterator of the view.
* [*Effects:] Inserts `x` before position if insertion is allowed by all
other views of the `bimap`.
* [*Returns:] The return value is a pair `p`. `p.second` is `true` if and only
if insertion took place. On successful insertion, `p.first` points to the
element inserted; otherwise, `p.first` points to an element that caused the
insertion to be banned. Note that more than one element can be causing
insertion not to be allowed.
* [link vector_of_complexity_signature [*Complexity:]] O(shl(end()-position,1) + I(n)).
* [*Exception safety:] Strong.


[#reference_vector_of_insert_iterator_size_value]

    void insert(iterator position, size_type m, const value_type & x);

* [*Requires: ] `position` is a valid iterator of the view.
* [*Effects: ] `for(size_type i = 0; i < m; ++i) insert(position, x);`
* [link vector_of_complexity_signature
[*Complexity:]] O(shl(end()-position,m) + m*I(n+m)).


[#reference_vector_of_insert_iterator_iterator_iterator]

    template< class InputIterator >
    void insert(iterator position, InputIterator first, InputIterator last);

* [*Requires: ] `position` is a valid iterator of the view. `InputIterator`
is a model of __SGI_INPUT_ITERATOR__ over elements of type `value_type` or a type
convertible to `value_type`. `first` and `last` are not iterators into any view
of the `bimap` to which this view belongs. `last` is reachable
from `first`.
* [*Effects: ] `while(first!=last)insert(position,*first++);`
* [link vector_of_complexity_signature
[*Complexity:]] O(shl(end()-position,m) + m*I(n+m)), where m is the number
of elements in `[first,last)`.
* [*Exception safety:] Basic.


[#reference_vector_of_erase_iterator]

    iterator erase(iterator position);

* [*Requires: ] `position` is a valid dereferenceable iterator of the view.
* [*Effects:] Deletes the element pointed to by `position`.
* [*Returns:] An iterator pointing to the element immediately following the
one that was deleted, or `end()` if no such element exists.
* [link vector_of_complexity_signature [*Complexity:]] O(D(n)).
* [*Exception safety:] nothrow.


[#reference_vector_of_erase_iterator_iterator]

    iterator erase(iterator first, iterator last);

* [*Requires: ] `[first,last)` is a valid range of the view.
* [*Effects:] Deletes the elements in `[first,last)`.
* [*Returns:] last.
* [link vector_of_complexity_signature
[*Complexity:]] O(m*D(n)), where m is the number of elements in `[first,last)`.
* [*Exception safety:] nothrow.


[#reference_vector_of_replace_iterator_value]

    bool replace(iterator position, const value_type & x);

* [*Requires: ] `position` is a valid dereferenceable iterator of the view.
* [*Effects:] Assigns the value x to the element pointed to by position into
the `bimap` to which the view belongs if replacing is allowed
by all other views of the `bimap`.
* [*Postconditions:] Validity of position is preserved in all cases.
* [*Returns: ] `true` if the replacement took place, `false` otherwise.
* [link vector_of_complexity_signature
[*Complexity:]] O(R(n)).
* [*Exception safety:] Strong. If an exception is thrown by some user-provided
operation the `bimap` to which the view belongs remains in its
original state.



[#reference_vector_of_replace_key_iterator_key]

    template< class CompatibleKey >
    bool replace_key(iterator position, const CompatibleKey & x);

* [*Requires: ] `position` is a valid dereferenceable iterator of the set view.
`CompatibleKey` can be assigned to `key_type`.
* [*Effects:] Assigns the value `x` to `e.first`, where `e` is the element pointed 
to by `position` into the `bimap` to which the set view belongs if replacing is allowed by
all other views of the `bimap`.
* [*Postconditions:] Validity of position is preserved in all cases.
* [*Returns: ] `true` if the replacement took place, `false` otherwise.
* [link vector_of_complexity_signature
[*Complexity:]] O(R(n)).
* [*Exception safety:] Strong. If an exception is thrown by some user-provided
operation, the `bimap` to which the set view belongs remains in
its original state.


[#reference_vector_of_replace_data_iterator_data]

    template< class CompatibleData >
    bool replace_data(iterator position, const CompatibleData & x);

* [*Requires: ] `position` is a valid dereferenceable iterator of the set view.
`CompatibleKey` can be assigned to `data_type`.
* [*Effects:] Assigns the value `x` to `e.second`, where `e` is the element pointed 
to by `position` into the `bimap` to which the set view belongs if replacing is allowed by
all other views of the `bimap`.
* [*Postconditions:] Validity of position is preserved in all cases.
* [*Returns: ] `true` if the replacement took place, `false` otherwise.
* [link vector_of_complexity_signature
[*Complexity:]] O(R(n)).
* [*Exception safety:] Strong. If an exception is thrown by some user-provided
operation, the `bimap` to which the set view belongs remains in
its original state.


[#reference_vector_of_modify_key_iterator_modifier]

    template< class KeyModifier >
    bool modify_key(iterator position, KeyModifier mod);

* [*Requires: ] `KeyModifier` is a model of __SGI_UNARY_FUNCTION__ accepting arguments of
type: `key_type&`; `position` is a valid dereferenceable iterator of the view.
* [*Effects:] Calls `mod(e.first)` where e is the element pointed to by position and 
rearranges `*position` into all the views of the `bimap`.
If the rearrangement fails, the element is erased.
It is successful if the rearrangement is allowed by all other views of the `bimap`.
* [*Postconditions:] Validity of `position` is preserved if the operation succeeds.
* [*Returns: ] `true` if the operation succeeded, `false` otherwise.
* [link vector_of_complexity_signature
[*Complexity:]] O(M(n)).
* [*Exception safety:] Basic. If an exception is thrown by some user-provided
operation (except possibly mod), then the element pointed to by position is erased.
* [*Note:] Only provided for map views. 


[#reference_vector_of_modify_data_iterator_modifier]

    template< class DataModifier >
    bool modify_data(iterator position, DataModifier mod);

* [*Requires: ] `DataModifier` is a model of __SGI_UNARY_FUNCTION__ accepting arguments of
type: `data_type&`; `position` is a valid dereferenceable iterator of the view.
* [*Effects:] Calls `mod(e.second)` where e is the element pointed to by position and 
rearranges `*position` into all the views of the `bimap`.
If the rearrangement fails, the element is erased.
It is successful if the rearrangement is allowed by all other views of the `bimap`.
* [*Postconditions:] Validity of `position` is preserved if the operation succeeds.
* [*Returns: ] `true` if the operation succeeded, `false` otherwise.
* [link vector_of_complexity_signature
[*Complexity:]] O(M(n)).
* [*Exception safety:] Basic. If an exception is thrown by some user-provided
operation (except possibly mod), then the element pointed to by position is erased.
* [*Note:] Only provided for map views. 

[/
[#reference_vector_of_modify_iterator_modifier]