ceph/src/boost/libs/ptr_container/doc/intro.xml

   1 <!--
   2 //
   3 // Boost.Pointer Container
   4 //
   5 //  Copyright Thorsten Ottosen 2003-2005. Use, modification and
   6 //  distribution is subject to the Boost Software License, Version
   7 //  1.0. (See accompanying file LICENSE_1_0.txt or copy at
   8 //  http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10 // For more information, see http://www.boost.org/libs/ptr_container/
  11 //
  12 -->
  13 <?xml version="1.0" encoding="utf-8"?>
  14 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  15 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
  16 <section id="ptr_container.intro" last-revision="$Date$">
  17         <title>Introduction</title>
  18
  19         <para>
  20             This library provides standard-like containers that are suitable
  21                      for storing pointers to both polymorphic and non-polymorphic objects.
  22                      For each of the standard containers there is a pointer container
  23                      equivalent that takes ownership of the stored pointers in an exception
  24                      safe manner. In this respect it is intended to solve
  25                      the so-called <emphasis>polymorphic class problem.    </emphasis>
  26         </para>
  27         <para>
  28          The main advantages are
  29           <itemizedlist>
  30                <listitem> Exception-safe and fool proof pointer storage and manipulation.</listitem>.
  31                <listitem> Exception-guarantees are generally much better than with standard containers (at least the strong guarantee</listitem>
  32                <listitem> Notational convinience compared to the use of containers of smart pointers.</listitem>
  33                <listitem> Iterators are automatically indirected so the comparison operations can be kept
  34                                 on object basis instead of making/adding pointer based variants.</listitem>
  35                <listitem> No memory-overhead as containers of smart_pointers can have.</listitem>
  36                <listitem> Faster than using containers of smart pointers.</listitem>
  37                <listitem> Provides an elegant solution to <code> vector< vector<T> > </code> performance
  38                                problems; simply use  <code>ptr_vector< vector<T> ></code></listtem>
  39         </para>
  40         <para>
  41          Below is given some example that show how the usage compares to a container of smart pointers:
  42         <programlisting>
  43     using namespace boost;
  44     using namespace std;
  45
  46     class Poly
  47     {
  48     public:
  49         virtual ~Poly() {}
  50         void foo() { doFoo(); }
  51     private:
  52         virtual void doFoo()
  53         {
  54             int i;
  55             ++i;
  56         }
  57     };
  58
  59     //
  60     // one doesn't need to introduce new names or live with long ones
  61     //
  62     typedef shared_ptr<Poly> PolyPtr;
  63
  64     //
  65     // one doesn't need to write this anymore
  66     //
  67     struct PolyPtrOps
  68     {
  69       void operator()( const PolyPtr & a )
  70         { a->foo(); }
  71     };
  72
  73     int main()
  74     {
  75         enum { size = 2000000 };
  76         vector<PolyPtr>    svec
  77         ptr_vector<Poly>   pvec;
  78
  79         for( int i = 0; i < size; ++i )
  80         {
  81             svec.push_back( PolyPtr( new Poly ) );
  82             pvec.push_back( new Poly );  // no extra syntax
  83         }
  84
  85         for_each( svec.begin(), svec.end(), PolyPtrOps() );
  86
  87         for_each( pvec.begin(), pvec.end(), mem_fun_ref( &Poly::foo ) );
  88      }
  89          </programlisting>
  90         </para>
  91 </section>