|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r54568 - in sandbox/cloneable/libs/cloneable/doc: . html html/cloneable html/index
From: christian.schladetsch_at_[hidden]
Date: 2009-07-01 16:50:31
Author: cschladetsch
Date: 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
New Revision: 54568
URL: http://svn.boost.org/trac/boost/changeset/54568
Log:
updated dox
Text files modified:
sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html | 4 +-
sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html | 4 +-
sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html | 56 ++++++++++++++++++++++++++++++----------
sandbox/cloneable/libs/cloneable/doc/html/index.html | 26 +++++++++---------
sandbox/cloneable/libs/cloneable/doc/html/index/s04.html | 6 ++--
sandbox/cloneable/libs/cloneable/doc/html/index/s05.html | 10 +++---
sandbox/cloneable/libs/cloneable/doc/tutorial.xml | 33 +++++++++++++++++++++--
7 files changed, 97 insertions(+), 42 deletions(-)
Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -25,10 +25,10 @@
<div class="section" title="Heterogenous Containers">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cloneable.containers"></a>Heterogenous Containers</h2></div></div></div>
-<div class="toc"><dl><dt><span class="section">Overview</span></dt></dl></div>
+<div class="toc"><dl><dt><span class="section">Overview</span></dt></dl></div>
<div class="section" title="Overview">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687714"></a>Overview</h3></div></div></div>
+<a name="id642982"></a>Overview</h3></div></div></div>
<p>This tutorial demonstrates the use of the <span class="emphasis"><em>heterogenous</em></span> container system provided in the Cloneable library.
</p>
</div>
Modified: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -24,10 +24,10 @@
<div class="section" title="Testsuite">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cloneable.tests"></a>Testsuite</h2></div></div></div>
-<div class="toc"><dl><dt><span class="section">Acceptance tests</span></dt></dl></div>
+<div class="toc"><dl><dt><span class="section">Acceptance tests</span></dt></dl></div>
<div class="section" title="Acceptance tests">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687789"></a>Acceptance tests</h3></div></div></div>
+<a name="id643056"></a>Acceptance tests</h3></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
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-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -26,16 +26,16 @@
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cloneable.tutorial"></a>Tutorial</h2></div></div></div>
<div class="toc"><dl>
-<dt><span class="section">Overview</span></dt>
-<dt><span class="section">Basic Cloning</span></dt>
-<dt><span class="section">Simple Hierarchical Cloning</span></dt>
-<dt><span class="section">Using External Types</span></dt>
-<dt><span class="section">Customising the Cloning Process</span></dt>
-<dt><span class="section">Using Custom Allocators</span></dt>
+<dt><span class="section">Overview</span></dt>
+<dt><span class="section">Basic Cloning</span></dt>
+<dt><span class="section">Simple Hierarchical Cloning</span></dt>
+<dt><span class="section">Using External Types</span></dt>
+<dt><span class="section">Customising the Cloning Process</span></dt>
+<dt><span class="section">Using Custom Allocators</span></dt>
</dl></div>
<div class="section" title="Overview">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687528"></a>Overview</h3></div></div></div>
+<a name="id642746"></a>Overview</h3></div></div></div>
<p>This tutorial progresses through the basic usage of the library,
demonstrating how to make a new Cloneable type, how to make
an exsiting, external type Cloneable, and how to deal with
@@ -43,7 +43,7 @@
</div>
<div class="section" title="Basic Cloning">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687539"></a>Basic Cloning</h3></div></div></div>
+<a name="id642756"></a>Basic Cloning</h3></div></div></div>
<p>
The following is a very quick introduction to Boost.Cloneable:
</p>
@@ -68,7 +68,7 @@
</div>
<div class="section" title="Simple Hierarchical Cloning">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687567"></a>Simple Hierarchical Cloning</h3></div></div></div>
+<a name="id642784"></a>Simple Hierarchical Cloning</h3></div></div></div>
<pre class="programlisting">
#include <string>
#include <boost/cloneable.hpp>
@@ -137,7 +137,9 @@
</pre>
<p>
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.
+When cloning this class, we specify which sub-object we wish to duplicate. Note that when using <code class="computeroutput">clone_as<T></code>, we actually are making a type of T, rather than making another type and casting up.
+</p>
+<p>
We can also use the Cloneable library to make a new instance, without duplication:
</p>
<pre class="programlisting">
@@ -155,12 +157,12 @@
}
</pre>
<p>
- This will create a new derived animal type (not a new base), and return a pointer to the base. Note that 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.
+ 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>, 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.
</p>
</div>
<div class="section" title="Using External Types">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687645"></a>Using External Types</h3></div></div></div>
+<a name="id642875"></a>Using External Types</h3></div></div></div>
<p>
Quite often we find ourselves using classes that are defined in an external library. These are not open to be changed, but we would still like them to be Cloneable. To address this issue, we can use the <code class="computeroutput">cloneable::adaptor<Type,Base></code> structure:
</p>
@@ -184,7 +186,7 @@
</div>
<div class="section" title="Customising the Cloning Process">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687668"></a>Customising the Cloning Process</h3></div></div></div>
+<a name="id642898"></a>Customising the Cloning Process</h3></div></div></div>
<p>
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, 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.
</p>
@@ -208,9 +210,35 @@
</div>
<div class="section" title="Using Custom Allocators">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id687694"></a>Using Custom Allocators</h3></div></div></div>
+<a name="id642924"></a>Using Custom Allocators</h3></div></div></div>
<p>
+ The entire <span class="emphasis"><em>Cloneable</em></span> system was designed to support general allocators. This is to ensure they work well in containers. When making a new object or sub-object or clone or sub-clone, the abstract_base is given a reference to an <code class="computeroutput">abstract_allocator</code>. This is an abstract interface (containing only pure virtual methods) that is used to expose a specialised <code class="computeroutput">allocator<T></code> to the non-specific <code class="computeroutput">abstract_base</code>. This is much easier to understand with some examples:
</p>
+<pre class="programlisting">
+ int main()
+ {
+ std::allocator<int> alloc;
+ Cat *cat = cloneable::create<Cat>(alloc); // create a Cat using the allocator
+ Cat *dupe = cat->clone_as<Cat>(alloc); // clone using the same allocator
+ }
+ </pre>
+<p>
+ As you can see, most of the internals can be safely ignored. However, if you write a clone override, you should do so for the method that takes an <code class="computeroutput">abstract_allocator &</code>, rather than just always use the heap:
+ </p>
+<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 &alloc) const
+ {
+ //Foo *copy = new Foo();
+ Foo *copy = cloneable::create<Foo>(alloc);
+ // write values to copy from this
+ return copy;
+ }
+};
+
+ </pre>
</div>
</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-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -30,7 +30,7 @@
</div></div>
<div><p class="copyright">Copyright © 2009 Christian Schladetsch</p></div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id687462"></a><p>Use, modification and distribution is subject to the Boost
+<a name="id642680"></a><p>Use, modification and distribution is subject to the Boost
Software License, Version 1.0. (See accompanying file
<code class="filename">LICENSE_1_0.txt</code> or copy at http://www.boost.org/LICENSE_1_0.txt)</p>
</div></div>
@@ -38,31 +38,31 @@
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
-<dt><span class="section">Introduction</span></dt>
+<dt><span class="section">Introduction</span></dt>
<dt><span class="section">Tutorial</span></dt>
<dd><dl>
-<dt><span class="section">Overview</span></dt>
-<dt><span class="section">Basic Cloning</span></dt>
-<dt><span class="section">Simple Hierarchical Cloning</span></dt>
-<dt><span class="section">Using External Types</span></dt>
-<dt><span class="section">Customising the Cloning Process</span></dt>
-<dt><span class="section">Using Custom Allocators</span></dt>
+<dt><span class="section">Overview</span></dt>
+<dt><span class="section">Basic Cloning</span></dt>
+<dt><span class="section">Simple Hierarchical Cloning</span></dt>
+<dt><span class="section">Using External Types</span></dt>
+<dt><span class="section">Customising the Cloning Process</span></dt>
+<dt><span class="section">Using Custom Allocators</span></dt>
</dl></dd>
<dt><span class="section">Heterogenous Containers</span></dt>
-<dd><dl><dt><span class="section">Overview</span></dt></dl></dd>
+<dd><dl><dt><span class="section">Overview</span></dt></dl></dd>
<dt><span class="section">Frequently Asked Questions</span></dt>
<dt><span class="section">Design Overview</span></dt>
<dd><dl>
-<dt><span class="section">Class Hierachy</span></dt>
-<dt><span class="section">Abstract Allocator</span></dt>
+<dt><span class="section">Class Hierachy</span></dt>
+<dt><span class="section">Abstract Allocator</span></dt>
</dl></dd>
<dt><span class="section">Testsuite</span></dt>
-<dd><dl><dt><span class="section">Acceptance tests</span></dt></dl></dd>
+<dd><dl><dt><span class="section">Acceptance tests</span></dt></dl></dd>
</dl>
</div>
<div class="section" title="Introduction">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id687483"></a>Introduction</h2></div></div></div>
+<a name="id642700"></a>Introduction</h2></div></div></div>
<p>
The <span class="emphasis"><em>Boost.Cloneable</em></span> library provides a means for creating,
duplicating, and querying instances of object types that are specified in class hierarchies, and a set of containers* for those objects.
Modified: sandbox/cloneable/libs/cloneable/doc/html/index/s04.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/index/s04.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s04.html 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -24,9 +24,9 @@
</div>
<div class="section" title="Frequently Asked Questions">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id687731"></a>Frequently Asked Questions</h2></div></div></div>
+<a name="id642999"></a>Frequently Asked Questions</h2></div></div></div>
<div class="qandaset" title="Frequently Asked Questions">
-<a name="id687738"></a><dl><dt>1. <a href="s04.html#id687741">Question?
+<a name="id643006"></a><dl><dt>1. <a href="s04.html#id643008">Question?
</a>
</dt></dl>
<table border="0" width="100%" summary="Q and A Set">
@@ -35,7 +35,7 @@
<tbody>
<tr class="question" title="1.">
<td align="left" valign="top">
-<a name="id687741"></a><a name="id687743"></a><p><b>1.</b></p>
+<a name="id643008"></a><a name="id643011"></a><p><b>1.</b></p>
</td>
<td align="left" valign="top"><p>Question?
</p></td>
Modified: sandbox/cloneable/libs/cloneable/doc/html/index/s05.html
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/html/index/s05.html (original)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s05.html 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -24,15 +24,15 @@
</div>
<div class="section" title="Design Overview">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id687761"></a>Design Overview</h2></div></div></div>
+<a name="id643029"></a>Design Overview</h2></div></div></div>
<div class="toc"><dl>
-<dt><span class="section">Class Hierachy</span></dt>
-<dt><span class="section">Abstract Allocator</span></dt>
+<dt><span class="section">Class Hierachy</span></dt>
+<dt><span class="section">Abstract Allocator</span></dt>
</dl></div>
<div class="section" title="Class Hierachy"><div class="titlepage"><div><div><h3 class="title">
-<a name="id687768"></a>Class Hierachy</h3></div></div></div></div>
+<a name="id643036"></a>Class Hierachy</h3></div></div></div></div>
<div class="section" title="Abstract Allocator"><div class="titlepage"><div><div><h3 class="title">
-<a name="id687776"></a>Abstract Allocator</h3></div></div></div></div>
+<a name="id643043"></a>Abstract Allocator</h3></div></div></div></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: , at </small></p></td>
Modified: sandbox/cloneable/libs/cloneable/doc/tutorial.xml
==============================================================================
--- sandbox/cloneable/libs/cloneable/doc/tutorial.xml (original)
+++ sandbox/cloneable/libs/cloneable/doc/tutorial.xml 2009-07-01 16:50:31 EDT (Wed, 01 Jul 2009)
@@ -108,7 +108,9 @@
</programlisting>
<para>
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.
+When cloning this class, we specify which sub-object we wish to duplicate. Note that when using <code>clone_as<T></code>, we actually are making a type of T, rather than making another type and casting up.
+</para>
+<para>
We can also use the Cloneable library to make a new instance, without duplication:
</para>
<programlisting>
@@ -126,7 +128,7 @@
}
</programlisting>
<para>
- This will create a new derived animal type (not a new base), and return a pointer to the base. Note that we used <code>abstract_base<Animal></code>, rather than just <code>Animal</code>, as the base type argument for the <code>MakeNew</code> function. This is because the base class we provided, <code>Animal</code>, does not derive from anything and does not have any clone-related methods. These methods are added by the <code>abstract_base<></code> mixin, which all derived <code>Animal</code>s are implicitly convertible to.
+ 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>abstract_base</code> template. We used <code>abstract_base<Animal></code>, rather than just <code>Animal</code>, as the base type argument for the <code>MakeNew</code> function. This is because the base class we provided, <code>Animal</code>, does not derive from anything and does not have any clone-related methods. These methods are added by the <code>abstract_base<></code> mixin, which all derived <code>Animal</code>s are implicitly convertible to.
</para>
</section>
<section><title>Using External Types</title>
@@ -176,8 +178,33 @@
<section>
<title>Using Custom Allocators</title>
<para>
+ The entire <emphasis>Cloneable</emphasis> system was designed to support general allocators. This is to ensure they work well in containers. When making a new object or sub-object or clone or sub-clone, the abstract_base is given a reference to an <code>abstract_allocator</code>. This is an abstract interface (containing only pure virtual methods) that is used to expose a specialised <code>allocator<T></code> to the non-specific <code>abstract_base</code>. This is much easier to understand with some examples:
</para>
-
+ <programlisting>
+ int main()
+ {
+ std::allocator<int> alloc;
+ Cat *cat = cloneable::create<Cat>(alloc); // create a Cat using the allocator
+ Cat *dupe = cat->clone_as<Cat>(alloc); // clone using the same allocator
+ }
+ </programlisting>
+ <para>
+ As you can see, most of the internals can be safely ignored. However, if you write a clone override, you should do so for the method that takes an <code>abstract_allocator &</code>, rather than just always use the heap:
+ </para>
+ <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 &alloc) const
+ {
+ //Foo *copy = new Foo();
+ Foo *copy = cloneable::create<Foo>(alloc);
+ // write values to copy from this
+ return copy;
+ }
+};
+
+ </programlisting>
</section>
</section>
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