126 lines
5.1 KiB
ReStructuredText
126 lines
5.1 KiB
ReStructuredText
++++++++++++++++++++++++++++++++++
|
|
|Boost| Pointer Container Library
|
|
++++++++++++++++++++++++++++++++++
|
|
|
|
.. |Boost| image:: boost.png
|
|
|
|
Conventions
|
|
+++++++++++
|
|
|
|
There are a few design decisions that will affect how the classes are
|
|
used. Besides these the classes are much like normal standard containers
|
|
and provides almost the same interface. The new conventions are:
|
|
|
|
.. contents:: :local:
|
|
|
|
Null pointers are not allowed by default
|
|
----------------------------------------
|
|
|
|
If the user tries to insert the null pointer, the operation will throw a
|
|
``bad_pointer`` exception (see `Example 1 <examples.html>`_).
|
|
|
|
Use `nullable <reference.html#class-nullable>`_ to allow null pointers.
|
|
|
|
Please notice that all preconditions of the form ::
|
|
|
|
x != 0;
|
|
|
|
are not active when the you have instantiated a container
|
|
with ``nullable<T>`` as in ::
|
|
|
|
boost::ptr_vector< boost::nullable<animal> > vec;
|
|
vec.push_back( 0 ); // ok
|
|
|
|
All default iterators apply an extra layer of indirection
|
|
---------------------------------------------------------
|
|
|
|
This is done to
|
|
make the containers easier and safer to use. It promotes a kind of
|
|
pointer-less programming and the user of a class needs not worry about
|
|
pointers except when allocating them (see `Example 2 <examples.html>`_). Iterators that
|
|
provide access to the naked pointers are also provided since they might be
|
|
useful in rare cases. For example, whenever ``begin()`` returns an iterator,
|
|
``ptr_begin()`` will return an iterator that allows one to iterate over the
|
|
stored pointers.
|
|
|
|
All comparison operations are done on the pointed to objects and not at the pointer level
|
|
-----------------------------------------------------------------------------------------
|
|
|
|
For example, in ``ptr_set<T>`` the ordering is by default done by
|
|
``boost::ptr_less<T>`` which compares the indirected pointers.
|
|
Similarly, ``operator==()`` for ``container<Foo>`` compares all objects
|
|
with ``operator==(const Foo&, const Foo&)``.
|
|
|
|
|
|
Stored elements are required to be `Cloneable <reference.html#the-Cloneable-concept>`_ for a subset of the operations
|
|
---------------------------------------------------------------------------------------------------------------------
|
|
|
|
This is because most polymorphic objects cannot be copied directly, but
|
|
they can often be so by a use of a member function (see `Example 4 <examples.html>`_). Often
|
|
it does not even make sense to clone an object in which case a large
|
|
subset of the operations are still workable.
|
|
|
|
Whenever objects are inserted into a container, they are cloned before insertion
|
|
--------------------------------------------------------------------------------
|
|
|
|
This is necessary because all pointer containers take ownerships of stored objects
|
|
(see `Example 5 <examples.html>`_).
|
|
|
|
Whenever pointers are inserted into a container, ownership is transferred to the container
|
|
------------------------------------------------------------------------------------------
|
|
|
|
All containers take ownership of the stored pointers and therefore a
|
|
container needs to have its own copies (see `Example 5 <examples.html>`_).
|
|
|
|
Ownership can be transferred from a container on a per pointer basis
|
|
--------------------------------------------------------------------
|
|
|
|
This can of course also be convenient. Whenever it happens, an
|
|
``SmartContainer::auto_type`` object is used to provide an exception-safe transfer
|
|
(see `Example 6 <examples.html>`_).
|
|
|
|
Ownership can be transferred from a container to another container on a per iterator range basis
|
|
------------------------------------------------------------------------------------------------
|
|
|
|
This makes it possible to exchange data safely between different pointer
|
|
containers without cloning the objects again (see `Example 7 <examples.html>`_).
|
|
|
|
A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container
|
|
----------------------------------------------------------------------------------------------------------------------
|
|
|
|
Two special member functions, ``clone()`` and ``release()``, both return a
|
|
``compatible-smart-ptr<SmartContainer>`` which can be assigned to another pointer container. This
|
|
effectively reduces the cost of returning a container to one
|
|
heap-allocation plus a call to ``swap()`` (see `Example 3 <examples.html>`_).
|
|
|
|
Iterators are invalidated as in the corresponding standard container
|
|
--------------------------------------------------------------------
|
|
|
|
Because the containers in this library wrap standard containers, the
|
|
rules for invalidation of iterators are the same as the rules
|
|
of the corresponding standard container.
|
|
|
|
For example, for both ``boost::ptr_vector<T>`` and ``std::vector<U>``
|
|
insertion and deletion only invalidates the deleted
|
|
element and elements following it; all elements before the inserted/deleted
|
|
element remain valid.
|
|
|
|
.. raw:: html
|
|
|
|
<hr>
|
|
|
|
**Navigate:**
|
|
|
|
- `home <ptr_container.html>`_
|
|
- `reference <reference.html>`_
|
|
|
|
.. raw:: html
|
|
|
|
<hr>
|
|
|
|
:Copyright: Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
|
|
|
|
__ http://www.boost.org/LICENSE_1_0.txt
|
|
|
|
|