Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r54586 - in sandbox/cloneable/libs/cloneable/doc: . html html/cloneable html/cloneable/tutorial
From: christian.schladetsch_at_[hidden]
Date: 2009-07-02 05:23:15

Next message: christian.schladetsch_at_[hidden]: "[Boost-commit] svn:boost r54587 - sandbox/cloneable/libs/cloneable"
Previous message: christian.schladetsch_at_[hidden]: "[Boost-commit] svn:boost r54585 - sandbox/cloneable"

Author: cschladetsch
Date: 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
New Revision: 54586
URL: http://svn.boost.org/trac/boost/changeset/54586

Log:
updated

Text files modified:
   sandbox/cloneable/libs/cloneable/doc/cloneable.qbk | 77 +++++++++++++++++++++++++++++++--------
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html | 2
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/intro.html | 2
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/customising_the_cloning_process.html | 21 ++++++----
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html | 37 ++++++++++++++++---
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_external_types.html | 34 ++++++++++++++++-
   sandbox/cloneable/libs/cloneable/doc/html/index.html | 4 +-
   7 files changed, 141 insertions(+), 36 deletions(-)

Modified: sandbox/cloneable/libs/cloneable/doc/cloneable.qbk
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/cloneable.qbk (original)
+++ sandbox/cloneable/libs/cloneable/doc/cloneable.qbk 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -36,7 +36,7 @@
Cloneable objects can create clones of derived types from base types,
can do so given any STL-compliant allocator, and support multiple clone type targets.

-The user of the libray is able to override the default cloning process,
+The user of the library is able to override the default cloning process,
 and may supply custom allocators. Cloneable types can derive from other cloneable
types, in which case the user can specify which subobject type to duplicate or create when
making a new clone or new object from an existing instance.
@@ -96,6 +96,11 @@

[section Simple Hierarchical Cloning]

+In the previous example, we did not supply a base class, so our Cloneable type
+was given the `default_base_type`. Below, we prepare our own base type `Animal`,
+which of course has a virtual destructor, as well as a means to get a member
+variable from a derived type:
+
``
#include <string>
#include <boost/cloneable.hpp>
@@ -136,15 +141,19 @@
``

In this example, we note that the `clone()` method returns
-a pointer to the base class of the type hierarchy. If you know
-the derived type that you wish to be cloned, you can use the
+a pointer to the base class of the type hierarchy - in this case, `Animal`.
+We had to use a dynamic cast to down-cast to our derived type.
+
+If you know the derived type that you wish to be cloned, you can use the
`clone_as<T>()` method instead and save some typing:

``
Cat *cloned = cat->clone_as<Cat>();
``

-We now add other animals to the hierachy, including the use of multiple inheritance:
+As we shall soon see, this is also handy when we have choices of which sub-object to clone.
+
+We now add other animals to the hierachy, including one that uses multiple inheritance:

``
class Dog : public cloneable::base<Dog, Animal>
@@ -160,14 +169,19 @@
 Labrador *lab = new Labrador();
 Dog *dog = lab->clone_as<Dog>();
 Labrador *cloned_lab = lab->clone_as<Labrador>();
+
+ assert(typeid(*dog) == typeid(Dog));
+ assert(typeid(*cloned_lab) == typeid(Labrador));
+
 return 0;
}
``

Here we see that class Labrador is-a Dog, and is also cloneable as a Labrador.
-When cloning this class, we specify which sub-object we wish to duplicate. Note that when using `clone_as<T>`, we actually are making a type of T, rather than making another type and casting up.
+When cloning this class, we specify which sub-object we wish to duplicate. Note that
+when using `clone_as<T>`, we actually are making a type of T, rather than making another type and casting up.

-We can also use the Cloneable library to make a new instance, without duplication:
+We can also use the Cloneable library to make a new instance, with no duplication:

``
Animal *MakeNew(const cloneable::abstract_base<Animal> &animal)
@@ -186,12 +200,16 @@

This will create a new derived animal type (not a new base), and return a pointer
to the base. Here we used a free-function to make the new object, to show how
-to use the `abstract_base` template. We used `abstract_base<Animal>`, rather than
+to use the `abstract_base` template structure. We used `abstract_base<Animal>`, rather than
just `Animal`, as the base type argument for the `MakeNew` function. This is because
the base class we provided, `Animal`, does not derive from anything and does not
-have any clone-related methods. These methods are added by the `abstract_base<>` mixin,
+have any clone-related methods. These methods are added by the `abstract_base<>` mix-in,
which all derived `Animal`s are implicitly convertible to.

+This is the basics of the cloneability side of the library. But there are a few more
+details and use-cases to cover before we get to the containers. The first of which is
+dealing with types that we can't change.
+
[endsect]

[section Using External Types]
@@ -201,7 +219,7 @@
To address this issue, we can use the `cloneable::adaptor<Type,Base>` structure:

``
-class External { }; // cannot be modified
+class External { /* hidden impl */ }; // for whatever reason, this cannot be modified

class MyBase { virtual ~MyBase() { } };

@@ -215,21 +233,44 @@
}
``

+By using the `cloneable::adaptor<Type, Base>` structure, we create a new type
+that is cloneable and can be used correctly in heterogenous containers.
+
Alternatively of course, we could just make a new structure which either derives
from or encapsulates the external class. This will be necessary if you wish to
pass construction arguments to the external type, or provide a custom clone
-method for it.
+method for it. For example:
+
+``
+class Wrapper : cloneable::base<Wrapper, Base>
+{
+ External *impl;
+public:
+ Wrapper() : impl(0) { }
+ Wrapper(const Wrapper &other)
+ {
+ impl = new Wrapper(*other.impl);
+ }
+};
+``
+
+There are of courswe many ways to do this, and how you do it will depend on many factors.
+Just bare in mind that `cloneable::adaptor<>` is there if you need it.
+
+Next, we look at how to customise the cloning operation itself, and how we can
+use our own or other allocators. This is important to understand before we
+finally get to the heterogenous containers.

[endsect]

[section Customising the Cloning Process]

So far, we have been making clones using the default cloning process.
-This uses the copy-constructor of the given type to generate the clone.
+This uses the copy-constructor of a given type T to generate the clone.
However, quite often we will want to have greater control over this process,
and sometimes we don't want to or cannot use a copy constructor at all.

-To customise the cloning process, it is a simple matter of providing a `make_copy`
+Customising the cloning process is a simple matter of providing a `make_copy`
method overload in your derived class:

``
@@ -238,16 +279,20 @@
 // over-ride the make_copy method, providing our own means to make a clone
 Foo *make_copy() const
 {
- Foo *copy = new Foo();
- // write values to copy from this
- return copy;
+ Foo *copy = new Foo();
+ // TODO: write values to copy from this
+ return copy;
 }
};
``

Please ensure that you override the `make_copy()` method correctly. It must return
a type that is co-variant with the base you used for the derived type, and must be
-`const`. This example uses the heap to make clones; now we will see how to make
+`const`. If you make a mistake on the return type, the compiler will complain. But
+if you forget to make the method const, it will not be invoked when needed and there
+will be no warning or error.
+
+This example uses the heap to make clones; we will next see how to make
clones using any standard-compliant allocator type.

[endsect]

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -27,7 +27,7 @@
<a name="cloneable.change_log"></a><a class="link" href="change_log.html" title="Change Log"> Change Log</a>
</h2></div></div></div>
<a name="cloneable.change_log.version_0_1"></a><h4>
-<a name="id669928"></a>
+<a name="id671355"></a>
<a class="link" href="change_log.html#cloneable.change_log.version_0_1">Version 0.1</a>
</h4>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/intro.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/intro.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/intro.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -36,7 +36,7 @@
 so given any STL-compliant allocator, and support multiple clone type targets.
 

- The user of the libray is able to override the default cloning process, and
+ The user of the library is able to override the default cloning process, and
 may supply custom allocators. Cloneable types can derive from other cloneable
 types, in which case the user can specify which subobject type to duplicate
 or create when making a new clone or new object from an existing instance.

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/customising_the_cloning_process.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/customising_the_cloning_process.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/customising_the_cloning_process.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -29,12 +29,12 @@
</h3></div></div></div>

 So far, we have been making clones using the default cloning process. This
- uses the copy-constructor of the given type to generate the clone. However,
+ uses the copy-constructor of a given type T to generate the clone. However,
 quite often we will want to have greater control over this process, and sometimes
 we don't want to or cannot use a copy constructor at all.
 

- To customise the cloning process, it is a simple matter of providing a <code class="computeroutput">make_copy</code> method overload in your derived
+ Customising the cloning process is a simple matter of providing a <code class="computeroutput">make_copy</code> method overload in your derived
 class:
 

@@ -45,9 +45,9 @@
 // over-ride the make_copy method, providing our own means to make a clone
 Foo *make_copy() const
 {
- Foo *copy = new Foo();
- // write values to copy from this
- return copy;
+ Foo *copy = new Foo();
+ // TODO: write values to copy from this
+ return copy;
 }
};
</pre>
@@ -56,9 +56,14 @@

 Please ensure that you override the <code class="computeroutput">make_copy()</code> method correctly. It must return a type
 that is co-variant with the base you used for the derived type, and must
- be <code class="computeroutput">const</code>. This example uses
- the heap to make clones; now we will see how to make clones using any standard-compliant
- allocator type.
+ be <code class="computeroutput">const</code>. If you make a mistake
+ on the return type, the compiler will complain. But if you forget to make
+ the method const, it will not be invoked when needed and there will be no
+ warning or error.
+ 
+
+ This example uses the heap to make clones; we will next see how to make clones
+ using any standard-compliant allocator type.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -28,6 +28,13 @@
 Hierarchical Cloning</a>
</h3></div></div></div>

+ In the previous example, we did not supply a base class, so our Cloneable
+ type was given the <code class="computeroutput">default_base_type</code>.
+ Below, we prepare our own base type <code class="computeroutput">Animal</code>,
+ which of course has a virtual destructor, as well as a means to get a member
+ variable from a derived type:
+ 
+


<pre class="programlisting">#include <string>
@@ -71,8 +78,12 @@
 

 In this example, we note that the <code class="computeroutput">clone()</code> method returns a pointer to the base class
- of the type hierarchy. If you know the derived type that you wish to be cloned,
- you can use the <code class="computeroutput">clone_as<T>()</code>
+ of the type hierarchy - in this case, <code class="computeroutput">Animal</code>.
+ We had to use a dynamic cast to down-cast to our derived type.
+ 
+
+ If you know the derived type that you wish to be cloned, you can use the
+ <code class="computeroutput">clone_as<T>()</code>
 method instead and save some typing:
 

@@ -83,7 +94,12 @@

 

- We now add other animals to the hierachy, including the use of multiple inheritance:
+ As we shall soon see, this is also handy when we have choices of which sub-object
+ to clone.
+ 
+
+ We now add other animals to the hierachy, including one that uses multiple
+ inheritance:
 


@@ -101,6 +117,10 @@
 Labrador *lab = new Labrador();
 Dog *dog = lab->clone_as<Dog>();
 Labrador *cloned_lab = lab->clone_as<Labrador>();
+
+ assert(typeid(*dog) == typeid(Dog));
+ assert(typeid(*cloned_lab) == typeid(Labrador));
+
 return 0;
}
</pre>
@@ -114,7 +134,7 @@
 up.
 

- We can also use the Cloneable library to make a new instance, without duplication:
+ We can also use the Cloneable library to make a new instance, with no duplication:
 


@@ -138,11 +158,16 @@
 This will create a new derived animal type (not a new base), and return a
 pointer to the base. Here we used a free-function to make the new object,
 to show how to use the <code class="computeroutput">abstract_base</code>
- template. We used <code class="computeroutput">abstract_base<Animal></code>, rather than just <code class="computeroutput">Animal</code>,
+ template structure. We used <code class="computeroutput">abstract_base<Animal></code>, rather than just <code class="computeroutput">Animal</code>,
 as the base type argument for the <code class="computeroutput">MakeNew</code>
 function. This is because the base class we provided, <code class="computeroutput">Animal</code>,
 does not derive from anything and does not have any clone-related methods.
- These methods are added by the <code class="computeroutput">abstract_base<></code> mixin, which all derived <code class="computeroutput">Animal</code>s are implicitly convertible to.
+ These methods are added by the <code class="computeroutput">abstract_base<></code> mix-in, which all derived <code class="computeroutput">Animal</code>s are implicitly convertible to.
+ 
+
+ This is the basics of the cloneability side of the library. But there are
+ a few more details and use-cases to cover before we get to the containers.
+ The first of which is dealing with types that we can't change.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_external_types.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_external_types.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_external_types.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -36,7 +36,7 @@



-<pre class="programlisting">class External { }; // cannot be modified
+<pre class="programlisting">class External { /* hidden impl */ }; // for whatever reason, this cannot be modified

class MyBase { virtual ~MyBase() { } };

@@ -52,10 +52,40 @@

 

+ By using the <code class="computeroutput">cloneable::adaptor<Type, Base></code>
+ structure, we create a new type that is cloneable and can be used correctly
+ in heterogenous containers.
+ 
+
 Alternatively of course, we could just make a new structure which either
 derives from or encapsulates the external class. This will be necessary if
 you wish to pass construction arguments to the external type, or provide
- a custom clone method for it.
+ a custom clone method for it. For example:
+ 
+
+
+
+<pre class="programlisting">class Wrapper : cloneable::base<Wrapper, Base>
+{
+ External *impl;
+public:
+ Wrapper() : impl(0) { }
+ Wrapper(const Wrapper &other)
+ {
+ impl = new Wrapper(*other.impl);
+ }
+};
+</pre>
+
+ 
+
+ There are of courswe many ways to do this, and how you do it will depend
+ on many factors. Just bare in mind that <code class="computeroutput">cloneable::adaptor<></code> is there if you need it.
+ 
+
+ Next, we look at how to customise the cloning operation itself, and how we
+ can use our own or other allocators. This is important to understand before
+ we finally get to the heterogenous containers.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>

Modified: sandbox/cloneable/libs/cloneable/doc/html/index.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/index.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/index.html 2009-07-02 05:23:14 EDT (Thu, 02 Jul 2009)
@@ -28,7 +28,7 @@
</h3></div></div></div>
<div>Copyright © 2009 Christian Schladetsch</div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id669843"></a>
+<a name="id671270"></a>
 Distributed under the Boost Software License, Version 1.0. (See accompanying
 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
@@ -56,7 +56,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: July 02, 2009 at 06:05:29 GMT</td>
+<td align="left">Last revised: July 02, 2009 at 09:22:22 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Next message: christian.schladetsch_at_[hidden]: "[Boost-commit] svn:boost r54587 - sandbox/cloneable/libs/cloneable"
Previous message: christian.schladetsch_at_[hidden]: "[Boost-commit] svn:boost r54585 - sandbox/cloneable"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk