Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r54658 - in sandbox/cloneable: boost/cloneable libs/cloneable/doc libs/cloneable/doc/html libs/cloneable/doc/html/cloneable libs/cloneable/doc/html/cloneable/heterogenous_containers libs/cloneable/doc/html/cloneable/tutorial libs/cloneable/test
From: christian.schladetsch_at_[hidden]
Date: 2009-07-04 19:20:43

Author: cschladetsch
Date: 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
New Revision: 54658
URL: http://svn.boost.org/trac/boost/changeset/54658

Log:
updated docs

Text files modified:
   sandbox/cloneable/boost/cloneable/abstract_base.hpp | 14 ++++++
   sandbox/cloneable/libs/cloneable/doc/cloneable.qbk | 67 +++++++++++++++++++-------------
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/change_log.html | 2
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/vector.html | 4
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html | 7 +-
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/cloneable_traits.html | 2
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/controlling_construction.html | 13 +++--
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/customising_the_cloning_process.html | 39 +++++++++++++++---
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/dealing_with_muliple_sub_objects.html | 27 +++++++++---
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/simple_hierarchical_cloning.html | 82 +++++++++++++++++++++------------------
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_custom_allocators.html | 14 +++--
   sandbox/cloneable/libs/cloneable/doc/html/index.html | 4
   sandbox/cloneable/libs/cloneable/test/tests.cpp | 2
   13 files changed, 177 insertions(+), 100 deletions(-)

Modified: sandbox/cloneable/boost/cloneable/abstract_base.hpp
==============================================================================
--- sandbox/cloneable/boost/cloneable/abstract_base.hpp (original)
+++ sandbox/cloneable/boost/cloneable/abstract_base.hpp 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -55,6 +55,20 @@
 return copy_construct(alloc);
 }

+ /// MUTABLE
+ virtual this_type *make_copy(abstract_allocator &) { return 0; }
+
+ /// MUTABLE
+ this_type *clone(abstract_allocator &alloc)
+ {
+ if (this_type *copy = make_copy(alloc))
+ return copy;
+ const this_type *const_this = const_cast<const this_type *>(this);
+ if (this_type *copy = const_this->make_copy(alloc))
+ return copy;
+ return const_this->copy_construct(alloc);
+ }
+
 /// non-virtual method that allocates using default allocator
 this_type *allocate() const
 {

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-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -144,7 +144,7 @@
}
``

-Note that we pass references to these functions rather than pointers, and these functions work for ['Cloneable] types and generally.
+__note__ we pass references to these functions rather than pointers, and these functions work for ['Cloneable] types and generally.
We can also pass an allocator to these functions, but more on custom allocation later.

Although it is fine to use
@@ -175,7 +175,7 @@
};
``

-Note that `Animal` doesn't have to derive from anything, or have any special members or methods.
+__note__ `Animal` doesn't have to derive from anything, or have any special members or methods.
Now let's use our base class to create a simple type hierarchy:

``
@@ -217,7 +217,7 @@
};
``

-Note that the `clone()` method returns
+__note__ the `clone()` method returns
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.

@@ -250,7 +250,7 @@
};
``

-`Dog` is just like a cat, but different. `Labrador` is the first example we have seen
+`Dog` is just like a cat, but different :-). `Labrador` is the first example we have seen
that uses multiple inheritance. In this case, we are saying that a Labrador is-a Dog,
and is Cloneable as either a Dog or a Labrador. Using these types:

@@ -428,15 +428,15 @@
{
 T2 *t2 = new T2();

- assert(can_clone_as<W>(*t2));
- assert(can_clone_as<T0>(*t2));
- assert(can_clone_as<T1>(*t2));
- assert(can_clone_as<T2>(*t2));
-
- assert(can_create_as<W>(*t2));
- assert(can_create_as<T0>(*t2));
- assert(can_create_as<T1>(*t2));
- assert(can_create_as<T2>(*t2));
+ assert(t2->can_clone_as<W>());
+ assert(t2->can_clone_as<T0>());
+ assert(t2->can_clone_as<T1>());
+ assert(t2->can_clone_as<T2>());
+
+ assert(t2->can_create_as<W>());
+ assert(t2->can_create_as<T0>());
+ assert(t2->can_create_as<T1>());
+ assert(t2->can_create_as<T2>());

 // clone sub-objects
 W *t2_w = t2->clone_as<W>();
@@ -454,7 +454,7 @@
}
``

-Note that if a sub-type `S` in type `T` is not default-constructabe, an exception of type
+__alert__ if a sub-type `S` in type `T` is not default-constructabe, an exception of type
`no_default_construction` will be thrown if you attempt to default-create a new `S` instance
from a `T` instance.

@@ -483,14 +483,23 @@
};
``

-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`. 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.
+Please ensure that you override the `make_copy() const` method correctly. It must return
+a type that is co-variant with the base you used for the derived type, and should be
+`const`. If you make a mistake on the return type, the compiler will complain.
+There is a non-const `make_copy()` method as well. This will be invoked on a non-const
+original, then the const `make_copy() const` will be attempted before finally using
+the `copy_construct() const` method. To summarise:
+
+* Attempting to make a copy of a non-const original will invoke `make_copy()`
+* If this fails or is not over-ridden, then the `make_copy() const` method is invoked.
+* If this fails is or not over-ridden, then `copy_construct() const` is invoked.
+
+This provides a means for clones to be made that alter the original, if you need
+to do that. For `const` originals, the process starts from step 2. All of these
+methods are over-loaded with a similar method that takes an `abstract_allocator` argument.

-This example uses the heap to make clones; we will next see how to make
-clones using any standard-compliant allocator type.
+Which is a nice segue into the next section. This example used the heap to make clones;
+we will next see how to make clones using any standard-compliant allocator type.

[endsect]

@@ -502,7 +511,7 @@

When making a new object, sub-object, clone or sub-clone, the underlying `abstract_base`
is given a reference to an `abstract_allocator`. This is
-an interface (containing only pure virtual methods) that is used to expose a specialised
+an interface used to expose a specialised
`allocator<T>` to the non-specific `abstract_base`. This process is easy to understand with some examples:

``
@@ -526,7 +535,7 @@
class Foo : public cloneable::base<Foo>
{
 // over-ride the make_copy method, providing our own means to make a clone
- Foo *make_copy(cloneable::abstract_allocator &alloc) const
+ Foo *make_copy(cloneable::abstract_allocator &alloc) const
 {
 Foo *copy = cloneable::create<Foo>(alloc);

@@ -540,10 +549,12 @@
Recall that if your class can be correctly copy-constructed, you do not need to
provide a custom clone override at all. If your class only members that have value
semantics and can in turn be copy-constructed (including `std::containers`, and heterogenous::containers),
-then you do not need to provide any customisation.
+then you do not need to provide any customisation. So don't start by making a custom clone override method.
+First, check your class to see if it is actually needed. Introducing a `make_copy()` method too early
+or when not needed can create maintenance problems.

-However, if your class contains pointers of any description, or references,
-then you will in general have to provide a sensible copy-constructor, or provide a custom clone override.
+__tip__ if your class contains pointers of any description, or references,
+then you will in general have to at least provide a sensible copy-constructor, or provide a custom clone override.

In summary, there are three stages of customisation:

@@ -576,7 +587,7 @@
BOOST_STATIC_ASSERT(!cloneable::is_default_constructable<T>::value);
``

-More details are in the `clonable::traits<T>` structure.
+More details are in the `clonable::traits<T>` structure. [@boost:/libs/cloneable/boost/cloneable/traits.hpp traits.hpp]

[endsect]

@@ -812,7 +823,7 @@
const Dog *maybe_dog = vector.cast<Dog>(0);
``

-['Again, the names here have undergone a number of changes and remain in flux. Suggestions welcome!]
+['__alert__ the names here have undergone a number of changes and remain in flux. Suggestions welcome!]

`push_back` works just like with `list` and is not surprising. But the `as` and `cast` methods are new.

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-04 19:20:41 EDT (Sat, 04 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="id657967"></a>
+<a name="id687458"></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">

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/vector.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/vector.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/heterogenous_containers/vector.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -51,8 +51,8 @@

 

- Again, the names here have undergone a number of changes and remain
- in flux. Suggestions welcome!
+ <img src="../../images/alert.png" alt="alert"> the names here have undergone a number of changes and
+ remain in flux. Suggestions welcome!
 

 <code class="computeroutput">push_back</code> works just like

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -127,9 +127,10 @@

 

- Note that we pass references to these functions rather than pointers, and these
- functions work for Cloneable types and generally. We can
- also pass an allocator to these functions, but more on custom allocation later.
+ <img src="../images/note.png" alt="note"> we pass references to these functions rather than pointers,
+ and these functions work for Cloneable types and generally.
+ We can also pass an allocator to these functions, but more on custom allocation
+ later.
 

 Although it is fine to use the default base class in this example and other

Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/cloneable_traits.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/cloneable_traits.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/cloneable_traits.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -54,7 +54,7 @@
 

 More details are in the <code class="computeroutput">clonable::traits<T></code>
- structure.
+ structure. traits.hpp
 
</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/controlling_construction.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/controlling_construction.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/controlling_construction.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -50,8 +50,7 @@
 errors when using this type in the Cloneable libray, you must indicate that
 it is not default-constructible by passing the <code class="computeroutput">no_default_construction_tag</code>
 type as a parameter to <code class="computeroutput">cloneable::base<></code>. The order that you give the base-type
- or tag-types to <code class="computeroutput">cloneable::base<></code> is not important and is dealt with
- correctly by the library.
+ or tag-types to <code class="computeroutput">cloneable::base<></code> is not important.
 

 Putting this type to use:
@@ -63,8 +62,8 @@
{
 string str = "foo";
 T0 *p = new T0(str);
- T0 *q = p->clone_as<T0>();
- assert(&q->str == &str);
+ T0 *q = clone(*p); // or, p->clone_as<T0>();
+ assert(&q->str == &str);

 // demonstrate that attempting to create
 // a new T0 instance without parameters
@@ -87,7 +86,11 @@

 A <code class="computeroutput">no_default_construction</code>
 exception is thrown if you attempt to default-construct a type that has no
- default constructor.
+ default constructor. As you would expect, if a Cloneable Q type derives from
+ a non-default-constructable type, then Q is also not default-constructable.
+ 
+
+ Next, we'll look at how to use existing 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/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-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -54,16 +54,39 @@

 

- 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>. 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.
+ Please ensure that you override the <code class="computeroutput">make_copy() const</code> method
+ correctly. It must return a type that is co-variant with the base you used
+ for the derived type, and should be <code class="computeroutput">const</code>.
+ If you make a mistake on the return type, the compiler will complain. There
+ is a non-const <code class="computeroutput">make_copy()</code> method as well. This will be invoked on
+ a non-const original, then the const <code class="computeroutput">make_copy() const</code> will
+ be attempted before finally using the <code class="computeroutput">copy_construct() const</code> method.
+ To summarise:
 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ Attempting to make a copy of a non-const original will invoke <code class="computeroutput">make_copy()</code>
+</li>
+<li class="listitem">
+ If this fails or is not over-ridden, then the <code class="computeroutput">make_copy() const</code>
+ method is invoked.
+ </li>
+<li class="listitem">
+ If this fails is or not over-ridden, then <code class="computeroutput">copy_construct() const</code>
+ is invoked.
+ </li>
+</ul></div>

- This example uses the heap to make clones; we will next see how to make clones
- using any standard-compliant allocator type.
+ This provides a means for clones to be made that alter the original, if you
+ need to do that. For <code class="computeroutput">const</code> originals,
+ the process starts from step 2. All of these methods are over-loaded with
+ a similar method that takes an <code class="computeroutput">abstract_allocator</code>
+ argument.
+ 
+
+ Which is a nice segue into the next section. This example used 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/dealing_with_muliple_sub_objects.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/dealing_with_muliple_sub_objects.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/dealing_with_muliple_sub_objects.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -31,7 +31,7 @@
 When working with types that have multiple cloneable sub-objects, we must
 use the <code class="computeroutput">clone_as<T></code> and
 <code class="computeroutput">create_as<T></code> methods
- to disambiguate which sub-type to clone or create.
+ or functions to disambiguate which sub-type to clone or create.
 

 This is demonstrated below:
@@ -49,16 +49,27 @@
{
 T2 *t2 = new T2();

+ assert(t2->can_clone_as<W>());
+ assert(t2->can_clone_as<T0>());
+ assert(t2->can_clone_as<T1>());
+ assert(t2->can_clone_as<T2>());
+
+ assert(t2->can_create_as<W>());
+ assert(t2->can_create_as<T0>());
+ assert(t2->can_create_as<T1>());
+ assert(t2->can_create_as<T2>());
+
 // clone sub-objects
 W *t2_w = t2->clone_as<W>();
- T1 *t2_t1 = t2->clone_as<T1>();
 T0 *t2_t0 = t2->clone_as<T0>();
+ T1 *t2_t1 = t2->clone_as<T1>();
+ T1 *t2_t2 = t2->clone_as<T2>();

 // create sub-objects
 W *t2_w_new = t2->create_as<W>();
- T1 *t2_t1_new = t2->create_as<T1>();
 T0 *t2_t0_new = t2->create_as<T0>();
-
+ T1 *t2_t1_new = t2->create_as<T1>();
+ T2 *t2_t2_new = t2->create_as<T2>();

 return 0;
}
@@ -66,9 +77,11 @@

 

- Note that if a sub-type S in type T is not default-constructabe, an exception
- of type no_default_construction will be thrown if you attempt to default-create
- a new S instance from a T instance.
+ <img src="../../images/alert.png" alt="alert"> if a sub-type <code class="computeroutput">S</code>
+ in type <code class="computeroutput">T</code> is not default-constructabe,
+ an exception of type <code class="computeroutput">no_default_construction</code>
+ will be thrown if you attempt to default-create a new <code class="computeroutput">S</code>
+ instance from a <code class="computeroutput">T</code> instance.
 
</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-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -52,9 +52,9 @@

 

- Note that <code class="computeroutput">Animal</code> doesn't
- have to derive from anything, or have any special members or methods. Now
- let's use our base class to create a simple type hierarchy:
+ <img src="../../images/note.png" alt="note"> <code class="computeroutput">Animal</code>
+ doesn't have to derive from anything, or have any special members or methods.
+ Now let's use our base class to create a simple type hierarchy:
 


@@ -81,7 +81,7 @@

 Other than that, <code class="computeroutput">Cat</code> implements
 the <code class="computeroutput">get_name</code> pure virtual
- method derived in the base class <code class="computeroutput">Animal</code>.
+ method derived from the base class <code class="computeroutput">Animal</code>.
 

 Now, let's use it:
@@ -107,10 +107,9 @@

 

- Note that the <code class="computeroutput">clone()</code>
- method returns a pointer to the base class 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.
+ <img src="../../images/note.png" alt="note"> the <code class="computeroutput">clone()</code> method returns a pointer to the base class
+ 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
@@ -126,7 +125,17 @@
 

 As we shall soon see, this is also handy when we have choices of which sub-object
- to clone.
+ to clone. Of course, we could also use the free-function <code class="computeroutput">clone</code>:
+ 
+
+
+
+<pre class="programlisting">using namespace cloneable;
+
+assert(can_clone_as<Cat>(*cat));
+Cat *cloned = clone(*cat);
+</pre>
+
 

 We now add other animals to the hierachy, including one that uses multiple
@@ -147,22 +156,24 @@
 

 <code class="computeroutput">Dog</code> is just like a cat, but
- different. <code class="computeroutput">Labrador</code> is the
- first example we have seen that uses multiple inheritance. In this case,
- we are saying that a Labrador is-a Dog, and is Cloneable as either a Dog
- or a Labrador. Using these types:
+ different <img src="../../images/smiley.png" alt="smiley">. <code class="computeroutput">Labrador</code>
+ is the first example we have seen that uses multiple inheritance. In this
+ case, we are saying that a Labrador is-a Dog, and is Cloneable as either
+ a Dog or a Labrador. Using these types:
 



<pre class="programlisting">int main()
{
- Labrador *lab = new Labrador();
- Dog *dog = lab->clone_as<Dog>();
- Labrador *cloned_lab = lab->clone_as<Labrador>();
+ Animal *lab = new Labrador();
+ Animal *lab_as_dog = lab->clone_as<Dog>();
+ Animal *lab_clone = lab->clone_as<Labrador>();

- assert(typeid(*dog) == typeid(Dog));
- assert(typeid(*cloned_lab) == typeid(Labrador));
+ assert(typeid(*lab_as_dog) == typeid(Dog));
+ assert(typeid(*lab_clone) == typeid(Labrador));
+
+ assert(!can_clone_as<Labrador>(lab_as_dog));

 return 0;
}
@@ -175,25 +186,24 @@
 method.
 

- It should be noted that when using <code class="computeroutput">clone_as<Ty></code>, we actually are making a type of <code class="computeroutput">Ty</code>, rather than making another type and
- casting up.
+ It should be noted that when using <code class="computeroutput">clone_as<Ty></code>, we actually are making an instance of
+ type <code class="computeroutput">Ty</code>, rather than making
+ another type and casting up.
 

- We can also use the Cloneable library to make a new instance, with no duplication:
+ We can also use the Cloneable library to make a new derived instance from
+ a base type:
 



-<pre class="programlisting">Animal *MakeNew(const cloneable::abstract_base<Animal> &animal)
-{
- return animal.create_new();
-}
-
-int main()
+<pre class="programlisting">int main()
{
- Cat *cat = new Cat();
- Animal *new_animal = MakeNew(*cat);
+ Animal *cat = new Cat();
+ Animal *new_animal = create_new(*cat);
+
 assert(typeid(*new_animal) == typeid(Cat));
+
 return 0;
}
</pre>
@@ -201,18 +211,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 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> mix-in, which all derived <code class="computeroutput">Animal</code>s are implicitly convertible to.
+ pointer to the base.
 

 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.
+ The first of these details is dealing with types that are not default-constructable.
+ This is a very useful part of the library, as it allows for containers with
+ elements that are not default constructable and do not have assignment operations.
+ We'll get to that in the containers tutorial, but for now let's quickly cover
+ the basics in the next section.
 
</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_custom_allocators.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_custom_allocators.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial/using_custom_allocators.html 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -36,8 +36,7 @@
 When making a new object, sub-object, clone or sub-clone, the underlying
 <code class="computeroutput">abstract_base</code> is given a
 reference to an <code class="computeroutput">abstract_allocator</code>.
- This is an interface (containing only pure virtual methods) that is used
- to expose a specialised <code class="computeroutput">allocator<T></code>
+ This is an interface used to expose a specialised <code class="computeroutput">allocator<T></code>
 to the non-specific <code class="computeroutput">abstract_base</code>.
 This process is easy to understand with some examples:
 
@@ -70,7 +69,7 @@
<pre class="programlisting">class Foo : public cloneable::base<Foo>
{
 // over-ride the make_copy method, providing our own means to make a clone
- Foo *make_copy(cloneable::abstract_allocator &amp;alloc) const
+ Foo *make_copy(cloneable::abstract_allocator &alloc) const
 {
 Foo *copy = cloneable::create<Foo>(alloc);

@@ -87,11 +86,14 @@
 to provide a custom clone override at all. If your class only members that
 have value semantics and can in turn be copy-constructed (including <code class="computeroutput">std::containers</code>,
 and heterogenous::containers), then you do not need to provide any customisation.
+ So don't start by making a custom clone override method. First, check your
+ class to see if it is actually needed. Introducing a <code class="computeroutput">make_copy()</code> method too early or when not needed can
+ create maintenance problems.
 

- However, if your class contains pointers of any description, or references,
- then you will in general have to provide a sensible copy-constructor, or
- provide a custom clone override.
+ <img src="../../images/tip.png" alt="tip"> if your class contains pointers of any description,
+ or references, then you will in general have to at least provide a sensible
+ copy-constructor, or provide a custom clone override.
 

 In summary, there are three stages of customisation:

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-04 19:20:41 EDT (Sat, 04 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="id657828"></a>
+<a name="id687319"></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)
 
@@ -74,7 +74,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 04, 2009 at 21:44:10 GMT</td>
+<td align="left">Last revised: July 04, 2009 at 23:19:19 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/cloneable/libs/cloneable/test/tests.cpp
==============================================================================
--- sandbox/cloneable/libs/cloneable/test/tests.cpp (original)
+++ sandbox/cloneable/libs/cloneable/test/tests.cpp 2009-07-04 19:20:41 EDT (Sat, 04 Jul 2009)
@@ -197,6 +197,8 @@
 assert(t2->can_create_as<T1>());
 assert(t2->can_create_as<T2>());
 assert(t2->can_create_as<W>());
+
+ // these free-functions currently do not work...
 /* assert(can_clone_as<W>(*t2));
 assert(can_clone_as<T0>(*t2));
 assert(can_clone_as<T1>(*t2));

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