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.pop_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.pop_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