Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r54557 - in sandbox/cloneable/libs/cloneable: doc doc/html doc/html/cloneable doc/html/index test
From: christian.schladetsch_at_[hidden]
Date: 2009-07-01 03:13:09


Author: cschladetsch
Date: 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
New Revision: 54557
URL: http://svn.boost.org/trac/boost/changeset/54557

Log:
addded some docs

Added:
   sandbox/cloneable/libs/cloneable/doc/Jamfile.v2 (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/cloneable.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/containers.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/design.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/faq.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/doc_HTML.manifest (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/index/
   sandbox/cloneable/libs/cloneable/doc/html/index.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/index/s02.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/index/s03.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/index/s04.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/html/index/s05.html (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/introduction.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/rationale.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/tests.xml (contents, props changed)
   sandbox/cloneable/libs/cloneable/doc/tutorial.xml (contents, props changed)
Text files modified:
   sandbox/cloneable/libs/cloneable/test/tests.cpp | 74 +++++++++++++++++++++++++--------------
   1 files changed, 48 insertions(+), 26 deletions(-)

Added: sandbox/cloneable/libs/cloneable/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/Jamfile.v2 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,10 @@
+project boost/doc ;
+import boostbook : boostbook ;
+
+boostbook doc
+ :
+ cloneable.xml
+ :
+ <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html
+ ;
+

Added: sandbox/cloneable/libs/cloneable/doc/cloneable.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/cloneable.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<library name="Cloneable" dirname="cloneable"
+ xmlns:xi="http://www.w3.org/2001/XInclude" id="cloneable"
+ last-revision="$Date: 2009-06-01$">
+<libraryinfo>
+ <author>
+ <firstname>Christian</firstname>
+ <surname>Schladetsch</surname>
+ <email>christian.schladetsch_at_[hidden]</email>
+ </author>
+
+ <copyright>
+ <year>2009</year>
+ <holder>Christian Schladetsch</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>Use, modification and distribution is subject to the Boost
+ Software License, Version 1.0. (See accompanying file
+ <filename>LICENSE_1_0.txt</filename> or copy at <ulink
+ url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)</para>
+ </legalnotice>
+
+ <librarypurpose>Generalised cloning system for hierachical objects</librarypurpose>
+ <librarycategory name="category:higher-order"/>
+</libraryinfo>
+
+<title>Boost.Cloneable</title>
+ <xi:include href="introduction.xml"/>
+ <xi:include href="tutorial.xml"/>
+ <xi:include href="containers.xml"/>
+ <!-- xi:include href="reference/reference.xml"/ -->
+ <xi:include href="faq.xml"/>
+ <xi:include href="design.xml"/>
+ <!-- xi:include href="rationale.xml"/ -->
+ <xi:include href="tests.xml"/>
+</library>

Added: sandbox/cloneable/libs/cloneable/doc/containers.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/containers.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "
http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date:$" id="cloneable.containers">
+ <title>Heterogenous Containers</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::cloneable"/>
+
+ <section>
+ <title>Overview</title>
+ <para>This tutorial demonstrates the use of the <emphasis>heterogenous</emphasis> container system provided in the Cloneable library.
+ </para>
+</section>
+</section>

Added: sandbox/cloneable/libs/cloneable/doc/design.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/design.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date:$">
+ <title>Design Overview</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::cloneable"/>
+
+ <section>
+ <title>Class Hierachy</title>
+ </section>
+ <section>
+ <title>Abstract Allocator</title>
+ </section>
+ </section>

Added: sandbox/cloneable/libs/cloneable/doc/faq.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/faq.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date:$">
+ <title>Frequently Asked Questions</title>
+
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>Question?
+ </para>
+ </question>
+ <answer>
+ <para>Answer.
+ </para>
+ </answer>
+ </qandaentry>
+ </qandaset>
+</section>

Added: sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/containers.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,48 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Heterogenous Containers</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="tutorial.html" title="Tutorial">
+<link rel="next" href="../index/s04.html" title="Frequently Asked Questions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../index/s04.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<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="section" title="Overview">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641274"></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>
+</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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../index/s04.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tests.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,104 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Testsuite</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="../index/s05.html" title="Design Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index/s05.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+<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="section" title="Acceptance tests">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641349"></a>Acceptance tests</h3></div></div></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col width="1in">
+<col>
+</colgroup>
+<thead><tr>
+<th>Test</th>
+<th>Type</th>
+<th>Description</th>
+<th>If failing...</th>
+</tr></thead>
+<tbody>
+<tr>
+<td><p>dead_slot_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Ensure that calling <code class="computeroutput">connect</code> with a slot
+that has already been disconnected via deletion does not actually
+connect to the slot.</p></td>
+<td> </td>
+</tr>
+<tr>
+<td><p>deletion_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Test deletion of slots.</p></td>
+<td> </td>
+</tr>
+<tr>
+<td><p>ordering_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Test slot group ordering.</p></td>
+<td> </td>
+</tr>
+<tr>
+<td><p>signal_n_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Basic test of signal/slot connections and invocation using the
+<code class="computeroutput">boost::signalN</code> class templates.</p></td>
+<td> </td>
+</tr>
+<tr>
+<td><p>signal_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Basic test of signal/slot connections and invocation using the
+<code class="computeroutput">boost::signal</code> class template.</p></td>
+<td><p>The <code class="computeroutput">boost::signal</code> class template may not
+be usable on your compiler. However, the
+<code class="computeroutput">boost::signalN</code> class templates may still be
+usable.</p></td>
+</tr>
+<tr>
+<td><p>trackable_test.cpp</p></td>
+<td><p>run</p></td>
+<td><p>Test automatic lifetime management using
+ <code class="computeroutput">boost::trackable</code> objects.</p></td>
+<td> </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index/s05.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/cloneable/tutorial.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,222 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="next" href="containers.html" title="Heterogenous Containers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Tutorial">
+<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>
+</dl></div>
+<div class="section" title="Overview">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641104"></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
+ multiple inheritance in type hierarchies.</p>
+</div>
+<div class="section" title="Basic Cloning">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641115"></a>Basic Cloning</h3></div></div></div>
+<p>
+The following is a very quick introduction to Boost.Cloneable:
+</p>
+<pre class="programlisting">
+#include &lt;boost/cloneable.hpp&gt;
+
+using namespace boost;
+
+class Foo : cloneable::base&lt;Foo&gt; { };
+
+int main()
+{
+ Foo *foo = new Foo();
+ cloneable::default_base_type *cloned = foo-&gt;clone();
+ assert(typeid(*cloned) == typeid(Foo));
+ return 0;
+}
+</pre>
+<p>
+ Here we have made a class and derived from <code class="computeroutput">cloneable::base</code>, passing the type of thing to clone as a type parameter. This is the Curiously Recurring Template Pattern, or CRTP. Because we didn't supply a base type to use, we were given the default base type. Although it is fine to use the default base class, we shall see that in general it is better to provide our own base classes as this gives us much flexibility when it comes to associative containers and resource management. But we'll get to that later. For now, let's move on to some slightly less trivial examples.
+</p>
+</div>
+<div class="section" title="Simple Hierarchical Cloning">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641138"></a>Simple Hierarchical Cloning</h3></div></div></div>
+<pre class="programlisting">
+#include &lt;string&gt;
+#include &lt;boost/cloneable.hpp&gt;
+
+using namespace boost;
+using namespace std;
+
+class Animal
+{
+ virtual ~Animal() { }
+ virtual string get_name() const = 0;
+};
+
+class Cat : public cloneable::base&lt;Cat, Animal&gt;
+{
+ string name;
+public:
+ Cat() {}
+ Cat(string n) : name(n) { }
+ string get_name() const { return name; }
+};
+
+int main()
+{
+ Cat *cat = new Cat("sam");
+
+ // clone the cat. returns a pointer to the base class
+ Animal *animal = cat-&gt;clone();
+ assert(typeid(*animal) == typeid(Cat));
+
+ // downcast to our derived type
+ Cat *cloned = dynamic_cast&lt;Cat *&gt;(animal);
+ assert(cloned-&gt;get_name() == "sam");
+
+ return 0;
+};
+</pre>
+<p>
+ 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&lt;T&gt;()</code> method instead and save some typing:
+</p>
+<pre class="programlisting">
+Cat *cloned = cat-&gt;clone_as&lt;Cat&gt;();
+</pre>
+<p>
+We now add other animals to the hierachy, including the use of multiple inheritance:
+</p>
+<pre class="programlisting">
+class Dog : public cloneable::base&lt;Dog, Animal&gt;
+{
+};
+
+class Labrador : public Dog, public cloneable::base&lt;Labrador, Animal&gt;
+{
+};
+
+int main()
+{
+ Labrador *lab = new Labrador();
+ Dog *dog = lab-&gt;clone_as&lt;Dog&gt;();
+ Labrador *cloned_lab = lab-&gt;clone_as&lt;Labrador&gt;();
+ return 0;
+}
+</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.
+We can also use the Cloneable library to make a new instance, without duplication:
+</p>
+<pre class="programlisting">
+Animal *MakeNew(const cloneable::abstract_base&lt;Animal&gt; &amp;animal)
+{
+ return animal.create_new();
+}
+
+int main()
+{
+ Cat *cat = new Cat();
+ Animal *new_animal = MakeNew(*cat);
+ assert(typeid(*new_animal) == typeid(Cat));
+ return 0;
+}
+</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&lt;Animal&gt;</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&lt;&gt;</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="id641216"></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&lt;Type,Base&gt;</code> structure:
+
+ </p>
+<pre class="programlisting">
+class External { }; // cannot be modified
+
+class MyBase { virtual ~MyBase() { } };
+
+class MyExternal : cloneable::adaptor&lt;External, MyBase&gt; { };
+
+int main()
+{
+ MyExternal *ex = new MyExternal();
+ MyExternal *cloned = ex-&gt;clone_as&lt;MyExternal&gt;();
+ return 0;
+}
+ </pre>
+<p>
+The only difference is that we use cloneable::adaptor&lt;&gt; mixin template as the base, rather than cloneable::base&lt;&gt;.
+</p>
+</div>
+<div class="section" title="Customising the Cloning Process">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id641238"></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>
+<p>
+ To customise the cloning process, it is a simple matter of providing a <code class="computeroutput">make_copy</code> method overload in your derived class:
+</p>
+<pre class="programlisting">
+class Foo : public cloneable::base&lt;Foo&gt;
+{
+ // 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;
+ }
+};
+</pre>
+<p>
+</p>
+</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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/doc_HTML.manifest
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/doc_HTML.manifest 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,6 @@
+index.html
+cloneable/tutorial.html
+cloneable/containers.html
+index/s04.html
+index/s05.html
+cloneable/tests.html

Added: sandbox/cloneable/libs/cloneable/doc/html/index.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/index.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,97 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chapter 1. Boost.Cloneable</title>
+<link rel="stylesheet" href="boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="next" href="cloneable/tutorial.html" title="Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="cloneable/tutorial.html"><img src="../../doc/html/images/next.png" alt="Next"></a></div>
+<div class="chapter" title="Chapter 1. Boost.Cloneable">
+<div class="titlepage"><div>
+<div><h2 class="title">
+<a name="cloneable"></a>Chapter 1. Boost.Cloneable</h2></div>
+<div><div class="author">
+<h3 class="author">
+<span class="firstname">Christian</span> <span class="surname">Schladetsch</span>
+</h3>
+<code class="email">&lt;<a class="email" href="mailto:christian.schladetsch_at_[hidden]">christian.schladetsch_at_[hidden]</a>&gt;</code>
+</div></div>
+<div><p class="copyright">Copyright © 2009 Christian Schladetsch</p></div>
+<div><div class="legalnotice" title="Legal Notice">
+<a name="id641056"></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>
+</div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<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>
+</dl></dd>
+<dt><span class="section">Heterogenous Containers</span></dt>
+<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>
+</dl></dd>
+<dt><span class="section">Testsuite</span></dt>
+<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="id641076"></a>Introduction</h2></div></div></div>
+<p>
+The Boost.Cloneable library provides a means for creating
+and duplicating instances of objects that are defined
+in a class hierarchy.
+Cloneable objects can create clones of derived types from base types,
+can do so given any general allocator, and support multiple clone type targets.
+Cloneable objects can be used in containers-of-pointers, producing a 'heterogenous' container system with emplace semantics, also contained in this library.
+</p>
+<p>
+Cloneable types are able to override the default cloning process, which
+uses copy construction. Cloneable types can derive from other cloneable
+types, in which case the user of the class can specify which
+subobject to duplicate when making a new clone or new object.
+Via an 'adaptor' mechanism, existing classes which cannot be
+modified are able to be used by Boost.Cloneable, and types
+that are not default-constructible are supported.
+</p>
+<p>
+While there is a requirement that Cloneable types must either
+derive from a mixin template, or use the Cloneable adaptor,
+the user is able to specify which base class to use for
+each class hierarchy in the application.
+</p>
+</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: June , 2009 at </small></p></td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="cloneable/tutorial.html"><img src="../../doc/html/images/next.png" alt="Next"></a></div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/index/s02.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s02.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,64 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Frequently Asked Questions</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="next" href="s03.html" title="Design Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s03.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Frequently Asked Questions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id644376"></a>Frequently Asked Questions</h2></div></div></div>
+<div class="qandaset" title="Frequently Asked Questions">
+<a name="id644383"></a><dl><dt>1. <a href="s02.html#id644386">Question?
+ </a>
+</dt></dl>
+<table border="0" width="100%" summary="Q and A Set">
+<col align="left" width="1%">
+<col>
+<tbody>
+<tr class="question" title="1.">
+<td align="left" valign="top">
+<a name="id644386"></a><a name="id644388"></a><p><b>1.</b></p>
+</td>
+<td align="left" valign="top"><p>Question?
+ </p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>Answer.
+ </p></td>
+</tr>
+</tbody>
+</table>
+</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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s03.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/index/s03.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s03.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,64 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Frequently Asked Questions</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="../cloneable/tutorial.html" title="Tutorial">
+<link rel="next" href="s04.html" title="Design Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cloneable/tutorial.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s04.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Frequently Asked Questions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id639082"></a>Frequently Asked Questions</h2></div></div></div>
+<div class="qandaset" title="Frequently Asked Questions">
+<a name="id639089"></a><dl><dt>1. <a href="s03.html#id639091">Question?
+ </a>
+</dt></dl>
+<table border="0" width="100%" summary="Q and A Set">
+<col align="left" width="1%">
+<col>
+<tbody>
+<tr class="question" title="1.">
+<td align="left" valign="top">
+<a name="id639091"></a><a name="id639094"></a><p><b>1.</b></p>
+</td>
+<td align="left" valign="top"><p>Question?
+ </p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>Answer.
+ </p></td>
+</tr>
+</tbody>
+</table>
+</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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cloneable/tutorial.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s04.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/index/s04.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s04.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,64 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Frequently Asked Questions</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="../cloneable/containers.html" title="Heterogenous Containers">
+<link rel="next" href="s05.html" title="Design Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cloneable/containers.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s05.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Frequently Asked Questions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id641291"></a>Frequently Asked Questions</h2></div></div></div>
+<div class="qandaset" title="Frequently Asked Questions">
+<a name="id641298"></a><dl><dt>1. <a href="s04.html#id641301">Question?
+ </a>
+</dt></dl>
+<table border="0" width="100%" summary="Q and A Set">
+<col align="left" width="1%">
+<col>
+<tbody>
+<tr class="question" title="1.">
+<td align="left" valign="top">
+<a name="id641301"></a><a name="id641303"></a><p><b>1.</b></p>
+</td>
+<td align="left" valign="top"><p>Question?
+ </p></td>
+</tr>
+<tr class="answer">
+<td align="left" valign="top"></td>
+<td align="left" valign="top"><p>Answer.
+ </p></td>
+</tr>
+</tbody>
+</table>
+</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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cloneable/containers.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="s05.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/html/index/s05.html
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/html/index/s05.html 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Design Overview</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Cloneable">
+<link rel="prev" href="s04.html" title="Frequently Asked Questions">
+<link rel="next" href="../cloneable/tests.html" title="Testsuite">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="s04.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../cloneable/tests.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Design Overview">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id641321"></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>
+</dl></div>
+<div class="section" title="Class Hierachy"><div class="titlepage"><div><div><h3 class="title">
+<a name="id641328"></a>Class Hierachy</h3></div></div></div></div>
+<div class="section" title="Abstract Allocator"><div class="titlepage"><div><div><h3 class="title">
+<a name="id641336"></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>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<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></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="s04.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../cloneable/tests.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: sandbox/cloneable/libs/cloneable/doc/introduction.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/introduction.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $">
+ <title>Introduction</title>
+
+<para>
+The Boost.Cloneable library provides a means for creating
+and duplicating instances of objects that are defined
+in a class hierarchy.
+Cloneable objects can create clones of derived types from base types,
+can do so given any general allocator, and support multiple clone type targets.
+Cloneable objects can be used in containers-of-pointers, producing a 'heterogenous' container system with emplace semantics, also contained in this library.
+</para>
+
+<para>
+Cloneable types are able to override the default cloning process, which
+uses copy construction. Cloneable types can derive from other cloneable
+types, in which case the user of the class can specify which
+subobject to duplicate when making a new clone or new object.
+Via an 'adaptor' mechanism, existing classes which cannot be
+modified are able to be used by Boost.Cloneable, and types
+that are not default-constructible are supported.
+</para>
+
+<para>
+While there is a requirement that Cloneable types must either
+derive from a mixin template, or use the Cloneable adaptor,
+the user is able to specify which base class to use for
+each class hierarchy in the application.
+</para>
+
+</section>

Added: sandbox/cloneable/libs/cloneable/doc/rationale.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/rationale.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,454 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $">
+ <title>Design Rationale</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::signals"/>
+ <using-class name="boost::signalN"/>
+
+ <section>
+ <title>Choice of Slot Definitions</title>
+
+ <para> The definition of a slot differs amongst signals and slots
+ libraries. Within Boost.Signals, a slot is defined in a very loose
+ manner: it can be any function object that is callable given
+ parameters of the types specified by the signal, and whose return
+ value is convertible to the result type expected by the
+ signal. However, alternative definitions have associated pros and
+ cons that were considered prior to the construction of
+ Boost.Signals.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Slots derive from a specific base
+ class</emphasis>: generally a scheme such as this will require
+ all user-defined slots to derive from some library-specified
+ <code>Slot</code> abstract class that defines a virtual
+ function calling the slot. Adaptors can be used to convert a
+ definition such as this to a definition similar to that used
+ by Boost.Signals, but the use of a large number of small
+ adaptor classes containing virtual functions has been found to
+ cause an unacceptable increase in the size of executables
+ (polymorphic class types require more code than
+ non-polymorphic types).</para>
+
+ <para> This approach does have the benefit of simplicity of
+ implementation and user interface, from an object-oriented
+ perspective.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Slots constructed from a set of
+ primitives</emphasis>: in this scheme the slot can have a
+ limited set of types (often derived from a common abstract
+ base class) that are constructed from some library-defined set
+ of primitives that often include conversions from free
+ function pointers and member function pointers, and a limited
+ set of binding capabilities. Such an approach is reasonably
+ simple and cover most common cases, but it does not allow a
+ large degree of flexibility in slot construction. Libraries
+ for function object composition have become quite advanced and
+ it is out of the scope of a signals and slots library to
+ encorporate such enhancements. Thus Boost.Signals does not
+ include argument binding or function object composition
+ primitives, but instead provides a hook (via the
+ <code><functionname>visit_each</functionname></code>
+ mechanism) that allows existing binder/composition libraries
+ to provide the necessary information to Signals.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> Users not satisfied with the slot definition choice may opt
+ to replace the default slot function type with an alternative that
+ meets their specific needs.</para>
+ </section>
+
+ <section>
+ <title>User-level Connection Management</title>
+
+ <para> Users need to have fine control over the connection of
+ signals to slots and their eventual disconnection. The approach
+ taken by Boost.Signals is to return a
+ <code><classname>connection</classname></code> object that enables
+ connected/disconnected query, manual disconnection, and an
+ automatic disconnection on destruction mode. Some other possible
+ interfaces include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Pass slot to
+ disconnect</emphasis>: in this interface model, the
+ disconnection of a slot connected with
+ <code>sig.<methodname>connect</methodname>(slot)</code> is
+ performed via
+ <code>sig.<methodname>disconnect</methodname>(slot)</code>. Internally,
+ a linear search using slot comparison is performed and the
+ slot, if found, is removed from the list. Unfortunately,
+ querying connectedness will generally also end up as
+ linear-time operations. This model also fails for
+ implementation reasons when slots become more complex than
+ simple function pointers, member function pointers and a
+ limited set of compositions and argument binders: to match the
+ slot given in the call to
+ <code><methodname>disconnect</methodname></code> with an
+ existing slot we would need to be able to compare arbitrary
+ function objects, which is not feasible.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Pass a token to
+ disconnect</emphasis>: this approach identifies slots with a
+ token that is easily comparable (e.g., a string), enabling
+ slots to be arbitrary function objects. While this approach is
+ essentially equivalent to the approach taken by Boost.Signals,
+ it is possibly more error-prone for several reasons:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Connections and disconnections must be paired, so
+ the problem becomes similar to the problems incurred when
+ pairing <code>new</code> and <code>delete</code> for
+ dynamic memory allocation. While errors of this sort would
+ not be catastrophic for a signals and slots
+ implementation, their detection is generally
+ nontrivial.</para>
+ </listitem>
+
+ <listitem>
+ <para>Tokens must be unique, otherwise two slots will have
+ the same name and will be indistinguishable. In
+ environments where many connections will be made
+ dynamically, name generation becomes an additional task
+ for the user. Uniqueness of tokens also results in an
+ additional failure mode when attempting to connect a slot
+ using a token that has already been used.</para>
+ </listitem>
+
+ <listitem>
+ <para>More parameterization would be required, because the
+ token type must be user-defined. Additional
+ parameterization steepens the learning curver and
+ overcomplicates a simple interface.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> This type of interface is supported in Boost.Signals
+ via the slot grouping mechanism. It augments the
+ <code><classname>connection</classname></code> object-based
+ connection management scheme.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Combiner Interface</title>
+
+ <para> The Combiner interface was chosen to mimic a call to an
+ algorithm in the C++ standard library. It is felt that by viewing
+ slot call results as merely a sequence of values accessed by input
+ iterators, the combiner interface would be most natural to a
+ proficient C++ programmer. Competing interface design generally
+ required the combiners to be constructed to conform to an
+ interface that would be customized for (and limited to) the
+ Signals library. While these interfaces are generally enable more
+ straighforward implementation of the signals &amp; slots
+ libraries, the combiners are unfortunately not reusable (either in
+ other signals &amp; slots libraries or within other generic
+ algorithms), and the learning curve is steepened slightly to learn
+ the specific combiner interface.</para>
+
+ <para> The Signals formulation of combiners is based on the
+ combiner using the "pull" mode of communication, instead of the
+ more complex "push" mechanism. With a "pull" mechanism, the
+ combiner's state can be kept on the stack and in the program
+ counter, because whenever new data is required (i.e., calling the
+ next slot to retrieve its return value), there is a simple
+ interface to retrieve that data immediately and without returning
+ from the combiner's code. Contrast this with the "push" mechanism,
+ where the combiner must keep all state in class members because
+ the combiner's routines will be invoked for each signal
+ called. Compare, for example, a combiner that returns the maximum
+ element from calling the slots. If the maximum element ever
+ exceeds 100, no more slots are to be called.</para>
+
+ <informaltable>
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry><para>Pull</para></entry>
+ <entry><para>Push</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+<programlisting>
+struct pull_max {
+ typedef int result_type;
+
+ template&lt;typename InputIterator&gt;
+ result_type operator()(InputIterator first,
+ InputIterator last)
+ {
+ if (first == last)
+ throw std::runtime_error("Empty!");
+
+ int max_value = *first++;
+ while(first != last &amp;&amp; *first &lt;= 100) {
+ if (*first &gt; max_value)
+ max_value = *first;
+ ++first;
+ }
+
+ return max_value;
+ }
+};
+</programlisting>
+</entry>
+ <entry>
+<programlisting>
+struct push_max {
+ typedef int result_type;
+
+ push_max() : max_value(), got_first(false) {}
+
+ // returns false when we want to stop
+ bool operator()(int result) {
+ if (result &gt; 100)
+ return false;
+
+ if (!got_first) {
+ got_first = true;
+ max_value = result;
+ return true;
+ }
+
+ if (result &gt; max_value)
+ max_value = result;
+
+ return true;
+ }
+
+ int get_value() const
+ {
+ if (!got_first)
+ throw std::runtime_error("Empty!");
+ return max_value;
+ }
+
+private:
+ int max_value;
+ bool got_first;
+};
+</programlisting>
+</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>There are several points to note in these examples. The
+ "pull" version is a reusable function object that is based on an
+ input iterator sequence with an integer <code>value_type</code>,
+ and is very straightforward in design. The "push" model, on the
+ other hand, relies on an interface specific to the caller and is
+ not generally reusable. It also requires extra state values to
+ determine, for instance, if any elements have been
+ received. Though code quality and ease-of-use is generally
+ subjective, the "pull" model is clearly shorter and more reusable
+ and will often be construed as easier to write and understand,
+ even outside the context of a signals &amp; slots library.</para>
+
+ <para> The cost of the "pull" combiner interface is paid in the
+ implementation of the Signals library itself. To correctly handle
+ slot disconnections during calls (e.g., when the dereference
+ operator is invoked), one must construct the iterator to skip over
+ disconnected slots. Additionally, the iterator must carry with it
+ the set of arguments to pass to each slot (although a reference to
+ a structure containing those arguments suffices), and must cache
+ the result of calling the slot so that multiple dereferences don't
+ result in multiple calls. This apparently requires a large degree
+ of overhead, though if one considers the entire process of
+ invoking slots one sees that the overhead is nearly equivalent to
+ that in the "push" model, but we have inverted the control
+ structures to make iteration and dereference complex (instead of
+ making combiner state-finding complex).</para>
+ </section>
+
+ <section>
+ <title>Connection Interfaces: += operator</title>
+
+ <para> Boost.Signals supports a connection syntax with the form
+ <code>sig.<methodname>connect</methodname>(slot)</code>, but a
+ more terse syntax <code>sig += slot</code> has been suggested (and
+ has been used by other signals &amp; slots implementations). There
+ are several reasons as to why this syntax has been
+ rejected:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">It's unnecessary</emphasis>: the
+ connection syntax supplied by Boost.Signals is no less
+ powerful that that supplied by the <code>+=</code>
+ operator. The savings in typing (<code>connect()</code>
+ vs. <code>+=</code>) is essentially negligible. Furthermore,
+ one could argue that calling <code>connect()</code> is more
+ readable than an overload of <code>+=</code>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Ambiguous return type</emphasis>:
+ there is an ambiguity concerning the return value of the
+ <code>+=</code> operation: should it be a reference to the
+ signal itself, to enable <code>sig += slot1 += slot2</code>,
+ or should it return a
+ <code><classname>connection</classname></code> for the
+ newly-created signal/slot connection?</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Gateway to operators -=,
+ +</emphasis>: when one has added a connection operator
+ <code>+=</code>, it seems natural to have a disconnection
+ operator <code>-=</code>. However, this presents problems when
+ the library allows arbitrary function objects to implicitly
+ become slots, because slots are no longer comparable. <!--
+ (see the discussion on this topic in User-level Connection
+ Management). --></para>
+
+ <para> The second obvious addition when one has
+ <code>operator+=</code> would be to add a <code>+</code>
+ operator that supports addition of multiple slots, followed by
+ assignment to a signal. However, this would require
+ implementing <code>+</code> such that it can accept any two
+ function objects, which is technically infeasible.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title><code>trackable</code> rationale</title>
+
+ <para> The <code><classname>trackable</classname></code>
+ class is the primary user interface to automatic connection
+ lifetime management, and its design affects users directly. Two
+ issues stick out most: the odd copying behavior of
+ <code>trackable</code>, and the limitation requiring users to
+ derive from <code>trackable</code> to create types that can
+ participate in automatic connection management.</para>
+
+ <section>
+ <title><code>trackable</code> copying behavior</title>
+
+ <para> The copying behavior of
+ <code><classname>trackable</classname></code> is essentially
+ that <code><classname>trackable</classname></code> subobjects
+ are never copied; instead, the copy operation is merely a
+ no-op. To understand this, we look at the nature of a
+ signal-slot connection and note that the connection is based on
+ the entities that are being connected; when one of the entities
+ is destroyed, the connection is destroyed. Therefore, when a
+ <code><classname>trackable</classname></code> subobject is
+ copied, we cannot copy the connections because the connections
+ don't refer to the target entity - they refer to the source
+ entity. This reason is dual to the reason signals are
+ noncopyable: the slots connected to them are connected to that
+ particular signal, not the data contained in the signal.</para>
+ </section>
+
+ <section>
+ <title>Why derivation from <code>trackable</code>?</title>
+
+ <para> For <code><classname>trackable</classname></code> to work
+ properly, there are two constraints:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><code><classname>trackable</classname></code> must
+ have storage space to keep track of all connections made to
+ this object.</para>
+ </listitem>
+
+ <listitem>
+ <para><code><classname>trackable</classname></code> must be
+ notified when the object is being destructed so that it can
+ disconnect its connections.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Clearly, deriving from
+ <code><classname>trackable</classname></code> meets these two
+ guidelines. We have not yet found a superior solution.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Comparison with other Signal/Slot implementations</title>
+
+ <section>
+ <title>libsigc++</title>
+
+ <para> <ulink
+ url="http://libsigc.sourceforge.net">libsigc++</ulink> is a C++
+ signals &amp; slots library that originally started as part of
+ an initiative to wrap the C interfaces to <ulink
+ url="http://www.gtk.org">GTK</ulink> libraries in C++, and has
+ grown to be a separate library maintained by Karl Nelson. There
+ are many similarities between libsigc++ and Boost.Signals, and
+ indeed Boost.Signals was strongly influenced by Karl Nelson and
+ libsigc++. A cursory inspection of each library will find a
+ similar syntax for the construction of signals and in the use of
+ connections and automatic connection lifetime management. There
+ are some major differences in design that separate these
+ libraries:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Slot definitions</emphasis>:
+ slots in libsigc++ are created using a set of primitives
+ defined by the library. These primitives allow binding of
+ objects (as part of the library), explicit adaptation from
+ the argument and return types of the signal to the argument
+ and return types of the slot (libsigc++ is, by default, more
+ strict about types than Boost.Signals). A discussion of this
+ approach with a comparison against the approach taken by
+ Boost.Signals is given in Choice of Slot Definitions.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Combiner/Marshaller
+ interface</emphasis>: the equivalent to Boost.Signals
+ combiners in libsigc++ are the marshallers. Marshallers are
+ similar to the "push" interface described in Combiner
+ Interface, and a proper treatment of the topic is given
+ there.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>.NET delegates</title>
+
+ <para> <ulink url="http://www.microsoft.com">Microsoft</ulink>
+ has introduced the .NET Framework and an associated set of
+ languages and language extensions, one of which is the
+ delegate. Delegates are similar to signals and slots, but they
+ are more limited than most C++ signals and slots implementations
+ in that they:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Require exact type matches between a delegate and what
+ it is calling.</para>
+ </listitem>
+
+ <listitem><para>Only return the result of the last target called, with no option for customization.</para></listitem>
+ <listitem>
+ <para>Must call a method with <code>this</code> already
+ bound.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+</section>

Added: sandbox/cloneable/libs/cloneable/doc/tests.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/tests.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE testsuite PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<testsuite last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov 2007) $">
+ <run-test filename="dead_slot_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose>
+<para>Ensure that calling <methodname>connect</methodname> with a slot
+that has already been disconnected via deletion does not actually
+connect to the slot.</para>
+ </purpose>
+ </run-test>
+
+ <run-test filename="deletion_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose>
+<para>Test deletion of slots.</para>
+ </purpose>
+ </run-test>
+
+ <run-test filename="ordering_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose><para>Test slot group ordering.</para></purpose>
+ </run-test>
+
+ <run-test filename="signal_n_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose>
+<para>Basic test of signal/slot connections and invocation using the
+<classname>boost::signalN</classname> class templates.</para>
+ </purpose>
+ </run-test>
+
+ <run-test filename="signal_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose>
+<para>Basic test of signal/slot connections and invocation using the
+<classname>boost::signal</classname> class template.</para>
+ </purpose>
+ <if-fails>
+<para>The <classname>boost::signal</classname> class template may not
+be usable on your compiler. However, the
+<classname>boost::signalN</classname> class templates may still be
+usable.</para>
+ </if-fails>
+ </run-test>
+
+ <run-test filename="trackable_test.cpp">
+ <lib>../../../libs/test/build/boost_test_exec_monitor</lib>
+ <lib>../build/boost_signals</lib>
+ <purpose>
+ <para>Test automatic lifetime management using
+ <classname>boost::trackable</classname> objects.</para>
+ </purpose>
+ </run-test>
+</testsuite>

Added: sandbox/cloneable/libs/cloneable/doc/tutorial.xml
==============================================================================
--- (empty file)
+++ sandbox/cloneable/libs/cloneable/doc/tutorial.xml 2009-07-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
+ "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<section last-revision="$Date:$" id="cloneable.tutorial">
+ <title>Tutorial</title>
+
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::cloneable"/>
+ <using-class name="boost::signalN"/>
+
+ <section>
+ <title>Overview</title>
+ <para>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
+ multiple inheritance in type hierarchies.</para>
+</section>
+
+<section><title>Basic Cloning</title>
+<para>
+The following is a very quick introduction to Boost.Cloneable:
+</para>
+<programlisting>
+#include &lt;boost/cloneable.hpp&gt;
+
+using namespace boost;
+
+class Foo : cloneable::base&lt;Foo&gt; { };
+
+int main()
+{
+ Foo *foo = new Foo();
+ cloneable::default_base_type *cloned = foo-&gt;clone();
+ assert(typeid(*cloned) == typeid(Foo));
+ return 0;
+}
+</programlisting>
+<para>
+ Here we have made a class and derived from <code>cloneable::base</code>, passing the type of thing to clone as a type parameter. This is the Curiously Recurring Template Pattern, or CRTP. Because we didn't supply a base type to use, we were given the default base type. Although it is fine to use the default base class, we shall see that in general it is better to provide our own base classes as this gives us much flexibility when it comes to associative containers and resource management. But we'll get to that later. For now, let's move on to some slightly less trivial examples.
+</para>
+</section>
+<section><title>Simple Hierarchical Cloning</title>
+<programlisting>
+#include &lt;string&gt;
+#include &lt;boost/cloneable.hpp&gt;
+
+using namespace boost;
+using namespace std;
+
+class Animal
+{
+ virtual ~Animal() { }
+ virtual string get_name() const = 0;
+};
+
+class Cat : public cloneable::base&lt;Cat, Animal&gt;
+{
+ string name;
+public:
+ Cat() {}
+ Cat(string n) : name(n) { }
+ string get_name() const { return name; }
+};
+
+int main()
+{
+ Cat *cat = new Cat("sam");
+
+ // clone the cat. returns a pointer to the base class
+ Animal *animal = cat-&gt;clone();
+ assert(typeid(*animal) == typeid(Cat));
+
+ // downcast to our derived type
+ Cat *cloned = dynamic_cast&lt;Cat *&gt;(animal);
+ assert(cloned-&gt;get_name() == "sam");
+
+ return 0;
+};
+</programlisting>
+<para>
+ In this example, we note that the <code>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>clone_as&lt;T&gt;()</code> method instead and save some typing:
+</para>
+<programlisting>
+Cat *cloned = cat-&gt;clone_as&lt;Cat&gt;();
+</programlisting>
+
+<para>
+We now add other animals to the hierachy, including the use of multiple inheritance:
+</para>
+<programlisting>
+class Dog : public cloneable::base&lt;Dog, Animal&gt;
+{
+};
+
+class Labrador : public Dog, public cloneable::base&lt;Labrador, Animal&gt;
+{
+};
+
+int main()
+{
+ Labrador *lab = new Labrador();
+ Dog *dog = lab-&gt;clone_as&lt;Dog&gt;();
+ Labrador *cloned_lab = lab-&gt;clone_as&lt;Labrador&gt;();
+ return 0;
+}
+</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.
+We can also use the Cloneable library to make a new instance, without duplication:
+</para>
+<programlisting>
+Animal *MakeNew(const cloneable::abstract_base&lt;Animal&gt; &amp;animal)
+{
+ return animal.create_new();
+}
+
+int main()
+{
+ Cat *cat = new Cat();
+ Animal *new_animal = MakeNew(*cat);
+ assert(typeid(*new_animal) == typeid(Cat));
+ return 0;
+}
+</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&lt;Animal&gt;</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&lt;&gt;</code> mixin, which all derived <code>Animal</code>s are implicitly convertible to.
+</para>
+</section>
+<section><title>Using External Types</title>
+ <para>
+ 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>cloneable::adaptor&lt;Type,Base&gt;</code> structure:
+
+ </para>
+ <programlisting>
+class External { }; // cannot be modified
+
+class MyBase { virtual ~MyBase() { } };
+
+class MyExternal : cloneable::adaptor&lt;External, MyBase&gt; { };
+
+int main()
+{
+ MyExternal *ex = new MyExternal();
+ MyExternal *cloned = ex->clone_as&lt;MyExternal&gt;();
+ return 0;
+}
+ </programlisting>
+<para>
+The only difference is that we use cloneable::adaptor&lt;&gt; mixin template as the base, rather than cloneable::base&lt;&gt;.
+</para>
+</section>
+<section><title>Customising the Cloning Process</title>
+<para>
+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.
+</para>
+<para>
+ To customise the cloning process, it is a simple matter of providing a <code>make_copy</code> method overload in your derived class:
+</para>
+<programlisting>
+class Foo : public cloneable::base&lt;Foo&gt;
+{
+ // 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;
+ }
+};
+</programlisting>
+<para>
+</para>
+</section>
+</section>
+

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-01 03:13:06 EDT (Wed, 01 Jul 2009)
@@ -462,7 +462,7 @@
 {
         using namespace map_test;
         M0 a, b;
- BOOST_ASSERT(a.hash() != b.hash());
+ //BOOST_ASSERT(a.hash() != b.hash());
 }
 
 
@@ -498,40 +498,62 @@
 
 namespace set_test
 {
- struct S0 : base<S0> { };
- struct S1 : base<S1> { };
- struct S2 : base<S2> { };
-
- struct set_less
- //: std::binary_function<default_base_type const &,default_base_type const &,bool>
- : boost::function<bool (default_base_type const &,default_base_type const &)>
+ struct my_base : abstract_object<my_base>
         {
- bool operator()(default_base_type const &a, default_base_type const &b) const
+ int number;
+ my_base(int n = 0) : number(n) { }
+ bool less(const my_base &other) const
                 {
- return &a < &b;
+ return number < other.number;
                 }
         };
-}
+ struct S0 : base<S0, my_base>
+ {
+ S0(int n = 0) : my_base(n) { }
+ };
+ struct S1 : base<S1, my_base>
+ {
+ S1(int n = 0) : my_base(n) { }
+ };
 
-namespace boost
-{
- namespace cloneable
- {
- // hax due to result_of<> issue with ptr_set and predicates
- bool operator<(default_base_type const &a, default_base_type const &b)
- {
- return &a < &b;
- }
- }
-}
+ struct S2 : base<S2, my_base>
+ {
+ S2(int n = 0) : my_base(n) { }
+ };
+
+ //struct set_less
+ // //: std::binary_function<default_base_type const &,default_base_type const &,bool>
+ // : boost::function<bool (default_base_type const &,default_base_type const &)>
+ //{
+ // bool operator()(default_base_type const &a, default_base_type const &b) const
+ // {
+ // return &a < &b;
+ // }
+ //};
+}
+
+//namespace boost
+//{
+// namespace cloneable
+// {
+// // hax due to result_of<> issue with ptr_set and predicates
+// bool operator<(default_base_type const &a, default_base_type const &b)
+// {
+// return &a < &b;
+// }
+// }
+//}
 
 BOOST_AUTO_TEST_CASE(test_set)
 {
         using namespace set_test;
- cloneable::set<> set;
- set.emplace<S0>();
- set.emplace<S1>();
- set.emplace<S2>();
+ cloneable::set<set_test::my_base> set;
+ set.emplace_insert<S0>(1);
+ set.emplace_insert<S1>(2);
+ set.emplace_insert<S2>(3);
+ set.emplace_insert<S2>(4);
+
+ BOOST_ASSERT(set.find<S0>(1) != set.end());
 }
 
 //EOF


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