Changeset 54657


Ignore:
Timestamp:
Jul 4, 2009, 10:39:03 PM (9 years ago)
Author:
cschladetsch
Message:

updated docs

Location:
sandbox/cloneable/libs/cloneable/doc
Files:
8 edited

Legend:

Unmodified
Added
Removed
  • sandbox/cloneable/libs/cloneable/doc/cloneable.qbk

    r54640 r54657  
    3535
    3636Cloneable objects can create clones of derived types from base types,
    37 can do so given any STL-compliant allocator, and support multiple clone type targets.
     37can do so given any STL-compliant allocator, and supports multiple clone type targets.
    3838
    3939The user of the library is able to override the default cloning process,
     
    5050or sensible defaults are generated.
    5151
     52Key features of the library:
     53
     54* Can make any class-type Cloneable with or without modification to its definition
     55* Optional user-supplied base classes
     56* Base types can be queried for the interfaces they support
     57* Clones can be created from base types
     58* Supports multiple inheritance, cloning of sub-objects
     59* Supports types with no default constructors
     60* Customisation of the cloning process
     61* Support for custom allocators
     62* A set of heterogenous containers with emplace semantics for object insertion
     63
    5264The complete source code for the library, with unit-tests, are available
    5365in the Boost SVN respository [@http://svn.boost.org/svn/boost/sandbox/cloneable/ here].
    5466
    55 [1] Cloneable objects can be used in containers-of-pointers (based on a modified [*Boost.PtrContainer] implementation), producing a 'heterogenous' container system with value semantics for comparison and copying, and emplace semantics for insertion. These containers are currently a part of the proposal as well, however it is intended that they eventually form a distinct library. This proposal will focus mostly on the single-object aspect of the system.
     67[1] Cloneable objects can be used in containers-of-pointers (based on a modified [*Boost.PtrContainer]
     68implementation), producing a 'heterogenous' container system with value semantics for
     69comparison and copying, and emplace semantics for insertion. These containers are currently
     70 a part of the proposal as well, however it is intended that they eventually form a
     71 distinct library. This proposal will focus mostly on the single-object aspect of the system.
    5672
    5773[endsect]
     
    6177[h3 Version 0.1]
    6278
     79* Associative heterogenous containers
     80* User-defined base classes
    6381* Created
    6482
     
    7189and how to deal with multiple inheritance in type hierarchies.
    7290
    73 The following is a very quick introduction to [*Boost.Cloneable]:
     91The following is a quick introduction to [*Boost.Cloneable]:
    7492
    7593``
     
    7997
    8098class Foo : public cloneable::base<Foo> { };
    81 
     99``
     100
     101Here we have included the main [*Boost.Cloneable] header, made a class and
     102derived from `cloneable::base`, passing the type of thing to clone as the first type parameter.
     103Now we can use it to make a clone:
     104
     105``
    82106int main()
    83107{
     
    89113``
    90114
    91 Here we have made a class and derived from `cloneable::base`, passing the
    92 type of thing to clone as a parameter.
    93 
    94115Because we didn't supply a base
    95 type to use, we were given `base_type`, which is the return type of the clone
    96 method.
     116type to use, the default base type named `cloneable::base_type` is used. This is
     117the return-type of the `clone` method added to the `Foo` type.
     118
     119An equivalent way of making the clone is to use a free-function:
     120
     121``
     122Foo *clone = cloneable::clone(*foo); // note: clone() takes a const reference, not a pointer
     123``
     124
     125This allows us to work with types that may or may not be ['Cloneable] in the sense
     126of this library. If the given type is not ['Cloneable], then the default way of
     127making a clone using `new Type(original)` is used. (['is defaulting to `new T(orig)` too dangerous? --CJS])
     128
     129To clone from a base class, which generally doesn't have any clone-related methods, we use the
     130free-functions `clone`, `can_clone_as` and `clone_as`:
     131
     132``
     133int main()
     134{
     135        using namespace cloneable;
     136       
     137        base_type *foo_base = new Foo();
     138        assert(can_clone_as<Foo>(*foo_base));
     139       
     140        Foo *foo_clone = clone_as<Foo>(*foo_base);
     141        assert(foo_clone != 0);
     142       
     143    return 0;
     144}
     145``
     146
     147Note that we pass references to these functions rather than pointers, and these functions work for ['Cloneable] types and generally.
     148We can also pass an allocator to these functions, but more on custom allocation later.
    97149
    98150Although it is fine to use
    99 this default base class, we shall see that in general it is better to provide
    100 our own base classes as this gives us much flexibility when it comes to
    101 associative containers and resource management.
     151the default base class in this example and other similar cases, we shall see that in general it is better to provide
     152our own base classes. This gives us flexibility and space for customisation, allows us to
     153use the types in associative containers, and to control resource management.
    102154 
    103155But we'll get to that later. For now, let's move on to some slightly less trivial examples.
     
    106158
    107159In the previous example, we did not supply a base class, so our Cloneable type
    108 was given the `base_type`. Below, we prepare our own base type `Animal`,
     160was given the default `base_type`. Below, we prepare our own base type `Animal`,
    109161which of course has a virtual destructor, as well as a means to get a member
    110162variable from a derived type:
     
    140192``
    141193
    142 We derive our `Cat` class from `cloneable::base<Cat, Animal>`. The first type argument to `base<...>` is
     194We derive our `Cat` class from `cloneable::base<Cat, Animal>`. The first type argument to `base<Cat, Animal>` is
    143195the derived type to use for cloning, and the second argument is the common base type of the hierarhcy. As
    144196we saw in the first example, if you do not provide your own base type, your Cloneable type will use the
    145197base `cloneable::base_type`.
    146198
    147 Other than that, `Cat` implements the `get_name` pure virtual method derived in the base class `Animal`.
     199Other than that, `Cat` implements the `get_name` pure virtual method derived from the base class `Animal`.
    148200
    149201Now, let's use it:
     
    178230
    179231As we shall soon see, this is also handy when we have choices of which sub-object to clone.
     232Of course, we could also use the free-function `clone`:
     233
     234``
     235using namespace cloneable;
     236
     237assert(can_clone_as<Cat>(*cat));
     238Cat *cloned = clone(*cat);
     239``
    180240
    181241We now add other animals to the hierachy, including one that uses multiple inheritance:
     
    198258int main()
    199259{
    200     Labrador *lab = new Labrador();
    201     Dog *dog = lab->clone_as<Dog>();
    202     Labrador *cloned_lab = lab->clone_as<Labrador>();
    203    
    204     assert(typeid(*dog) == typeid(Dog));
    205     assert(typeid(*cloned_lab) == typeid(Labrador));
     260    Animal *lab = new Labrador();
     261    Animal *lab_as_dog = lab->clone_as<Dog>();
     262    Animal *lab_clone = lab->clone_as<Labrador>();
     263   
     264    assert(typeid(*lab_as_dog) == typeid(Dog));
     265    assert(typeid(*lab_clone) == typeid(Labrador));
     266   
     267    assert(!can_clone_as<Labrador>(lab_as_dog));
    206268   
    207269    return 0;
     
    212274`clone_as<Ty>` method.
    213275
    214 It should be noted that when using `clone_as<Ty>`, we actually are making a type of `Ty`, rather than
     276It should be noted that when using `clone_as<Ty>`, we actually are making an instance of type `Ty`, rather than
    215277making another type and casting up.
    216278
    217 We can also use the Cloneable library to make a new instance, with no duplication:
    218 
    219 ``
    220 Animal *MakeNew(const cloneable::abstract_base<Animal> &animal)
    221 {
    222     return animal.create_new();
    223 }
    224 
    225 int main()
    226 {
    227     Cat *cat = new Cat();
    228     Animal *new_animal = MakeNew(*cat);
     279We can also use the Cloneable library to make a new derived instance from a base type:
     280
     281``
     282int main()
     283{
     284    Animal *cat = new Cat();
     285    Animal *new_animal = create_new(*cat);
     286   
    229287    assert(typeid(*new_animal) == typeid(Cat));
     288   
    230289    return 0;
    231290}
     
    233292
    234293This will create a new derived animal type (not a new base), and return a pointer
    235 to the base. Here we used a free-function to make the new object, to show how
    236 to use the `abstract_base` template structure. We used `abstract_base<Animal>`, rather than
    237 just `Animal`, as the base type argument for the `MakeNew` function. This is because
    238 the base class we provided, `Animal`, does not derive from anything and does not
    239 have any clone-related methods. These methods are added by the `abstract_base<>` mix-in,
    240 which all derived `Animal`s are implicitly convertible to.
     294to the base.
    241295
    242296This is the basics of the cloneability side of the library. But there are a few more
    243 details and use-cases to cover before we get to the containers. The first of which is
    244 dealing with types that we can't change.
     297details and use-cases to cover before we get to the containers. The first of these details is
     298dealing with types that are not default-constructable. This is a very useful part of the
     299library, as it allows for containers with elements that are not default constructable and
     300do not have assignment operations. We'll get to that in the containers tutorial, but
     301for now let's quickly cover the basics in the next section.
    245302
    246303[endsect]
     
    265322indicate that it is not default-constructible by passing the `no_default_construction_tag`
    266323type as a parameter to `cloneable::base<>`. The order that you give the base-type or tag-types
    267 to `cloneable::base<>` is not important and is dealt with correctly by the library.
     324to `cloneable::base<>` is not important.
    268325
    269326Putting this type to use:
     
    274331    string str = "foo";
    275332    T0 *p = new T0(str);
    276     T0 *q = p->clone_as<T0>();
     333    T0 *q = clone(*p); // or, p->clone_as<T0>();
    277334    assert(&q->str == &str);
    278335   
     
    295352
    296353A `no_default_construction` exception is thrown if you attempt to default-construct a
    297 type that has no default constructor.
     354type that has no default constructor. As you would expect, if a Cloneable Q type derives
     355from a non-default-constructable type, then Q is also not default-constructable.
     356
     357Next, we'll look at how to use existing types that we can't change.
    298358
    299359[endsect]
     
    353413
    354414When working with types that have multiple cloneable sub-objects, we must use the
    355 `clone_as<T>` and `create_as<T>` methods to disambiguate which sub-type to clone
     415`clone_as<T>` and `create_as<T>` methods or functions to disambiguate which sub-type to clone
    356416or create.
    357417
     
    369429    T2 *t2 = new T2();
    370430   
     431    assert(can_clone_as<W>(*t2));
     432    assert(can_clone_as<T0>(*t2));
     433    assert(can_clone_as<T1>(*t2));
     434    assert(can_clone_as<T2>(*t2));
     435   
     436    assert(can_create_as<W>(*t2));
     437    assert(can_create_as<T0>(*t2));
     438    assert(can_create_as<T1>(*t2));
     439    assert(can_create_as<T2>(*t2));
     440   
    371441    // clone sub-objects
    372442    W *t2_w = t2->clone_as<W>();
     443    T0 *t2_t0 = t2->clone_as<T0>();
    373444    T1 *t2_t1 = t2->clone_as<T1>();
    374     T0 *t2_t0 = t2->clone_as<T0>();
     445    T1 *t2_t2 = t2->clone_as<T2>();
    375446   
    376447    // create sub-objects
    377448    W *t2_w_new = t2->create_as<W>();
     449    T0 *t2_t0_new = t2->create_as<T0>();
    378450    T1 *t2_t1_new = t2->create_as<T1>();
    379     T0 *t2_t0_new = t2->create_as<T0>();
    380    
     451    T2 *t2_t2_new = t2->create_as<T2>();
    381452   
    382453    return 0;
     
    384455``
    385456
    386 Note that if a sub-type S in type T is not default-constructabe, an exception of type
    387 no_default_construction will be thrown if you attempt to default-create a new S instance
    388 from a T instance.
     457Note that if a sub-type `S` in type `T` is not default-constructabe, an exception of type
     458`no_default_construction` will be thrown if you attempt to default-create a new `S` instance
     459from a `T` instance.
    389460
    390461[endsect]
     
    789860``
    790861
     862TODO
     863
    791864[endsect]
    792865
     
    800873        typedef heterogenous::map<Animal> Map;
    801874        Map map;
    802         Map::value_type &pair0 = map.key<Dog>("spot", 12).value<Dog>("rover", 8);
    803         Map::value_type &pair1 = map.key<Cat>("sam", 6).value<Cat>("sooty", 10);
    804         Map::value_type &pair2 = map.key<Cat>("fluffy", 10).value<Cat>("tigger", 14);
    805         Map::value_type &pair3 = map.key<Labrador>("max", 12).value<Cat>("sooty", 3);
     875        Map::value_type pair0 = map.key<Dog>("spot", 12).value<Dog>("rover", 8).value;
     876        Map::value_type pair1 = map.key<Cat>("sam", 6).value<Cat>("sooty", 10).value;
     877        Map::value_type pair2 = map.key<Cat>("fluffy", 10).value<Cat>("tigger", 14).value;
     878        Map::value_type pair3 = map.key<Labrador>("max", 12).value<Cat>("sooty", 3).value;
    806879       
    807880        Map copy = map;
     
    814887}
    815888``
     889
     890TODO
     891
    816892[endsect]
    817893
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html

    r54640 r54657  
    2828</h2></div></div></div>
    2929<a name="cloneable.change_log.version_0_1"></a><h4>
    30 <a name="id651373"></a>
     30<a name="id657967"></a>
    3131      <a class="link" href="change_log.html#cloneable.change_log.version_0_1">Version 0.1</a>
    3232    </h4>
    33 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
     33<div class="itemizedlist"><ul class="itemizedlist" type="disc">
     34<li class="listitem">
     35        Associative heterogenous containers
     36      </li>
     37<li class="listitem">
     38        User-defined base classes
     39      </li>
     40<li class="listitem">
    3441        Created
    35       </li></ul></div>
     42      </li>
     43</ul></div>
    3644</div>
    3745<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/map.html

    r54634 r54657  
    3737        <span class="keyword">typedef</span> <span class="identifier">heterogenous</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">Animal</span><span class="special">&gt;</span> <span class="identifier">Map</span><span class="special">;</span>
    3838        <span class="identifier">Map</span> <span class="identifier">map</span><span class="special">;</span>
    39         <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="special">&amp;</span><span class="identifier">pair0</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Dog</span><span class="special">&gt;(</span><span class="string">"spot"</span><span class="special">,</span> <span class="number">12</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Dog</span><span class="special">&gt;(</span><span class="string">"rover"</span><span class="special">,</span> <span class="number">8</span><span class="special">);</span>
    40         <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="special">&amp;</span><span class="identifier">pair1</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sam"</span><span class="special">,</span> <span class="number">6</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sooty"</span><span class="special">,</span> <span class="number">10</span><span class="special">);</span>
    41         <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="special">&amp;</span><span class="identifier">pair2</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"fluffy"</span><span class="special">,</span> <span class="number">10</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"tigger"</span><span class="special">,</span> <span class="number">14</span><span class="special">);</span>
    42         <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="special">&amp;</span><span class="identifier">pair3</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Labrador</span><span class="special">&gt;(</span><span class="string">"max"</span><span class="special">,</span> <span class="number">12</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sooty"</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span>
     39        <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">pair0</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Dog</span><span class="special">&gt;(</span><span class="string">"spot"</span><span class="special">,</span> <span class="number">12</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Dog</span><span class="special">&gt;(</span><span class="string">"rover"</span><span class="special">,</span> <span class="number">8</span><span class="special">).</span><span class="identifier">value</span><span class="special">;</span>
     40        <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">pair1</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sam"</span><span class="special">,</span> <span class="number">6</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sooty"</span><span class="special">,</span> <span class="number">10</span><span class="special">).</span><span class="identifier">value</span><span class="special">;</span>
     41        <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">pair2</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"fluffy"</span><span class="special">,</span> <span class="number">10</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"tigger"</span><span class="special">,</span> <span class="number">14</span><span class="special">).</span><span class="identifier">value</span><span class="special">;</span>
     42        <span class="identifier">Map</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">pair3</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">.</span><span class="identifier">key</span><span class="special">&lt;</span><span class="identifier">Labrador</span><span class="special">&gt;(</span><span class="string">"max"</span><span class="special">,</span> <span class="number">12</span><span class="special">).</span><span class="identifier">value</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">&gt;(</span><span class="string">"sooty"</span><span class="special">,</span> <span class="number">3</span><span class="special">).</span><span class="identifier">value</span><span class="special">;</span>
    4343       
    4444        <span class="identifier">Map</span> <span class="identifier">copy</span> <span class="special">=</span> <span class="identifier">map</span><span class="special">;</span>
     
    5252</pre>
    5353<p>
     54      </p>
     55<p>
     56        TODO
    5457      </p>
    5558</div>
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/set.html

    r54634 r54657  
    6767<p>
    6868      </p>
     69<p>
     70        TODO
     71      </p>
    6972</div>
    7073<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/intro.html

    r54636 r54657  
    3434<p>
    3535      Cloneable objects can create clones of derived types from base types, can do
    36       so given any STL-compliant allocator, and support multiple clone type targets.
     36      so given any STL-compliant allocator, and supports multiple clone type targets.
    3737    </p>
    3838<p>
     
    5353      classes, or sensible defaults are generated.
    5454    </p>
     55<p>
     56      Key features of the library:
     57    </p>
     58<div class="itemizedlist"><ul class="itemizedlist" type="disc">
     59<li class="listitem">
     60        Can make any class-type Cloneable with or without modification to its definition
     61      </li>
     62<li class="listitem">
     63        Optional user-supplied base classes
     64      </li>
     65<li class="listitem">
     66        Base types can be queried for the interfaces they support
     67      </li>
     68<li class="listitem">
     69        Clones can be created from base types
     70      </li>
     71<li class="listitem">
     72        Supports multiple inheritance, cloning of sub-objects
     73      </li>
     74<li class="listitem">
     75        Supports types with no default constructors
     76      </li>
     77<li class="listitem">
     78        Customisation of the cloning process
     79      </li>
     80<li class="listitem">
     81        Support for custom allocators
     82      </li>
     83<li class="listitem">
     84        A set of heterogenous containers with emplace semantics for object insertion
     85      </li>
     86</ul></div>
    5587<p>
    5688      The complete source code for the library, with unit-tests, are available in
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html

    r54634 r54657  
    4848    </p>
    4949<p>
    50       The following is a very quick introduction to <span class="bold"><strong>Boost.Cloneable</strong></span>:
     50      The following is a quick introduction to <span class="bold"><strong>Boost.Cloneable</strong></span>:
    5151    </p>
    5252<p>
     
    5858
    5959<span class="keyword">class</span> <span class="identifier">Foo</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;</span> <span class="special">{</span> <span class="special">};</span>
    60 
    61 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
     60</pre>
     61<p>
     62    </p>
     63<p>
     64      Here we have included the main <span class="bold"><strong>Boost.Cloneable</strong></span>
     65      header, made a class and derived from <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base</span></code>, passing
     66      the type of thing to clone as the first type parameter. Now we can use it to
     67      make a clone:
     68    </p>
     69<p>
     70     
     71</p>
     72<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
    6273<span class="special">{</span>
    6374     <span class="identifier">Foo</span> <span class="special">*</span><span class="identifier">foo</span> <span class="special">=</span> <span class="keyword">new</span> <span class="identifier">Foo</span><span class="special">();</span>
     
    7081    </p>
    7182<p>
    72       Here we have made a class and derived from <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base</span></code>, passing
    73       the type of thing to clone as a parameter.
     83      Because we didn't supply a base type to use, the default base type named <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base_type</span></code> is used. This is the return-type
     84      of the <code class="computeroutput"><span class="identifier">clone</span></code> method added to
     85      the <code class="computeroutput"><span class="identifier">Foo</span></code> type.
    7486    </p>
    7587<p>
    76       Because we didn't supply a base type to use, we were given <code class="computeroutput"><span class="identifier">base_type</span></code>,
    77       which is the return type of the clone method.
     88      An equivalent way of making the clone is to use a free-function:
    7889    </p>
    7990<p>
    80       Although it is fine to use this default base class, we shall see that in general
    81       it is better to provide our own base classes as this gives us much flexibility
    82       when it comes to associative containers and resource management.
     91     
     92</p>
     93<pre class="programlisting"><span class="identifier">Foo</span> <span class="special">*</span><span class="identifier">clone</span> <span class="special">=</span> <span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">clone</span><span class="special">(*</span><span class="identifier">foo</span><span class="special">);</span> <span class="comment">// note: clone() takes a const reference, not a pointer
     94</span></pre>
     95<p>
     96    </p>
     97<p>
     98      This allows us to work with types that may or may not be <span class="emphasis"><em>Cloneable</em></span>
     99      in the sense of this library. If the given type is not <span class="emphasis"><em>Cloneable</em></span>,
     100      then the default way of making a clone using <code class="computeroutput"><span class="keyword">new</span>
     101      <span class="identifier">Type</span><span class="special">(</span><span class="identifier">original</span><span class="special">)</span></code>
     102      is used. (<span class="emphasis"><em>is defaulting to <code class="computeroutput"><span class="keyword">new</span>
     103      <span class="identifier">T</span><span class="special">(</span><span class="identifier">orig</span><span class="special">)</span></code> too
     104      dangerous? --CJS</em></span>)
     105    </p>
     106<p>
     107      To clone from a base class, which generally doesn't have any clone-related
     108      methods, we use the free-functions <code class="computeroutput"><span class="identifier">clone</span></code>,
     109      <code class="computeroutput"><span class="identifier">can_clone_as</span></code> and <code class="computeroutput"><span class="identifier">clone_as</span></code>:
     110    </p>
     111<p>
     112     
     113</p>
     114<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
     115<span class="special">{</span>
     116        <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">cloneable</span><span class="special">;</span>
     117       
     118        <span class="identifier">base_type</span> <span class="special">*</span><span class="identifier">foo_base</span> <span class="special">=</span> <span class="keyword">new</span> <span class="identifier">Foo</span><span class="special">();</span>
     119        <span class="identifier">assert</span><span class="special">(</span><span class="identifier">can_clone_as</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(*</span><span class="identifier">foo_base</span><span class="special">));</span>
     120       
     121        <span class="identifier">Foo</span> <span class="special">*</span><span class="identifier">foo_clone</span> <span class="special">=</span> <span class="identifier">clone_as</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(*</span><span class="identifier">foo_base</span><span class="special">);</span>
     122        <span class="identifier">assert</span><span class="special">(</span><span class="identifier">foo_clone</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span>
     123       
     124    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
     125<span class="special">}</span>
     126</pre>
     127<p>
     128    </p>
     129<p>
     130      Note that we pass references to these functions rather than pointers, and these
     131      functions work for <span class="emphasis"><em>Cloneable</em></span> types and generally. We can
     132      also pass an allocator to these functions, but more on custom allocation later.
     133    </p>
     134<p>
     135      Although it is fine to use the default base class in this example and other
     136      similar cases, we shall see that in general it is better to provide our own
     137      base classes. This gives us flexibility and space for customisation, allows
     138      us to use the types in associative containers, and to control resource management.
    83139    </p>
    84140<p>
  • sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html

    r54639 r54657  
    3030<p>
    3131        In the previous example, we did not supply a base class, so our Cloneable
    32         type was given the <code class="computeroutput"><span class="identifier">base_type</span></code>.
     32        type was given the default <code class="computeroutput"><span class="identifier">base_type</span></code>.
    3333        Below, we prepare our own base type <code class="computeroutput"><span class="identifier">Animal</span></code>,
    3434        which of course has a virtual destructor, as well as a means to get a member
     
    7474<p>
    7575        We derive our <code class="computeroutput"><span class="identifier">Cat</span></code> class from
    76         <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">,</span> <span class="identifier">Animal</span><span class="special">&gt;</span></code>. The first type argument to <code class="computeroutput"><span class="identifier">base</span><span class="special">&lt;...&gt;</span></code>
    77         is the derived type to use for cloning, and the second argument is the common
    78         base type of the hierarhcy. As we saw in the first example, if you do not
    79         provide your own base type, your Cloneable type will use the base <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base_type</span></code>.
     76        <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">,</span> <span class="identifier">Animal</span><span class="special">&gt;</span></code>. The first type argument to <code class="computeroutput"><span class="identifier">base</span><span class="special">&lt;</span><span class="identifier">Cat</span><span class="special">,</span> <span class="identifier">Animal</span><span class="special">&gt;</span></code> is the derived type to use for cloning,
     77        and the second argument is the common base type of the hierarhcy. As we saw
     78        in the first example, if you do not provide your own base type, your Cloneable
     79        type will use the base <code class="computeroutput"><span class="identifier">cloneable</span><span class="special">::</span><span class="identifier">base_type</span></code>.
    8080      </p>
    8181<p>
  • sandbox/cloneable/libs/cloneable/doc/html/index.html

    r54640 r54657  
    2929<div><p class="copyright">Copyright © 2009 Christian Schladetsch</p></div>
    3030<div><div class="legalnotice" title="Legal Notice">
    31 <a name="id651274"></a><p>
     31<a name="id657828"></a><p>
    3232        Distributed under the Boost Software License, Version 1.0. (See accompanying
    3333        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
     
    7575</div>
    7676<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
    77 <td align="left"><p><small>Last revised: July 04, 2009 at 10:03:51 GMT</small></p></td>
     77<td align="left"><p><small>Last revised: July 04, 2009 at 21:44:10 GMT</small></p></td>
    7878<td align="right"><div class="copyright-footer"></div></td>
    7979</tr></table>
Note: See TracChangeset for help on using the changeset viewer.