libs/ptr_container/doc/examples.rst
++++++++++++++++++++++++++++++++++
|Boost| Pointer Container Library
++++++++++++++++++++++++++++++++++
.. |Boost| image:: boost.png
========
Examples
========
Some examples are given here and in the accompanying test files:
.. contents:: :local:
.. _`Example 1`:
1. Null pointers cannot be stored in the containers
+++++++++++++++++++++++++++++++++++++++++++++++++++
::
my_container.push_back( 0 ); // throws bad_ptr
my_container.replace( an_iterator, 0 ); // throws bad_ptr
my_container.insert( an_iterator, 0 ); // throws bad_ptr
std::auto_ptr<T> p( 0 );
my_container.push_back( p ); // throws bad_ptr
.. _`Example 2`:
2. Iterators and other operations return indirected values
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
::
ptr_vector<X> pvec;
std::vector<X*> vec;
*vec.begin() = new X; // fine, memory leak
*pvec.begin() = new X; // compile time error
( *vec.begin() )->foo(); // call X::foo(), a bit clumsy
pvec.begin()->foo(); // no indirection needed
*vec.front() = X(); // overwrite first element
pvec.front() = X(); // no indirection needed
.. _`Example 3`:
3. Copy-semantics of pointer containers
+++++++++++++++++++++++++++++++++++++++
::
ptr_vector<T> vec1;
...
ptr_vector<T> vec2( vec1.clone() ); // deep copy objects of 'vec1' and use them to construct 'vec2', could be very expensive
vec2 = vec1.release(); // give up ownership of pointers in 'vec1' and pass the ownership to 'vec2', rather cheap
vec2.release(); // give up ownership; the objects will be deallocated if not assigned to another container
vec1 = vec2; // deep copy objects of 'vec2' and assign them to 'vec1', could be very expensive
ptr_vector<T> vec3( vec1 ); // deep copy objects of 'vec1', could be very expensive
.. _`Example 4`:
4. Making a non-copyable type Cloneable
+++++++++++++++++++++++++++++++++++++++
::
// a class that has no normal copy semantics
class X : boost::noncopyable { public: X* clone() const; ... };
// this will be found by the library by argument dependent lookup (ADL)
X* new_clone( const X& x )
{ return x.clone(); }
// we can now use the interface that requires cloneability
ptr_vector<X> vec1, vec2;
...
vec2 = vec1.clone(); // 'clone()' requires cloning <g>
vec2.insert( vec2.end(), vec1.begin(), vec1.end() ); // inserting always means inserting clones
.. _`Example 5`:
5. Objects are cloned before insertion, inserted pointers are owned by the container
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
::
class X { ... }; // assume 'X' is Cloneable
X x; // and 'X' can be stack-allocated
ptr_list<X> list;
list.push_back( new_clone( x ) ); // insert a clone
list.push_back( new X ); // always give the pointer directly to the container to avoid leaks
list.push_back( &x ); // don't do this!!!
std::auto_ptr<X> p( new X );
list.push_back( p ); // give up ownership
BOOST_ASSERT( p.get() == 0 );
.. _`Example 6`:
6. Transferring ownership of a single element
+++++++++++++++++++++++++++++++++++++++++++++
::
ptr_deque<T> deq;
typedef ptr_deque<T>::auto_type auto_type;
// ... fill the container somehow
auto_type ptr = deq.release_back(); // remove back element from container and give up ownership
auto_type ptr2 = deq.release( deq.begin() + 2 ); // use an iterator to determine the element to release
ptr = deq.release_front(); // supported for 'ptr_list' and 'ptr_deque'
deq.push_back( ptr.release() ); // give ownership back to the container
.. _`Example 7`:
7. Transferring ownership of pointers between different pointer containers
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
::
ptr_list<X> list; ptr_vector<X> vec;
...
//
// note: no cloning happens in these examples
//
list.transfer( list.begin(), vec.begin(), vec ); // make the first element of 'vec' the first element of 'list'
vec.transfer( vec.end(), list.begin(), list.end(), list ); // put all the lists element into the vector
We can also transfer objects from ``ptr_container<Derived>`` to ``ptr_container<Base>`` without any problems.
.. _`Example 8`:
8. Selected test files
++++++++++++++++++++++
:incomplete_type_test.cpp_: Shows how to implement the Composite pattern.
:simple_test.cpp_: Shows how the usage of pointer container compares with a
container of smart pointers
:view_example.cpp_: Shows how to use a pointer container as a view into other container
:tree_test.cpp_: Shows how to make a tree-structure
:array_test.cpp_: Shows how to make an n-ary tree
.. _incomplete_type_test.cpp : ../test/incomplete_type_test.cpp
.. _simple_test.cpp : ../test/simple_test.cpp
.. _view_example.cpp : ../test/view_example.cpp
.. _tree_test.cpp : ../test/tree_test.cpp
.. _array_test.cpp : ../test/ptr_array.cpp
9. A large example
++++++++++++++++++
This example shows many of the most common
features at work. The example provide lots of comments.
The source code can also be found `here <../test/tut1.cpp>`_.
.. raw:: html
:file: tutorial_example.html
..
10. Changing the Clone Allocator
++++++++++++++++++++++++++++++++
This example shows how we can change
the Clone Allocator to use the pointer containers
as view into other containers:
.. raw:: html
:file: tut2.html
.. 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
