123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125 |
- ++++++++++++++++++++++++++++++++++
- |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
|