diff options
| author | nobody <nobody@localhost> | 2003-08-18 18:40:31 +0000 |
|---|---|---|
| committer | nobody <nobody@localhost> | 2003-08-18 18:40:31 +0000 |
| commit | f8d6db30ae4a57a7404900787db925ee21411aff (patch) | |
| tree | 4236fd455a4b53e027e30e7ff3622c44b538c4e9 | |
| parent | ce5e16b6ae28e66369cdcfc6c416db64fd0298ba (diff) | |
| parent | ba4e1cbe3c6a612e610f45446840f2cad6feabf2 (diff) | |
| download | boost-f8d6db30ae4a57a7404900787db925ee21411aff.tar.gz | |
This commit was manufactured by cvs2svn to create tag
'Version_1_30_2'.
[SVN r19685]
220 files changed, 17211 insertions, 0 deletions
diff --git a/.gitmodules b/.gitmodules index d72a772305..91ff204f96 100644 --- a/.gitmodules +++ b/.gitmodules @@ -2,3 +2,195 @@ path = libs/smart_ptr url = ../smart_ptr.git fetchRecurseSubmodules = on-demand +[submodule "build"] + path = tools/build + url = ../build.git + fetchRecurseSubmodules = on-demand +[submodule "tokenizer"] + path = libs/tokenizer + url = ../tokenizer.git + fetchRecurseSubmodules = on-demand +[submodule "utility"] + path = libs/utility + url = ../utility.git + fetchRecurseSubmodules = on-demand +[submodule "integer"] + path = libs/integer + url = ../integer.git + fetchRecurseSubmodules = on-demand +[submodule "python"] + path = libs/python + url = ../python.git + fetchRecurseSubmodules = on-demand +[submodule "compose"] + path = libs/compose + url = ../compose.git + fetchRecurseSubmodules = on-demand +[submodule "function"] + path = libs/function + url = ../function.git + fetchRecurseSubmodules = on-demand +[submodule "math"] + path = libs/math + url = ../math.git + fetchRecurseSubmodules = on-demand +[submodule "crc"] + path = libs/crc + url = ../crc.git + fetchRecurseSubmodules = on-demand +[submodule "rational"] + path = libs/rational + url = ../rational.git + fetchRecurseSubmodules = on-demand +[submodule "regex"] + path = libs/regex + url = ../regex.git + fetchRecurseSubmodules = on-demand +[submodule "iterator"] + path = libs/iterator + url = ../iterator.git + fetchRecurseSubmodules = on-demand +[submodule "array"] + path = libs/array + url = ../array.git + fetchRecurseSubmodules = on-demand +[submodule "random"] + path = libs/random + url = ../random.git + fetchRecurseSubmodules = on-demand +[submodule "dynamic_bitset"] + path = libs/dynamic_bitset + url = ../dynamic_bitset.git + fetchRecurseSubmodules = on-demand +[submodule "format"] + path = libs/format + url = ../format.git + fetchRecurseSubmodules = on-demand +[submodule "pool"] + path = libs/pool + url = ../pool.git + fetchRecurseSubmodules = on-demand +[submodule "bind"] + path = libs/bind + url = ../bind.git + fetchRecurseSubmodules = on-demand +[submodule "any"] + path = libs/any + url = ../any.git + fetchRecurseSubmodules = on-demand +[submodule "thread"] + path = libs/thread + url = ../thread.git + fetchRecurseSubmodules = on-demand +[submodule "timer"] + path = libs/timer + url = ../timer.git + fetchRecurseSubmodules = on-demand +[submodule "disjoint_sets"] + path = libs/disjoint_sets + url = ../disjoint_sets.git + fetchRecurseSubmodules = on-demand +[submodule "test"] + path = libs/test + url = ../test.git + fetchRecurseSubmodules = on-demand +[submodule "graph"] + path = libs/graph + url = ../graph.git + fetchRecurseSubmodules = on-demand +[submodule "detail"] + path = libs/detail + url = ../detail.git + fetchRecurseSubmodules = on-demand +[submodule "multi_array"] + path = libs/multi_array + url = ../multi_array.git + fetchRecurseSubmodules = on-demand +[submodule "mpl"] + path = libs/mpl + url = ../mpl.git + fetchRecurseSubmodules = on-demand +[submodule "exception"] + path = libs/exception + url = ../exception.git + fetchRecurseSubmodules = on-demand +[submodule "spirit"] + path = libs/spirit + url = ../spirit.git + fetchRecurseSubmodules = on-demand +[submodule "optional"] + path = libs/optional + url = ../optional.git + fetchRecurseSubmodules = on-demand +[submodule "property_map"] + path = libs/property_map + url = ../property_map.git + fetchRecurseSubmodules = on-demand +[submodule "interval"] + path = libs/numeric/interval + url = ../interval.git + fetchRecurseSubmodules = on-demand +[submodule "ublas"] + path = libs/numeric/ublas + url = ../ublas.git + fetchRecurseSubmodules = on-demand +[submodule "config"] + path = libs/config + url = ../config.git + fetchRecurseSubmodules = on-demand +[submodule "type_traits"] + path = libs/type_traits + url = ../type_traits.git + fetchRecurseSubmodules = on-demand +[submodule "lambda"] + path = libs/lambda + url = ../lambda.git + fetchRecurseSubmodules = on-demand +[submodule "conversion"] + path = libs/conversion + url = ../conversion.git + fetchRecurseSubmodules = on-demand +[submodule "concept_check"] + path = libs/concept_check + url = ../concept_check.git + fetchRecurseSubmodules = on-demand +[submodule "io"] + path = libs/io + url = ../io.git + fetchRecurseSubmodules = on-demand +[submodule "signals"] + path = libs/signals + url = ../signals.git + fetchRecurseSubmodules = on-demand +[submodule "functional"] + path = libs/functional + url = ../functional.git + fetchRecurseSubmodules = on-demand +[submodule "static_assert"] + path = libs/static_assert + url = ../static_assert.git + fetchRecurseSubmodules = on-demand +[submodule "filesystem"] + path = libs/filesystem + url = ../filesystem.git + fetchRecurseSubmodules = on-demand +[submodule "tuple"] + path = libs/tuple + url = ../tuple.git + fetchRecurseSubmodules = on-demand +[submodule "date_time"] + path = libs/date_time + url = ../date_time.git + fetchRecurseSubmodules = on-demand +[submodule "compatibility"] + path = libs/compatibility + url = ../compatibility.git + fetchRecurseSubmodules = on-demand +[submodule "inspect"] + path = tools/inspect + url = ../inspect.git + fetchRecurseSubmodules = on-demand +[submodule "preprocessor"] + path = libs/preprocessor + url = ../preprocessor.git + fetchRecurseSubmodules = on-demand diff --git a/Jamfile b/Jamfile new file mode 100644 index 0000000000..c24e7e5c88 --- /dev/null +++ b/Jamfile @@ -0,0 +1,10 @@ +project-root ; + +# please order by name to ease maintenance +subinclude libs/date_time/build ; +subinclude libs/filesystem/build ; +subinclude libs/python/build ; +subinclude libs/regex/build ; +subinclude libs/signals/build ; +subinclude libs/test/build ; +subinclude libs/thread/build ; diff --git a/Jamfile.v2 b/Jamfile.v2 new file mode 100644 index 0000000000..b985804afc --- /dev/null +++ b/Jamfile.v2 @@ -0,0 +1,26 @@ +# +# This is Boost Jamfile for Boost.Build V2. +# Currently, known to work on Linux with gcc +# +# To build Boost with it, run +# +# bjam --v2 link=static +# +# from the top-level directory + + +project boost + : requirements <include>. + ; + +build-project libs/test/build ; +build-project libs/date_time/build ; +build-project libs/regex/build ; +build-project libs/signals/build ; +build-project libs/graph/build ; + +# Comment this out if you don't have Python2.2 installed +build-project libs/python/build ; +build-project libs/thread/build ; +build-project libs/filesystem/build ; + diff --git a/Jamrules b/Jamrules new file mode 100644 index 0000000000..ec7481631a --- /dev/null +++ b/Jamrules @@ -0,0 +1,14 @@ +# Boost.Build top level Jamrules + +# See tools/build/index.html for documentation. + +# Set some important global variables if they haven't already been set by the +# user on the command-line or in the environment + +# Establish this as the root of the boost installation. Most targets will want +# $(BOOST_ROOT) in their #include path. $(gTOP) is the name of the variable +# containing the path from the invocation directory to the project root. +path-global BOOST_ROOT : $($(gTOP)) ; + +# The current version of Boost. +BOOST_VERSION ?= 1.30.2 ; diff --git a/README b/README new file mode 100644 index 0000000000..5f109fd009 --- /dev/null +++ b/README @@ -0,0 +1,11 @@ +For the most current version of Boost libraries and documentation, see: + + http://www.boost.org + +Boost documentation is in HTML format. + +The highest level directory (which contains this README file) should have a file index.htm +with links to all documentation. When viewing index.htm with a web browser, follow the +"Libraries" link on the navigation bar for information on building boost libraries for +your particular compiler and operating system. + diff --git a/boost-build.jam b/boost-build.jam new file mode 100644 index 0000000000..4749ebf13c --- /dev/null +++ b/boost-build.jam @@ -0,0 +1,18 @@ +BOOST_ROOT = $(.boost-build-file:D) ; +if --v2 in $(ARGV) +{ + if $(JAM_VERSION:J="") < 030103 + { + ECHO "error: Boost.Jam 3.1.3 or later required" ; + EXIT ; + } + else + { + JAMFILE = [Jj]amfile.v2 ; + boost-build tools/build/new ; + } +} +else +{ + boost-build tools/build ; +} diff --git a/boost.css b/boost.css new file mode 100644 index 0000000000..03510b223e --- /dev/null +++ b/boost.css @@ -0,0 +1,54 @@ +H1 +{ + FONT-SIZE: 200%; + COLOR: #00008B; +} +H2 +{ + FONT-SIZE: 150%; +} +H3 +{ + FONT-SIZE: 125%; +} +H4 +{ + FONT-SIZE: 108%; +} +BODY +{ + FONT-SIZE: 100%; + BACKGROUND-COLOR: #ffffff; +} +PRE +{ + MARGIN-LEFT: 2em; + FONT-FAMILY: Courier; +} +CODE +{ + FONT-FAMILY: Courier; + white-space: pre; +} +.index +{ + TEXT-ALIGN: left; +} +.page-index +{ + TEXT-ALIGN: left; +} +.definition +{ + TEXT-ALIGN: left; +} +.footnote +{ + FONT-SIZE: 66%; + VERTICAL-ALIGN: super; + TEXT-DECORATION: none; +} +.function-semantics +{ + CLEAR: left; +} diff --git a/c++boost.gif b/c++boost.gif Binary files differnew file mode 100644 index 0000000000..58be431a3f --- /dev/null +++ b/c++boost.gif diff --git a/doc/html/any.html b/doc/html/any.html new file mode 100644 index 0000000000..275f936d0f --- /dev/null +++ b/doc/html/any.html @@ -0,0 +1,40 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.Any</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="index.html" title="The Boost C++ Libraries"><link rel="previous" href="index.html" title="The Boost C++ Libraries"><link rel="next" href="ch01s02.html" title="Examples"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="any.html#id2878869" title="Introduction"><link rel="section" href="ch01s02.html" title="Examples"><link rel="section" href="any.reference.html" title="Reference"><link rel="section" href="ch01s04.html" title="Acknowledgements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="any"></a>Boost.Any</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Kevlin</span> <span class="surname">Henney</span></h3></div></div><div><p class="copyright">Copyright © 2001 Kevlin Henney</p></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="any.html#id2878869">Introduction</a></dt><dt><a href="ch01s02.html">Examples</a></dt><dt><a href="any.reference.html">Reference</a></dt><dd><dl><dt><a href="any.reference.html#any.ValueType">ValueType requirements</a></dt><dt><a href="any.reference.html#header.boost.any.hpp">Header <boost/any.hpp></a></dt></dl></dd><dt><a href="ch01s04.html">Acknowledgements</a></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2878869"></a>Introduction</h2></div></div><div></div></div><p>There are times when a generic (in the sense of + <span class="emphasis"><em>general</em></span> as opposed to + <span class="emphasis"><em>template-based programming</em></span>) type is needed: + variables that are truly variable, accommodating values of many + other more specific types rather than C++'s normal strict and + static types. We can distinguish three basic kinds of generic + type:</p><div class="itemizedlist"><ul type="disc"><li><p>Converting types that can hold one of a number of + possible value types, e.g. <tt class="computeroutput">int</tt> and + <tt class="computeroutput">string</tt>, and freely convert between them, for + instance interpreting <tt class="computeroutput">5</tt> as <tt class="computeroutput">"5"</tt> or + vice-versa. Such types are common in scripting and other + interpreted + languages. + <tt class="computeroutput">boost::lexical_cast</tt> + supports such conversion functionality.</p></li><li><p> + Discriminated types that contain values of different types but + do not attempt conversion between them, i.e. <tt class="computeroutput">5</tt> is + held strictly as an <tt class="computeroutput">int</tt> and is not implicitly + convertible either to <tt class="computeroutput">"5"</tt> or to + <tt class="computeroutput">5.0</tt>. Their indifference to interpretation but + awareness of type effectively makes them safe, generic + containers of single values, with no scope for surprises from + ambiguous conversions.</p></li><li><p> + Indiscriminate types that can refer to anything but are + oblivious to the actual underlying type, entrusting all forms + of access and interpretation to the programmer. This niche is + dominated by <tt class="computeroutput">void *</tt>, which offers plenty of scope + for surprising, undefined behavior.</p></li></ul></div><p>The <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">boost::any</a></tt> class + (based on the class of the same name described in <a href="http://www.two-sdg.demon.co.uk/curbralan/papers/ValuedConversions.pdf" target="_top">"Valued + Conversions"</a> by Kevlin Henney, <span class="emphasis"><em>C++ + Report</em></span> 12(7), July/August 2000) is a variant value type + based on the second category. It supports copying of any value + type and safe checked extraction of that value strictly against + its type. A similar design, offering more appropriate operators, + can be used for a generalized function adaptor, + <tt class="computeroutput">any_function</tt>, a generalized iterator adaptor, + <tt class="computeroutput">any_iterator</tt>, and other object types that need + uniform runtime treatment but support only compile-time template + parameter conformance.</p></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small></small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s02.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">The Boost C++ Libraries </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Examples</td></tr></table></div></body></html> diff --git a/doc/html/any.reference.html b/doc/html/any.reference.html new file mode 100644 index 0000000000..80bf9848e8 --- /dev/null +++ b/doc/html/any.reference.html @@ -0,0 +1,29 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Reference</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.html" title="Boost.Any"><link rel="previous" href="ch01s02.html" title="Examples"><link rel="next" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="any.reference.html#any.ValueType" title="ValueType requirements"><link rel="subsection" href="any.reference.html#header.boost.any.hpp" title="Header <boost/any.hpp>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="any.reference"></a>Reference</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="any.ValueType"></a><span class="emphasis"><em>ValueType</em></span> requirements</h3></div></div><div></div></div><p>Values are strongly informational objects for which + identity is not significant, i.e. the focus is principally on + their state content and any behavior organized around + that. Another distinguishing feature of values is their + granularity: normally fine-grained objects representing simple + concepts in the system such as quantities.</p><p>As the emphasis of a value lies in its state not its + identity, values can be copied and typically assigned one to + another, requiring the explicit or implicit definition of a + public copy constructor and public assignment operator. Values + typically live within other scopes, i.e. within objects or + blocks, rather than on the heap. Values are therefore normally + passed around and manipulated directly as variables or through + references, but not as pointers that emphasize identity and + indirection.</p><p>The specific requirements on value types to be used in an + <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">any</a></tt> + are:</p><div class="itemizedlist"><ul type="disc" compact><li>A <span class="emphasis"><em>ValueType</em></span> is + <span class="emphasis"><em>CopyConstructible</em></span> [20.1.3].</li><li>A <span class="emphasis"><em>ValueType</em></span> is + optionally <span class="emphasis"><em>Assignable</em></span> [23.1]. The strong + exception-safety guarantee is required for all forms of + assignment.</li><li>The destructor for a + <span class="emphasis"><em>ValueType</em></span> upholds the no-throw + exception-safety guarantee.</li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="header.boost.any.hpp"></a>Header <<a href="../../boost/any.hpp" target="_top">boost/any.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <a href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><span class="bold"><b>class</b></span> bad_any_cast;</a> + <a href="class.boost.any.html" title="Class any"><span class="bold"><b>class</b></span> any;</a> + <a href="id2827840.html" title="Function any_cast"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> ValueType any_cast(<span class="bold"><b>const</b></span> any &)</a>; + <a href="id2827840.html" title="Function any_cast"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> <span class="bold"><b>const</b></span> ValueType * any_cast(<span class="bold"><b>const</b></span> any *)</a>; + <a href="id2827840.html" title="Function any_cast"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> ValueType * any_cast(any *)</a>; +}</pre></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s02.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.bad_any_cast.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class bad_any_cast</td></tr></table></div></body></html> diff --git a/doc/html/ch01s02.html b/doc/html/ch01s02.html new file mode 100644 index 0000000000..a99b49ab21 --- /dev/null +++ b/doc/html/ch01s02.html @@ -0,0 +1,100 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Examples</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.html" title="Boost.Any"><link rel="previous" href="any.html" title="Boost.Any"><link rel="next" href="any.reference.html" title="Reference"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2814007"></a>Examples</h2></div></div><div></div></div><p>The following code demonstrates the syntax for using + implicit conversions to and copying of any objects:</p><pre class="programlisting"> +#include <list> +#include <boost/any.hpp> + +using <a href="id2827840.html" title="Function any_cast">boost::any_cast</a>; +typedef std::list<<a href="class.boost.any.html" title="Class any">boost::any</a>> many; + +void append_int(many & values, int value) +{ + <a href="class.boost.any.html" title="Class any">boost::any</a> to_append = value; + values.push_back(to_append); +} + +void append_string(many & values, const std::string & value) +{ + values.push_back(value); +} + +void append_char_ptr(many & values, const char * value) +{ + values.push_back(value); +} + +void append_any(many & values, const <a href="class.boost.any.html" title="Class any">boost::any</a> & value) +{ + values.push_back(value); +} + +void append_nothing(many & values) +{ + values.push_back(<a href="class.boost.any.html" title="Class any">boost::any</a>()); +} +</pre><p>The following predicates follow on from the previous + definitions and demonstrate the use of queries on any + objects:</p><pre class="programlisting"> +bool is_empty(const <a href="class.boost.any.html" title="Class any">boost::any</a> & operand) +{ + return operand.<a href="class.boost.any.html#id2827762">empty</a>(); +} + +bool is_int(const <a href="class.boost.any.html" title="Class any">boost::any</a> & operand) +{ + return operand.<a href="class.boost.any.html#id2827796">type</a>() == typeid(int); +} + +bool is_char_ptr(const <a href="class.boost.any.html" title="Class any">boost::any</a> & operand) +{ + try + { + <a href="id2827840.html" title="Function any_cast">any_cast</a><const char *>(operand); + return true; + } + catch(const <a href="class.boost.bad_any_cast.html" title="Class bad_any_cast">boost::bad_any_cast</a> &) + { + return false; + } +} + +bool is_string(const <a href="class.boost.any.html" title="Class any">boost::any</a> & operand) +{ + return <a href="id2827840.html" title="Function any_cast">any_cast</a><std::string>(&operand); +} + +void count_all(many & values, std::ostream & out) +{ + out << "#empty == " + << std::count_if(values.begin(), values.end(), is_empty) << std::endl; + out << "#int == " + << std::count_if(values.begin(), values.end(), is_int) << std::endl; + out << "#const char * == " + << std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl; + out << "#string == " + << std::count_if(values.begin(), values.end(), is_string) << std::endl; +} +</pre><p>The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types:</p><pre class="programlisting"> +struct property +{ + property(); + property(const std::string &, const <a href="class.boost.any.html" title="Class any">boost::any</a> &); + + std::string name; + <a href="class.boost.any.html" title="Class any">boost::any</a> value; +}; + +typedef std::list<property> properties; +</pre><p>The following base class demonstrates one approach to + runtime polymorphism based callbacks that also require arbitrary + argument types. The absence of virtual member templates requires + that different solutions have different trade-offs in terms of + efficiency, safety, and generality. Using a checked variant type + offers one approach:</p><pre class="programlisting"> +class consumer +{ +public: + virtual void notify(const <a href="class.boost.any.html" title="Class any">any</a> &) = 0; + ... +}; +</pre></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="any.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="any.reference.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Boost.Any </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Reference</td></tr></table></div></body></html> diff --git a/doc/html/ch01s04.html b/doc/html/ch01s04.html new file mode 100644 index 0000000000..7f16748730 --- /dev/null +++ b/doc/html/ch01s04.html @@ -0,0 +1,2 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Acknowledgements</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.html" title="Boost.Any"><link rel="previous" href="id2827840.html" title="Function any_cast"><link rel="next" href="function.html" title="Boost.Function"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2812847"></a>Acknowledgements</h2></div></div><div></div></div><p>Doug Gregor ported the documentation to the BoostBook format.</p></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2827840.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Function any_cast </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Boost.Function</td></tr></table></div></body></html> diff --git a/doc/html/ch04s02.html b/doc/html/ch04s02.html new file mode 100644 index 0000000000..f838ae5f50 --- /dev/null +++ b/doc/html/ch04s02.html @@ -0,0 +1,575 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Tutorial</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="signals.html" title="Boost.Signals"><link rel="next" href="signals.reference.html" title="Reference"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="ch04s02.html#id2888202" title="How to Read this Tutorial"><link rel="subsection" href="ch04s02.html#id2888275" title="Compatibility Note"><link rel="subsection" href="ch04s02.html#id2888425" title="Hello, World! (Beginner)"><link rel="subsection" href="ch04s02.html#id2888584" title="Calling multiple slots"><link rel="subsection" href="ch04s02.html#id2889063" title="Passing values to and from slots"><link rel="subsection" href="ch04s02.html#id2890060" title="Connection Management"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2888195"></a>Tutorial</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2888202"></a>How to Read this Tutorial</h3></div></div><div></div></div><p>This tutorial is not meant to be read linearly. Its top-level +structure roughly separates different concepts in the library +(e.g., handling calling multiple slots, passing values to and from +slots) and in each of these concepts the basic ideas are presented +first and then more complex uses of the library are described +later. Each of the sections is marked <span class="emphasis"><em>Beginner</em></span>, +<span class="emphasis"><em>Intermediate</em></span>, or <span class="emphasis"><em>Advanced</em></span> to help guide the +reader. The <span class="emphasis"><em>Beginner</em></span> sections include information that all +library users should know; one can make good use of the Signals +library after having read only the <span class="emphasis"><em>Beginner</em></span> sections. The +<span class="emphasis"><em>Intermediate</em></span> sections build on the <span class="emphasis"><em>Beginner</em></span> +sections with slightly more complex uses of the library. Finally, +the <span class="emphasis"><em>Advanced</em></span> sections detail very advanced uses of the +Signals library, that often require a solid working knowledge of +the <span class="emphasis"><em>Beginner</em></span> and <span class="emphasis"><em>Intermediate</em></span> topics; most users +will not need to read the <span class="emphasis"><em>Advanced</em></span> sections.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2888275"></a>Compatibility Note</h3></div></div><div></div></div><p>Boost.Signals has two syntactical forms: the preferred form and +the compatibility form. The preferred form fits more closely with the +C++ language and reduces the number of separate template parameters +that need to be considered, often improving readability; however, the +preferred form is not supported on all platforms due to compiler +bugs. The compatible form will work on all compilers supported by +Boost.Signals. Consult the table below to determine which syntactic +form to use for your compiler. Users of Boost.Function, please note +that the preferred syntactic form in Signals is equivalent to that of +Function's preferred syntactic form.</p><p>If your compiler does not appear in this list, please try the +preferred syntax and report your results to the Boost list so that +we can keep this table up-to-date.</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><div class="itemizedlist"><ul type="disc"><li><p>GNU C++ 2.95.x, 3.0.x, 3.1.x</p></li><li><p>Comeau C++ 4.2.45.2</p></li><li><p>SGI MIPSpro 7.3.0</p></li><li><p>Intel C++ 5.0, 6.0</p></li><li><p>Compaq's cxx 6.2</p></li></ul></div></td><td align="left"><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></p></li><li><p>Microsoft Visual C++ 6.0, 7.0</p></li><li><p>Borland C++ 5.5.1</p></li><li><p>Sun WorkShop 6 update 2 C++ 5.3</p></li><li><p>Metrowerks CodeWarrior 8.1</p></li></ul></div></td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2888425"></a>Hello, World! (Beginner)</h3></div></div><div></div></div><p>The following example writes "Hello, World!" using signals and +slots. First, we create a signal <tt class="computeroutput">sig</tt>, a signal that +takes no arguments and has a void return value. Next, we connect +the <tt class="computeroutput">hello</tt> function object to the signal using the +<tt class="computeroutput">connect</tt> method. Finally, use the signal +<tt class="computeroutput">sig</tt> like a function to call the slots, which in turns +invokes <tt class="computeroutput">HelloWorld::operator()</tt> to print "Hello, +World!".</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +struct HelloWorld +{ + void operator()() const + { + std::cout << "Hello, World!" << std::endl; + } +}; + +// ... + +// Signal with no arguments and a void return value +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><void ()> sig; + +// Connect a HelloWorld slot +HelloWorld hello; +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(hello); + +// Call all of the slots +sig(); +</pre></td><td align="left"><pre class="programlisting"> +struct HelloWorld +{ + void operator()() const + { + std::cout << "Hello, World!" << std::endl; + } +}; + +// ... + +// Signal with no arguments and a void return value +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal0</a><void> sig; + +// Connect a HelloWorld slot +HelloWorld hello; +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(hello); + +// Call all of the slots +sig(); +</pre></td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2888584"></a>Calling multiple slots</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2888590"></a>Connecting multiple slots (Beginner)</h4></div></div><div></div></div><p>Calling a single slot from a signal isn't very interesting, so +we can make the Hello, World program more interesting by splitting +the work of printing "Hello, World!" into two completely separate +slots. The first slot will print "Hello" and may look like +this:</p><pre class="programlisting"> +struct Hello +{ + void operator()() const + { + std::cout << "Hello"; + } +}; +</pre><p>The second slot will print ", World!" and a newline, to complete +the program. The second slot may look like this:</p><pre class="programlisting"> +struct World +{ + void operator()() const + { + std::cout << ", World!" << std::endl; + } +}; +</pre><p>Like in our previous example, we can create a signal +<tt class="computeroutput">sig</tt> that takes no arguments and has a +<tt class="computeroutput">void</tt> return value. This time, we connect both a +<tt class="computeroutput">hello</tt> and a <tt class="computeroutput">world</tt> slot to the same +signal, and when we call the signal both slots will be called.</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><void ()> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(Hello()); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(World()); + +sig(); +</pre></td><td align="left"><pre class="programlisting"> +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal0</a><void> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(Hello()); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(World()); + +sig(); +</pre></td></tr></tbody></table></div><p>Now, if you compile and run this program, you might see +something strange. It is possible that the output will look like +this:</p><pre class="programlisting"> + , World! +Hello +</pre><p>The underlying reason is that the ordering of signals isn't +guaranteed. The signal is free to call either the +<tt class="computeroutput">Hello</tt> slot or the <tt class="computeroutput">World</tt> slot first, but +every slot will be called unless something bad (e.g., an exception) +occurs. Read on to learn how to control the ordering so that +"Hello, World!" always prints as expected.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2888807"></a>Ordering slot call groups (Intermediate)</h4></div></div><div></div></div><p>Slots are free to have side effects, and that can mean that some +slots will have to be called before others. The Boost.Signals +library allows slots to be placed into groups that are ordered in +some way. For our Hello, World program, we want "Hello" to be +printed before ", World!", so we put "Hello" into a group that must +be executed before the group that ", World!" is in. To do this, we +can supply an extra parameter at the beginning of the +<tt class="computeroutput">connect</tt> call that specifies the group. Group values +are, by default, <tt class="computeroutput">int</tt>s, and are ordered by the integer +< relation. Here's how we construct Hello, World:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><void ()> sig; +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(0, Hello()); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(1, World()); +sig(); +</pre></td><td align="left"><pre class="programlisting"> +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal0</a><void> sig; +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(0, Hello()); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(1, World()); +sig(); +</pre></td></tr></tbody></table></div><p>This program will correctly print "Hello, World!", because the +<tt class="computeroutput">Hello</tt> object is in group 0, which precedes group 1 +where the <tt class="computeroutput">World</tt> object resides.</p><p>The group parameter is, in fact, optional. We omitted it in the +first Hello, World example because it was unnecessary when all of +the slots are independent. So what happens if we mix calls to +connect that use the group parameter and those that don't? The +"unnamed" slots (i.e., those that have been connected without +specifying a group name) go into a separate group that is special +in that it follows all other groups. So if we add a new slot to our +example like this:</p><pre class="programlisting"> +struct GoodMorning +{ + void operator()() const + { + std::cout << "... and good morning!" << std::endl; + } +}; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(GoodMorning()); +</pre><p>... we will get the result we wanted:</p><pre class="programlisting"> +Hello, World! +... and good morning! +</pre><p>The last interesting point with groups of slots is the behavior +when multiple slots are connected in the same group. Within groups, +calls to slots are unordered: if we connect slots <tt class="computeroutput">A</tt> +and <tt class="computeroutput">B</tt> to the same signal with the same group name, +either <tt class="computeroutput">A</tt> or <tt class="computeroutput">B</tt> will be called first (but +both will be called). This is the same behavior we saw before with +the second version of Hello, World, where the slots could be called +in the wrong order, mangling the output.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2889063"></a>Passing values to and from slots</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2889069"></a>Slot Arguments (Beginner)</h4></div></div><div></div></div><p>Signals can propagate arguments to each of the slots they call. +For instance, a signal that propagates mouse motion events might +want to pass along the new mouse coordinates and whether the mouse +buttons are pressed.</p><p>As an example, we'll create a signal that passes two +<tt class="computeroutput">float</tt> arguments to its slots. Then we'll create a few +slots that print the results of various arithmetic operations on +these values.</p><pre class="programlisting"> +void print_sum(float x, float y) +{ + std::cout << "The sum is " << x+y << std::endl; +} + +void print_product(float x, float y) +{ + std::cout << "The product is " << x*y << std::endl; +} + +void print_difference(float x, float y) +{ + std::cout << "The difference is " << x-y << std::endl; +} + +void print_quotient(float x, float y) +{ + std::cout << "The quotient is " << x/y << std::endl; +} +</pre><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><void (float, float)> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_difference); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_quotient); + +sig(5, 3); +</pre></td><td align="left"><pre class="programlisting"> +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal2</a><void, float, float> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_difference); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&print_quotient); + +sig(5, 3); +</pre></td></tr></tbody></table></div><p>This program will print out something like the following, +although the ordering of the lines may differ:</p><pre class="programlisting"> +The sum is 8 +The difference is 2 +The product is 15 +The quotient is 1.66667 +</pre><p>So any values that are given to <tt class="computeroutput">sig</tt> when it is +called like a function are passed to each of the slots. We have to +declare the types of these values up front when we create the +signal. The type <tt class="computeroutput"><a href="class.boost.signal.html" title="Class template signal">boost::signal</a><void (float, +float)></tt> means that the signal has a <tt class="computeroutput">void</tt> +return value and takes two <tt class="computeroutput">float</tt> values. Any slot +connected to <tt class="computeroutput">sig</tt> must therefore be able to take two +<tt class="computeroutput">float</tt> values.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2889329"></a>Signal Return Values (Advanced)</h4></div></div><div></div></div><p>Just as slots can receive arguments, they can also return +values. These values can then be returned back to the caller of the +signal through a <span class="emphasis"><em>combiner</em></span>. The combiner is a mechanism +that can take the results of calling slots (there many be no +results or a hundred; we don't know until the program runs) and +coalesces them into a single result to be returned to the caller. +The single result is often a simple function of the results of the +slot calls: the result of the last slot call, the maximum value +returned by any slot, or a container of all of the results are some +possibilities.</p><p>We can modify our previous arithmetic operations example +slightly so that the slots all return the results of computing the +product, quotient, sum, or difference. Then the signal itself can +return a value based on these results to be printed:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +float compute_product(float x, float y) { return x*y; } +float compute_quotient(float x, float y) { return x/y; } +float compute_sum(float x, float y) { return x+y; } +float compute_difference(float x, float y) { return x-y; } + +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><float (float x, float y)> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_quotient); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_difference); + +std::cout << sig(5, 3) << std::endl; +</pre></td><td align="left"><pre class="programlisting"> +float compute_product(float x, float y) { return x*y; } +float compute_quotient(float x, float y) { return x/y; } +float compute_sum(float x, float y) { return x+y; } +float compute_difference(float x, float y) { return x-y; } + +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal2</a><float, float, float> sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_quotient); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_difference); + +std::cout << sig(5, 3) << std::endl; +</pre></td></tr></tbody></table></div><p>This example program will output either <tt class="computeroutput">8</tt>, +<tt class="computeroutput">1.6667</tt>, <tt class="computeroutput">15</tt>, or <tt class="computeroutput">2</tt>, depending +on the order that the signals are called. This is because the +default behavior of a signal that has a return type +(<tt class="computeroutput">float</tt>, the first template argument given to the +<tt class="computeroutput"><a href="class.boost.signal.html" title="Class template signal">boost::signal</a></tt> class template) is to call all slots and +then return the result returned by the last slot called. This +behavior is admittedly silly for this example, because slots have +no side effects and the result is essentially randomly chosen from +the slots.</p><p>A more interesting signal result would be the maximum of the +values returned by any slot. To do this, we create a custom +combiner that looks like this:</p><pre class="programlisting"> +template<typename T> +struct maximum +{ + typedef T result_type; + + template<typename InputIterator> + T operator()(InputIterator first, InputIterator last) const + { + // If there are no slots to call, just return the + // default-constructed value + if (first == last) + return T(); + + T max_value = *first++; + while (first != last) { + if (max_value < *first) + max_value = *first; + ++first; + } + + return max_value; + } +}; +</pre><p>The <tt class="computeroutput">maximum</tt> class template acts as a function +object. Its result type is given by its template parameter, and +this is the type it expects to be computing the maximum based on +(e.g., <tt class="computeroutput">maximum<float></tt> would find the maximum +<tt class="computeroutput">float</tt> in a sequence of <tt class="computeroutput">float</tt>s). When a +<tt class="computeroutput">maximum</tt> object is invoked, it is given an input +iterator sequence <tt class="computeroutput">[first, last)</tt> that includes the +results of calling all of the slots. <tt class="computeroutput">maximum</tt> uses this +input iterator sequence to calculate the maximum element, and +returns that maximum value.</p><p>We actually use this new function object type by installing it +as a combiner for our signal. The combiner template argument +follows the signal's calling signature:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><float (float x, float y), + maximum<float> > sig; +</pre></td><td align="left"><pre class="programlisting"> +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal2</a><float, float, float, + maximum<float> > sig; +</pre></td></tr></tbody></table></div><p>Now we can connect slots that perform arithmetic functions and +use the signal:</p><pre class="programlisting"> +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_quotient); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_difference); + +std::cout << sig(5, 3) << std::endl; +</pre><p>The output of this program will be <tt class="computeroutput">15</tt>, because +regardless of the order in which the slots are called, the product +of 5 and 3 will be larger than the quotient, sum, or +difference.</p><p>In other cases we might want to return all of the values +computed by the slots together, in one large data structure. This +is easily done with a different combiner:</p><pre class="programlisting"> +template<typename Container> +struct aggregate_values +{ + typedef Container result_type; + + template<typename InputIterator> + Container operator()(InputIterator first, InputIterator last) const + { + return Container(first, last); + } +}; +</pre><p> +Again, we can create a signal with this new combiner: +</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a><float (float, float), + aggregate_values<std::vector<float> > > sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_quotient); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_difference); + +std::vector<float> results = sig(5, 3); +std::copy(results.begin(), results.end(), + std::ostream_iterator<float>(cout, " ")); +</pre></td><td align="left"><pre class="programlisting"> +<a href="class.boost.signalN.html" title="Class template signalN">boost::signal2</a><float, float, float, + aggregate_values<std::vector<float> > > sig; + +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_quotient); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_product); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_sum); +sig.<a href="class.boost.signalN.html#id2841744">connect</a>(&compute_difference); + +std::vector<float> results = sig(5, 3); +std::copy(results.begin(), results.end(), + std::ostream_iterator<float>(cout, " ")); +</pre></td></tr></tbody></table></div><p>The output of this program will contain 15, 8, 1.6667, and 2 +(but not necessarily in that order). It is interesting here that +the first template argument for the <tt class="computeroutput">signal</tt> class, +<tt class="computeroutput">float</tt>, is not actually the return type of the signal. +Instead, it is the return type used by the connected slots and will +also be the <tt class="computeroutput">value_type</tt> of the input iterators passed +to the combiner. The combiner itself is a function object and its +<tt class="computeroutput">result_type</tt> member type becomes the return type of the +signal.</p><p>The input iterators passed to the combiner transform dereference +operations into slot calls. Combiners therefore have the option to +invoke only some slots until some particular criterion is met. For +instance, in a distributed computing system, the combiner may ask +each remote system whether it will handle the request. Only one +remote system needs to handle a particular request, so after a +remote system accepts the work we do not want to ask any other +remote systems to perform the same task. Such a combiner need only +check the value returned when dereferencing the iterator, and +return when the value is acceptable. The following combiner returns +the first non-NULL pointer to a <tt class="computeroutput">FulfilledRequest</tt> data +structure, without asking any later slots to fulfill the +request:</p><pre class="programlisting"> +struct DistributeRequest { + typedef FulfilledRequest* result_type; + + template<typename InputIterator> + result_type operator()(InputIterator first, InputIterator last) const + { + while (first != last) { + if (result_type fulfilled = *first) + return fulfilled; + ++first; + } + return 0; + } +}; +</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2890060"></a>Connection Management</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2890066"></a>Disconnecting Slots (Beginner)</h4></div></div><div></div></div><p>Slots aren't expected to exist indefinately after they are +connected. Often slots are only used to receive a few events and +are then disconnected, and the programmer needs control to decide +when a slot should no longer be connected.</p><p>The entry point for managing connections explicitly is the +<tt class="computeroutput"><a href="id2890015.html" title="Class connection">boost::signals::connection</a></tt> class. The +<tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> class uniquely represents the connection +between a particular signal and a particular slot. The +<tt class="computeroutput"><a href="id2890015.html#id2893725">connected</a>()</tt> method checks if the signal and slot are +still connected, and the <tt class="computeroutput"><a href="id2890015.html#id2908738">disconnect()</a></tt> method +disconnects the signal and slot if they are connected before it is +called. Each call to the signal's <tt class="computeroutput">connect()</tt> method +returns a connection object, which can be used to determine if the +connection still exists or to disconnect the signal and slot.</p><pre class="programlisting"> +boost::signals::connection c = sig.<a href="class.boost.signalN.html#id2841744">connect</a>(HelloWorld()); +if (c.<a href="class.boost.signalN.html#id2841744">connect</a>ed()) { +<span class="emphasis"><em>// c is still connected to the signal</em></span> + sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span> +} + +c.disconnect(); <span class="emphasis"><em>// Disconnect the HelloWorld object</em></span> +assert(!c.<a href="class.boost.signalN.html#id2841744">connect</a>ed()); <span class="emphasis"><em>c isn't connected any more</em></span> + +sig(); <span class="emphasis"><em>// Does nothing: there are no connected slots</em></span> +</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2890208"></a>Scoped connections (Intermediate)</h4></div></div><div></div></div><p>The <tt class="computeroutput">boost::signals::scoped_connection</tt> class +references a signal/slot connection that will be disconnected when +the <tt class="computeroutput">scoped_connection</tt> class goes out of scope. This +ability is useful when a connection need only be temporary, +e.g.,</p><pre class="programlisting"> +{ + boost::signals::scoped_connection c = sig.<a href="class.boost.signalN.html#id2841744">connect</a>(ShortLived()); + sig(); <span class="emphasis"><em>// will call ShortLived function object</em></span> +} +sig(); <span class="emphasis"><em>// ShortLived function object no longer connected to sig</em></span> +</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2890264"></a>Automatic connection management (Intermediate)</h4></div></div><div></div></div><p>Boost.Signals can automatically track the lifetime of objects +involved in signal/slot connections, including automatic +disconnection of slots when objects involved in the slot call are +destroyed. For instance, consider a simple news delivery service, +where clients connect to a news provider that then sends news to +all connected clients as information arrives. The news delivery +service may be constructed like this: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +class NewsItem { /* ... */ }; + +boost::signal<void (const NewsItem& latestNews)> deliverNews; +</pre></td><td align="left"><pre class="programlisting"> +class NewsItem { /* ... */ }; + +boost::signal1<void, const NewsItem&> deliverNews; +</pre></td></tr></tbody></table></div><p>Clients that wish to receive news updates need only connect a +function object that can receive news items to the +<tt class="computeroutput">deliverNews</tt> signal. For instance, we may have a +special message area in our application specifically for news, +e.g.,:</p><pre class="programlisting"> +struct NewsMessageArea : public MessageArea +{ +public: + // ... + + void displayNews(const NewsItem& news) const + { + messageText = news.text(); + update(); + } +}; + +// ... +NewsMessageArea newsMessageArea = new NewsMessageArea(/* ... */); +// ... +deliverNews.<a href="class.boost.signalN.html#id2841744">connect</a>(boost::bind(&NewsMessageArea::displayNews, + newsMessageArea, _1)); +</pre><p>However, what if the user closes the news message area, +destroying the <tt class="computeroutput">newsMessageArea</tt> object that +<tt class="computeroutput">deliverNews</tt> knows about? Most likely, a segmentation +fault will occur. However, with Boost.Signals one need only make +<tt class="computeroutput">NewsMessageArea</tt> <span class="emphasis"><em>trackable</em></span>, and the slot +involving <tt class="computeroutput">newsMessageArea</tt> will be disconnected when +<tt class="computeroutput">newsMessageArea</tt> is destroyed. The +<tt class="computeroutput">NewsMessageArea</tt> class is made trackable by deriving +publicly from the <tt class="computeroutput">boost::signals::trackable</tt> class, +e.g.:</p><pre class="programlisting"> +struct NewsMessageArea : public MessageArea, public boost::signals::trackable +{ + // ... +}; +</pre><p>At this time there is a significant limitation to the use of +<tt class="computeroutput">trackable</tt> objects in making slot connections: function +objects built using Boost.Bind are understood, such that pointers +or references to <tt class="computeroutput">trackable</tt> objects passed to +<tt class="computeroutput">boost::bind</tt> will be found and tracked.</p><p><span class="bold"><b>Warning</b></span>: User-defined function objects and function +objects from other libraries (e.g., Boost.Function or Boost.Lambda) +do not implement the required interfaces for <tt class="computeroutput">trackable</tt> +object detection, and <span class="emphasis"><em>will silently ignore any bound trackable +objects</em></span>. Future versions of the Boost libraries will address +this limitation.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2890510"></a>When can disconnections occur? (Intermediate)</h4></div></div><div></div></div><p>Signal/slot disconnections occur when any of these conditions +occur:</p><div class="itemizedlist"><ul type="disc"><li><p>The connection is explicitly disconnected via the connection's +<tt class="computeroutput">disconnect</tt> method directly, or indirectly via the +signal's <tt class="computeroutput">disconnect</tt> method or +<tt class="computeroutput">scoped_connection</tt>'s destructor.</p></li><li><p>A <tt class="computeroutput">trackable</tt> object bound to the slot is +destroyed.</p></li><li><p>The signal is destroyed.</p></li></ul></div><p>These events can occur at any time without disrupting a signal's +calling sequence. If a signal/slot connection is disconnected at +any time during a signal's calling sequence, the calling sequence +will still continue but will not invoke the disconnected slot. +Additionally, a signal may be destroyed while it is in a calling +sequence, and which case it will complete its slot call sequence +but may not be accessed directly.</p><p>Signals may be invoked recursively (e.g., a signal A calls a +slot B that invokes signal A...). The disconnection behavior does +not change in the recursive case, except that the slot calling +sequence includes slot calls for all nested invocations of the +signal.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2890595"></a>Passing slots (Intermediate)</h4></div></div><div></div></div><p>Slots in the Boost.Signals library are created from arbitrary +function objects, and therefore have no fixed type. However, it is +commonplace to require that slots be passed through interfaces that +cannot be templates. Slots can be passed via the +<tt class="computeroutput">slot_type</tt> for each particular signal type and any +function object compatible with the signature of the signal can be +passed to a <tt class="computeroutput">slot_type</tt> parameter. For instance:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +class Button +{ + typedef boost::signal<void (int x, int y)> OnClick; + +public: + void doOnClick(const OnClick::slot_type& slot); + +private: + OnClick onClick; +}; + +void Button::doOnClick(const OnClick::slot_type& slot) +{ + onClick.<a href="class.boost.signalN.html#id2841744">connect</a>(slot); +} + +void printCoordinates(long x, long y) +{ + std::cout << "(" << x << ", " << y << ")\n"; +} + +void f(Button& button) +{ + button.doOnClick(&printCoordinates); +} +</pre></td><td align="left"><pre class="programlisting"> +class Button +{ + typedef <a href="class.boost.signalN.html" title="Class template signalN">boost::signal2</a><void, int x, int y> OnClick; + +public: + void doOnClick(const OnClick::slot_type& slot); + +private: + OnClick onClick; +}; + +void Button::doOnClick(const OnClick::slot_type& slot) +{ + onClick.<a href="class.boost.signalN.html#id2841744">connect</a>(slot); +} + +void printCoordinates(long x, long y) +{ + std::cout << "(" << x << ", " << y << ")\n"; +} + +void f(Button& button) +{ + button.doOnClick(&printCoordinates); +} +</pre></td></tr></tbody></table></div><p>The <tt class="computeroutput">doOnClick</tt> method is now functionally equivalent +to the <tt class="computeroutput">connect</tt> method of the <tt class="computeroutput">onClick</tt> +signal, but the details of the <tt class="computeroutput">doOnClick</tt> method can be +hidden in an implementation detail file.</p></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="signals.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="signals.reference.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Boost.Signals </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Reference</td></tr></table></div></body></html> diff --git a/doc/html/ch04s04.html b/doc/html/ch04s04.html new file mode 100644 index 0000000000..999f976e53 --- /dev/null +++ b/doc/html/ch04s04.html @@ -0,0 +1,27 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Frequently Asked Questions</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="id2830650.html" title="Class last_value<void>"><link rel="next" href="ch04s05.html" title="Design Overview"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2895619"></a>Frequently Asked Questions</h2></div></div><div></div></div><div class="qandaset"><dl><dt>1. <a href="ch04s04.html#id2895627">Don't noncopyable signal semantics mean that a class + with a signal member will be noncopyable as well?</a></dt><dt>2. <a href="ch04s04.html#id2895654">Is Boost.Signals thread-safe?</a></dt><dt>3. <a href="ch04s04.html#id2895679">How do I get Boost.Signals to work with Qt?</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id2895627"></a><a name="id2895630"></a><b>1. </b></td><td align="left" valign="top"><p>Don't noncopyable signal semantics mean that a class + with a signal member will be noncopyable as well?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>No. The compiler will not be able to generate a copy + constructor or copy assignment operator for your class if it + has a signal as a member, but you are free to write your own + copy constructor and/or copy assignment operator. Just don't + try to copy the signal.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2895654"></a><a name="id2895657"></a><b>2. </b></td><td align="left" valign="top"><p>Is Boost.Signals thread-safe?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>No. Using Boost.Signals in a multithreaded concept is + very dangerous, and it is very likely that the results will be + less than satisfying. Boost.Signals will support thread safety + in the future.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2895679"></a><a name="id2895682"></a><b>3. </b></td><td align="left" valign="top"><p>How do I get Boost.Signals to work with Qt?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>When building with Qt, the Moc keywords + <tt class="computeroutput">signals</tt> and <tt class="computeroutput">slots</tt> are defined using + preprocessor macros, causing programs using Boost.Signals and + Qt together to fail to compile. Although this is a problem + with Qt and not Boost.Signals, a user can use the two systems + together by defining the <tt class="computeroutput">BOOST_SIGNALS_NAMESPACE</tt> + macro to some other identifier (e.g., <tt class="computeroutput">signalslib</tt>) + when building and using the Boost.Signals library. Then the + namespace of the Boost.Signals library will be + <tt class="computeroutput">boost::BOOST_SIGNALS_NAMESPACE</tt> instead of + <tt class="computeroutput">boost::signals</tt>. To retain the original namespace + name in translation units that do not interact with Qt, you + can use a namespace alias:</p><pre class="programlisting"> + namespace boost { + namespace signals = BOOST_SIGNALS_NAMESPACE; + } +</pre></td></tr></tbody></table></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2830650.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s05.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class last_value<void> </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Design Overview</td></tr></table></div></body></html> diff --git a/doc/html/ch04s05.html b/doc/html/ch04s05.html new file mode 100644 index 0000000000..16e2fa7c6f --- /dev/null +++ b/doc/html/ch04s05.html @@ -0,0 +1,102 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Design Overview</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="ch04s04.html" title="Frequently Asked Questions"><link rel="next" href="ch04s06.html" title="Design Rationale"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="ch04s05.html#id2895772" title="Type Erasure"><link rel="subsection" href="ch04s05.html#id2895860" title="connection class"><link rel="subsection" href="ch04s05.html#id2895993" title="Slot Call Iterator"><link rel="subsection" href="ch04s05.html#id2896236" title="visit_each function template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2895766"></a>Design Overview</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2895772"></a>Type Erasure</h3></div></div><div></div></div><p>"Type erasure", where static type information is eliminated + by the use of dynamically dispatched interfaces, is used + extensively within the Boost.Signals library to reduce the amount + of code generated by template instantiation. Each signal must + manage a list of slots and their associated connections, along + with a <tt class="computeroutput">std::map</tt> to map from group identifiers to + their associated connections. However, instantiating this map for + every token type, and perhaps within each translation unit (for + some popular template instantiation strategies) increase compile + time overhead and space overhead.</p><p> To combat this so-called "template bloat", we use + Boost.Function and Boost.Any to store unknown types and + operations. Then, all of the code for handling the list of slots + and the mapping from slot identifiers to connections is factored + into the class <tt class="computeroutput">signal_base</tt> + that deals exclusively with the <tt class="computeroutput">any</tt> and + <tt class="computeroutput"><a href="class.boost.function.html" title="Class template function">function</a></tt> objects, hiding the + actual implementations using the well-known pimpl idiom. The + actual <tt class="computeroutput"><a href="class.boost.signalN.html" title="Class template signalN">signalN</a></tt> class templates + deal only with code that will change depending on the number of + arguments or which is inherently template-dependent (such as + connection).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2895860"></a><tt class="computeroutput">connection</tt> class</h3></div></div><div></div></div><p> The <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> class is + central to the behavior of the Boost.Signals library. It is the + only entity within the Boost.Signals system that has knowledge of + all objects that are associated by a given connection. To be + specific, the <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> class + itself is merely a thin wrapper over a + <tt class="computeroutput">shared_ptr</tt> to a + <tt class="computeroutput">basic_connection</tt> object.</p><p> <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> objects are + stored by all participants in the Signals system: each + <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> object contains a + list of <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> objects + describing all connections it is a part of; similarly, all signals + contain a set of pairs that define a slot. The pairs consist of a + slot function object (generally a Boost.Function object) and a + <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> object (that will + disconnect on destruction). Finally, the mapping from slot groups + to slots is based on the key value in a + <tt class="computeroutput">std::multimap</tt> (the stored data + in the <tt class="computeroutput">std::multimap</tt> is the + slot pair).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2895993"></a>Slot Call Iterator</h3></div></div><div></div></div><p> The slot call iterator is conceptually a stack of iterator + adaptors that modify the behavior of the underlying iterator + through the list of slots. The following table describes the type + and behavior of each iterator adaptor required. Note that this is + only a conceptual model: the implementation collapses all these + layers into a single iterator adaptor because several popular + compilers failed to compile the implementation of the conceptual + model.</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Iterator Adaptor</th><th align="left">Purpose</th></tr></thead><tbody><tr><td align="left"><p>Slot List Iterator</p></td><td align="left"><p>An iterator through the list of slots + connected to a signal. The <tt class="computeroutput">value_type</tt> of this + iterator will be + <tt class="computeroutput">std::pair<any, + connection></tt>, where the + <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">any</a></tt> contains an + instance of the slot function type.</p></td></tr><tr><td align="left"><p>Filter Iterator Adaptor</p></td><td align="left"><p>This filtering iterator adaptor filters out + slots that have been disconnected, so we never see a + disconnected slot in later stages.</p></td></tr><tr><td align="left"><p>Projection Iterator Adaptor</p></td><td align="left"><p>The projection iterator adaptor returns a + reference to the first member of the pair that constitutes + a connected slot (e.g., just the + <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">boost::any</a></tt> object that + holds the slot function).</p></td></tr><tr><td align="left"><p>Transform Iterator Adaptor</p></td><td align="left"><p>This transform iterator adaptor performs an + <tt class="computeroutput"><a href="id2827840.html" title="Function any_cast">any_cast</a></tt> to + extract a reference to the slot function with the + appropriate slot function type.</p></td></tr><tr><td align="left"><p>Transform Iterator Adaptor</p></td><td align="left"><p>This transform iterator adaptor calls the + function object returned by dereferencing the underlying + iterator with the set of arguments given to the signal + itself, and returns the result of that slot + call.</p></td></tr><tr><td align="left"><p>Input Caching Iterator Adaptor</p></td><td align="left"><p>This iterator adaptor caches the result of + dereferencing the underlying iterator. Therefore, + dereferencing this iterator multiple times will only + result in the underlying iterator being dereferenced once; + thus, a slot can only be called once but its result can be + used multiple times.</p></td></tr><tr><td align="left"><p>Slot Call Iterator</p></td><td align="left"><p>Iterates over calls to each slot.</p></td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2896236"></a><tt class="computeroutput">visit_each</tt> function template</h3></div></div><div></div></div><p> The <tt class="computeroutput"><a href="id2905241.html" title="Function template visit_each">visit_each</a></tt> + function template is a mechanism for discovering objects that are + stored within another object. Function template + <tt class="computeroutput"><a href="id2905241.html" title="Function template visit_each">visit_each</a></tt> takes three + arguments: an object to explore, a visitor function object that is + invoked with each subobject, and the <tt class="computeroutput">int</tt> 0. </p><p> The third parameter is merely a temporary solution to the + widespread lack of proper function template partial ordering. The + primary <tt class="computeroutput"><a href="id2905241.html" title="Function template visit_each">visit_each</a></tt> + function template specifies this third parameter type to be + <tt class="computeroutput">long</tt>, whereas any user specializations must specify + their third parameter to be of type <tt class="computeroutput">int</tt>. Thus, even + though a broken compiler cannot tell the ordering between, e.g., a + match against a parameter <tt class="computeroutput">T</tt> and a parameter + <tt class="computeroutput">A<T></tt>, it can determine that the conversion from + the integer 0 to <tt class="computeroutput">int</tt> is better than the conversion to + <tt class="computeroutput">long</tt>. The ordering determined by this conversion thus + achieves partial ordering of the function templates in a limited, + but successful, way. The following example illustrates the use of + this technique:</p><pre class="programlisting"> +template<typename> class A {}; +template<typename T> void foo(T, long); +template<typename T> void foo(A<T>, int); +A<T> at; +foo(at, 0); +</pre><p> In this example, we assume that our compiler can not tell + that <tt class="computeroutput">A<T></tt> is a better match than + <tt class="computeroutput">T</tt>, and therefore assume that the function templates + cannot be ordered based on that parameter. Then the conversion + from 0 to <tt class="computeroutput">int</tt> is better than the conversion from 0 to + <tt class="computeroutput">long</tt>, and the second function template is + chosen. </p></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s06.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Frequently Asked Questions </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Design Rationale</td></tr></table></div></body></html> diff --git a/doc/html/ch04s06.html b/doc/html/ch04s06.html new file mode 100644 index 0000000000..e56a99617a --- /dev/null +++ b/doc/html/ch04s06.html @@ -0,0 +1,269 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Design Rationale</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="ch04s05.html" title="Design Overview"><link rel="next" href="ch04s07.html" title="Testsuite"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="ch04s06.html#id2896415" title="Choice of Slot Definitions"><link rel="subsection" href="ch04s06.html#id2896550" title="User-level Connection Management"><link rel="subsection" href="ch04s06.html#id2811980" title="Combiner Interface"><link rel="subsection" href="ch04s06.html#id2897087" title="Connection Interfaces: += operator"><link rel="subsection" href="ch04s06.html#id2897291" title="trackable rationale"><link rel="subsection" href="ch04s06.html#id2897506" title="Comparison with other Signal/Slot implementations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2896408"></a>Design Rationale</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2896415"></a>Choice of Slot Definitions</h3></div></div><div></div></div><p> 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.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><b>Slots derive from a specific base + class</b></span>: generally a scheme such as this will require + all user-defined slots to derive from some library-specified + <tt class="computeroutput">Slot</tt> 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).</p><p> This approach does have the benefit of simplicity of + implementation and user interface, from an object-oriented + perspective.</p></li><li><p><span class="bold"><b>Slots constructed from a set of + primitives</b></span>: 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 + <tt class="computeroutput"><a href="id2905241.html" title="Function template visit_each">visit_each</a></tt> + mechanism) that allows existing binder/composition libraries + to provide the necessary information to Signals.</p></li></ul></div><p> 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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2896550"></a>User-level Connection Management</h3></div></div><div></div></div><p> 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 + <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> object that enables + connected/disconnected query, manual disconnection, and an + automatic disconnection on destruction mode. Some other possible + interfaces include:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><b>Pass slot to + disconnect</b></span>: in this interface model, the + disconnection of a slot connected with + <tt class="computeroutput">sig.<a href="class.boost.signalN.html#id2841744">connect</a>(slot)</tt> is + performed via + <tt class="computeroutput">sig.<a href="class.boost.signalN.html#id2846925">disconnect</a>(slot)</tt>. 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 + <tt class="computeroutput"><a href="class.boost.signalN.html#id2846925">disconnect</a></tt> with an + existing slot we would need to be able to compare arbitrary + function objects, which is not feasible.</p></li><li><p><span class="bold"><b>Pass a token to + disconnect</b></span>: 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:</p><div class="itemizedlist"><ul type="circle"><li><p>Connections and disconnections must be paired, so + the problem becomes similar to the problems incurred when + pairing <tt class="computeroutput">new</tt> and <tt class="computeroutput">delete</tt> for + dynamic memory allocation. While errors of this sort would + not be catastrophic for a signals and slots + implementation, their detection is generally + nontrivial.</p></li><li><p>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.</p></li><li><p>More parameterization would be required, because the + token type must be user-defined. Additional + parameterization steepens the learning curver and + overcomplicates a simple interface.</p></li></ul></div><p> This type of interface is supported in Boost.Signals + via the slot grouping mechanism. It augments the + <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> object-based + connection management scheme.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2811980"></a>Combiner Interface</h3></div></div><div></div></div><p> 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 & slots + libraries, the combiners are unfortunately not reusable (either in + other signals & slots libraries or within other generic + algorithms), and the learning curve is steepened slightly to learn + the specific combiner interface.</p><p> 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.</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left"><p>Pull</p></th><th align="left"><p>Push</p></th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> +struct pull_max { + typedef int result_type; + + template<typename InputIterator> + result_type operator()(InputIterator first, + InputIterator last) + { + if (first == last) + throw std::runtime_error("Empty!"); + + int max_value = *first++; + while(first != last && *first <= 100) { + if (*first > max_value) + max_value = *first; + ++first; + } + + return max_value; + } +}; +</pre></td><td align="left"><pre class="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 > 100) + return false; + + if (!got_first) { + got_first = true; + max_value = result; + return true; + } + + if (result > 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; +}; +</pre></td></tr></tbody></table></div><p>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 <tt class="computeroutput">value_type</tt>, + 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 & slots library.</p><p> 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).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2897087"></a>Connection Interfaces: += operator</h3></div></div><div></div></div><p> Boost.Signals supports a connection syntax with the form + <tt class="computeroutput">sig.<a href="class.boost.signalN.html#id2841744">connect</a>(slot)</tt>, but a + more terse syntax <tt class="computeroutput">sig += slot</tt> has been suggested (and + has been used by other signals & slots implementations). There + are several reasons as to why this syntax has been + rejected:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><b>It's unnecessary</b></span>: the + connection syntax supplied by Boost.Signals is no less + powerful that that supplied by the <tt class="computeroutput">+=</tt> + operator. The savings in typing (<tt class="computeroutput">connect()</tt> + vs. <tt class="computeroutput">+=</tt>) is essentially negligible. Furthermore, + one could argue that calling <tt class="computeroutput">connect()</tt> is more + readable than an overload of <tt class="computeroutput">+=</tt>.</p></li><li><p><span class="bold"><b>Ambiguous return type</b></span>: + there is an ambiguity concerning the return value of the + <tt class="computeroutput">+=</tt> operation: should it be a reference to the + signal itself, to enable <tt class="computeroutput">sig += slot1 += slot2</tt>, + or should it return a + <tt class="computeroutput"><a href="id2890015.html" title="Class connection">connection</a></tt> for the + newly-created signal/slot connection?</p></li><li><p><span class="bold"><b>Gateway to operators -=, + +</b></span>: when one has added a connection operator + <tt class="computeroutput">+=</tt>, it seems natural to have a disconnection + operator <tt class="computeroutput">-=</tt>. However, this presents problems when + the library allows arbitrary function objects to implicitly + become slots, because slots are no longer comparable. </p><p> The second obvious addition when one has + <tt class="computeroutput">operator+=</tt> would be to add a <tt class="computeroutput">+</tt> + operator that supports addition of multiple slots, followed by + assignment to a signal. However, this would require + implementing <tt class="computeroutput">+</tt> such that it can accept any two + function objects, which is technically infeasible.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2897291"></a><tt class="computeroutput">trackable</tt> rationale</h3></div></div><div></div></div><p> The <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> + 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 + <tt class="computeroutput">trackable</tt>, and the limitation requiring users to + derive from <tt class="computeroutput">trackable</tt> to create types that can + participate in automatic connection management.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897340"></a><tt class="computeroutput">trackable</tt> copying behavior</h4></div></div><div></div></div><p> The copying behavior of + <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> is essentially + that <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> 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 + <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> 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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897409"></a>Why derivation from <tt class="computeroutput">trackable</tt>?</h4></div></div><div></div></div><p> For <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> to work + properly, there are two constraints:</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> must + have storage space to keep track of all connections made to + this object.</p></li><li><p><tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> must be + notified when the object is being destructed so that it can + disconnect its connections.</p></li></ul></div><p>Clearly, deriving from + <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">trackable</a></tt> meets these two + guidelines. We have not yet found a superior solution.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2897506"></a>Comparison with other Signal/Slot implementations</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897514"></a>libsigc++</h4></div></div><div></div></div><p> <a href="http://libsigc.sourceforge.net" target="_top">libsigc++</a> is a C++ + signals & slots library that originally started as part of + an initiative to wrap the C interfaces to <a href="http://www.gtk.org" target="_top">GTK</a> 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:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><b>Slot definitions</b></span>: + 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.</p></li><li><p><span class="bold"><b>Combiner/Marshaller + interface</b></span>: 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.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897600"></a>.NET delegates</h4></div></div><div></div></div><p> <a href="http://www.microsoft.com" target="_top">Microsoft</a> + has introduced the .NET Framework and an associated set of + languages and language extensions, one of which is the + delgate. Delegates are similar to signals and slots, but they + are more limited than most C++ signals and slots implemetations + in that they:</p><div class="itemizedlist"><ul type="disc"><li><p>Require exact type matches between a delegate and what + it is calling.</p></li><li><p>Do not allow return types.</p></li><li><p>Must call a method with <tt class="computeroutput">this</tt> already + bound.</p></li></ul></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s05.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s07.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Design Overview </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Testsuite</td></tr></table></div></body></html> diff --git a/doc/html/ch04s07.html b/doc/html/ch04s07.html new file mode 100644 index 0000000000..91edb716f8 --- /dev/null +++ b/doc/html/ch04s07.html @@ -0,0 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Testsuite</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="ch04s06.html" title="Design Rationale"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="ch04s07.html#id2897667" title="Acceptance tests"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2897663"></a>Testsuite</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2897667"></a>Acceptance tests</h3></div></div><div></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Test</th><th>Type</th><th>Description</th><th>If failing...</th></tr></thead><tbody><tr><td><p><a href="../../libs/signals/test/dead_slot_test.cpp" target="_top">dead_slot_test.cpp</a></p></td><td><p>run</p></td><td><p>Ensure that calling connect 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><a href="../../libs/signals/test/deletion_test.cpp" target="_top">deletion_test.cpp</a></p></td><td><p>run</p></td><td><p>Test deletion of slots.</p></td><td> </td></tr><tr><td><p><a href="../../libs/signals/test/ordering_test.cpp" target="_top">ordering_test.cpp</a></p></td><td><p>run</p></td><td><p>Test slot group ordering.</p></td><td> </td></tr><tr><td><p><a href="../../libs/signals/test/signal_n_test.cpp" target="_top">signal_n_test.cpp</a></p></td><td><p>run</p></td><td><p>Basic test of signal/slot connections and invocation using the +<a href="class.boost.signalN.html" title="Class template signalN">boost::signalN</a> class templates.</p></td><td> </td></tr><tr><td><p><a href="../../libs/signals/test/signal_test.cpp" target="_top">signal_test.cpp</a></p></td><td><p>run</p></td><td><p>Basic test of signal/slot connections and invocation using the +<a href="class.boost.signal.html" title="Class template signal">boost::signal</a> class template.</p></td><td><p>The <a href="class.boost.signal.html" title="Class template signal">boost::signal</a> class template may not +be usable on your compiler. However, the +<a href="class.boost.signalN.html" title="Class template signalN">boost::signalN</a> class templates may still be +usable.</p></td></tr><tr><td><p><a href="../../libs/signals/test/trackable_test.cpp" target="_top">trackable_test.cpp</a></p></td><td><p>run</p></td><td><p>Test automatic lifetime management using + boost::trackable objects.</p></td><td> </td></tr></tbody></table></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s06.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Design Rationale </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html> diff --git a/doc/html/class.boost.any.html b/doc/html/class.boost.any.html new file mode 100644 index 0000000000..7d0a77b147 --- /dev/null +++ b/doc/html/class.boost.any.html @@ -0,0 +1,72 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class any</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.reference.html#header.boost.any.hpp" title="Header <boost/any.hpp>"><link rel="previous" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="next" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.any.html#id2865702" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.any"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class any</span></h2><p>boost::any — A class whose instances can hold instances of any + type that satisfies ValueType + requirements.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> any { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="class.boost.any.html#id2623685construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.any.html#id2828868">any()</a>; + <a href="class.boost.any.html#id2828883">any(<span class="bold"><b>const</b></span> any &)</a>; + <a href="class.boost.any.html#id2828939"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> any(<span class="bold"><b>const</b></span> ValueType &)</a>; + <a href="class.boost.any.html#id2829010">any & <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> any &)</a>; + <a href="class.boost.any.html#id2829076"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> any & <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> ValueType &)</a>; + <a href="class.boost.any.html#id2828993">~any()</a>; + + <span class="emphasis"><em>// <a href="class.boost.any.html#id2829139">modifiers</a></em></span> + <a href="class.boost.any.html#id2829145">any & swap(any &)</a>; + + <span class="emphasis"><em>// <a href="class.boost.any.html#id2827756">queries</a></em></span> + <a href="class.boost.any.html#id2827762"><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span></a>; + <a href="class.boost.any.html#id2827796"><span class="bold"><b>const</b></span> std::type_info & type() <span class="bold"><b>const</b></span></a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2623685construct-copy-destruct"></a><tt class="computeroutput">any</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2828868"></a>any();</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.any.html#id2827762">empty</a>()</tt></p></li><li><pre class="literallayout"><a name="id2828883"></a>any(<span class="bold"><b>const</b></span> any & other);</pre><p><b><span class="term">Effects</span></b>: + Copy constructor that copies content of + <tt class="computeroutput">other</tt> into new instance, so that any content + is equivalent in both type and value to the content of + <tt class="computeroutput">other</tt>, or empty if <tt class="computeroutput">other</tt> is + empty. <br><b><span class="term">Throws</span></b>: + May fail with a + <tt class="computeroutput">std::bad_alloc</tt> + exception or any exceptions arising from the copy + constructor of the contained type.</p></li><li><pre class="literallayout"><a name="id2828939"></a><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> any(<span class="bold"><b>const</b></span> ValueType & value);</pre><p><b><span class="term">Effects</span></b>: + Makes a copy of <tt class="computeroutput">value</tt>, so + that the initial content of the new instance is equivalent + in both type and value to + <tt class="computeroutput">value</tt>.<br><b><span class="term">Throws</span></b>: + <tt class="computeroutput">std::bad_alloc</tt> + or any exceptions arising from the copy constructor of the + contained type.</p></li><li><pre class="literallayout"><a name="id2829010"></a>any & <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> any & rhs);</pre><p><b><span class="term">Effects</span></b>: + Copies content of <tt class="computeroutput">rhs</tt> into + current instance, discarding previous content, so that the + new content is equivalent in both type and value to the + content of <tt class="computeroutput">rhs</tt>, or empty if + <tt class="computeroutput">rhs.<a href="class.boost.any.html#id2827762">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + <tt class="computeroutput">std::bad_alloc</tt> + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.</p></li><li><pre class="literallayout"><a name="id2829076"></a><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> any & <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> ValueType & rhs);</pre><p><b><span class="term">Effects</span></b>: + Makes a copy of <tt class="computeroutput">rhs</tt>, + discarding previous content, so that the new content of is + equivalent in both type and value to + <tt class="computeroutput">rhs</tt>.<br><b><span class="term">Throws</span></b>: + <tt class="computeroutput">std::bad_alloc</tt> + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.</p></li><li><pre class="literallayout"><a name="id2828993"></a>~any();</pre><p><b><span class="term">Effects</span></b>: + Releases any and all resources used in + management of instance.<br><b><span class="term">Throws</span></b>: + Nothing.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2829139"></a><tt class="computeroutput">any</tt> modifiers</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2829145"></a>any & swap(any & rhs);</pre><p><b><span class="term">Effects</span></b>: + Exchange of the contents of + <tt class="computeroutput">*this</tt> and + <tt class="computeroutput">rhs</tt>.<br><b><span class="term">Returns</span></b>: + <tt class="computeroutput">*this</tt><br><b><span class="term">Throws</span></b>: + Nothing.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2827756"></a><tt class="computeroutput">any</tt> queries</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2827762"></a><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if instance is + empty, otherwise <tt class="computeroutput">false</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2827796"></a><span class="bold"><b>const</b></span> std::type_info & type() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + the <tt class="computeroutput">typeid</tt> of the + contained value if instance is non-empty, otherwise + <tt class="computeroutput">typeid(void)</tt>.<br><b><span class="term">Notes</span></b>: + Useful for querying against types known + either at compile time or only at + runtime.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.bad_any_cast.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.reference.html#header.boost.any.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2827840.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class bad_any_cast </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Function any_cast</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.bad_any_cast.html b/doc/html/class.boost.bad_any_cast.html new file mode 100644 index 0000000000..d1b80052f5 --- /dev/null +++ b/doc/html/class.boost.bad_any_cast.html @@ -0,0 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class bad_any_cast</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.reference.html#header.boost.any.hpp" title="Header <boost/any.hpp>"><link rel="previous" href="any.reference.html" title="Reference"><link rel="next" href="class.boost.any.html" title="Class any"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.bad_any_cast"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class bad_any_cast</span></h2><p>boost::bad_any_cast — The exception thrown in the event of a failed + any_cast of an + any value.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> bad_any_cast : <span class="bold"><b>public</b></span> std::bad_cast { +<span class="bold"><b>public</b></span>: + <a name="id2623670"></a><span class="bold"><b>const</b></span> <span class="bold"><b>char</b></span> * what() <span class="bold"><b>const</b></span>; +};</pre></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="any.reference.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.reference.html#header.boost.any.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.any.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Reference </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class any</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.function.html b/doc/html/class.boost.function.html new file mode 100644 index 0000000000..6ee8be15e8 --- /dev/null +++ b/doc/html/class.boost.function.html @@ -0,0 +1,109 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template function</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.reference.html#header.boost.function.hpp" title="Header <boost/function.hpp>"><link rel="previous" href="class.boost.functionN.html" title="Class template functionN"><link rel="next" href="function.faq.html" title="Frequently Asked Questions"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.function.html#id2884268" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.function"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template function</span></h2><p>boost::function — A generalized function pointer that can be used for + callbacks or wrapping function objects.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="emphasis"><em> // Function type R (T1, T2, ..., TN)</em></span> + <span class="bold"><b>typename</b></span> Allocator = std::allocator<void> > +<span class="bold"><b>class</b></span> function : <span class="bold"><b>public</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><R, T1, T2, ..., TN, Allocator> { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> R result_type; + <span class="bold"><b>typedef</b></span> Allocator allocator_type; + <span class="bold"><b>typedef</b></span> T1 argument_type; <span class="emphasis"><em>// If N == 1</em></span> + <span class="bold"><b>typedef</b></span> T1 first_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T2 second_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T1 arg1_type; + <span class="bold"><b>typedef</b></span> T2 arg2_type; + . + . + . + <span class="bold"><b>typedef</b></span> TN argN_type; + + <span class="emphasis"><em>// static constants</em></span> + <span class="bold"><b>static</b></span> <span class="bold"><b>const</b></span> <span class="bold"><b>int</b></span> arity = N; + + <span class="emphasis"><em>// <a href="class.boost.function.html#id2747518construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.function.html#id2821169">function()</a>; + <a href="class.boost.function.html#id2821190">function(<span class="bold"><b>const</b></span> functionN&)</a>; + <a href="class.boost.function.html#id2821239">function(<span class="bold"><b>const</b></span> function&)</a>; + <a href="class.boost.function.html#id2821288"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> F> function(F)</a>; + <a href="class.boost.function.html#id2834405">function& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> functionN&)</a>; + <a href="class.boost.function.html#id2820958">function& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> function&)</a>; + <a href="class.boost.function.html#id2834383">~function()</a>; + + <span class="emphasis"><em>// <a href="class.boost.function.html#id2821009">modifiers</a></em></span> + <a href="class.boost.function.html#id2821015"><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> function&)</a>; + <a href="class.boost.function.html#id2821057"><span class="bold"><b>void</b></span> clear()</a>; + + <span class="emphasis"><em>// <a href="class.boost.function.html#id2821084">capacity</a></em></span> + <a href="class.boost.function.html#id2833437"><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span></a>; + <a href="class.boost.function.html#id2833472"><span class="bold"><b>operator</b></span> safe_bool() <span class="bold"><b>const</b></span></a>; + <a href="class.boost.function.html#id2833516"><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>!() <span class="bold"><b>const</b></span></a>; + + <span class="emphasis"><em>// <a href="class.boost.function.html#id2833546">invocation</a></em></span> + <a href="class.boost.function.html#id2833552">result_type <span class="bold"><b>operator</b></span>()(arg1_type, arg2_type, ..., argN_type) <span class="bold"><b>const</b></span></a>; +}; + +<span class="emphasis"><em>// <a href="class.boost.function.html#id2700310">specialized algorithms</a></em></span> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2700316">swap</a>(<a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>&, <a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>&); + +<span class="emphasis"><em>// <a href="class.boost.function.html#id2747987">undefined operators</a></em></span> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2747993"><span class="bold"><b>operator</b></span>==</a>(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>&); +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2748081"><span class="bold"><b>operator</b></span>!=</a>(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>&);</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p> + Class template <a href="class.boost.function.html" title="Class template function">function</a> is a thin wrapper + around the numbered class templates <a href="class.boost.functionN.html" title="Class template functionN">function0</a>, <a href="class.boost.functionN.html" title="Class template functionN">function1</a>, etc. It accepts a + function type with N arguments and will will derive from + <a href="class.boost.functionN.html" title="Class template functionN">functionN</a> instantiated with the arguments it receives. + + The semantics of all operations in class template + <a href="class.boost.function.html" title="Class template function">function</a> are equivalent to that of the underlying + <a href="class.boost.functionN.html" title="Class template functionN">functionN</a> object, although additional member + functions are required to allow proper copy construction and + copy assignment of function objects. + </p><div class="refsect2" lang="en"><h3><a name="id2747518construct-copy-destruct"></a><tt class="computeroutput">function</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2821169"></a>function();</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.function.html#id2833437">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2821190"></a>function(<span class="bold"><b>const</b></span> functionN& f);</pre><p><b><span class="term">Postconditions</span></b>: + Contains a copy of the <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.function.html#id2833437">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw unless copying the target of <tt class="computeroutput">f</tt> throws.</p></li><li><pre class="literallayout"><a name="id2821239"></a>function(<span class="bold"><b>const</b></span> function& f);</pre><p><b><span class="term">Postconditions</span></b>: + Contains a copy of the <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.function.html#id2833437">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw unless copying the target of <tt class="computeroutput">f</tt> throws.</p></li><li><pre class="literallayout"><a name="id2821288"></a><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> F> function(F f);</pre><p><b><span class="term">Requires</span></b>: + F is a function object Callable from <tt class="computeroutput">this</tt>.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">*this</tt> targets a copy of <tt class="computeroutput">f</tt> if <tt class="computeroutput">f</tt> is nonempty, or <tt class="computeroutput">this-><a href="class.boost.function.html#id2833437">empty</a>()</tt> if <tt class="computeroutput">f</tt> is empty.<br><b><span class="term">Throws</span></b>: + Will not throw when <tt class="computeroutput">f</tt> is a stateless function object.</p></li><li><pre class="literallayout"><a name="id2834405"></a>function& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> functionN& f);</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">*this</tt> targets a copy of <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.function.html#id2833437">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw when the target of <tt class="computeroutput">f</tt> is a stateless function object or a reference to the function object.</p></li><li><pre class="literallayout"><a name="id2820958"></a>function& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> function& f);</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">*this</tt> targets a copy of <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.function.html#id2833437">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw when the target of <tt class="computeroutput">f</tt> is a stateless function object or a reference to the function object.</p></li><li><pre class="literallayout"><a name="id2834383"></a>~function();</pre><p><b><span class="term">Effects</span></b>: + If <tt class="computeroutput">!this-><a href="class.boost.function.html#id2833437">empty</a>()</tt>, destroys the target of <tt class="computeroutput">this</tt>.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2821009"></a><tt class="computeroutput">function</tt> modifiers</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2821015"></a><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> function& f);</pre><p><b><span class="term">Effects</span></b>: + Interchanges the targets of <tt class="computeroutput">*this</tt> and <tt class="computeroutput">f</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2821057"></a><span class="bold"><b>void</b></span> clear();</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.function.html#id2833437">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2821084"></a><tt class="computeroutput">function</tt> capacity</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2833437"></a><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if <tt class="computeroutput">this</tt> has a target, and <tt class="computeroutput">false</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2833472"></a><span class="bold"><b>operator</b></span> safe_bool() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + A <tt class="computeroutput">safe_bool</tt> that evaluates <tt class="computeroutput">false</tt> in a boolean context when <tt class="computeroutput">this-><a href="class.boost.function.html#id2833437">empty</a>()</tt>, and <tt class="computeroutput">true</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2833516"></a><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>!() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">this-><a href="class.boost.function.html#id2833437">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2833546"></a><tt class="computeroutput">function</tt> invocation</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2833552"></a>result_type <span class="bold"><b>operator</b></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">f(a1, a2, ..., aN)</tt>, where <tt class="computeroutput">f</tt> is the target of <tt class="computeroutput">*this</tt>.<br><b><span class="term">Returns</span></b>: + if <tt class="computeroutput">R</tt> is <tt class="computeroutput">void</tt>, nothing is returned; otherwise, the return value of the call to <tt class="computeroutput">f</tt> is returned.<br><b><span class="term">Throws</span></b>: + <tt class="computeroutput"><a href="id2837192.html" title="Class bad_function_call">bad_function_call</a></tt> if <tt class="computeroutput">!this-><a href="class.boost.function.html#id2833437">empty</a>()</tt>. Otherwise, may through any exception thrown by the target function <tt class="computeroutput">f</tt>.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2700310"></a><tt class="computeroutput">function</tt> specialized algorithms</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a name="id2700316"></a>swap(<a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>& f1, + <a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>& f2);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">f1.<a href="class.boost.function.html#id2821015">swap</a>(f2)</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2747987"></a><tt class="computeroutput">function</tt> undefined operators</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a name="id2747993"></a><span class="bold"><b>operator</b></span>==(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>& f1, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>& f2);</pre><p><b><span class="term">Notes</span></b>: + This function must be left undefined.<br><b><span class="term">Rationale</span></b>: + The <tt class="computeroutput">safe_bool</tt> conversion opens a loophole whereby two function instances can be compared via <tt class="computeroutput">==</tt>. This undefined <tt class="computeroutput">void operator ==</tt> closes the loophole and ensures a compile-time or link-time error.</p></li><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a name="id2748081"></a><span class="bold"><b>operator</b></span>!=(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>& f1, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>& f2);</pre><p><b><span class="term">Notes</span></b>: + This function must be left undefined.<br><b><span class="term">Rationale</span></b>: + The <tt class="computeroutput">safe_bool</tt> conversion opens a loophole whereby two function instances can be compared via <tt class="computeroutput">!=</tt>. This undefined <tt class="computeroutput">void operator !=</tt> closes the loophole and ensures a compile-time or link-time error.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.functionN.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.reference.html#header.boost.function.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.faq.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template functionN </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Frequently Asked Questions</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.functionN.html b/doc/html/class.boost.functionN.html new file mode 100644 index 0000000000..b8efaa059a --- /dev/null +++ b/doc/html/class.boost.functionN.html @@ -0,0 +1,99 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template functionN</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.reference.html#header.boost.function.hpp" title="Header <boost/function.hpp>"><link rel="previous" href="class.boost.function_base.html" title="Class function_base"><link rel="next" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.functionN.html#id2882120" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.functionN"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template functionN</span></h2><p>boost::functionN — A set of generalized function pointers that can be used for callbacks or wrapping function objects.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> R, <span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, + <span class="bold"><b>typename</b></span> Allocator = std::allocator<void> > +<span class="bold"><b>class</b></span> functionN : <span class="bold"><b>public</b></span> <a href="class.boost.function_base.html" title="Class function_base">function_base</a> { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> R result_type; + <span class="bold"><b>typedef</b></span> Allocator allocator_type; + <span class="bold"><b>typedef</b></span> T1 argument_type; <span class="emphasis"><em>// If N == 1</em></span> + <span class="bold"><b>typedef</b></span> T1 first_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T2 second_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T1 arg1_type; + <span class="bold"><b>typedef</b></span> T2 arg2_type; + . + . + . + <span class="bold"><b>typedef</b></span> TN argN_type; + + <span class="emphasis"><em>// static constants</em></span> + <span class="bold"><b>static</b></span> <span class="bold"><b>const</b></span> <span class="bold"><b>int</b></span> arity = N; + + <span class="emphasis"><em>// <a href="class.boost.functionN.html#id2720100construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.functionN.html#id2746690">functionN()</a>; + <a href="class.boost.functionN.html#id2699960">functionN(<span class="bold"><b>const</b></span> functionN&)</a>; + <a href="class.boost.functionN.html#id2832222"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> F> functionN(F)</a>; + <a href="class.boost.functionN.html#id2832562">functionN& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> functionN&)</a>; + <a href="class.boost.functionN.html#id2832544">~functionN()</a>; + + <span class="emphasis"><em>// <a href="class.boost.functionN.html#id2826241">modifiers</a></em></span> + <a href="class.boost.functionN.html#id2826247"><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> functionN&)</a>; + <a href="class.boost.functionN.html#id2728923"><span class="bold"><b>void</b></span> clear()</a>; + + <span class="emphasis"><em>// <a href="class.boost.functionN.html#id2728950">capacity</a></em></span> + <a href="class.boost.functionN.html#id2728955"><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span></a>; + <a href="class.boost.functionN.html#id2765962"><span class="bold"><b>operator</b></span> safe_bool() <span class="bold"><b>const</b></span></a>; + <a href="class.boost.functionN.html#id2766007"><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>!() <span class="bold"><b>const</b></span></a>; + + <span class="emphasis"><em>// <a href="class.boost.functionN.html#id2805174">invocation</a></em></span> + <a href="class.boost.functionN.html#id2805179">result_type <span class="bold"><b>operator</b></span>()(arg1_type, arg2_type, ..., argN_type) <span class="bold"><b>const</b></span></a>; +}; + +<span class="emphasis"><em>// <a href="class.boost.functionN.html#id2837093">specialized algorithms</a></em></span> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2837098">swap</a>(<a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>&, + <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>&); + +<span class="emphasis"><em>// <a href="class.boost.functionN.html#id2818156">undefined operators</a></em></span> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2818162"><span class="bold"><b>operator</b></span>==</a>(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>&); +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2822734"><span class="bold"><b>operator</b></span>!=</a>(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>&);</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p> + Class template <a href="class.boost.functionN.html" title="Class template functionN">functionN</a> is actually a + family of related classes <a href="class.boost.functionN.html" title="Class template functionN">function0</a>, + <a href="class.boost.functionN.html" title="Class template functionN">function1</a>, etc., up to some + implementation-defined maximum. In this context, + <tt class="computeroutput">N</tt> refers to the number of + parameters. + </p><div class="refsect2" lang="en"><h3><a name="id2720100construct-copy-destruct"></a><tt class="computeroutput">functionN</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2746690"></a>functionN();</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2699960"></a>functionN(<span class="bold"><b>const</b></span> functionN& f);</pre><p><b><span class="term">Postconditions</span></b>: + Contains a copy of the <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.functionN.html#id2728955">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw unless copying the target of <tt class="computeroutput">f</tt> throws.</p></li><li><pre class="literallayout"><a name="id2832222"></a><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> F> functionN(F f);</pre><p><b><span class="term">Requires</span></b>: + F is a function object Callable from <tt class="computeroutput">this</tt>.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">*this</tt> targets a copy of <tt class="computeroutput">f</tt> if <tt class="computeroutput">f</tt> is nonempty, or <tt class="computeroutput">this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt> if <tt class="computeroutput">f</tt> is empty.<br><b><span class="term">Throws</span></b>: + Will not throw when <tt class="computeroutput">f</tt> is a stateless function object.</p></li><li><pre class="literallayout"><a name="id2832562"></a>functionN& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> functionN& f);</pre><p><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">*this</tt> targets a copy of <tt class="computeroutput">f</tt>'s target, if it has one, or is empty if <tt class="computeroutput">f.<a href="class.boost.functionN.html#id2728955">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw when the target of <tt class="computeroutput">f</tt> is a stateless function object or a reference to the function object.</p></li><li><pre class="literallayout"><a name="id2832544"></a>~functionN();</pre><p><b><span class="term">Effects</span></b>: + If <tt class="computeroutput">!this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt>, destroys the target of this.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2826241"></a><tt class="computeroutput">functionN</tt> modifiers</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2826247"></a><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> functionN& f);</pre><p><b><span class="term">Effects</span></b>: + Interchanges the targets of <tt class="computeroutput">*this</tt> and <tt class="computeroutput">f</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2728923"></a><span class="bold"><b>void</b></span> clear();</pre><p><b><span class="term">Postconditions</span></b>: + this-><a href="class.boost.functionN.html#id2728955">empty</a>()<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2728950"></a><tt class="computeroutput">functionN</tt> capacity</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2728955"></a><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if <tt class="computeroutput">this</tt> has a target, and <tt class="computeroutput">false</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2765962"></a><span class="bold"><b>operator</b></span> safe_bool() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + A <tt class="computeroutput">safe_bool</tt> that evaluates <tt class="computeroutput">false</tt> in a boolean context when <tt class="computeroutput">this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt>, and <tt class="computeroutput">true</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2766007"></a><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>!() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2805174"></a><tt class="computeroutput">functionN</tt> invocation</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2805179"></a>result_type <span class="bold"><b>operator</b></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">f(a1, a2, ..., aN)</tt>, where <tt class="computeroutput">f</tt> is the target of <tt class="computeroutput">*this</tt>.<br><b><span class="term">Returns</span></b>: + if <tt class="computeroutput">R</tt> is <tt class="computeroutput">void</tt>, nothing is returned; otherwise, the return value of the call to <tt class="computeroutput">f</tt> is returned.<br><b><span class="term">Throws</span></b>: + <tt class="computeroutput"><a href="id2837192.html" title="Class bad_function_call">bad_function_call</a></tt> if <tt class="computeroutput">!this-><a href="class.boost.functionN.html#id2728955">empty</a>()</tt>. Otherwise, may through any exception thrown by the target function <tt class="computeroutput">f</tt>.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2837093"></a><tt class="computeroutput">functionN</tt> specialized algorithms</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a name="id2837098"></a>swap(<a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>& f1, + <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>& f2);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">f1.<a href="class.boost.functionN.html#id2826247">swap</a>(f2)</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2818156"></a><tt class="computeroutput">functionN</tt> undefined operators</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a name="id2818162"></a><span class="bold"><b>operator</b></span>==(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>& f1, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>& f2);</pre><p><b><span class="term">Notes</span></b>: + This function must be left undefined.<br><b><span class="term">Rationale</span></b>: + The <tt class="computeroutput">safe_bool</tt> conversion opens a loophole whereby two function instances can be compared via <tt class="computeroutput">==</tt>. This undefined <tt class="computeroutput">void operator ==</tt> closes the loophole and ensures a compile-time or link-time error.</p></li><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a name="id2822734"></a><span class="bold"><b>operator</b></span>!=(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>& f1, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>& f2);</pre><p><b><span class="term">Notes</span></b>: + This function must be left undefined.<br><b><span class="term">Rationale</span></b>: + The <tt class="computeroutput">safe_bool</tt> conversion opens a loophole whereby two function instances can be compared via <tt class="computeroutput">!=</tt>. This undefined <tt class="computeroutput">void operator !=</tt> closes the loophole and ensures a compile-time or link-time error.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.function_base.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.reference.html#header.boost.function.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.function.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class function_base </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template function</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.function_base.html b/doc/html/class.boost.function_base.html new file mode 100644 index 0000000000..f18261a82f --- /dev/null +++ b/doc/html/class.boost.function_base.html @@ -0,0 +1,12 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class function_base</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.reference.html#header.boost.function.hpp" title="Header <boost/function.hpp>"><link rel="previous" href="id2837192.html" title="Class bad_function_call"><link rel="next" href="class.boost.functionN.html" title="Class template functionN"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.function_base.html#id2881255" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.function_base"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class function_base</span></h2><p>boost::function_base — The common base class for all Boost.Function + objects. Objects of type function_base may not be created + directly.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> function_base { +<span class="bold"><b>public</b></span>: + + <span class="emphasis"><em>// <a href="class.boost.function_base.html#id2747963">capacity</a></em></span> + <a href="class.boost.function_base.html#id2720063"><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span></a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2747963"></a><tt class="computeroutput">function_base</tt> capacity</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2720063"></a><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if <tt class="computeroutput">this</tt> has a target, and <tt class="computeroutput">false</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2837192.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.reference.html#header.boost.function.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.functionN.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class bad_function_call </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template functionN</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.last_value.html b/doc/html/class.boost.last_value.html new file mode 100644 index 0000000000..7caae9fd61 --- /dev/null +++ b/doc/html/class.boost.last_value.html @@ -0,0 +1,16 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template last_value</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2875832" title="Header <boost/last_value.hpp>"><link rel="previous" href="id2905241.html" title="Function template visit_each"><link rel="next" href="id2830650.html" title="Class last_value<void>"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.last_value.html#id2895295" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.last_value"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template last_value</span></h2><p>boost::last_value — Evaluate an InputIterator sequence and return the + last value in the sequence.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> +<span class="bold"><b>class</b></span> last_value { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> T result_type; + + <span class="emphasis"><em>// <a href="class.boost.last_value.html#id2900055">invocation</a></em></span> + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> InputIterator> + result_type <a href="class.boost.last_value.html#id2897944"><span class="bold"><b>operator</b></span>()</a>(InputIterator, InputIterator) <span class="bold"><b>const</b></span>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2900055"></a><tt class="computeroutput">last_value</tt> invocation</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> InputIterator> + result_type <a name="id2897944"></a><span class="bold"><b>operator</b></span>()(InputIterator first, InputIterator last) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Requires</span></b>: + <tt class="computeroutput">first != last</tt><br><b><span class="term">Effects</span></b>: + Dereferences every iterator in the sequence <tt class="computeroutput">[first, last)</tt>.<br><b><span class="term">Returns</span></b>: + The result of dereferencing the iterator <tt class="computeroutput">last-1</tt>.</p></li></ol></div></div><div class="refsect2" lang="en"><h3>Specializations</h3><div class="itemizedlist"><ul type="disc"><li><p><a href="id2830650.html" title="Class last_value<void>">Class last_value<void></a></p></li></ul></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2905241.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2875832"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2830650.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Function template visit_each </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class last_value<void></td></tr></table></div></body></html> diff --git a/doc/html/class.boost.signal.html b/doc/html/class.boost.signal.html new file mode 100644 index 0000000000..670f14dcaf --- /dev/null +++ b/doc/html/class.boost.signal.html @@ -0,0 +1,21 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template signal</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#header.boost.signal.hpp" title="Header <boost/signal.hpp>"><link rel="previous" href="class.boost.signalN.html" title="Class template signalN"><link rel="next" href="class.boost.slot.html" title="Class template slot"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.signal.html#id2892409" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.signal"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template signal</span></h2><p>boost::signal — Safe multicast callback.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="emphasis"><em> // Function type R (T1, T2, ..., TN)</em></span> + <span class="bold"><b>typename</b></span> Allocator = std::allocator<void>, + <span class="bold"><b>typename</b></span> Combiner = <a href="class.boost.last_value.html" title="Class template last_value">last_value</a><R>, + <span class="bold"><b>typename</b></span> Group = int, + <span class="bold"><b>typename</b></span> GroupCompare = std::less<Group>, + <span class="bold"><b>typename</b></span> SlotFunction = <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><Signature> > +<span class="bold"><b>class</b></span> signal : <span class="bold"><b>public</b></span> <a href="class.boost.signalN.html" title="Class template signalN">signalN</a><R, T1, T2, ..., TN, Combiner, Group, GroupCompare, SlotFunction> { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="class.boost.signal.html#id2876506construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.signal.html#id2876702">signal</a>(<span class="bold"><b>const</b></span> combiner_type& = combiner_type(), + <span class="bold"><b>const</b></span> group_compare_type& = group_compare_type()); +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>Class template <a href="class.boost.signal.html" title="Class template signal">signal</a> is a thin + wrapper around the numbered class templates <a href="class.boost.signalN.html" title="Class template signalN">signal0</a>, <a href="class.boost.signalN.html" title="Class template signalN">signal1</a>, etc. It accepts a function + type with N arguments instead of N separate arguments, and + derives from the appropriate <a href="class.boost.signalN.html" title="Class template signalN">signalN</a> + instantiation.</p><p>All functionality of this class template is in its base + class <a href="class.boost.signalN.html" title="Class template signalN">signalN</a>.</p><div class="refsect2" lang="en"><h3><a name="id2876506construct-copy-destruct"></a><tt class="computeroutput">signal</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2876702"></a>signal(<span class="bold"><b>const</b></span> combiner_type& combiner = combiner_type(), + <span class="bold"><b>const</b></span> group_compare_type& compare = group_compare_type());</pre><p><b><span class="term">Effects</span></b>: + Initializes the base class with the given combiner + and comparison objects.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.signalN.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#header.boost.signal.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.slot.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template signalN </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template slot</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.signalN.html b/doc/html/class.boost.signalN.html new file mode 100644 index 0000000000..7dc2215086 --- /dev/null +++ b/doc/html/class.boost.signalN.html @@ -0,0 +1,134 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template signalN</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#header.boost.signal.hpp" title="Header <boost/signal.hpp>"><link rel="previous" href="signals.reference.html" title="Reference"><link rel="next" href="class.boost.signal.html" title="Class template signal"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.signalN.html#id2891517" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.signalN"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template signalN</span></h2><p>boost::signalN — Set of safe multicast callback types.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> R, <span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, + <span class="bold"><b>typename</b></span> Combiner = <a href="class.boost.last_value.html" title="Class template last_value">last_value</a><R>, <span class="bold"><b>typename</b></span> Group = int, + <span class="bold"><b>typename</b></span> GroupCompare = std::less<Group>, + <span class="bold"><b>typename</b></span> SlotFunction = <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><R, T1, T2, ..., TN> > +<span class="bold"><b>class</b></span> signalN : <span class="bold"><b>public</b></span> <a href="id2852290.html" title="Class trackable">signals::trackable</a>, <span class="bold"><b>private</b></span> noncopyable { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> typename Combiner::result_type result_type; + <span class="bold"><b>typedef</b></span> Combiner combiner_type; + <span class="bold"><b>typedef</b></span> Group group_type; + <span class="bold"><b>typedef</b></span> GroupCompare group_compare_type; + <span class="bold"><b>typedef</b></span> SlotFunction slot_function_type; + <span class="bold"><b>typedef</b></span> <a href="class.boost.slot.html" title="Class template slot">slot</a><SlotFunction> slot_type; + <span class="bold"><b>typedef</b></span> unspecified slot_result_type; + <span class="bold"><b>typedef</b></span> unspecified slot_call_iterator; + <span class="bold"><b>typedef</b></span> T1 argument_type; <span class="emphasis"><em>// If N == 1</em></span> + <span class="bold"><b>typedef</b></span> T1 first_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T2 second_argument_type; <span class="emphasis"><em>// If N == 2</em></span> + <span class="bold"><b>typedef</b></span> T1 arg1_type; + <span class="bold"><b>typedef</b></span> T2 arg2_type; + . + . + . + <span class="bold"><b>typedef</b></span> TN argN_type; + + <span class="emphasis"><em>// static constants</em></span> + <span class="bold"><b>static</b></span> <span class="bold"><b>const</b></span> <span class="bold"><b>int</b></span> arity = N; + + <span class="emphasis"><em>// <a href="class.boost.signalN.html#id2855793construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.signalN.html#id2875800">signalN</a>(<span class="bold"><b>const</b></span> combiner_type& = combiner_type(), + <span class="bold"><b>const</b></span> group_compare_type& = group_compare_type()); + <a href="class.boost.signalN.html#id2851500">~signalN()</a>; + + <span class="emphasis"><em>// <a href="class.boost.signalN.html#id2841740">connection management</a></em></span> + <a href="class.boost.signalN.html#id2870792">signals::connection connect(<span class="bold"><b>const</b></span> slot_type&)</a>; + <a href="class.boost.signalN.html#id2885476">signals::connection connect(<span class="bold"><b>const</b></span> group_type&, <span class="bold"><b>const</b></span> slot_type&)</a>; + <a href="class.boost.signalN.html#id2846925"><span class="bold"><b>void</b></span> disconnect(<span class="bold"><b>const</b></span> group_type&)</a>; + <a href="class.boost.signalN.html#id2859894"><span class="bold"><b>void</b></span> disconnect_all_slots()</a>; + <a href="class.boost.signalN.html#id2881781"><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span></a>; + + <span class="emphasis"><em>// <a href="class.boost.signalN.html#id2853108">invocation</a></em></span> + <a href="class.boost.signalN.html#id2867592">result_type <span class="bold"><b>operator</b></span>()(arg1_type, arg2_type, ..., argN_type)</a>; + <a href="class.boost.signalN.html#id2841874">result_type <span class="bold"><b>operator</b></span>()(arg1_type, arg2_type, ..., argN_type) <span class="bold"><b>const</b></span></a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p> + The class template <a href="class.boost.signalN.html" title="Class template signalN">signalN</a> covers + several related classes signal0, signal1, signal2, etc., + where the number suffix describes the number of function + parameters the signal and its connected slots will + take. Instead of enumerating all classes, a single pattern + <a href="class.boost.signalN.html" title="Class template signalN">signalN</a> will be described, where N + represents the number of function parameters. + </p><div class="refsect2" lang="en"><h3><a name="id2855793construct-copy-destruct"></a><tt class="computeroutput">signalN</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2875800"></a>signalN(<span class="bold"><b>const</b></span> combiner_type& combiner = combiner_type(), + <span class="bold"><b>const</b></span> group_compare_type& compare = group_compare_type());</pre><p><b><span class="term">Effects</span></b>: + Initializes the signal to contain no slots, copies the given combiner into internal storage, and stores the given group comparison function object to compare groups.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.signalN.html#id2881781">empty</a>()</tt></p></li><li><pre class="literallayout"><a name="id2851500"></a>~signalN();</pre><p><b><span class="term">Effects</span></b>: + Disconnects all slots connected to <tt class="computeroutput">*this</tt>.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2841740"></a><tt class="computeroutput">signalN</tt> connection management</h3><div class="orderedlist"><ol type="1"><li><p><a name="id2841744"></a></p><pre class="literallayout"><a name="id2870792"></a>signals::connection connect(<span class="bold"><b>const</b></span> slot_type& slot); +<a name="id2885476"></a>signals::connection connect(<span class="bold"><b>const</b></span> group_type& group, <span class="bold"><b>const</b></span> slot_type& slot);</pre><p><b><span class="term">Effects</span></b>: + Connects the signal this to the incoming slot. If + the slot is inactive, i.e., any of the trackable objects + bound by the slot call have been destroyed, then the call to + connect is a no-op. If the second version of + <tt class="computeroutput">connect</tt> is invoked, the + slot is associated with the given group.<br><b><span class="term">Returns</span></b>: + A + <tt class="computeroutput"><a href="id2890015.html" title="Class connection">signals::connection</a></tt> + object that references the newly-created connection between + the signal and the slot; if the slot is inactive, returns a + disconnected connection.<br><b><span class="term">Throws</span></b>: + This routine meets the strong exception guarantee, + where any exception thrown will cause the slot to not be + connected to the signal.<br><b><span class="term">Complexity</span></b>: + O(lg n) where n is the number of + slots known to the signal.<br><b><span class="term">Notes</span></b>: + It is unspecified whether connecting a slot while the + signal is calling will result in the slot being called + immediately.</p></li><li><pre class="literallayout"><a name="id2846925"></a><span class="bold"><b>void</b></span> disconnect(<span class="bold"><b>const</b></span> group_type& group);</pre><p><b><span class="term">Effects</span></b>: + Any slots in the given group are disconnected.<br><b><span class="term">Throws</span></b>: + Will not throw unless a user destructor throws. If a + user destructor throws, not all slots in this group may be + disconnected.<br><b><span class="term">Complexity</span></b>: + O(lg n) + k where n is the number of slots known + to the signal and k is the number of slots in the + group.</p></li><li><pre class="literallayout"><a name="id2859894"></a><span class="bold"><b>void</b></span> disconnect_all_slots();</pre><p><b><span class="term">Effects</span></b>: + Disconnects all slots connected to the signal.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">this-><a href="class.boost.signalN.html#id2881781">empty</a>()</tt>.<br><b><span class="term">Throws</span></b>: + If disconnecting a slot causes an exception to be + thrown, not all slots may be disconnected.<br><b><span class="term">Complexity</span></b>: + Linear in the number of slots known to the + signal.<br><b><span class="term">Notes</span></b>: + May be called at any time within the lifetime of the + signal, including during calls to the signal's slots.</p></li><li><pre class="literallayout"><a name="id2881781"></a><span class="bold"><b>bool</b></span> empty() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if no slots + are connected to the signal, and + <tt class="computeroutput">false</tt> otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.<br><b><span class="term">Complexity</span></b>: + Linear in the number of slots known to the + signal.<br><b><span class="term">Rationale</span></b>: + Slots can disconnect at any point in time, + including while those same slots are being invoked. It is + therefore possible that the implementation must search + through a list of disconnected slots to determine if any + slots are still connected.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2853108"></a><tt class="computeroutput">signalN</tt> invocation</h3><div class="orderedlist"><ol type="1"><li><p><a name="id2867587"></a></p><pre class="literallayout"><a name="id2867592"></a>result_type <span class="bold"><b>operator</b></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN); +<a name="id2841874"></a>result_type <span class="bold"><b>operator</b></span>()(arg1_type a1, arg2_type a2, ... , argN_type aN) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + Invokes the combiner with a + <tt class="computeroutput">slot_call_iterator</tt> range + [first, last) corresponding to the sequence of calls to the + slots connected to signal + <tt class="computeroutput">*this</tt>. Dereferencing an + iterator in this range causes a slot call with the given set + of parameters <tt class="computeroutput">(a1, a2, ..., + aN)</tt>, the result of which is returned from + the iterator dereference operation.<br><b><span class="term">Returns</span></b>: + The result returned by the combiner.<br><b><span class="term">Throws</span></b>: + If an exception is thrown by a slot call, or if the + combiner does not dereference any slot past some given slot, + all slots after that slot in the internal list of connected + slots will not be invoked.<br><b><span class="term">Notes</span></b>: + <p>Only the slots associated with iterators that are + actually dereferenced will be invoked. Multiple dereferences + of the same iterator will not result in multiple slot + invocations, because the return value of the slot will be + cached.</p><p>The <tt class="computeroutput">const</tt> version of + the function call operator will invoke the combiner as + <tt class="computeroutput">const</tt>, whereas the + non-<tt class="computeroutput">const</tt> version will + invoke the combiner as + non-<tt class="computeroutput">const</tt>.</p><p>Ordering between members of a given group or between + ungrouped slots is unspecified.</p><p>Calling the function call operator may invoke undefined + behavior if no slots are connected to the signal, depending + on the combiner used. The default combiner is well-defined + for zero slots when the return type is void but is undefined + when the return type is any other type (because there is no + way to synthesize a return value).</p></p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="signals.reference.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#header.boost.signal.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.signal.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Reference </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template signal</td></tr></table></div></body></html> diff --git a/doc/html/class.boost.slot.html b/doc/html/class.boost.slot.html new file mode 100644 index 0000000000..6bcdae5135 --- /dev/null +++ b/doc/html/class.boost.slot.html @@ -0,0 +1,17 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template slot</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2895664" title="Header <boost/signals/slot.hpp>"><link rel="previous" href="class.boost.signal.html" title="Class template signal"><link rel="next" href="id2852290.html" title="Class trackable"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="class.boost.slot.html#id2892680" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="class.boost.slot"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template slot</span></h2><p>boost::slot — Pass slots as function arguments.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> SlotFunction> +<span class="bold"><b>class</b></span> slot { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="class.boost.slot.html#id2871631construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="class.boost.slot.html#id2860043"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Slot> slot(Slot)</a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2871631construct-copy-destruct"></a><tt class="computeroutput">slot</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2860043"></a><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Slot> slot(Slot target);</pre><p><b><span class="term">Effects</span></b>: + <p>Invokes + <tt class="computeroutput"><a href="id2905241.html" title="Function template visit_each">visit_each</a></tt> + (unqualified) to discover pointers and references to + <tt class="computeroutput"><a href="id2852290.html" title="Class trackable">signals::trackable</a></tt> + objects in <tt class="computeroutput">target</tt>.</p><p>Initializes <tt class="computeroutput">this</tt> to + contain the incoming slot + <tt class="computeroutput">target</tt>, which may be any + function object with which a + <tt class="computeroutput">SlotFunction</tt> can be + constructed.</p></p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.signal.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2895664"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2852290.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template signal </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class trackable</td></tr></table></div></body></html> diff --git a/doc/html/function.faq.html b/doc/html/function.faq.html new file mode 100644 index 0000000000..f95d42ea6c --- /dev/null +++ b/doc/html/function.faq.html @@ -0,0 +1,24 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Frequently Asked Questions</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="class.boost.function.html" title="Class template function"><link rel="next" href="function.misc.html" title="Miscellaneous Notes"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.faq"></a>Frequently Asked Questions</h2></div></div><div></div></div><div class="qandaset"><dl><dt>1. <a href="function.faq.html#id2885834">I see void pointers; is this [mess] type safe?</a></dt><dt>2. <a href="function.faq.html#id2885869">Why are there workarounds for void returns? C++ allows them!</a></dt><dt>3. <a href="function.faq.html#id2885932">Why (function) cloning?</a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id2885834"></a><a name="id2885837"></a><b>1. </b></td><td align="left" valign="top"><p>I see void pointers; is this [mess] type safe?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>Yes, <tt class="computeroutput">boost::function</tt> is type +safe even though it uses void pointers and pointers to functions +returning void and taking no arguments. Essentially, all type +information is encoded in the functions that manage and invoke +function pointers and function objects. Only these functions are +instantiated with the exact type that is pointed to by the void +pointer or pointer to void function. The reason that both are required +is that one may cast between void pointers and object pointers safely +or between different types of function pointers (provided you don't +invoke a function pointer with the wrong type). </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2885869"></a><a name="id2885871"></a><b>2. </b></td><td align="left" valign="top"><p>Why are there workarounds for void returns? C++ allows them!</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>Void returns are permitted by the C++ standard, as in this code snippet: +</p><pre class="programlisting">void f(); +void g() { return f(); }</pre><p> + </p><p> This is a valid usage of <tt class="computeroutput">boost::function</tt> because void returns are not used. With void returns, we would attempting to compile ill-formed code similar to: +</p><pre class="programlisting">int f(); +void g() { return f(); }</pre><p> +</p><p> In essence, not using void returns allows +<tt class="computeroutput">boost::function</tt> to swallow a return value. This is +consistent with allowing the user to assign and invoke functions and +function objects with parameters that don't exactly match.</p></td></tr><tr class="question"><td align="left" valign="top"><a name="id2885932"></a><a name="id2885934"></a><b>3. </b></td><td align="left" valign="top"><p>Why (function) cloning?</p></td></tr><tr class="answer"><td align="left" valign="top"><b></b></td><td align="left" valign="top"><p>In November and December of 2000, the issue of cloning + vs. reference counting was debated at length and it was decided + that cloning gave more predictable semantics. I won't rehash the + discussion here, but if it cloning is incorrect for a particular + application a reference-counting allocator could be used.</p></td></tr></tbody></table></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.function.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.misc.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template function </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Miscellaneous Notes</td></tr></table></div></body></html> diff --git a/doc/html/function.history.html b/doc/html/function.history.html new file mode 100644 index 0000000000..5ec0055b44 --- /dev/null +++ b/doc/html/function.history.html @@ -0,0 +1,52 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>History & Compatibility Notes</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="function.html" title="Boost.Function"><link rel="next" href="function.tutorial.html" title="Tutorial"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.history"></a>History & Compatibility Notes</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc" compact><li><p><span class="bold"><b>Version 1.30.0</b></span>: </p><div class="itemizedlist"><ul type="circle" compact><li><p>All features deprecated in version 1.29.0 have + been removed from Boost.Function.</p></li><li><p><tt class="computeroutput"><a href="class.boost.function.html" title="Class template function">boost::function</a></tt> + and <tt class="computeroutput"><a href="class.boost.functionN.html" title="Class template functionN">boost::functionN</a></tt> objects + can be assigned to 0 (semantically equivalent to calling + <tt class="computeroutput"><a href="class.boost.function.html#id2821057">clear</a>()</tt>) and + compared against 0 (semantically equivalent to calling + <tt class="computeroutput"><a href="class.boost.function.html#id2833437">empty</a>()</tt>).</p></li><li><p>The Boost.Function code is now generated + entirely by the <a href="../../libs/preprocessor/index.html" target="_top">Preprocessor</a> library, + so it is now possible to generate + <tt class="computeroutput"><a href="class.boost.function.html" title="Class template function">boost::function</a></tt> and + <tt class="computeroutput"><a href="class.boost.functionN.html" title="Class template functionN">boost::functionN</a></tt> class + templates for any number of arguments.</p></li><li><p>The + <a href="id2837192.html" title="Class bad_function_call">boost::bad_function_call</a> exception class + was introduced.</p></li></ul></div></li><li><p><span class="bold"><b>Version 1.29.0</b></span>: + Boost.Function has been partially redesigned to minimize the + interface and make it cleaner. Several seldom- or never-used + features of the older Boost.Function have been deprecated and will + be removed in the near future. Here is a list of features that have + been deprecated, the likely impact of the deprecations, and how to + adjust your code: + +</p><div class="itemizedlist"><ul type="circle" compact><li><p>The <tt class="computeroutput">boost::function</tt> class template syntax has + changed. The old syntax, e.g., <tt class="computeroutput">boost::function<int, float, + double, std::string></tt>, has been changed to a more natural + syntax <tt class="computeroutput">boost::function<int (float, double, + std::string)></tt>, where all return and argument types are + encoded in a single function type parameter. Any other template + parameters (e.g., the <tt class="computeroutput">Allocator</tt>) follow this single + parameter.</p><p> The resolution to this change depends on the + abilities of your compiler: if your compiler supports template + partial specialization and can parse function types (most do), modify + your code to use the newer + syntax (preferable) or directly use one of the + <tt class="computeroutput">functionN</tt> classes whose syntax has not + changed. If your compiler does not support template partial + specialization or function types, you must take the latter option and + use the numbered Boost.Function classes. This option merely requires + changing types such as <tt class="computeroutput">boost::function<void, int, int></tt> + to <tt class="computeroutput">boost::function2<void, int, int></tt> (adding the number of + function arguments to the end of the class name).</p><p> Support for the old syntax with the + <tt class="computeroutput">boost::function</tt> class template will persist for a short + while, but will eventually be removed so that we can provide better + error messages and link compatibility. </p></li><li><p>The invocation + policy template parameter (<tt class="computeroutput">Policy</tt>) has been deprecated + and will be removed. There is no direct equivalent to this rarely + used feature.</p></li><li><p>The mixin template parameter + (<tt class="computeroutput">Mixin</tt>) has been deprecated and will be removed. There + is not direct equivalent to this rarely used feature.</p></li><li><p>The + <tt class="computeroutput">set</tt> methods have been deprecated and will be + removed. Use the assignment operator instead.</p></li></ul></div><p> +</p></li></ul></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.tutorial.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Boost.Function </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Tutorial</td></tr></table></div></body></html> diff --git a/doc/html/function.html b/doc/html/function.html new file mode 100644 index 0000000000..4c73014cbf --- /dev/null +++ b/doc/html/function.html @@ -0,0 +1,21 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.Function</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="index.html" title="The Boost C++ Libraries"><link rel="previous" href="ch01s04.html" title="Acknowledgements"><link rel="next" href="function.history.html" title="History & Compatibility Notes"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="function.html#function.intro" title="Introduction"><link rel="section" href="function.history.html" title="History & Compatibility Notes"><link rel="section" href="function.tutorial.html" title="Tutorial"><link rel="section" href="function.reference.html" title="Reference"><link rel="section" href="function.faq.html" title="Frequently Asked Questions"><link rel="section" href="function.misc.html" title="Miscellaneous Notes"><link rel="section" href="function.testsuite.html" title="Testsuite"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="function"></a>Boost.Function</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Douglas</span> <span class="surname">Gregor</span></h3></div></div><div><p class="copyright">Copyright © 2001-2003 Douglas Gregor</p></div><div><div class="legalnotice"><p>Permission to copy, use, sell and distribute this software + is granted provided this copyright notice appears in all copies. + Permission to modify the code and to distribute modified code is + granted provided this copyright notice appears in all copies, and + a notice that the code was modified is included with the copyright + notice. </p><p> This software is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any + purpose. </p></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="function.html#function.intro">Introduction</a></dt><dt><a href="function.history.html">History & Compatibility Notes</a></dt><dt><a href="function.tutorial.html">Tutorial</a></dt><dd><dl><dt><a href="function.tutorial.html#id2879195">Basic Usage</a></dt><dt><a href="function.tutorial.html#id2879609">Free functions</a></dt><dt><a href="function.tutorial.html#id2879654">Member functions</a></dt><dt><a href="function.tutorial.html#id2879906">References to Functions</a></dt></dl></dd><dt><a href="function.reference.html">Reference</a></dt><dd><dl><dt><a href="function.reference.html#function.definitions">Definitions</a></dt><dt><a href="function.reference.html#header.boost.function.hpp">Header <boost/function.hpp></a></dt></dl></dd><dt><a href="function.faq.html">Frequently Asked Questions</a></dt><dt><a href="function.misc.html">Miscellaneous Notes</a></dt><dd><dl><dt><a href="function.misc.html#id2885974">Boost.Function vs. Function Pointers</a></dt><dt><a href="function.misc.html#id2886053">Performance</a></dt><dd><dl><dt><a href="function.misc.html#id2886060">Function object wrapper size</a></dt><dt><a href="function.misc.html#id2886078">Copying efficiency</a></dt><dt><a href="function.misc.html#id2886105">Invocation efficiency</a></dt></dl></dd><dt><a href="function.misc.html#id2886122">Combatting virtual function "bloat"</a></dt><dt><a href="function.misc.html#id2886152">Acknowledgements</a></dt></dl></dd><dt><a href="function.testsuite.html">Testsuite</a></dt><dd><dl><dt><a href="function.testsuite.html#function.testsuite.acceptance">Acceptance tests</a></dt><dt><a href="function.testsuite.html#function.testsuite.negative">Negative tests</a></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.intro"></a>Introduction</h2></div></div><div></div></div><p>The Boost.Function library contains a family of class templates +that are function object wrappers. The notion is similar to a +generalized callback. It shares features with function pointers in +that both define a call interface (e.g., a function taking two integer +arguments and returning a floating-point value) through which some +implementation can be called, and the implementation that is invoked +may change throughout the course of the program.</p><p> Generally, any place in which a function pointer would be used +to defer a call or make a callback, Boost.Function can be used instead +to allow the user greater flexibility in the implementation of the +target. Targets can be any 'compatible' function object (or function +pointer), meaning that the arguments to the interface designated by +Boost.Function can be converted to the arguments of the target +function object.</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small></small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s04.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.history.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Acknowledgements </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> History & Compatibility Notes</td></tr></table></div></body></html> diff --git a/doc/html/function.misc.html b/doc/html/function.misc.html new file mode 100644 index 0000000000..4050114ea2 --- /dev/null +++ b/doc/html/function.misc.html @@ -0,0 +1,13 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Miscellaneous Notes</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="function.faq.html" title="Frequently Asked Questions"><link rel="next" href="function.testsuite.html" title="Testsuite"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="function.misc.html#id2885974" title="Boost.Function vs. Function Pointers"><link rel="subsection" href="function.misc.html#id2886053" title="Performance"><link rel="subsection" href="function.misc.html#id2886122" title="Combatting virtual function "bloat""><link rel="subsection" href="function.misc.html#id2886152" title="Acknowledgements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.misc"></a>Miscellaneous Notes</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2885974"></a>Boost.Function vs. Function Pointers</h3></div></div><div></div></div><p>Boost.Function has several advantages over function pointers, namely: + +</p><div class="itemizedlist"><ul type="disc" compact><li><p>Boost.Function allows arbitrary compatible function objects to be targets (instead of requiring an exact function signature).</p></li><li><p>Boost.Function may be used with argument-binding and other function object construction libraries.</p></li><li><p>Boost.Function has predictible behavior when an empty function object is called. </p></li></ul></div><p> And, of course, function pointers have several advantages over Boost.Function: + +</p><div class="itemizedlist"><ul type="disc" compact><li><p> Function pointers are smaller (the size of one pointer instead of three) </p></li><li><p> Function pointers are faster (Boost.Function may require two calls through function pointers) </p></li><li><p> Function pointers are backward-compatible with C libraries.</p></li><li><p> More readable error messages. </p></li></ul></div><p> +</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2886053"></a>Performance</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2886060"></a>Function object wrapper size</h4></div></div><div></div></div><p> Function object wrappers will be the size of two function pointers plus one function pointer or data pointer (whichever is larger). On common 32-bit platforms, this amounts to 12 bytes per wrapper. Additionally, the function object target will be allocated on the heap.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2886078"></a>Copying efficiency</h4></div></div><div></div></div><p> Copying function object wrappers may require allocating memory for a copy of the function object target. The default allocator may be replaced with a faster custom allocator or one may choose to allow the function object wrappers to only store function object targets by reference (using <tt class="computeroutput">ref</tt>) if the cost of this cloning becomes prohibitive.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2886105"></a>Invocation efficiency</h4></div></div><div></div></div><p> With a properly inlining compiler, an invocation of a function object requires one call through a function pointer. If the call is to a free function pointer, an additional call must be made to that function pointer (unless the compiler has very powerful interprocedural analysis).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2886122"></a>Combatting virtual function "bloat"</h3></div></div><div></div></div><p> The use of virtual functions tends to cause 'code bloat' on many compilers. When a class contains a virtual function, it is necessary to emit an additional function that classifies the type of the object. It has been our experience that these auxiliary functions increase the size of the executable significantly when many <tt class="computeroutput">boost::function</tt> objects are used. </p><p> In Boost.Function, an alternative but equivalent approach was taken using free functions instead of virtual functions. The Boost.Function object essentially holds two pointers to make a valid target call: a void pointer to the function object it contains and a void pointer to an "invoker" that can call the function object, given the function pointer. This invoker function performs the argument and return value conversions Boost.Function provides. A third pointer points to a free function called the "manager", which handles the cloning and destruction of function objects. The scheme is typesafe because the only functions that actually handle the function object, the invoker and the manager, are instantiated given the type of the function object, so they can safely cast the incoming void pointer (the function object pointer) to the appropriate type.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2886152"></a>Acknowledgements</h3></div></div><div></div></div><p> Many people were involved in the construction of this + library. William Kempf, Jesse Jones and Karl Nelson were all + extremely helpful in isolating an interface and scope for the + library. John Maddock managed the formal review, and many + reviewers gave excellent comments on interface, implementation, + and documentation. Peter Dimov led us to the function + declarator-based syntax.</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.faq.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.testsuite.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Frequently Asked Questions </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Testsuite</td></tr></table></div></body></html> diff --git a/doc/html/function.reference.html b/doc/html/function.reference.html new file mode 100644 index 0000000000..2cc87e7a66 --- /dev/null +++ b/doc/html/function.reference.html @@ -0,0 +1,75 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Reference</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="function.tutorial.html" title="Tutorial"><link rel="next" href="id2837192.html" title="Class bad_function_call"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="function.reference.html#function.definitions" title="Definitions"><link rel="subsection" href="function.reference.html#header.boost.function.hpp" title="Header <boost/function.hpp>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.reference"></a>Reference</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="function.definitions"></a>Definitions</h3></div></div><div></div></div><p> + </p><div class="itemizedlist"><ul type="disc"><li><p>A function object <tt class="computeroutput">f</tt> is + <span class="emphasis"><em>compatible</em></span> if for the given set of argument + types <tt class="computeroutput">Arg1</tt>, + <tt class="computeroutput">Arg2</tt>, ..., + <tt class="computeroutput">ArgN</tt> and a + return type <tt class="computeroutput">ResultType</tt>, the + appropriate following function is well-formed: +</p><pre class="programlisting"> + <span class="emphasis"><em>// if ResultType is not <span class="bold"><b>void</b></span></em></span> + ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<span class="emphasis"><em>N</em></span> arg<span class="emphasis"><em>N</em></span>) + { + <span class="bold"><b>return</b></span> f(arg1, arg2, ..., arg<span class="emphasis"><em>N</em></span>); + } + + <span class="emphasis"><em>// if ResultType is <span class="bold"><b>void</b></span></em></span> + ResultType foo(Arg1 arg1, Arg2 arg2, ..., Arg<span class="emphasis"><em>N</em></span> arg<span class="emphasis"><em>N</em></span>) + { + f(arg1, arg2, ..., arg<span class="emphasis"><em>N</em></span>); + } +</pre><p> A special provision is made for pointers to member + functions. Though they are not function objects, Boost.Function + will adapt them internally to function objects. This requires + that a pointer to member function of the form <tt class="computeroutput">R + (X::*mf)(Arg1, Arg2, ..., ArgN) + cv-quals</tt> be adapted to a + function object with the following function call operator + overloads: +</p><pre class="programlisting"> + <span class="bold"><b>template</b></span><<span class="bold"><b>typename P</b></span>> + R <span class="bold"><b>operator</b></span>()(<span class="emphasis"><em>cv-quals</em></span> P& x, Arg1 arg1, Arg2 arg2, ..., Arg<span class="emphasis"><em>N</em></span> arg<span class="emphasis"><em>N</em></span>) <span class="bold"><b>const</b></span> + { + <span class="bold"><b>return</b></span> (*x).*mf(arg1, arg2, ..., arg<span class="emphasis"><em>N</em></span>); + } +</pre><p> +</p></li><li><p>A function object <tt class="computeroutput">f</tt> of + type <tt class="computeroutput">F</tt> is + <span class="emphasis"><em>stateless</em></span> if it is a function pointer or if + <tt class="computeroutput">boost::is_stateless<T></tt> + is true. The construction of or copy to a Boost.Function object + from a stateless function object will not cause exceptions to be + thrown and will not allocate any storage. + </p></li></ul></div><p> +</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="header.boost.function.hpp"></a>Header <<a href="../../boost/function.hpp" target="_top">boost/function.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <a href="id2837192.html" title="Class bad_function_call"><span class="bold"><b>class</b></span> bad_function_call;</a> + <a href="class.boost.function_base.html" title="Class function_base"><span class="bold"><b>class</b></span> function_base;</a> + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> R, <span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, + <span class="bold"><b>typename</b></span> Allocator = std::allocator<void> > + <span class="bold"><b>class</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a>; + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2837098">swap</a>(<a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>&, + <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator>&); + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2818162"><span class="bold"><b>operator</b></span>==</a>(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>&); + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, <span class="bold"><b>typename</b></span> Allocator1, + <span class="bold"><b>typename</b></span> U1, <span class="bold"><b>typename</b></span> U2, ..., <span class="bold"><b>typename</b></span> UN, <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.functionN.html#id2822734"><span class="bold"><b>operator</b></span>!=</a>(<span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><T1, T2, ..., TN, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><U1, U2, ..., UN, Allocator2>&); + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="bold"><b>typename</b></span> Allocator = std::allocator<void> > + <span class="bold"><b>class</b></span> <a href="class.boost.function.html" title="Class template function">function</a>; + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="bold"><b>typename</b></span> Allocator> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2700316">swap</a>(<a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>&, + <a href="class.boost.function.html" title="Class template function">function</a><Signature, Allocator>&); + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2747993"><span class="bold"><b>operator</b></span>==</a>(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>&); + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature1, <span class="bold"><b>typename</b></span> Allocator1, <span class="bold"><b>typename</b></span> Signature2, + <span class="bold"><b>typename</b></span> Allocator2> + <span class="bold"><b>void</b></span> <a href="class.boost.function.html#id2748081"><span class="bold"><b>operator</b></span>!=</a>(<span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature1, Allocator1>&, + <span class="bold"><b>const</b></span> <a href="class.boost.function.html" title="Class template function">function</a><Signature2, Allocator2>&); +}</pre></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.tutorial.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2837192.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Tutorial </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class bad_function_call</td></tr></table></div></body></html> diff --git a/doc/html/function.testsuite.html b/doc/html/function.testsuite.html new file mode 100644 index 0000000000..0d3aabedcc --- /dev/null +++ b/doc/html/function.testsuite.html @@ -0,0 +1,2 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Testsuite</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="function.misc.html" title="Miscellaneous Notes"><link rel="next" href="ref.html" title="Boost.Ref"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="function.testsuite.html#function.testsuite.acceptance" title="Acceptance tests"><link rel="subsection" href="function.testsuite.html#function.testsuite.negative" title="Negative tests"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.testsuite"></a>Testsuite</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="function.testsuite.acceptance"></a>Acceptance tests</h3></div></div><div></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Test</th><th>Type</th><th>Description</th><th>If failing...</th></tr></thead><tbody><tr><td><p><a href="../../libs/function/test/function_test.cpp" target="_top">function_test.cpp</a></p></td><td><p>run</p></td><td><p>Test the capabilities of the <a href="class.boost.function.html" title="Class template function">boost::function</a> class template.</p></td><td><p>The <a href="class.boost.function.html" title="Class template function">boost::function</a> class template may not be usable on your compiler. However, the library may still be usable via the <a href="class.boost.functionN.html" title="Class template functionN">boost::functionN</a> class templates.</p></td></tr><tr><td><p><a href="../../libs/function/test/function_n_test.cpp" target="_top">function_n_test.cpp</a></p></td><td><p>run</p></td><td><p>Test the capabilities of the <a href="class.boost.functionN.html" title="Class template functionN">boost::functionN</a> class templates.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/allocator_test.cpp" target="_top">allocator_test.cpp</a></p></td><td><p>run</p></td><td><p>Test the use of custom allocators.</p></td><td><p>Allocators are ignored by the implementation.</p></td></tr><tr><td><p><a href="../../libs/function/test/stateless_test.cpp" target="_top">stateless_test.cpp</a></p></td><td><p>run</p></td><td><p>Test the optimization of stateless function objects in the Boost.Function library.</p></td><td><p>The exception-safety and performance guarantees given for stateless function objects may not be met by the implementation.</p></td></tr><tr><td><p><a href="../../libs/function/test/lambda_test.cpp" target="_top">lambda_test.cpp</a></p></td><td><p>run</p></td><td><p>Test the interaction between Boost.Function and Boost.Lambda.</p></td><td><p>Either Boost.Lambda does not work on the platform, or Boost.Function cannot safely be applied without the use of boost::unlambda.</p></td></tr><tr><td><p><a href="../../libs/function/test/function_30.cpp" target="_top">function_30.cpp</a></p></td><td><p>compile</p></td><td><p>Test the generation of a Boost.Function function object adaptor accepting 30 arguments.</p></td><td><p>The Boost.Function library may work for function object adaptors of up to 10 parameters, but will be unable to generate adaptors for an arbitrary number of parameters. Failure often indicates an error in the compiler's preprocessor.</p></td></tr><tr><td><p><a href="../../libs/function/test/function_arith_cxx98.cpp" target="_top">function_arith_cxx98.cpp</a></p></td><td><p>run</p></td><td><p>Test the first tutorial example.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/function_arith_portable.cpp" target="_top">function_arith_portable.cpp</a></p></td><td><p>run</p></td><td><p>Test the first tutorial example.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/sum_avg_cxx98.cpp" target="_top">sum_avg_cxx98.cpp</a></p></td><td><p>run</p></td><td><p>Test the second tutorial example.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/sum_avg_portable.cpp" target="_top">sum_avg_portable.cpp</a></p></td><td><p>run</p></td><td><p>Test the second tutorial example.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/mem_fun_cxx98.cpp" target="_top">mem_fun_cxx98.cpp</a></p></td><td><p>run</p></td><td><p>Test member function example from tutorial.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/mem_fun_portable.cpp" target="_top">mem_fun_portable.cpp</a></p></td><td><p>run</p></td><td><p>Test member function example from tutorial.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/std_bind_cxx98.cpp" target="_top">std_bind_cxx98.cpp</a></p></td><td><p>run</p></td><td><p>Test standard binders example from tutorial.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/std_bind_portable.cpp" target="_top">std_bind_portable.cpp</a></p></td><td><p>run</p></td><td><p>Test standard binders example from tutorial.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/function_ref_cxx98.cpp" target="_top">function_ref_cxx98.cpp</a></p></td><td><p>run</p></td><td><p>Test <a href="id2833212.html#id2695067">boost::ref</a> example from tutorial.</p></td><td> </td></tr><tr><td><p><a href="../../libs/function/test/function_ref_portable.cpp" target="_top">function_ref_portable.cpp</a></p></td><td><p>run</p></td><td><p>Test <a href="id2833212.html#id2695067">boost::ref</a> example from tutorial.</p></td><td> </td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="function.testsuite.negative"></a>Negative tests</h3></div></div><div></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Test</th><th>Type</th><th>Description</th><th>If failing...</th></tr></thead><tbody><tr><td><p><a href="../../libs/function/test/function_test_fail1.cpp" target="_top">function_test_fail1.cpp</a></p></td><td><p>compile-fail</p></td><td><p>Test the (incorrect!) use of comparisons between Boost.Function function objects.</p></td><td><p>Intuitive (but incorrect!) code may compile and will give meaningless results.</p></td></tr><tr><td><p><a href="../../libs/function/test/function_test_fail2.cpp" target="_top">function_test_fail2.cpp</a></p></td><td><p>compile-fail</p></td><td><p>Test the use of an incompatible function object with Boost.Function</p></td><td><p>Incorrect code may compile (with potentially unexpected results).</p></td></tr></tbody></table></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.misc.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ref.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Miscellaneous Notes </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Boost.Ref</td></tr></table></div></body></html> diff --git a/doc/html/function.tutorial.html b/doc/html/function.tutorial.html new file mode 100644 index 0000000000..ff8bcb387e --- /dev/null +++ b/doc/html/function.tutorial.html @@ -0,0 +1,135 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Tutorial</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.html" title="Boost.Function"><link rel="previous" href="function.history.html" title="History & Compatibility Notes"><link rel="next" href="function.reference.html" title="Reference"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="function.tutorial.html#id2879195" title="Basic Usage"><link rel="subsection" href="function.tutorial.html#id2879609" title="Free functions"><link rel="subsection" href="function.tutorial.html#id2879654" title="Member functions"><link rel="subsection" href="function.tutorial.html#id2879906" title="References to Functions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="function.tutorial"></a>Tutorial</h2></div></div><div></div></div><p> Boost.Function has two syntactical forms: the preferred form +and the portable form. The preferred form fits more closely with the +C++ language and reduces the number of separate template parameters +that need to be considered, often improving readability; however, the +preferred form is not supported on all platforms due to compiler +bugs. The compatible form will work on all compilers supported by +Boost.Function. Consult the table below to determine which syntactic +form to use for your compiler. + + </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><div class="itemizedlist"><ul type="disc" compact><li>GNU C++ 2.95.x, 3.0.x, 3.1.x</li><li>Comeau C++ 4.2.45.2</li><li>SGI MIPSpro 7.3.0</li><li>Intel C++ 5.0, 6.0</li><li>Compaq's cxx 6.2</li></ul></div></td><td align="left"><div class="itemizedlist"><ul type="disc" compact><li><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></li><li>Microsoft Visual C++ 6.0, 7.0</li><li>Borland C++ 5.5.1</li><li>Sun WorkShop 6 update 2 C++ 5.3</li><li>Metrowerks CodeWarrior 8.1</li></ul></div></td></tr></tbody></table></div><p> + +</p><p> If your compiler does not appear in this list, please try the preferred syntax and report your results to the Boost list so that we can keep this table up-to-date.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2879195"></a>Basic Usage</h3></div></div><div></div></div><p> A function wrapper is defined simply +by instantiating the <tt class="computeroutput">function</tt> class +template with the desired return type and argument types, formulated +as a C++ function type. Any number of arguments may be supplied, up to +some implementation-defined limit (10 is the default maximum). The +following declares a function object wrapper +<tt class="computeroutput">f</tt> that takes two +<tt class="computeroutput">int</tt> parameters and returns a +<tt class="computeroutput">float</tt>: + + </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"><a href="class.boost.function.html" title="Class template function">boost::function</a><float (int x, int y)> f;</pre></td><td align="left"><pre class="programlisting"><a href="class.boost.functionN.html" title="Class template functionN">boost::function2</a><float, int, int> f;</pre></td></tr></tbody></table></div><p> +</p><p> By default, function object wrappers are empty, so we can create a +function object to assign to <tt class="computeroutput">f</tt>: + +</p><pre class="programlisting">struct int_div { + float operator()(int x, int y) const { return ((float)x)/y; }; +};</pre><p> +</p><pre class="programlisting">f = int_div();</pre><p> +</p><p> Now we can use <tt class="computeroutput">f</tt> to execute +the underlying function object +<tt class="computeroutput">int_div</tt>: + +</p><pre class="programlisting">std::cout << f(5, 3) << std::endl;</pre><p> +</p><p> We are free to assign any compatible function object to +<tt class="computeroutput">f</tt>. If +<tt class="computeroutput">int_div</tt> had been declared to take two +<tt class="computeroutput">long</tt> operands, the implicit +conversions would have been applied to the arguments without any user +interference. The only limit on the types of arguments is that they be +CopyConstructible, so we can even use references and arrays: + + </p><div class="informaltable"><table border="1"><colgroup><col></colgroup><thead><tr><th align="left">Preferred syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"><a href="class.boost.function.html" title="Class template function">boost::function</a><void (int values[], int n, int& sum, float& avg)> sum_avg;</pre></td></tr></tbody></table></div><p> + </p><div class="informaltable"><table border="1"><colgroup><col></colgroup><thead><tr><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"><a href="class.boost.functionN.html" title="Class template functionN">boost::function4</a><void, int[], int, int&, float> sum_avg;</pre></td></tr></tbody></table></div><p> + +</p><pre class="programlisting">void do_sum_avg(int values[], int n, int& sum, float& avg) +{ + sum = 0; + for (int i = 0; i < n; i++) + sum += values[i]; + avg = (float)sum / n; +}</pre><p> + + +</p><pre class="programlisting">sum_avg = &do_sum_avg;</pre><p> +</p><p> Invoking a function object wrapper that does not actually +contain a function object is a precondition violation, much like +trying to call through a null function pointer, and will throw a <a href="id2837192.html" title="Class bad_function_call">bad_function_call</a> exception). We can check for an +empty function object wrapper by using it in a boolean context (it evaluates <tt class="computeroutput">true</tt> if the wrapper is not empty) or compare it against <tt class="computeroutput">0</tt>. For instance: +</p><pre class="programlisting">if (f) + std::cout << f(5, 3) << std::endl; +else + std::cout << "f has no target, so it is unsafe to call" << std::endl;</pre><p> +</p><p> Alternatively, +<tt class="computeroutput"><a href="class.boost.function.html#id2833437">empty</a>()</tt> +method will return whether or not the wrapper is empty. </p><p> Finally, we can clear out a function target by assigning it to <tt class="computeroutput">0</tt> or by calling the <tt class="computeroutput"><a href="class.boost.function.html#id2821057">clear</a>()</tt> member function, e.g., +</p><pre class="programlisting">f = 0;</pre><p> +</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2879609"></a>Free functions</h3></div></div><div></div></div><p> Free function pointers can be considered singleton function objects with const function call operators, and can therefore be directly used with the function object wrappers: +</p><pre class="programlisting">float mul_ints(int x, int y) { return ((float)x) * y; }</pre><p> +</p><pre class="programlisting">f = &mul_ints;</pre><p> +</p><p> Note that the <tt class="computeroutput">&</tt> isn't really necessary unless you happen to be using Microsoft Visual C++ version 6. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2879654"></a>Member functions</h3></div></div><div></div></div><p> In many systems, callbacks often call to member functions of a +particular object. This is often referred to as "argument binding", +and is beyond the scope of Boost.Function. The use of member functions +directly, however, is supported, so the following code is valid: + +</p><pre class="programlisting">struct X { + int foo(int); +};</pre><p> + + </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"><a href="class.boost.function.html" title="Class template function">boost::function</a><int (X*, int)> f; + +f = &X::foo; + +X x; +f(&x, 5);</pre></td><td align="left"><pre class="programlisting"><a href="class.boost.functionN.html" title="Class template functionN">boost::function2</a><int, X*, int> f; + +f = &X::foo; + +X x; +f(&x, 5);</pre></td></tr></tbody></table></div><p> +</p><p> Several libraries exist that support argument binding. Three such libraries are summarized below: +</p><div class="itemizedlist"><ul type="disc"><li><p><a href="../../libs/bind/index.html" target="_top">Bind</a>. This library allows binding of + arguments for any function object. It is lightweight and very + portable.</p></li><li><p>The C++ Standard library. Using + <tt class="computeroutput">std::bind1st</tt> and + <tt class="computeroutput">std::mem_fun</tt> together one can bind + the object of a pointer-to-member function for use with + Boost.Function: + + </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> <a href="class.boost.function.html" title="Class template function">boost::function</a><int (int)> f; + X x; + f = std::bind1st( + std::mem_fun(&X::foo), &x); + f(5); // Call x.foo(5)</pre></td><td align="left"><pre class="programlisting"> <a href="class.boost.functionN.html" title="Class template functionN">boost::function1</a><int, int> f; + X x; + f = std::bind1st( + std::mem_fun(&X::foo), &x); + f(5); // Call x.foo(5)</pre></td></tr></tbody></table></div><p> +</p></li><li><p>The <a href="../../libs/lambda/index.html" target="_top">Lambda</a> library. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. </p></li></ul></div><p> +</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2879906"></a>References to Functions</h3></div></div><div></div></div><p> In some cases it is + expensive (or semantically incorrect) to have Boost.Function clone a + function object. In such cases, it is possible to request that + Boost.Function keep only a reference to the actual function + object. This is done using the <tt class="computeroutput">ref</tt> + and <tt class="computeroutput">cref</tt> functions to wrap a + reference to a function object: + + </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Preferred syntax</th><th align="left">Portable syntax</th></tr></thead><tbody><tr><td align="left"><pre class="programlisting"> stateful_type a_function_object; + <a href="class.boost.function.html" title="Class template function">boost::function</a><int (int)> f; + f = <a href="id2833212.html#id2695067">boost::ref</a>(a_function_object); + + <a href="class.boost.function.html" title="Class template function">boost::function</a><int (int)> f2(f);</pre></td><td align="left"><pre class="programlisting"> stateful_type a_function_object; + <a href="class.boost.functionN.html" title="Class template functionN">boost::function1</a><int, int> f; + f = <a href="id2833212.html#id2695067">boost::ref</a>(a_function_object); + + <a href="class.boost.functionN.html" title="Class template functionN">boost::function1</a><int, int> f2(f);</pre></td></tr></tbody></table></div><p> +</p><p> Here, <tt class="computeroutput">f</tt> will not make a copy +of <tt class="computeroutput">a_function_object</tt>, nor will +<tt class="computeroutput">f2</tt> when it is targeted to +<tt class="computeroutput">f</tt>'s reference to +<tt class="computeroutput">a_function_object</tt>. Additionally, when +using references to function objects, Boost.Function will not throw +exceptions during assignment or construction. +</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 03:32:15 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.history.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="function.reference.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">History & Compatibility Notes </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Reference</td></tr></table></div></body></html> diff --git a/doc/html/id2695148.html b/doc/html/id2695148.html new file mode 100644 index 0000000000..be768686b3 --- /dev/null +++ b/doc/html/id2695148.html @@ -0,0 +1,7 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template is_reference_wrapper</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="ref.reference.html#header.boost.ref.hpp" title="Header <boost/ref.hpp>"><link rel="previous" href="id2833212.html" title="Class template reference_wrapper"><link rel="next" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2695148.html#id2887879" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2695148"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template is_reference_wrapper</span></h2><p>boost::is_reference_wrapper — Determine if a type T is an instantiation of reference_wrapper.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> +<span class="bold"><b>class</b></span> is_reference_wrapper { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// static constants</em></span> + <span class="bold"><b>static</b></span> <span class="bold"><b>const</b></span> <span class="bold"><b>bool</b></span> value = unspecified; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>The <tt class="computeroutput">value</tt> static constant will be <tt class="computeroutput">true</tt> iff the type <tt class="computeroutput">T</tt> is a specialization of <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a></tt>.</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small>Copyright © 1999, 2000 Jaakko Järvi<br>Copyright © 2001, 2002 Peter Dimov<br>Copyright © 2002 David Abrahams</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2833212.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ref.reference.html#header.boost.ref.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2695230.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template reference_wrapper </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template unwrap_reference</td></tr></table></div></body></html> diff --git a/doc/html/id2695230.html b/doc/html/id2695230.html new file mode 100644 index 0000000000..c2f8d96b55 --- /dev/null +++ b/doc/html/id2695230.html @@ -0,0 +1,7 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template unwrap_reference</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="ref.reference.html#header.boost.ref.hpp" title="Header <boost/ref.hpp>"><link rel="previous" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="next" href="ref.ack.html" title="Acknowledgements"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2695230.html#id2887984" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2695230"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template unwrap_reference</span></h2><p>boost::unwrap_reference — Find the type in a reference_wrapper.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> +<span class="bold"><b>class</b></span> unwrap_reference { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> unspecified T; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>The typedef <tt class="computeroutput">type</tt> is <tt class="computeroutput">T::type</tt> if <tt class="computeroutput">T</tt> is a <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a></tt>, <tt class="computeroutput">T</tt> otherwise.</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small>Copyright © 1999, 2000 Jaakko Järvi<br>Copyright © 2001, 2002 Peter Dimov<br>Copyright © 2002 David Abrahams</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2695148.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ref.reference.html#header.boost.ref.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ref.ack.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template is_reference_wrapper </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Acknowledgements</td></tr></table></div></body></html> diff --git a/doc/html/id2827840.html b/doc/html/id2827840.html new file mode 100644 index 0000000000..90e768d947 --- /dev/null +++ b/doc/html/id2827840.html @@ -0,0 +1,21 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Function any_cast</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="any.reference.html#header.boost.any.hpp" title="Header <boost/any.hpp>"><link rel="previous" href="class.boost.any.html" title="Class any"><link rel="next" href="ch01s04.html" title="Acknowledgements"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2827840.html#id2812766" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2827840"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Function any_cast</span></h2><p>boost::any_cast — Custom keyword cast for extracting a value + of a given type from an + any.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> ValueType any_cast(<span class="bold"><b>const</b></span> any & operand); +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> <span class="bold"><b>const</b></span> ValueType * any_cast(<span class="bold"><b>const</b></span> any * operand); +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> ValueType> ValueType * any_cast(any * operand);</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p><b><span class="term">Returns</span></b>: + If passed a pointer, it returns a + similarly qualified pointer to the value content if + successful, otherwise null is returned. If passed a value or + reference, it returns a copy of the value content if + successful.<br><b><span class="term">Throws</span></b>: + Overloads taking an + <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">any</a></tt> pointer do not + throw; the overload taking an + <tt class="computeroutput"><a href="class.boost.any.html" title="Class any">any</a></tt> value or reference + throws <tt class="computeroutput"><a href="class.boost.bad_any_cast.html" title="Class bad_any_cast">bad_any_cast</a></tt> if + unsuccessful.<br><b><span class="term">Rationale</span></b>: + The value/reference version returns a + copy because the C++ keyword casts return + copies.</p></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001 Kevlin Henney</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.any.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="any.reference.html#header.boost.any.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s04.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class any </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Acknowledgements</td></tr></table></div></body></html> diff --git a/doc/html/id2830650.html b/doc/html/id2830650.html new file mode 100644 index 0000000000..33ff9052e9 --- /dev/null +++ b/doc/html/id2830650.html @@ -0,0 +1,13 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class last_value<void></title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2875832" title="Header <boost/last_value.hpp>"><link rel="previous" href="class.boost.last_value.html" title="Class template last_value"><link rel="next" href="ch04s04.html" title="Frequently Asked Questions"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2830650.html#id2895526" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2830650"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class last_value<void></span></h2><p>boost::last_value<void> — Evaluate an InputIterator sequence.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> last_value<void> { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> unspecified result_type; + + <span class="emphasis"><em>// <a href="id2830650.html#id2899868">invocation</a></em></span> + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> InputIterator> + result_type <a href="id2830650.html#id2842507"><span class="bold"><b>operator</b></span>()</a>(InputIterator, InputIterator) <span class="bold"><b>const</b></span>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2899868"></a><tt class="computeroutput">last_value</tt> invocation</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> InputIterator> + result_type <a name="id2842507"></a><span class="bold"><b>operator</b></span>()(InputIterator first, InputIterator last) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + Dereferences every iterator in the sequence <tt class="computeroutput">[first, last)</tt>.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.last_value.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2875832"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s04.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template last_value </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Frequently Asked Questions</td></tr></table></div></body></html> diff --git a/doc/html/id2833212.html b/doc/html/id2833212.html new file mode 100644 index 0000000000..6f94094e80 --- /dev/null +++ b/doc/html/id2833212.html @@ -0,0 +1,44 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class template reference_wrapper</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="ref.reference.html#header.boost.ref.hpp" title="Header <boost/ref.hpp>"><link rel="previous" href="ref.reference.html" title="Reference"><link rel="next" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2833212.html#id2887409" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2833212"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class template reference_wrapper</span></h2><p>boost::reference_wrapper — + Contains a reference to an object of type + T. + </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> +<span class="bold"><b>class</b></span> reference_wrapper { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// types</em></span> + <span class="bold"><b>typedef</b></span> T type; + + <span class="emphasis"><em>// <a href="id2833212.html#id2833212construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="id2833212.html#id2833271">reference_wrapper(T&)</a>; + + <span class="emphasis"><em>// <a href="id2833212.html#id2833314">access</a></em></span> + <a href="id2833212.html#id2833319"><span class="bold"><b>operator</b></span> T&() <span class="bold"><b>const</b></span></a>; + <a href="id2833212.html#id2833343">T& get() <span class="bold"><b>const</b></span></a>; + <a href="id2833212.html#id2833366">T* get_pointer() <span class="bold"><b>const</b></span></a>; +}; + +<span class="emphasis"><em>// <a href="id2833212.html#id2695061">constructors</a></em></span> +<a href="id2833212.html#id2695067">reference_wrapper<T> ref(T&)</a>; +<a href="id2833212.html#id2695106">reference_wrapper<T <span class="bold"><b>const</b></span>> cref(T <span class="bold"><b>const</b></span>&)</a>;</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p> + <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a></tt> + is primarily used to "feed" references to function templates + (algorithms) that take their parameter by value. It provides + an implicit conversion to + <tt class="computeroutput">T&</tt>, which usually allows + the function templates to work on references unmodified. + </p><div class="refsect2" lang="en"><h3><a name="id2833212construct-copy-destruct"></a><tt class="computeroutput">reference_wrapper</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2833271"></a>reference_wrapper(T& t);</pre><p><b><span class="term">Effects</span></b>: + Constructs a + <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a></tt> + object that stores a reference to + <tt class="computeroutput">t</tt>.<br><b><span class="term">Throws</span></b>: + Does not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2833314"></a><tt class="computeroutput">reference_wrapper</tt> access</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2833319"></a><span class="bold"><b>operator</b></span> T&() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + The stored reference.<br><b><span class="term">Throws</span></b>: + Does not throw.</p></li><li><pre class="literallayout"><a name="id2833343"></a>T& get() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + The stored reference.<br><b><span class="term">Throws</span></b>: + Does not throw.</p></li><li><pre class="literallayout"><a name="id2833366"></a>T* get_pointer() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + A pointer to the object referenced by the stored reference.<br><b><span class="term">Throws</span></b>: + Does not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2695061"></a><tt class="computeroutput">reference_wrapper</tt> constructors</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2695067"></a>reference_wrapper<T> ref(T& t);</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a><T>(t)</tt><br><b><span class="term">Throws</span></b>: + Does not throw.</p></li><li><pre class="literallayout"><a name="id2695106"></a>reference_wrapper<T <span class="bold"><b>const</b></span>> cref(T <span class="bold"><b>const</b></span>& t);</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">reference_wrapper</a><T const>(t)</tt><br><b><span class="term">Throws</span></b>: + Does not throw.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small>Copyright © 1999, 2000 Jaakko Järvi<br>Copyright © 2001, 2002 Peter Dimov<br>Copyright © 2002 David Abrahams</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.reference.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ref.reference.html#header.boost.ref.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2695148.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Reference </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template is_reference_wrapper</td></tr></table></div></body></html> diff --git a/doc/html/id2837192.html b/doc/html/id2837192.html new file mode 100644 index 0000000000..7e01acc7e9 --- /dev/null +++ b/doc/html/id2837192.html @@ -0,0 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class bad_function_call</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="function.reference.html#header.boost.function.hpp" title="Header <boost/function.hpp>"><link rel="previous" href="function.reference.html" title="Reference"><link rel="next" href="class.boost.function_base.html" title="Class function_base"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2837192.html#id2881116" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2837192"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class bad_function_call</span></h2><p>boost::bad_function_call — An exception type thrown when an instance of a function object is empty when invoked.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> bad_function_call : <span class="bold"><b>public</b></span> std::runtime_error { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="id2837192.html#id2837192construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="id2837192.html#id2747934">bad_function_call()</a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2837192construct-copy-destruct"></a><tt class="computeroutput">bad_function_call</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2747934"></a>bad_function_call();</pre><p><b><span class="term">Effects</span></b>: + Constructs a <tt class="computeroutput"><a href="id2837192.html" title="Class bad_function_call">bad_function_call</a></tt> exception object.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 19, 2003 at 22:46:09 GMT</small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.reference.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="function.reference.html#header.boost.function.hpp"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.function_base.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Reference </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class function_base</td></tr></table></div></body></html> diff --git a/doc/html/id2852290.html b/doc/html/id2852290.html new file mode 100644 index 0000000000..c3b219b222 --- /dev/null +++ b/doc/html/id2852290.html @@ -0,0 +1,37 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class trackable</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2900517" title="Header <boost/signals/trackable.hpp>"><link rel="previous" href="class.boost.slot.html" title="Class template slot"><link rel="next" href="id2890015.html" title="Class connection"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2852290.html#id2892968" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2852290"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class trackable</span></h2><p>boost::signals::trackable — Enables safe use of multicast callbacks.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> trackable { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="id2852290.html#id2852290construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="id2852290.html#id2889800">trackable()</a>; + <a href="id2852290.html#id2891558">trackable(<span class="bold"><b>const</b></span> trackable&)</a>; + <a href="id2852290.html#id2873094">trackable& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> trackable&)</a>; + <a href="id2852290.html#id2903091">~trackable()</a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>The <tt class="computeroutput">trackable</tt> class + provides automatic disconnection of signals and slots when + objects bound in slots (via pointer or reference) are + destroyed. The <tt class="computeroutput">trackable</tt> + class may only be used as a public base class for some other + class; when used as such, that class may be bound to function + objects used as part of slots. The manner in which a + <tt class="computeroutput">trackable</tt> object tracks the + set of signal-slot connections it is a part of is + unspecified.</p><p>The actual use of + <tt class="computeroutput">trackable</tt> is contingent on + the presence of appropriate + <a href="id2905241.html" title="Function template visit_each">visit_each</a> overloads for any type + that may contain pointers or references to trackable + objects.</p><div class="refsect2" lang="en"><h3><a name="id2852290construct-copy-destruct"></a><tt class="computeroutput">trackable</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2889800"></a>trackable();</pre><p><b><span class="term">Effects</span></b>: + Sets the list of connected slots to empty.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2891558"></a>trackable(<span class="bold"><b>const</b></span> trackable& other);</pre><p><b><span class="term">Effects</span></b>: + Sets the list of connected slots to empty.<br><b><span class="term">Throws</span></b>: + Will not throw.<br><b><span class="term">Rationale</span></b>: + Signal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.</p></li><li><pre class="literallayout"><a name="id2873094"></a>trackable& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> trackable& other);</pre><p><b><span class="term">Effects</span></b>: + Sets the list of connected slots to empty.<br><b><span class="term">Returns</span></b>: + <tt class="computeroutput">*this</tt><br><b><span class="term">Throws</span></b>: + Will not throw.<br><b><span class="term">Rationale</span></b>: + Signal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.</p></li><li><pre class="literallayout"><a name="id2903091"></a>~trackable();</pre><p><b><span class="term">Effects</span></b>: + Disconnects all signal/slot connections that + contain a pointer or reference to this trackable object that + can be found by + <a href="id2905241.html" title="Function template visit_each">visit_each</a>.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class.boost.slot.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2900517"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2890015.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template slot </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class connection</td></tr></table></div></body></html> diff --git a/doc/html/id2877648.html b/doc/html/id2877648.html new file mode 100644 index 0000000000..d9f2ba9685 --- /dev/null +++ b/doc/html/id2877648.html @@ -0,0 +1,29 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class scoped_connection</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2858799" title="Header <boost/signals/connection.hpp>"><link rel="previous" href="id2890015.html" title="Class connection"><link rel="next" href="id2905241.html" title="Function template visit_each"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2877648.html#id2894490" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2877648"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class scoped_connection</span></h2><p>boost::signals::scoped_connection — Limits a signal-slot connection lifetime to a particular scope.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> scoped_connection : <span class="bold"><b>private</b></span> noncopyable { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="id2877648.html#id2877648construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="id2877648.html#id2899197">scoped_connection(<span class="bold"><b>const</b></span> connection&)</a>; + <a href="id2877648.html#id2856525">~scoped_connection()</a>; + + <span class="emphasis"><em>// <a href="id2877648.html#id2902063">connection management</a></em></span> + <a href="id2877648.html#id2902069"><span class="bold"><b>void</b></span> disconnect() <span class="bold"><b>const</b></span></a>; + <a href="id2877648.html#id2865054"><span class="bold"><b>bool</b></span> connected() <span class="bold"><b>const</b></span></a>; +};</pre></div><div class="refsect1" lang="en"><h2>Description</h2><div class="refsect2" lang="en"><h3><a name="id2877648construct-copy-destruct"></a><tt class="computeroutput">scoped_connection</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2899197"></a>scoped_connection(<span class="bold"><b>const</b></span> connection& other);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">this</tt> references + the connection referenced by + <tt class="computeroutput">other</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2856525"></a>~scoped_connection();</pre><p><b><span class="term">Effects</span></b>: + If + <tt class="computeroutput">this-><a href="id2877648.html#id2865054">connected</a>()</tt>, + disconnects the signal-slot connection.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2902063"></a><tt class="computeroutput">scoped_connection</tt> connection management</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2902069"></a><span class="bold"><b>void</b></span> disconnect() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + If + <tt class="computeroutput">this-><a href="id2877648.html#id2865054">connected</a>()</tt>, + disconnects the signal and slot referenced by this; + otherwise, this operation is a no-op.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">!this-><a href="id2877648.html#id2865054">connected</a>()</tt>.</p></li><li><pre class="literallayout"><a name="id2865054"></a><span class="bold"><b>bool</b></span> connected() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if this + references a non-NULL connection that is still active + (connected), and <tt class="computeroutput">false</tt> + otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2890015.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2858799"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2905241.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class connection </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Function template visit_each</td></tr></table></div></body></html> diff --git a/doc/html/id2890015.html b/doc/html/id2890015.html new file mode 100644 index 0000000000..4291126d11 --- /dev/null +++ b/doc/html/id2890015.html @@ -0,0 +1,74 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Class connection</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2858799" title="Header <boost/signals/connection.hpp>"><link rel="previous" href="id2852290.html" title="Class trackable"><link rel="next" href="id2877648.html" title="Class scoped_connection"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2890015.html#id2893618" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2890015"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Class connection</span></h2><p>boost::signals::connection — Query/disconnect a signal-slot connection.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>class</b></span> connection { +<span class="bold"><b>public</b></span>: + <span class="emphasis"><em>// <a href="id2890015.html#id2890015construct-copy-destruct">construct/copy/destruct</a></em></span> + <a href="id2890015.html#id2886986">connection()</a>; + <a href="id2890015.html#id2886853">connection(<span class="bold"><b>const</b></span> connection&)</a>; + <a href="id2890015.html#id2870983">connection& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> connection&)</a>; + + <span class="emphasis"><em>// <a href="id2890015.html#id2908734">connection management</a></em></span> + <a href="id2890015.html#id2908738"><span class="bold"><b>void</b></span> disconnect() <span class="bold"><b>const</b></span></a>; + <a href="id2890015.html#id2893725"><span class="bold"><b>bool</b></span> connected() <span class="bold"><b>const</b></span></a>; + + <span class="emphasis"><em>// <a href="id2890015.html#id2848854">modifiers</a></em></span> + <a href="id2890015.html#id2848859"><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> connection&)</a>; + + <span class="emphasis"><em>// <a href="id2890015.html#id2895677">comparisons</a></em></span> + <a href="id2890015.html#id2855780"><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>==(<span class="bold"><b>const</b></span> connection&) <span class="bold"><b>const</b></span></a>; + <a href="id2890015.html#id2869664"><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span><(<span class="bold"><b>const</b></span> connection&) <span class="bold"><b>const</b></span></a>; +}; + +<span class="emphasis"><em>// <a href="id2890015.html#id2849362">specialized algorithms</a></em></span> +<a href="id2890015.html#id2883120"><span class="bold"><b>void</b></span> swap(connection&, connection&)</a>;</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p> + The <a href="id2890015.html" title="Class connection">connection</a> class represents a + connection between a Signal and a Slot. It is a lightweight + object that has the ability to query whether the signal and + slot are currently connected, and to disconnect the signal + and slot. It is always safe to query or disconnect a + connection. + </p><div class="refsect2" lang="en"><h3><a name="id2890015construct-copy-destruct"></a><tt class="computeroutput">connection</tt> construct/copy/destruct</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2886986"></a>connection();</pre><p><b><span class="term">Effects</span></b>: + Sets the currently represented connection to the + NULL connection.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">!this-><a href="id2890015.html#id2893725">connected</a>()</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2886853"></a>connection(<span class="bold"><b>const</b></span> connection& other);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">this</tt> references + the connection referenced by + <tt class="computeroutput">other</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2870983"></a>connection& <span class="bold"><b>operator</b></span>=(<span class="bold"><b>const</b></span> connection& other);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">this</tt> references + the connection referenced by + <tt class="computeroutput">other</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2908734"></a><tt class="computeroutput">connection</tt> connection management</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2908738"></a><span class="bold"><b>void</b></span> disconnect() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Effects</span></b>: + If + <tt class="computeroutput">this-><a href="id2890015.html#id2893725">connected</a>()</tt>, + disconnects the signal and slot referenced by this; + otherwise, this operation is a no-op.<br><b><span class="term">Postconditions</span></b>: + <tt class="computeroutput">!this-><a href="id2890015.html#id2893725">connected</a>()</tt>.</p></li><li><pre class="literallayout"><a name="id2893725"></a><span class="bold"><b>bool</b></span> connected() <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if this + references a non-NULL connection that is still active + (connected), and <tt class="computeroutput">false</tt> + otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2848854"></a><tt class="computeroutput">connection</tt> modifiers</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2848859"></a><span class="bold"><b>void</b></span> swap(<span class="bold"><b>const</b></span> connection& other);</pre><p><b><span class="term">Effects</span></b>: + Swaps the connections referenced in + <tt class="computeroutput">this</tt> and + <tt class="computeroutput">other</tt>.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2895677"></a><tt class="computeroutput">connection</tt> comparisons</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2855780"></a><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span>==(<span class="bold"><b>const</b></span> connection& other) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if + <tt class="computeroutput">this</tt> and + <tt class="computeroutput">other</tt> reference the same + connection or both reference the NULL connection, and + <tt class="computeroutput">false</tt> + otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li><li><pre class="literallayout"><a name="id2869664"></a><span class="bold"><b>bool</b></span> <span class="bold"><b>operator</b></span><(<span class="bold"><b>const</b></span> connection& other) <span class="bold"><b>const</b></span>;</pre><p><b><span class="term">Returns</span></b>: + <tt class="computeroutput">true</tt> if the + connection referenced by + <tt class="computeroutput">this</tt> precedes the + connection referenced by + <tt class="computeroutput">other</tt> based on some + unspecified ordering, and + <tt class="computeroutput">false</tt> + otherwise.<br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div><div class="refsect2" lang="en"><h3><a name="id2849362"></a><tt class="computeroutput">connection</tt> specialized algorithms</h3><div class="orderedlist"><ol type="1"><li><pre class="literallayout"><a name="id2883120"></a><span class="bold"><b>void</b></span> swap(connection& x, connection& y);</pre><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">x.swap(y)</tt><br><b><span class="term">Throws</span></b>: + Will not throw.</p></li></ol></div></div></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2852290.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2858799"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2877648.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class trackable </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class scoped_connection</td></tr></table></div></body></html> diff --git a/doc/html/id2905241.html b/doc/html/id2905241.html new file mode 100644 index 0000000000..29f2454a2f --- /dev/null +++ b/doc/html/id2905241.html @@ -0,0 +1,26 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Function template visit_each</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.reference.html#id2905340" title="Header <boost/visit_each.hpp>"><link rel="previous" href="id2877648.html" title="Class scoped_connection"><link rel="next" href="class.boost.last_value.html" title="Class template last_value"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="id2905241.html#id2894940" title="Description"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="refentry" lang="en"><a name="id2905241"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Function template visit_each</span></h2><p>boost::visit_each — Allow limited exploration of class members.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +<span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Visitor, <span class="bold"><b>typename</b></span> T> + <span class="bold"><b>void</b></span> visit_each(<span class="bold"><b>const</b></span> Visitor& visitor, <span class="bold"><b>const</b></span> T& t, <span class="bold"><b>int</b></span> );</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>The <a href="id2905241.html" title="Function template visit_each">visit_each</a> mechanism + allows a visitor to be applied to every subobject in a given + object. It is used by the Signals library to discover + <a href="id2852290.html" title="Class trackable">signals::trackable</a> objects within a + function object, but other uses may surface if used universally + (e.g., conservative garbage collection). To fit within the + <a href="id2905241.html" title="Function template visit_each">visit_each</a> framework, a + <a href="id2905241.html" title="Function template visit_each">visit_each</a> overload must be supplied for + each object type. </p><p><b><span class="term">Effects</span></b>: + <tt class="computeroutput">visitor(t)</tt>, and for + every subobject <tt class="computeroutput">x</tt> of + <tt class="computeroutput">t</tt>: + <div class="itemizedlist"><ul type="disc"><li><p>If <tt class="computeroutput">x</tt> is a reference, <tt class="computeroutput">visit_each(visitor, <a href="id2833212.html#id2695067">ref</a>(x), 0)</tt></p></li><li><p>Otherwise, <tt class="computeroutput">visit_each(visitor, x, 0)</tt></p></li></ul></div> + <br><b><span class="term">Notes</span></b>: + <p>The third parameter is + <tt class="computeroutput">long</tt> for the fallback version + of <a href="id2905241.html" title="Function template visit_each">visit_each</a> and the argument + supplied to this third paramter must always be 0. The third + parameter is an artifact of the widespread lack of proper + function template ordering, and will be removed in the future.</p><p>Library authors will be expected to add additional + overloads that specialize the T argument for their classes, so + that subobjects can be visited.</p><p>Calls to visit_each are required to be unqualified, to + enable argument-dependent lookup.</p></p></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2877648.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.reference.html#id2905340"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.last_value.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class scoped_connection </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template last_value</td></tr></table></div></body></html> diff --git a/doc/html/images/blank.png b/doc/html/images/blank.png Binary files differnew file mode 100644 index 0000000000..764bf4f0c3 --- /dev/null +++ b/doc/html/images/blank.png diff --git a/doc/html/images/caution.png b/doc/html/images/caution.png Binary files differnew file mode 100644 index 0000000000..5b7809ca4a --- /dev/null +++ b/doc/html/images/caution.png diff --git a/doc/html/images/draft.png b/doc/html/images/draft.png Binary files differnew file mode 100644 index 0000000000..0084708c9b --- /dev/null +++ b/doc/html/images/draft.png diff --git a/doc/html/images/home.png b/doc/html/images/home.png Binary files differnew file mode 100644 index 0000000000..cbb711de71 --- /dev/null +++ b/doc/html/images/home.png diff --git a/doc/html/images/important.png b/doc/html/images/important.png Binary files differnew file mode 100644 index 0000000000..12c90f607a --- /dev/null +++ b/doc/html/images/important.png diff --git a/doc/html/images/next.png b/doc/html/images/next.png Binary files differnew file mode 100644 index 0000000000..45835bf89a --- /dev/null +++ b/doc/html/images/next.png diff --git a/doc/html/images/note.png b/doc/html/images/note.png Binary files differnew file mode 100644 index 0000000000..d0c3c645ab --- /dev/null +++ b/doc/html/images/note.png diff --git a/doc/html/images/prev.png b/doc/html/images/prev.png Binary files differnew file mode 100644 index 0000000000..cf24654f8a --- /dev/null +++ b/doc/html/images/prev.png diff --git a/doc/html/images/tip.png b/doc/html/images/tip.png Binary files differnew file mode 100644 index 0000000000..5c4aab3bb3 --- /dev/null +++ b/doc/html/images/tip.png diff --git a/doc/html/images/toc-blank.png b/doc/html/images/toc-blank.png Binary files differnew file mode 100644 index 0000000000..6ffad17a0c --- /dev/null +++ b/doc/html/images/toc-blank.png diff --git a/doc/html/images/toc-minus.png b/doc/html/images/toc-minus.png Binary files differnew file mode 100644 index 0000000000..abbb020c8e --- /dev/null +++ b/doc/html/images/toc-minus.png diff --git a/doc/html/images/toc-plus.png b/doc/html/images/toc-plus.png Binary files differnew file mode 100644 index 0000000000..941312ce0d --- /dev/null +++ b/doc/html/images/toc-plus.png diff --git a/doc/html/images/up.png b/doc/html/images/up.png Binary files differnew file mode 100644 index 0000000000..07634de26b --- /dev/null +++ b/doc/html/images/up.png diff --git a/doc/html/images/warning.png b/doc/html/images/warning.png Binary files differnew file mode 100644 index 0000000000..1c33db8f34 --- /dev/null +++ b/doc/html/images/warning.png diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000000..6d948233a5 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,2 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The Boost C++ Libraries</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="next" href="any.html" title="Boost.Any"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2878946"></a>The Boost C++ Libraries</h1></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="any.html">Boost.Any</a></dt><dd><dl><dt><a href="any.html#id2878869">Introduction</a></dt><dt><a href="ch01s02.html">Examples</a></dt><dt><a href="any.reference.html">Reference</a></dt><dd><dl><dt><a href="any.reference.html#any.ValueType">ValueType requirements</a></dt><dt><a href="any.reference.html#header.boost.any.hpp">Header <boost/any.hpp></a></dt></dl></dd><dt><a href="ch01s04.html">Acknowledgements</a></dt></dl></dd><dt><a href="function.html">Boost.Function</a></dt><dd><dl><dt><a href="function.html#function.intro">Introduction</a></dt><dt><a href="function.history.html">History & Compatibility Notes</a></dt><dt><a href="function.tutorial.html">Tutorial</a></dt><dd><dl><dt><a href="function.tutorial.html#id2879195">Basic Usage</a></dt><dt><a href="function.tutorial.html#id2879609">Free functions</a></dt><dt><a href="function.tutorial.html#id2879654">Member functions</a></dt><dt><a href="function.tutorial.html#id2879906">References to Functions</a></dt></dl></dd><dt><a href="function.reference.html">Reference</a></dt><dd><dl><dt><a href="function.reference.html#function.definitions">Definitions</a></dt><dt><a href="function.reference.html#header.boost.function.hpp">Header <boost/function.hpp></a></dt></dl></dd><dt><a href="function.faq.html">Frequently Asked Questions</a></dt><dt><a href="function.misc.html">Miscellaneous Notes</a></dt><dd><dl><dt><a href="function.misc.html#id2885974">Boost.Function vs. Function Pointers</a></dt><dt><a href="function.misc.html#id2886053">Performance</a></dt><dd><dl><dt><a href="function.misc.html#id2886060">Function object wrapper size</a></dt><dt><a href="function.misc.html#id2886078">Copying efficiency</a></dt><dt><a href="function.misc.html#id2886105">Invocation efficiency</a></dt></dl></dd><dt><a href="function.misc.html#id2886122">Combatting virtual function "bloat"</a></dt><dt><a href="function.misc.html#id2886152">Acknowledgements</a></dt></dl></dd><dt><a href="function.testsuite.html">Testsuite</a></dt><dd><dl><dt><a href="function.testsuite.html#function.testsuite.acceptance">Acceptance tests</a></dt><dt><a href="function.testsuite.html#function.testsuite.negative">Negative tests</a></dt></dl></dd></dl></dd><dt><a href="ref.html">Boost.Ref</a></dt><dd><dl><dt><a href="ref.html#ref.intro">Introduction</a></dt><dt><a href="ref.reference.html">Reference</a></dt><dd><dl><dt><a href="ref.reference.html#header.boost.ref.hpp">Header <boost/ref.hpp></a></dt></dl></dd><dt><a href="ref.ack.html">Acknowledgements</a></dt></dl></dd><dt><a href="signals.html">Boost.Signals</a></dt><dd><dl><dt><a href="signals.html#id2888155">Introduction</a></dt><dt><a href="ch04s02.html">Tutorial</a></dt><dd><dl><dt><a href="ch04s02.html#id2888202">How to Read this Tutorial</a></dt><dt><a href="ch04s02.html#id2888275">Compatibility Note</a></dt><dt><a href="ch04s02.html#id2888425">Hello, World! (Beginner)</a></dt><dt><a href="ch04s02.html#id2888584">Calling multiple slots</a></dt><dd><dl><dt><a href="ch04s02.html#id2888590">Connecting multiple slots (Beginner)</a></dt><dt><a href="ch04s02.html#id2888807">Ordering slot call groups (Intermediate)</a></dt></dl></dd><dt><a href="ch04s02.html#id2889063">Passing values to and from slots</a></dt><dd><dl><dt><a href="ch04s02.html#id2889069">Slot Arguments (Beginner)</a></dt><dt><a href="ch04s02.html#id2889329">Signal Return Values (Advanced)</a></dt></dl></dd><dt><a href="ch04s02.html#id2890060">Connection Management</a></dt><dd><dl><dt><a href="ch04s02.html#id2890066">Disconnecting Slots (Beginner)</a></dt><dt><a href="ch04s02.html#id2890208">Scoped connections (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890264">Automatic connection management (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890510">When can disconnections occur? (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890595">Passing slots (Intermediate)</a></dt></dl></dd></dl></dd><dt><a href="signals.reference.html">Reference</a></dt><dd><dl><dt><a href="signals.reference.html#header.boost.signal.hpp">Header <boost/signal.hpp></a></dt><dt><a href="signals.reference.html#id2895664">Header <boost/signals/slot.hpp></a></dt><dt><a href="signals.reference.html#id2900517">Header <boost/signals/trackable.hpp></a></dt><dt><a href="signals.reference.html#id2858799">Header <boost/signals/connection.hpp></a></dt><dt><a href="signals.reference.html#id2905340">Header <boost/visit_each.hpp></a></dt><dt><a href="signals.reference.html#id2875832">Header <boost/last_value.hpp></a></dt></dl></dd><dt><a href="ch04s04.html">Frequently Asked Questions</a></dt><dt><a href="ch04s05.html">Design Overview</a></dt><dd><dl><dt><a href="ch04s05.html#id2895772">Type Erasure</a></dt><dt><a href="ch04s05.html#id2895860">connection class</a></dt><dt><a href="ch04s05.html#id2895993">Slot Call Iterator</a></dt><dt><a href="ch04s05.html#id2896236">visit_each function template</a></dt></dl></dd><dt><a href="ch04s06.html">Design Rationale</a></dt><dd><dl><dt><a href="ch04s06.html#id2896415">Choice of Slot Definitions</a></dt><dt><a href="ch04s06.html#id2896550">User-level Connection Management</a></dt><dt><a href="ch04s06.html#id2811980">Combiner Interface</a></dt><dt><a href="ch04s06.html#id2897087">Connection Interfaces: += operator</a></dt><dt><a href="ch04s06.html#id2897291">trackable rationale</a></dt><dd><dl><dt><a href="ch04s06.html#id2897340">trackable copying behavior</a></dt><dt><a href="ch04s06.html#id2897409">Why derivation from trackable?</a></dt></dl></dd><dt><a href="ch04s06.html#id2897506">Comparison with other Signal/Slot implementations</a></dt><dd><dl><dt><a href="ch04s06.html#id2897514">libsigc++</a></dt><dt><a href="ch04s06.html#id2897600">.NET delegates</a></dt></dl></dd></dl></dd><dt><a href="ch04s07.html">Testsuite</a></dt><dd><dl><dt><a href="ch04s07.html#id2897667">Acceptance tests</a></dt></dl></dd></dl></dd></dl></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small></small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="any.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Boost.Any</td></tr></table></div></body></html> diff --git a/doc/html/ref.ack.html b/doc/html/ref.ack.html new file mode 100644 index 0000000000..0f5bee8ce6 --- /dev/null +++ b/doc/html/ref.ack.html @@ -0,0 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Acknowledgements</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="ref.html" title="Boost.Ref"><link rel="previous" href="id2695230.html" title="Class template unwrap_reference"><link rel="next" href="signals.html" title="Boost.Signals"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref.ack"></a>Acknowledgements</h2></div></div><div></div></div><p><a href="id2833212.html#id2695067">ref</a> and <a href="id2833212.html#id2695106">cref</a> + were originally part of the <a href="../../libs/tuple/index.html" target="_top">Tuple</a> library + by Jaakko Järvi. They were "promoted to boost:: status" by + Peter Dimov because they are generally useful. Douglas Gregor and + Dave Abrahams contributed + <a href="id2695148.html" title="Class template is_reference_wrapper">is_reference_wrapper</a> and + <a href="id2695230.html" title="Class template unwrap_reference">unwrap_reference</a>.</p></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small>Copyright © 1999, 2000 Jaakko Järvi<br>Copyright © 2001, 2002 Peter Dimov<br>Copyright © 2002 David Abrahams</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="id2695230.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="signals.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Class template unwrap_reference </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Boost.Signals</td></tr></table></div></body></html> diff --git a/doc/html/ref.html b/doc/html/ref.html new file mode 100644 index 0000000000..a08973a369 --- /dev/null +++ b/doc/html/ref.html @@ -0,0 +1,37 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.Ref</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="index.html" title="The Boost C++ Libraries"><link rel="previous" href="function.testsuite.html" title="Testsuite"><link rel="next" href="ref.reference.html" title="Reference"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="ref.html#ref.intro" title="Introduction"><link rel="section" href="ref.reference.html" title="Reference"><link rel="section" href="ref.ack.html" title="Acknowledgements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref"></a>Boost.Ref</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jaakko</span> <span class="surname">Järvi</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Peter</span> <span class="surname">Dimov</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Douglas</span> <span class="surname">Gregor</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Dave</span> <span class="surname">Abrahams</span></h3></div></div><div><p class="copyright">Copyright © 1999, 2000 Jaakko Järvi</p></div><div><p class="copyright">Copyright © 2001, 2002 Peter Dimov</p></div><div><p class="copyright">Copyright © 2002 David Abrahams</p></div><div><div class="legalnotice"><p>Permission to copy, use, modify, sell and distribute this + software is granted provided this copyright notice appears in + all copies. This software is provided "as is" without express + or implied warranty, and with no claim as to its suitability for + any purpose. + </p></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="ref.html#ref.intro">Introduction</a></dt><dt><a href="ref.reference.html">Reference</a></dt><dd><dl><dt><a href="ref.reference.html#header.boost.ref.hpp">Header <boost/ref.hpp></a></dt></dl></dd><dt><a href="ref.ack.html">Acknowledgements</a></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref.intro"></a>Introduction</h2></div></div><div></div></div><p>The Ref library is a small library that is useful for passing + references to function templates (algorithms) that would usually + take copies of their arguments. It defines the class template + <tt class="computeroutput"><a href="id2833212.html" title="Class template reference_wrapper">boost::reference_wrapper<T></a></tt>, + the two functions + <tt class="computeroutput"><a href="id2833212.html#id2695067">boost::ref</a></tt> and + <tt class="computeroutput"><a href="id2833212.html#id2695106">boost::cref</a></tt> that return + instances of <tt class="computeroutput">boost::reference_wrapper<T></tt>, and the + two traits classes + <tt class="computeroutput"><a href="id2695148.html" title="Class template is_reference_wrapper">boost::is_reference_wrapper<T></a></tt> + and + <tt class="computeroutput"><a href="id2695230.html" title="Class template unwrap_reference">boost::unwrap_reference<T></a></tt>.</p><p>The purpose of + <tt class="computeroutput">boost::reference_wrapper<T></tt> is to + contain a reference to an object of type T. It is primarily used to + "feed" references to function templates (algorithms) that take their + parameter by value.</p><p>To support this usage, + <tt class="computeroutput">boost::reference_wrapper<T></tt> provides an implicit + conversion to <tt class="computeroutput">T&</tt>. This usually allows the function + templates to work on references unmodified.</p><p><tt class="computeroutput">boost::reference_wrapper<T></tt> is + both CopyConstructible and Assignable (ordinary references are not + Assignable).</p><p>The expression <tt class="computeroutput">boost::ref(x)</tt> + returns a + <tt class="computeroutput">boost::reference_wrapper<X>(x)</tt> where X + is the type of x. Similarly, + <tt class="computeroutput">boost::cref(x)</tt> returns a + <tt class="computeroutput">boost::reference_wrapper<X const>(x)</tt>.</p><p>The expression + <tt class="computeroutput">boost::is_reference_wrapper<T>::value</tt> + is true if T is a <tt class="computeroutput">reference_wrapper</tt>, and + false otherwise.</p><p>The type-expression + <tt class="computeroutput">boost::unwrap_reference<T>::type</tt> is T::type if T + is a <tt class="computeroutput">reference_wrapper</tt>, T otherwise.</p></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small></small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="function.testsuite.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ref.reference.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Testsuite </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Reference</td></tr></table></div></body></html> diff --git a/doc/html/ref.reference.html b/doc/html/ref.reference.html new file mode 100644 index 0000000000..ecdf6f3afe --- /dev/null +++ b/doc/html/ref.reference.html @@ -0,0 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Reference</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="ref.html" title="Boost.Ref"><link rel="previous" href="ref.html" title="Boost.Ref"><link rel="next" href="id2833212.html" title="Class template reference_wrapper"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="ref.reference.html#header.boost.ref.hpp" title="Header <boost/ref.hpp>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref.reference"></a>Reference</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="header.boost.ref.hpp"></a>Header <<a href="../../boost/ref.hpp" target="_top">boost/ref.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <a href="id2833212.html" title="Class template reference_wrapper"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> <span class="bold"><b>class</b></span> reference_wrapper;</a> + <a href="id2833212.html#id2695067">reference_wrapper<T> ref(T&)</a>; + <a href="id2833212.html#id2695106">reference_wrapper<T <span class="bold"><b>const</b></span>> cref(T <span class="bold"><b>const</b></span>&)</a>; + <a href="id2695148.html" title="Class template is_reference_wrapper"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> <span class="bold"><b>class</b></span> is_reference_wrapper;</a> + <a href="id2695230.html" title="Class template unwrap_reference"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> <span class="bold"><b>class</b></span> unwrap_reference;</a> +}</pre></div></div><table width="100%"><tr><td align="left"><small>Last revised: February 18, 2003 at 14:32:03 GMT</small></td><td align="right"><small>Copyright © 1999, 2000 Jaakko Järvi<br>Copyright © 2001, 2002 Peter Dimov<br>Copyright © 2002 David Abrahams</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="id2833212.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Boost.Ref </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template reference_wrapper</td></tr></table></div></body></html> diff --git a/doc/html/reference.css b/doc/html/reference.css new file mode 100644 index 0000000000..be4e64cc07 --- /dev/null +++ b/doc/html/reference.css @@ -0,0 +1,5 @@ +PRE.synopsis { + background-color: #e0ffff; + border: thin solid blue; + padding: 1em +} diff --git a/doc/html/signals.html b/doc/html/signals.html new file mode 100644 index 0000000000..41b6e9f6dd --- /dev/null +++ b/doc/html/signals.html @@ -0,0 +1,24 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Boost.Signals</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="index.html" title="The Boost C++ Libraries"><link rel="previous" href="ref.ack.html" title="Acknowledgements"><link rel="next" href="ch04s02.html" title="Tutorial"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="section" href="signals.html#id2888155" title="Introduction"><link rel="section" href="ch04s02.html" title="Tutorial"><link rel="section" href="signals.reference.html" title="Reference"><link rel="section" href="ch04s04.html" title="Frequently Asked Questions"><link rel="section" href="ch04s05.html" title="Design Overview"><link rel="section" href="ch04s06.html" title="Design Rationale"><link rel="section" href="ch04s07.html" title="Testsuite"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="signals"></a>Boost.Signals</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Douglas</span> <span class="surname">Gregor</span></h3></div></div><div><p class="copyright">Copyright © 2001-2003 Douglas Gregor</p></div><div><div class="legalnotice"><p>Permission to copy, use, sell and distribute this software + is granted provided this copyright notice appears in all copies. + Permission to modify the code and to distribute modified code is + granted provided this copyright notice appears in all copies, and + a notice that the code was modified is included with the copyright + notice. </p><p> This software is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any + purpose. </p></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="signals.html#id2888155">Introduction</a></dt><dt><a href="ch04s02.html">Tutorial</a></dt><dd><dl><dt><a href="ch04s02.html#id2888202">How to Read this Tutorial</a></dt><dt><a href="ch04s02.html#id2888275">Compatibility Note</a></dt><dt><a href="ch04s02.html#id2888425">Hello, World! (Beginner)</a></dt><dt><a href="ch04s02.html#id2888584">Calling multiple slots</a></dt><dd><dl><dt><a href="ch04s02.html#id2888590">Connecting multiple slots (Beginner)</a></dt><dt><a href="ch04s02.html#id2888807">Ordering slot call groups (Intermediate)</a></dt></dl></dd><dt><a href="ch04s02.html#id2889063">Passing values to and from slots</a></dt><dd><dl><dt><a href="ch04s02.html#id2889069">Slot Arguments (Beginner)</a></dt><dt><a href="ch04s02.html#id2889329">Signal Return Values (Advanced)</a></dt></dl></dd><dt><a href="ch04s02.html#id2890060">Connection Management</a></dt><dd><dl><dt><a href="ch04s02.html#id2890066">Disconnecting Slots (Beginner)</a></dt><dt><a href="ch04s02.html#id2890208">Scoped connections (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890264">Automatic connection management (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890510">When can disconnections occur? (Intermediate)</a></dt><dt><a href="ch04s02.html#id2890595">Passing slots (Intermediate)</a></dt></dl></dd></dl></dd><dt><a href="signals.reference.html">Reference</a></dt><dd><dl><dt><a href="signals.reference.html#header.boost.signal.hpp">Header <boost/signal.hpp></a></dt><dt><a href="signals.reference.html#id2895664">Header <boost/signals/slot.hpp></a></dt><dt><a href="signals.reference.html#id2900517">Header <boost/signals/trackable.hpp></a></dt><dt><a href="signals.reference.html#id2858799">Header <boost/signals/connection.hpp></a></dt><dt><a href="signals.reference.html#id2905340">Header <boost/visit_each.hpp></a></dt><dt><a href="signals.reference.html#id2875832">Header <boost/last_value.hpp></a></dt></dl></dd><dt><a href="ch04s04.html">Frequently Asked Questions</a></dt><dt><a href="ch04s05.html">Design Overview</a></dt><dd><dl><dt><a href="ch04s05.html#id2895772">Type Erasure</a></dt><dt><a href="ch04s05.html#id2895860">connection class</a></dt><dt><a href="ch04s05.html#id2895993">Slot Call Iterator</a></dt><dt><a href="ch04s05.html#id2896236">visit_each function template</a></dt></dl></dd><dt><a href="ch04s06.html">Design Rationale</a></dt><dd><dl><dt><a href="ch04s06.html#id2896415">Choice of Slot Definitions</a></dt><dt><a href="ch04s06.html#id2896550">User-level Connection Management</a></dt><dt><a href="ch04s06.html#id2811980">Combiner Interface</a></dt><dt><a href="ch04s06.html#id2897087">Connection Interfaces: += operator</a></dt><dt><a href="ch04s06.html#id2897291">trackable rationale</a></dt><dd><dl><dt><a href="ch04s06.html#id2897340">trackable copying behavior</a></dt><dt><a href="ch04s06.html#id2897409">Why derivation from trackable?</a></dt></dl></dd><dt><a href="ch04s06.html#id2897506">Comparison with other Signal/Slot implementations</a></dt><dd><dl><dt><a href="ch04s06.html#id2897514">libsigc++</a></dt><dt><a href="ch04s06.html#id2897600">.NET delegates</a></dt></dl></dd></dl></dd><dt><a href="ch04s07.html">Testsuite</a></dt><dd><dl><dt><a href="ch04s07.html#id2897667">Acceptance tests</a></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2888155"></a>Introduction</h2></div></div><div></div></div><p>The Boost.Signals library is an implementation of a managed +signals and slots system. Signals represent callbacks with multiple +targets, and are also called publishers or events in similar +systems. Signals are connected to some set of slots, which are +callback receivers (also called event targets or subscribers), which +are called when the signal is "emitted."</p><p>Signals and slots are managed, in that signals and slots (or, +more properly, objects that occur as part of the slots) track all +connections and are capable of automatically disconnecting signal/slot +connections when either is destroyed. This enables the user to make +signal/slot connections without expending a great effort to manage the +lifetimes of those connections with regard to the lifetimes of all +objects involved.</p><p>When signals are connected to multiple slots, there is a +question regarding the relationship between the return values of the +slots and the return value of the signals. Boost.Signals allows the +user to specify the manner in which multiple return values are +combined.</p></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small></small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.ack.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="index.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s02.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Acknowledgements </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Tutorial</td></tr></table></div></body></html> diff --git a/doc/html/signals.reference.html b/doc/html/signals.reference.html new file mode 100644 index 0000000000..35649bc393 --- /dev/null +++ b/doc/html/signals.reference.html @@ -0,0 +1,32 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Reference</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="The Boost C++ Libraries"><link rel="up" href="signals.html" title="Boost.Signals"><link rel="previous" href="ch04s02.html" title="Tutorial"><link rel="next" href="class.boost.signalN.html" title="Class template signalN"><link rel="chapter" href="any.html" title="Boost.Any"><link rel="refentry" href="class.boost.bad_any_cast.html" title="Class bad_any_cast"><link rel="refentry" href="class.boost.any.html" title="Class any"><link rel="refentry" href="id2827840.html" title="Function any_cast"><link rel="chapter" href="function.html" title="Boost.Function"><link rel="refentry" href="id2837192.html" title="Class bad_function_call"><link rel="refentry" href="class.boost.function_base.html" title="Class function_base"><link rel="refentry" href="class.boost.functionN.html" title="Class template functionN"><link rel="refentry" href="class.boost.function.html" title="Class template function"><link rel="chapter" href="ref.html" title="Boost.Ref"><link rel="refentry" href="id2833212.html" title="Class template reference_wrapper"><link rel="refentry" href="id2695148.html" title="Class template is_reference_wrapper"><link rel="refentry" href="id2695230.html" title="Class template unwrap_reference"><link rel="chapter" href="signals.html" title="Boost.Signals"><link rel="refentry" href="class.boost.signalN.html" title="Class template signalN"><link rel="refentry" href="class.boost.signal.html" title="Class template signal"><link rel="refentry" href="class.boost.slot.html" title="Class template slot"><link rel="refentry" href="id2852290.html" title="Class trackable"><link rel="refentry" href="id2890015.html" title="Class connection"><link rel="refentry" href="id2877648.html" title="Class scoped_connection"><link rel="refentry" href="id2905241.html" title="Function template visit_each"><link rel="refentry" href="class.boost.last_value.html" title="Class template last_value"><link rel="refentry" href="id2830650.html" title="Class last_value<void>"><link rel="subsection" href="signals.reference.html#header.boost.signal.hpp" title="Header <boost/signal.hpp>"><link rel="subsection" href="signals.reference.html#id2895664" title="Header <boost/signals/slot.hpp>"><link rel="subsection" href="signals.reference.html#id2900517" title="Header <boost/signals/trackable.hpp>"><link rel="subsection" href="signals.reference.html#id2858799" title="Header <boost/signals/connection.hpp>"><link rel="subsection" href="signals.reference.html#id2905340" title="Header <boost/visit_each.hpp>"><link rel="subsection" href="signals.reference.html#id2875832" title="Header <boost/last_value.hpp>"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table border="1" cellpadding="2" bgcolor="#007F7F"><tr><td bgcolor="#FFFFFF"><img src="../../c%2B%2Bboost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td><td><a href="../../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home</font></a></td><td><a href="../../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries</font></a></td><td><a href="../../people/people.htm"><font color="#FFFFFF" size="4" face="Arial">People</font></a></td><td><a href="../../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ</font></a></td><td><a href="../../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More</font></a></td></tr></table><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="signals.reference"></a>Reference</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="header.boost.signal.hpp"></a>Header <<a href="../../boost/signal.hpp" target="_top">boost/signal.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> R, <span class="bold"><b>typename</b></span> T1, <span class="bold"><b>typename</b></span> T2, ..., <span class="bold"><b>typename</b></span> TN, + <span class="bold"><b>typename</b></span> Combiner = <a href="class.boost.last_value.html" title="Class template last_value">last_value</a><R>, <span class="bold"><b>typename</b></span> Group = int, + <span class="bold"><b>typename</b></span> GroupCompare = std::less<Group>, + <span class="bold"><b>typename</b></span> SlotFunction = <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><R, T1, T2, ..., TN> > + <span class="bold"><b>class</b></span> <a href="class.boost.signalN.html" title="Class template signalN">signalN</a>; + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Signature, <span class="bold"><b>typename</b></span> Allocator = std::allocator<void>, + <span class="bold"><b>typename</b></span> Combiner = <a href="class.boost.last_value.html" title="Class template last_value">last_value</a><R>, <span class="bold"><b>typename</b></span> Group = int, + <span class="bold"><b>typename</b></span> GroupCompare = std::less<Group>, + <span class="bold"><b>typename</b></span> SlotFunction = <a href="class.boost.functionN.html" title="Class template functionN">functionN</a><Signature> > + <span class="bold"><b>class</b></span> <a href="class.boost.signal.html" title="Class template signal">signal</a>; +}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2895664"></a>Header <<a href="../../boost/signals/slot.hpp" target="_top">boost/signals/slot.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <a href="class.boost.slot.html" title="Class template slot"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> SlotFunction> <span class="bold"><b>class</b></span> slot;</a> +}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2900517"></a>Header <<a href="../../boost/signals/trackable.hpp" target="_top">boost/signals/trackable.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <span class="bold"><b>namespace</b></span> signals { + <a href="id2852290.html" title="Class trackable"><span class="bold"><b>class</b></span> trackable;</a> + } +}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2858799"></a>Header <<a href="../../boost/signals/connection.hpp" target="_top">boost/signals/connection.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <span class="bold"><b>namespace</b></span> signals { + <a href="id2890015.html" title="Class connection"><span class="bold"><b>class</b></span> connection;</a> + <a href="id2890015.html#id2883120"><span class="bold"><b>void</b></span> swap(connection&, connection&)</a>; + <a href="id2877648.html" title="Class scoped_connection"><span class="bold"><b>class</b></span> scoped_connection;</a> + } +}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2905340"></a>Header <<a href="../../boost/visit_each.hpp" target="_top">boost/visit_each.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> Visitor, <span class="bold"><b>typename</b></span> T> + <span class="bold"><b>void</b></span> <a href="id2905241.html" title="Function template visit_each">visit_each</a>(<span class="bold"><b>const</b></span> Visitor&, <span class="bold"><b>const</b></span> T&, <span class="bold"><b>int</b></span>); +}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2875832"></a>Header <<a href="../../boost/last_value.hpp" target="_top">boost/last_value.hpp</a>></h3></div></div><div></div></div><pre class="synopsis"><span class="bold"><b>namespace</b></span> boost { + <a href="class.boost.last_value.html" title="Class template last_value"><span class="bold"><b>template</b></span><<span class="bold"><b>typename</b></span> T> <span class="bold"><b>class</b></span> last_value;</a> + + <a href="id2830650.html" title="Class last_value<void>"><span class="bold"><b>template</b></span><> <span class="bold"><b>class</b></span> last_value<<span class="bold"><b>void</b></span>>;</a> +}</pre></div></div><table width="100%"><tr><td align="left"><small></small></td><td align="right"><small>Copyright © 2001-2003 Douglas Gregor</small></td></tr></table><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s02.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="signals.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="class.boost.signalN.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Tutorial </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Class template signalN</td></tr></table></div></body></html> diff --git a/google_logo_40wht.gif b/google_logo_40wht.gif Binary files differnew file mode 100644 index 0000000000..89789203e9 --- /dev/null +++ b/google_logo_40wht.gif diff --git a/index.htm b/index.htm new file mode 100644 index 0000000000..73f164f061 --- /dev/null +++ b/index.htm @@ -0,0 +1,461 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Boost C++ Libraries</title> + <meta name="generator" content="Microsoft FrontPage 5.0"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + </head> + <body bgcolor="#ffffff" text="#000000"> + <h1><img src="c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"> + Welcome to Boost.org!</h1> + <table> + <tr> + <td> + <table border="3" cellpadding="5" align="left"> + <tr> + <td> + <p><b>Libraries<br> + </b>. <a href="libs/libraries.htm">Documentation</a><br> + . <a href="more/download.html">Download</a><br> + . <a href="more/download.html#Installation">Install</a> & <a href="tools/build/index.html"> + Build<br> + </a>. Regression Tests:<br> + <a href="status/compiler_status.html">General + Info</a><br> + <a href="http://boost.sourceforge.net/regression-logs">Test Summary</a></p> + <p><b>Mailing Lists<br> + and newsgroups</b><br> + . <a href="more/mailing_lists.htm#main">Boost (Developers)</a><br> + . <a href="more/mailing_lists.htm#users">Boost Users</a><br> + . <a href="more/mailing_lists.htm#projects">Project-Specific</a><br> + . <a href="more/mailing_lists.htm#announce">Announcements</a><br> + . <a href="more/discussion_policy.htm">Discussion Policy</a></p> + <p><b>Support<br> + </b>. <a href="more/faq.htm">FAQ</a><br> + . <a href="http://sourceforge.net/tracker/?group_id=7586">Request Support</a><br> + . <a href="more/bugs.htm">Report Bugs</a><br> + . <a href="more/requesting_new_features.htm">Suggest Features</a><br> + . <a href="more/links.htm#Commercial%20Support">Commercial Support</a><br> + . Also: <a href="more/mailing_lists.htm">Mailing Lists</a></p> + <p><b>About<br> + </b>. <a href="more/formal_review_process.htm">Formal Reviews</a><b><br> + </b>. <a href="more/formal_review_schedule.html">Review Schedule<br> + </a>. <a href="more/lib_guide.htm#Requirements">Requirements</a><br> + . <a href="more/lib_guide.htm#Guidelines">Guidelines</a><br> + . <a href="more/submission_process.htm">Submissions</a></p> + <p><b>Other Resources<br> + </b>. <a href="http://www.yahoogroups.com/files/boost/">Files</a> (members + only)<br> + . <a href="more/download.html#CVS">Main CVS</a><br> + . <a href="more/mailing_lists.htm#sandbox">Sandbox CVS</a><br> + . <a href="tools/index.html">Tools</a><br> + . <a href="people/people.htm">People</a><br> + . <a href="more/moderators.html">Moderators</a><br> + . <a href="more/index.htm">More Boost...</a><br> + . <a href="more/links.htm#cpp">More C++...</a></p> + <p><b>Unofficial<br> + </b>. <a href="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl"> + Wiki</a><br> + . <a href="http://boost.c-view.org">Chinese mirror</a><br> + </p> + </td> + </tr> + </table> + <table> + <tr> + <td> </td> + <td> + <p>The Boost web site provides free peer-reviewed portable C++ source libraries. + The emphasis is on libraries which work well with the C++ Standard Library. One + goal is to establish "existing practice" and provide reference implementations + so that the Boost libraries are suitable for eventual standardization. Some of + the libraries have already been proposed for inclusion in the <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/"> + C++ Standards Committee</a>'s upcoming C++ Standard Library Technical + Report.</p> + <p>Although Boost was begun by members of the C++ Standards Committee Library + Working Group, membership has expanded to include nearly two thousand members + of the C++ community at large.</p> + <h2><a name="Membership">Membership</a></h2> + <p>If you are interested in becoming a member of Boost, please do so by joining our + main developers mailing list. Discussions include both technical and + site-related issues, and members are encouraged to participate in formal + reviews of proposed libraries. There is also a users mailing list.</p> + <p>Both the main Boost developers list and the users list are also accessible as <a href="more/mailing_lists.htm"> + newsgroups</a>.</p> + <h2>Search Boost</h2> + <!-- Search Google --> + <center> + <form method="get" action="http://www.google.com/custom"> + <table bgcolor="#ffffff" cellspacing="0" border="0"> + <tr valign="top"> + <td><a href="http://www.google.com/search"><img src="google_logo_40wht.gif" border="0" alt="Google" align="middle" width="128" height="53"></a></td> + <td><input type="text" name="q" size="31" maxlength="255"> <input type="submit" name="sa" value="Google Search"> + <input type="hidden" name="cof" value="LW:277;L:http://www.boost.org/c++boost.gif;LH:86;AH:center;GL:0;S:http://www.boost.org;AWFID:9b83d16ce652ed5a;"> + <font face="arial,sans-serif" size="-1"><input type="hidden" name="domains" value="lists.boost.org;www.boost.org"><br> + <input type="radio" name="sitesearch" value="www.boost.org" checked> Search + www.boost.org <input type="radio" name="sitesearch" value="lists.boost.org"> Search + lists.boost.org</font><br> + </td> + </tr> + </table> + </form> + </center> + <!-- Search Google --> + <h2><a name="Latest News">Latest News</a></h2> + +<p>August 19, 2003 - Version 1.30.2 (bugfix release)</p> + +<ul> + +<li><a href="http://www.boost-consulting.com">Boost Consulting</a> is now hosting +Boost CVS mirrors - see our <a href="more\download.html#CVS">download page</a>. +</li> + + +<li>Backported changes to the <a href="libs/config/config.htm">config system</a>, to +better handle new compiler releases. +</li> + +<li>Bugs in regression reporting in subproject tests were fixed. +</li> + +<li>Tests are now run in the context of the user's PATH environment settings +</li> + +<li><a href="tools/build/msvc-stlport-tools.html">msvc-stlport</a> and +<a href="tools/build/intel-win32-tools.html">intel-win32-stlport</a> toolsets now +build static libraries with multithreading enabled, to be compatible with the +STLPort builds. +</li> + +<li><a href="tools/build/intel-win32-tools.html">intel-win32</a> +toolset now handles <code>wchar_t</code> correctly when intel is installed over msvc6. + +<li>Backported fixes from the main trunk which prevent errors building the +<a href="libs/test/doc/index.htm">Boost.Test</a> library in its default configuration. +</li> + +<li>Backported portability improvements for +<a href="libs/utility/checked_delete.html">checked_delete</a>. +</li> + +<li> +Locale support for metrowerks (requiring a statically-linked runtime) is more uniformly handled. +</li> + +<li>Backported <a href="libs/conversion/lexical_cast.htm">conversion/lexical_cast</a>'s +<code>wchar_t</code> fixes from the main trunk. +</li> + +<li><a href="tools/build/intel-linux-tools.html">intel-linux-tools</a>: +added <code>rt</code> to FINDLIBS in order to make the <code>clock_gettime()</code> +function available (backport of a patch in CVS HEAD). +</li> + +<li><a href="tools\regression\index.htm">regression/compiler_status.cpp</a>: backported +fixes in error log links generation. +</li> + +</ul> + + <p>August 12, 2003 - <b>ALERT</b></p> + + <p>Significant problems were found in + the 1.30.1 release, so it has been + withdrawn from the website. These + problems mostly take the form of + missing files due to an error by the + release manager in using CVS to tag + the release. We expect to release + Version 1.30.2 in a few days. Stay + tuned. + + <p>Until then, you may want to get + the <code>RC_1_30_0</code> branch + (which, with only very slight + modification, will become version + 1.30.2) from our <a + href="more/download.html#CVS">CVS</a> + repository or the <a + href="more/download.html#CVS">CVS + mirror</a> at <a + href="http://www.boost-consulting.com">Boost + Consulting</a>. + + <p>August 4, 2003 - Version 1.30.1 (bugfix release)</p> + + Fixes were made to the following libraries: + + <ul> + <li>The <a + href="libs/lambda/doc/index.html">Boost.Lambda</a> + library is now usable with + gcc-2.95.2 + +<li><a + href="libs/spirit/index.html">Boost.Spirit</a>: +<ul> + <li> Fixed. Using MSVC++6 (SP5), calling the assign action with a string value on parsers +using the file_iterator will not work. + <li>Fixed: using assign semantic action in a grammar with a multi_pass iterator adaptor +applied to an std::istream_iterator resulted in a failure to compile under msvc 7.0. + <li> Fixed: There is a bug in the "range_run<CharT>::set (range<CharT> const& r)" function in +the "boost\spirit\utility\impl\chset\range_run.ipp". + <li>Fixed: handling of trailing whitespace bug (ast_parse/pt_parse related) + <li>Fixed: comment_p and end of data bug + <li>Fixed: Most trailing space bug: + <li>Fixed: + <code>chset<>::operator~(range<>)</code> bug, + <code>operator&(chset<>, range<>)</code> bug, + <code>operator&(range<>, chset<>)</code> bug, + <li> Fixed: <code>impl::detach_clear</code> bug + <li> Fixed: mismatch closure return type bug + <li> Fixed: <code>access_node_d[]</code> and <code>access_match_d[]</code> iterator bugs + <li>Fixed a bug regarding threadsafety of Phoenix/Spirit closures. + + </ul> + +<li>The Boost Template <a +href="libs/mpl/doc/index.html">Metaprogramming Library (MPL)</a>'s typeof implementation is now compatible with Metrowerks CodeWarrior Pro8. + +<li><a +href="libs/function/index.html">Boost.Function</a>: workaround for the new Borland patch (version 0x564) and MSVC++ .NET +2003. + +<li><a href="libs/config/index.html">Boost.Config</a>, <a href="libs/format/doc/format.html">Boost.Format</a>, and <a href="libs/regex/index.html">Boost.Regex</a> have been adjusted to avoid warnings with GCC-3.3, and Boost.Format also now works with string types other than <code>std::string</code>. + +<li><a href="libs/smart_ptr/index.htm">Smart Pointers</a> +<ul> + <li><code>checked_delete</code> now works on more platforms + <li>Compatibility with the SunPro compiler + <li>Added missing <code>#include</code>s. + </ul> + +<li><a href="libs/python/index.html">Boost.Python</a> + +<ul> + <li> warning +suppression for finicky compilers + <li> fixed a crashing bug in +the <code>raw_function</code> facility when no keyword arguments were +passed. + <li> Improved conversion of NULL <code>shared_ptr</code>s to Python. +</ul> + + + + </ul> + + + <p>March 19, 2003 - Version 1.30.0</p> + <ul> + <li> + <a href="libs/filesystem/doc/index.htm">Filesystem Library</a> + added - Portable paths, iteration over directories, and other useful filesystem + operations, from Beman Dawes. + <li> + <a href="libs/optional/doc/optional.html">Optional Library</a> + added - A discriminated-union wrapper for optional values, from Fernando + Cacciola. + <li> + <a href="libs/numeric/interval/doc/interval.htm">Interval Library</a> + added - Extends the usual arithmetic functions to mathematical intervals, from + Guillaume Melquiond, Hervé Brönnimann and Sylvain Pion. + <li> + <a href="libs/mpl/doc/index.html">MPL</a> + added - Template metaprogramming framework of compile-time algorithms, + sequences and metafunction classes, from Aleksey Gurtovoy. + <li> + <a href="libs/spirit/index.html">Spirit Library</a> + added - An LL (unlimited lookahead) parser framework that represents parsers + directly as EBNF grammars in inlined C++ source code, complete with semantic + actions, ASTs and much more, from Joel de Guzman and team. + <li> + <a href="libs/smart_ptr/index.htm">Smart Pointers Library</a> - cast functions are now + spelled <A href="libs/smart_ptr/shared_ptr.htm#static_pointer_cast">static_pointer_cast</A> + / <A href="libs/smart_ptr/shared_ptr.htm#dynamic_pointer_cast">dynamic_pointer_cast</A> + ; <A href="libs/smart_ptr/enable_shared_from_this.html">enable_shared_from_this</A> + added; shared_ptr::shared_ptr(), shared_ptr::reset(), weak_ptr::weak_ptr(), + weak_ptr::reset() no longer throw; <A href="libs/smart_ptr/shared_ptr.htm#get_deleter"> + get_deleter</A> added; weak_ptr::get() removed; make_shared is now spelled <A href="libs/smart_ptr/weak_ptr.htm#lock"> + weak_ptr::lock()</A> ; <A href="libs/smart_ptr/intrusive_ptr.html">intrusive_ptr + documentation</A> added; some experimental undocumented shared_ptr features + have been removed; a <A href="libs/smart_ptr/sp_techniques.html">page describing + some smart pointer programming techniques</A> + has been added. + <LI> + <A href="libs/utility/assert.html">boost/assert.hpp</A>, <A href="libs/utility/current_function.html"> + boost/current_function.hpp</A>, <A href="libs/utility/throw_exception.html">boost/throw_exception.hpp</A>, + <A href="libs/utility/checked_delete.html">boost/checked_delete.hpp</A> + have been documented. + <li> <a href="libs/date_time/doc/index.html">Date-Time Library</a> - several fixes and small additions including an interface change to partial_date. See <a href="libs/date_time/doc/Changes.html">Date-Time Change History</a> for more details. + </li> + <li> <a href="libs/function/index.html">Function Library</a> + - added support for assignment to zero (to clear) and comparison against zero (to check if empty). </li> + <li> + <a href="libs/utility/operators.htm#symmetry"> + Operators Library</a> - now takes advantage + of named return value optimization (NRVO) + when available, from Daniel Frey.</li> + <li> <a href="status/compiler_status.html"> + Regression Tests</a> - Much expanded, plus a + very nice + <a href="http://boost.sourceforge.net/regression-logs/"> + summary page</a> from Rene Rivera.</li> + <LI> <a href="libs/test/index.html">Test Library</a> + - introduced following new facilities: + <ul> + <li>Automatic registration of unit tests</li> + <li>XML log format</li> + <li>XML report format</li> + <li>BOOST_CHECK_NO_THROW test tool</li> + <li>BOOST_BITWISE_CHECK test tool</li> + </ul> + + For complete list of changes see Test Library <a href="libs/test/doc/release_notes.htm#v1_30_0">release notes</a> + + <li><a href="libs/libraries.htm">Documentation</a> for some Boost libraries has been converted to a new format allowing PDF and Unix man pages to be generated along with HTML.</li> + <li> + Many fixes and enhancements to other libraries.</li> + </ul> + <p>October 10, 2002 - Version 1.29.0</p> + <ul> + <li> + <a href="libs/date_time/doc/index.html">Date-Time Library</a> + added - Dates, times, leap seconds, infinity, and more, from Jeff Garland. + <li> + <a href="libs/dynamic_bitset/dynamic_bitset.html">Dynamic Bitset</a> added - A + runtime sized version of the <tt>std::bitset</tt> + class from Jeremy Siek and Chuck Allison. + <li> + <a href="libs/format/index.htm">Format Library</a> + added - Type-safe 'printf-like' format operations, from Samuel Krempp. + <li> + <a href="libs/function/index.html">Function Library</a>: Major syntactic + changes have been made. Some old syntax and little-used features have been + deprecated (and will be removed shortly), and the syntax for the <code>boost::function</code> + class template has been greatly improved on conforming compilers. Please see + the <a href="libs/function/index.html#compatibility">compatibility note</a> + for more information. + <li> + <a href="libs/multi_array/doc/index.html">Multi-array Library</a> + added - Multidimensional containers and adaptors for arrays of contiguous data, + from Ron Garcia. + <li> + <a href="libs/preprocessor/index.html">Preprocessor Library</a>: Major + upgrade, from Paul Mensonides. + <li> + <a href="libs/python/doc/index.html">Python Library</a> + - Version 2 is released, from Dave Abrahams and others. This is a major rewrite + which works on many more compilers and platforms, with a completely new + interface and lots of new features. Boost.Python v2 requires Python 2.2 or + later. + <li> + <a href="libs/signals/doc/index.html">Signals Library</a> + added - Managed signals & slots callback implementation, from Doug Gregor. + <li> + <a href="libs/test/doc/index.htm">Test Library</a>: Major new version, + including full unit test capabilities, from Gennadiy Rozental. + <li> + <a href="libs/numeric/ublas/doc/index.htm">uBLAS Library</a> added - Basic + linear algebra for dense, packed and sparse matrices, from Joerg Walter and + Mathias Koch.</li> + </ul> + <p>May 15, 2002 - Version 1.28.0</p> + <ul> + <li> + The Boost mailing lists are now also accessible as <a href="more/mailing_lists.htm#newsgroup"> + newsgroups</a>. + <li> + A powerful <a href="http://aspn.activestate.com/ASPN/Mail/Archives/boost/">mailing + list archive</a> has been contributed by the <a href="http://aspn.activestate.com/ASPN"> + ActiveState Programmer Network</a>. + <li> + <a href="libs/lambda/doc/index.html">Lambda Library</a> added, from Jaakko + Järvi and Gary Powell. Define small unnamed function objects at the actual call + site:<br> + <br> + <code> for_each(a.begin(), a.end(), std::cout << _1 + << ' ');</code><br> + + <li> + <a href="libs/io/doc/ios_state.html">I/O State Saver Library added</a> + - Save I/O state to prevent jumbled data, from Daryle Walker. + <li> + <a href="libs/config/config.htm">Configuration Library</a>: User code + should not use BOOST_NO_LIMITS. + <li> + <a href="libs/random/index.html">Random Number Library</a>: Avoid compiler + warnings + <li> + <a href="libs/smart_ptr/index.htm">Smart Pointers Library</a>: Added <a href="libs/smart_ptr/shared_ptr.htm#shared_polymorphic_cast"> + shared_polymorphic_cast</a> and <a href="libs/smart_ptr/shared_ptr.htm#shared_polymorphic_downcast"> + shared_polymorphic_downcast</a>. + <li> + <a href="libs/function/index.html">Function Library</a>: Now supports function + objects with the unary <code>&</code> + operator overloaded. + <li> + <a href="libs/utility/utility.htm">Utility Library</a>: Added <code>addressof()</code> + function. + <li> + The usual small fixes and tweaks.</li> + </ul> + <p>February 5, 2002 - Version 1.27.0</p> + <ul> + <li> + <a href="libs/python/doc/index.html">Python Library</a>: Scott Snyder + contributed inplace operator support. + <li> + <a href="libs/integer/index.htm">Integer Library</a>: Daryle Walker contributed + enhancements to the <a href="libs/integer/integer.htm">type selection templates</a>, + and added new compile-time <a href="libs/integer/doc/integer_mask.html">bit mask</a>, + <a href="libs/integer/doc/static_log2.html">binary logarithm</a>, and <a href="libs/integer/doc/static_min_max.html"> + extrema</a> + templates. + <li> + <a href="libs/function/index.html">Function Library</a>: user may request that <code> + boost::function</code> objects store a reference to a function object + target instead of a copy, using <a href="libs/bind/ref.html"><code>ref</code></a>. + Stateless objects are optimized so that they require no dynamic storage. + <li> + <a href="libs/math/quaternion/index.html">Quaternions</a>: added support + for GCC 2.95.x. + <li> + <a href="libs/math/octonion/index.html">Octonions</a>: added support for + GCC 2.95.x. + <li> + <a href="libs/smart_ptr/index.htm">Smart Pointers Library</a>: Peter Dimov + contributed a new implementation that fixes some bugs and adds some features + including <a href="libs/smart_ptr/compatibility.htm#threadsafe">thread safety</a> + when manipulating the use count, <a href="libs/smart_ptr/shared_ptr.htm#constructors"> + custom delete functions</a>, a new <a href="libs/smart_ptr/weak_ptr.htm">weak_ptr</a>, + and <a href="libs/smart_ptr/shared_ptr.htm#shared_static_cast">shared_static_cast</a> + and <a href="libs/smart_ptr/shared_ptr.htm#shared_dynamic_cast">shared_dynamic_cast</a>. + <li> + <a href="libs/preprocessor/doc/index.html">Preprocessor Library</a>: changed + macro prefix from BOOST_PREPROCESSOR to BOOST_PP, added support for list data + structure manipulation, added examples, made library ANSI C friendly, added + generalized <a href="libs/preprocessor/doc/ref/for.html">repetition</a> and <a href="libs/preprocessor/doc/ref/while.html"> + iteration</a> + primitives, improved reference manual. + <li> + <a href="libs/thread/doc/index.html">Threads Library:</a> + Mac Carbon implementation contributed by Mac Murrett. + <li> + Minor fixes to many libraries.</li> + </ul> + </td> + </tr> + </table> + </td> + </tr> + </table> + <hr> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d + %B, %Y" startspan -->12 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="28847" --></p> + </body> +</html> diff --git a/libs/any b/libs/any new file mode 160000 +Subproject 98de2fac59cf7dc3e55012c0124b924981731cd diff --git a/libs/array b/libs/array new file mode 160000 +Subproject 63c804495c4bfc4180880fca9530946910d5796 diff --git a/libs/bind b/libs/bind new file mode 160000 +Subproject 3a800816423aba79926261e6ae1920fa97fc768 diff --git a/libs/compatibility b/libs/compatibility new file mode 160000 +Subproject 917f309ee442cf4a733af8d238322ed916af2ae diff --git a/libs/compose b/libs/compose new file mode 160000 +Subproject f83d6927178c33a764a4fb5a211479ec463bb29 diff --git a/libs/concept_check b/libs/concept_check new file mode 160000 +Subproject 65f48a6cd6fa8eb07e445acafe8a89e4d1c6988 diff --git a/libs/config b/libs/config new file mode 160000 +Subproject 027a183e9992a0de17ad9ce6d915610dc76e22f diff --git a/libs/conversion b/libs/conversion new file mode 160000 +Subproject ae524a712c9e9f89a24d16aac9159a6b837e240 diff --git a/libs/crc b/libs/crc new file mode 160000 +Subproject 832f20e31f055917320e33cd7dfee0fb9d379b3 diff --git a/libs/date_time b/libs/date_time new file mode 160000 +Subproject 891503f7b2404272829894da6d23a116d73e875 diff --git a/libs/detail b/libs/detail new file mode 160000 +Subproject f01d63f8f77283d0048cb6eaacca62905b972d1 diff --git a/libs/disjoint_sets b/libs/disjoint_sets new file mode 160000 +Subproject 9273536db7d335df8622402984ad0f274171dc8 diff --git a/libs/dynamic_bitset b/libs/dynamic_bitset new file mode 160000 +Subproject 2b1fcc1e548b81be9da34908ec28d028a0be194 diff --git a/libs/exception b/libs/exception new file mode 160000 +Subproject ed51c3ce266932f8af4e7f4d9ef993c386534c5 diff --git a/libs/filesystem b/libs/filesystem new file mode 160000 +Subproject 0101f505cc30335f9f23a4244921314f77503c9 diff --git a/libs/format b/libs/format new file mode 160000 +Subproject 5f00d37f8eacaf524b3cb1faede8078868706b3 diff --git a/libs/function b/libs/function new file mode 160000 +Subproject e1e08b9e188e97bbc309059dc95a1c8c38d9de3 diff --git a/libs/functional b/libs/functional new file mode 160000 +Subproject dff0359e1d2af39fe8bd636a878ef5f0834cc94 diff --git a/libs/graph b/libs/graph new file mode 160000 +Subproject 892bc47bd628d7bc771433d8d83d05dd4f96d3a diff --git a/libs/index.html b/libs/index.html new file mode 100644 index 0000000000..94045cf1bf --- /dev/null +++ b/libs/index.html @@ -0,0 +1,9 @@ +<html> +<head> +<meta http-equiv="refresh" content="0; URL=libraries.htm"> +</head> +<body> +Automatic redirection failed, please go to +<a href="libraries.htm">libraries.htm</a>. +</body> +</html> diff --git a/libs/integer b/libs/integer new file mode 160000 +Subproject e48e347077ee2007e443617d6155ad686f5b5b4 diff --git a/libs/io b/libs/io new file mode 160000 +Subproject 074a89efcf5326e3c05b65c6fe331dd7c1b1e9c diff --git a/libs/iterator b/libs/iterator new file mode 160000 +Subproject bd7c13518b3ae3c5a34879cecb57783c5c99899 diff --git a/libs/lambda b/libs/lambda new file mode 160000 +Subproject ef8a7f4a317b164a38d75a90f5ec220dc8d278d diff --git a/libs/libraries.htm b/libs/libraries.htm new file mode 100644 index 0000000000..addb0fc125 --- /dev/null +++ b/libs/libraries.htm @@ -0,0 +1,507 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<title>Boost Libraries</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial">Home</font></a></td> + <td><a href="libraries.htm"><font color="#FFFFFF" + size="4" face="Arial">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial">People</font></a></td> + <td><a href="../more/faq.htm"><font color="#FFFFFF" + size="4" face="Arial">FAQ</font></a></td> + <td><a href="../more/index.htm"><font color="#FFFFFF" + size="4" face="Arial">More</font></a></td> + </tr> +</table> + +<h1>Boost Libraries</h1> +<p> +<a href="#Alphabetically">Libraries Listed Alphabetically</a><br> +<a href="#Category">Libraries Listed by Category<br> +</a> <a href="#String">String and text processing<br> +</a> <a href="#Containers">Containers<br> +</a> <a href="#Iterators">Iterators<br> +</a> <a href="#Algorithms">Algorithms<br> +</a> <a href="#Function-objects">Function Objects and +higher-order programming<br> +</a> <a href="#Generic">Generic Programming</a><br> + <a href="#Generic">Template +Metaprogramming</a><br> + <a href="#Preprocessor">Preprocessor Metaprogramming</a><a href="#Generic"><br> +</a> <a href="#Concurrent">Concurrent Programming</a><br> + <a href="#Math">Math and numerics<br> +</a> <a href="#Correctness">Correctness and testing<br> +</a> <a href="#Data">Data structures<br> +</a> <a href="#IO">Input/Output</a><a href="#Memory"><br> +</a> <a href="#Inter-language">Inter-language support</a><br> + <a href="#Memory">Memory</a><br> + <a href="#Parsing">Parsing</a><br> + <a href="#Miscellaneous">Miscellaneous</a><br> + <a href="#workarounds">Broken compiler workarounds</a><br> +<a href="#Obsolete">Obsolete Libraries</a><br> +<a href="#Beta">Beta Libraries</a></p> + +<p>See <a href="../status/compiler_status.html">Compiler Status</a> + page to find out what library works with which compiler.<br> +See <a href="hdr_depend.html">Header Dependencies</a> page to find +out what other headers each boost header includes.<br> +See <a href="../more/download.html">Download and Installation</a> page to find out +how to download and install the libraries.<br> +See <a href="../tools/build/index.html">Building Boost Libraries</a> page to find +out how to build object libraries, when needed.</p> + +<p>Documentation for some Boost libraries is available in alternative formats:</p> +<ul> + <li>PDF [<a href="http://boost.sourceforge.net/release/boost_1_30_doc_pdf.zip">zip</a>] [<a href="http://boost.sourceforge.net/release/boost_1_30_doc_pdf.tar.gz">tar.gz</a>] [<a href="http://boost.sourceforge.net/release/boost_1_30_doc_pdf.tar.bz2">tar.bz2</a>]</li> + <li>Unix man pages [<a href="http://boost.sourceforge.net/release/boost_1_30_doc_man.tar.gz">tar.gz</a>] [<a href="http://boost.sourceforge.net/release/boost_1_30_doc_man.tar.bz2">tar.bz2</a>]</li> +</ul> + +<hr> + +<h2>Libraries Listed <a name="Alphabetically">Alphabetically</a></h2> + +<ul> + <li><a href="any/index.html">any</a> - Safe, generic container for single + values of different value types, from Kevlin Henney. </li> + <li><a href="array/index.htm">array</a> - STL compliant + container wrapper for arrays of constant size, from + Nicolai Josuttis.</li> + <li><a href="bind/bind.html">bind</a> and <a href="bind/mem_fn.html"> mem_fn</a> - Generalized binders for function/object/pointers and member functions, from Peter + Dimov.</li> + <li><a href="utility/call_traits.htm">call_traits</a> - + Defines types for passing parameters, from John Maddock, + Howard Hinnant, et al.</li> + <li><a href="compatibility/index.html">compatibility</a> - Help for + non-conforming standard libraries, from Ralf Grosse-Kunstleve and Jens + Maurer.</li> + <li><a href="compose/index.htm">compose</a> - Functional + composition adapters for the STL, from Nicolai Josuttis.</li> + <li><a href="utility/compressed_pair.htm">compressed_pair</a> + - Empty member optimization, from John Maddock, Howard + Hinnant, et al.</li> + <li><a href="concept_check/concept_check.htm">concept check</a> + - Tools for generic programming, from Jeremy Siek.</li> + <li><a href="config/config.htm">config</a> - Helps boost + library developers adapt to compiler idiosyncrasies; not + intended for library users.</li> + <li><a href="conversion/index.htm">conversion</a> - Numeric, + polymorphic, and lexical casts, from Dave Abrahams and + Kevlin Henney.</li> + <li><a href="crc/index.html">crc</a> - Cyclic Redundancy Code, from Daryle + Walker.</li> + <li><a href="date_time/doc/index.html">date_time</a> - Date-Time library from Jeff Garland.</li> + <li><a href="dynamic_bitset/dynamic_bitset.html">dynamic_bitset</a> - A runtime sized version of <tt>std::bitset</tt> from Jeremy Siek and Chuck Allison.</li> + <li><a href="filesystem/doc/index.htm">filesystem</a> - Portable paths, + iteration over directories, and other useful filesystem operations, from + Beman Dawes.</li> + <li><a href="format/index.htm">format</a> - Type-safe 'printf-like' format + operations, from Samuel Krempp.</li> + <li><a href="function/index.html">function</a> - Function object wrappers + for deferred calls or callbacks, from Doug Gregor.</li> + <li><a href="functional/index.html">functional</a> - Enhanced + function object adaptors, from Mark Rodgers.</li> + <li><a href="graph/doc/table_of_contents.html">graph</a> - + Generic graph components and algorithms, from Jeremy Siek + and a University of Notre Dame team.</li> + <li><a href="integer/index.htm">integer</a> - Headers to ease + dealing with integral types.</li> + <li><a href="numeric/interval/doc/interval.htm">interval </a>- Extends the + usual arithmetic functions to mathematical intervals, from Guillaume + Melquiond, Hervé Brönnimann and Sylvain Pion.</li> + <li><a href="io/doc/ios_state.html">io state savers</a> - Save I/O state to + prevent jumbled data, from Daryle Walker.</li> + <li><a href="utility/iterator_adaptors.htm">iterator adaptors</a> + - Adapt a base type into a standard conforming iterator, + and more, from Dave Abrahams, Jeremy Siek, and John + Potter.</li> + <li><a href="lambda/doc/index.html">lambda</a> - Define small unnamed + function objects at the actual call site, and more, from Jaakko Järvi and + Gary Powell.</li> + <li><a href="math/doc/index.html">math</a> - Several contributions in the + domain of mathematics, from various authors.</li> + <li><a href="math/doc/common_factor.html">math/common_factor</a> - Greatest + common divisor and least common multiple, from Daryle Walker.</li> + <li><a href="math/octonion/index.html">math/octonion</a> - + Octonions, from Hubert Holin.</li> + <li><a href="math/quaternion/index.html">math/quaterion</a> - + Quaterions, from Hubert Holin.</li> + <li><a href="math/special_functions/index.html">math/special_functions</a> - + Mathematical special functions such as atanh, sinc, and sinhc, + from Hubert Holin.</li> + <li><a href="mpl/doc/index.html">mpl</a> - Template metaprogramming + framework of compile-time algorithms, sequences and metafunction classes, + from Aleksey Gurtovoy.</li> + <li><a href="multi_array/doc/index.html">multi_array</a> - Multidimensional + containers and adaptors for arrays of contiguous data, from Ron Garcia.</li> + <li><a href="utility/operators.htm">operators</a> - Templates + ease arithmetic classes and iterators, from Dave Abrahams + and Jeremy Siek.</li> + <li><a href="optional/doc/optional.html">optional</a> - Discriminated-union + wrapper for optional values, from Fernando Cacciola.</li> + <li><a href="pool/doc/index.html">pool</a> - Memory pool management, from + Steve Cleary.</li> + <li><a href="preprocessor/doc/index.html">preprocessor</a> - Preprocessor + metaprogramming tools including repetition and recursion, from Vesa Karvonen + and Paul Mensonides.</li> + <li><a href="property_map/property_map.html">property map</a> + - Concepts defining interfaces which map key objects to + value objects, from Jeremy Siek.</li> + <li><a href="python/doc/index.html">python</a> - Reflects C++ + classes and functions into <a + href="http://www.python.org">Python</a>, from Dave + Abrahams.</li> + <li><a href="random/index.html">random</a> - A complete + system for random number generation, from Jens Maurer.</li> + <li><a href="rational/index.html">rational</a> - A rational + number class, from Paul Moore.</li> + + <li><a href="bind/ref.html">ref</a> - A utility library for + passing references to generic functions, from Jaako Järvi, + Peter Dimov, Doug Gregor, and Dave Abrahams.</li> + + <li><a href="regex/index.htm">regex</a> - Regular expression + library, from John Maddock.</li> + <li><a href="signals/index.html">signals</a> - managed signals & + slots callback implementation, from Doug Gregor.</li> + <li><a href="smart_ptr/index.htm">smart_ptr</a> - Five smart + pointer class templates, from Greg Colvin, Beman Dawes, + Peter Dimov, and Darin Adler.</li> + <li><a href="static_assert/static_assert.htm">static_assert</a> + - Static assertions (compile time assertions), from John + Maddock.</li> + <li><a href="spirit/index.html">spirit</a> - LL parser framework + represents parsers directly as EBNF grammars in inlined C++, from Joel de + Guzman and team.</li> + <li><a href="test/doc/index.htm">test</a> - Support for simple program testing, + full unit testing, and for program + execution monitoring, from Gennadiy Rozental.</li> + <li><a href="thread/doc/index.html">thread</a> - Portable C++ + multi-threading, from William Kempf.</li> + <li><a href="timer/index.htm">timer</a> - Event timer, + progress timer, and progress display classes, from Beman + Dawes.</li> + <li><a href="tokenizer/index.htm">tokenizer</a> - Break of a string or other + character sequence into a series of tokens, from John Bandela.</li> + <li><a href="tuple/doc/tuple_users_guide.html">tuple</a> - Ease definition of functions returning multiple values, and more, + from Jaakko Järvi.</li> + <li><a href="type_traits/index.htm">type_traits</a> - + Templates for fundamental properties of types, from John + Maddock, Steve Cleary, et al.</li> + <li><a href="numeric/ublas/doc/index.htm">uBLAS</a> - Basic linear algebra + for dense, packed and sparse matrices, from Joerg Walter and Mathias Koch.</li> + <li><a href="utility/utility.htm">utility</a> - Class <b>noncopyable</b> + plus <b>checked_delete()</b>, <b>checked_array_delete()</b>, <b>next(),</b> + <b>prior()</b> + function templates, plus <b>base-from-member idiom</b>, from Dave Abrahams and others. </li> +</ul> + +<hr> + +<h2>Libraries Listed by <a name="Category">Category</a></h2> + +<h3><a name="String">String</a> and text processing</h3> + +<ul> + <li><a href="conversion/lexical_cast.htm">conversion/lexical_cast</a> - <tt>lexical_cast</tt> + class template, from Kevlin Henney.</li> + <li><a href="format/index.htm">format</a> - Type-safe 'printf-like' format + operations, from Samuel Krempp.</li> + <li><a href="regex/index.htm">regex</a> - Regular expression + library, from John Maddock</li> + <li><a href="spirit/index.html">spirit</a> - LL parser framework + represents parsers directly as EBNF grammars in inlined C++, from Joel de + Guzman and team.</li> + <li><a href="tokenizer/index.htm">tokenizer</a> - Break of a string or other + character sequence into a series of tokens, from John Bandela.</li> +</ul> + +<h3><a name="Containers">Containers</a></h3> + +<ul> + <li><a href="array/index.htm">array</a> - STL compliant + container wrapper for arrays of constant size, from + Nicolai Josuttis.</li> + <li><a href="dynamic_bitset/dynamic_bitset.html">dynamic_bitset</a> - A runtime sized version of <tt>std::bitset</tt> from Jeremy Siek and Chuck Allison.</li> + <li><a href="graph/doc/table_of_contents.html">graph</a> - + Generic graph components and algorithms, from Jeremy Siek + and a University of Notre Dame team.</li> + <li><a href="multi_array/doc/index.html">multi_array</a> - Multidimensional + containers and adaptors for arrays of contiguous data, from Ron Garcia.</li> + <li><a href="property_map/property_map.html">property map</a> + - Concepts defining interfaces which map key objects to + value objects, from Jeremy Siek.</li> +</ul> + +<h3><a name="Iterators">Iterators</a></h3> + +<ul> + <li><a href="graph/doc/table_of_contents.html">graph</a> - + Generic graph components and algorithms, from Jeremy Siek + and a University of Notre Dame team.</li> + <li><a href="utility/iterator_adaptors.htm">iterator adaptors</a> + - Adapt a base type into a standard conforming iterator, + and more, from Dave Abrahams, Jeremy Siek, and John + Potter.</li> + <li><a href="utility/operators.htm">operators</a> - Templates + ease arithmetic classes and iterators, from Dave Abrahams + and Jeremy Siek.</li> + <li><a href="tokenizer/index.htm">tokenizer</a> - Break of a string or other + character sequence into a series of tokens, from John Bandela.</li> +</ul> + +<h3><a name="Algorithms">Algorithms</a></h3> + +<ul> + <li><a href="graph/doc/table_of_contents.html">graph</a> - + Generic graph components and algorithms, from Jeremy Siek + and a University of Notre Dame team.</li> + <li><a href="utility/utility.htm">utility</a> - Class <b>next(),</b> <b>prior()</b> + function templates, from Dave Abrahams and others. </li> +</ul> + +<h3><a name="Function-objects">Function objects</a> and higher-order programming</h3> + +<ul> + <li><a href="bind/bind.html">bind</a> and <a href="bind/mem_fn.html"> mem_fn</a> - Generalized binders for function/object/pointers and member functions, from Peter Dimov.</li> + + <li><a href="compose/index.htm">compose</a> - Functional + composition adapters for the STL, from Nicolai Josuttis.</li> + <li><a href="function/index.html">function</a> - Function object wrappers + for deferred calls or callbacks, from Doug Gregor.</li> + <li><a href="functional/index.html">functional</a> - Enhanced + function object adaptors, from Mark Rodgers.</li> + <li><a href="lambda/doc/index.html">lambda</a> - Define small unnamed + function objects at the actual call site, and more, from Jaakko Järvi and + Gary Powell.</li> + + <li><a href="bind/ref.html">ref</a> - A utility library for + passing references to generic functions, from Jaako Järvi, + Peter Dimov, Doug Gregor, and Dave Abrahams.</li> + + <li><a href="signals/index.html">signals</a> - managed signals & + slots callback implementation, from Doug Gregor.</li> +</ul> + +<h3><a name="Generic">Generic</a> Programming</h3> + +<ul> + <li><a href="utility/call_traits.htm">call_traits</a> - + Defines types for passing parameters, from John Maddock, + Howard Hinnant, et al.</li> + <li><a href="concept_check/concept_check.htm">concept check</a> + - Tools for generic programming, from Jeremy Siek.</li> + <li><a href="utility/operators.htm">operators</a> - Templates + ease arithmetic classes and iterators, from Dave Abrahams + and Jeremy Siek.</li> + <li><a href="property_map/property_map.html">property map</a> + - Concepts defining interfaces which map key objects to + value objects, from Jeremy Siek.</li> + <li><a href="static_assert/static_assert.htm">static_assert</a> + - Static assertions (compile time assertions), from John + Maddock.</li> + <li><a href="type_traits/index.htm">type_traits</a> - + Templates for fundamental properties of types, from John + Maddock, Steve Cleary, et al.</li> +</ul> + +<h3>Template <a name="Metaprogramming"> Metaprogramming</a></h3> + +<ul> + <li><a href="mpl/doc/index.html">mpl</a> - Template metaprogramming + framework of compile-time algorithms, sequences and metafunction classes, + from Aleksey Gurtovoy.</li> + <li><a href="static_assert/static_assert.htm">static_assert</a> + - Static assertions (compile time assertions), from John + Maddock.</li> + <li><a href="type_traits/index.htm">type_traits</a> - + Templates for fundamental properties of types, from John + Maddock, Steve Cleary, et al.</li> +</ul> + +<h3><a name="Preprocessor">Preprocessor</a> Metaprogramming</h3> + +<ul> + <li><a href="preprocessor/doc/index.html">preprocessor</a> - Preprocessor + metaprogramming tools including repetition and recursion, from Vesa Karvonen + and Paul Mensonides.</li> +</ul> + +<h3><a name="Concurrent">Concurrent</a> Programming</h3> + +<ul> + <li><a href="thread/doc/index.html">thread</a> - Portable C++ + multi-threading, from William Kempf.</li> +</ul> + +<h3><a name="Math">Math</a> and numerics</h3> + +<ul> + <li><a href="math/doc/index.html">math</a> - Several contributions in the + domain of mathematics, from various authors.</li> + <li><a href="conversion/cast.htm">conversion/numeric_cast</a> - <tt>numeric_cast</tt> + class template, from Kevlin Henney.</li> + <li><a href="integer/index.htm">integer</a> - Headers to ease + dealing with integral types.</li> + <li><a href="numeric/interval/doc/interval.htm">interval </a>- Extends the + usual arithmetic functions to mathematical intervals, from Guillaume + Melquiond, Hervé Brönnimann and Sylvain Pion.</li> + <li><a href="math/doc/common_factor.html">math/common_factor</a> - Greatest + common divisor and least common multiple, from Daryle Walker.</li> + <li><a href="math/octonion/index.html">math/octonion</a> - + Octonions, from Hubert Holin.</li> + <li><a href="math/quaternion/index.html">math/quaterion</a> - + Quaterions, from Hubert Holin.</li> + <li><a href="math/special_functions/index.html">math/special_functions</a> - + Mathematical special functions such as atanh, sinc, and sinhc, + from Hubert Holin.</li> + <li><a href="multi_array/doc/index.html">multi_array</a> - Multidimensional + containers and adaptors for arrays of contiguous data, from Ron Garcia.</li> + <li><a href="utility/operators.htm">operators</a> - Templates + ease arithmetic classes and iterators, from Dave Abrahams + and Jeremy Siek.</li> + <li><a href="random/index.html">random</a> - A complete + system for random number generation, from Jens Maurer.</li> + <li><a href="rational/index.html">rational</a> - A rational + number class, from Paul Moore.</li> + <li><a href="numeric/ublas/doc/index.htm">uBLAS</a> - Basic linear algebra + for dense, packed and sparse matrices, from Joerg Walter and Mathias Koch.</li> +</ul> + +<h3><a name="Correctness">Correctness</a> and testing</h3> + +<ul> + <li><a href="concept_check/concept_check.htm">concept check</a> + - Tools for generic programming, from Jeremy Siek.</li> + <li><a href="static_assert/static_assert.htm">static_assert</a> + - Static assertions (compile time assertions), from John + Maddock.</li> + <li><a href="test/doc/index.htm">test</a> - Support for simple program testing, + full unit testing, and for program + execution monitoring, from Gennadiy Rozental.</li> +</ul> + +<h3><a name="Data">Data</a> structures</h3> + +<ul> + <li><a href="any/index.html">any</a> - Safe, generic container for single + values of different value types, from Kevlin Henney.</li> + <li><a href="utility/compressed_pair.htm">compressed_pair</a> + - Empty member optimization, from John Maddock, Howard + Hinnant, et al.</li> + <li><a href="tuple/doc/tuple_users_guide.html">tuple</a> - Ease definition of functions returning multiple values, and more, + from Jaakko Järvi.</li> +</ul> + +<h3><a name="IO">Input/Output</a></h3> +<ul> + <li><a href="format/index.htm">format</a> - Type-safe 'printf-like' format + operations, from Samuel Krempp.</li> + <li><a href="io/doc/ios_state.html">io state savers</a> - Save I/O state to + prevent jumbled data, from Daryle Walker.</li> +</ul> + +<h3><a name="Inter-language">Inter-language</a> support</h3> + +<ul> + <li><a href="python/doc/index.html">python</a> - Reflects C++ + classes and functions into <a + href="http://www.python.org">Python</a>, from Dave + Abrahams.</li> +</ul> + +<h3><a name="Memory">Memory</a></h3> + +<ul> + <li><a href="pool/doc/index.html">pool</a> - Memory pool management, from + Steve Cleary.</li> + <li><a href="smart_ptr/index.htm">smart_ptr</a> - Five smart + pointer class templates, from Greg Colvin, Beman Dawes, + Peter Dimov, and Darin Adler.</li> + <li><a href="utility/utility.htm">utility</a> - Class <b>noncopyable</b> + plus <b>checked_delete()</b>, <b>checked_array_delete()</b>, <b>next(),</b> + <b>prior()</b> + function templates, plus <b>base-from-member idiom</b>, from Dave Abrahams and others. </li> +</ul> + +<h3><a name="Parsing">Parsing</a></h3> + +<ul> + <li><a href="spirit/index.html">spirit</a> - LL parser framework + represents parsers directly as EBNF grammars in inlined C++, from Joel de + Guzman and team.</li> +</ul> + +<h3><a name="Miscellaneous">Miscellaneous</a></h3> + +<ul> + <li><a href="utility/base_from_member.html">base-from-member</a> - Idiom to + initialize a base class with a member, from Daryle Walker.</li> + <li><a href="utility/compressed_pair.htm">compressed_pair</a> + - Empty member optimization, from John Maddock, Howard + Hinnant, et al.</li> + <li><a href="conversion/index.htm">conversion</a> - Numeric, + polymorphic, and lexical casts, from Dave Abrahams and + Kevlin Henney.</li> + <li><a href="crc/index.html">crc</a> - Cyclic Redundancy Code, from Daryle + Walker.</li> + <li><a href="date_time/doc/index.html">date_time</a> - Date-Time library from Jeff Garland.</li> + <li><a href="filesystem/doc/index.htm">filesystem</a> - Portable paths, + iteration over directories, and other useful filesystem operations, from + Beman Dawes.</li> + <li><a href="optional/doc/optional.html">optional</a> - Discriminated-union + wrapper for optional values, from Fernando Cacciola.</li> + <li><a href="timer/index.htm">timer</a> - Event timer, + progress timer, and progress display classes, from Beman + Dawes.</li> + <li><a href="utility/utility.htm">utility</a> - Class <b>noncopyable</b> + plus <b>checked_delete()</b>, <b>checked_array_delete()</b>, <b>next(),</b> + <b>prior()</b> + function templates, plus <b>base-from-member idiom</b>, from Dave Abrahams and others. </li> +</ul> + +<h3>Broken compiler <a name="workarounds">workarounds</a></h3> + +<ul> + <li><a href="compatibility/index.html">compatibility</a> - Help for + non-conforming standard libraries, from Ralf Grosse-Kunstleve and Jens + Maurer.</li> + <li><a href="config/config.htm">config</a> - Helps boost + library developers adapt to compiler idiosyncrasies; not + intended for library users.</li> +</ul> + +<p>[Category suggestions from Aleksey Gurtovoy and Beman Dawes]</p> + +<hr> + +<h2><a name="Obsolete">Obsolete</a> Libraries</h2> + +<ul> + <li><a href="min_rand/index.htm">min_rand</a> - a random + number generator class from Beman Dawes. Replaced by <a + href="random/index.html">random</a>.</li> +</ul> + +<hr> + +<p>Revised +<!--webbot bot="Timestamp" s-type="EDITED" +s-format="%d %b %Y" startspan -->04 Feb 2003<!--webbot bot="Timestamp" endspan i-checksum="14388" --></p> +</body> +</html>
\ No newline at end of file diff --git a/libs/math b/libs/math new file mode 160000 +Subproject f0c1fd049f8998b42138ddca824398c0f5de421 diff --git a/libs/mpl b/libs/mpl new file mode 160000 +Subproject 5f3190f36ab04f3978dabbbf55ac66fb769a951 diff --git a/libs/multi_array b/libs/multi_array new file mode 160000 +Subproject 77b637777d2d42473d4eb00fd5d92a3f0c800ed diff --git a/libs/numeric/index.html b/libs/numeric/index.html new file mode 100644 index 0000000000..116646f253 --- /dev/null +++ b/libs/numeric/index.html @@ -0,0 +1,9 @@ +<html> +<head> +<meta http-equiv="refresh" content="0; URL=ublas/doc/index.htm"> +</head> +<body> +Automatic redirection failed, please go to +<a href="ublas/doc/index.htm">ublas/doc/index.htm</a>. +</body> +</html>
\ No newline at end of file diff --git a/libs/numeric/interval b/libs/numeric/interval new file mode 160000 +Subproject 66fc425474290996243ce5d8fa43f8c851667c7 diff --git a/libs/numeric/sublibs b/libs/numeric/sublibs new file mode 100644 index 0000000000..721d7c4a92 --- /dev/null +++ b/libs/numeric/sublibs @@ -0,0 +1 @@ +The existance of this file tells the regression reporting programs that the directory contains sub-directories which are libraries.
\ No newline at end of file diff --git a/libs/numeric/ublas b/libs/numeric/ublas new file mode 160000 +Subproject 2d0228a6d9839d4839c3578613c344a2f061418 diff --git a/libs/optional b/libs/optional new file mode 160000 +Subproject 20f9f6d2e9b05845652bdcd27a61bc313a17d60 diff --git a/libs/pool b/libs/pool new file mode 160000 +Subproject 709bfb809ea3aa108f7ad923d950106aef4e453 diff --git a/libs/preprocessor b/libs/preprocessor new file mode 160000 +Subproject 8018de965a627ff3e4c7d81f814c637797ed482 diff --git a/libs/property_map b/libs/property_map new file mode 160000 +Subproject 4cb9c5104736f38fdaaba7dc723f9aaa8e07e41 diff --git a/libs/python b/libs/python new file mode 160000 +Subproject 6a08750b23c858c5a54705a266a0b37f0577be3 diff --git a/libs/random b/libs/random new file mode 160000 +Subproject 65c8fecf3ffe6c0b760e52aaad73044c4df848c diff --git a/libs/rational b/libs/rational new file mode 160000 +Subproject 41c1e18e538f80e9afcf22ff292961990aa0bf5 diff --git a/libs/regex b/libs/regex new file mode 160000 +Subproject 136f8c02e0270767db4bfa4dc9e1158b94c60b6 diff --git a/libs/signals b/libs/signals new file mode 160000 +Subproject 5fa21417b162ed3194fa3c3feb4d496de8be7fa diff --git a/libs/smart_ptr b/libs/smart_ptr -Subproject c47f309991b83794f0f037a320dc223939d65b0 +Subproject da6c0c8dd5e6b49f949bc60e3574521b697aca7 diff --git a/libs/spirit b/libs/spirit new file mode 160000 +Subproject c45625a1c5f875d7034c60bea7452c2a0cba4b9 diff --git a/libs/static_assert b/libs/static_assert new file mode 160000 +Subproject a034d08143fdbe81fd5515d31cd034f096f6212 diff --git a/libs/test b/libs/test new file mode 160000 +Subproject e6eda03a8cf14ebfbb3a8fb3878d17a6e9903b4 diff --git a/libs/thread b/libs/thread new file mode 160000 +Subproject 4c5073b43de837be25ff95894236ca477b74c58 diff --git a/libs/timer b/libs/timer new file mode 160000 +Subproject c7a36839965246a4e54ff5b5bfcb1926de74ff6 diff --git a/libs/tokenizer b/libs/tokenizer new file mode 160000 +Subproject 4c8d76b56110432d6e39206d5b4dd1629ba57d9 diff --git a/libs/tuple b/libs/tuple new file mode 160000 +Subproject 193ae0d9243e30e3e5828826c30079fcf15880e diff --git a/libs/type_traits b/libs/type_traits new file mode 160000 +Subproject 2b3e3c765dd39f53edf9fe150adfff7038b24dc diff --git a/libs/utility b/libs/utility new file mode 160000 +Subproject df4b43a1bf39eac1c25e59d57a0bd1c979fa20f diff --git a/more/borland_cpp.html b/more/borland_cpp.html new file mode 100644 index 0000000000..14f5e3f271 --- /dev/null +++ b/more/borland_cpp.html @@ -0,0 +1,398 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Portability Hints: Borland C++ 5.5.1</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<p> + +<h1>Portability Hints: Borland C++ 5.5.1</h1> + +It is a general aim for boost libraries to be +<a href="lib_guide.htm#Portability">portable</a>. The primary means +for achieving this goal is to adhere to ISO Standard C++. However, +ISO C++ is a broad and complex standard and most compilers are +not fully conformant to ISO C++ yet. In order to achieve portability +in the light of this restriction, it seems advisable to get acquainted +with those language features that some compilers do not fully +implement yet. +<p> + +This page gives portability hints on some language features of the +Borland C++ version 5.5.1 compiler. Furthermore, the appendix +presents additional problems with Borland C++ version 5.5. Borland +C++ 5.5.1 is a freely available command-line compiler for Win32 +available at +<a href="http://www.borland.com/">http://www.borland.com/</a>. +<p> + +Each entry in the following list describes a particular issue, +complete with sample source code to demonstrate the effect. +Most sample code herein has been verified to compile with gcc 2.95.2 +and Comeau C++ 4.2.44. + + +<h2>Preprocessor symbol</h2> + +The preprocessor symbol <code>__BORLANDC__</code> is defined for all +Borland C++ compilers. Its value is the version number of the +compiler interpreted as a hexadecimal number. The following table +lists some known values. +<p> + +<table border="1"> +<tr> +<th>Compiler</th> +<th><code>__BORLANDC__</code> value</th> +</tr> + +<tr> +<td>Borland C++ Builder 4</td> +<td>0x0540</td> +</tr> + +<tr> +<td>Borland C++ Builder 5</td> +<td>0x0550</td> +</tr> + +<tr> +<td>Borland C++ 5.5</td> +<td>0x0550</td> +</tr> + +<tr> +<td>Borland C++ 5.5.1</td> +<td>0x0551</td> +</tr> + +<tr> +<td>Borland C++ Builder 6</td> +<td>0x0560</td> +</tr> + +</table> + +<h2>Core Language</h2> + +<h3>[using-directive] Mixing <code>using</code>-declarations and +<code>using</code>-directives</h3> + +Mixing <code>using</code>-directives (which refer to whole namespaces) +and namespace-level <code>using</code>-declarations (which refer to +individual identifiers within foreign namespaces) causes ambiguities +where there are none. The following code fragment illustrates this: + +<pre> +namespace N { + int x(); +} + +using N::x; +using namespace N; + +int main() +{ + &x; // Ambiguous overload +} +</pre> + + +<h3>[using template] <code>using</code>-declarations for class +templates</h3> + +Identifiers for class templates can be used as arguments to +<code>using</code>-declarations as any other identifier. However, the +following code fails to compile with Borland C++: + +<pre> +template<class T> +class X { }; + +namespace N +{ + // "cannot use template 'X<T>' without specifying specialization parameters" + using ::X; +}; +</pre> + + +<h3>[template const arg] Deduction of constant arguments to function +templates</h3> + +Template function type deduction should omit top-level constness. +However, this code fragment instantiates "f<const int>(int)": + +<pre> +template<class T> +void f(T x) +{ + x = 1; // works + (void) &x; + T y = 17; + y = 20; // "Cannot modify a const object in function f<const int>(int)" + (void) &y; +} + +int main() +{ + const int i = 17; + f(i); +} +</pre> + +The boost/rational.hpp header exhibits this problem in connection with +the gcd() function. + + +<h3>[function address] Resolving addresses of overloaded +functions</h3> + +Addresses of overloaded functions are not in all contexts properly +resolved (std:13.4 [over.over]); here is a small example: +<pre> +template<class Arg> +void f( void(*g)(Arg) ); + +void h(int); +void h(double); + +template<class T> +void h2(T); + +int main() +{ + void (*p)(int) = h; // this works (std:13.4-1.1) + void (*p2)(unsigned char) = h2; // this works as well (std:13.4-1.1) + f<int>(h2); // this also works (std:13.4-1.3) + + // "Cannot generate template specialization from h(int)", + // "Could not find a match for f<Arg>(void (*)(int))" + f<double>(h); // should work (std:13.4-1.3) + + f( (void(*)(double))h); // C-style cast works (std:13.4-1.6 with 5.4) + + // "Overloaded 'h' ambiguous in this context" + f(static_cast<void(*)(double)>(h)); // should work (std:13.4-1.6 with 5.2.9) +} +</pre> + +<strong>Workaround:</strong> Always use C-style casts when determining +addresses of (potentially) overloaded functions. + +<h3>[string conversion] Converting <code>const char *</code> to +<code>std::string</code></h3> + +Implicitly converting <code>const char *</code> parameters to +<code>std::string</code> arguments fails if template functions are +explicitly instantiated (it works in the usual cases, though): + +<pre> +#include <string> + +template<class T> +void f(const std::string & s) +{} + +int main() +{ + f<double>("hello"); // "Could not find a match for f<T>(char *)" +} + +</pre> + +<strong>Workaround:</strong> Avoid explicit template function +instantiations (they have significant problems with Microsoft Visual +C++) and pass default-constructed unused dummy arguments with the +appropriate type. Alternatively, if you wish to keep to the explicit +instantiation, you could use an explicit conversion to +<code>std::string</code> or declare the template function as taking a +<code>const char *</code> parameter. + + +<h3>[template value defaults] Dependent default arguments for template +value parameters</h3> + +Template value parameters which default to an expression dependent on +previous template parameters don't work: + +<pre> +template<class T> +struct A +{ + static const bool value = true; +}; + +// "Templates must be classes or functions", "Declaration syntax error" +template<class T, bool v = A<T>::value> +struct B {}; + +int main() +{ + B<int> x; +} + +</pre> + + +<strong>Workaround:</strong> If the relevant non-type template +parameter is an implementation detail, use inheritance and a fully +qualified identifier (for example, ::N::A<T>::value). + + +<h3>[function partial ordering] Partial ordering of function +templates</h3> + +Partial ordering of function templates, as described in std:14.5.5.2 +[temp.func.order], does not work: + +<pre> +#include <iostream> + +template<class T> struct A {}; + +template<class T1> +void f(const A<T1> &) +{ + std::cout << "f(const A<T1>&)\n"; +} + +template<class T> +void f(T) +{ + std::cout << "f(T)\n"; +} + +int main() +{ + A<double> a; + f(a); // output: f(T) (wrong) + f(1); // output: f(T) (correct) +} +</pre> + +<strong>Workaround:</strong> Declare all such functions uniformly as +either taking a value or a reference parameter. + + +<h3>[instantiate memfun ptr] Instantiation with member function pointer</h3> + +When directly instantiating a template with some member function +pointer, which is itself dependent on some template parameter, the +compiler cannot cope: +<pre> +template<class U> class C { }; +template<class T> +class A +{ + static const int v = C<void (T::*)()>::value; +}; +</pre> + +<strong>Workaround:</strong> Use an intermediate <code>typedef</code>: + +<pre> +template<class U> class C { }; +template<class T> +class A +{ + typedef void (T::*my_type)(); + static const int v = C<my_type>::value; +}; +</pre> + +(Extracted from e-mail exchange of David Abrahams, Fernando Cacciola, +and Peter Dimov; not actually tested.) + + +<h2>Library</h2> + + +<h3>[cmath.abs] Function <code>double std::abs(double)</code> +missing</h3> + +The function <code>double std::abs(double)</code> should be defined +(std:26.5-5 [lib.c.math]), but it is not: + +<pre> +#include <cmath> + +int main() +{ + double (*p)(double) = std::abs; // error +} +</pre> + +Note that <code>int std::abs(int)</code> will be used without warning +if you write <code>std::abs(5.1)</code>. +<p> +Similar remarks apply to seemingly all of the other standard math +functions, where Borland C++ fails to provide <code>float</code> and +<code>long double</code> overloads. +<p> +<strong>Workaround:</strong> Use <code>std::fabs</code> instead if +type genericity is not required. + +<h2>Appendix: Additional issues with Borland C++ version 5.5</h2> + +These issues are documented mainly for historic reasons. If you are +still using Borland C++ version 5.5, you are strongly encouraged to +obtain an upgrade to version 5.5.1, which fixes the issues described +in this section. + +<h3>[inline friend] Inline friend functions in template classes</h3> + +If a friend function of some class has not been declared before the +friend function declaration, the function is declared at the namespace +scope surrounding the class definition. Together with class templates +and inline definitions of friend functions, the code in the following +fragment should declare (and define) a non-template function "bool +N::f(int,int)", which is a friend of class N::A<int>. However, +Borland C++ v5.5 expects the function f to be declared beforehand: + +<pre> +namespace N { +template<class T> +class A +{ + // "f is not a member of 'N' in function main()" + friend bool f(T x, T y) { return x < y; } +}; +} + +int main() +{ + N::A<int> a; +} +</pre> + +This technique is extensively used in boost/operators.hpp. Giving in +to the wish of the compiler doesn't work in this case, because then +the "instantiate one template, get lots of helper functions at +namespace scope" approach doesn't work anymore. Defining +BOOST_NO_OPERATORS_IN_NAMESPACE (a define +BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this case +better) works around this problem and leads to another one, see +[using-template]. + +<p> + +<hr> + +2000-09-30 <a href="../people/jens_maurer.htm">Jens Maurer</a> +</body> +</html> diff --git a/more/bugs.htm b/more/bugs.htm new file mode 100644 index 0000000000..e8f37c28b4 --- /dev/null +++ b/more/bugs.htm @@ -0,0 +1,113 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head> + <meta http-equiv="Content-Language" content="en-us"> + + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Bugs</title> +</head> + + +<body bgcolor="#ffffff" text="#000000"> + +<table border="1" bgcolor="#007f7f" cellpadding="2"> + + <tbody><tr> + <td bgcolor="#ffffff"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#ffffff"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#ffffff"><big> + Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#ffffff"><big> + People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#ffffff"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#ffffff"><big>More</big></font></a></td> + </tr> +</tbody> +</table> + +<h1>What to do about Boost bugs</h1> + +<ol> + + <li>Make sure the bug isn't already fixed in the latest sources. The most + recent version of everything on the Boost web site is available from + the <a href="http://www.boost.org/more/download.html#CVS">boost public CVS + repository</a>.<br> +<br> + </li> + <li>If you are a Boost user, or a Boost developer that doesn't have a CVS + write access: <br> +<br> + <ol> + <li>Submit a bug report to either + <a href="http://www.boost.org/more/mailing_lists.htm#users">boost-users list</a>, + <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing + list</a>, or our <a href="http://sourceforge.net/tracker/?group_id=7586">bug + tracking facility</a> at SourceForge; submitting it to either of the mailing + lists is a preferred way - because many of the Boost developers read the + lists on a daily basis, this way you are likely to get a quicker response, + and the discussions that often arise there from (possible) bug reports are + quite interesting and educational as well;<br> +<br> + </li> + <li>If you have a proposed patch to the code, post it along with your bug + report, preferably in the <em>context diffs</em> format (<code>diff -c</code>); + if you can, send a patch relative to the current CVS state. A canonical +example of creating a patch file follows (let's assume that you've found +a bug in the file <code>intentional_bug.hpp</code>:<br> +<br> + <ol> + <li>Download the latest version of <code>intentional_bug.hpp</code> from CVS.</li> + <li>Make sure that the bug is still present in the code.</li> + <li>Copy the file <code>intentional_bug.hpp</code> to a file called <code>intentional_bug.hpp.orig</code>.</li> + <li>Apply your changes to <code>intentional_bug.hpp</code>.</li> + <li>Run "<code>diff -c intentional_bug.hpp.orig intentional_bug.hpp > intentional_bug.hpp.patch</code>" from the command prompt.</li> + <li>Submit the patch file together with an explanation of the bug +and the proposed fix; and don't forget to include the word <b>patch</b> or <b>bug</b> +in the subject if you're submitting to the <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing list</a>.<br> + <br> +</li> + </ol> + + </li> + + </ol> + </li> + <li>If you are a Boost developer, and you have a CVS write access: <br> +<br> + <ol> + <li>If the bug is trivial (e.g. misspelled name, missed <code>typename</code>, + etc.), and you are willing to make a fix, either make your changes locally + and contact the library author(s)/maintainer(s) about it, or go ahead and + check the fix into CVS, but post a notification about it to the + <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing + list</a> (if the author is not very active on the list, you also might want + to consider <code>cc</code>'ing him as well); <br> +<br> + </li> + <li>If the bug is non-trivial, and/or you don't have the time and resources to fix it, + submit a bug report (see p. 2 above); chances are that the maintainer(s) + will respond promptly and take care of the problem; <br> +<br> + </li> + <li>Otherwise, create a temporary branch in CVS, make your changes there, and + ask the library author(s)/maintainer(s) to review them; if they are ok with + the new code, either you or they can integrate the fixes into the main + trunk. </li> + </ol> + </li> +</ol> + +<hr> +<p>Contributed by <a href="../people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a></p> + +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 January, 2002<!--webbot bot="Timestamp" i-checksum="38453" endspan --> +</p> + + +<br> + +</body></html>
\ No newline at end of file diff --git a/more/count_bdy.htm b/more/count_bdy.htm new file mode 100644 index 0000000000..0dd6f0bc79 --- /dev/null +++ b/more/count_bdy.htm @@ -0,0 +1,1166 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<HTML> + +<HEAD> + + <TITLE>Counted Body Techniques</TITLE> + + <META NAME="GENERATOR" CONTENT="Microsoft FrontPage 4.0"> + + <META NAME="Author" CONTENT="Kevlin Henney"> + + <META NAME="KeyWords" CONTENT="C++, Reference Counting, Advanced Techniques, Smart Pointers, Patterns"> + +</HEAD> + +<BODY bgcolor="#FFFFFF" text="#000000"> + + + +<H1 ALIGN=CENTER><I><FONT SIZE=+4>Counted Body Techniques</FONT></I></H1> + + + +<CENTER><P><B><FONT SIZE=+1><a href="../people/kevlin_henney.htm">Kevlin Henney</a><BR> + +</FONT>(<A HREF="mailto:kevlin@acm.org">kevlin@acm.org</A>, <a HREF="mailto:khenney@qatraining.com">khenney@qatraining.com</a>)</B></P></CENTER> + + + +<UL> + +<P>Reference counting techniques? Nothing new, you might think. Every good + +C++ text that takes you to an intermediate or advanced level will introduce + +the concept. It has been explored with such thoroughness in the past that + +you might be forgiven for thinking that everything that can be said has + +been said. Well, let's start from first principles and see if we can unearth + +something new....</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>And then there were none...</H2> + + +<UL> + +<P>The principle behind reference counting is to keep a running usage count + +of an object so that when it falls to zero we know the object is unused. + +This is normally used to simplify the memory management for dynamically + +allocated objects: keep a count of the number of references held to that + +object and, on zero, delete the object.</P> + + + +<P>How to keep a track of the number of users of an object? Well, normal + +pointers are quite dumb, and so an extra level of indirection is required + +to manage the count. This is essentially the P<FONT SIZE=-1>ROXY</FONT> + +pattern described in <I>Design Patterns</I> [Gamma, Helm, Johnson & + +Vlissides, Addison-Wesley, <FONT SIZE=-1>ISBN </FONT>0-201-63361-2]. The + +intent is given as</P> + + + +<UL> + +<P><I>Provide a surrogate or placeholder for another object to control + +access to it.</I></P> + +</UL> + + + +<P>Coplien [<I>Advanced C++ Programming Styles and Idioms</I>, Addison-Wesley, + +<FONT SIZE=-1>ISBN </FONT>0-201-56365-7] defines a set of idioms related + +to this essential separation of a handle and a body part. The <I>Taligent + +Guide to Designing Programs </I>[Addison-Wesley, <FONT SIZE=-1>ISBN </FONT>0-201-40888-0] + +identifies a number of specific categories for proxies (aka surrogates). + +Broadly speaking they fall into two general categories:</P> + + + +<UL> + +<LI><I>Hidden</I>: The handle is the object of interest, hiding the body + +itself. The functionality of the handle is obtained by delegation to the + +body, and the user of the handle is unaware of the body. Reference counted + +strings offer a transparent optimisation. The body is shared between copies + +of a string until such a time as a change is needed, at which point a copy + +is made. Such a C<FONT SIZE=-1>OPY</FONT> <FONT SIZE=-1>ON</FONT> W<FONT SIZE=-1>RITE</FONT> + +pattern (a specialisation of L<FONT SIZE=-1>AZY</FONT> E<FONT SIZE=-1>VALUATION</FONT>) + +requires the use of a hidden reference counted body.</LI> + + + +<LI><I>Explicit</I>: Here the body is of interest and the handle merely + +provides intelligence for its access and housekeeping. In C++ this is often + +implemented as the S<FONT SIZE=-1>MART</FONT> P<FONT SIZE=-1>OINTER</FONT> + +idiom. One such application is that of reference counted smart pointers + +that collaborate to keep a count of an object, deleting it when the count + +falls to zero.</LI> + +</UL> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Attached vs detached</H2> + + +<UL> + +<P>For reference counted smart pointers there are two places the count + +can exist, resulting in two different patterns, both outlined in <I>Software + +Patterns</I> [Coplien, SIGS, <FONT SIZE=-1>ISBN </FONT>0-884842-50-X]:</P> + + + +<UL> + +<LI>C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> or A<FONT SIZE=-1>TTACHED</FONT> + +C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +places the count within the object being counted. The benefits are that + +countability is a part of the object being counted, and that reference + +counting does not require an additional object. The drawbacks are clearly + +that this is intrusive, and that the space for the reference count is wasted + +when the object is not heap based. Therefore the reference counting ties + +you to a particular implementation and style of use.</LI> + + + +<LI>D<FONT SIZE=-1>ETACHED</FONT> C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +places the count outside the object being counted, such that they are handled + +together. The clear benefit of this is that this technique is completely + +unintrusive, with all of the intelligence and support apparatus in the + +smart pointer, and therefore can be used on classes created independently + +of the reference counted pointer. The main disadvantage is that frequent + +use of this can lead to a proliferation of small objects, i.e. the counter, + +being created on the heap.</LI> + +</UL> + + + +<P>Even with this simple analysis, it seems that the D<FONT SIZE=-1>ETACHED</FONT> + +C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +approach is ahead. Indeed, with the increasing use of templates this is + +often the favourite, and is the principle behind the common - but not standard + +- <TT><FONT SIZE=+1>counted_ptr</FONT></TT>. +<I>[The Boost name is <a href="../libs/smart_ptr/shared_ptr.htm"><TT><FONT SIZE=+1>shared_ptr</FONT></TT></a> + +rather than <TT><FONT SIZE=+1>counted_ptr</FONT></TT>.]</I></P> + + + +<P>A common implementation of C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> + +is to provide the counting mechanism in a base class that the counted type + +is derived from. Either that, or the reference counting mechanism is provided + +anew for each class that needs it. Both of these approaches are unsatisfactory + +because they are quite closed, coupling a class into a particular framework. + +Added to this the non-cohesiveness of having the count lying dormant in + +a non-counted object, and you get the feeling that excepting its use in + +widespread object models such as COM and CORBA the C<FONT SIZE=-1>OUNTED</FONT> + +B<FONT SIZE=-1>ODY</FONT> approach is perhaps only of use in specialised + +situations.</P> + +</UL> + + + +<HR WIDTH="100%"> +<H2>A requirements based approach</H2> + + +<UL> + +<P>It is the question of openness that convinced me to revisit the problems + +with the C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> idiom. + +Yes, there is a certain degree of intrusion expected when using this idiom, + +but is there anyway to minimise this and decouple the choice of counting + +mechanism from the smart pointer type used?</P> + + + +<P>In recent years the most instructive body of code and specification + +for constructing open general purpose components has been the Stepanov + +and Lee's STL (Standard Template Library), now part of the C++ standard + +library. The STL approach makes extensive use of compile time polymorphism + +based on well defined operational requirements for types. For instance, + +each container, contained and iterator type is defined by the operations + +that should be performable on an object of that type, often with annotations + +describing additional constraints. Compile time polymorphism, as its name + +suggests, resolves functions at compile time based on function name and + +argument usage, i.e. overloading. This is less intrusive, although less + +easily diagnosed if incorrect, than runtime poymorphism that is based on + +types, names and function signatures.</P> + + + +<P>This requirements based approach can be applied to reference counting. + +The operations we need for a type to be <I>Countable</I> are loosely:</P> + + + +<UL> + +<LI>An <TT><FONT SIZE=+1>acquire</FONT></TT> operation that registers interest + +in a <I>Countable </I>object.</LI> + + + +<LI>A <TT><FONT SIZE=+1>release</FONT></TT> operation unregisters interest + +in a <I>Countable </I>object.</LI> + + + +<LI>An <TT><FONT SIZE=+1>acquired</FONT></TT> query that returns whether + +or not a <I>Countable </I>object is currently acquired.</LI> + + + +<LI>A <TT><FONT SIZE=+1>dispose</FONT></TT> operation that is responsible + +for disposing of an object that is no longer acquired.</LI> + +</UL> + + + +<P>Note that the count is deduced as a part of the abstract state of this + +type, and is not mentioned or defined in any other way. The openness of + +this approach derives in part from the use of global functions, meaning + +that no particular member functions are implied; a perfect way to wrap + +up an existing counted body class without modifying the class itself. The + +other aspect to the openness comes from a more precise specification of + +the operations.</P> + + + +<P>For a type to be <I>Countable</I> it must satisfy the following requirements, + +where <TT><FONT SIZE=+1>ptr</FONT></TT> is a non-null pointer to a single + +object (i.e. not an array) of the type, and <I><TT><FONT SIZE=+1>#function</FONT></TT></I> + +indicates number of calls to <TT><FONT SIZE=+1><I>function(</I>ptr<I>)</I></FONT></TT>:</P> + + + +<CENTER><TABLE BORDER=1 CELLSPACING=2 CELLPADDING=2 > + +<TR> + +<TD><I>Expression</I></TD> + + + +<TD><I>Return type</I></TD> + + + +<TD><I>Semantics and notes</I></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquire(ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>post</I>: <TT><FONT SIZE=+1>acquired(ptr)</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>release(ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>pre</I>: <TT><FONT SIZE=+1>acquired(ptr)<BR> + +</FONT></TT><I>post</I>: <TT><FONT SIZE=+1>acquired(ptr) == #acquire - + +#release</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquired(ptr)</FONT></TT></TD> + + + +<TD>convertible to <TT><FONT SIZE=+1>bool</FONT></TT></TD> + + + +<TD><I>return</I>: <TT><FONT SIZE=+1>#acquire > #release</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>dispose(ptr, ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>pre</I>: <TT><FONT SIZE=+1>!acquired(ptr)<BR> + +</FONT></TT><I>post</I>: <TT><FONT SIZE=+1>*ptr</FONT></TT> no longer usable</TD> + +</TR> + +</TABLE></CENTER> + + + +<P>Note that the two arguments to <TT><FONT SIZE=+1>dispose</FONT></TT> + +are to support selection of the appropriate type safe version of the function + +to be called. In the general case the intent is that the first argument + +determines the type to be deleted, and would typically be templated, while + +the second selects which template to use, e.g. by conforming to a specific + +base class.</P> + + + +<P>In addition the following requirements must also be satisfied, where + +<TT><FONT SIZE=+1>null</FONT></TT> is a null pointer to the <I>Countable</I> + +type:</P> + + + +<CENTER><TABLE BORDER=1 > + +<TR> + +<TD><I>Expression</I></TD> + + + +<TD><I>Return type</I></TD> + + + +<TD><I>Semantics and notes</I></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquire(null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>release(null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquired(null)</FONT></TT></TD> + + + +<TD>convertible to <TT><FONT SIZE=+1>bool</FONT></TT></TD> + + + +<TD><I>return</I>: <TT><FONT SIZE=+1>false</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>dispose(null, null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + +</TABLE></CENTER> + + + +<P>Note that there are no requirements on these functions in terms of exceptions + +thrown or not thrown, except that if exceptions are thrown the functions + +themselves should be exception safe.</P> + +</UL> + + + +<HR WIDTH="100%"> +<H2>Getting smart</H2> + + +<UL> + +<P>Given the <I>Countable</I> requirements for a type, it is possible to + +define a generic smart pointer type that uses them for reference counting:</P> + + + +<UL> +<PRE><TT>template<typename countable_type> +class countable_ptr +{ +public: // construction and destruction + + explicit countable_ptr(countable_type *); + countable_ptr(const countable_ptr &); + ~countable_ptr(); + +public: // access + + countable_type *operator->() const; + countable_type &operator*() const; + countable_type *get() const; + +public: // modification + + countable_ptr &clear(); + countable_ptr &assign(countable_type *); + countable_ptr &assign(const countable_ptr &); + countable_ptr &operator=(const countable_ptr &); + +private: // representation + + countable_type *body; + +}; +</TT></PRE> + +</UL> + + + +<P>The interface to this class has been kept intentionally simple, e.g. + +member templates and <TT><FONT SIZE=+1>throw</FONT></TT> specs have been + +omitted, for exposition. The majority of the functions are quite simple + +in implementation, relying very much on the <TT><FONT SIZE=+1>assign</FONT></TT> + +member as a keystone function:</P> + + + +<UL> + +<PRE><TT>template<typename countable_type> +countable_ptr<countable_type>::countable_ptr(countable_type *initial) + : body(initial) +{ + acquire(body); +} + +template<typename countable_type> +countable_ptr<countable_type>::countable_ptr(const countable_ptr &other) + : body(other.body) +{ + acquire(body); +} + +template<typename countable_type> +countable_ptr<countable_type>::~countable_ptr() +{ + clear(); +} + +template<typename countable_type> +countable_type *countable_ptr<countable_type>::operator->() const +{ + return body; +} + +template<typename countable_type> +countable_type &countable_ptr<countable_type>::operator*() const +{ + return *body; +} + +template<typename countable_type> +countable_type *countable_ptr<countable_type>::get() const +{ + return body; +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::clear() +{ + return assign(0); +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::assign(countable_type *rhs) +{ + // set to rhs (uses Copy Before Release idiom which is self assignment safe) + acquire(rhs); + countable_type *old_body = body; + body = rhs; + + // tidy up + release(old_body); + if(!acquired(old_body)) + { + dispose(old_body, old_body); + } + + return *this; +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::assign(const countable_ptr &rhs) +{ + return assign(rhs.body); +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::operator=(const countable_ptr &rhs) +{ + return assign(rhs); +} +</TT></PRE> + +</UL> + +</UL> + + + +<HR WIDTH="100%"> +<H2>Public accountability</H2> + + +<UL> + +<P>Conformance to the requirements means that a type can be used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>. + +Here is an implementation mix-in class (<I>mix-imp</I>) that confers countability + +on its derived classes through member functions. This class can be used + +as a class adaptor:</P> + + + +<UL> + +<PRE><TT>class countability +{ +public: // manipulation + + void acquire() const; + void release() const; + size_t acquired() const; + +protected: // construction and destruction + + countability(); + ~countability(); + +private: // representation + + mutable size_t count; + +private: // prevention + + countability(const countability &); + countability &operator=(const countability &); + +}; +</TT></PRE> + +</UL> + + + +<P>Notice that the manipulation functions are <TT><FONT SIZE=+1>const</FONT></TT> + +and that the <TT><FONT SIZE=+1>count</FONT></TT> member itself is <TT><FONT SIZE=+1>mutable</FONT></TT>. + +This is because countability is not a part of an object's abstract state: + +memory management does not depend on the <TT><FONT SIZE=+1>const</FONT></TT>-ness + +or otherwise of an object. I won't include the definitions of the member + +functions here as you can probably guess them: increment, decrement and + +return the current count, respectively for the manipulation functions. + +In a multithreaded environment you should ensure that such read and write + +operations are atomic.</P> + + + +<P>So how do we make this class <I>Countable</I>? A simple set of forwarding + +functions does the job:</P> + + + +<UL> + +<PRE><TT>void acquire(const countability *ptr) +{ + if(ptr) + { + ptr->acquire(); + } +} + +void release(const countability *ptr) +{ + if(ptr) + { + ptr->release(); + } +} + +size_t acquired(const countability *ptr) +{ + return ptr ? ptr->acquired() : 0; +} + +template<class countability_derived> +void dispose(const countability_derived *ptr, const countability *) +{ + delete ptr; +} +</TT></PRE> + +</UL> + + + +<P>Any type that now derives from <TT><FONT SIZE=+1>countability</FONT></TT> + +may now be used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>:</P> + + + +<UL> + +<PRE><TT>class example : public countability +{ + ... +}; + +void simple() +{ + countable_ptr<example> ptr(new example); + countable_ptr<example> qtr(ptr); + ptr.clear(); // set ptr to point to null +} // allocated object deleted when qtr destructs +</TT></PRE> +</UL> +</UL> + + + + +<HR WIDTH="100%"> +<H2>Runtime mixin</H2> + + +<UL> + +<P>The challenge is to apply C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> + +in a non-intrusive fashion, such that there is no overhead when an object + +is not counted. What we would like to do is confer this capability on a + +per object rather than on a per class basis. Effectively we are after <I>Countability + +</I>on any object, i.e. anything pointed to by a <TT><FONT SIZE=+1>void + +*</FONT></TT>! It goes without saying that <TT><FONT SIZE=+1>void</FONT></TT> + +is perhaps the least committed of any type.</P> + + + +<P>The forces to resolve on this are quite interesting, to say the least. + +Interesting, but not insurmountable. Given that the class of a runtime + +object cannot change dynamically in any well defined manner, and the layout + +of the object must be fixed, we have to find a new place and time to add + +the counting state. The fact that this must be added only on heap creation + +suggests the following solution:</P> + + + +<UL> + +<PRE><TT>struct countable_new; +extern const countable_new countable; + +void *operator new(size_t, const countable_new &); +void operator delete(void *, const countable_new &);</TT></PRE> +</UL> + + + +<P>We have overloaded <TT><FONT SIZE=+1>operator new</FONT></TT> with a + +dummy argument to distinguish it from the regular global <TT><FONT SIZE=+1>operator + +new</FONT></TT>. This is comparable to the use of the <TT><FONT SIZE=+1>std::nothrow_t</FONT></TT> + +type and <TT><FONT SIZE=+1>std::nothrow</FONT></TT> object in the standard + +library. The placement <TT><FONT SIZE=+1>operator delete</FONT></TT> is + +there to perform any tidy up in the event of failed construction. Note + +that this is not yet supported on all that many compilers.</P> + + + +<P>The result of a <TT><FONT SIZE=+1>new</FONT></TT> expression using <TT><FONT SIZE=+1>countable</FONT></TT> + +is an object allocated on the heap that has a header block that holds the + +count, i.e. we have extended the object by prefixing it. We can provide + +a couple of features in an anonymous namespace (not shown) in the implementation + +file for for supporting the count and its access from a raw pointer:</P> + + + +<UL> + +<PRE><TT>struct count +{ + size_t value; +}; + +count *header(const void *ptr) +{ + return const_cast<count *>(static_cast<const count *>(ptr) - 1); +} +</TT></PRE> + +</UL> + + + +<P>An important constraint to observe here is the alignment of <TT><FONT SIZE=+1>count</FONT></TT> + +should be such that it is suitably aligned for any type. For the definition + +shown this will be the case on almost all platforms. However, you may need + +to add a padding member for those that don't, e.g. using an anonymous <TT><FONT SIZE=+1>union</FONT></TT> + +to coalign <TT><FONT SIZE=+1>count</FONT></TT> and the most aligned type. + +Unfortunately, there is no portable way of specifying this such that the + +minimum alignment is also observed - this is a common problem when specifying + +your own allocators that do not directly use the results of either <TT><FONT SIZE=+1>new</FONT></TT> + +or <TT><FONT SIZE=+1>malloc</FONT></TT>.</P> + + + +<P>Again, note that the count is not considered to be a part of the logical + +state of the object, and hence the conversion from <TT><FONT SIZE=+1>const</FONT></TT> + +to non-<TT><FONT SIZE=+1>const</FONT></TT> - <TT><FONT SIZE=+1>count</FONT></TT> + +is in effect a <TT><FONT SIZE=+1>mutable</FONT></TT> type.</P> + + + +<P>The allocator functions themselves are fairly straightforward:</P> + + + +<UL> + +<PRE><TT>void *operator new(size_t size, const countable_new &) +{ + count *allocated = static_cast<count *>(::operator new(sizeof(count) + size)); + *allocated = count(); // initialise the header + return allocated + 1; // adjust result to point to the body +} + +void operator delete(void *ptr, const countable_new &) +{ + ::operator delete(header(ptr)); +} +</TT></PRE> + +</UL> + + + +<P>Given a correctly allocated header, we now need the <I>Countable </I>functions + +to operate on <TT><FONT SIZE=+1>const void *</FONT></TT> to complete the + +picture:</P> + + + +<UL> + +<PRE><TT>void acquire(const void *ptr) +{ + if(ptr) + { + ++header(ptr)->value; + } +} + +void release(const void *ptr) +{ + if(ptr) + { + --header(ptr)->value; + } +} + +size_t acquired(const void *ptr) +{ + return ptr ? header(ptr)->value : 0; +} + +template<typename countable_type> +void dispose(const countable_type *ptr, const void *) +{ + ptr->~countable_type(); + operator delete(const_cast<countable_type *>(ptr), countable); +} +</TT></PRE> + +</UL> + + + +<P>The most complex of these is the <TT><FONT SIZE=+1>dispose</FONT></TT> + +function that must ensure that the correct type is destructed and also + +that the memory is collected from the correct offset. It uses the value + +and type of first argument to perform this correctly, and the second argument + +merely acts as a strategy selector, i.e. the use of <TT><FONT SIZE=+1>const + +void *</FONT></TT> distinguishes it from the earlier dispose shown for + +<TT><FONT SIZE=+1>const countability *</FONT></TT>.</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Getting smarter</H2> + + + +<UL> + +<P>Now that we have a way of adding countability at creation for objects + +of any type, what extra is needed to make this work with the <TT><FONT SIZE=+1>countable_ptr</FONT></TT> + +we defined earlier? Good news: nothing!</P> + + + +<UL> + +<PRE><TT>class example +{ + ... +}; + +void simple() +{ + countable_ptr<example> ptr(new(countable) example); + countable_ptr<example> qtr(ptr); + ptr.clear(); // set ptr to point to null +} // allocated object deleted when qtr destructs +</TT></PRE> + +</UL> + + + +<P>The <TT><FONT SIZE=+1>new(countable)</FONT></TT> expression defines + +a different policy for allocation and deallocation and, in common with + +other allocators, any attempt to mix your allocation policies, e.g. call + +<TT><FONT SIZE=+1>delete</FONT></TT> on an object allocated with <TT><FONT SIZE=+1>new(countable)</FONT></TT>, + +results in undefined behaviour. This is similar to what happens when you + +mix <TT><FONT SIZE=+1>new[]</FONT></TT> with <TT><FONT SIZE=+1>delete</FONT></TT> + +or <TT><FONT SIZE=+1>malloc</FONT></TT> with <TT><FONT SIZE=+1>delete</FONT></TT>. + +The whole point of <I>Countable </I>conformance is that <I>Countable </I>objects + +are used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>, and this ensures + +the correct use.</P> + + + +<P>However, accidents will happen, and inevitably you may forget to allocate + +using <TT><FONT SIZE=+1>new(countable)</FONT></TT> and instead use <TT><FONT SIZE=+1>new</FONT></TT>. + +This error and others can be detected in most cases by extending the code + +shown here to add a check member to the <TT><FONT SIZE=+1>count</FONT></TT>, + +validating the check on every access. A benefit of ensuring clear separation + +between header and implementation source files means that you can introduce + +a checking version of this allocator without having to recompile your code.</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Conclusion</H2> + + + +<UL> + +<P>There are two key concepts that this article has introduced:</P> + + + +<UL> + +<LI>The use of a generic requirements based approach to simplify and adapt + +the use of the C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> pattern.</LI> + + + +<LI>The ability, through control of allocation, to dynamically and non-intrusively + +add capabilities to fixed types using the R<FONT SIZE=-1>UNTIME</FONT> + +M<FONT SIZE=-1>IXIN</FONT> pattern.</LI> + +</UL> + + + +<P>The application of the two together gives rise to a new variant of the + +essential C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> pattern, + +U<FONT SIZE=-1>NINTRUSIVE</FONT> C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT>. + +You can take this theme even further and contrive a simple garbage collection + +system for C++.</P> + + + +<P>The complete code for <TT><FONT SIZE=+1>countable_ptr</FONT></TT>, <TT><FONT SIZE=+1>countability</FONT></TT>, + +and the <TT><FONT SIZE=+1>countable new</FONT></TT> is also available.</P> + +</UL> + + + +<DIV ALIGN=right><P> + +<HR WIDTH="100%"><FONT SIZE=-1><I>First published in </I><a href="http://www.accu.org/c++sig/public/Overload.html">Overload</a> <I>25, + +April 1998, ISSN 1354-3172<BR> + +© Copyright Kevlin Henney, 1998, 1999</I></FONT></DIV> + + + +</BODY> + +</HTML> + diff --git a/more/cpp_committee_meetings.html b/more/cpp_committee_meetings.html new file mode 100644 index 0000000000..24cb74a8d4 --- /dev/null +++ b/more/cpp_committee_meetings.html @@ -0,0 +1,111 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<title>C++ Committee Meetings</title> +</head> + +<body bgcolor="#FFFFFF"> + +<h1>C++ Committee Meeting FAQ for Boost Members</h1> +<p><b>Who can attend C++ Committee meetings?</b> Members of +J16 (the INCITS/ANSI committee) or of a WG21 (ISO) member country committee +("national body" in +ISO-speak). <a href="http://www.ncits.org/"> +INCITS</a> has broadened J16 membership requirements so anyone can +join, regardless of nationality or employer.</p> +<p>In addition, a small number of "technical experts" who are not committee +members can also attend meetings. The "technical expert" umbrella is broad enough to cover +the +Boost members who attend meetings.</p> +<p><b>When and where is the next meeting?</b> See a general +<a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/meetings">list of locations and +dates</a>. Detailed information about a particular meeting, including hotel +information, is usually provided in a paper appearing in the <a href="#Mailing"> +pre- or post-meeting mailing</a> for the prior meeting. You will have to go to +the committee's <a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/">Papers +web page</a> and search a bit.</p> +<p><b>Is there a fee for attending meetings?</b> No, but there can be a lot of +incidental expenses like travel, lodging, and meals, and there is a $US 800 a +year INCITS fee to become a voting member.</p> +<p><b>What is the schedule?</b> The meetings start at 9:00AM on +Monday, and 8:30AM other days, unless otherwise announced. It is best to arrive +a half-hour early to grab a good seat, some coffee, tea, or donuts, and to say +hello to people. (There is also a Sunday evening a WG21 administrative meeting, +which is closed except to delegates from national bodies.)</p> +<p>The Friday meeting is generally over by 11:00AM. Because the Friday +meeting is for formal votes only, it is primarily of interest only to committee +members.</p> +<p>Sometimes there are evening technical sessions; the details aren't +usually available until the Monday morning meeting. There may be a +reception one evening, and, yes, significant others are +invited. Again, details usually become available Monday morning.</p> +<p><b>What actually happens at the meetings?</b> Monday morning an hour or two +is spent in full committee on administrivia, and then the committee breaks up +into working groups (Core, Library, and Enhancements). The full committee also +gets together later in the week to hear working group progress reports.</p> +<p>The working groups are where most technical activities take place. Each +active issue that appears on an issues list is discussed, as are papers from the +mailing. Most issues are non-controversial and disposed of in a few minutes. +Technical discussions are often led by long-term committee members, often +referring to past decisions or longstanding working group practice. Sometimes a +controversy erupts. It takes first-time attendees awhile to understand the +discussions and how decisions are actually made. The working group chairperson +moderates.</p> +<p>Sometimes straw polls are taken. In a straw poll anyone attending can vote, +in contrast to the formal votes taken by the full committee, where only voting +members can vote.</p> +<p>Lunch break is an hour and a half. Informal subgroups often lunch +together; a lot of technical problems are discussed or actually solved at lunch, +or later at dinner. In many ways these discussions involving only a few people +are the most interesting. Sometimes during the regular meetings, a working group +chair will break off a sub-group to tackle a difficult problem. </p> +<p><b>Do I have to stay at the main hotel?</b> No, and committee members on +tight budgets often stay at other, cheaper, hotels. (The main hotels are usually +chosen because they have large meeting rooms available, and thus tend to be pricey.) +The advantage of staying at the main hotel is that it is then easier to +participate in the off-line discussions which can be at least as interesting +as what actually happens in the scheduled meetings.</p> +<p><b>What do people wear at meetings?</b> Programmer casual. No neckties +to be seen. </p> +<p><b>What should I bring to a meeting?</b> It is very handy to have a laptop +computer along. There is normally a little network with Internet connectivity, +so bring your Ethernet adapter and a longish cable. There may be 802.11b, but +don't bet on it.</p> +<p><b>What should I do to prepare for a meeting?</b> It is helpful to have +downloaded the mailing or individual papers for the +meeting, and read any papers you are interested in. Familiarize yourself with +the issues lists if you haven't done so already. Decide which of the working +groups you want to attend.</p> +<p><b>What is a "<a name="Paper">Paper</a>"?</b> An electronic document containing issues, +proposals, or anything else the committee is interested in. Very little gets +discussed at a meeting, much less acted upon, unless it is presented in a paper. +<a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/">Papers are available</a> +to anyone. Papers don't just appear randomly; they become available four times a +year, before and after each meeting. Committee members often refer to a paper by +saying what mailing it was in: "See the pre-Redmond mailing."</p> +<p><b>What is a "<a name="Mailing">Mailing</a>"?</b> A mailing is the +set of papers prepared four times a year before and after each meeting. It +is physically just a +<a href="http://std.dkuug.dk/jtc1/sc22/wg21/docs/mailings/">.zip or .gz</a> +archive of +all the papers for a meeting. Although the mailing's archive file itself is only available to committee members and technical +experts, the contents (except copies of the standard) are available to the +general public as individual papers. The ways of ISO are +inscrutable.</p> +<p><b>What is a "Reflector"?</b> The committee's mailing lists are +called "reflectors". There are a number of them; "all", "core", "lib", and "ext" +are the main ones. As a courtesy, Boost technical experts can be added to +committee reflectors at the request of a committee member. </p> +<hr> +<p>© Copyright Beman Dawes, 2002</p> +<p>Revised +<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->September 09, 2002<!--webbot bot="Timestamp" endspan i-checksum="38011" --></p> +<p> </p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/discussion_policy.htm b/more/discussion_policy.htm new file mode 100644 index 0000000000..f28f1156cc --- /dev/null +++ b/more/discussion_policy.htm @@ -0,0 +1,126 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Discussion Policy</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Discussion Policy</h1> +<p>Email discussion is the tie that binds boost members together into a community. +If the discussion is stimulating and effective, the community thrives. If +the discussion degenerates into name calling and ill will, the community withers +and dies.</p> +<h2>Acceptable topics</h2> +<ul> + <li>Queries to determine interest in a possible library submission.</li> + <li>Technical discussions about a proposed or existing library, including bug + reports and requests for help.</li> + <li>Formal Reviews of proposed libraries.</li> + <li>Reports of user experiences with Boost libraries.</li> + <li>Boost administration or policies.</li> + <li>Compiler specific workarounds as applied to Boost libraries.</li> +</ul> +<p>Other topics related to boost development may be acceptable, at the discretion of moderators. If unsure, go ahead and post. The moderators +will let you know.</p> +<h2>Unacceptable topics</h2> +<ul> + <li>Advertisements for commercial products.</li> + <li>Requests for help getting non-boost code to compile with your compiler. + Try the comp.lang.c++.moderated newsgroup instead.</li> + <li>Requests for help interpreting the C++ standard. Try the comp.std.c++ + newsgroup instead.</li> + <li>Job offers.</li> + <li>Requests for solutions to homework assignments.</ul> +<h2>Message size</h2> +<p>The mailing list software automatically limits message and attachment size to +a reasonable amount, typically 75K, which is adjusted from time-to-time by the +moderators.. This limit is a courtesy to those who rely on dial-up Internet +access.</p> +<h2>Prohibited behavior</h2> +<p>Prohibited behavior will not be tolerated. The moderators will ban +postings by abusers.</p> +<h3>Flame wars</h3> +<p>Personal insults, argument for the sake of argument, and all the other +behaviors which fall into the "flame war" category are +prohibited. Discussions should focus on technical arguments, not the +personality traits or motives of participants.</p> +<h3>Third-party attacks</h3> +<p>Attacks on third parties such as software vendors, hardware vendors, or any +other organizations, are prohibited. Boost exists to unite and serve the +entire C++ community, not to disparage the work of others.</p> +<p>Does this mean that we ban the occasional complaint or wry remark about a +troublesome compiler? No, but be wary of overdoing it.</p> +<h3>Off-topic posts</h3> +<p>Discussions which stray from the acceptable topics are strongly discouraged. +While off-topic posts are often well meaning and not as individually corrosive +as other abuses, cumulatively the distraction damages the effectiveness of +discussion.</p> +<h2>Culture</h2> +<p>In addition to technical skills, Boost members value collaboration, +acknowledgement of the help of others, and a certain level of politeness. Boost +membership is very international, and ranges widely in age and other +characteristics. Think of discussion as occurring among colleagues in a widely read forum, rather +than among a few close friends.</p> + +<p>Always remember that the cumulative effort spent by people reading +your contribution scales with the (already large) number of boost +members. Thus, do invest time and effort to make your message as +readable as possible. Adhere to English syntax and grammar rules such +as proper capitalization. Avoid copious informalism, colloquial +language, or abbreviations, they may not be understood by all readers. +Re-read your message before submitting it.</p> + +<h2>Guidelines for effective discussions</h2> +<p>Apply social engineering to prevent heated technical discussion from +degenerating into a shouting match, and to actively encourage the cooperation +upon which Boost depends.</p> +<ul> + <li>Questions help. If someone suggests something that you don't think + will work, then replying with a question like "will that compile?" + or "won't that fail to compile, or am I missing something?" is a + lot smoother than "That's really stupid - it won't compile." + Saying "that fails to compile for me, and seems to violate section + n.n.n of the standard" would be yet another way to be firm without + being abrasive.</li> + <li>If most of the discussion has been code-free generalities, posting a bit + of sample code can focus people on the practical issues.</li> + <li>If most of the discussion has been in terms of specific code, try to talk + a bit about hidden assumptions and generalities that may be preventing + discussion closure.</li> + <li>Taking a time-out is often effective. Just say: "Let me think + about that for a day or two. Let's take a time-out to digest the + discussion so far."</li> +</ul> +<p>Avoid Parkinson's Bicycle Shed. Parkinson described a committee formed +to oversee design of an early nuclear power plant. There were three agenda +items - when to have tea, where to put the bicycle shed, and how to +ensure nuclear safety. Tea was disposed of quickly as trivial. +Nuclear safety was discussed for only +an hour - it was so complex, scary, and technical that even +among experts few felt comfortable with the issues. Endless days were then +spent discussing where to put the bicycle shed (the parking lot would +be a modern equivalent) because everyone +understood the issues and felt comfortable discussing them. </p> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->13 May, 2002<!--webbot bot="Timestamp" i-checksum="13969" endspan --> +</p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/download.html b/more/download.html new file mode 100644 index 0000000000..0c12967eec --- /dev/null +++ b/more/download.html @@ -0,0 +1,178 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<html> + <head> + <meta name="generator" content= + "Microsoft FrontPage 5.0"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + + <title>Boost Download and Installation</title> + </head> + + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt= + "c++boost.gif (8819 bytes)" width="277" height="86"></td> + + <td><a href="../index.htm"><font face="Arial,Helvetica" color= + "#FFFFFF"><big>Home</big></font></a></td> + + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" + color="#FFFFFF"><big>Libraries</big></font></a></td> + + <td><a href="../people/people.htm"><font face="Arial,Helvetica" + color="#FFFFFF"><big>People</big></font></a></td> + + <td><a href="faq.htm"><font face="Arial,Helvetica" color= + "#FFFFFF"><big>FAQ</big></font></a></td> + + <td><a href="index.htm"><font face="Arial,Helvetica" color= + "#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + + <h1>Boost Download and Installation</h1> + The boost libraries are intended for easy download and <a href= + "#Installation">installation</a>; many libraries require nothing more + that downloading and unpacking to be ready for use, including full + documentation. When required, see <a href= + "../tools/build/index.html">Building Boost Libraries</a> to create object + libraries. + + <h2>Download</h2> + <p>Click here to <b> + <a href="http://sourceforge.net/project/showfiles.php?group_id=7586"> + <font size="4">download releases from SourceForge</font></a></b>. </p> + <p>The Boost release includes all of the libraries and other material from + the web site. It is available in <a href="#.zip">ZIP</a> or + <a href="#.tar.gz">TAR.GZ</a> formats. Past releases are also available.</p> + It is also possible to download current snapshots of work-in-progress from + Boost's <a href="#CVS">CVS repository</a>.<h3><a name=".zip">.zip</a> file</h3> + The .zip format is widely supported by both free decoders and commercial + compress/archive utilities. If you don't already have a .zip file + decoder, download one from the <a href= + "http://www.info-zip.org/">Info-ZIP</a> web site, which supplies versions + for many operating systems. + + <p>Text file line endings in the .zip file are as supplied by each + library developer. This works fine for Windows, but not for + Unix/Linux. The .tar.gz file supplies Unix/Linux friendly line + endings.</p> + + <h3><a name=".tar.gz">.tar.gz</a> file</h3> + The .tar.gz format is widely supported on Unix/Linux platforms. Some + Windows compress/archive utilities can read the format as well. + Because the gzip format compresses the archive as a single file rather + than compressing each file individually, the .tar.gz file is smaller that + the .zip file. + + <p>Text file line endings in the .tar.gz file have been converted to + newlines for ease of use on Unix/Linux platforms.</p> + + <h2>Boost <a name="CVS">CVS</a> Repository</h2> + + <p>All Boost files, including the entire distribution tree including web + site HTML is maintained in a CVS repository. Command line, GUI, or browser + access is available.</p> + + <h3>Boost CVS access via command line or graphical clients</h3> + For those who have CVS clients installed, the libraries are also + available from the public <a href= + "http://sourceforge.net/cvs/?group_id=7586">Boost CVS repository</a>. Free + command line clients (often already installed on Linux/Unix systems) are + available for many systems, and free GUI clients are available for Windows, + Mac, and other systems.<p>See the much improved + <a href="http://sourceforge.net/docman/?group_id=1">CVS documentation</a> + (Section F) from SourceForge, which includes links to the home pages for various + GUI and command line clients.</p> + + <p>The general procedure for command-line clients is something like + this:</p> + + <blockquote> + <code>cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost + login</code><br> + [Hit <return> when it asks for a password]<br> + <code>cvs -z3 + -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost checkout + boost<br> + cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost + logout</code> + </blockquote> + Read the manual for your CVS client for further information. + + <p>This access is read-only; if you are a library author and wish to have + CVS write access, please contact one of the <a href= + "mailto:boost-owner@yahoogroups.com">moderators</a>.</p> + + <p>Because SourceForge has been having some trouble managing the + load of anonymous CVS users, <a + href="http://www.boost-consulting.com">Boost Consulting</a> is + hosting three mirrors: + +<ol> + <li> + the Boost anonymous CVS tree, updated nightly. Access it as + follows: + +<pre> + cvs -d :pserver:anonymous@boost-consulting.com:/boost login + <i>no password; just hit return</i> + + cvs -d :pserver:anonymous@boost-consulting.com:/boost checkout boost +</pre> + + <li>A <a + href="http://www.boost-consulting.com/boost.tar.bz2">bzipped + tarball</a> snapshot of the current Boost CVS state, updated + hourly. + + <li>A <a href="http://www.boost-consulting.com:/boost">browsable + image</a> of the current Boost CVS state, updated hourly. + </ol> + + <h3>Boost CVS access via web <a name="Browser">Browser</a></h3> + For access to the CVS archive from any modern web browser, you can also + use the <a href= + "http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost/boost/">web + browser interface</a>. Try one of the color diffs to see how + a file has changed over time. + + <h2><a name="Installation">Installation</a></h2> + Boost does not yet have a standardized installation process. There has + been some interest in developing one; as of this writing <a href= + "../people/william_kempf.htm">Bill Kempf</a> has volunteered to + coordinate and is gathering volunteers. If you have expertise in this + area (particularly cross-platform expertise), and you would like to + contribute, please announce your availability on the <a href= + "http://lists.boost.org/mailman/listinfo.cgi/boost-install">Boost + Install</a> mailing list. + + <p>That said, preparing to use Boost in a development project is + relatively straightforward. Most boost libraries are implemented entirely + within their header files. The only preparation for their use is to add + the boost root directory to your compiler's list of + <code>#include<...></code> search paths. For example, using Windows + 2000, if you have unzipped release 1.28.0 from boost_all.zip into the top + level directory of your C drive, adding '-Ic:/boost_1_28_0' to the + command line of most compilers is sufficient.</p> + + <p>The <a href="../libs/python/doc/index.html">Python</a>, <a href= + "../libs/regex/index.htm">Regex</a>, and <a href= + "../libs/thread/doc/index.html">Threads</a> libraries are implemented in + part as separate source files, and thus require compilation before use. + See <a href="../tools/build/index.html">Building Boost Libraries</a> for + an automatic tool to prepare such libraries. Some of the individual + libraries also include make and/or project files for various compilers, + but <em>every</em> library with a built component includes the neccessary + <code>Jamfile</code> for building with <a href= + "../tools/build/index.html">Boost.Build</a>, our standard build tool.</p> + <hr> + Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->15 February, 2003<!--webbot bot="Timestamp" endspan i-checksum="40407" --> + + <p>Written by <a href="../people/jens_maurer.htm">Jens Maurer</a> + 2001-02-11</p> + </body> +</html> diff --git a/more/error_handling.html b/more/error_handling.html new file mode 100644 index 0000000000..b6d68ec556 --- /dev/null +++ b/more/error_handling.html @@ -0,0 +1,212 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=windows-1252"> + + <title>Error and Exception Handling</title> + </head> + + <body> + <h1>Error and Exception Handling</h1> + + <h2>References</h2> + + <p>The following paper is a good introduction to some of the issues of + writing robust generic components:</p> + + <blockquote> + <a href="generic_exception_safety.html">D. Abrahams: ``Exception Safety + in Generic Components''</a>, originally published in <a href= + "http://www.springer.de/cgi-bin/search_book.pl?isbn=3-540-41090-2">M. + Jazayeri, R. Loos, D. Musser (eds.): Generic Programming, Proc. of a + Dagstuhl Seminar, Lecture Notes on Computer Science. Volume. 1766</a> + </blockquote> + + <h2>Guidelines</h2> + + <h3>When should I use exceptions?</h3> + + <p>The simple answer is: ``whenever the semantic and performance + characteristics of exceptions are appropriate.''</p> + + <p>An oft-cited guideline is to ask yourself the question ``is this an + exceptional (or unexpected) situation?'' This guideline has an attractive + ring to it, but is usually a mistake. The problem is that one person's + ``exceptional'' is another's ``expected'': when you really look at the + terms carefully, the distinction evaporates and you're left with no + guideline. After all, if you check for an error condition, then in some + sense you expect it to happen, or the check is wasted code.</p> + + <p>A more appropriate question to ask is: ``do we want stack unwinding + here?'' Because actually handling an exception is likely to be + significantly slower than executing mainline code, you should also ask: + ``Can I afford stack unwinding here?'' For example, a desktop application + performing a long computation might periodically check to see whether the + user had pressed a cancel button. Throwing an exception could allow the + operation to be cancelled gracefully. On the other hand, it would + probably be inappropriate to throw and <i>handle</i> exceptions in the + inner loop of this computation because that could have a significant + performance impact.</p> + + <h3>How should I design my exception classes?</h3> + + <ol> + <li><b>Inherit from <code>std::exception</code></b>. Except in *very* + rare circumstances where you can't afford the cost of a virtual table, + <code>std::exception</code> makes a reasonable exception base class, + and when used universally, allows programmers to catch "everything" + without resorting to <code>catch(...)</code>. For more about + <code>catch(...)</code>, see below.</li> + + <li> + <b><i>Don't</i> embed a std::string object</b> or any other data + member or base class whose copy constructor could throw an exception. + That could lead directly to std::terminate() at the throw point. + Similarly, it's a bad idea to use a base or member whose ordinary + constructor(s) might throw, because, though not necessarily fatal to + your program, you may report a different exception than intended from + a <i>throw-expression</i> that includes construction such as: + + <blockquote> +<pre> +throw some_exception(); +</pre> + </blockquote> + + <p>There are various ways to avoid copying string objects when + exceptions are copied, including embedding a fixed-length buffer in + the exception object, or managing strings via reference-counting. + However, consider the next point before pursuing either of these + approaches.</p> + </li> + + <li><b>Format the <code>what()</code> message on demand</b>, if you + feel you really must format the message. Formatting an exception error + message is typically a memory-intensive operation that could + potentially throw an exception. This is an operation best delayed until + after stack unwinding has occurred, and presumably, released some + resources. It's a good idea in this case to protect your + <code>what()</code> function with a <code>catch(...)</code> block so + that you have a fallback in case the formatting code throws</li> + + <li><b>Don't worry <i>too</i> much about the <code>what()</code> + message</b>. It's nice to have a message that a programmer stands a + chance of figuring out, but you're very unlikely to be able to compose + a relevant and <i>user</i>-comprehensible error message at the point an + exception is thrown. Certainly, internationalization is beyond the + scope of the exception class author. <a href= + "../people/peter_dimov.htm">Peter Dimov</a> makes an excellent argument + that the proper use of a <code>what()</code> string is to serve as a + key into a table of error message formatters. Now if only we could get + standardized <code>what()</code> strings for exceptions thrown by the + standard library...</li> + + <li><b>Expose relevant information about the cause of the error</b> in + your exception class' public interface. A fixation on the + <code>what()</code> message is likely to mean that you neglect to + expose information someone might need in order to make a coherent + message for users. For example, if your exception reports a numeric + range error, it's important to have the actual numbers involved + available <i>as numbers</i> in the exception class' public interface + where error reporting code can do something intelligent with them. If + you only expose a textual representation of those numbers in the + <code>what()</code> string, you will make life very difficult for + programmers who need to do something more (e.g. subtraction) with them + than dumb output.</li> + + <li><b>Make your exception class immune to double-destruction</b> if + possible. Unfortunately, several popular compilers occasionally cause + exception objects to be destroyed twice. If you can arrange for that to + be harmless (e.g. by zeroing deleted pointers) your code will be more + robust.</li> + </ol> + + <h3>What About Programmer Errors?</h3> + + <p>As a developer, if I have violated a precondition of a library I'm + using, I don't want stack unwinding. What I want is a core dump or the + equivalent - a way to inspect the state of the program at the exact point + where the problem was detected. That usually means <tt>assert()</tt> or + something like it.</p> + + <p>Sometimes it is necessary to have resilient APIs which can stand up to + nearly any kind of client abuse, but there is usually a significant cost + to this approach. For example, it usually requires that each object used + by a client be tracked so that it can be checked for validity. If you + need that sort of protection, it can usually be provided as a layer on + top of a simpler API. Beware half-measures, though. An API which promises + resilience against some, but not all abuse is an invitation to disaster. + Clients will begin to rely on the protection and their expectations will + grow to cover unprotected parts of the interface.</p> + + <p><b>Note for Windows developers</b>: unfortunately, the native + exception-handling used by most Windows compilers actually throws an + exception when you use <tt>assert()</tt>. Actually, this is true of other + programmer errors such as segmentation faults and divide-by-zero errors. + One problem with this is that if you use JIT (Just In Time) debugging, + there will be collateral exception-unwinding before the debugger comes up + because <code>catch(...)</code> will catch these not-really-C++ + exceptions. Fortunately, there is a simple but little-known workaround, + which is to use the following incantation:</p> + + <blockquote> +<pre> +extern "C" void straight_to_debugger(unsigned int, EXCEPTION_POINTERS*) +{ + throw; +} +extern "C" void (*old_translator)(unsigned, EXCEPTION_POINTERS*) + = _set_se_translator(straight_to_debugger); +</pre> + </blockquote> + This technique doesn't work if the SEH is raised from within a catch + block (or a function called from within a catch block), but it still + eliminates the vast majority of JIT-masking problems. + + <h3>How should I handle exceptions?</h3> + + <p>Often the best way to deal with exceptions is to not handle them at + all. If you can let them pass through your code and allow destructors to + handle cleanup, your code will be cleaner.</p> + + <h4>Avoid <code>catch(...)</code> when possible</h4> + Unfortunately, operating systems other than Windows also wind non-C++ + "exceptions" (such as thread cancellation) into the C++ EH machinery, and + there is sometimes no workaround corresponding to the + <code>_set_se_translator</code> hack described above. The result is that + <code>catch(...)</code> can have the effect of making some unexpected + system notification at a point where recovery is impossible look just + like a C++ exception thrown from a reasonable place, invalidating the + usual safe assumptions that destructors and catch blocks have taken valid + steps to ensure program invariants during unwinding. + + <p>I reluctantly concede this point to Hillel Y. Sims, who beat it into + me (<wink>): until all OSes are "fixed", if every exception were + derived from <code>std::exception</code> and everyone substituted + <code>catch(std::exception&)</code> for <code>catch(...)</code>, the + world would be a better place.</p> + + <p>Sometimes, <code>catch(...)</code>, is still the most appropriate + pattern, in spite of bad interactions with OS/platform design choices. If + you have no idea what kind of exception might be thrown and you really + <i>must</i> stop unwinding it's probably still your best bet. One obvious + place where this occurs is at language boundaries.</p> + <hr> + + <p>© Copyright David Abrahams 2001-2003. Permission to copy, use, + modify, sell and distribute this document is granted provided this + copyright notice appears in all copies. This document is provided "as is" + without express or implied warranty, and with no claim as to its + suitability for any purpose.</p> + + <p>Revised + <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan --> + 25 March, 2003<!--webbot bot="Timestamp" endspan i-checksum="34359" --> + </p> + </body> +</html> + diff --git a/more/faq.htm b/more/faq.htm new file mode 100644 index 0000000000..eda774e537 --- /dev/null +++ b/more/faq.htm @@ -0,0 +1,173 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost FAQ</title> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td> + </tr> +</table> + +<h1>Boost Frequently Asked Questions</h1> + +<p><strong>How do I download the libraries?</strong> + See <a href="../libs/libraries.htm#Download">Download</a> instructions.</p> + +<p><b>What support is available for the libraries?</b> The +<a href="mailing_lists.htm#users">Boost-Users mailing list</a> is a good start.</p> + +<p><b>What do the Boost version numbers mean? </b>The scheme is x.y.z, where x is incremented only for massive changes, such as a reorganization of many libraries, y is incremented whenever a new library is added, and z is incremented for maintenance releases. y and z are reset to 0 if +the value to the left changes. <br> +<br> +<b>Is there any assurance libraries actually work as claimed?</b> No. The review +process will hopefully eliminate the most seriously flawed libraries, but a well +constructed library with hidden defects is likely to slip through. Encouraging ordinary +users to report their experience with a library is intended to address such concerns. +See the <a href="../status/compiler_status.html">Status</a> page for an +indication of how well a library works on specific platforms. </p> + +<p> +<b>How can the Boost libraries be used successfully for important projects? +</b>Many of the Boost libraries are actively maintained and improved, so backward compatibility with prior version isn't always possible. Deal with this by freezing the version of the Boost libraries used by your project. Only upgrade at points in your project's life cycle where a bit of change will not cause problems. Individual bug fixes can always be obtained from the CVS repository. </p> + +<p><b>How is a library accepted for posting on the site?</b> +See <a href="submission_process.htm">Library Submission Process</a></p> + +<p><b>How does someone submit a Formal Review comment?</b> Send email to <a +href="mailto:boost@yahoogroups.com">boost@yahoogroups.com</a>. See the <a href="formal_review_process.htm">Formal +Review</a> page for more information. </p> + +<p><strong>How does someone submit a library?</strong> See <a href="lib_guide.htm">Library +Guidelines</a></p> + +<p><b>Are commercial libraries requiring a fee acceptable?</b> No. However, a library that +a commercial enterprise makes available without fee is acceptable. If the description of +the library makes a low-key plug for the supplier, that is acceptable as long as the +library delivers real value and isn't just a Trojan horse for the plug.</p> + +<p><b>Are shareware libraries acceptable?</b> No. Only free libraries +will be accepted.</p> + +<p><strong>Are open source license libraries acceptable?</strong> Some +are, many are not. +Open source licenses often require redistribution or availability of source code, +inclusion of license document with machine-executable redistribution, give the initial +developer rights to licensee modifications, or need a lawyer to understand. These +would be immediate disqualifications for many business, commercial, and consumer +applications. Boost aims to avoid subjecting users to hard-to-comply-with license +terms. See <a href="lib_guide.htm#License">License requirements</a>.<br> +<br> +This is subject to review for a particularly important piece of software, or as the +industry changes.</p> + +<p><b>Must full source code be provided?</b> Yes, these are source code libraries.</p> + +<p><b>What about documentation?</b> A very simple library might be accepted with only a +well commented header file. For more substantial libraries, some form of documentation is +certainly going to be expected. HTML is the preferred form.</p> + +<p><b>Are platform specific libraries acceptable?</b> There is a preference for portable +libraries. Libraries will be accepted that have portable interfaces but require platform +specific implementations, as long as the author supplies implementations for a couple of +disparate major operating systems.</p> + +<p><b>Must a library do useful work? </b>No. A library meant as a teaching example or +demonstration might not actually do any work.</p> + +<p><b>Can an existing library be accepted by Boost?</b> Yes, although it would +have to be "Boostified" to meet the requirements. The Boost +Graph and Regex libraries are examples of libraries which began life elsewhere.</p> + +<p><b>Who owns the libraries?</b> Presumably many authors will copyright their libraries. +Others authors may wish to place their libraries in the public domain. The Boost.org +policy is to only accept libraries with a clear copyright notice and meeting the +<a href="lib_guide.htm#License">License requirements</a>.. It is up to +potential users to decide if the terms acceptable, and not to use +libraries with unacceptable copyrights or licenses.</p> + +<p><b>Is there a formal relationship between Boost.org and the C++ Standards Committee?</b> + No, although there is a strong informal relationship in that many members +of the committee participate in Boost, and the people who started Boost were all +committee members.</p> + +<p><b>Will the Boost.org libraries become part of the next C++ Standard?</b> Some +might, someday, but that is up to the standards committee. Committee +members who also participate in Boost will definitely be proposing at least some +Boost libraries for standardization.</p> + +<p>Libraries which are "existing practice" are most likely to be +accepted by the C++ committee for future standardization. Having a library +accepted by Boost is +one way to establish existing practice.</p> + +<p><b>Where does the name "Boost" come from?</b> Boost began with +Robert Klarer and me fantasizing about a new library effort over dinner at a C++ +committee meeting in Sofia Antipolis, France. Robert mentioned that Herb Sutter +was working on a spoof proposal for a new language named Booze, which was +supposed to be better than Java. Somehow that kicked off the idea of +"Boost" as a name. We'd probably had a couple of glasses of good +French wine at that point. It was just a working name, but no one ever came up +with a replacement. (Beman Dawes)</p> + +<p><b>Is the web site a commercial business?</b> No. It is just some people getting together +as a kind of cyberspace civic association. If it ever needs to incorporate, it would be as +non-profit organization.</p> + +<p><b>Is there any charge for submitting libraries or reviews to Boost.org?</b> No. Unlike +the standards committees, you don't have to pay to volunteer!</p> + +<p><b>Will the site include material beyond libraries?</b> The main focus is on libraries, +but if people contribute occasional articles or other material to make the site more +interesting, that could be a nice fit.</p> + +<p><b>Why isn't there a separate boost mailing list for my favorite +library? </b> One of the reasons for boost's success has been the cross-pollination of ideas between diverse library +projects and the occasional look into other threads by otherwise uninterested parties. The more people participate, the less they tend to be annoyed by +"noise".</p> + +<p><b>How can I cope with the large volume of boost mailing list messages?</b> +One approach is to use the YahooGroups digest option; that cuts the email blizzard +down to about three (long) messages per day, so you can glance over the subjects +summary at the top and quickly read what you think is important. The +YahooGroups "no mail/web only" option is best if you just occasionally +want to look at messages.</p> + +<p>Yet another approach is to use your email program's capabilities to filter messages and automatically +transfer them into several boost folders. Then only read the folders you +care about. Boost list posters are +encouraged to include keywords in the subject like "thread", +"review", and "CVS" to aid message filtering.</p> + +<p><b>Why do Boost headers have a .hpp suffix rather than .h or none at all?</b> +File extensions communicate the "type" of the file, both to humans and +to computer programs. The '.h' extension is used for C header files, and +therefore communicates the wrong thing about C++ header files. Using no +extension communicates nothing and forces inspection of file contents to +determine type. Using '.hpp' unambiguously identifies it as C++ header file, and +works well in actual practice. (Rainer Deyke)</p> + +<p><b>What should I do if I spot a bug in the Boost code or documentation?</b> +See the suggestions on the <a href="bugs.htm">Bugs page</a>.</p> + +<p><b>How can I request a new feature in a Boost Library? </b>See the +<a href="requesting_new_features.htm">Requesting New Features</a> page.</p> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->18 January, 2002<!--webbot bot="Timestamp" i-checksum="38453" endspan --> +</p> +</body> +</html> diff --git a/more/feature_model_diagrams.htm b/more/feature_model_diagrams.htm new file mode 100644 index 0000000000..b685e37a9d --- /dev/null +++ b/more/feature_model_diagrams.htm @@ -0,0 +1,104 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Feature Model Diagrams</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<p><img border="0" src="../c++boost.gif" width="277" height="86"></p> +<h1>Feature Model Diagrams in text and HTML</h1> +<p>By <a href="../people/beman_dawes.html">Beman Dawes</a></p> +<h2>Introduction</h2> +<p>In their seminal book, Generative Programming, Czarnecki and Eisenecker (<a href="#Generative Programming">C&E</a>) +describe how to build feature models [C&E 4.4] consisting of a feature +diagram plus semantic, rationale, and other attributes. Feature models are +then used to drive design cycles which eventually lead to manual or automatic +assembly of configurations.</p> +<p>Feature models provide a language to describe the library variability that is +often such an issue in boost.org discussions. The Whorf hypothesis that +"Language shapes the way we think, and determines what we can think +about" seems to apply. In discussion of library variability issues, +we have been crippled by lack of a good language. With feature models we now +have a language to carry on the dialog.</p> +<p>The graphical feature diagrams presented by C&E are not in a suitable +form for the email discussions boost.org depends upon. The hierarchical nature +of feature diagrams can be represented by a simple text-based feature diagram +language. A feature model can also take advantage of the hyperlinks +inherent in HTML.</p> +<h2><a name="Grammar">Grammar</a></h2> +<p>The grammar for the feature diagram language is expressed in Extended +Bakus-Naur Form; ::= represents productions, [...] represents options, {...} +represents zero or more instances, and represents | alternatives.</p> +<blockquote> + <pre>feature-model ::= concept-name details { feature }</pre> + <pre>feature ::= feature-name [details]</pre> + <pre>details ::= "(" feature-list ")" // required features + | "[" feature-list "]" // optional features</pre> + <pre>feature-list ::= element { "|" element } // one only + | element { "+" element } // one or more + | element { "," element } // all + // [a+b] equivalent to [a,b]</pre> + <pre>element ::= feature + | details</pre> + <pre>concept-name ::= name</pre> + <pre>feature-name ::= name</pre> +</blockquote> +<p>The usual lexical conventions apply. Names are case-insensitive and consist +of a leading letter, followed by letters, digits, underscores or hyphens, with +no spaces allowed.</p> +<p>At least one instance of each name should be hyperlinked to the corresponding +<a href="#Feature Descriptions">Feature Description</a>.</p> +<p>While the grammar is intended for written communication between people, it +may also be trivially machine parsed for use by automatic tools.</p> +<h2><a name="Feature Descriptions">Feature Description</a></h2> +<p>Descriptive information is associated with each concept or feature. According +to [C&E 4.4.2] this includes:</p> +<ul> + <li>Semantic descriptions.</li> + <li>Rationale.</li> + <li>Stakeholders and client programs.</li> + <li>Exemplar systems.</li> + <li>Constraints and default dependency rules.</li> + <li>Availability sites, binding sites, and binding mode.</li> + <li>Open/Closed attribute.</li> +</ul> +<h2>What is a Feature?</h2> +<p>A feature [C&E 4.9.1] is "anything users or client programs might +want to control about a concept. Thus, during feature modeling, we +document no only functional features ... but also implementation features, ..., +various optimizations, alternative implementation techniques, and so on."</p> +<h2>Example</h2> +<blockquote> + <pre>special-container ( organization, + performance, + interface ) // all required</pre> + <pre>organization [ ordered + indexed ] // zero or more (4 configurations)</pre> + <pre>indexed [ hash-function ] // zero or one (2 configurations)</pre> + <pre>performance ( fast | small | balanced ) // exactly one (3 configurations)</pre> + <pre>interface ( STL-style + cursor-style ) // one or more (3 configurations)</pre> +</blockquote> +<p>There should be feature descriptions for <code>some-container, organization, +ordered, indexed, hash-function, performance, fast, small, balanced, interface, +STL-style, and cursor-style</code>.</p> +<p>The number of possible configurations is (2 + 2*2) * 3 * 3 = 54, +assuming no constraints.</p> +<p>There are equivalent representations. For example:</p> +<blockquote> + <pre>special-container ( organization[ ordered+indexed[ hash-function ]], + performance( fast|small|balanced ), + interface( STL-style+cursor-style ) )</pre> +</blockquote> +<h2>References</h2> +<p>Krzysztof Czarnecki and Ulrich W. Eisenecker, <a name="Generative Programming" href="http://www.generative-programming.org">Generative +Programming</a>, Addison-Wesley, 2000, ISBN 0-210-30977-7</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->19 August 2001<!--webbot bot="Timestamp" endspan i-checksum="31287" --></p> +<p>© Copyright Beman Dawes, 2000</p> + +</body> + +</html> diff --git a/more/formal_review_process.htm b/more/formal_review_process.htm new file mode 100644 index 0000000000..7de007e5b6 --- /dev/null +++ b/more/formal_review_process.htm @@ -0,0 +1,246 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + + <title>Boost Formal Review Process</title> + </head> + + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt= + "c++boost.gif (8819 bytes)" width="277" height="86"></td> + + <td><a href="../index.htm"><font face="Arial" color= + "#FFFFFF"><big>Home</big></font></a></td> + + <td><a href="../libs/libraries.htm"><font face="Arial" color= + "#FFFFFF"><big>Libraries</big></font></a></td> + + <td><a href="../people/people.htm"><font face="Arial" color= + "#FFFFFF"><big>People</big></font></a></td> + + <td><a href="faq.htm"><font face="Arial" color= + "#FFFFFF"><big>FAQ</big></font></a></td> + + <td><a href="index.htm"><font face="Arial" color= + "#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + + <h1>Boost Formal Review Process</h1> + + <p><a href="#Introduction">Introduction</a><br> + <a href="#Comments">What to include in Review Comments</a><br> + <a href="#Results">Results</a><br> + <a href="#Review_Manager">Notes for Review Managers</a><br> + <a href="#Submitters">Notes for Library Submitters</a><br> + <a href="#Wizard">Review Wizard</a></p> + + <h2><a name="Introduction">Introduction</a></h2> + + <p>Proposed libraries are accepted into Boost only after undergoing a + formal review, where Boost mailing list members comment on their + evaluation of the library.</p> + + <p>The final "accept" or "reject" decision is made by the <a href= + "#Review_Manager">Review Manager</a>, based on the review comments + received from boost mailing list members.</p> + + <p>Boost mailing list members are encouraged to submit Formal Review + comments:</p> + + <blockquote> + <ul> + <li>Publicly on the mailing list.</li> + + <li>Privately to the Review Manager.</li> + </ul> + </blockquote> + + <p>Private comments to a library submitter may be helpful to her or him, + but won't help the Review Manager reach a decision, so the other forms + are preferred.</p> + + <h2>What to include in Review <a name="Comments">Comments</a></h2> + + <p>Your comments may be brief or lengthy, but basically the Review + Manager needs your evaluation of the library. If you identify + problems along the way, please note if they are minor, serious, or + showstoppers.</p> + + <p>Here are some questions you might want to answer in your review:</p> + + <ul> + <li>What is your evaluation of the design?<br> + </li> + + <li>What is your evaluation of the implementation?<br> + </li> + + <li>What is your evaluation of the documentation?<br> + </li> + + <li>What is your evaluation of the potential usefulness of the + library?<br> + </li> + + <li>Did you try to use the library? With what compiler? Did + you have any problems?<br> + </li> + + <li>How much effort did you put into your evaluation? A glance? A quick + reading? In-depth study?<br> + </li> + + <li>Are you knowledgeable about the problem domain?</li> + </ul> + + <p>And finally, every review should answer this question:<br> + </p> + + <ul> + <li>Do you think the library should be accepted as a Boost + library? Be sure to say this explicitly so that your other + comments don't obscure your overall opinion.</li> + </ul> + + <h2><a name="Results">Results</a></h2> + + <p>At the conclusion of the comment period, the Review Manager will post + a message to the mailing list saying if the library has been accepted or + rejected. A rationale is also helpful, but its extent is up to the + Review Manager. If there are suggestions, or conditions that must be met + before final inclusion, they should be stated.</p> + + <h2>Notes for <a name="Review_Manager">Review Manager</a>s</h2> + + <p>Before a library can be scheduled for formal review, an active boost + member not connected with the library submission must volunteer to be the + "Review Manager" for the library.</p> + + <p>The Review Manager:</p> + + <ul> + <li>Checks the submission to make sure it really is complete enough to + warrant formal review. See the <a href="lib_guide.htm">Boost + Library Requirements and Guidelines</a>. If necessary, work with + the submitter to verify the code compiles and runs correctly on several + compilers and platforms.</li> + + <li>Finalizes the schedule with the <a href="#Wizard">Review Wizard</a> + and the submitter .</li> + + <li> + Posts a notice of the review schedule on both the regular <b><a href= + "mailto:boost@lists.boost.org">boost mailing list</a></b> and the + <b><a href="mailto:boost-announce@lists.boost.org">boost-announce</a> + mailing list</b>. + + <ul> + <li>The notice should include a brief description of the library + and what it does, to let readers know if the library is one they + are interested in reviewing.</li> + + <li>If the library is known to fail with certain compilers, please + mention them in the review notice so reviewers with those compilers + won't waste time diagnosing known problems.</li> + </ul> + </li> + + <li>Inspects the Boost <a href="../libs/libraries.htm">library + catalogue</a> for libraries which may interact with the new submission. + These potential interactions should be pointed out in the review + announcement, and the author(s) of these libraries should be privately + notified and urged to participate in the review.</li> + + <li>Urges people to do reviews if they aren't forthcoming.</li> + + <li>Follows review discussions regarding the library, moderating or + answering questions as needed.</li> + + <li>Decides if there is consensus to accept the library, and if there + are any conditions attached.</li> + + <li>Posts a message on both the <b><a href= + "mailto:boost@lists.boost.org">boost</a></b> and <b><a href= + "mailto:boost-announce@lists.boost.org">boost-announce</a></b> lists + informing members of the <a href="#Results">review results</a>.</li> + </ul> + + <p>In other words, it is the Review Manager's responsibility to make sure + the review process works smoothly.</p> + + <h2>Notes for Library <a name="Submitters">Submitters</a></h2> + + <p>See <a href="submission_process.htm">Submission Process</a> for a + description of the steps a library developer goes through to get a + library accepted by Boost.</p> + + <p>A proposed library should remain stable during the review period; it + will just confuse and irritate reviewers if there are numerous + changes. It is, however, useful to upload fixes for serious bugs + right away, particularly those which prevent reviewers from fully + evaluating the library. Post a notice of such fixes on the mailing + list.</p> + + <p>Library improvements suggested by reviewers should normally be held + until after the completion of review period. If the suggested + changes might affect reviewer's judgments, post a notice of the + pending change on the mailing list.</p> + + <h2>Review <a name="Wizard">Wizard</a></h2> + + <p>The Review Wizard coordinates the formal review schedule:</p> + + <ul> + <li>Maintains a list of review manager volunteers, in the form of a + queue, so that volunteers who least recently managed reviews become the + prime candidates for upcoming reviews.</li> + + <li>When a formal review is requested for a library:</li> + + <li style="list-style: none"> + <ul> + <li>Assign a review manager and suggests a schedule, after checking + (via private email) availability of the volunteers at the top of + review manager queue.</li> + + <li>Finalize the schedule, once the review manager verifies the + library is actually ready for review.</li> + + <li>Resolve schedule slips or other issues with review managers and + submitters.</li> + </ul> + </li> + + <li>Maintains a schedule of both past and pending reviews, in the form + of the <a href="formal_review_schedule.html">Review Schedule</a> web + page.</li> + + <li>Resolves questions from review managers and library submitters, who + sometimes want a third opinion on questions such as "Should we extend + the review period because ...?"</li> + + <li>Monitors the general review process, and makes minor adjustments as + needed, or queries the list about possible major adjustments.</li> + </ul> + The role of Boost Review Wizard is currently played by <a href= + "mailto:witt@ive.uni-hannover.de">Thomas Witt</a>. + <hr> + + <p>Revised + <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 + November, 2002<!--webbot bot="Timestamp" endspan i-checksum="34406" --></p> + + <p> </p> + </body> +</html> + diff --git a/more/formal_review_schedule.html b/more/formal_review_schedule.html new file mode 100644 index 0000000000..e01cf4d2dc --- /dev/null +++ b/more/formal_review_schedule.html @@ -0,0 +1,258 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Formal Review Schedule</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Formal Review Schedule</h1> +<p>Reviews are usually scheduled on a first-come-first-served basis, and +normally last ten days. See <a href="formal_review_process.htm">Formal +Review Process</a> for more information.</p> +<p>The schedule shows submissions ordered by review date. In addition to +upcoming reviews, it includes recent reviews already completed; that helps +track review manager assignments and libraries reviewed but not yet posted on +the web site. There is often a lag between acceptance and site posting as +authors address issues raised in the formal review.</p> +<h2><a name="Schedule">Schedule</a></h2> +<table border="1" cellpadding="5" cellspacing="0"> + <tr> + <td valign="top"><b>Submission</b></td> + <td valign="top"><b>Submitter</b></td> + <td valign="top"><b>Review<br> + Manager</b></td> + <td valign="top"><b>Review<br> + Dates</b></td> + </tr> + <tr> + <td>String Algorithm Library</td> + <td>Pavol Droba</td> + <td>-</td> + <td>-</td> + </tr> + <tr> + <td>Shifted Pointer</td> + <td>Philippe A. Bouchard</td> + <td>-</td> + <td>-</td> + </tr> + <tr> + <td>Fixed-Point Decimal</td> + <td>Bill Seymour</td> + <td>-</td> + <td>-</td> + </tr> + <tr> + <td>Command Line & Config</td> + <td>Vladimir Prus</td> + <td>-</td> + <td>-</td> + </tr> + <tr> + <td>Math Constants</td> + <td>Paul A. Bristow</td> + <td>-</td> + <td>-</td> + </tr> + <tr> + <td>I/O Manipulators and Adaptors</td> + <td>Daryle Walker</td> + <td>Ed Brey</td> + <td>27 Feb - 11 Mar 2003</td> + </tr> + <tr> + <td>Variant</td> + <td>Eric Friedman & Itay Maman</td> + <td>Jeff Garland</td> + <td>16 - 25 Feb 2003</td> + </tr> + <tr> + <td>Optional</td> + <td>Fernando Cacciola</td> + <td>Douglas Gregor</td> + <td>09 - 18 Dec 2002</td> + </tr> + <tr> + <td>Serialization</td> + <td>Robert Ramey</td> + <td>Dave Abrahams</td> + <td>02 - 11 Nov 2002</td> + </tr> + <tr> + <td>Spirit</td> + <td>Joel de Guzman</td> + <td>John Maddock</td> + <td>11 - 20 Oct 2002</td> + </tr> + <tr> + <td>Minmax</td> + <td>Hervé Bronnimann</td> + <td>Thomas Witt</td> + <td>28 Sep - 07 Oct 2002</td> + </tr> + <tr> + <td>Filesystem</td> + <td>Beman Dawes</td> + <td>William Kempf</td> + <td>14 - 23 Sep 2002</td> + </tr> + <tr> + <td>Interval Arithmetic Library</td> + <td>Hervé Bronnimann & Guillaume Melquiond & Sylvain Pion</td> + <td>Beman Dawes</td> + <td>31 Aug - 09 Sep 2002</td> + </tr> + <tr> + <td>Template Meta Programming Library MPL</td> + <td>Aleksey Gurtovoy</td> + <td>Douglas Gregor</td> + <td>15 - 29 Jul 2002</td> + </tr> + <tr> + <td>uBLAS</td> + <td>Joerg Walter & Mathias Koch</td> + <td>Ed Brey</td> + <td>21 Jun - 01 Jul 2002</td> + </tr> + <tr> + <td>Dynamic Bitset</td> + <td>Chuck Alison & Jeremy Siek</td> + <td>Mat Marcus</td> + <td>08 - 17 Jun 2002</td> + </tr> + <tr> + <td>Date / Time</td> + <td>Jeff Garland</td> + <td>Darin Adler</td> + <td>15 - 24 Apr 2002</td> + </tr> + <tr> + <td>Lambda</td> + <td>Jaakko Järvi & Gary Powell</td> + <td>Aleksey Gurtovoy</td> + <td>08 - 20 Mar 2002</td> + </tr> + <tr> + <td>Signals</td> + <td>Douglas Gregor</td> + <td>William Kempf</td> + <td>18 - 27 Feb 2002</td> + </tr> + <tr> + <td>I/O State Saver</td> + <td>Daryle Walker</td> + <td>Beman Dawes</td> + <td>06 - 16 Feb 2002</td> + </tr> + <tr> + <td>printf-like formatting for iostreams</td> + <td>Samuel Krempp</td> + <td>Jens Maurer</td> + <td>13 - 23 Jan 2002</td> + </tr> + <tr> + <td>Multi-array</td> + <td>Ron Garcia</td> + <td>John Maddock</td> + <td>02 - 12 Jan 2002</td> + </tr> + <tr> + <td>Unit Test Library</td> + <td>Gennadiy Rozental</td> + <td>Jeremy Siek</td> + <td>01 - 13 Dec 2001</td> + </tr> + <tr> + <td>GCD Library plus integer additions</td> + <td>Daryle Walker</td> + <td>Dave Abrahams</td> + <td>17 - 26 Sep 2001</td> + </tr> + <tr> + <td>Thread Library</td> + <td>Bill Kempf</td> + <td>Ed Brey</td> + <td>Aug 30 - Sep 8</td> + </tr> + <tr> + <td>Config System</td> + <td>John Maddock</td> + <td>Doug Gregor</td> + <td>Aug 20 - 29 </td> + </tr> + <tr> + <td>Bind Library</td> + <td>Peter Dimov</td> + <td>Darin Adler</td> + <td>Aug 10 - 19</td> + </tr> + <tr> + <td>Base from Member Library</td> + <td>Daryle Walker</td> + <td>Beman Dawes</td> + <td>Jul 30 - Aug 9</td> + </tr> + <tr> + <td>Coding Guidelines</td> + <td>Dave Abrahams</td> + <td>Aleksey Gurtovoy</td> + <td>Jul 20 - 29</td> + </tr> + <tr> + <td>Preprocessor Library</td> + <td>Vesa Karvonen</td> + <td>Jeremy Siek</td> + <td>Jun 28 - Jul 9</td> + </tr> + <tr> + <td>Tuples Library</td> + <td>Jaakko Järvi</td> + <td>Beman Dawes</td> + <td>Jun 17 - 26</td> + </tr> + <tr> + <td>Function Library</td> + <td>Doug Gregor</td> + <td>John Maddock</td> + <td>Jun 6 - 16</td> + </tr> + <tr> + <td>Tokenizer</td> + <td>John Bandela</td> + <td>Doug Gregor</td> + <td>May 28 - Jun 6</td> + </tr> + <tr> + <td>Special Functions</td> + <td>Hubert Holin</td> + <td>Jens Maurer</td> + <td>May 18 - 27</td> + </tr> +</table> +<h2>Review <a name="Managers">Managers</a></h2> +<p>We try to rotate the task of Review Manager between many experienced Boost +members, both to ensure fairness, and to spread the workload. If you would +like to volunteer to become a review manager, please contact the <a href= + "mailto:witt@ive.uni-hannover.de">Review Wizard</a>.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %b %Y" startspan -->19 Mar 2003<!--webbot bot="Timestamp" i-checksum="14882" endspan --> +</p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/generic_exception_safety.html b/more/generic_exception_safety.html new file mode 100644 index 0000000000..7410c86182 --- /dev/null +++ b/more/generic_exception_safety.html @@ -0,0 +1,684 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- saved from url=(0052)http://people.ne.mediaone.net/abrahams/abrahams.html --> + + <meta name="generator" content="Microsoft FrontPage 5.0"> + <title>Exception-Safety in Generic Components</title> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta content="MSHTML 5.50.4522.1800" name="GENERATOR"> + + <h1 align="center">Exception-Safety in Generic Components</h1> + + <p align="center"><i><b>Lessons Learned from Specifying Exception-Safety + for the C++ Standard Library</b></i> + + <h3 align="center">David Abrahams</h3> + + <h3 align="center"><a href="mailto:david.abrahams@rcn.com"> + david.abrahams@rcn.com</a></h3> + + <p><b>Abstract.</b> This paper represents the knowledge accumulated in + response to a real-world need: that the C++ Standard Template Library + exhibit useful and well-defined interactions with exceptions, the + error-handling mechanism built-in to the core C++ language. It explores the + meaning of exception-safety, reveals surprising myths about exceptions and + genericity, describes valuable tools for reasoning about program + correctness, and outlines an automated testing procedure for verifying + exception-safety. + + <p><b>Keywords:</b> exception-safety, exceptions, STL, C++ + + <h2>1 What is exception-safety?</h2> + + <p>Informally, exception-safety in a component means that it exhibits + reasonable behavior when an exception is thrown during its execution. For + most people, the term ``reasonable'' includes all the usual + expectations for error-handling: that resources should not be leaked, and + that the program should remain in a well-defined state so that execution + can continue. For most components, it also includes the expectation that + when an error is encountered, it is reported to the caller. + + <p>More formally, we can describe a component as minimally exception-safe + if, when exceptions are thrown from within that component, its invariants + are intact. Later on we'll see that at least three different levels of + exception-safety can be usefully distinguished. These distinctions can help + us to describe and reason about the behavior of large systems. + + <p>In a generic component, we usually have an additional expectation of + <i>exception-neutrality</i>, which means that exceptions thrown by a + component's type parameters should be propagated, unchanged, to the + component's caller. + + <h2>2 Myths and Superstitions</h2> + + <p>Exception-safety seems straightforward so far: it doesn't constitute + anything more than we'd expect from code using more traditional + error-handling techniques. It might be worthwhile, however, to examine the + term from a psychological viewpoint. Nobody ever spoke of + ``error-safety'' before C++ had exceptions. + + <p>It's almost as though exceptions are viewed as a <i>mysterious + attack</i> on otherwise correct code, from which we must protect ourselves. + Needless to say, this doesn't lead to a healthy relationship with error + handling! During standardization, a democratic process which requires broad + support for changes, I encountered many widely-held superstitions. In order + to even begin the discussion of exception-safety in generic components, it + may be worthwhile confronting a few of them. + + <p><i>``Interactions between templates and exceptions are not + well-understood.''</i> This myth, often heard from those who consider + these both new language features, is easily disposed of: there simply are + no interactions. A template, once instantiated, works in all respects like + an ordinary class or function. A simple way to reason about the behavior of + a template with exceptions is to think of how a specific instantiation of + that template works. Finally, the genericity of templates should not cause + special concern. Although the component's client supplies part of the + operation (which may, unless otherwise specified, throw arbitrary + exceptions), the same is true of operations using familiar virtual + functions or simple function pointers. + + <p><i>``It is well known to be impossible to write an exception-safe + generic container.''</i> This claim is often heard with reference to + an article by Tom Cargill <a title= + "Tom Cargill, ``Exception Handling: A False Sense of Security'', C++ Report, Nov-Dec 1994" + href= + "#reference4"><sup>[4]</sup></a> + in which he explores the problem of exception-safety for a generic stack + template. In his article, Cargill raises many useful questions, but + unfortunately fails to present a solution to his problem.<a title= + "Probably the greatest impediment to a solution in Cargill's case was an unfortunate combination of choices on his part: the interface he chose for his container was incompatible with his particular demands for safety. By changing either one he might have solved the problem." + href= + "#footnote1"><sup>1</sup></a> + He concludes by suggesting that a solution may not be possible. + Unfortunately, his article was read by many as ``proof'' of that + speculation. Since it was published there have been many examples of + exception-safe generic components, among them the C++ standard library + containers. + + <p><i>``Dealing with exceptions will slow code down, and templates are + used specifically to get the best possible performance.''</i> A good + implementation of C++ will not devote a single instruction cycle to dealing + with exceptions until one is thrown, and then it can be handled at a speed + comparable with that of calling a function <a title= + "D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997." + href= + "#reference7"><sup>[7]</sup></a>. + That alone gives programs using exceptions performance equivalent to that + of a program which ignores the possibility of errors. Using exceptions can + actually result in faster programs than ``traditional'' error + handling methods for other reasons. First, a catch block clearly indicates + to the compiler which code is devoted to error-handling; it can then be + separated from the usual execution path, improving locality of reference. + Second, code using ``traditional'' error handling must typically + test a return value for errors after every single function call; using + exceptions completely eliminates that overhead. + + <p><i>``Exceptions make it more difficult to reason about a program's + behavior.''</i> Usually cited in support of this myth is the way + ``hidden'' execution paths are followed during stack-unwinding. + Hidden execution paths are nothing new to any C++ programmer who expects + local variables to be destroyed upon returning from a function: + + <blockquote> +<pre>ErrorCode f( int& result ) // 1 +{ // 2 + X x; // 3 + ErrorCode err = x.g( result ); // 4 + if ( err != kNoError ) // 5 + return err; // 6 + // ...More code here... + return kNoError; // 7 +} +</pre> + </blockquote> + + <p>In the example above, there is a ``hidden'' call to + <code>X::~X()</code> in lines 6 and 7. Granted, using exceptions, there is + no code devoted to error handling visible: + + <blockquote> +<pre>int f() // 1 +{ // 2 + X x; // 3 + int result = x.g(); // 4 + // ...More code here... + return result; // 5 +} +</pre> + </blockquote> + + <p>For many programmers more familiar with exceptions, the second example + is actually more readable and understandable than the first. The + ``hidden'' code paths include the same calls to destructors of + local variables. In addition, they follow a simple pattern which acts + <i>exactly</i> as though there were a potential return statement after each + function call in case of an exception. Readability is enhanced because the + normal path of execution is unobscured by error-handling, and return values + are freed up to be used in a natural way. + + <p>There is an even more important way in which exceptions can enhance + correctness: by allowing simple class invariants. In the first example, if + <code>x</code>'s constructor should need to allocate resources, it has no + way to report a failure: in C++, constructors have no return values. The + usual result when exceptions are avoided is that classes requiring + resources must include a separate initializer function which finishes the + job of construction. The programmer can therefore never be sure, when an + object of class <code>X</code> is used, whether he is handling a + full-fledged <code>X</code> or some abortive attempt to construct one (or + worse: someone simply forgot to call the initializer!) + + <h2>3 A contractual basis for exception-safety</h2> + + <p>A non-generic component can be described as exception-safe in isolation, + but because of its configurability by client code, exception-safety in a + generic component usually depends on a contract between the component and + its clients. For example, the designer of a generic component might require + that an operation which is used in the component's destructor not throw any + exceptions.<a title= + " It is usually inadvisable to throw an exception from a destructor in C++, since the destructor may itself be called during the stack-unwinding caused by another exception. If the second exception is allowed to propagate beyond the destructor, the program is immediately terminated." + href= + "#footnote2"><sup>2</sup></a> + The generic component might, in return, provide one of the following + guarantees: + + <ul> + <li>The <i>basic</i> guarantee: that the invariants of the component are + preserved, and no resources are leaked. + + <li>The <i>strong</i> guarantee: that the operation has either completed + successfully or thrown an exception, leaving the program state exactly as + it was before the operation started. + + <li>The <i>no-throw</i> guarantee: that the operation will not throw an + exception. + </ul> + + <p>The basic guarantee is a simple minimum standard for exception-safety to + which we can hold all components. It says simply that after an exception, + the component can still be used as before. Importantly, the preservation of + invariants allows the component to be destroyed, potentially as part of + stack-unwinding. This guarantee is actually less useful than it might at + first appear. If a component has many valid states, after an exception we + have no idea what state the component is in|only that the state is valid. + The options for recovery in this case are limited: either destruction or + resetting the component to some known state before further use. Consider + the following example: + + <blockquote> +<pre>template <class X> +void print_random_sequence() +{ + std::vector<X> v(10); // A vector of 10 items + try { + // Provides only the <i>basic</i> guarantee + v.insert( v.begin(), X() ); + } + catch(...) {} // ignore any exceptions above + // print the vector's contents + std::cout "(" << v.size() << ") "; + std::copy( v.begin(), v.end(), + std::ostream_iterator<X>( std::cout, " " ) ); +} +</pre> + </blockquote> + + <p>Since all we know about v after an exception is that it is valid, the + function is allowed to print any random sequence of <code>X</code>s.<a + title= + "In practice of course, this function would make an extremely poor random sequence generator!" + href= + "#footnote3"><sup>3</sup></a> + It is ``safe'' in the sense that it is not allowed to crash, but + its output may be unpredictable. + + <p>The <i>strong</i> guarantee provides full + ``commit-or-rollback'' semantics. In the case of C++ standard + containers, this means, for example, that if an exception is thrown all + iterators remain valid. We also know that the container has exactly the + same elements as before the exception was thrown. A transaction that has no + effects if it fails has obvious benefits: the program state is simple and + predictable in case of an exception. In the C++ standard library, nearly + all of the operations on the node-based containers list, set, multiset, + map, and multimap provide the <i>strong</i> guarantee.<a title= + "It is worth noting that mutating algorithms usually cannot provide the strong guarantee: to roll back a modified element of a range, it must be set back to its previous value using operator=, which itself might throw. In the C++ standard library, there are a few exceptions to this rule, whose rollback behavior consists only of destruction: uninitialized_copy, uninitialized_fill, and uninitialized_fill_n." + href= + "#footnote4"><sup>4</sup></a>). + + <p>The <i>no-throw</i> guarantee is the strongest of all, and it says that + an operation is guaranteed not to throw an exception: it always completes + successfully. This guarantee is necessary for most destructors, and indeed + the destructors of C++ standard library components are all guaranteed not + to throw exceptions. The <i>no-throw</i> guarantee turns out to be + important for other reasons, as we shall see.<a title= + "All type parameters supplied by clients of the C++ standard library are required not to throw from their destructors. In return, all components of the C++ standard library provide at least the basic guarantee." + href= + "#footnote5"><sup>5</sup></a> + + <h2>4 Legal Wrangling</h2> + + <p>Inevitably, the contract can get more complicated: a quid pro quo + arrangement is possible. Some components in the C++ Standard Library give + one guarantee for arbitrary type parameters, but give a stronger guarantee + in exchange for additional promises from the client type that no exceptions + will be thrown. For example, the standard container operation + <code>vector<T>::erase</code> gives the <i>basic</i> guarantee for + any <code>T</code>, but for types whose copy constructor and copy + assignment operator do not throw, it gives the <i>no-throw</i> guarantee.<a + title= + "Similar arrangements might have been made in the C++ standard for many of the mutating algorithms, but were never considered due to time constraints on the standardization process." + href= + "#footnote6"><sup>6</sup></a> + + <h2>5 What level of exception-safety should a component specify?</h2> + + <p>From a client's point-of-view, the strongest possible level of safety + would be ideal. Of course, the <i>no-throw</i> guarantee is simply + impossible for many operations, but what about the <i>strong</i> guarantee? + For example, suppose we wanted atomic behavior for + <code>vector<T>::insert</code>. Insertion into the middle of a vector + requires copying elements after the insertion point into later positions, + to make room for the new element. If copying an element can fail, rolling + back the operation would require ``undoing'' the previous + copies...which depends on copying again. If copying back should fail (as it + likely would), we have failed to meet our guarantee. + + <p>One possible alternative would be to redefine <code>insert</code> to + build the new array contents in a fresh piece of memory each time, and only + destroy the old contents when that has succeeded. Unfortunately, there is a + non-trivial cost if this approach is followed: insertions near the end of a + vector which might have previously caused only a few copies would now cause + every element to be copied. The <i>basic</i> guarantee is a + ``natural'' level of safety for this operation, which it can + provide without violating its performance guarantees. In fact all of the + operations in the library appear to have such a ``natural'' level + of safety. + + <p>Because performance requirements were already a well-established part of + the draft standard and because performance is a primary goal of the STL, + there was no attempt to specify more safety than could be provided within + those requirements. Although not all of the library gives the <i>strong</i> + guarantee, almost any operation on a standard container which gives the + <i>basic</i> guarantee can be made <i>strong</i> using the ``make a + new copy'' strategy described above: + + <blockquote> +<pre>template <class Container, class BasicOp> +void MakeOperationStrong( Container& c, const BasicOp& op ) +{ + Container tmp(c); // Copy c + op(tmp); // Work on the copy + c.swap(tmp); // Cannot fail<a title= +"Associative containers whose Compare object might throw an exception when copied cannot use this technique, since the swap function might fail." + href= +"#footnote7"><sup>7</sup></a> +} +</pre> + </blockquote> + + <p>This technique can be folded into a wrapper class to make a similar + container which provides stronger guarantees (and different performance + characteristics).<a title= + "This suggests another potential use for the oft-wished-for but as yet unseen container traits<> template: automated container selection to meet exceptionsafety constraints." + href= + "#footnote8"><sup>8</sup></a> + + <h2>6 Should we take everything we can get?</h2> + + <p>By considering a particular implementation, we can hope to discern a + natural level of safety. The danger in using this to establish requirements + for a component is that the implementation might be restricted. If someone + should come up with a more-efficient implementation which we'd like to use, + we may find that it's incompatible with our exception-safety requirements. + One might expect this to be of no concern in the well-explored domains of + data structures and algorithms covered by the STL, but even there, advances + are being made. A good example is the recent <i>introsort</i> algorithm <a + title= + "D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997." + href= + "#reference6"><sup>[6]</sup></a>, + which represents a substantial improvement in worst-case complexity over + the well-established <i>quicksort</i>. + + <p>To determine exactly how much to demand of the standard components, I + looked at a typical real-world scenario. The chosen test case was a + ``composite container.'' Such a container, built of two or more + standard container components, is not only commonly needed, but serves as a + simple representative case for maintaining invariants in larger systems: + + <blockquote> +<pre>// SearchableStack - A stack which can be efficiently searched +// for any value. +template <class T> +class SearchableStack +{ + public: + void push(const T& t); // O(log n) + void pop(); // O(log n) + bool contains(const T& t) const; // O(log n) + const T& top() const; // O(1) + private: + std::set<T> set_impl; + std::list<std::set<T>::iterator> list_impl; +}; +</pre> + </blockquote> + + <p>The idea is that the list acts as a stack of set iterators: every + element goes into the set first, and the resulting position is pushed onto + the list. The invariant is straightforward: the set and the list should + always have the same number of elements, and every element of the set + should be referenced by an element of the list. The following + implementation of the push function is designed to give the <i>strong</i> + guarantee within the natural levels of safety provided by set and list: + + <blockquote> +<pre>template <class T> // 1 +void SearchableStack<T>::push(const T& t) // 2 +{ // 3 + set<T>::iterator i = set_impl.insert(t); // 4 + try // 5 + { // 6 + list_impl.push_back(i); // 7 + } // 8 + catch(...) // 9 + { // 10 + set_impl.erase(i); // 11 + throw; // 12 + } // 13 +} // 14 +</pre> + </blockquote> + + <p>What does our code actually require of the library? We need to examine + the lines where non-const operations occur: + + <ul> + <li>Line 4: if the insertion fails but <code>set_impl</code> is modified + in the process, our invariant is violated. We need to be able to rely on + the <i>strong</i> guarantee from <code>set<T>::insert</code>. + + <li>Line 7: likewise, if <code>push_back</code> fails, but + <code>list_impl</code> is modified in the process, our invariant is + violated, so we need to be able to rely on the <i>strong</i> guarantee + from list<T>::insert. + + <li>Line 11: here we are ``rolling back'' the insertion on line + 4. If this operation should fail, we will be unable to restore our + invariant. We absolutely depend on the <i>no-throw</i> guarantee from + <code>set<T>::erase</code>.<a title= + "One might be tempted to surround the erase operation with a try/catch block to reduce the requirements on set<T> and the problems that arise in case of an exception, but in the end that just begs the question. First, erase just failed and in this case there are no viable alternative ways to produce the necessary result. Second and more generally, because of the variability of its type parameters a generic component can seldom be assured that any alternatives will succeed." + href= + "#footnote9"><sup>9</sup></a> + + <li>Line 11: for the same reasons, we also depend on being able to pass + the <code>i</code> to the <code>erase</code> function: we need the + <i>no-throw</i> guarantee from the copy constructor of + <code>set<T>::iterator</code>. + </ul> + + <p>I learned a great deal by approaching the question this way during + standardization. First, the guarantee specified for the composite container + actually depends on stronger guarantees from its components (the + <i>no-throw</i> guarantees in line 11). Also, I took advantage of all of + the natural level of safety to implement this simple example. Finally, the + analysis revealed a requirement on iterators which I had previously + overlooked when operations were considered on their own. The conclusion was + that we should provide as much of the natural level of safety as possible. + Faster but less-safe implementations could always be provided as extensions + to the standard components. <sup><a title= + "The prevalent philosophy in the design of STL was that functionality that wasn't essential to all uses should be left out in favor of efficiency, as long as that functionality could be obtained when needed by adapting the base components. This departs from that philosophy, but it would be difficult or impossible to obtain even the basic guarantee by adapting a base component that doesn't already have it." + name="#footnote10">10</a></sup> + + <h2>7 Automated testing for exception-safety</h2> + + <p>As part of the standardization process, I produced an exception-safe + reference implementation of the STL. Error-handling code is seldom + rigorously tested in real life, in part because it is difficult to cause + error conditions to occur. It is very common to see error-handling code + which crashes the first time it is executed ...in a shipping product! To + bolster confidence that the implementation actually worked as advertised, I + designed an automated test suite, based on an exhaustive technique due to + my colleague Matt Arnold. + + <p>The test program started with the basics: reinforcement and + instrumentation, especially of the global operators <code>new</code> and + <code>delete</code>.<sup><a title= + "An excellent discussion on how to fortify memory subsystems can be found in: Steve Maguire, Writing Solid Code, Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4." + name="#footnote11">11</a></sup>Instances of the components (containers and + algorithms) were created, with type parameters chosen to reveal as many + potential problems as possible. For example, all type parameters were given + a pointer to heap-allocated memory, so that leaking a contained object + would be detected as a memory leak. + + <p>Finally, a scheme was designed that could cause an operation to throw an + exception at each possible point of failure. At the beginning of every + client-supplied operation which is allowed to throw an exception, a call to + <code>ThisCanThrow</code> was added. A call to <code>ThisCanThrow</code> + also had to be added everywhere that the generic operation being tested + might throw an exception, for example in the global operator + <code>new</code>, for which an instrumented replacement was supplied. + + <blockquote> +<pre>// Use this as a type parameter, e.g. vector<TestClass> +struct TestClass +{ + TestClass( int v = 0 ) + : p( ThisCanThrow(), new int( v ) ) {} + TestClass( const TestClass& rhs ) + : p( ThisCanThrow(), new int( *rhs.p ) ) {} + const TestClass& operator=( const TestClass& rhs ) + { ThisCanThrow(); *p = *rhs.p; } + bool operator==( const TestClass& rhs ) + { ThisCanThrow(); return *p == *rhs.p; } + ...etc... + ~TestClass() { delete p; } +}; +</pre> + </blockquote> + + <p><code>ThisCanThrow</code> simply decrements a ``throw + counter'' and, if it has reached zero, throws an exception. Each test + takes a form which begins the counter at successively higher values in an + outer loop and repeatedly attempts to complete the operation being tested. + The result is that the operation throws an exception at each successive + step along its execution path that can possibly fail. For example, here is + a simplified version of the function used to test the <i>strong</i> + guarantee: <a title= + "Note that this technique requires that the operation being tested be exception-neutral. If the operation ever tries to recover from an exception and proceed, the throw counter will be negative, and subsequent operations that might fail will not be tested for exception-safety." + href= + "#footnote12"><sup>12</sup></a> + + <blockquote> +<pre>extern int gThrowCounter; // The throw counter +void ThisCanThrow() +{ + if (gThrowCounter-- == 0) + throw 0; +} + +template <class Value, class Operation> +void StrongCheck(const Value& v, const Operation& op) +{ + bool succeeded = false; + for (long nextThrowCount = 0; !succeeded; ++nextThrowCount) + { + Value duplicate = v; + try + { + gThrowCounter = nextThrowCount; + op( duplicate ); // Try the operation + succeeded = true; + } + catch(...) // Catch all exceptions + { + bool unchanged = duplicate == v; // Test <i>strong</i> guarantee + assert( unchanged ); + } + // Specialize as desired for each container type, to check + // integrity. For example, size() == distance(begin(),end()) + CheckInvariant(v); // Check any invariant + } +} +</pre> + </blockquote> + + <p>Notably, this kind of testing is much easier and less intrusive with a + generic component than with non-generics, because testing-specific type + parameters can be used without modifying the source code of the component + being tested. Also, generic functions like <code>StrongCheck</code> above + were instrumental in performing the tests on a wide range of values and + operations. + + <h2>8 Further Reading</h2> + To my knowledge, there are currently only two descriptions of STL + exception-safety available. The original specification <a title= + "D. Abrahams, Exception Safety in STLport" href= + "#reference2"><sup>[2]</sup></a> + for the reference exception-safe implementation of the STL is an informal + specification, simple and self-explanatory (also verbose), and uses the + <i>basic-</i> and <i>strong-</i>guarantee distinctions outlined in this + article. It explicitly forbids leaks, and differs substantively from the + final C++ standard in the guarantees it makes, though they are largely + identical. I hope to produce an updated version of this document soon. + + <p>The description of exception-safety in the C++ Standard <a title= + "International Standard ISO/IEC 14882, Information Technology-Programming Languages-C++, Document Number ISO/IEC 14882-1998" + href= + "#reference1"><sup>[1]</sup></a> + is only slightly more formal, but relies on hard-to-read + ``standardese'' and an occasionally subtle web of implication.<a + title= + "The changes to the draft standard which introduced exception-safety were made late in the process, when amendments were likely to be rejected solely on the basis of the number of altered words. Unfortunately, the result compromises clarity somewhat in favor of brevity. Greg Colvin was responsible for the clever language-lawyering needed to minimize the extent of these changes." + href= + "#footnote13"><sup>13</sup></a> + In particular, leaks are not treated directly at all. It does have the + advantage that it <i>is</i> the standard. + + <p>The original reference implementation <a title= + "B. Fomitchev, Adapted SGI STL Version 1.0, with exception handling code by D. Abrahams" + href= + "#reference5"><sup>[5]</sup></a> + of the exception-safe STL is an adaptation of an old version of the SGI + STL, designed for C++ compilers with limited features. Although it is not a + complete STL implementation, the code may be easier to read, and it + illustrates a useful base-class technique for eliminating + exception-handling code in constructors. The full test suite <a title= + "D. Abrahams and B. Fomitchev, Exception Handling Test Suite" href= + "#reference3"><sup>[3]</sup></a> + used to validate the reference implementation has been used successfully to + validate all recent versions of the SGI STL, and has been adapted to test + one other vendor's implementation (which failed). As noted on the + documentation page, it also seems to have the power to reveal hidden + compiler bugs, particularly where optimizers interact with + exception-handling code. + + <h2>References</h2> + + <ol> + <li><a name="reference1">International</a> Standard ISO/IEC 14882, + <i>Information Technology-Programming Languages-C++</i>, Document Number + ISO/IEC 14882-1998, available from <a href= + "http://webstore.ansi.org/ansidocstore/default.asp">http://webstore.ansi.org/ansidocstore/default.asp</a>. + + <li><a name="reference2">D.</a> Abrahams, <i>Exception Safety in + STLport</i>, available at <a href= + "http://www.stlport.org/doc/exception_safety.html">http://www.stlport.org/doc/exception_safety.html</a>. + + <li><a name="reference3">D.</a> Abrahams and B. Fomitchev, <i>Exception + Handling Test Suite</i>, available at <a href= + "http://www.stlport.org/doc/eh_testsuite.html">http://www.stlport.org/doc/eh_testsuite.html</a>. + + <li><a name="reference4">Tom</a> Cargill, ``Exception Handling: + A False Sense of Security,'' C++ Report, Nov-Dec 1994, also + available at <a href= + "http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html">http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html</a>. + + <li><a name="reference5">B.</a> Fomitchev, <i>Adapted SGI STL Version + 1.0</i>, with exception handling code by D. Abrahams, available at <a + href= + "http://www.metabyte.com/~fbp/stl/old.html">http://www.metabyte.com/~fbp/stl/old.html</a>. + + <li><a name="reference6">D.</a> R. Musser, ``Introspective Sorting + and Selection Algorithms,'' <i>Software-Practice and Experience</i> + 27(8):983-993, 1997. + + <li><a name="reference7">Bjarne</a> Stroustrup, <i>The Design And + Evolution of C++</i>. Addison Wesley, Reading, MA, 1995, ISBN + 0-201-54330-3, Section 16.9.1. + </ol> + + <h2>Footnotes</h2> + + <p><a name="footnote1">1</a> Probably the greatest impediment to a solution + in Cargill's case was an unfortunate combination of choices on his part: + the interface he chose for his container was incompatible with his + particular demands for safety. By changing either one he might have solved + the problem. + + <p><a name="footnote2">2</a> It is usually inadvisable to throw an + exception from a destructor in C++, since the destructor may itself be + called during the stack-unwinding caused by another exception. If the + second exception is allowed to propagate beyond the destructor, the program + is immediately terminated. + + <p><a name="footnote3">3</a> In practice of course, this function would + make an extremely poor random sequence generator! + + <p><a name="footnote4">4</a> It is worth noting that mutating algorithms + usually cannot provide the <i>strong</i> guarantee: to roll back a modified + element of a range, it must be set back to its previous value using + <code>operator=</code>, which itself might throw. In the C++ standard + library, there are a few exceptions to this rule, whose rollback behavior + consists only of destruction: <code>uninitialized_copy</code>, + <code>uninitialized_fill</code>, and <code>uninitialized_fill_n</code>. + + <p><a name="footnote5">5</a> All type parameters supplied by clients of the + C++ standard library are required not to throw from their destructors. In + return, all components of the C++ standard library provide at least the + <i>basic</i> guarantee. + + <p><a name="footnote6">6</a> Similar arrangements might have been made in + the C++ standard for many of the mutating algorithms, but were never + considered due to time constraints on the standardization process. + + <p><a name="footnote7">7</a> Associative containers whose + <code>Compare</code> object might throw an exception when copied cannot use + this technique, since the swap function might fail. + + <p><a name="footnote8">8</a> This suggests another potential use for the + oft-wished-for but as yet unseen <code>container_traits<></code> + template: automated container selection to meet exception-safety + constraints. + + <p><a name="footnote9">9</a> One might be tempted to surround the erase + operation with a <code>try</code>/<code>catch</code> block to reduce the + requirements on <code>set<T></code> and the problems that arise in + case of an exception, but in the end that just begs the question. First, + erase just failed and in this case there are no viable alternative ways to + produce the necessary result. Second and more generally, because of the + variability of its type parameters a generic component can seldom be + assured that any alternatives will succeed. + + <p><a name="footnote10">10</a> The prevalent philosophy in the design of + STL was that functionality that wasn't essential to all uses should be left + out in favor of efficiency, as long as that functionality could be obtained + when needed by adapting the base components. This departs from that + philosophy, but it would be difficult or impossible to obtain even the + <i>basic</i> guarantee by adapting a base component that doesn't already + have it. + + <p><a name="footnote11">11</a> An excellent discussion on how to fortify + memory subsystems can be found in: Steve Maguire, Writing Solid Code, + Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4. + + <p><a name="footnote12">12</a> Note that this technique requires that the + operation being tested be exception-neutral. If the operation ever tries to + recover from an exception and proceed, the throw counter will be negative, + and subsequent operations that might fail will not be tested for + exception-safety. + + <p><a name="footnote13">13</a> The changes to the draft standard which + introduced exception-safety were made late in the process, when amendments + were likely to be rejected solely on the basis of the number of altered + words. Unfortunately, the result compromises clarity somewhat in favor of + brevity. Greg Colvin was responsible for the clever language-lawyering + needed to minimize the extent of these changes.
\ No newline at end of file diff --git a/more/generic_programming.html b/more/generic_programming.html new file mode 100644 index 0000000000..9cd5d80342 --- /dev/null +++ b/more/generic_programming.html @@ -0,0 +1,448 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + + <title>Generic Programming Techniques</title> + + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" + width="277" height="86"> + + <body bgcolor="#FFFFFF" text="#000000"> + + <h1>Generic Programming Techniques</h1> + + <p>This is an incomplete survey of some of the generic programming + techniques used in the <a href="../index.htm">boost</a> libraries. + + <h2>Table of Contents</h2> + + <ul> + <li><a href="#introduction">Introduction</a> + + <li><a href="#concept">The Anatomy of a Concept</a> + + <li><a href="#traits">Traits</a> + + <li><a href="#tag_dispatching">Tag Dispatching</a> + + <li><a href="#adaptors">Adaptors</a> + + <li><a href="#type_generator">Type Generators</a> + + <li><a href="#object_generator">Object Generators</a> + + <li><a href="#policy">Policy Classes</a> + </ul> + + <h2><a name="introduction">Introduction</a></h2> + + <p>Generic programming is about generalizing software components so that + they can be easily reused in a wide variety of situations. In C++, class + and function templates are particularly effective mechanisms for generic + programming because they make the generalization possible without + sacrificing efficiency. + + <p>As a simple example of generic programming, we will look at how one + might generalize the <tt>memcpy()</tt> function of the C standard library. + An implementation of <tt>memcpy()</tt> might look like the following: + <br> + <br> + + <blockquote> +<pre> +void* memcpy(void* region1, const void* region2, size_t n) +{ + const char* first = (const char*)region2; + const char* last = ((const char*)region2) + n; + char* result = (char*)region1; + while (first != last) + *result++ = *first++; + return result; +} +</pre> + </blockquote> + The <tt>memcpy()</tt> function is already generalized to some extent by the + use of <tt>void*</tt> so that the function can be used to copy arrays of + different kinds of data. But what if the data we would like to copy is not + in an array? Perhaps it is in a linked list. Can we generalize the notion + of copy to any sequence of elements? Looking at the body of + <tt>memcpy()</tt>, the function's <b><i>minimal requirements</i></b> are + that it needs to to <i>traverse</i> through the sequence using some sort of + pointer, <i>access</i> elements pointed to, <i>write</i> the elements to + the destination, and <i>compare</i> pointers to know when to stop. The C++ + standard library groups requirements such as these into + <b><i>concepts</i></b>, in this case the <a href= + "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a> concept + (for <tt>region2</tt>) and the <a href= + "http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a> + concept (for <tt>region1</tt>). + + <p>If we rewrite the <tt>memcpy()</tt> as a function template, and use the + <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a> + and <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output + Iterator</a> concepts to describe the requirements on the template + parameters, we can implement a highly reusable <tt>copy()</tt> function in + the following way: + <br> + <br> + + <blockquote> +<pre> +template <typename InputIterator, typename OutputIterator> +OutputIterator +copy(InputIterator first, InputIterator last, OutputIterator result) +{ + while (first != last) + *result++ = *first++; + return result; +} +</pre> + </blockquote> + + <p>Using the generic <tt>copy()</tt> function, we can now copy elements + from any kind of sequence, including a linked list that exports iterators + such as <tt>std::<a href= + "http://www.sgi.com/tech/stl/List.html">list</a></tt>. + <br> + <br> + + <blockquote> +<pre> +#include <list> +#include <vector> +#include <iostream> + +int main() +{ + const int N = 3; + std::vector<int> region1(N); + std::list<int> region2; + + region2.push_back(1); + region2.push_back(0); + region2.push_back(3); + + std::copy(region2.begin(), region2.end(), region1.begin()); + + for (int i = 0; i < N; ++i) + std::cout << region1[i] << " "; + std::cout << std::endl; +} +</pre> + </blockquote> + + <h2><a name="concept">Anatomy of a Concept</a></h2> + A <b><i>concept</i></b> is a set requirements, where the requirements + consist of valid expressions, associated types, invariants, and complexity + guarantees. A type that satisfies the set of requirements is said to + <b><i>model</i></b> the concept. A concept can extend the requirements of + another concept, which is called <b><i>refinement</i></b>. + + <ul> + <li><a name="valid_expression"><b>Valid Expressions</b></a> are C++ + expressions which must compile successfully for the objects involved in + the expression to be considered <i>models</i> of the concept. + + <li><a name="associated_type"><b>Associated Types</b></a> are types that + are related to the modeling type in that they participate in one or more + of the valid expressions. Typically associated types can be accessed + either through typedefs nested within a class definition for the modeling + type, or they are accessed through a <a href="#traits">traits class</a>. + + <li><b>Invariants</b> are run-time characteristics of the objects that + must always be true, that is, the functions involving the objects must + preserve these characteristics. The invariants often take the form of + pre-conditions and post-conditions. + + <li><b>Complexity Guarantees</b> are maximum limits on how long the + execution of one of the valid expressions will take, or how much of + various resources its computation will use. + </ul> + + <p>The concepts used in the C++ Standard Library are documented at the <a + href="http://www.sgi.com/tech/stl/table_of_contents.html">SGI STL site</a>. + + <h2><a name="traits">Traits</a></h2> + + <p>A traits class provides a way of associating information with a + compile-time entity (a type, integral constant, or address). For example, + the class template <tt><a href= + "http://www.sgi.com/tech/stl/iterator_traits.html">std::iterator_traits<T></a></tt> + looks something like this: + + <blockquote> +<pre> +template <class Iterator> +struct iterator_traits { + typedef ... iterator_category; + typedef ... value_type; + typedef ... difference_type; + typedef ... pointer; + typedef ... reference; +}; +</pre> + </blockquote> + The traits' <tt>value_type</tt> gives generic code the type which the + iterator is "pointing at", while the <tt>iterator_category</tt> can be used + to select more efficient algorithms depending on the iterator's + capabilities. + + <p>A key feature of traits templates is that they're <i>non-intrusive</i>: + they allow us to associate information with arbitrary types, including + built-in types and types defined in third-party libraries, Normally, traits + are specified for a particular type by (partially) specializing the traits + template. + + <p>For an in-depth description of <tt>std::iterator_traits</tt>, see <a + href="http://www.sgi.com/tech/stl/iterator_traits.html">this page</a> + provided by SGI. Another very different expression of the traits idiom in + the standard is <tt>std::numeric_limits<T></tt> which provides + constants describing the range and capabilities of numeric types. + + <h2><a name="tag_dispatching">Tag Dispatching</a></h2> + + <p>A technique that often goes hand in hand with traits classes is tag + dispatching, which is a way of using function overloading to dispatch based + on properties of a type. A good example of this is the implementation of the + <a href= + "http://www.sgi.com/tech/stl/advance.html"><tt>std::advance()</tt></a> + function in the C++ Standard Library, which increments an iterator + <tt>n</tt> times. Depending on the kind of iterator, there are different + optimizations that can be applied in the implementation. If the iterator is + <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">random + access</a> (can jump forward and backward arbitrary distances), then the + <tt>advance()</tt> function can simply be implemented with <tt>i += n</tt>, + and is very efficient: constant time. Other iterators must be + <tt>advance</tt>d in steps, making the operation linear in n. If the + iterator is <a href= + "http://www.sgi.com/tech/stl/BidirectionalIterator.html">bidirectional</a>, + then it makes sense for <tt>n</tt> to be negative, so we must decide whether + to increment or decrement the iterator. + + <p>The relation between tag dispatching and traits classes is that the + property used for dispatching (in this case the <tt>iterator_category</tt>) + is often accessed through a traits class. The main <tt>advance()</tt> function + uses the <a href= + "http://www.sgi.com/tech/stl/iterator_traits.html"><tt>iterator_traits</tt></a> + class to get the <tt>iterator_category</tt>. It then makes a call the the + overloaded <tt>advance_dispatch()</tt> function. The appropriate + <tt>advance_dispatch()</tt> is selected by the compiler based on whatever + type the <tt>iterator_category</tt> resolves to, either <a href= + "http://www.sgi.com/tech/stl/input_iterator_tag.html"><tt>input_iterator_tag</tt></a>, + <a href= + "http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html"><tt>bidirectional_iterator_tag</tt></a>, + or <a href= + "http://www.sgi.com/tech/stl/random_access_iterator_tag.html"><tt>random_access_iterator_tag</tt></a>. + A <b><i>tag</i></b> is simply a class whose only purpose is to convey some + property for use in tag dispatching and similar techniques. Refer to <a + href="http://www.sgi.com/tech/stl/iterator_tags.html">this page</a> for a + more detailed description of iterator tags. + + <blockquote> +<pre> +namespace std { + struct input_iterator_tag { }; + struct bidirectional_iterator_tag { }; + struct random_access_iterator_tag { }; + + namespace detail { + template <class InputIterator, class Distance> + void advance_dispatch(InputIterator& i, Distance n, <b>input_iterator_tag</b>) { + while (n--) ++i; + } + + template <class BidirectionalIterator, class Distance> + void advance_dispatch(BidirectionalIterator& i, Distance n, + <b>bidirectional_iterator_tag</b>) { + if (n >= 0) + while (n--) ++i; + else + while (n++) --i; + } + + template <class RandomAccessIterator, class Distance> + void advance_dispatch(RandomAccessIterator& i, Distance n, + <b>random_access_iterator_tag</b>) { + i += n; + } + } + + template <class InputIterator, class Distance> + void advance(InputIterator& i, Distance n) { + typename <b>iterator_traits<InputIterator>::iterator_category</b> category; + detail::advance_dispatch(i, n, <b>category</b>); + } +} +</pre> + </blockquote> + + <h2><a name="adaptors">Adaptors</a></h2> + + <p>An <i>adaptor</i> is a class template which builds on another type or + types to provide a new interface or behavioral variant. Examples of + standard adaptors are <a href= + "http://www.sgi.com/tech/stl/ReverseIterator.html">std::reverse_iterator</a>, + which adapts an iterator type by reversing its motion upon + increment/decrement, and <a href= + "http://www.sgi.com/tech/stl/stack.html">std::stack</a>, which adapts a + container to provide a simple stack interface. + + <p>A more comprehensive review of the adaptors in the standard can be found + <a href= + "http://www.cs.rpi.edu/~wiseb/xrds/ovp2-3b.html#SECTION00015000000000000000"> + here</a>. + + <h2><a name="type_generator">Type Generators</a></h2> + + <p>A <i>type generator</i> is a template whose only purpose is to + synthesize a new type or types based on its template argument(s)<a href= + "#1">[1]</a>. The generated type is usually expressed as a nested typedef + named, appropriately <tt>type</tt>. A type generator is usually used to + consolidate a complicated type expression into a simple one, as in + <tt>boost::<a href= + "../libs/utility/filter_iterator.htm">filter_iterator_generator</a></tt>, + which looks something like this: + + <blockquote> +<pre> +template <class Predicate, class Iterator, + class Value = <i>complicated default</i>, + class Reference = <i>complicated default</i>, + class Pointer = <i>complicated default</i>, + class Category = <i>complicated default</i>, + class Distance = <i>complicated default</i> + > +struct filter_iterator_generator { + typedef iterator_adaptor< + Iterator,filter_iterator_policies<Predicate,Iterator>, + Value,Reference,Pointer,Category,Distance> <b>type</b>; +}; +</pre> + </blockquote> + + <p>Now, that's complicated, but producing an adapted filter iterator is + much easier. You can usually just write: + + <blockquote> +<pre> +boost::filter_iterator_generator<my_predicate,my_base_iterator>::type +</pre> + </blockquote> + + <h2><a name="object_generator">Object Generators</a></h2> + + <p>An <i>object generator</i> is a function template whose only purpose is + to construct a new object out of its arguments. Think of it as a kind of + generic constructor. An object generator may be more useful than a plain + constructor when the exact type to be generated is difficult or impossible + to express and the result of the generator can be passed directly to a + function rather than stored in a variable. Most Boost object generators are + named with the prefix "<tt>make_</tt>", after <tt>std::<a href= + "http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const T&, const U&)</tt>. + + <p>For example, given: + + <blockquote> +<pre> +struct widget { + void tweak(int); +}; +std::vector<widget *> widget_ptrs; +</pre> + </blockquote> + By chaining two standard object generators, <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/functio2.html#bind2nd">bind2nd</a>()</tt> + and <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/functio2.html#mem_fun">mem_fun</a>()</tt>, + we can easily tweak all widgets: + + <blockquote> +<pre> +void tweak_all_widgets1(int arg) +{ + for_each(widget_ptrs.begin(), widget_ptrs.end(), + <b>bind2nd</b>(std::<b>mem_fun</b>(&widget::tweak), arg)); +} +</pre> + </blockquote> + + <p>Without using object generators the example above would look like this: + + <blockquote> +<pre> +void tweak_all_widgets2(int arg) +{ + for_each(struct_ptrs.begin(), struct_ptrs.end(), + <b>std::binder2nd<std::mem_fun1_t<void, widget, int> ></b>( + std::<b>mem_fun1_t<void, widget, int></b>(&widget::tweak), arg)); +} +</pre> + </blockquote> + + <p>As expressions get more complicated the need to reduce the verbosity of + type specification gets more compelling. + + <h2><a name="policy">Policy Classes</a></h2> + + <p>A policy class is a template parameter used to transmit behavior. An + example from the standard library is <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></tt>, + which supplies memory management behaviors to standard <a href= + "http://www.sgi.com/tech/stl/Container.html">containers</a>. + + <p>Policy classes have been explored in detail by <a href= + "mailto:andrewalex@hotmail.com">Andrei Alexandrescu</a> in <a href= + "http://www.cs.ualberta.ca/~hoover/cmput401/XP-Notes/xp-conf/Papers/7_3_Alexandrescu.pdf"> + this paper</a>. He writes: + + <blockquote> + <p>Policy classes are implementations of punctual design choices. They + are inherited from, or contained within, other classes. They provide + different strategies under the same syntactic interface. A class using + policies is templated having one template parameter for each policy it + uses. This allows the user to select the policies needed. + + <p>The power of policy classes comes from their ability to combine + freely. By combining several policy classes in a template class with + multiple parameters, one achieves combinatorial behaviors with a linear + amount of code. + </blockquote> + + <p>Andrei's description of policy classes describe their power as being + derived from their granularity and orthogonality. Boost has probably + diluted the distinction in the <a href= + "../libs/utility/iterator_adaptors.htm">Iterator Adaptors</a> library, + where we transmit all of an adapted iterator's behavior in a single policy + class. There is precedent for this, however: <tt><a href= + "http://www.dinkumware.com/htm_cpl/string2.html#char_traits">std::char_traits</a></tt>, + despite its name, acts as a policies class that determines the behaviors of + <a href= + "http://www.dinkumware.com/htm_cpl/string2.html#basic_string">std::basic_string</a>. + + <h2>Notes</h2> + <a name="1">[1]</a> Type generators are a workaround for the lack of + ``templated typedefs'' in C++. + <hr> + + <p>Revised + <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->14 Mar 2001<!--webbot bot="Timestamp" endspan i-checksum="14885" --> + + + <p>© Copyright David Abrahams 2001. Permission to copy, use, modify, + sell and distribute this document is granted provided this copyright notice + appears in all copies. This document is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any purpose. + <!-- LocalWords: HTML html charset gif alt htm struct SGI namespace std libs + --> + <!-- LocalWords: InputIterator BidirectionalIterator RandomAccessIterator pdf + --> + <!-- LocalWords: typename Alexandrescu templated Andrei's Abrahams memcpy int + --> + + <!-- LocalWords: const OutputIterator iostream pre cpl + --> + + </body> diff --git a/more/header.htm b/more/header.htm new file mode 100644 index 0000000000..08d948080a --- /dev/null +++ b/more/header.htm @@ -0,0 +1,97 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost Header policy</title> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="Microsoft Border" content="none, default"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Header Policy</h1> +<p>Header files are the place where a library comes into contact with user code +and other libraries. To co-exist peacefully and productively, headers must +be "good neighbors".</p> +<p>Here are the standards for namespace boost headers. Many of +these are also reasonable guidelines for general use. +<ul> + <li>Headers should have a .hpp (lowercase) filename extension. </li> + <li>Wrap the header in #ifndef guards so that multiple inclusion is + benign. Use a naming convention that minimizes the chance of clashes + with macro names from other's code. The <a href="#Sample header">sample + header</a> uses the Boost convention of all uppercase letters, with the + header name prefixed by the namespace name, and suffixed with HPP, separated + by underscores.</li> + <li>Wrap the header contents in a namespace to prevent global namespace + pollution. The namespace approach to pollution control is strongly preferred + to older approaches such as adding funny prefixes to global names. + Libraries which are designed to work well with other Boost libraries should + be placed namespace <tt>boost</tt>.</li> + + <li>Make sure that a translation unit consisting of just the + contents of the header file will compile successfully. + + <li>Place the header file in a sub-directory to prevent conflict with + identically named header files in other libraries. The parent + directory is added to the compiler's include search path. Then both + your code and user code specifies the sub-directory in <tt>#include</tt> + directives. Thus the header <a href="#Sample header">sample header</a> + would be included by <tt>#include <boost/furball.hpp></tt></li> + <li>The preferred ordering for class definitions is public members, protected + members, and finally private members.</li> + <li>Include the boost/config.hpp <a href="../libs/config/config.htm">configuration + header</a> if there is a need to deal with compiler or platform + configuration issues.</li> +</ul> +<h2><a name="Sample header"></a>Sample Header</h2> +<pre><tt>// Boost general library furball.hpp header file ---------------------------// + +// (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and +// distribute this software is granted provided this copyright notice appears +// in all copies. This software is provided "as is" without express or implied +// warranty, and with no claim as to its suitability for any purpose. + +// See http://www.boost.org for updates, documentation, and revision history. + +#ifndef BOOST_FURBALL_HPP +#define BOOST_FURBALL_HPP + +namespace boost { + +// Furball class declaration -----------------------------------------------// + + class furball + { + public: + void throw_up(); + private: + int whatever; + }; // furball + +} // namespace + +#endif // BOOST_FURBALL_HPP</tt></pre> +<h2>Coding Style</h2> +<p>The alert reader will have noticed that the <a href="#Sample header">sample +header</a> employs a certain coding style for indentation, positioning braces, +commenting ending braces, and similar formatting issues. These stylistic +issues are viewed as personal preferences and are not part of the Boost Header +Policy.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 September, 2001<!--webbot bot="Timestamp" endspan i-checksum="39344" --></p> + +</body> + +</html> diff --git a/more/imp_vars.htm b/more/imp_vars.htm new file mode 100644 index 0000000000..a267910693 --- /dev/null +++ b/more/imp_vars.htm @@ -0,0 +1,201 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Implementation Variations</title> +</head> + +<body link="#0000ff" vlink="#800080" bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Implementation Variations</h1> +<h2>Separation of interface and implementation</h2> +<p>The interface specifications for boost.org library components (as well as for +quality software in general) are conceptually separate from implementations of +those interfaces. This may not be obvious, particularly when a component is +implemented entirely within a header, but this separation of interface and +implementation is always assumed. From the perspective of those concerned with +software design, portability, and standardization, the interface is what is +important, while the implementation is just a detail.</p> +<p>Dietmar Kühl, one of the original boost.org contributors, comments "The +main contribution is the interface, which is augmented with an implementation, +proving that it is possible to implement the corresponding class and providing a +free implementation."</p> +<b> +<h2>Implementation variations</h2> +</b> +<p>There may be a need for multiple implementations of an interface, to +accommodate either platform dependencies or performance tradeoffs. Examples of +platform dependencies include compiler shortcomings, file systems, thread +mechanisms, and graphical user interfaces. The classic example of a performance +tradeoff is a fast implementation which uses a lot of memory versus a slower +implementation which uses less memory.</p> +<p>Boost libraries generally use a <a href="../libs/config/config.htm">configuration +header</a>, boost/config.hpp, to capture compiler and platform +dependencies. Although the use of boost/config.hpp is not required, it is +the preferred approach for simple configuration problems. </p> +<h2>Boost policy</h2> +<p>The Boost policy is to avoid platform dependent variations in interface +specifications, but supply implementations which are usable over a wide range of +platforms and applications. That means boost libraries will use the +techniques below described as appropriate for dealing with platform +dependencies.</p> +<p>The Boost policy toward implementation variations designed to enhance +performance is to avoid them unless the benefits greatly exceed the full +costs. The term "full costs" is intended to include both +tangible costs like extra maintenance, and intangible cost like increased +difficulty in user understanding.</p> +<b> +<h2>Techniques for providing implementation variations</h2> +</b> +<p>Several techniques may be used to provide implementation variations. Each is +appropriate in some situations, and not appropriate in other situations.</p> +<h3>Single general purpose implementation</h3> +<p>The first technique is to simply not provide implementation variation at +all. Instead, provide a single general purpose implementation, and forgo +the increased complexity implied by all other techniques.</p> +<p><b>Appropriate:</b> When it is possible to write a single portable +implementation which has reasonable performance across a wide range of +platforms. Particularly appropriate when alternative implementations differ only +in esoteric ways.</p> +<p><b>Not appropriate:</b> When implementation requires platform specific +features, or when there are multiple implementation possible with widely +differing performance characteristics.</p> +<p>Beman Dawes comments "In design discussions some implementation is often +alleged to be much faster than another, yet a timing test discovers no +significant difference. The lesson is that while algorithmic differences may +affect speed dramatically, coding differences such as changing a class from +virtual to non-virtual members or removing a level of indirection are unlikely +to make any measurable difference unless deep in an inner loop. And even in an +inner loop, modern CPU’s often execute such competing code sequences in the +same number of clock cycles! A single general purpose implementation is +often just fine."</p> +<p>Or as Donald Knuth said, "Premature optimization is the root of all +evil." (Computing Surveys, vol 6, #4, p 268).</p> +<h3>Macros</h3> +<p>While the evils of macros are well known, there remain a few cases where +macros are the preferred solution:</p> +<blockquote> + <ul> + <li> Preventing multiple inclusion of headers via #include guards.</li> + <li> Passing minor configuration information from a configuration + header to other files.</li> + </ul> +</blockquote> +<p><b>Appropriate:</b> For small compile-time variations which would +otherwise be costly or confusing to install, use, or maintain. More appropriate +to communicate within and between library components than to communicate with +library users.</p> +<p><b>Not appropriate: </b> If other techniques will do.</p> +<p>To minimize the negative aspects of macros:</p> +<blockquote> + <ul> + <li>Only use macros when they are clearly superior to other + techniques. They should be viewed as a last resort.</li> + <li>Names should be all uppercase, and begin with the namespace name. This + will minimize the chance of name collisions. For example, the #include + guard for a boost header called foobar.h might be named BOOST_FOOBAR_H.</li> + </ul> +</blockquote> +<h3>Separate files</h3> +<p>A library component can have multiple variations, each contained in its own +separate file or files. The files for the most appropriate variation are +copied to the appropriate include or implementation directories at installation +time.</p> +<p>The way to provide this approach in boost libraries is to include specialized +implementations as separate files in separate sub-directories in the .ZIP +distribution file. For example, the structure within the .ZIP distribution file +for a library named foobar which has both default and specialized variations +might look something like:</p> +<blockquote> + <pre>foobar.h // The default header file +foobar.cpp // The default implementation file +readme.txt // Readme explains when to use which files +self_contained/foobar.h // A variation with everything in the header +linux/foobar.cpp // Implementation file to replace the default +win32/foobar.h // Header file to replace the default +win32/foobar.cpp // Implementation file to replace the default</pre> +</blockquote> +<p><b>Appropriate:</b> When different platforms require different +implementations, or when there are major performance differences between +possible implementations. </p> +<p><b>Not appropriate:</b> When it makes sense to use more that one of the +variations in the same installation.</p> +<h3>Separate components</h3> +<p>Rather than have several implementation variations of a single component, +supply several separate components. For example, the Boost library currently +supplies <code>scoped_ptr</code> and <code>shared_ptr</code> classes rather than +a single <code>smart_ptr</code> class parameterized to distinguish between the +two cases. There are several ways to make the component choice:</p> +<blockquote> + <ul> + <li>Hardwired by the programmer during coding.</li> + <li>Chosen by programmer written runtime logic (trading off some extra + space, time, and program complexity for the ability to select the + implementation at run-time.)</li> + </ul> +</blockquote> +<p><b>Appropriate: </b>When the interfaces for the variations diverge, and when +it is reasonably to use more than one of the variations. When run-time selection +of implementation is called for.</p> +<p><b>Not appropriate:</b> When the variations are data type, traits, or +specialization variations which can be better handled by making the component a +template. Also not appropriate when choice of variation is best done by some +setup or installation mechanism outside of the program itself. Thus +usually not appropriate to cope with platform differences.</p> +<p><b>Note:</b> There is a related technique where the interface is specified as +an abstract (pure virtual) base class (or an interface definition language), and +the implementation choice is passed off to some third-party, such as a +dynamic-link library or object-request broker. While that is a powerful +technique, it is way beyond the scope of this discussion.</p> +<h3>Template-based approaches</h3> +<p>Turning a class or function into a template is often an elegant way to cope +with variations. Template-based approaches provide optimal space and time +efficiency in return for constraining the implementation selection to compile +time. </p> +<p>Important template techniques include:</p> +<blockquote> + <ul> + <li>Data type parameterization. This allows a single component to + operate on a variety of data types, and is why templates were originally + invented.</li> + <li>Traits parameterization. If parameterization is complex, bundling + up aspects into a single traits helper class can allow great variation + while hiding messy details. The C++ Standard Library provides + several examples of this idiom, such as <code>iterator_traits<></code> + (24.3.1 lib.iterator.traits) and <tt>char_traits<></tt> (21.2 + lib.char.traits).</li> + <li>Specialization. A template parameter can be used purely for the + purpose of selecting a specialization. For example:</li> + </ul> + <blockquote> + <blockquote> + <pre>SomeClass<fast> my_fast_object; // fast and small are empty classes +SomeClass<small> my_small_object; // used just to select specialization</pre> + </blockquote> + </blockquote> +</blockquote> +<p><b>Appropriate: </b>When the need for variation is due to data type or +traits, or is performance related like selecting among several algorithms, and +when a program might reasonably use more than one of the variations.</p> +<p><b>Not appropriate:</b> When the interfaces for variations are +different, or when choice of variation is best done by some mechanism outside of +the program itself. Thus usually not appropriate to cope with platform +differences.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 September, 2001<!--webbot bot="Timestamp" endspan i-checksum="39344" --></p> + +</body> + +</html> diff --git a/more/index.htm b/more/index.htm new file mode 100644 index 0000000000..f2c20cb374 --- /dev/null +++ b/more/index.htm @@ -0,0 +1,129 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<title>Boost More Information</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial">Home</font></a></td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" + size="4" face="Arial">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial">People</font></a></td> + <td><a href="faq.htm"><font color="#FFFFFF" size="4" + face="Arial">FAQ</font></a></td> + <td><a href="index.htm"><font color="#FFFFFF" size="4" + face="Arial">More</font></a></td> + </tr> +</table> + +<h1>More Information</h1> + +<h2>Boost Policies</h2> + +<blockquote> + <p><a href="discussion_policy.htm"><b>Mailing List Discussion + Policy.</b></a> What's acceptable and what isn't.</p> + <p><a href="lib_guide.htm"><b>Library Requirements and + Guidelines</b></a>. Basic standards for those preparing + a submission.</p> + <p><a href="writingdoc/index.html"><strong>Writing + Documentation for Boost</strong></a> Basic guidelines + for writing documentation and templates for quickly generating + documentation that follows the guidelines.</p> + <p><a href="test_policy.htm"><b>Test Policy and Protocols</b></a>. + How testing works at Boost.</p> + <p><a href="submission_process.htm"><b>Library Submission + Process</b></a>. How to submit a library to Boost.</p> + <p><a href="formal_review_process.htm"><b>Library Formal + Review Process</b></a>. Including how to submit a review + comment.</p> + <p><a href="header.htm"><b>Header Policy</b></a>. + Headers are where a library contacts its users, so + programming practices are particularly important.</p> + <p><a href="imp_vars.htm"><b>Implementation Variations</b></a>. + Sometimes one size fits all, sometimes it doesn't. This + page deals with the trade-offs.</p> + <p><a href="library_reuse.htm"><b>Library Reuse</b></a>. + Should Boost libraries use other boost libraries? What + about the C++ Standard Library? It's another trade-off.</p> + <p><b><a href="moderators.html">Moderators</a></b>. Who they are and + what they do.</p> +</blockquote> + +<h2>Boost Whatever</h2> + +<blockquote> + <p><a href="../status/compiler_status.html"><b>Compiler + Status</b></a> Describes what library works with + which compiler.</p> + <p><b><a href="links.htm">Links</a></b> Links of special interest to + Boost users.</p> + <p><b><a href="formal_review_schedule.html">Formal Review Schedule</a></b> + Future, current, and recently past Formal Reviews.</p> + <p><b><a href="release_procedures.htm">Release Procedures</a></b> How + developers and the release manager prepare for a Boost release.</p> + <p><a href="regression.html"><b>Internal Regression Test + Suite</b></a> Describes the tool for generating + the compiler status tables </p> + <p><b><a href="proposal.pdf">Proposal for a C++ Library Repository Web Site</a></b> + The original 1998 proposal that launched Boost.</p> + <p><b><a href="bugs.htm">How to report bugs</a></b> Ways to report + Boost bugs.</p> + <p><b><a href="requesting_new_features.htm">How to request features</a></b> + Ways to request new library features.</p> + <p><b><a href="cpp_committee_meetings.html">C++ Committee Meetings</a></b> + FAQ for Boost Members wishing to attend a standards committee meeting.</p> +</blockquote> + +<h2>Articles and Papers</h2> + +<blockquote> + <p><a href="error_handling.html"><b>Error and Exception + Handling</b></a> describes approaches to errors and + exceptions by <a href="../people/dave_abrahams.htm">David + Abrahams</a>. </p> + <p><a href="count_bdy.htm"><b>Counted Body Techniques</b></a> + by <a href="../people/kevlin_henney.htm">Kevlin Henney</a> is + must reading for those interested in reference counting, a + widely used object management idiom. Originally + published in <a + href="http://www.accu.org/c++sig/public/Overload.html">Overload</a> + magazine.</p> + <p><a href="generic_programming.html"><b>Generic Programming + Techniques</b></a> by <a href="../people/dave_abrahams.htm">David + Abrahams</a> and <a href="../people/jeremy_siek.htm">Jeremy + Siek</a> describe some of the techniques used in Boost + libraries.</p> + <p><a href="feature_model_diagrams.htm"><b>Feature Model + Diagrams in text and HTML</b></a> describes how to represent + feature model diagrams in text form.</p> + <p><a href="borland_cpp.html"><b>Portability Hints: Borland C++ + 5.5.1</b></a> describes Borland C++ portability issues, with + suggested workarounds.</p> + <p><a href="microsoft_vcpp.html"><b>Portability Hints: + Microsoft VC++ 6.0 SP4</b></a> describes Microsoft C++ + portability issues, with suggested workarounds.</p> + <p><a href="int_const_guidelines.htm"><strong>Coding + Guidelines for Integral Constant Expressions</strong></a> + describes how to work through the maze of compiler related + bugs surrounding this tricky topic.</p> +</blockquote> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" +s-format="%d %B, %Y" startspan -->07 March, 2003<!--webbot bot="Timestamp" i-checksum="28842" endspan --></p> +</body> +</html>
\ No newline at end of file diff --git a/more/int_const_guidelines.htm b/more/int_const_guidelines.htm new file mode 100644 index 0000000000..ef3cf145c1 --- /dev/null +++ b/more/int_const_guidelines.htm @@ -0,0 +1,323 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="Template" +content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"> +<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> +<title></title> +</head> + +<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080"> + +<h2 align="center">Coding Guidelines for Integral Constant +Expressions</h2> + +<p>Integral Constant Expressions are used in many places in C++; +as array bounds, as bit-field lengths, as enumerator +initialisers, and as arguments to non-type template parameters. +However many compilers have problems handling integral constant +expressions; as a result of this, programming using non-type +template parameters in particular can be fraught with difficulty, +often leading to the incorrect assumption that non-type template +parameters are unsupported by a particular compiler. This short +article is designed to provide a set of guidelines and +workarounds that, if followed, will allow integral constant +expressions to be used in a manner portable to all the compilers +currently supported by boost. Although this article is mainly +targeted at boost library authors, it may also be useful for +users who want to understand why boost code is written in a +particular way, or who want to write portable code themselves.</p> + +<h3>What is an Integral Constant Expression?</h3> + +<p>Integral constant expressions are described in section 5.19 of +the standard, and are sometimes referred to as "compile time +constants". An integral constant expression can be one of +the following:</p> + +<ol> + <li>A literal integral value, for example 0u or 3L.</li> + <li>An enumerator value.</li> + <li>Global integral constants, for example: <font + face="Courier New"><code><br> + </code></font><code>const int my_INTEGRAL_CONSTANT = 3;</code></li> + <li>Static member constants, for example: <br> + <code>struct myclass<br> + { static const int value = 0; };</code></li> + <li>Member enumerator values, for example:<br> + <code>struct myclass<br> + { enum{ value = 0 }; };</code></li> + <li>Non-type template parameters of integral or enumerator + type.</li> + <li>The result of a <code>sizeof</code> expression, for + example:<br> + <code>sizeof(foo(a, b, c))</code></li> + <li>The result of a <code>static_cast</code>, where the + target type is an integral or enumerator type, and the + argument is either another integral constant expression, + or a floating-point literal.</li> + <li>The result of applying a binary operator to two integral + constant expressions: <br> + <code>INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2 <br> + p</code>rovided that the operator is not an assignment + operator, or comma operator.</li> + <li>The result of applying a unary operator to an integral + constant expression: <br> + <code>op INTEGRAL_CONSTANT1<br> + </code>provided that the operator is not the increment or + decrement operator.</li> +</ol> + +<p> </p> + +<h3>Coding Guidelines</h3> + +<p>The following guidelines are declared in no particular order (in +other words you need to obey all of them - sorry!), and may also +be incomplete, more guidelines may be added as compilers change +and/or more problems are encountered.</p> + +<p><b><i>When declaring constants that are class members always +use the macro BOOST_STATIC_CONSTANT.</i></b></p> + +<pre>template <class T> +struct myclass +{ + BOOST_STATIC_CONSTANT(int, value = sizeof(T)); +};</pre> + +<p>Rationale: not all compilers support inline initialisation of +member constants, others treat member enumerators in strange ways +(they're not always treated as integral constant expressions). +The BOOST_STATIC_CONSTANT macro uses the most appropriate method +for the compiler in question.</p> + +<p><b><i>Don't declare integral constant expressions whose type +is wider than int.</i></b></p> + +<p>Rationale: while in theory all integral types are usable in +integral constant expressions, in practice many compilers limit +integral constant expressions to types no wider than <b>int</b>.</p> + +<p><b><i>Don't use logical operators in integral constant +expressions; use template meta-programming instead.</i></b></p> + +<p>The header <boost/type_traits/ice.hpp> contains a number +of workaround templates, that fulfil the role of logical +operators, for example instead of:</p> + +<p><code>INTEGRAL_CONSTANT1 || INTEGRAL_CONSTANT2</code></p> + +<p>Use:</p> + +<p><code>::boost::type_traits::ice_or<INTEGRAL_CONSTANT1,INTEGRAL_CONSTANT2>::value</code></p> + +<p>Rationale: A number of compilers (particularly the Borland and +Microsoft compilers), tend to not to recognise integral constant +expressions involving logical operators as genuine integral +constant expressions. The problem generally only shows up when +the integral constant expression is nested deep inside template +code, and is hard to reproduce and diagnose.</p> + +<p><b><i>Don't use any operators in an integral constant +expression used as a non-type template parameter</i></b></p> + +<p>Rather than:</p> + +<p><code>typedef myclass<INTEGRAL_CONSTANT1 == +INTEGRAL_CONSTANT2> mytypedef;</code></p> + +<p>Use:</p> + +<p><code>typedef myclass< some_symbol> mytypedef;</code></p> + +<p>Where <code>some_symbol</code> is the symbolic name of a an +integral constant expression whose value is <code>(INTEGRAL_CONSTANT1 +== INTEGRAL_CONSTANT2).</code></p> + +<p>Rationale: the older EDG based compilers (some of which are +used in the most recent version of that platform's compiler), +don't recognise expressions containing operators as non-type +template parameters, even though such expressions can be used as +integral constant expressions elsewhere.</p> + +<p><b><i>Always use a fully qualified name to refer to an +integral constant expression.</i></b></p> + +<p>For example:</p> + +<pre><code>typedef</code> myclass< ::boost::is_integral<some_type>::value> mytypedef;</pre> + +<p>Rationale: at least one compiler (Borland's), doesn't +recognise the name of a constant as an integral constant +expression unless the name is fully qualified (which is to say it +starts with ::).</p> + +<p><b><i>Always leave a space after a '<' and before '::'</i></b></p> + +<p>For example:</p> + +<pre><code>typedef</code> myclass< ::boost::is_integral<some_type>::value> mytypedef; + ^ + ensure there is space here!</pre> + +<p>Rationale: <: is a legal digraph in it's own right, so <:: +is interpreted as the same as [:.</p> + +<p><b><i>Don't use local names as integral constant expressions</i></b></p> + +<p>Example:</p> + +<pre>template <class T> +struct foobar +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); + typedef myclass<temp> mytypedef; // error +};</pre> + +<p>Rationale: At least one compiler (Borland's) doesn't accept +this.</p> + +<p>Although it is possible to fix this by using:</p> + +<pre>template <class T> +struct foobar +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); + typedef foobar self_type; + typedef myclass<(self_type::temp)> mytypedef; // OK +};</pre> + +<p>This breaks at least one other compiler (VC6), it is better to +move the integral constant expression computation out into a +separate traits class:</p> + +<pre>template <class T> +struct foobar_helper +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); +}; + +template <class T> +struct foobar +{ + typedef myclass< ::foobar_helper<T>::value> mytypedef; // OK +};</pre> + +<p><b><i>Don't use dependent default parameters for non-type +template parameters.</i></b></p> + +<p>For example:</p> + +<pre>template <class T, int I = ::boost::is_integral<T>::value> // Error can't deduce value of I in some cases. +struct foobar;</pre> + +<p>Rationale: this kind of usage fails for Borland C++. Note that +this is only an issue where the default value is dependent upon a +previous template parameter, for example the following is fine:</p> + +<pre>template <class T, int I = 3> // OK, default value is not dependent +struct foobar;</pre> + +<p> </p> + +<h3>Unresolved Issues</h3> + +<p>The following issues are either unresolved or have fixes that +are compiler specific, and/or break one or more of the coding +guidelines.</p> + +<p><b><i>Be careful of numeric_limits</i></b></p> + +<p>There are three issues here:</p> + +<ol> + <li>The header <limits> may be absent - it is + recommended that you never include <limits> + directly but use <boost/pending/limits.hpp> instead. + This header includes the "real" <limits> + header if it is available, otherwise it supplies it's own + std::numeric_limits definition. Boost also defines the + macro BOOST_NO_LIMITS if <limits> is absent.</li> + <li>The implementation of std::numeric_limits may be defined + in such a way that its static-const members may not be + usable as integral constant expressions. This contradicts + the standard but seems to be a bug that affects at least + two standard library vendors; boost defines + BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS in <boost/config.hpp> + when this is the case.</li> + <li>There is a strange bug in VC6, where the members of std::numeric_limits + can be "prematurely evaluated" in template + code, for example:</li> +</ol> + +<pre>template <class T> +struct limits_test +{ + BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized); +};</pre> + +<p>This code fails to compile with VC6 even though no instances +of the template are ever created; for some bizarre reason <code>::std::numeric_limits<T>::is_specialized +</code>always evaluates to false, irrespective of what the +template parameter T is. The problem seems to be confined to +expressions which depend on std::numeric_limts: for example if +you replace <code>::std::numeric_limits<T>::is_specialized</code> +with <code>::boost::is_arithmetic<T>::value</code>, then +everything is fine. The following workaround also works but +conflicts with the coding guidelines:</p> + +<pre>template <class T> +struct limits_test +{ + BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized); + BOOST_STATIC_ASSERT(check); +};</pre> + +<p>So it is probably best to resort to something like this:</p> + +<pre>template <class T> +struct limits_test +{ +#ifdef BOOST_MSVC + BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized); + BOOST_STATIC_ASSERT(check); +#else + BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized); +#endif +};</pre> + +<p><b><i>Be careful how you use the sizeof operator</i></b></p> + +<p>As far as I can tell, all compilers treat sizeof expressions +correctly when the argument is the name of a type (or a template-id), +however problems can occur if:</p> + +<ol> + <li>The argument is the name of a member-variable, or a local + variable (code may not compile with VC6).</li> + <li>The argument is an expression which involves the creation + of a temporary (code will not compile with Borland C++).</li> + <li>The argument is an expression involving an overloaded + function call (code compiles but the result is a garbage + value with Metroworks C++).</li> +</ol> + +<p><b><i>Don't use boost::is_convertible unless you have to</i></b></p> + +<p>Since is_convertible is implemented in terms of the sizeof +operator, it consistently gives the wrong value when used with +the Metroworks compiler, and may not compile with the Borland's +compiler (depending upon the template arguments used).</p> + +<hr> + +<p>Copyright Dr John Maddock 2001, all rights reserved.</p> + +<p> </p> + +<p> </p> +</body> +</html> diff --git a/more/lib_guide.htm b/more/lib_guide.htm new file mode 100644 index 0000000000..416ffca641 --- /dev/null +++ b/more/lib_guide.htm @@ -0,0 +1,456 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost Library Requirements and Guidelines</title> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="Microsoft Border" content="none, default"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1 align="left">Boost Library Requirements and Guidelines</h1> +<p align="left"><a href="#Introduction">Introduction</a><br> +<a href="#Requirements">Requirements</a><br> + <a href="#License">License requirements</a><br> + <a href="#Portability">Portability requirements</a><br> + <a href="#Ownership">Ownership</a><br> +<a href="#Guidelines">Guidelines</a><br> + <a href="#Design_and_Programming">Design and programming</a><br> + <a href="#Directory_structure">Directory structure and +filenames</a><br> + <a href="#Naming_consistency">Naming consistency</a><br> + <a href="#Documentation">Documentation</a><br> +<a href="#Rationale">Rationale</a><br> + <a href="#Exception-specification">Exception-specification +rationale</a><br> + <a href="#Naming">Naming conventions rationale</a><br> + <a href="#code_fonts">Source code fonts rationale</a><br> + <a href="#Tabs">Tabs rationale</a><br> + <a href="#JavaScript">ECMAScript/JavaScript rationale</a><br> + <a href="#Rationale_rationale">Rationale rationale</a><br> + <a href="#Acknowledgements">Acknowledgements rationale</a></p> +<h2 align="left"><a name="Introduction">Introduction</a></h2> +<p align="left">This page describes requirements and guidelines for the content +of a library submitted to Boost.</p> +<p align="left">See the <a href="submission_process.htm">Boost Library +Submission Process</a> page for a description of the process involved.</p> +<h2 align="left"><a name="Requirements">Requirements</a></h2> +<p>To avoid the frustration and wasted time of a proposed library being +rejected, it must meets these requirements:</p> +<ul> + <li>The license must meet the <a href="#License">license requirements</a> + below. Restricted licenses like the GPL and LGPL are not acceptable. + </li> + <li>The + copyright <a href="#Ownership">ownership</a> must be clear. + </li> + <li>The library must be generally useful and not restricted to a narrow + problem domain. + </li> + <li>The library must meet the <a href="#Portability">portability requirements</a> + below. + </li> + <li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a> + below. + <ul> + <li><a href="#Design_and_Programming">Design and Programming</a></li> + <li><a href="#Directory_structure">Directory Structure</a></li> + <li><a href="#Documentation">Documentation</a></li> + </ul> + </li> + <li>The author must be willing to participate in discussions on the mailing + list, and to refine the library accordingly.</li> +</ul> +<p>There's no requirement that an author read the mailing list for a time before +making a submission. It has been noted, however, that submissions which begin +"I just started to read this mailing list ..." seem to fail, often +embarrassingly.</p> +<h3 align="left"><a name="License">License</a> requirements</h3> +<ul> + <li>Must be simple to read and understand. + </li> + <li>Must grant permission without fee to copy, use and modify the software for any use + (commercial and non-commercial). + </li> + <li>Must require that the license appear on all copies of the software source + code. + </li> + <li>Must not require that the license appear with executables or other binary + uses of the library. + </li> + <li>Must not require that the source code be + available for execution or other binary uses of the library. + </li> + <li>May restrict the use of the name and description of the library to the + standard version found on the Boost web site.</li> +</ul> +<h3 align="left"><a name="Portability">Portability</a> requirements</h3> +<ul> + <li> + <p align="left">A library's interface must portable and not restricted to a + particular compiler or operating system. + </li> + <li> + <p align="left">A library's implementation must if possible be portable and + not restricted to a particular compiler or operating system. If a + portable implementation is not possible, non-portable constructions are + acceptable if reasonably easy to port to other environments, and + implementations are provided for at least two popular operating systems + (such as UNIX and Windows). + </li> + <li> + <p align="left">There is no requirement that a library run on C++ compilers + which do not conform to the ISO standard. + </li> + <li> + <p align="left">There is no requirement that a library run on any particular + C++ compiler. Boost contributors often try to ensure their libraries + work with popular compilers. The boost/config.hpp <a href="../libs/config/config.htm">configuration + header</a> is the preferred mechanism for working around compiler + deficiencies.</li> +</ul> +<p align="left">Since there is no absolute way to prove portability, many boost +submissions demonstrate practical portability by compiling and executing +correctly with two different C++ compilers, often under different operating +systems. Otherwise reviewers may disbelieve that porting is in fact +practical.</p> +<h3 align="left"><a name="Ownership">Ownership</a></h3> +<p align="left">Are you sure you own the library you are thinking of +submitting? "How to Copyright Software" by MJ Salone, Nolo +Press, 1990 says:</p> +<blockquote> + <p align="left">Doing work on your own time that is very similar to + programming you do for your employer on company time can raise nasty legal + problems. In this situation, it's best to get a written release from + your employer in advance.</p> +</blockquote> +<p align="left">Place a copyright notice in all the important files you submit. +Boost won't accept libraries without clear copyright information.</p> +<h2 align="left"><a name="Guidelines">Guidelines</a></h2> +<p align="left">Please use these guidelines as a checklist for preparing the +content a library submission. Not every guideline applies to every +library, but a reasonable effort to comply is expected.</p> +<h3><a name="Design_and_Programming">Design and Programming</a></h3> +<ul> + <li>Aim first for clarity and correctness; optimization should be only a + secondary concern in most Boost libraries.</li> +</ul> +<ul> + <li>Aim for ISO Standard C++. Than means making effective use of the standard + features of the language, and avoiding non-standard compiler extensions. It + also means using the C++ Standard Library where applicable.</li> +</ul> +<ul> + <li>Headers should be good neighbors. See the <a href="header.htm">header + policy</a>. See <a href="#Naming_consistency">Naming consistency</a>.</li> +</ul> +<ul> + <li>Follow quality programming practices. See, for example, "Effective + C++" 2nd Edition, and "More Effective C++", both by Scott + Meyers, published by Addison Wesley.</li> +</ul> +<ul> + <li>Use the C++ Standard Library or other Boost libraries, but only when the + benefits outweigh the costs. Do not use libraries other than the C++ + Standard Library or Boost. See <a href="library_reuse.htm">Library reuse</a>.</li> +</ul> +<ul> + <li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to + supply performance, platform, or other implementation variations.</li> +</ul> +<ul> + <li>Use the naming conventions of the C++ Standard Library (See + <a href="#Naming">Naming conventions rationale</a>): <br> + <ul> + <li>Names (except as noted below) should be all lowercase, with words + separated by underscores.</li> + <li>Acronyms should be treated as ordinary names (e.g. <code>xml_parser</code> instead of <code>XML_parser</code>).</li> + <li>Template parameter names begin with an uppercase letter.</li> + <li>Macro (gasp!) names all uppercase and begin with BOOST_.</li> +</ul> + </li> +</ul> +<ul> + <li>Choose meaningful names - explicit is better than implicit, and readability counts. + There is a strong preference for clear and descriptive names, even if + lengthy.</li> +</ul> +<ul> + <li>Use exceptions to report errors where appropriate, and write code that is + safe in the face of exceptions.</li> +</ul> +<ul> + <li>Avoid exception-specifications. See <a href="#Exception-specification">exception-specification + rationale</a>.</li> +</ul> +<ul> + <li>Provide sample programs or confidence tests so potential users can see how + to use your library.</li> +</ul> +<ul> + <li>Provide a regression test program or programs which follow the <a href="test_policy.htm">Test + Policies and Protocols</a>.</li> +</ul> +<ul> + <li>Although some boost members use proportional fonts, tabs, and unrestricted + line lengths in their own code, boost's widely distributed source code + should follow more conservative guidelines: + <ul> + <li>Use fixed-width fonts. See <a href="#code_fonts">fonts rationale</a>.</li> + <li>Use spaces rather than tabs. See <a href="#Tabs">tabs rationale</a>.</li> + <li>Limit line lengths to 80 characters.</li> + </ul> + </li> +</ul> +<ul> + <li>Begin all source files with: + <ul> + <li>A comment line describing the contents of the file.</li> + <li>Comments describing copyright and licensing.</li> + <li>A comment line referencing your library on the Boost web site:<br> + <br> + <code>// See http://www.boost.org/libs/foo for documentation.</code><br> + <br> + where <code>foo</code> is the directory name (see below) for your library. + As well as aiding users who come across a Boost file detached from its + documentation, some of Boost's automatic tools depend on this comment to + identify which library header files belong to.</li> + </ul> + </li> +</ul> +<h3><a name="Directory_structure">Directory Structure</a> and Filenames</h3> +<ul> + <li>File and directory names must contain only lowercase ASCII letters , + numbers, underscores, and a period. Leading character must be + alphabetic. Maximum length 31. Only a single period is permitted. + These requirements ensure file and directory names are relatively portable.</li> + <li>All libraries have at their highest level a primary directory named for + the particular library. See <a href="#Naming_consistency">Naming consistency</a>. The primary directory may have sub-directories.</li> + <li>For very simple libraries implemented entirely within the library header, + all files go in the primary directory (except headers, which go in the boost + header directory).</li> +</ul> +<blockquote> + <p><b>Boost standard sub-directory names</b></p> + <table border="1" cellpadding="5"> + <tr> + <td><b>Sub-directory</b></td> + <td><b>Contents</b></td> + <td><b>Required</b></td> + </tr> + <tr> + <td><code>build</code></td> + <td>Library build files such as a Jamfile.</td> + <td>If any build files.</td> + </tr> + <tr> + <td>doc</td> + <td>Documentation (HTML) files.</td> + <td>If several doc files.</td> + </tr> + <tr> + <td><code>example</code></td> + <td>Sample program files.</td> + <td>If several sample files.</td> + </tr> + <tr> + <td><code>src</code></td> + <td>Source files which must be compiled to build the library. </td> + <td>If any source files.</td> + </tr> + <tr> + <td><code>test</code></td> + <td>Regression or other test programs or scripts.</td> + <td>If several test files.</td> + </tr> + </table> +</blockquote> +<h4><a name="Redirection">Redirection</a></h4> +<p>The primary directory should always contain a file named index.html (or +index.htm). Authors have requested this so that they can publish URL's in the +form <i>http://www.boost.org/libs/lib-name</i> with the assurance a +documentation reorganization won't invalidate the URL. Boost's internal tools +are also simplified by knowing that a library's documentation is always +reachable via the simplified URL.</p> +<p>If the documentation is in a doc sub-directory, the primary directory index.html file +should just do an automatic redirection to the doc subdirectory:</p> +<blockquote> + <pre><html> +<head> +<meta http-equiv="refresh" content="0; URL=doc/index.html"> +</head> +<body> +Automatic redirection failed, please go to +<a href="doc/index.html">doc/index.html</a> +</body> +</html></pre> +</blockquote> +<h3><a name="Naming_consistency">Naming consistency</a></h3> +<p>As library developers and users have gained experience with Boost, the +following consistent naming approach has come to be viewed as very helpful, +particularly for larger libraries which need their own header subdirectories and +namespaces.</p> +<p>Here is how it works. The library is given a name which describes the +contents of the library. Cryptic abbreviations are not acceptable. +Following the practice of the C++ Standard Library, names are usually singular +rather than plural. For example, a library dealing with file systems might +chose the name "filesystem", but not "filesystems", "fs" or "nicecode".</p> +<ul> + <li>The library's primary directory (in parent <i>boost-root/libs</i>) is + given that same name. For example, <i>boost-root/libs/filesystem</i>.<br> + </li> + <li>The library's primary header directory (in parent <i>boost-root/boost</i>) + is given that same name. For example, <i>boost-root/boost/filesystem</i>.<br> + </li> + <li>The library's primary namespace (in parent <i>::boost</i>) is given that + same name. For example, <i>::boost::filesystem</i>.</li> +</ul> +<h3><a name="Documentation">Documentation</a></h3> +<p>Even the simplest library needs some documentation; the amount should be +proportional to the need. The documentation should assume the readers have +a basic knowledge of C++, but are not necessarily experts.</p> +<p>The format for documentation should be HTML, and should not require an +advanced browser or server-side extensions. Style sheets are acceptable. ECMAScript/JavaScript +is not acceptable. The documentation entry point should +always be a file named index.html or index.htm; see <a href="#Redirection"> +Redirection</a>.</p> +<p>There is no single right way to do documentation. HTML documentation is often +organized quite differently from traditional printed documents. Task-oriented +styles differ from reference oriented styles. In the end, it comes down to the +question: Is the documentation sufficient for the mythical "average" +C++ programmer to use the library successfully?</p> +<p>Appropriate topics for documentation often include: +<ul> + <li>General introduction to the library.</li> + <li>Description of each class.</li> + <li>Relationship between classes.</li> + <li>For each function, as applicable, description, requirements (preconditions), + effects, post-conditions, returns, and throws.</li> + <li>Discussion of error detection and recovery strategy.</li> + <li>How to use including description of typical uses.</li> + <li>How to compile and link.</li> + <li>How to test.</li> + <li>Version or revision history.</li> + <li>Rationale for design decisions. See <a href="#Rationale">Rationale + rationale</a>.</li> + <li>Acknowledgements. See <a href="#Acknowledgements">Acknowledgments + rationale.</a></li> +</ul> +<p>If you need more help with how to write documentation you can check out the + article on <a href="writingdoc/index.html">Writing Documentation for Boost</a>.</p> +<h2><a name="Rationale">Rationale</a></h2> +<p>Rationale for some of the requirements and guidelines follows.</p> +<hr> +<h3><a name="Exception-specification">Exception-specification</a> rationale</h3> +<p>Exception specifications [ISO 15.4] are sometimes coded to indicate what +exceptions may be thrown, or because the programmer hopes they will improved +performance. But consider the following member from a smart pointer:</p> +<pre> T& operator*() const throw() { return *ptr; }</pre> +<p>This function calls no other functions; it only manipulates fundamental data +types like pointers Therefore, no runtime behavior of the +exception-specification can ever be invoked. The function is completely +exposed to the compiler; indeed it is declared inline Therefore, a smart +compiler can easily deduce that the functions are incapable of throwing +exceptions, and make the same optimizations it would have made based on the +empty exception-specification. A "dumb" compiler, however, may make +all kinds of pessimizations.</p> +<p>For example, some compilers turn off inlining if there is an +exception-specification. Some compilers add try/catch blocks. Such +pessimizations can be a performance disaster which makes the code unusable in +practical applications.</p> +<p>Although initially appealing, an exception-specification tends to have +consequences that require <b>very</b> careful thought to understand. The biggest +problem with exception-specifications is that programmers use them as though +they have the effect the programmer would like, instead of the effect they +actually have.</p> +<p>A non-inline function is the one place a "throws nothing" +exception-specification may have some benefit with some compilers.</p> +<hr> +<h3><a name="Naming">Naming</a> conventions rationale</h3> +<p>The C++ standard committee's Library Working Group discussed this issue in +detail, and over a long period of time. The discussion was repeated again in +early boost postings. A short summary:</p> +<ul> + <li>Naming conventions are contentious, and although several are widely used, + no one style predominates. + </li> + <li>Given the intent to propose portions of boost for the next revision of the + C++ standard library, boost decided to follow the standard library's + conventions. + </li> + <li>Once a library settles on a particular convention, a vast majority of + stakeholders want that style to be consistently used. + </li> +</ul> +<hr> +<h3>Source <a name="code_fonts">code fonts</a> rationale</h3> +<p>Dave Abrahams comments: An important purpose (I daresay the primary purpose) +of source code is communication: the documentation of intent. This is a doubly +important goal for boost, I think. Using a fixed-width font allows us to +communicate with more people, in more ways (diagrams are possible) right there +in the source. Code written for fixed-width fonts using spaces will read +reasonably well when viewed with a variable-width font, and as far as I can tell +every editor supporting variable-width fonts also supports fixed width. I don't +think the converse is true.</p> +<hr> +<h3><a name="Tabs">Tabs</a> rationale</h3> +<p>Tabs are banned because of the practical problems caused by tabs in +multi-developer projects like Boost, rather than any dislike in principle. See +<a href="mailing_lists.htm#archive">mailing list archives</a>. Problems include +maintenance of a single source file by programmers using tabs and programmers +using spaces, and the difficulty of enforcing a consistent tab policy other than +just "no tabs". Discussions concluded that Boost files should either all use +tabs, or all use spaces, and thus the decision to stick with spaces.</p> +<hr> +<h3>ECMAScript/<a name="JavaScript">JavaScript</a> rationale</h3> +<p>Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript +documentation. Controversy followed (see <a href="mailing_lists.htm#archive"> +mailing list archives</a>), and the developers were asked to remove the +ECMAScript/JavaScript. Reasons given for banning included:</p> +<ul> + <li>Incompatible with some older browsers and some text based browsers.</li> + <li>Makes printing docs pages difficult.</li> + <li>Often results in really bad user interface design.</li> + <li>"It's just annoying in general."</li> + <li>Would require Boost to test web pages for ECMAScript/JavaScript + compliance.</li> + <li>Makes docs maintenance by other than the original developer more + difficult.</li> +</ul> +<hr> +<h3><a name="Rationale_rationale">Rationale rationale</a></h3> +<p>Rationale is defined as "The fundamental reasons for something; +basis" by the American Heritage Dictionary.</p> +<p>Beman Dawes comments: Failure to supply contemporaneous rationale for +design decisions is a major defect in many software projects. Lack of accurate +rationale causes issues to be revisited endlessly, causes maintenance bugs when a +maintainer changes something without realizing it was done a certain way for +some purpose, and shortens the useful lifetime of software.</p> +<p>Rationale is fairly easy to provide at the time decisions are made, but very +hard to accurately recover even a short time later.</p> +<hr> +<h3><a name="Acknowledgements">Acknowledgements</a> rationale</h3> +<p>As a library matures, it almost always accumulates improvements suggested to +the authors by other boost members. It is a part of the culture of +boost.org to acknowledge such contributions, identifying the person making the +suggestion. Major contributions are usually acknowledged in the +documentation, while minor fixes are often mentioned in comments within the code +itself.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->26 February, 2003<!--webbot bot="Timestamp" endspan i-checksum="40410" --></p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/library_reuse.htm b/more/library_reuse.htm new file mode 100644 index 0000000000..35efd133ca --- /dev/null +++ b/more/library_reuse.htm @@ -0,0 +1,72 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Library Reuse</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<h1>Boost Library reuse: cost versus benefit trade-offs</h1> +<p>A Boost library <b>should not</b> use libraries other than Boost or the C++ +Standard Library.</p> +<p>A Boost library <b>should</b> use other Boost Libraries or the C++ Standard +Library, but only when the benefits outweigh the costs. </p> +<p>The benefits of using components from other libraries may include clearer, +more understandable code, reduced development and maintenance costs, and the +assurance which comes from reusing well-known and trusted building blocks.</p> +<p>The costs may include undesirable coupling between components, and added +compilation and runtime costs. If the interface to the additional +component is complex, using it may make code less readable, and thus actually +increase development and maintenance costs.</p> +<p>Negative effects of coupling become obvious when one library uses a second +library which uses a third, and so on. The worst form of coupling requires the +user understand each of the coupled libraries. Coupling may also reduce the +portability of a library - even in case when all used libraries are +self-sufficient (see example of questionable usage of <iostream> library +below).</p> +<p><b>Example where another boost component should certainly be used:</b> +boost::noncopyable (in <a href="../boost/utility.hpp">boost/utility.hpp</a>) has +considerable benefits; it simplifies code, improves readability, and signals +intent. Costs are low as coupling is limited; noncopyable itself +uses no other classes and its header includes only the lightweight headers +<boost/config.hpp> and <cstddef>. There are no runtime costs +at all. With costs so low and benefits so high, other boost libraries should use +boost::noncopyable when the need arises except in exceptional circumstances.</p> +<p><b>Example where a standard library component might possibly be used:</b> +Providing diagnostic output as a debugging aid can be a nice feature for a +library. Yet using Standard Library <iostream> can involves a lot of +additional cost, particularly if <iostream> is unlikely to be use +elsewhere in the application. In certain GUI or embedded applications, +coupling to <iostream> would be a disqualification. +Consider redesign of the boost library in question so that the user supplies the +diagnostic output mechanism.</p> +<p><b>Example where another boost component should not be used:</b> The +boost dir_it library has considerable coupling and runtime costs, not to mention +portability issues for unsupported operating systems. While completely +appropriate when directory iteration is required, it would not be reasonable for +another boost library to use dir_it just to check that a file is available +before opening. C++ Standard Library file open functionality does this at +lower cost. Don't use dir_it just for the sake of using a boost library.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->06 February 2001<!--webbot bot="Timestamp" endspan i-checksum="40613" --></p> +<p> </p> +<p> </p> + +</body> + +</html> diff --git a/more/links.htm b/more/links.htm new file mode 100644 index 0000000000..f93b356163 --- /dev/null +++ b/more/links.htm @@ -0,0 +1,58 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<title>Links</title> +</head> + +<body bgcolor="#FFFFFF"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + + +<h1>Links</h1> +<p>Here are a few links of special interest to Boost users. For general queries, +try your favorite search engine.</p> +<h2><a name="Commercial Support">Commercial Support</a> for Boost Libraries</h2> +<ul> + <li><a href="http://www.boost-consulting.com">Boost Consulting</a> - Support, + training, and consulting from Boost experts.</li> +</ul> +<h2><a name="cpp">C++</a> Organizations</h2> +<ul> + <li><a href="http://std.dkuug.dk/jtc1/sc22/wg21">C++ Standards Committee</a> - + Issues lists and papers give insight into current status and future + directions.</li> + <li><a href="http://www.accu.org">Association of C & C++ Users</a> - Over 2400 + book reviews, and lots more.</li> +</ul> +<h2>Copies of the C++ Standard</h2> +<ul> + <li> + <a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=INCITS/ISO/IEC+14882-1998"> + ANSI Store</a> - The full C++ Standard (INCITS/ISO/IEC 14882) is available online for $18 US. The document is certainly not a + tutorial, but is interesting to those who care about the + precise specification of both the language and the standard + library.</li> +</ul> +<hr> +<p>Revised +<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->10 September, 2002<!--webbot bot="Timestamp" endspan i-checksum="39330" --></p> +<p> </p> +<p> </p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/mailing_lists.htm b/more/mailing_lists.htm new file mode 100644 index 0000000000..6b6a053795 --- /dev/null +++ b/more/mailing_lists.htm @@ -0,0 +1,216 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<html> + <head> + <meta name="generator" content= + "Microsoft FrontPage 5.0"> + <meta http-equiv="Content-Type" content= + "text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + + <title>Mailing Lists</title> + </head> + + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt= + "c++boost.gif (8819 bytes)" width="277" height="86"></td> + + <td><a href="../index.htm"><font face="Arial" color= + "#FFFFFF"><big>Home</big></font></a></td> + + <td><a href="../libs/libraries.htm"><font face="Arial" color= + "#FFFFFF"><big>Libraries</big></font></a></td> + + <td><a href="../people/people.htm"><font face="Arial" color= + "#FFFFFF"><big>People</big></font></a></td> + + <td><a href="faq.htm"><font face="Arial" color= + "#FFFFFF"><big>FAQ</big></font></a></td> + + <td><a href="index.htm"><font face="Arial" color= + "#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + + <h1>Boost Mailing Lists and other resources</h1> + + <dl> + <dt><a href="#main">Boost developers</a> list</dt> + + <dd> + <dl> + <dt><a href="#archive">Archives</a> for the Boost developers + list</dt> + </dl> + </dd> + + <dt><a href="#users">Boost Users</a> list</dt> + + <dt><a href="#announce">Boost Announce</a> list</dt> + + <dt><a href="#projects">Project-Specific</a> lists</dt> + + <dd> + <dl> + <dt><a href="#jamboost">Boost.Build</a> (jamboost) list</dt> + + <dt><a href="#cplussig">Python C++-Sig</a> (for Boost.Python)</dt> + </dl> + </dd> + + <dt><a href="#sandbox">Boost Sandbox CVS</a></dt> + </dl> + + <p>The mailing lists are the heart of the Boost community. You may + read the lists via full-content email, email digests, or via newsgroup + reader.</p> + + <p>Hosting for the mailing lists is donated by the <a href= + "http://www.osl.iu.edu/">Open Systems Lab at Indiana University</a>.</p> + + <p>Access to Boost mailing lists via newsgroup (NNTP) is contributed by + <a href="http://www.gmane.org/">GMANE</a>.</p> + + <h2><a name="main">Boost</a> developers mailing list (also available via + newsgroup)</h2> + + <p>This is the main Boost mailing list. It is high volume (over + 1000 messages per month), very technical, and oriented toward Boost + library developers. It is also read by many other members interested in + watching the Boost library development process. Virtually all Boost + decisions, major or minor, technical or otherwise, are reached via public + discussion on this mailing list. It is where the formal reviews of + proposed libraries take place. Subscribe or unsubscribe at <a href= + "http://lists.boost.org/mailman/listinfo.cgi/boost">http://lists.boost.org/mailman/listinfo.cgi/boost</a></p> + + <p>When we talk about the "members of Boost", we are talking about those + signed up for this main mailing list.</p> + + <p>For those who prefer to participate via an NNTP (<a name= + "newsgroup">newsgroup</a>) interface, a gateway to the Boost mailing list + is available at <a href= + "news://news.gmane.org/gmane.comp.lib.boost.devel">news://news.gmane.org/gmane.comp.lib.boost.devel</a>. + Postings to the newsgroup will only be accepted for the mailing list if + from a <a href= + "http://lists.boost.org/mailman/listinfo.cgi/boost">subscribed</a> email + address, though you can configure your subscription settings to disable + mail delivery if you prefer to read messages via the newsgroup.</p> + + <p>For this list's members only, preliminary libraries under discussion + are available from the YahooGroups <a href= + "http://www.yahoogroups.com/files/boost/">Files section</a> (formerly + called the "vault").</p> + + <h3><a name="archive">Archives</a> for Boost developers list</h3> + + <p>A <a href="http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/boost/">searchable mailing list + archive</a> has been generously contributed to the <a href= + "http://aspn.activestate.com">ActiveState Programmer Network</a> by <a + href="http://aspn.activestate.com">ActiveState Corporation</a>. <a href= + "http://aspn.activestate.com"><img align="top" src= + "http://www.activestate.com/img/ASPN_logo_smallest.gif" width="65" + height="20"></a><a href="http://www.activestate.com"><img align="top" + src="http://aspn.activestate.com/ASPN/img/ASLogo_57x25.gif" width="57" + height="25"></a></p> + Other archives of Boost messages include the <a href= + "http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.devel">Boost + GMane NNTP Archive</a>, <a href= + "http://www.mail-archive.com/boost%40lists.boost.org/">The Mail + Archive</a>, and of course there is a Google search link for our <a href= + "http://lists.boost.org/MailArchives/boost/">MailMan Archive</a> on <a + href="../index.htm">our home page</a>. + + <h2>Boost <a name="users">Users</a> mailing list (also available via + newsgroup)</h2> + + <p>This list is oriented toward casual users of the Boost + libraries. Feel free to post both "newbie" and more + challenging questions, but please check first to see if there's an + appropriate <a href="#projects">Project-Specific</a> list; you'll + often get better answers in a forum dedicated to your problem + area. This list is relatively low volume (less than 100 per + month). Subscribe or unsubscribe at the <a href= + "http://groups.yahoo.com/group/Boost-Users">Boost Users list home + page</a>.</p> + + <p>For those who prefer to participate via an NNTP (<a name= + "users_newsgroup">newsgroup</a>) interface, a gateway to the Boost Users + mailing list is available at <a href= + "news://news.gmane.org/gmane.comp.lib.boost.user">news://news.gmane.org/gmane.comp.lib.boost.user</a>. + You can also browse <a href= + "http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.user">Gmane's + searchable archive</a>.</p> + + <h2>Boost <a name="announce">Announce</a> mailing list</h2> + + <p>This is an announce-only list for notification of upcoming software + releases and formal reviews of proposed libraries. One to three messages + per month. Subscribe or unsubscribe at the <a href= + "http://lists.boost.org/mailman/listinfo.cgi/boost-announce">Boost + Announce list home page</a>.</p> + + <h2><a name="projects">Project-Specific lists</a></h2> + Several mailing lists have been established for specific Boost projects: +<dl> + <dd> + <h3><a name="jamboost">Boost.Build</a> (jamboost) list</h3> + The Yahoogroups mailing list for the <a href="../tools/build">Boost Build + System</a> is located <a href= + "http://groups.yahoo.com/group/jamboost/">here</a>. GMane provides <a + href="news://news.gmane.org/gmane.comp.lib.boost.build">NNTP access</a> + and <a href= + "http://news.gmane.org/thread.php?group=gmane.comp.lib.boost.build">Searchable + Archives</a> as well. + <h3><a name="cplussig">Python C++-Sig</a> (for Boost.Python)</h3> + The <a href="http://www.python.org/sigs/c++-sig/">Python C++-sig</a> is not + strictly Boost-specific, but nearly all the traffic concerns <a href="../libs/python">Boost.Python</a>. + GMane provides <a href= + "news://news.gmane.org/gmane.comp.python.c%2b%2b">NNTP access</a> and + <a href= + "http://news.gmane.org/thread.php?group=gmane.comp.python.c%2b%2b">Searchable + Archives</a> as well. There are also searchable archives at <a href= + "http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/c++-sig">ASPN</a>. + <h3><a name="spirit">Boost.Spirit</a> lists</h3> + Spirit has two additional mailing lists. <a href="https://lists.sourceforge.net/lists/listinfo/spirit-general">Spirit-general</a> + for Spirit users and <a href="https://lists.sourceforge.net/lists/listinfo/spirit-devel">Spirit-devel</a> + for Spirit developers (open to anyone who wishes to hang out with Spirit coders). + Both have <a href="http://www.gmane.org">GMane</a> NNTP access (<a href="news://news.gmane.org/gmane.comp.parsers.spirit.general">Spirit-general</a> + and <a href="news://news.gmane.org/gmane.comp.parsers.spirit.devel">Spirit-devel</a>) + with searchable archives (<a href="http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.devel">Spirit-general</a> + and <a href="http://news.gmane.org/thread.php?group=gmane.comp.parsers.spirit.devel">Spirit-devel</a>). <h3><a name="boostdocs">Boost.Documentation</a> list</h3> + The SourceForge mailing list for the <a href="../tools/boostbook">Boost Documentation + System</a> is located <a href= + "https://lists.sourceforge.net/lists/listinfo/boost-docs">here</a>. + <h3><a name="boostinstall">Boost.Install</a> list</h3> + The mailing list for installation assistance + is located <a href= + "http://lists.boost.org/mailman/listinfo.cgi/boost-install">here</a>. + <h3><a name="ublas-dev">uBLAS development</a> (ublas-dev) list</h3> + The YahooGroups mailing list for <a href="../libs/numeric/ublas/index.html">Boost + uBLAS</a> is located <a href="http://groups.yahoo.com/group/ublas-dev/">here</a>. +</dd> +</dl> +<h2>Boost <a name="sandbox">Sandbox</a> CVS</h2> + + <p>In addition to the main <a href="download.html#CVS">Boost CVS + repository</a>, a separate Sandbox CVS is available for Boost developers + wishing to collaborate on projects prior to formal acceptance of a new + library. It can be accessed <a href= + "http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost-sandbox/boost-sandbox/"> + via the web</a>, or via CVS client at:</p> + + <blockquote> + <p> + <code>:pserver:anonymous@cvs.boost-sandbox.sourceforge.net:/cvsroot/boost-sandbox</code></p> + </blockquote> + <hr> + + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="34472" --> +</p> + </body> +</html> diff --git a/more/microsoft_vcpp.html b/more/microsoft_vcpp.html new file mode 100644 index 0000000000..0b589bea23 --- /dev/null +++ b/more/microsoft_vcpp.html @@ -0,0 +1,318 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Portability Hints: Microsoft Visual C++ 6.0 SP4</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<p> + +<h1>Portability Hints: Microsoft Visual C++ 6.0 SP4</h1> + +Similar to the +<a href="borland_cpp.html">portability hints for Borland C++</a>, +this page provides hints on some language features of the Microsoft Visual C++ +version 6.0 service pack 4 compiler. A list of +acknowledged deficiencies can be found at the +<a href="http://support.microsoft.com/support/kb/articles/q243/4/51.asp">Microsoft support site</a>. +<p> + +Each entry in the following list describes a particular issue, +complete with sample source code to demonstrate the effect. +Most sample code herein has been verified to compile with gcc 2.95.2 +and Comeau C++ 4.2.44. + + +<h2>Preprocessor symbol</h2> + +The preprocessor symbol <code>_MSC_VER</code> is defined for all +Microsoft C++ compilers. Its value is the internal version number of the +compiler interpreted as a decimal number. Since a few other compilers +also define this symbol, boost provides the symbol +<code>BOOST_MSVC</code>, which is defined in +<a href="../boost/config.hpp">boost/config.hpp</a> +to the value of _MSC_VER if and only if the compiler is really +Microsoft Visual C++. + +The following table lists some known values. +<p> + +<table border="1"> +<tr> +<th>Compiler</th> +<th><code>BOOST_MSVC</code> value</th> +</tr> + +<tr> +<td>Microsoft Visual C++ 6.0 (up to SP4)</td> +<td>1200</td> +</tr> + +</table> + + +<h2>Core Language</h2> + +<h3>[chained using] Chaining <code>using</code>-declarations</h3> + +Chaining <code>using</code>-declarations does not work. +<pre> +void f(); + +namespace N { + using ::f; +} + +void g() +{ + using N::f; // C2873: 'f': the symbol cannot be used in a using-declaration +} +</pre> + + +<h3>[explicit-instantiation] Explicit function template +instantiation</h3> + +Trying to explicitly instantiate a function template leads to the +wrong function being called silently. + +<pre> +#include <stdio.h> + +template<class T> +void f() +{ + printf("%d\n", sizeof(T)); +} + +int main() +{ + f<double>(); // output: "1" + f<char>(); // output: "1" + return 0; +} +</pre> + + +<h3>[for-scoping] Scopes of definitions in for-loops</h3> + +The scope of variable definitions in <code>for</code> loops should be +local to the loop's body, but it is instead local to the enclosing +block. + + +<pre> +int main() +{ + for(int i = 0; i < 5; ++i) + ; + for(int i = 0; i < 5; ++i) // C2374: 'i': Redefinition; multiple initialization + ; + return 0; +} +</pre> + +<strong>Workaround:</strong> Enclose the offending <code>for</code> +loops in another pair of curly braces. +<p> +Another possible workaround (brought to my attention by Vesa Karvonen) +is this: +<pre> +#ifndef for +#define for if (0) {} else for +#endif +</pre> + +Note that platform-specific inline functions in included headers might +depend on the old-style <code>for</code> scoping. + + +<h3>[inclass-member-init] In-class member initialization</h3> + +In-class member initialization, required to implement a +Standard-conforming <code>std::numeric_limits</code> template, does +not work. + +<pre> +struct A +{ + static const int i = 5; // "invalid syntax for pure virtual method" +}; +</pre> + +<strong>Workaround:</strong> Either use an enum (which has incorrect +type, but can be used in compile-time constant expressions), or define +the value out-of-line (which allows for the correct type, but prohibits +using the constant in compile-time constant expressions). See +<a href="int_const_guidelines.htm">Coding Guidelines for Integral Constant Expressions</a> +for guidelines how to define member constants portably in boost +libraries. + + +<h3>[koenig-lookup] Argument-dependent lookup</h3> + +Argument-dependent lookup, also called Koenig lookup, works for +overloaded operators, but not for ordinary functions. No +additional namespaces induced from the argument types seem to be +considered. + +<pre> +namespace N { + struct A {}; + void f(A); +} + +void g() +{ + N::A a; + f(a); // 'f': undeclared identifier +} +</pre> + + +<h3>[template-friend] Templates as friends</h3> + +A Template cannot be declared a friend of a class. + +<pre> +template<class T> +struct A {}; + +struct B +{ + template<class T> + friend struct A; // "syntax error" +}; +</pre> + + +<h3>[member-template-outofline] Out-of-line definitions of member +templates</h3> + +Defining member templates outside their enclosing class does not work. + +<pre> +template<class T> +struct A +{ + template<class U> + void f(); +}; + +template<class T> +template<class U> // "syntax error" +void A<T>::f() // "T: undeclared identifier" +{ +} +</pre> + +<strong>Workaround:</strong> Define member templates in-line within +their enclosing class. + + +<h3>[partial-spec] Partial specialization</h3> + +Partial specialization of class templates does not work. + +<pre> +template<class T> +struct A {}; + +template<class T> +struct B {}; + +template<class T> +struct A<B<T> > {}; // template class was already defined as a non-template +</pre> + +<strong>Workaround:</strong> In some situations where interface +does not matter, class member templates can simulate partial +specialization. + + +<h3>[template-value] Dependent template value parameters</h3> + +Template value parameters whose type depends on a previous template +parameter provoke an internal compiler error if the correct syntax +(with "typename") is used. + +<pre> +template<class T, typename T::result_type> // C1001: INTERNAL COMPILER ERROR: msc1.cpp, line 1794 +struct B {}; + // (omit "typename" and it compiles) + +</pre> + +<strong>Workaround:</strong> Leave off the "typename" keyword. That makes +the program non-conforming, though. + + +<h3>[wchar_t] <code>wchar_t</code> is not built-in</h3> + +The type <code>wchar_t</code> is not a built-in type. + +<pre> +wchar_t x; // "missing storage class or type identifier" +</pre> + +<strong>Workaround:</strong> When using Microsoft Visual C++, the +header +<a href="../boost/config.hpp">boost/config.hpp</a> +includes <code><cstddef></code>, which defines +<code>wchar_t</code> as a typedef for <code>unsigned +short</code>. Note that this means that the compiler does not regard +<code>wchar_t</code> and <code>unsigned short</code> as distinct +types, as is required by the standard, and so ambiguities may emanate +when overloading on <code>wchar_t</code>. The macro +<code>BOOST_NO_INTRINSIC_WCHAR_T</code> is defined in this situation. + + +<h3>[delete-const-pointer] Deleting <code>const X *</code> does not work</h3> + +Trying to delete a pointer to a cv-qualified type gives an error: +<pre> +void f() +{ + const int *p = new int(5); + delete p; // C2664: cannot convert from "const int *" to "void *" +} +</pre> + +<strong>Workaround:</strong> Define the function +<pre> +inline void operator delete(const void *p) throw() +{ operator delete(const_cast<void*>(p)); } +</pre> +and similar functions for the other cv-qualifier combinations, for +operator delete[], and for the <code>std::nothrow</code> variants. + + + +<h2>Standard Library</h2> + +<h3>[clib-namespace] C library names in global namespace instead of std</h3> +<p>Library names from the <c...> headers are in the global namespace +instead of namespace std.<p><b>Workaround:</b> The header <a href="../libs/config/config.htm">boost/config.hpp</a> +will define BOOST_NO_STDC_NAMESPACE. It can be used as follows: +<pre># ifdef BOOST_NO_STDC_NAMESPACE + namespace std { using ::abs; using ::fabs; } +# endif</pre> +<p>Because std::size_t and std::ptrdiff_t are so commonly used, the workaround +for these is already provided in boost/config.hpp.<p> +<hr> + +2001-05-04 <a href="../people/jens_maurer.htm">Jens Maurer</a> +</body> +</html> diff --git a/more/moderators.html b/more/moderators.html new file mode 100644 index 0000000000..0ab9862e56 --- /dev/null +++ b/more/moderators.html @@ -0,0 +1,60 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Moderators</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Moderators</h1> +<p>The Boost moderators are Dave Abrahams, +Darin Adler, Carl Daniel, Beman Dawes, Doug Gregor, and John Maddock.</p> +<h2>Moderator Functions</h2> +<ul> + <li>Monitor the mailing list to ensure dialog remains within the acceptable + boundaries set by the <a href="discussion_policy.htm">discussion policy</a>. + When discussion strays, use private email to gently remind, strongly rebuke, + or outright ban, as the situation demands.</li> +</ul> +<ul> + <li>Approve the initial postings of new (and thus still moderated) members, + and move members to the "Group Policy" posting status.</li> +</ul> +<ul> + <li>Administer the internal operations of the Boost web site, the main Boost + mailing list, the CVS repository, and other Boost administrative machinery.</li> +</ul> +<ul> + <li>Act as an executive committee overseeing important administrative and + policy decisions. Boost is a zero-budget organization with no income + and no expenses, so that eliminates the need for most management. Technical + decisions are worked out on the mailing list. The moderators handle the few + remaining decisions that need a definite answer.</li> +</ul> +<ul> + <li>Beyond the purely administrative duties, work to keep the Boost community + vibrant and alive. That may be as simple as saying "thank you" to + an individual member, or as complex as starting some major new + initiative. Do whatever it takes!</li> +</ul> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->18 February, 2003<!--webbot bot="Timestamp" endspan i-checksum="40413" --> +</p> +<p> </p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/proposal.pdf b/more/proposal.pdf Binary files differnew file mode 100644 index 0000000000..d85860bac1 --- /dev/null +++ b/more/proposal.pdf diff --git a/more/regression.html b/more/regression.html new file mode 100644 index 0000000000..789885c002 --- /dev/null +++ b/more/regression.html @@ -0,0 +1,239 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<title>Boost Regression Test User Documentation</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial,Helvetica">Home</font></a></td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" + size="4" face="Arial,Helvetica">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial,Helvetica">People</font></a></td> + <td><a href="faq.htm"><font color="#FFFFFF" size="4" + face="Arial,Helvetica">FAQ</font></a></td> + <td><a href="index.htm"><font color="#FFFFFF" size="4" + face="Arial,Helvetica">More</font></a></td> + </tr> +</table> + +<h1>Boost Regression Test User Documentation</h1> + +<p><a href="#Introduction">Introduction</a><br> +<a href="#Preparation">Preparation</a><br> +<a href="#Execution">Execution</a><br> +<a href="#Adding_new_test">Adding a new test</a><br> +<a href="#Requirements">Requirements</a><br> +<a href="#History">History</a></p> + +<h2><a name="Introduction">Introduction</a></h2> + +<p>Boost's internal regression test suite produces the <a +href="../status/compiler_status.html">compiler status tables</a>. +</p> + +<p>Although not ordinarily run by Boost library users, it is +documented here for the benefit of Boost developers, and for +Boost users porting to a new platform.</p> + +<p>Version 3 of the Boost regression testing framework is based +on <a href="../tools/build/index.html">Boost.Build</a>, and uses <i>bjam</i> +to actually run the tests. Because Boost.Build does dependency +analysis, only tests for which some dependency has change are +rerun.</p> + +<p>The reporting of test results as HTML files is accomplished by +separate <a href="../tools/regression/index.htm">regression +reporting programs</a> which process the residue and log files +from the <i>bjam</i> run.</p> + +<h2><a name="Preparation">Preparation</a></h2> + +<p>Install the following programs on your system, in some +location suitable for program executables. Normally that location +must be in a directory which is part of your search path for +executables.</p> + +<ul> + <li><i>bjam</i> - Executables and sources are available; see <a + href="../tools/build/index.html#Jam">Boost.Build docs</a>. + Before worrying about regression tests, you might want to + verify your <i>bjam</i> installation works by <a + href="../tools/build/index.html#Building">building the + boost-root/status/Jamfile libraries</a>.<br> + </li> + <li><i>process_jam_log</i> and <i>compiler_status</i> - <a + href="regression.html">Sources and docs</a> are available + for these, too. </li> +</ul> + +<h2><a name="Execution">Execution</a></h2> + +<p>These examples assume several environment variables have been +set:</p> + +<ul> + <li>BOOST_ROOT is set to the directory where the unzipped + Boost distribution or CVS working copy resides. For + example:<br> + <br> + set BOOST_ROOT=/boost_1_29_0<br> + </li> + <li>TOOLS is set to the <a + href="../tools/build/index.html#Tools">compiler toolsets</a> + you wish to use. For example:<br> + <br> + set TOOLS=borland gcc intel-win32 metrowerks vc7<br> + </li> + <li>Any environment variables required for particular + compilers. You might wish to test first with one + compiler at a time to make sure each toolset is fully + operational.</li> +</ul> + +<p>Just running bjam for a specific library can be run like this on Windows, +using the Filesystem Library as an example:</p> + +<blockquote> + <pre>cd \boost-root\libs\filesystem\test +bjam</pre> +</blockquote> +<p>For POSIX systems, just change the backslashes to forward slashes.</p> + +<p>A full set of tests and status tables can be run thusly +on a Windows system:</p> + +<blockquote> + <pre>cd %BOOST_ROOT%\status +bjam --dump-tests test >bjam.log 2>&1 +start notepad bjam.log +process_jam_log <bjam.log +compiler_status %BOOST_ROOT% cs-win32.html +rem Specify links file, even though it will be overwritten, so report html includes links +rem This works because the generated bookmark names are the same regardless of other settings +compiler_status --ignore-pass --no-warn %BOOST_ROOT% cs-win32-fail.html cs-win32-links.html +compiler_status --ignore-pass %BOOST_ROOT% cs-win32-warn-or-fail.html cs-win32-links.html +compiler_status %BOOST_ROOT% cs-win32-full.html cs-win32-links.html</pre> +</blockquote> + +<p>Modulo syntax adjustments, the same procedure should work on +other operating systems (an example a <a href="../tools/regression/run_tests.sh"> +UNIX shell script</a> for this is provided, see the +script itself for comments and directions). Rename the cs-win-xxx +output files as appropriate.</p> + +<p>If you execute <i>compiler_status</i> without arguments, you +can see the available options and tailor your own favorite report.</p> + +<p>If you want to run just a single test, specify it as the <i>bjam</i> +target rather than "test". For example, to debug +configurations, it might be useful to just run the <i>config_info</i> +test, with a switch to force even up-to-date programs be rebuilt:</p> + +<blockquote> + <pre>bjam -a --dump-tests config_info >bjam.log 2>&1 +process_jam_log <bjam.log +compiler_status %BOOST_ROOT% cs-win32.html +</pre> +</blockquote> + +<h2><a name="Adding_new_test">Adding a new test</a></h2> + +<h3>The best way - the <a name="subinclude"> <i>subinclud</i>e</a> approach</h3> + +<p>The best way to add a test to the <a +href="../status/Jamfile">boost-root/status/Jamfile</a> is usually to use the bjam +<i>subinclude</i> feature, since it allows the same test specification to be run +either as part of the overall Boost regression test or as a standalone test of +only the library involved.</p> + +<p>The test is specified in a Jamfile, which is usually placed in the library's +<i>test</i> subdirectory. See the <a href="../libs/filesystem/test/Jamfile"> +Filesystem Library's test Jamfile</a> for an example, including the boilerplate +wrapped around the actual tests. By <a href="#Execution">executing bjam</a> +(with or without the status reporting programs) in the library's <i>test</i> +subdirectory, the library can be tested without the need to run the full Boost +regression tests.</p> + +<p>Then by adding a <i>subinclude</i> statement to <a +href="../status/Jamfile">boost-root/status/Jamfile</a>, the library's test +Jamfile will become part of the main Boost regression tests. For example, +the Filesystem Library's tests are included by this line in the main +boost-root/status Jamfile:</p> + +<blockquote> + <pre>subinclude libs/filesystem/test ;</pre> +</blockquote> + +<p>Don't forget that Jamfiles are white-space sensitive; delete the +space before the semi-colon in the example above, and you will +get an introduction to Jam error messages.</p> + +<h3>Another way - direct inclusion in Boost regression tests</h3> + +<p>Adding a test is as simple as adding a single line to the <a +href="../status/Jamfile">boost-root/status/Jamfile</a>:</p> + +<blockquote> + <pre>run libs/mylib/test/mytest.cpp ;</pre> +</blockquote> + +<p>For creating more complex tests and test-suites, use the +<a href="#subinclude">subinclude approach</a>. Look at +examples in the <a +href="../status/Jamfile">boost-root/status/Jamfile</a>. +The <i>bind</i> and <i>config</i> test-suites are simple +examples, while the <i>regex</i> and <i>threads</i> test suites +show more of the power of Jam based testing.</p> + +<h2><a name="Requirements">Requirements</a></h2> + +<p>The test suite has been designed to meet to the following +requirements. </p> + +<ul> + <li>Doesn't depend on an external toolchain. This requirement + is met by supplying all tools in the regular <a + href="download.html">Boost distribution</a>, except for a + C++ compiler.</li> + <li>Tools are written in C++; it is the only language that + all Boost developers and users are comfortable with.</li> + <li>Supports tests which expect an error </li> + <li>Configuration is independent of the target platform or + compiler. </li> + <li>HTML output </li> +</ul> + +<p>These requirements rule out any script-based approach such as +dejagnu (requires Tcl and expect) or even shell scripts. </p> + +<h2><a name="History">History</a></h2> + +<p>The version 3 testing.jam and status/Jamfile foundation was +contributed by Dave Abrahams. The post-bjam processing programs +were contributed by Beman Dawes.</p> + +<p>The version 2 regression.cpp test program was contributed by +Jens Maurer, generalizing and improving an earlier version 1 +program by Beman Dawes.</p> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" startspan s-type="EDITED" +s-format="%d %B, %Y" -->20 January, 2003<!--webbot bot="Timestamp" +i-checksum="38566" endspan --></p> + +<p>Original author: <a href="../people/jens_maurer.htm">Jens +Maurer</a><br> +Updates: <a href="../people/beman_dawes.html">Beman Dawes</a></p> +</body> +</html>
\ No newline at end of file diff --git a/more/release_procedures.htm b/more/release_procedures.htm new file mode 100644 index 0000000000..555de8f69d --- /dev/null +++ b/more/release_procedures.htm @@ -0,0 +1,204 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<title>Release Procedures</title> +</head> + +<body bgcolor="#FFFFFF"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + + +<h1>Boost Release Procedures</h1> +<p><a href="#Introduction">Introduction</a><br> +<a href="#Overview">Procedure Overview</a><br> +<a href="#Developers">Procedures for Developers</a><br> +<a href="#Manager">Procedures for the Release Manager</a><br> +<a href="#FAQ">FAQ</a><br> +<a href="#Acknowledgements">Acknowledgements</a></p> +<h2><a name="Introduction">Introduction</a></h2> +<p>Each release of Boost software is overseen by a release manager, who +coordinates release activities via the Boost mailing list, as well as performing +the detailed procedures for the release.</p> +<p>Boost developers assist the release manager by reviewing regression test +logs, and committing fixes to CVS.</p> +<h2>Release Procedure <a name="Overview">Overview</a></h2> +<ul> + <li>Discussion on the main Boost mailing list to determine the target date for + release candidate branch and tag of the CVS main trunk.<br> + </li> + <li>Release manager performs release candidate branch, and also tags the + branch point in main trunk.<br> + </li> + <li>Regression tests run on release candidate branch.<br> + </li> + <li>Developers fix problems, test, and commit fixes. See below for details.<br> + </li> + <li>Repeat previous two steps until release manager is satisfied.<br> + </li> + <li>Release manager rolls out the actual release.</li> +</ul> +<h2>Release Procedures for <a name="Developers">Developers</a></h2> +<ul> + <li>As the release candidate branch date approaches (as announced on the main + mailing list), bring the main trunk CVS files you are responsible for into a + stable state.<br> + </li> + <li>If you know of changes in either your code or its dependencies, start + checking regression test results to ensure your tests still pass. Don't + necessarily wait for the initial release tagging.<br> + </li> + <li>After the release manager announces that the release candidate branch has + occurred, check the latest regression test results to be sure + your tests haven't broken.<br> + </li> + <li>Developers can continue working on main trunk code changes after + the release candidate branch has occurred. There is no need to wait until the release + itself. + Modified files committed to CVS on the main trunk will not be included in the release unless the + developer explicitly commits the changes to the release candidate branch.<br> + </li> + <li>If specific to the release candidate only, the fixes should be committed + directly to the release candidate branch. In the more common case of fixes + which apply to both the main trunk and the release branch, the fixes are best + made to the main trunk, and then merged into the release candidate branch. See + FAQ for <a href="#merged_to_RC_n_n_n">tag rationale</a>.<br> + <br> + After a fix has been committed to the main trunk, here is a + typical procedure (assuming the release candidate branch is named RC_1_26_2) + to merge the fixed main trunk into the release candidate branch:</li> +</ul> +<blockquote> + <ul> + <li>Command Line CVS:</li> + </ul> + <blockquote> + <ul> + <li>Fixed code is committed to main branch <br> + </li> + <li>Switch to the release candidate branch + <blockquote> + <code>cvs update -r RC_1_26_2</code></blockquote> + </li> + <li>Merge changes in a trunk since previous merge to branch + <blockquote> +<pre>cvs update -j<a href="#merged_to_RC_n_n_n">merged_to_RC_1_26_2</a> -jHEAD buggycode.hpp + --> RCS file: /cvsroot/boost/.../buggycode.hpp,v + --> retrieving revision 1.4 + --> retrieving revision 1.6 + --> Merging differences between 1.4 and 1.6 into buggycode.hpp</pre> + </blockquote> + </li> + <li>Commit merged branch + <blockquote> +<pre>cvs commit -m "Merged fix for problem xyz from trunk to branch" buggycode.hpp</pre> + </blockquote> + </li> + <li>Go back to main trunk + <blockquote> +<pre>cvs update -A</pre> + </blockquote> + </li> + <li>Move tag to a new merged point + <blockquote> +<pre>cvs tag -F -c merged_to_RC_1_28_2 buggycode.hpp</pre> + </blockquote> + </li> + <li>Repeat as needed + </li> + </ul> + </blockquote> + <ul> + <li>WinCVS:</li> + </ul> + <blockquote> + <ul> + <li>After fixed code is committed to main branch, switch to the release + candidate branch:</li> + </ul> + <blockquote> + <blockquote> + <p>Select file(s) if not already selected.</p> + <p>Modify | Update selection... | + Update settings | Sticky options | Retrieve rev/tag/branch: <code>RC_1_26_2</code> | OK</p> + </blockquote> + </blockquote> + <ul> + <li>Merge changes from main trunk into the release candidate branch:</li> + </ul> + <blockquote> + <blockquote> + <p>Modify | Update selection... | + Update settings | Merge options | Only this rev/tag: <code> + <a href="#merged_to_RC_n_n_n">merged_to_RC_1_26_2</a></code> + | Plus with this rev/tag: <code>HEAD</code> | OK</p> + </blockquote> + </blockquote> + <ul> + <li>Commit merge results:</li> + </ul> + <blockquote> + <blockquote> + <p>Modify | Commit... | Enter log message: ... | OK</p> + </blockquote> + </blockquote> + <ul> + <li>Go back to main trunk:</li> + </ul> + <blockquote> + <blockquote> + <p>Modify | Update selection... | Update settings | Reset any sticky + date/tag/-k options | OK</p> + </blockquote> + </blockquote> + <ul> + <li>Tag as new merge point:</li> + </ul> + <blockquote> + <blockquote> + <p>Modify | Create tag on selection... | Create tag settings | Enter the tag + name to create: <code>merged_to_RC_1_26_2</code>, Overwrite existing tags + with same name | OK.</p> + </blockquote> + </blockquote> + </blockquote> +</blockquote> +<h2>Release Procedures for the Release <a name="Manager">Manager</a></h2> +<p>At time of branch-for-release:</p> +<ul> + <li>Tag the main trunk <code>merged_to_RC_n_n_n</code>.</li> + <li>Branch the main trunk with the tag <code>RC_n_n_n</code>.</li> +</ul> +<h2><a name="FAQ">FAQ</a></h2> +<p><b>What is the purpose of the <i><a name="merged_to_RC_n_n_n"> +merged_to_RC_n_n_n</a></i> tag?</b> This tag allows multiple merges from the +main trunk to the release candidate branch. Without it, merging an initial main +trunk fix into the release candidate branch would work, but merging a +second fix from main trunk to release candidate branch would result in a merge +conflict. Although this procedure seems convoluted, it works much better in +practice than several prior procedures we tried.</p> +<h2><a name="Acknowledgements">Acknowledgements</a></h2> +<p>This web page was written by Beman Dawes, with helpful suggestions from Dave +Abrahams and Steve Robbins. Jim Hyslop contributed the original CVS procedures. +Updated by Jeff Garland after 1.29 release based on list discussions.</p> +<hr> +<p>Revised: +<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->11 March, 2003<!--webbot bot="Timestamp" i-checksum="28831" endspan --></p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/requesting_new_features.htm b/more/requesting_new_features.htm new file mode 100644 index 0000000000..2dcedc525d --- /dev/null +++ b/more/requesting_new_features.htm @@ -0,0 +1,50 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Requesting New Features</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big> + Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big> + People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Requesting new features for Boost libraries</h1> +<p>If you have an idea for a feature or improvement to an existing Boost library +- go ahead and post it to either +<a href="http://www.boost.org/more/mailing_lists.htm#users">boost-users list</a> +or <a href="http://www.boost.org/more/mailing_lists.htm#main">boost mailing list</a> +(if you are posting for the first time, please read our +<a href="http://www.boost.org/more/discussion_policy.htm">discussion policy</a> +before you actually post). </p> +<p>You can also use our <a href="http://sourceforge.net/tracker/?group_id=7586"> +feature request tracking facility</a> at SourceForge, but experience has shown +that posting to either of the mailing lists is usually a more effective way to +get attention of boost developers. </p> +<p>If your proposal has its merits, it's very likely that it will generate a +constructive discussion that might actually result in (sometimes substantial) +improvement of the library - and your name being put on the library's +<a href="http://www.boost.org/more/lib_guide.htm#Acknowledgements"> +Acknowledgements</a> section! </p> +<hr> +<p>Contributed by <a href="../people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a></p> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 January, 2002<!--webbot bot="Timestamp" i-checksum="38453" endspan --> +</p> + +</body> + +</html> diff --git a/more/submission_process.htm b/more/submission_process.htm new file mode 100644 index 0000000000..f1c06e0bf6 --- /dev/null +++ b/more/submission_process.htm @@ -0,0 +1,127 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Library Submission Process</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Library Submission Process</h1> +<p>This page describes the process a library developer goes through to get a +library accepted by Boost.</p> +<p>See the <a href="lib_guide.htm">Boost Library Requirements and Guidelines</a> +page for issues of content.</p> +<h3><b>Steps for getting a library accepted by Boost:</b></h3> +<ul> + <li><a href="#Learn">Learn about Boost</a>.</li> + <li><a href="#interest">Determine interest</a>.</li> + <li><a href="#Preliminary">Preliminary submission</a>.</li> + <li><a href="#Refinement">Refinement</a>.</li> + <li><a href="#Submission">Submission for review</a>.</li> + <li><a href="#Review">Formal Review</a>.</li> + <li><a href="#site posting">Web site posting</a>.</li> + <li><a href="#People">People page.</a></li> + <li><a href="#Lifecycle">Lifecycle</a>.</li> +</ul> +<h2><a name="Learn">Learn</a> about Boost</h2> +<p>Subscribe to the <a href="mailing_lists.htm#main">main developers mailing list</a> for a +while, or look through the <a href="mailing_lists.htm#archive">archives</a>. +Click around the <a href="../index.htm">web site</a>. Understand the <a href="lib_guide.htm">Requirements</a>. +Read the rest of this page to learn about the process. Otherwise, you will +just end up wasting everyone's time.</p> +<p>There is a culture associated with Boost, aimed at encouraging high quality +libraries by a process of discussion and refinement.</p> +<p>If what you really want is a site that will just post your library without +even looking at it, you should go elsewhere.</p> +<h2>Determine <a name="interest">interest</a></h2> +<p>Potential library submitters should use the Boost developers <a href="mailing_lists.htm">mailing +list</a> as a forum to gauge interest a possible submission.</p> +<p>A message might be as simple as "Is there any interest in a library +which solves Traveling Salesperson problems in linear time?"</p> +<p>A bit of further description or snippet of code may be helpful. Messages +should be plain text; not rich text, HTML, etc.</p> +<p>Please don't post lengthy descriptions, documentation, or code to the mailing +list, and no attachments, even small ones. Please post lengthy material in +the YahooGroups boost <a href="http://www.yahoogroups.com/files/boost/">Files section</a> +(formerly called the " vault"). </p> +<h2><a name="Preliminary">Preliminary</a> submission</h2> +<p>If response to an initial query indicates interest, then post the preliminary +submission files in the <a href="http://www.yahoogroups.com/files/boost/">files section</a> of +the Boost YahooGroups web site if you haven't already done so.</p> +<h2><a name="Refinement">Refinement</a></h2> +<p>Discuss, refine, resubmit. Repeat until satisfied.</p> +<p>The exact details of this process varies a lot. Sometimes it is public, +on the mailing list, sometimes a lot of discussion happens in private +emails. For some libraries the process is over quickly, for others it goes +on for months. It's often challenging, and sometimes leads off in +completely unexpected directions. </p> +<p>The <a href="mailing_lists.htm#archive">archive</a> of past +messages is one way to see how this process worked for other Boost +libraries.</p> +<h2><a name="Submission">Submission</a> for review </h2> +<p>All of the files which make up the library should be combined and compressed +into a single submission file using the .zip format. Free encoders +and decoders for this format running on many different platforms are available +at the <a href="http://www.info-zip.org/pub/infozip/">Info-ZIP</a> web site, which +includes a FAQ and much other useful information about the .zip format. Many +commercial compressor-archiver utilities also support this format.</p> +<p>The submission file should contain material as if on the +boost.org web site. The closer the submission file mirrors the final +<a href="lib_guide.htm#Directory_structure">directory +structure</a> and format of the web site, the better. +<p>Like a preliminary submission, post the final submission .zip file in the <a href="http://www.yahoogroups.com/files/boost/">files section</a> of +the Boost YahooGroups web site +<h2>Formal <a name="Review">Review</a></h2> +<p>Before asking for formal review, your submission should be posted in the +Boost files/vault. Please verify that your submission compiles +and runs under at least two compilers. This flushes out obvious +portability problems. If you don't have access to a second compiler, ask +for help on the Boost mailing list.</p> +<p>Once a library author feels a submission (which presumably is now in the +files/vault) has matured enough for formal review, the author sends a message +requesting a formal review to the mailing list. Please use a subject in +the form "Review Request: library" where <i>library</i> is replaced by +the library name.</p> +<p>See <a href="formal_review_process.htm">Formal Review Process</a> for +details.</p> +<p>Formal Review schedules are posted on the <a href="mailing_lists.htm">mailing lists</a>. </p> +<h2>Boost web <a name="site posting">site posting</a></h2> +<p>Once an accepted library is ready for inclusion on the Boost web site, the +submitter is typically given Boost CVS write access, and expected to check-in +and maintain the library in the CVS. Contact the moderators if you need write +access or CVS use isn't possible for you.</p> +<h2><a name="People">People</a> page</h2> +<p>If the boost.org web site doesn't already have your capsule biography +and picture (optional, with not-too-serious pictures preferred), please +send them to the Boost webmaster.. It is +up to you as to whether or not the biography includes your email address or +other contact information. The preferred picture format is .jpg, but other +common formats are acceptable. The preferred image size is 500x375 but the +webmaster has photo editing software and can do the image preparation if +necessary.</p> +<h2><a name="Lifecycle">Lifecycle</a></h2> +<p>Libraries are software; they lose their value over time if not maintained. +Postings on the Boost developers or users mailing lists can alert you to +potential maintenance needs; please plan to maintain your library over time. If +you no longer can or wish to maintain your library, please post a message on the +Boost developers mailing list and help someone else take over as the library +maintainer.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->09 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38582" --></p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/test_policy.htm b/more/test_policy.htm new file mode 100644 index 0000000000..3967ae3255 --- /dev/null +++ b/more/test_policy.htm @@ -0,0 +1,95 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Test Policies and Protocols</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Test Policies and Protocols</h1> +<p>The Boost libraries are intended to be both reliable and portable. +Every experienced programmer knows that means each library must be tested against a suitable number of test cases, on a wide range of platforms, +and then tested again (regression tested) every time a change is made and before +every release. </p> +<p>"Quality assurance based on a wide range of targeted tests" as one +of the key answers to <a href="http://users.comlab.ox.ac.uk/tony.hoare">C.A.R +Hoare's</a> question +<a href="http://users.comlab.ox.ac.uk/tony.hoare/icse18.html">"How +did software get so reliable without proof."</a></p> +<h2>Regression test</h2> +<p>Boost uses an automatic <a href="regression.html"> regression test suite</a> which generates HTML +<a href="../status/compiler_status.html">compiler +status tables</a>.</p> +<h2>Test Policy</h2> +<h3>Required</h3> +<ul> + <li>Every Boost library should supply one or more suitable test programs to be + exercised by the Boost <a href="regression.html"> regression test suite</a>. In addition to + the usual compile-link-run tests expecting successful completion, + compile-only or compile-and-link-only tests may be performed, and success + for the test may be defined as failure of the steps.</li> + <li>Test program execution must report errors by returning a non-zero value. They + may also write to stdout or stderr, but that output should be relatively + brief. Regardless of other output, a non-zero return value is the only + way the regression test framework will recognize an error has + occurred. Note that test programs to be included in the status tables must + compile, link, and run quickly since the tests are executed many, many, + times.</li> + <li>Libraries with time consuming tests should be divided into a + fast-execution basic test program for the status tables, and a separate + full-coverage test program for exhaustive test cases. The basic test + should concentrate on compilation issues so that the status tables + accurately reflect the library's likelihood of correct compilation on a + platform.</li> + <li>If for any reason the usual test policies do not apply to a particular + library, an alternate test strategy must be implemented. </li> +</ul> +<h3>Optional</h3> +<ul> + <li>Use the Boost Test Library for the construction of simple tests.</li> + <li>[Planned] Use the Boost Unit Test Library for the construction of more complex tests + and test suites.</li> + <li>The Boost Program Execution Library is also available for very simple + tests, but the Boost Test Library is much preferred even for very simple + tests.</li> +</ul> +<h2>Suggested Protocol for Fixing Bugs or Adding Features.</h2> +<ul> + <li>First, add regression test cases that detects the bug or tests the + feature. Sometimes adding one case suggests similar untested cases, and they + are added too.</li> + <li>Second, for bugs, run the regression test and verify that the bug is now + detected.</li> + <li>Third, then, and only then, fix the bug or add the feature.</li> + <li>Finally, rerun the full regression tests - sometimes the change breaks + something else.</li> +</ul> +<h2>History</h2> +<p>The current regression test program was developed by Jens Maurer in December, +2000. The original regression test concept and program, including the automatic +generation of HTML compiler status tables, was developed by Beman Dawes in June, +2000.</p> +<h2>Acknowledgements</h2> +<p>Written by Beman Dawes. Jens Maurer, Paul Moore, Gary Powell and Jeremy Siek contributed helpful suggestions.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->17 February, 2003<!--webbot bot="Timestamp" endspan i-checksum="40411" --> +</p> +<p> </p> +<p> </p> + +</body> + +</html>
\ No newline at end of file diff --git a/more/writingdoc/design.html b/more/writingdoc/design.html new file mode 100644 index 0000000000..20021cbac3 --- /dev/null +++ b/more/writingdoc/design.html @@ -0,0 +1,379 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../boost.css"> +<title>Writing Documentation for Boost - HTML Design</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost" src="../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">Writing Documentation for Boost</h1> + <h2 align="center">HTML Design</h2> + </td> + </tr> +</table> +<hr> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#common-pages">Common Pages Included in HTML Documentation</a></dt> + <dl class="page-index"> + <dt><a href="#index-page">Index</a></dt> + <dt><a href="#overview-page">Overview</a></dt> + <dt><a href="#definitions-page">Definitions</a></dt> + <dt><a href="#rationale-page">Rationale</a></dt> + <dt><a href="#configuration-page">Configuration Information</a></dt> + <dt><a href="#faq-page">Frequently Asked Questions</a></dt> + <dt><a href="#bibliography-page">Bibliography</a></dt> + <dt><a href="#acknowledgements-page">Acknowledgment</a></dt> + <dt><a href="#header-page">Header Reference</a></dt> + </dl> + <dt><a href="#layout">Layout</a></dt> + <dl class="page-index"> + <dt><a href="#page-banner">Page Banner</a></dt> + <dt><a href="#page-index">Page Index</a></dt> + <dt><a href="#content">Documentation Content</a></dt> + <dl class="page-index"> + <dt><a href="#doc-footnotes">Footnotes</a></dt> + </dl> + <dt><a href="#revision-info">Revision Information</a></dt> + <dt><a href="#copyright">Copyright Information</a></dt> + </dl> + <dt><a href="#format">Format</a></dt> + <dl class="page-index"> + <dt><a href="#style-sheets">Cascading Style Sheets</a></dt> + <dl class="page-index"> + <dt><a href="#boost-style-sheet">Boost Style Sheet</a></dt> + </dl> + </dl> + <dt><a href="#templates">Templates</a></dt> + <dl class="page-index"> + <dt><a href="#index-template">Index Page Template</a></dt> + <dt><a href="#overview-template">Overview Page Template</a></dt> + <dt><a href="#definitions-template">Definitions Page Template</a></dt> + <dt><a href="#rationale-template">Rationale Page Template</a></dt> + <dt><a href="#configuration-template">Configuration Page Template</a></dt> + <dt><a href="#faq-template">FAQ (Frequently Asked Questions) Page Template</a></dt> + <dt><a href="#bibliography-template">Bibliography Page Template</a></dt> + <dt><a href="#acknowledgements-template">Acknowledgments Page Template</a></dt> + <dt><a href="#header-template">Header Page Template</a></dt> + </dl> +</dl> +<h2><a name="introduction"></a>Introduction</h2> +<p>Boost places no requirements on the design of HTML documentation for library + submitters. If you are submitting a library for which documentation already + exists in either HTML or in a form easily converted to HTML then there is no + need for you to read this document. However, if you have not yet written the + documentation, or if you expect to have to translate documentation written in + a format not easily convertible to HTML then this document can give you a lot + of information on how to go about writing documentation in HTML.</p> +<p>In several places this document assumes you're writing the documentation to + conform to the structure described in the <a href="structure.html">Documentation + Structure</a> document. There is no requirement that your documentation content + follow these guidelines, but they provide an effective way to communicate technical + specifications for a library in a terse yet precise manner that's familiar to + many Boost users.</p> +<p>This document also contains links to <a href="#templates">HTML template files</a> + that can be used to rapidly develop documentation for a library submission. + These templates follow the guidelines presented here and in the <a href="structure.html">Documentation + Structure</a> document.</p> +<h2><a name="common-pages"></a>Common Pages Included in HTML Documentation</h2> +<p>Most HTML documentation projects will contain some common pages. General guidelines + for these common pages are provided below.</p> +<h3><a name="index-page"></a>Index</h3> +<p>The index page is the first page presented to a user when he browses the documentation. + Generally this page should not contain any actual content, but instead contains + a list of links to specific content. At a minimum this list should contain a + link to every HTML page contained in the documentation. Optionally, sub-lists + may be provided for individual pages linking to specific subjects within the + page. These sub-lists should form a "tree" hierarchy based on the + level of heading tag used for the specific subject. Inclusion of such sub-lists + for every page can make the index rather lengthy, and since each page should + include its own <a href="#page-index">Page Index</a>, it may make the navigation + of the documentation easier if such sub-lists are avoided. However, there is + one exception to this guideline: reference documentation should contain a link + to every header file in the library and a sub-list with a link to every macro, + value, type, class, function and object (see <a href="structure.html">Documentation + Structure</a>) found in the header. Users aren't always sure what header file + any of these may be contained in, so this structure in the index allows for + easy navigation of the reference documentation.</p> +<p>The index list should generally be constructed using an HTML "definition + list" (<dl> and <dt> tags). A definition list has no bullets + or ordered specifications and produces a cleaner layout then an unordered list + (<ul> and <li> tags) or an ordered list (<ol> and <li> + tags). If you choose to use the common <a href="#boost-style-sheet">Boost Style + Sheet</a> you should add a <code>class="index"</code> attribute/value pair to + the <dl> tag.</p> +<p>An Index page <a href="#index-template">template</a> is provided for use.</p> +<h3><a name="overview-page"></a>Overview</h3> +<p>The Overview page is used to introduce the reader to the library. It should + give a high-level overview of the purpose of the library and introduce the reader + to any concepts they may be unfamiliar with. This may also be an appropriate + place for some "light" rationale, though more thorough presentation + of any rationale would be better placed in the <a href="#rationale-page">Rational + Page</a>.</p> +<p>Like most content pages, the Overview page should include a <a href="#page-index">Page + Index</a>.</p> +<p>An Overview page <a href="#overview-template">template</a> is provided for + use.</p> +<h3><a name="definitions-page"></a>Definitions</h3> +<p>The Definitions page is used to provide a list of definitions for terms that + a user may be unfamiliar with.</p> +<p>The definition list should generally be constructed using an HTML "definition + list" (<dl> and <DT> tags). A definition list has no bullets + or ordered specifications and produces a cleaner layout then an unordered list + (<UL> and <li> tags) or an ordered list (<ol> and <li> + tags). If you choose to use the common <a href="#boost-style-sheet">Boost Style + Sheet</a> you should add a <code>class="definition"</code> attribute/value pair + to the <dl> tag.</p> +<p>Because this page's content should only contain a list of definitions, it should + not have a <a href="#page-index">Page Index</a>.</p> +<p></p> +<p> A Definitions page <a href="#definitions-template">template</a> is provided + for use.</p> +<h3><a name="rationale-page"></a>Rationale</h3> +<p>The Rationale page is used to provide lengthy descriptions of the rationale + behind the library's design. This information helps users to understand why + a library was designed the way it was and may reduce the frequency of a number + of frequently asked questions. For a better description of why rationale is + important see the <a href="http://www.boost.org/more/lib_guide.htm#Rationale">Rationale + rationale</a> in the general submission guidelines.</p> +<p>Like most content pages, the Rationale page should include a <a href="#page-index">Page + Index</a>.</p> +<p></p> +<p>A Rationale page <a href="#rationale-template">template</a> is provided for + use.</p> +<h3><a name="configuration-page"></a>Configuration Information</h3> +<p>The Configuration Information page is used to document configuration macros + used by the library. Such macros belong in one of three groups: macros used + by library implenters defined in <code><boost/config.hpp></code>, macros + used by library users to detect platform configuration information and macros + defined by library users to configure library behavior.</p> +<p>Like most content pages, the Overview page should include a <a href="#page-index">Page + Index</a>.</p> +<p></p> +<p>A Configuration page <a href="#configuration-template">template</a> is provided + for use.</p> +<h3><a name="faq-page"></a>Frequently Asked Questions</h3> +<p>As a library matures the users will have questions about the usage of the library. + Often users will ask the same questions over and over again. Rather than having + to deal with answering the question every time it's asked, a Frequently Asked + Questions (commonly known as FAQs) page can be used to document the questions + and answers. This is such a valuable piece of documentation not only for the + users but for the maintainers as well, that a FAQ page should be provided from + the outset. If there are no questions that will obviously become a FAQ, the + initial page may just indicate that there are no FAQs yet. This empty place + holder helps to indicate to the users that you plan to address any FAQs as they + occur.</p> +<p>The <a href="#page-index">Page Index</a> for the FAQ page should contain a + list of all the questions contained in the document. The actual question entries + should be formatted with the question in a heading tag and the answers in standard + paragraph format. This provides a clean presentation that's easy to read.</p> +<p>A Frequently Asked Questions page <a href="#faq-template">template</a> is provided + for use.</p> +<h3><a name="bibliography-page"></a>Bibliography</h3> +<p>The Bibliography page is used to document any bibliographical information associated + with references made within the documentation to external resources. Parenthetical + references are used within the documentation which link to entries in the Bibliography + page. Bibliographical entries provide detailed information about the external + resource and may contain hyper links to the resource if it's available online. + There are several formal styles used for writing bibliographies. You may use + what ever style you want, but one of the better styles to consider using can + be referenced <a href="http://www.columbia.edu/cu/cup/cgos/idx_basic.html">here</a>.</p> +<p>Since the Bibliography page should contain only bibliographical information + there is no need for a <a href="#page-index">Page Index</a>.</p> +<p>A Bibliography page <a href="#bibliography-template">template</a> is provided + for use.</p> +<h3><a name="acknowledgements-page"></a>Acknowledgment</h3> +<p>The Acknowledgment page is used to give credit where credit is due. When individuals + provide input on the design or implementation, or when you make use of someone + else's work, you should acknowledge them. This is a courtesy that you'd expect + others to extend to you, so you should strive to acknowledge the efforts of + everyone else in your own documentation.</p> +<p>Since the Acknowledgment page should contain only a list of acknowledgment + there is no need for a <a href="#page-index">Page Index</a>.</p> +<p>An Acknowledgments page <a href="#acknowledgements-template">template</a> is + provided for use.</p> +<h3><a name="header-page"></a>Header Reference</h3> +<p>The Header Reference pages are the most important pages in your documentation. + They document all library headers, including all the macros, values, types, + classes, functions and objects defined in them. In general it may prove useful + to follow the guidelines in <a href="structure.html">Documentation Structure</a> + when writing the content for these pages.</p> +<p>Like most content pages, the Header Reference pages should include a <a href="#page-index">Page + Index</a>.</p> +<p>A Header Reference page <a href="#header-template">template</a> is provided + for use.</p> +<h2><a name="layout"></a>Layout</h2> +<p>There are certain page layout concepts that will be used frequently in many + of your pages. This section outlines some general guidelines that you can follow + when designing each of these layout concepts for your documentation.</p> +<h3><a name="page-banner"></a>Page Banner</h3> +<p>The Page Banner is located at the very top of a page and provides quick information + about the page contents. This includes the Boost logo, which indicates to the + reader that this page is part of the Boost web site, a title for the documentation + (generally the library name) and the page title. The Boost logo should hyper + link to the Boost home page on the index page and to the index page on all other + pages. This allows the user to easily navigate through the Boost web site and + through the documentation. The <title> tag for the HTML page should consist + of the documentation title and the page title separated by a hyphen.</p> +<p>The Page Banner should be separated from the rest of the page by the use of + an <hr> tag. This helps to clearly separate the actual content from the + title information and produces cleaner text.</p> +<h3><a name="page-index"></a>Page Index</h3> +<p>The page index is used to quickly navigate to the various sections of the documentation + on the page, and when present should be located just below the Page Banner.</p> +<p>The index list should generally be constructed using an HTML "definition + list" (<dl> and <DT> tags). A definition list has no bullets + or ordered specifications and produces a cleaner layout then an unordered list + (<UL> and <li> tags) or an ordered list (<ol> and <li> + tags). If you choose to use the Boost Style Sheet you should add a <code>class="page-index"</code> + attribute/value pair to the <dl> tag.</p> +<p>Most pages should include a Page Index.</p> +<h3><a name="content"></a>Documentation Content</h3> +<p>The page's actual documentation content will be formatted according to the + specific needs of individual pages, and should be placed right after the Page + Index if present, or after the Page Banner if not. In general the documentation + content will take the form of paragraph text contained underneath section headings.</p> +<h3><a name="doc-footnotes"></a>Footnotes</h3> +<p>Footnotes may be used within a page's documentation. Within the documentation + content a footnote reference should take the form of a footnote number in parentheses + (the parentheses make it easier for the reader to click on the hyper link) hyper + linking to the actual footnote at the bottom of the page's documentation content. + You may either use the <sup> tag to format such footnote numbers, or, + preferably, you can use a CSS style class in order to distinguish the number + as a footnote instead of as part of the actual text. If you choose to use the + common <a href="#boost-style-sheet">Boost Style Sheet</a>, a <code>footnote</code> + class is defined for this purpose.</p> +<h3><a name="revision-info"></a>Revision Information</h3> +<p>At the bottom of every page should be some revision information indicating + when the page was last revised. This information should be separated from the + rest of the page above by an <hr> tag. The following HTML code snippet + can be used to track this revision information (this code uses some server components + that exist on the Boost web site to automatically track revision dates with + out the need for hand editing the date text):</p> +<pre><hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 01 January, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +</pre> +<h3><a name="copyright"></a>Copyright Information</h3> +<p>The very bottom of the page should contain any copyright information that applies + to the document.</p> +<h2><a name="format"></a>Format</h2> +<p>This section provides general guidelines for formatting documentation using + HTML. The description of the various "common pages" gave specific + details for formatting specific sections of the documentation, which should + override these guidelines.</p> +<h3><a name="code-format"></a>Code</h3> +<p>Code within the documentation should be placed within either <code></code> + or <pre></pre> tags. For code that's placed inline with other text + you use <code></code> tags, while <pre></pre> tags are + used for code "blocks". If a cascading style sheet is used to specify + formatting for these tags, a fixed width sans serif font should be used. This + insures that the code is easily distinguishable from the rest of the text. It + may also be beneficial to set the style for <pre></pre> tags to + indent the text, to help separate code blocks from other structural HTML blocks. + The <a href="#boost-style-sheet">Boost Style Sheet</a> specifies formatting + for these tags.</p> +<p><b>Note:</b> "Code" includes variable names, function names, etc.</p> +<h3><a name="lists"></a>Lists</h3> +<p>Lists should be constructed as unordered (<UL> and <li> tags), + ordered (<ol> and <li> tags) or definition (<dl> and <DT> + tags) lists in HTML. You use an unordered list when you need a collection of + items that don't have any kind of logical ordering, such as a list of data types + that are defined by the library and can be used for a template argument. You + use an ordered list when the collection of items must be grouped in a logical + ordering, such as when enumerating the steps that an action logically performs. + You use a definition list when the list consists of not only items that have + no logical ordering, but also contains definitions/descriptions/etc. of the + items. A good example of this is the function specifications as described in + <a href="structure.html">Documentation Structure</a>.</p> +<h3><a name="graphics"></a>Graphics</h3> +<p>Graphics should be used very sparingly, if at all. Graphic images greatly effect + the download time for many people, which can discourage users from reading the + documentation. If you need graphic images to help illustrate something in your + documentation consider supplying only a link to the image within the documentation, + instead of embedding it directly in the text. If an image is going to be included + in the text of the document you should specify the image's size in the <img> + tag, in order to allow the user's browser to optimize the formatting of the + text before the image is loaded.</p> +<h3><a name="non-breaking-spaces"></a>Non-breaking Spaces</h3> +<p>Non-breaking spaces (&nbsp;) should be avoided in HTML text. Generally + there are more appropriate ways to format the document, such as using list constructs + or specifying indentation as a style attribute or in cascading style sheets.</p> +<h3><a name="style-sheets"></a>Cascading Style Sheets</h3> +<p>Cascading style sheets allow you to apply some advanced formatting styles to + an HTML document. More importantly, they allow you to change the formatting + in a single file and effect all pages using the style sheet. Instead of struggling + to produce a specific format in HTML it's often easier and more flexible to + specify the formatting in a style sheet.</p> +<h4><a name="boost-style-sheet"></a>Boost Style Sheet</h4> +<p>The concept of using cascading style sheets to format HTML is such a good idea + that it can be beneficial to apply this across the entire Boost site. Of course + we can't require this (if Boost were to require such trivia for submissions + it's likely that many programmers would be discouraged from contributing). However, + a "standard" Boost style sheet (http://www.boost.org/boost.css) is + supplied anyway, so that a contributer can quickly and easily produce clear + and consistent documentation that reflects a Boost "brand" if they + so choose. If, at a later date, it's decided to update the Boost "brand", + it may be done in this single file and all documents using the style sheet will + automatically be updated.</p> +<p>The Boost supplied style sheet not only specifies styles for many standard + tags, it also specifies several style "classes". A class is specified + for a given tag instead of being applied to all instances of a given tag type. + Below is a list of the classes specified in the Boost style sheet and a description + of when to use them:</p> +<dl> + <dt><b>index</b> Used for <dl> tags when writing index lists.</dt> + <dt><b>page-index</b> Used for <dl> tags when writing page index lists.</dt> + <dt><b>Footnote</b> Used when writing Footnote numbers.</dt> + <dt><b>function-semantics</b> Used for <dl> tags when writing function + semantic lists.</dt> +</dl> +<h2><a name="templates"></a>Templates</h2> +<p>Instead of hand coding every HTML page, HTML "templates" can be used instead. + The list below provides links to templates that may be used when writing documentation + for a contribution to Boost. Links provided in these templates assume the files + will reside in the "traditional" directory hierarchy of <i>boost/libs/library/doc</i>. + They may need correcting if the file will reside in some other location.</p> +<p><b>Note:</b> Since these "templates" are just HTML pages simply clicking + on the links below will load the template in your browser. You will need to + use a browser specific method to download the files instead of loading them + into the browser (for instance, on most Windows browsers you can right click + on the link and select the appropriate command from the context sensitive menu).</p> +<ul> + <li><a name="index-template"></a><a href="template/index.html">Index Page Template</a></li> + <li><a name="overview-template"></a><a href="template%5Coverview.html">Overview + Page Template</a></li> + <li><a name="definitions-template"></a><a href="template/definitions.html">Definitions + Page Template</a></li> + <li><a name="rationale-template"></a><a href="template/rationale.html">Rationale + Page Template</a></li> + <li><a name="configuration-template"></a><a href="template/configuration.html">Configuration + Page Template</a></li> + <li><a name="faq-template"></a><a href="template/faq.html">FAQ (Frequently Asked + Questions) Page Template</a></li> + <li><a name="bibliography-template"></a><a href="template/bibliography.html">Bibliography + Page Template</a></li> + <li><a name="acknowledgements-template"></a><a href="template/acknowledgments.html">Acknowledgments + Page Template</a></li> + <li><a name="header-template"></a><a href="template/header.html">Header Page + Template</a></li> +</ul> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> + 2001. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/index.html b/more/writingdoc/index.html new file mode 100644 index 0000000000..89eac51d12 --- /dev/null +++ b/more/writingdoc/index.html @@ -0,0 +1,36 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../boost.css"> +<title>Writing Documentation for Boost</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">Writing Documentation for Boost</h1> + <h2 align="center">Index</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="introduction.html">Introduction</a></dt> + <dt><a href="structure.html">Documentation Structure</a></dt> + <dt><a href="design.html">HTML Design</a></dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> + 2001. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/introduction.html b/more/writingdoc/introduction.html new file mode 100644 index 0000000000..112e2bed64 --- /dev/null +++ b/more/writingdoc/introduction.html @@ -0,0 +1,48 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../boost.css"> +<title>Writing Documentation for Boost - Introduction</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="index.htm"><img height="86" width="277" alt="C++ Boost" src="../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">Writing Documentation for Boost</h1> + <h2 align="center">Introduction</h2> + </td> + </tr> +</table> +<hr> +<p>Boost does not have any requirements on how you write your documentation. If + you are submitting a library that already has written documentation in HTML + format, there is no reason to change it to follow any of the guidelines presented + here. However, if you have documentation that's not in HTML format and can't + be easily converted to HTML, or if you're starting on a library from scratch + or have a library with no documentation then these guidelines can make writing + the documentation much easier.</p> +<p>The section on <a href="structure.html">Documentation Structure</a> describes + how to go about structuring the documentation's content. This section may be + helpful even for libraries that already have documentation. If there's a desire + to present the library for possible inclusion by the C++ Standards Committee + then there may be a need to restructure the documentation's content in order + to insure the content meets explicit requirements for library components (Section + 17.3).</p> +<p>The section on <a href="design.html">HTML Design</a> gives general rules to + follow when writing HTML documentation in order to give a professional and consistent + look. This section also contains some template files that can be used to rapidly + create documentation pages.</p> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> + 2001. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/structure.html b/more/writingdoc/structure.html new file mode 100644 index 0000000000..14b271beb9 --- /dev/null +++ b/more/writingdoc/structure.html @@ -0,0 +1,257 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../boost.css"> +<title>Writing Documentation for Boost - Documentation Structure</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="index.htm"><img height="86" width="277" alt="C++ Boost" src="../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">Writing Documentation for Boost</h1> + <h2 align="center">Documentation Structure</h2> + </td> + </tr> +</table> +<hr> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#standards-conforming">Standards Conforming Documentation</a></dt> + <dl class="page-index"> + <dt><a href="#elements">Document elements</a></dt> + <dl class="page-index"> + <dt><a href="#summary">Summary</a></dt> + <dt><a href="#requirements">Requirements</a></dt> + <dt><a href="#detailed-specs">Detailed specifications</a></dt> + <dt><a href="#ref-cpp">References to the Standard C++ library</a></dt> + <dt><a href="#ref-c">References to the Standard C library</a></dt> + </dl> + <dt><a href="#other">Other conventions</a></dt> + <dl class="page-index"> + <dt><a href="#type-descs">Type descriptions</a></dt> + </dl> + </dl> + <dt><a href="#more">More Information</a></dt> + <dl class="page-index"> + <dt><a href="#function-semantic-explanations">Function semantic element explanations</a></dt> + <dl class="page-index"> + <dt><a href="#requires">Requires</a></dt> + <dt><a href="#effects">Effects</a></dt> + <dt><a href="#postconditions">Postconditions</a></dt> + <dt><a href="#returns">Returns</a></dt> + <dt><a href="#throws">Throws</a></dt> + <dt><a href="#complexity">Complexity</a></dt> + <dt><a href="#rationale">Rationale</a></dt> + </dl> + </dl> + <dt><a href="#footnotes">Footnotes</a></dt> +</dl> +<h2><a name="introduction">Introduction</a></h2> +<p>Boost itself does not require any specific documentation structure. The C++ + Standard, however, has very explicit requirements for the description of library + components (Section 17.3). So for Boost libraries likely to be proposed for + inclusion in the standard, it is highly desirable to structure documentation + in a way that meets the requirements of the the standard. Doing so eliminates + the need to rewrite the documentation for standardization.</p> +<p>Library developers should remember that for a library to be accepted as part + of the C++ Standard Library, the proposal must include full wording. The committee + will not do that work for you.</p> +<p>Beyond that, the documentation structure required for the standard is an effective + way to communicate the technical specifications for a library. Although terse, + it is already familiar to many Boost users, and is far more precise than most + ad hoc documentation structures.</p> +<p>The following description is for the structure of documentation required by + the standard. Boost libraries should also provided additional documentation, + such as introductory, tutorial, example, and rationale material.</p> +<h2><a name="standards-conforming">Standards Conforming</a> Documentation</h2> +<h3><a name="elements">Document elements</a></h3> +<p>Each document contains the following elements, as applicable<a class="footnote" href="#footnote1">(1)</a>:</p> +<ul> + <li><a href="#summary">Summary</a></li> + <li><a href="#requirements">Requirements</a></li> + <li><a href="#detailed-specs">Detailed specifications</a></li> + <li><a href="#ref-cpp">References to the Standard C++ library</a></li> + <li><a href="#ref-c">References to the Standard C library</a></li> +</ul> +<h4><a name="summary">Summary</a></h4> +<p>The Summary provides a synopsis of the category, and introduces the first-level + subclauses. Each subclause also provides a summary, listing the headers specified + in the subclause and the library entities provided in each header.</p> +<p>Paragraphs labeled "Note(s):" or "Example(s):" are informative, other paragraphs + are normative.</p> +<p>The summary and the detailed specifications are presented in the order:</p> +<ul> + <li>Macros</li> + <li>Values</li> + <li>Types</li> + <li>Classes</li> + <li>Functions</li> + <li>Objects</li> +</ul> +<h4><a name="requirements">Requirements</a></h4> +<p>The library can be extended by a C++ program. Each clause, as applicable, describes + the requirements that such extensions must meet. Such extensions are generally + one of the following:</p> +<ul> + <li>Template arguments</li> + <li>Derived classes</li> + <li>Containers, iterators, and/or algorithms that meet an interface convention</li> +</ul> +<p>Interface convention requirements are stated as generally as possible. Instead + of stating "<code>class X</code> has to define a member function <code>operator++()</code>," + the interface requires "for any object <code>x</code> of <code>class X</code>, + <code>++x</code> is defined." That is, whether the operator is a member is unspecified.</p> +<p>Requirements are stated in terms of well-defined expressions, which define + valid terms of the types that satisfy the requirements. For every set of requirements + there is a table that specifies an initial set of the valid expressions and + their semantics. Any generic algorithm that uses the requirements is described + in terms of the valid expressions for its formal type parameters.</p> +<p>Template argument requirements are sometimes referenced by name.</p> +<p>In some cases the semantic requirements are presented as C++ code. Such code + is intended as a specification of equivalance of a construct to another construct, + not necessarily as the way the construct must be implemented.<a class="footnote" href="#footnote2">(2)</a></p> +<h4><a name="detailed-specs">Detailed specification</a></h4> +<p>The detailed specifications each contain the following elements:</p> +<ul> + <li>Name and brief description</li> + <li>Synopsis (class definition or function prototype, as appropriate)</li> + <li>Restrictions on template arguments, if any</li> + <li>Description of class invariants</li> + <li>Description of function semantics</li> +</ul> +<p>Descriptions of class member functions follow the order (as appropriate)<a class="footnote" href="#footnote3">(3)</a>:</p> +<ul> + <li>Constructor(s) and destructor</li> + <li>Copying and assignment functions</li> + <li>Comparison functions</li> + <li>Modifier functions</li> + <li>Observer functions</li> + <li>Operators and other non-member functions</li> +</ul> +<p>Descriptions of function semantics contain the following <a name="function-elements">elements</a> + (as appropriate)<a class="footnote" href="#footnote4">(4):</a></p> +<dl class="function-semantics"> + <dt><b><a href="#requires">Requires:</a></b> the preconditions for calling the + function</dt> + <dt><b><a href="#effects">Effects:</a></b> the actions performed by the function</dt> + <dt><b><a href="#postconditions">Postconditions:</a></b> the observable results + established by the function</dt> + <dt><b><a href="#returns">Returns:</a></b> a description of the value(s) returned + by the function</dt> + <dt><b><a href="#throws">Throws:</a></b> any exceptions thrown by the function, + and the conditions that would cause the exception</dt> + <dt><b><a href="#complexity">Complexity:</a></b> the time and/or space complexity + of the function</dt> + <dt><b><a href="#rationale">Rationale:</a></b> the rationale for the function's design + or existence</dt> +</dl> +<p>Complexity requirements specified in the library clauses are upper bounds, + and implementations that provide better complexity guarantees satisfy the requirements.</p> +<h4><a name="ref-cpp">References to the C++ Standard library</a></h4> +<h4><a name="ref-c">References to the C Standard library</a></h4> +<h3><a name="other">Other conventions</a></h3> +<p>These conventions are for describing implementation-defined types, and member + functions.</p> +<h4><a name="type-descs">Type descriptions</a></h4> +<p>The Requirements subclauses may describe names that are used to specify constraints + on template arguments.</p> +<h2><a name="more">More Information</a></h2> +<h3><a name="function-semantic-explanations">Function semantic element explanations</a></h3> +<p>The function semantic element description <a href="#function-elements">above</a> + is taken directly from the C++ standard, and is quite terse. Here is a more + detailed explanation of each of the elements.</p> +<p>Note the use of the <code><code> ... </code></code> font tag to + distinguish actual C++ usage from English prose.</p> +<h4><a name="requires">Requires</a></h4> +<p>Preconditions for calling the function, typically expressed as predicates. + The most common preconditions are requirements on the value of arguments, often + in the form of C++ expressions. For example, +<pre> +<code>void limit( int * p, int min, int max );</code> +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> <code>p != 0 && min <= max</code></dt> +</dl> +<p>Requirements already enforced by the C++ language rules (such as the type of + arguments) are not repeated in Requires paragraphs.</p> +<h4><a name="effects">Effects</a></h4> +<p>The actions performed by the function, described either in prose or in C++. + A description in prose is often less limiting on implementors, but is often + less precise than C++ code.</p> +<p>If an effect is specified in one of the other elements, particularly <i>postconditions</i>, + <i>returns</i>, or <i>throws</i>, it is not also described in the <i>effects</i> + paragraph. Having only a single description ensures that there is one and only + one specification, and thus eliminates the risk of divergence.</p> +<h4><a name="postconditions">Postconditions</a></h4> +<p>The observable results of the function, such as the value of variables. Postconditions + are often expressed as predicates that are true after the function completes, + in the form of C++ expressions. For example:</p> +<pre> +void make_zero_if_negative( int & x ); +</pre> +<dl class="function-semantics"> + <dt><b>Postcondition:</b> <code>x >= 0</code></dt> +</dl> +<h4><a name="returns">Returns</a></h4> +<p>The value returned by the function, usually in the form of a C++ expression. + For example:</p> +<pre> +int sum( int x, int y ); +</pre> +<dl class="function-semantics"> + <dt><b>Returns:</b> <code>x + y</code></dt> +</dl> +<p>Only specify the return value; the type is already dictated by C++ language + rules. +<h4><a name="throws">Throws</a></h4> +<p>Specify both the type of exception thrown, and the condition that causes the + exception to be thrown. For example, the <code>std::basic_string</code> class + specifies: +<pre> +void resize(size_type n, charT c); +</pre> +<dl class="function-semantics"> + <dt><b>Throws:</b> <code> length_error</code> if <code>n > max_size()</code>.</dt> +</dl> +<h4><a name="complexity">Complexity</a></h4> +<p>Specifying the time and/or space complexity of a function is often not desirable + because it over-constrains implementors and is hard to specify correctly. Complexity + is thus often best left as a quality of implementation issue.</p> +<p>A library component, however, can become effectively non-portable if there + is wide variation in performance between conforming implementations. Containers + are a prime example. In these cases it becomes worthwhile to specify complexity.</p> +<p>Complexity is often specified in generalized <a href="http://hissa.nist.gov/dads/HTML/bigOnotation.html"> + "Big-O" notation</a>.</p> +<h4><a name="rationale">Rationale</a></h4> +<p>Specifying the rationale for a function's design or existence can often give users + a lot of insight into why a library is designed the way it is. More importantly, it + can help prevent "fixing" something that wasn't really broken as the library matures.</p> +<h2><a name="footnotes">Footnotes</a></h2> +<dl> + <dt><a class="footnote" name="footnote1">(1)</a> + To save space, items that do not apply to a clause are omitted. For example, + if a clause does not specify any requirements, there will be no "Requirements" + subclause.</dt> + <dt><a class="footnote" name="footnote2">(2)</a> Although in some cases the + code is unambiguously the optimum implementation.</dt> + <dt><a class="footnote" name="footnote3">(3)</a> To save space, items that do + not apply to a class are omitted. For example, if a class does not specify + any comparison functions, there will be no "Comparison functions" subclause.</dt> + <dt><a class="footnote" name="footnote4">(4)</a> To save space, items that do + not apply to a function are omitted. For example, if a function does not specify + any precondition, there will be no "Requires" paragraph.</dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> + 2001. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/acknowledgments.html b/more/writingdoc/template/acknowledgments.html new file mode 100644 index 0000000000..eec331734c --- /dev/null +++ b/more/writingdoc/template/acknowledgments.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Acknowledgments</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Acknowledgments</h2> + </td> + </tr> +</table> +<hr> +{{text}} +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/bibliography.html b/more/writingdoc/template/bibliography.html new file mode 100644 index 0000000000..27bfc5efa3 --- /dev/null +++ b/more/writingdoc/template/bibliography.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Bibliography</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Bibliography</h2> + </td> + </tr> +</table> +<hr> +{{bibliographical information}} +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/configuration.html b/more/writingdoc/template/configuration.html new file mode 100644 index 0000000000..e35646dfe3 --- /dev/null +++ b/more/writingdoc/template/configuration.html @@ -0,0 +1,90 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Configuration</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Configuration</h2> + </td> + </tr> +</table> +<hr> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#app-defined">Application Defined Macros</a></dt> + <dt><a href="#lib-defined-public">Public Library Defined Macros</a></dt> + <dt><a href="#lib-defined-impl">Library Defined Implementation Macros</a></dt> +</dl> +<h2><a name="introduction"></a>Introduction</h2> +<p>{{library}} uses several configuration macros in <a href="http://www.boost.org/libs/config/config.htm"><boost/config.hpp></a>, + as well as configuration macros meant to be supplied by the application. These + macros are documented here.</p> +<h2><a name="app-defined"></a>Application Defined Macros</h2> +<p>These are the macros that may be defined by an application using {{library}}.</p> +<table summary="application defined macros" cellspacing="10" width="100%"> + <tr> + <td><b>Macro</b></td> + <td><b>Meaning</b></td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> +</table> +<h2><a name="lib-defined-public"></a>Public Library Defined Macros</h2> +<p>These macros are defined by {{library}} but are expected to be used by application + code.</p> +<table summary="public library defined macros" cellspacing="10" width="100%"> + <tr> + <td><b>Macro</b></td> + <td><b>Meaning</b></td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> +</table> +<h2><a name="lib-defined-impl"></a>Library Defined Implementation Macros</h2> +<p>These macros are defined by {{library}} and are implementation details of interest + only to implementers.</p> +<table summary="library defined implementation macros" cellspacing="10" width="100%"> + <tr> + <td><b>Macro</b></td> + <td><b>Meaning</b></td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> + <tr> + <td>{{macro}}</td> + <td>{{meaning}}</td> + </tr> +</table> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/definitions.html b/more/writingdoc/template/definitions.html new file mode 100644 index 0000000000..beceb12ed7 --- /dev/null +++ b/more/writingdoc/template/definitions.html @@ -0,0 +1,47 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Definitions</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Definitions</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#definitinos">Definitions</a></dt> + <dl class="page-index"> + <dt><a href="#definition-term1">Term 1</a></dt> + <dt><a href="#definition-term2">Term 2</a></dt> + </dl> +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p>{{Introductory text}}</p> +<h2><a name="definitions"></a>Definitions</h2> +<dl class="definitions"> + <dt><a name="definition-term1"></a><b>{{term}}:</b> {{definition}}</dt> + <dt><a name="definition-term2"></a><b>{{term}}:</b> {{definition}}</dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/faq.html b/more/writingdoc/template/faq.html new file mode 100644 index 0000000000..d214df9cd9 --- /dev/null +++ b/more/writingdoc/template/faq.html @@ -0,0 +1,38 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - FAQ</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Frequently Asked Questions (FAQs)</h2> + </td> + </tr> +</table> +<hr> +<dl class="page-index"> + <dt><a href="#question1">{{question}}</a></dt> + <dt><a href="#question2">{{question}}</a></dt> +</dl> +<h2><a name="question1"></a>{{question}}</h2> +<p>{{answer}}</p> +<h2><a name="question2"></a>{{question}}</h2> +<p>{{answer}}</p> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/header.html b/more/writingdoc/template/header.html new file mode 100644 index 0000000000..3e12586e28 --- /dev/null +++ b/more/writingdoc/template/header.html @@ -0,0 +1,195 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{library}} - Header <{{header}}></title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{library}}</h1> + <h2 align="center">Header <{{header}}></h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#macros">Macros</a></dt> + <dl class="page-index"> + <dt><a href="#macro-spec">{{macro name}}</a></dt> + </dl> + <dt><a href="#values">Values</a></dt> + <dl class="page-index"> + <dt><a href="#value-spec">{{value name}}</a></dt> + </dl> + <dt><a href="#types">Types</a></dt> + <dl class="page-index"> + <dt><a href="#type-spec">{{type name}}</a></dt> + </dl> + <dt><a href="#classes">Classes</a></dt> + <dl class="page-index"> + <dt><a href="#class-spec">Class <code>{{class name}}</code></a></dt> + <dl class="page-index"> + <dt><a href="#class-spec-synopsis">Class <code>{{class name}}</code> synopsis</a></dt> + <dt><a href="#class-spec-ctors">Class <code>{{class name}}</code> constructors and destructor</a></dt> + <dt><a href="#class-spec-comparisons">Class <code>{{class name}}</code> comparison functions</a></dt> + <dt><a href="#class-spec-modifiers">Class <code>{{class name}}</code> modifier functions</a></dt> + <dt><a href="#class-spec-observers">Class <code>{{class name}}</code> observer functions</a></dt> + <dt><a href="#class-spec-statics">Class <code>{{class name}}</code> static functions</a></dt> + </dl> + </dl> + <dt><a href="#functions">Functions</a></dt> + <dl class="page-index"> + <dt><a href="#function-spec">{{function name}}</a></dt> + </dl> + <dt><a href="#objects">Objects</a></dt> + <dl class="page-index"> + <dt><a href="#object-spec">{{object name}}</a></dt> + </dl> + <dt><a href="#examples">Example(s)</a></dt> +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p>{{Introductory text}}</p> +<h2><a name="macros"></a>Macros</h2> +<p><a name="macro-spec"></a>{{Macro specifications}}</p> +<h2><a name="values"></a>Values</h2> +<p><a name="value-spec"></a>{{Value specifications}}</p> +<h2><a name="types"></a>Types</h2> +<p><a name="type-spec"></a>{{Type specifications}}</p> +<h2><a name="classes"></a>Classes</h2> +<h3><a name="class-spec"></a>Class <code>{{class name}}</code></h3> +<p>{{class overview text}}</p> +<h4><a name="class-spec-synopsis"></a>Class <code>{{class name}}</code> synopsis</h4> +<pre> +namespace boost +{ + class {{class name}} + { + }; +}; +</pre> +<h4><a name="class-spec-ctors"></a>Class <code>{{class name}}</code> constructors and destructor</h4> +<pre> +{{constructor}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<pre> +{{destructor}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h4><a name="class-spec-comparisons"></a>Class <code>{{class name}}</code> comparison functions</h4> +<pre> +{{function}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h4><a name="class-spec-modifiers"></a>Class <code>{{class name}}</code> modifier functions</h4> +<pre> +{{function}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h4><a name="class-spec-observers"></a>Class <code>{{class name}}</code> observer functions</h4> +<pre> +{{function}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h4><a name="class-spec-statics"></a>Class <code>{{class name}}</code> static functions</h4> +<pre> +{{function}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h2><a name="functions"></a>Functions</h2> +<pre> +<a name="function-spec"></a>{{function}} +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> {{text}}</dt> + <dt><b>Effects:</b> {{text}}</dt> + <dt><b>Postconditions:</b> {{text}}</dt> + <dt><b>Returns:</b> {{text}}</dt> + <dt><b>Throws:</b> {{text}}</dt> + <dt><b>Complexity:</b> {{text}}</dt> + <dt><b>Note:</b> {{text}}</dt> + <dt><b>Danger:</b> {{text}}</dt> + <dt><b>Rationale:</b> {{text}}</dt> +</dl> +<h2><a name="objects"></a>Objects</h2> +<p><a name="object-spec"></a>{{Object specifications}}</p> +<h2><a name="examples"></a>Example(s)</h2> +<p>{{Example(s)}}</p> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/index.html b/more/writingdoc/template/index.html new file mode 100644 index 0000000000..13b5dcb7dd --- /dev/null +++ b/more/writingdoc/template/index.html @@ -0,0 +1,70 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}}</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Index</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="overview.html">Overview</a></dt> + <dt>Reference</dt> + <dl class="index"> + <dt><a href="header.html">{{header}}</a></dt> + <dl class="index"> + <dt><a href="header.html#macros">Macros</a></dt> + <dl class="index"> + <dt><a href="header.html#macro-spec">{{macro name}}</a></dt> + </dl> + <dt><a href="header.html#values">Values</a></dt> + <dl class="index"> + <dt><a href="header.html#value-spec">{{value name}}</a></dt> + </dl> + <dt><a href="header.html#types">Types</a></dt> + <dl class="index"> + <dt><a href="header.html#value-spec">{{type name}}</a></dt> + </dl> + <dt><a href="header.html#classes">Classes</a></dt> + <dl class="index"> + <dt><a href="header.html#value-spec">{{class name}}</a></dt> + </dl> + <dt><a href="header.html#functions">Functions</a></dt> + <dl class="index"> + <dt><a href="header.html#value-spec">{{function name}}</a></dt> + </dl> + <dt><a href="header.html#objects">Objects</a></dt> + <dl class="index"> + <dt><a href="header.html#value-spec">{{object name}}</a></dt> + </dl> + </dl> + </dl> + <dt><a href="configuration.html">Configuration Information</a></dt> + <dt><a href="rationale.html">Rationale</a></dt> + <dt><a href="definitions.html">Definitions</a></dt> + <dt><a href="faq.html">Frequently Asked Questions (FAQs)</a></dt> + <dt><a href="bibliography.html">Bibliography</a></dt> + <dt><a href="acknowledgments.html">Acknowledgments</a></dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/overview.html b/more/writingdoc/template/overview.html new file mode 100644 index 0000000000..789e475bcb --- /dev/null +++ b/more/writingdoc/template/overview.html @@ -0,0 +1,47 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Overview</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Overview</h2> + </td> + </tr> +</table> +<hr> +<dl class="index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#topic1">First topic</a></dt> + <dt><a href="#topic2">Second topic</a></dt> + <dt><a href="#footnotes">Footnotes</a></dt> +</dl> +<h2><a name="introduction"></a>Introduction</h2> +<p>{{text}}</p> +<h2><a name="topic1"></a>First Topic</h2> +<p>{{text}}</p> +<h2><a name="topic2"></a>Second Topic</h2> +<p>{{text}}</p> +<h2><a name="footnotes"></a>Footnotes</h2> +<dl> + <dt><a name="footnote1" class="footnote">(1)</a> {{text}}</dt> + <dt><a name="footnote2" class="footnote">(2)</a> {{text}}</dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/more/writingdoc/template/rationale.html b/more/writingdoc/template/rationale.html new file mode 100644 index 0000000000..8116ee9163 --- /dev/null +++ b/more/writingdoc/template/rationale.html @@ -0,0 +1,47 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<link rel="stylesheet" type="text/css" href="../../../boost.css"> +<title>{{Library}} - Rationale</title> +</head> +<body link="#0000ff" vlink="#800080"> +<table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center">{{Library}}</h1> + <h2 align="center">Rationale</h2> + </td> + </tr> +</table> +<hr> +<dl class="index"> + <dt><a href="#introduction">Introduction</a></dt> + <dt><a href="#topic1">First topic</a></dt> + <dt><a href="#topic2">Second topic</a></dt> + <dt><a href="#footnotes">Footnotes</a></dt> +</dl> +<h2><a name="introduction"></a>Introduction</h2> +<p>{{text}}</p> +<h2><a name="topic1"></a>First Topic</h2> +<p>{{text}}</p> +<h2><a name="topic2"></a>Second Topic</h2> +<p>{{text}}</p> +<h2><a name="footnotes"></a>Footnotes</h2> +<dl> + <dt><a name="footnote1" class="footnote">(1)</a> {{text}}</dt> + <dt><a name="footnote2" class="footnote">(2)</a> {{text}}</dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 05 November, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="mailto:{{address}}">{{author}}</a> + 2002. All Rights Reserved.</i></p> +</body> +</html> diff --git a/people/aleksey_gurtovoy.htm b/people/aleksey_gurtovoy.htm new file mode 100644 index 0000000000..94c5237d6c --- /dev/null +++ b/people/aleksey_gurtovoy.htm @@ -0,0 +1,45 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Aleksey Gurtovoy</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/aleksey_gurtovoy.jpg"><img border="0" src="http://boost.sourceforge.net/photos/aleksey_gurtovoy_small.jpg" alt="http://boost.sourceforge.net/photos/aleksey_gurtovoy.jpg (12871 bytes)" align="left" hspace="10" vspace="5" width="100" height="120"></a></p> + <p>Aleksey Gurtovoy is just a one Russian guy from Siberia, who now lives and + works in the United States. He is a technical lead in a small software company <a href="http://www.meta-comm.com"> + MetaCommunications</a>, a job and people which have taught him so much.</p> + <p>He was born in early 1977, has been in love with computers since 1989, and + still has a lot of (exciting) ideas for his "spare time" in the next + few years. The first computer he worked with was DEC PDP-11, and he still has a + kind of nostalgia about this amazing machine. He graduated with honors from + Krasnoyarsk Technical State University in 1998 with a Master Degree in Computer + Science.</p> + <p>While being acknowledged as a talented programmer, Aleksey tries to be a + better engineer than he is now and hopes that reading good books will help him + with that task. He reads a lot... One of his favorite books about his + profession is 'The Mythical Man-Month' by Frederic P. Brooks, Jr.</p> + <p>He has been working with C++ since 1993, he loves the language and wants to be + involved in its progress. Sometimes you can come across his articles in the <a href="news:comp.lang.c++.moderated"> + comp.lang.c++.moderated</a> and <a href="news:comp.std.c++">comp.std.c++</a><a> + newsgroups. The other numerous things Aleksey is interested in include + patterns, object-oriented methodology and programming languages, organization + of software development process and tools & technologies which make + programmer's life easier (e.g. compilers).</p> + <p>He is not married, but he has in mind one great girl he hopes to be with + someday.</p> + <p>You can contact him by sending mail to </a><a href="mailto:alexy@meta-comm.com">alexy@meta-comm.com</a><a>.</p> + </a> + </body> +</html> diff --git a/people/beman_dawes.html b/people/beman_dawes.html new file mode 100644 index 0000000000..0b4967dc8e --- /dev/null +++ b/people/beman_dawes.html @@ -0,0 +1,32 @@ +<html> + <head> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Beman Dawes</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/beman_dawes.jpg"><img src="http://boost.sourceforge.net/photos/beman_dawes_small.jpg" alt="http://boost.sourceforge.net/photos/beman_dawes.jpg (62536 bytes)" border="0" align="left" hspace="10" vspace="5" width="100" height="133"></a> + Beman Dawes is a software developer from Virginia in the United States and the + founder of boost.org.</p> + <p>He is the author of the StreetQuick® geographic atlas library used by digital + map publishers to help people get really, really, lost.</p> + <p>He wrote his first computer program 40 years ago, and does not mourn the + passing of <a href="http://www.mta.ca/~amiller/ibm650/ibm650.htm">bi-quinary</a> + arithmetic.</p> + <p>Beman has been a voting member of the ANSI/ISO C++ Standards Committee since + 1992, and chaired the Library Working Group for five years.</p> + <p>He enjoys travel, sailing, hiking, and biking. He is married, and he and his + wife have three cats.</p> + <p>Email: <a href="mailto:bdawes@acm.org">bdawes@acm.org</a></p> + </body> +</html> diff --git a/people/darin_adler.htm b/people/darin_adler.htm new file mode 100644 index 0000000000..21afdcd7fc --- /dev/null +++ b/people/darin_adler.htm @@ -0,0 +1,46 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Darin Adler</title> + </head> + <body> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/darin_adler.jpg"><img border="0" + src="http://boost.sourceforge.net/photos/darin_adler_small.jpg" + alt="http://boost.sourceforge.net/photos/darin_adler.jpg (30416 bytes)" align="left" hspace="10" vspace="5" width="100" height="135"></a>Darin + Adler has been programming computers since 1976. He loves to do it.</p> + <p>His first major professional experience was at <a href="http://apple.com">Apple + Computer</a>. In 1988 he led the team that rewrote the Macintosh Finder in + C++. Before that project was completed, he was shanghaied to be the technical + lead for the System 7 project (these days they would call it "Mac OS + 7"). The group he formed to help him do that, the Blue Meanies, is still a <a href="http://www.spies.com/~greg/bluemeanies.html"> + legend</a> in the Apple community.</p> + <p>Since Apple, Darin has worked at <a href="http://www.generalmagic.com">General + Magic</a> as an architect of the <a href="http://www.google.com/search?q=Magic+Cap"> + Magic Cap</a> OS, used the moniker <a href="http://bentspoon.com">Bent Spoon + Software</a> to do consulting, and helped start Eazel, a company that worked + to make Linux easier to use and developed the Nautilus graphical shell for <a href="http://www.gnome.org"> + GNOME</a>. Since 1997, he has worked from his home in Los Angeles, CA, + collaborating with clients and coworkers in other locations.</p> + <p>He prefers to use and program Macintosh computers with C++. But work on the + GNOME project is best accomplished with a non-Macintosh PC. (That's why Darin + is sitting in front of <a href="darin_adler.jpg">two computers</a>.) The other + people working on the GNOME project don't like C++, so he's writing a lot of C + code these days.</p> + <p>The <a href="darin_adler.jpg">larger version</a> of his picture shows him hard + at work with his C++ guru, his daughter Sophia.</p> + <p>He has hobbies and stuff but you don't want to read about that here.</p> + <p>You can contact him by sending mail to <a href="mailto:darin@bentspoon.com">darin@bentspoon.com</a>.</p> + </body> +</html> diff --git a/people/daryle_walker.html b/people/daryle_walker.html new file mode 100644 index 0000000000..96a94cd209 --- /dev/null +++ b/people/daryle_walker.html @@ -0,0 +1,22 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<html> + <head> + <title>Daryle Walker</title> + </head> + <body bgcolor="white" text="black"> + <table border="1" bgcolor="teal" cellpadding="2"> + <tr> + <td bgcolor="white"><img src="../c++boost.gif" alt="c++boost.gif + (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="white"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="white"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="white"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="white"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="white"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/daryle_walker.jpg"><img src="http://boost.sourceforge.net/photos/daryle_walker.jpg" alt="http://boost.sourceforge.net/photos/daryle_walker.jpg (3618 bytes)" border="0" align="left" hspace="10" vspace="5" width="100" height="127"></a> + Daryle Walker, born and raised in the United States since 1973, needs to write + a fuller biography.</p> + </body> +</html> diff --git a/people/dave_abrahams.htm b/people/dave_abrahams.htm new file mode 100644 index 0000000000..02a24fc5b8 --- /dev/null +++ b/people/dave_abrahams.htm @@ -0,0 +1,34 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Dave Abrahams</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif + (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/dave_abrahams.jpg"> + <img src="http://boost.sourceforge.net/photos/dave_abrahams_small.jpg" + alt="dave_abrahams.jpg (30926 bytes)" border="0" align="left" hspace="10" vspace="5" width="100" height="75"></a> + <a href="mailto:dave@boost-consulting.com">Dave Abrahams</a> is a founding + member and moderator of Boost, and an active member of the wider open-source + community. He has been an ANSI/ISO C++ committee member since 1996, and has + worked in the software industry since 1988. In 2001 He founded <a href="http://www.boost-consulting.com"> + Boost Consulting</a> + , a company dedicated to providing professional support and development + services for the Boost C++ libraries and associated tools. + <p> + Dave often shows up at C++ standards committee meetings on a bicycle. He lives + in Somerville, Massachusetts with his beautiful wife, Luann.</p> + </body> +</html> diff --git a/people/dietmar_kuehl.htm b/people/dietmar_kuehl.htm new file mode 100644 index 0000000000..13e11a432c --- /dev/null +++ b/people/dietmar_kuehl.htm @@ -0,0 +1,48 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>Dietmar Kuehl </title> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" WIDTH="277" HEIGHT="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/dietmar_kuehl.jpg"><img src="http://boost.sourceforge.net/photos/dietmar_kuehl_small.jpg" hspace="10" vspace="5" alt="dietmar_kuehl.jpg (57821 bytes)" border="0" align="left" WIDTH="100" HEIGHT="133"></a>Dietmar + Kuehl (the "ue" is actually a "u-umlaut", ie. one of those + funny German characters which has two dots above it) was fork(2)ed in early + 1968.</p> + <p>He visited school more or less successfully from 1973 to 1987. In 1987 he + started to study at the Technical University of Berlin. He finished his studies + in 1997 with a Diplom (roughly the German equivalent of a masters) in + Mathematics. His thesis was "Design Pattern for the Implementation of + Graph Algorithms"; strike the "Design Pattern" and put in + "Generic" somehow to get an idea of the main topic. The thesis is + available from <a href="ftp://ftp.informatik.uni-konstanz.de/pub/algo/personal/kuehl/da.ps.gz"> + ftp://ftp.informatik.uni-konstanz.de/pub/algo/personal/kuehl/da.ps.gz</a>.</p> + <p>Since 1997 he has worked as consultant for a small company called Claas + Solutions (the "aa" is no typo), mainly working for major German + banks. Since late 1995 Dietmar Kuehl has been one of the moderators of the + newsgroup <a href="news:comp.lang.c++.moderated">comp.lang.c++.moderated</a>. + He is active on the C++ Standards committee.</p> + <p>Email: <a href="mailto:dietmar.kuehl@claas-solutions.de">dietmar.kuehl@claas-solutions.de</a></p> + <p>Home page: <a href="http://www.claas-solutions.de/kuehl/">http://www.claas-solutions.de/kuehl/</a></p> + </body> +</html> diff --git a/people/doug_gregor.html b/people/doug_gregor.html new file mode 100644 index 0000000000..46b3f71324 --- /dev/null +++ b/people/doug_gregor.html @@ -0,0 +1,35 @@ +<html> + <head> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Doug Gregor</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/doug_gregor.jpg"><img src="http://boost.sourceforge.net/photos/doug_gregor_small.jpg" alt="doug_gregor.jpg (62536 bytes)" border="0" align="left" hspace="10" vspace="5" width="100" height="133"></a> + <p>Doug is a PhD student in the <a href="http://www.cs.rpi.edu">Computer Science</a> + department at <a href="http://www.rpi.edu">Rensselaer Polytechnic Institute</a> + (no, it's not in Rochester), where it is rumored that early alpha versions of + the Standard Template Library were inflicted upon unwitting Freshman... + <p>As a generic programming zealot, his search for the One True Generic Language + has brought him to the <a href="http://www.cs.rpi.edu/research/gpg">Generic + Programming Group</a>, where much of his time is devoted to research in <a href="http://www.cs.rpi.edu/research/gpg/Simplicissimus"> + high-level compiler optimizers</a> + for the C++ language. + <p> + When not hunched over in front of an <a href="http://www.xemacs.org">XEmacs</a> + window, Doug looks to his wife Amy to help him navigate through the daylight. + Once there, he enjoys tennis and the occasional game of paintball. + <p>Email: <a href="mailto:gregod@cs.rpi.edu">gregod@cs.rpi.edu</a></p> + <p>Home page: <a href="http://www.cs.rpi.edu/~gregod"><code>http://www.cs.rpi.edu/~gregod</code></a> + </body> +</html> diff --git a/people/ed_brey.htm b/people/ed_brey.htm new file mode 100644 index 0000000000..57ea57c3e7 --- /dev/null +++ b/people/ed_brey.htm @@ -0,0 +1,45 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Ed Brey</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/ed_brey.jpg"><img src="http://boost.sourceforge.net/photos/ed_brey_small.jpg" alt="ed_brey.jpg" border="0" align="left" hspace="10" vspace="5" width="100" height="133"></a> + Ed Brey lives in Menomonee Falls, Wisconsin, a village outside of Milwaukee. In + the summertime, he likes to play tennis with his wife, and in the winter, if + there is enough snow, he likes to go tobogganing or ice-skating. If it is not + nice enough outside for either of those, he plays on the piano. + <p>Ed works at <a href="http://www.eaton.com">Eaton Corporation</a> in Milwaukee. + He started working there as part of <a href="http://www.mu.edu">Marquette + University</a>'s engineering co-op program. Upon graduation in 1995 from + Marquette with a BS in electrical and computer engineering, he was hired on + full-time, where he initially worked on firmware for industrial controls. More + recently, he has been working on a PC-based configuration tool for industrial + networks. Ed received his MS in computer engineering in 2001 from <a href="http://www.ntu.edu"> + NTU</a> + . + <p> + Ed has held programming as a pastime since his grade school days, when he wrote + a babysitting invoicing program. Soon after, he wrote a game inspired by the TV + game show “Press Your Luck”. Ever since, programming languages and + concepts, along with finding ways to improve the art and science of coding + software, have always peeked his interest. + <p>Lastly, Ed has managed to retain his perspective. As fun as computers and + programming are, Ed's true loves in life are the Lord Jesus whom he serves and + his dear wife Beth.</p> + <hr> + <p>Home page: <a href="http://BreyFamily.net">http://BreyFamily.net</a> + </body> +</html> diff --git a/people/gary_powell.htm b/people/gary_powell.htm new file mode 100644 index 0000000000..d28aafa658 --- /dev/null +++ b/people/gary_powell.htm @@ -0,0 +1,30 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Gary Powell</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/gary_powell.jpg"><img border="0" src="http://boost.sourceforge.net/photos/gary_powell_small.jpg" alt="gary_powell.jpg (13577 bytes)" align="left" hspace="10" vspace="5" width="100" height="133"></a>Gary + Powell has been messing around with C++ since '87 when he dreamed about adding + his own operators to the language. Since then he's been busy overloading + everything in sight, and working on bringing functional programming to C++.</p> + <p>He currently works for Sierra On-line <a href="http://www.sierra.com">http://www.sierra.com</a> + a division of Havas Interactive, a wholly owned subsidiary of Vivedi Universal + of France, <a href="http://www.vivendi.com">http://www.vivendi.com</a> as a + game programmer where he writes AI.</p> + <p>He can be reached at <a href="mailto:gary.powell@sierra.com">gary.powell@sierra.com</a> + but don't ask him how to solve the riddle of the left handed troll.</p> + </body> +</html> diff --git a/people/greg_colvin.htm b/people/greg_colvin.htm new file mode 100644 index 0000000000..d115fb1196 --- /dev/null +++ b/people/greg_colvin.htm @@ -0,0 +1,34 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>Greg Colvin</title> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" WIDTH="277" HEIGHT="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/greg_colvin.jpg"><img src="http://boost.sourceforge.net/photos/greg_colvin_small.jpg" alt="greg_colvin.jpg (52k bytes)" border="0" align="left" hspace="10" vspace="5" WIDTH="100" HEIGHT="133"></a> + Dr. Greg Colvin has been hacking happily since 1972. He is a member of the + ANSI/ISO C++ standards committee and a Principal Member of Technical Staff with + the Java Products Group at Oracle Corporation. In his spare time he plays + apocalyptic electric blues guitar in his Colorado, USA home studio.</p> + </body> +</html> diff --git a/people/howard_hinnant.htm b/people/howard_hinnant.htm new file mode 100644 index 0000000000..a825be7022 --- /dev/null +++ b/people/howard_hinnant.htm @@ -0,0 +1,38 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Howard Hinnant</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/howard_hinnant.jpg"><img border="0" src="http://boost.sourceforge.net/photos/howard_hinnant_small.jpg" align="left" hspace="10" vspace="5" alt="howard_hinnant.jpg (19817 bytes)" width="100" height="97"></a>When + Howard Hinnant is not monkeying around, he is the principal author of the + Metrowerks CodeWarrior C++ library. He is also a member of the C++ Standards + committee.</p> + <p>Howard is married with four children, two dogs, one cat, a rabbit, an + undetermined number of rodents (which the cat ignores), and ... well, we're + really not sure what else. When not sitting in front of his computer, Howard + enjoys snow skiing and ... more, snow skiing.</p> + </body> +</html> diff --git a/people/hubert_holin.html b/people/hubert_holin.html new file mode 100644 index 0000000000..407fec9968 --- /dev/null +++ b/people/hubert_holin.html @@ -0,0 +1,46 @@ +<html> + <head> + <title>Hubert Holin</title> + <meta http-equiv="generator" content="Adobe GoLive 5"> + <meta http-equiv="content-type" content="text/html;charset=ISO-8859-1"> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" WIDTH="277" HEIGHT="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/hubert_holin.jpg"><img src="http://boost.sourceforge.net/photos/hubert_holin_small.jpg" width="100" height="120" border="0" align="left"></a>Hubert + Holin is a mathematician. He is currently a civil servant of the french state + (no longer indentured, but still stuck). He has also worked as a developper in + a small french start-up , and as a math teacher in a private non-religious + higher-ed school.</p> + <p>His first programs were in assembly language/micro-code on an Hewlett-Packard <a href="http://www.hpmuseum.org/hp25.htm"> + HP 25</a> hand-held calculator (a marked improvement over his father's use of + binary-on-strips-of-paper on some forgoten piece of metal...), back in the + mists of time. He is a Mac-using refugee of the Atari, and on a personal jihad + against The Evil Empire Of Computing ™.</p> + <p>Very much a Child of the World, he has lived in Europe, Africa, the U.S.A., + and is married with a chinese girl (with whom he has both a daughter and a + son).</p> + <p></p> + <hr> + <p>Email: <a href="mailto:Hubert.Holin@Bigfoot.com">Hubert.Holin@Bigfoot.com</a></p> + <p>Home page: <a href="http://www.Bigfoot.com/~Hubert.Holin">http://www.Bigfoot.com/~Hubert.Holin</a></p> + </body> +</html> diff --git a/people/jaakko_jarvi.htm b/people/jaakko_jarvi.htm new file mode 100644 index 0000000000..72faa90e3e --- /dev/null +++ b/people/jaakko_jarvi.htm @@ -0,0 +1,29 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Jaakko Järvi</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/jaakko_jarvi.jpg"><img border="0" src="http://boost.sourceforge.net/photos/jaakko_jarvi_small.jpg" alt="jaakko_jarvi.jpg (25365 bytes)" align="center" hspace="10" vspace="5" width="100" height="82"></a></p> + <p>Jaakko Järvi is currently a researcher (Post doc) at the <a href="http://www.tucs.abo.fi/"> + Turku Centre for Computer Science</a> in Turku, Finland.<br> + <br> + He's the author of the <a href="../libs/tuple/doc/tuple_users_guide.html">Tuple + Library</a> and co-author of the Lambda Library.<br> + <br> + He can be reached at <a href="mailto:jaakko.jarvi@cs.utu.fi">jaakko.jarvi@cs.utu.fi</a>. + </p> + </body> +</html> diff --git a/people/jens_maurer.htm b/people/jens_maurer.htm new file mode 100644 index 0000000000..1575456538 --- /dev/null +++ b/people/jens_maurer.htm @@ -0,0 +1,34 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Jens Maurer</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/jens_maurer.jpg"><img border="0" src="http://boost.sourceforge.net/photos/jens_maurer_small.jpg" alt="jens_maurer.jpg (15698 bytes)" hspace="10" vspace="5" align="left" width="100" height="124"></a> + Jens Maurer is a software developer from Germany who lives close to + Frankfurt/Main. He was born in 1973 and hasn't died yet.</p> + <p>He has worked for a multimedia company programming home-banking applications, + CGI scripts and Java applications. He also helped program some simulation + systems for long-term decision support to aid businessmen in arguing about + company investments.</p> + <p>He is neither married nor does he have a girl friend, but asked his colleagues + to find one for him.</p> + <p>In his spare time, he likes visiting foreign countries but dislikes getting + there in uncomfortable airplane seats. On random week-ends, he enjoys + participating in historic dance courses (without a costume, of course). + Sometimes, he needs fresh air and goes for a walk. </p> + <p>Email: <a href="mailto:Jens.Maurer@gmx.net">Jens.Maurer@gmx.net</a></p> + </body> +</html> diff --git a/people/jeremy_siek.htm b/people/jeremy_siek.htm new file mode 100644 index 0000000000..81f2e3f85b --- /dev/null +++ b/people/jeremy_siek.htm @@ -0,0 +1,42 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Jeremy Siek</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/jeremy_siek.jpg"><img border="0" src="http://boost.sourceforge.net/photos/jeremy_siek_small.jpg" alt="jeremy_siek.jpg (12867 bytes)" align="left" hspace="10" vspace="5" width="100" height="133"></a>Jeremy + Siek is a Ph.D. student at Indiana Univ. Bloomington.<br> + <br> + He is the author of the Matrix Template Library (MTL), and helped design the + Generic Graph Component Library, which is now the Boost Graph Library (BGL).<br> + <br> + Once in a while Jeremy "comes up for air" and enjoys fencing, hiking, skiing, + and reading. He's also been spotted at a few fightin' irish tailgaters (BYOB).<br> + <br> + Jeremy has an intense fear for the ancient dark forests where dusty decks + thrive and devour programmers, places where the light of abstraction has not + yet reached.</p> + </body> +</html> diff --git a/people/john_maddock.htm b/people/john_maddock.htm new file mode 100644 index 0000000000..6a014956c2 --- /dev/null +++ b/people/john_maddock.htm @@ -0,0 +1,34 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> + <title>John Maddock</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" face="Arial">Home </font></a> + </td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" size="4" face="Arial">Libraries + </font></a> + </td> + <td><a href="people.htm"><font color="#FFFFFF" size="4" face="Arial">People </font></a> + </td> + <td><a href="../more/faq.htm"><font color="#FFFFFF" size="4" face="Arial">FAQ </font> + </a> + </td> + <td><a href="../more/index.htm"><font color="#FFFFFF" size="4" face="Arial">More </font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/john_maddock.jpg"><img src="http://boost.sourceforge.net/photos/john_maddock_small.jpg" alt="john_maddock.jpg (14611bytes)" align="left" border="0" hspace="10" vspace="5" width="100" height="133"></a> + John Maddock is a software developer from England and holds a PhD in Chemistry, + but found that computers smell less and explode less often!</p> + <p>John is the author of the <a href="http://ourworld.compuserve.com/homepages/John_Maddock/regexpp.htm"> + regex++ regular expression package</a>, has an almost pathological interest + in anything that "can't be done", and can be contacted at <a href="mailto:John_Maddock@compuserve.com"> + John_Maddock@compuserve.com</a>.</p> + </body> +</html> diff --git a/people/kevlin_henney.htm b/people/kevlin_henney.htm new file mode 100644 index 0000000000..a28990c38a --- /dev/null +++ b/people/kevlin_henney.htm @@ -0,0 +1,55 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Kevlin Henney</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font> + </a> + </td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big> + </font></a> + </td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font> + </a> + </td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font> + </a> + </td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font> + </a> + </td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/kevlin_henney.jpg"><img border="0" src="http://boost.sourceforge.net/photos/kevlin_henney_small.jpg" alt="kevlin_henney.jpg (18107 bytes)" align="left" hspace="10" vspace="5" width="100" height="142"></a> + Kevlin Henney (<a href="mailto:kevlin@curbralan.com">mailto:kevlin@curbralan.com</a>, + <a href="http://www.curbralan.com">http://www.curbralan.com</a>) is an + independent consultant and trainer based in the UK. He has developed and + delivered training course material and consultancy on many aspects of OO + development, which he has practiced across a number of domains for longer than + he cares (or can) remember. His professional interests include patterns, OO and + component-based design, architecture, distributed object systems, and + languages, including C++, C#, Java, and Ruby. He is also a member of the BSI + C++ standards committee. + </p> + <p>Now that writing code is no longer the core responsibility of his job, his + non-professional interests seem to include the hacking associated with the + aforementioned professional interests. However, never being one to keep + something to himself (like C++'s relationship with C, this is regarded as both + a strength and a weakness), he shares/inflicts (delete as necessary) his + professional and non-professional development experiences with/on (ditto) + others through writing articles and presenting tutorials, workshops and papers + at conferences.</p> + <p>He is married, and not just to his work. He and Carolyn have one child, + Stefan. The little spare time that remains to him is taken up with music, + reading, pub appreciation, etc. Although with a newborn, there is more reading + and less pub appreciation (pubs are still appreciated, but more in memory than + in interaction). Finally, although he enjoys writing, Kevlin is not + really one for writing in the third person.</p> + </body> +</html> diff --git a/people/liequan_lee.htm b/people/liequan_lee.htm new file mode 100644 index 0000000000..a4cec4bc36 --- /dev/null +++ b/people/liequan_lee.htm @@ -0,0 +1,28 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Lie-Quan Lee</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + + <p><a href="http://boost.sourceforge.net/photos/liequan_lee.jpg"><img border="0" src="http://boost.sourceforge.net/photos/liequan_lee_small.jpg" alt="liequan_lee.jpg (24165 bytes)" hspace="10" vspace="5" width="93" height="133" align="left"></a>Lie-Quan + Lee, AKA Rich Lee, is a graduate stduent in Computer Science at University of + Notre Dame. He is the author of the Generic Graph Component Library (GGCL).</p> + <p>He has a strong desire of learning to disassemble and assemable any electrical + appliances. He likes playing bridge but never had a chance to play it after he + entered the wonderful world of computers.</p> + <p>He can be contacted at llee1@lsc.nd.edu.</p> + </body> +</html> diff --git a/people/mac_murrett.htm b/people/mac_murrett.htm new file mode 100644 index 0000000000..3d00c4c5e0 --- /dev/null +++ b/people/mac_murrett.htm @@ -0,0 +1,27 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <title>Mac Murrett</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/mac_murrett.jpg"><img border="0" src="http://boost.sourceforge.net/photos/mac_murrett_small.jpg" alt="mac_murrett.jpg (19542 bytes)" align="left" hspace="10" vspace="5" width="100" height="135"></a> + Mac Murrett is an Advanced Developer at <a href="http://www.vanteon.com/">Vanteon</a>. + He lives in Rochester, NY, where everything closes at 10 PM. This gives him + plenty of time to think.</p> + <p>Mac graduated from SUNY: University at Buffalo with a degree in Mathematics. + He has been programming Macintoshes since he was 12 years old, and recently won <a href="http://www.hax.com/MacHack/HackContest.html"> + the Best Hack Contest</a> at <a href="http://www.machack.com/">MacHack 2001<a />. + Nonetheless, he swears up and down that his name has nothing to do with the + computer.</p> + </body> +</html> diff --git a/people/mark_rodgers.htm b/people/mark_rodgers.htm new file mode 100644 index 0000000000..97402e3964 --- /dev/null +++ b/people/mark_rodgers.htm @@ -0,0 +1,33 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Mark Rodgers</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/mark_rodgers.jpg"><img border="0" src="http://boost.sourceforge.net/photos/mark_rodgers_small.jpg" alt="mark_rodgers.jpg (23035 bytes)" align="left" hspace="10" vspace="5" width="100" height="75"></a>Mark + Rodgers lives in <a href="http://www.wcc.govt.nz/wellington/">Wellington</a>, + the capital of <a href="http://www.govt.nz/aboutnz/profile.php3">New Zealand</a>, + with his wife, Clare, and their son, Ronnie.</p> + <p>He studied Computer Science at <a href="http://www.vuw.ac.nz">Victoria + University of Wellington</a> from 1983 to 1986, completing a <nobr>B.Sc. + (Hons).</nobr> He now works as consultant through his company, Cadenza New + Zealand Ltd, and also markets Cadenza Drawing Board™, a CAD system he + developed.</p> + <p>Mark has been programming in C++ since about 1990, and loves every minute of + it, but is continually amazed at how much more he still has to learn.</p> + <p>You can contact Mark at <a href="mailto:mark.rodgers@cadenza.co.nz">mark.rodgers@cadenza.co.nz</a> + . + </body> +</html> diff --git a/people/mat_marcus.htm b/people/mat_marcus.htm new file mode 100644 index 0000000000..9869e192c4 --- /dev/null +++ b/people/mat_marcus.htm @@ -0,0 +1,40 @@ +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <title>Mat Marcus</title> + </head> + <body bgcolor="#FFFFFF"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/mat_marcus.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/mat_marcus_small.jpg" xthumbnail-orig-image="mat_marcus.jpg" width="112" height="130" align="left" hspace="10" vspace="5"></a>Mat + Marcus is a senior computer scientist in the Advanced Technology Group at Adobe + Systems, Inc. He has been developing software since 1985. In the summer of + 2000, during a camping trip on the Washington coast, he read Czarnecki and + Eisenecker's seminal "Generative Programming" book. This opened up a + world of development possibilities beyond objects for him, and he hasn't looked + back. His first contribution to Boost followed soon afterwards; he discovered a + way to exploit the properties of the sizeof operator to simulate partial + specialization (is_pointer, etc. with Jesse Jones). + </p> + <p>A mathematician by training, Mat is amused by abstraction. In his spare + professional time he is studying algebraic specification, category theory, and + philosophy in the hopes of someday understanding and exploiting the deep + answers to the question "What is a type?". He is currently active as + Adobe's principal representative on the ANSI/ISO C++ committee. Mat also enjoys + ultimate frisbee, go, bodysurfing, and camping with his family. But above all, + he likes to laugh.</p> + <p>Mat lives in Seattle with his wife and young son (shown in large photo). + </p> + </body> +</html> diff --git a/people/paul_mensonides.htm b/people/paul_mensonides.htm new file mode 100644 index 0000000000..081f214ab4 --- /dev/null +++ b/people/paul_mensonides.htm @@ -0,0 +1,25 @@ +<html> + <head> + <title>Paul Mensonides</title> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p> + <a href="http://boost.sourceforge.net/photos/paul_mensonides.jpg"><img border="0" src="http://boost.sourceforge.net/photos/paul_mensonides_small.jpg" alt="paul_mensonides.jpg (286309 bytes)" align="left" hspace="10" vspace="5" width="100" height="131"></a> + Paul Mensonides was born on March 31 in 1977. He lives in Tacoma, + Washington. + </p> + <p> + His interests include musical composition, playing the guitar, skiing, and + programming--particularly in C and C++. + </p> + </body> +</html> diff --git a/people/paul_moore.htm b/people/paul_moore.htm new file mode 100644 index 0000000000..4ade7782bb --- /dev/null +++ b/people/paul_moore.htm @@ -0,0 +1,33 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Paul Moore</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/paul_moore.jpg"><img border="0" src="http://boost.sourceforge.net/photos/paul_moore_small.jpg" alt="paul_moore.jpg (12023 bytes)" align="left" hspace="10" vspace="5" width="100" height="81"></a>Paul + Moore lives in Cheshire, England. He is married, with one son. His "day + job" is as an Oracle DBA, but he writes C and C++ programs in his spare + time.</p> + <p>Paul started programming on Acorn's BBC Micro and RISC PC series of computers, + but finally went mainstream and bought a PC, on which he now runs Windows and + Linux. Paul's main interest is in porting and developing open-source software, + and so his main programming language is C (at least until the open source + community switches to C++).</p> + <p>Paul's main claim to C++ fame is that he owns all 3 editions of Bjarne + Stroustrup's "The C++ Programming language", plus the ARM and the C++ + standard, but he didn't own a C++ compiler until after the 3rd edition of + Stroustrup's book came out. Make of that what you will...</p> + </body> +</html> diff --git a/people/people.htm b/people/people.htm new file mode 100644 index 0000000000..d0f281a419 --- /dev/null +++ b/people/people.htm @@ -0,0 +1,151 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>Boost People</title> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <meta name="Microsoft Border" content="none, default"> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <h1>Boost People</h1> + <p>(Click on the names for biographies)<br> + (Click on the images for enlarged images)</p> + <table border="0" cellpadding="4" cellspacing="4"> + <tr> + <td><a href="dave_abrahams.htm">Dave Abrahams</a></td> + <td><a href="http://boost.sourceforge.net/photos/dave_abrahams.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/dave_abrahams_small.jpg" alt="http://boost.sourceforge.net/photos/dave_abrahams.jpg (30926 bytes)" width="100" height="75"></a></td> + </tr> + <tr> + <td><a href="darin_adler.htm">Darin Adler</a></td> + <td><a href="http://boost.sourceforge.net/photos/darin_adler.jpg"><img border="0" src="http://boost.sourceforge.net/photos/darin_adler_small.jpg" alt="http://boost.sourceforge.net/photos/darin_adler.jpg (30416 bytes)" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="ed_brey.htm">Ed Brey</a></td> + <td><a href="http://boost.sourceforge.net/photos/ed_brey.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/ed_brey_small.jpg" alt="http://boost.sourceforge.net/photos/ed_brey.jpg (13913 bytes)" width="100" height="118"></a></td> + </tr> + <tr> + <td><a href="greg_colvin.htm">Greg Colvin</a></td> + <td><a href="http://boost.sourceforge.net/photos/greg_colvin.jpg"> <img src="http://boost.sourceforge.net/photos/greg_colvin_small.jpg" alt="http://boost.sourceforge.net/photos/greg_colvin.jpg (52740 bytes)" border="0" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="beman_dawes.html">Beman Dawes</a></td> + <td><a href="http://boost.sourceforge.net/photos/beman_dawes.jpg"> <img src="http://boost.sourceforge.net/photos/beman_dawes_small.jpg" alt="http://boost.sourceforge.net/photos/beman_dawes.jpg (47863 bytes)" border="0" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="peter_dimov.htm">Peter Dimov</a></td> + <td><a href="http://boost.sourceforge.net/photos/peter_dimov.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/peter_dimov_small.jpg" alt="http://boost.sourceforge.net/photos/peter_dimov.jpg (16507 bytes)" width="100" height="131"></a></td> + </tr> + <tr> + <td><a href="ronald_garcia.htm">Ron Garcia</a></td> + <td><a href="http://boost.sourceforge.net/photos/ronald_garcia.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/ronald_garcia_small.jpg" xthumbnail-orig-image="http://boost.sourceforge.net/photos/ronald_garcia.jpg" width="92" height="133"></a></td> + </tr> + <tr> + <td><a href="doug_gregor.html">Doug Gregor</a></td> + <td><a href="http://boost.sourceforge.net/photos/doug_gregor.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/doug_gregor_small.jpg" alt="http://boost.sourceforge.net/photos/doug_gregor.jpg (30947 bytes)" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="ralf_w_grosse_kunstleve.htm">Ralf W Grosse-Kunstleve</a></td> + <td><a href="http://boost.sourceforge.net/photos/ralf_w_grosse_kunstleve.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/ralf_w_grosse_kunstleve_sm.jpg" alt="http://boost.sourceforge.net/photos/ralf_w_grosse_kunstleve.jpg (29133 bytes)" width="100" height="134"></td> + </tr> + <tr> + <td><a href="aleksey_gurtovoy.htm">Aleksey Gurtovoy</a></td> + <td><a href="http://boost.sourceforge.net/photos/aleksey_gurtovoy.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/aleksey_gurtovoy_small.jpg" alt="http://boost.sourceforge.net/photos/aleksey_gurtovoy.jpg (12871 bytes)" width="100" height="120"></a></td> + </tr> + <tr> + <td><a href="kevlin_henney.htm">Kevlin Henney</a></td> + <td><a href="http://boost.sourceforge.net/photos/kevlin_henney.jpg"><img src="http://boost.sourceforge.net/photos/kevlin_henney_small.jpg" alt="http://boost.sourceforge.net/photos/kevlin_henney.jpg (27191 bytes)" border="0" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="howard_hinnant.htm">Howard Hinnant</a></td> + <td><a href="http://boost.sourceforge.net/photos/howard_hinnant.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/howard_hinnant_small.jpg" alt="http://boost.sourceforge.net/photos/howard_hinnant.jpg (19817 bytes)" width="100" height="97"></a></td> + </tr> + <tr> + <td><a href="hubert_holin.html">Hubert Holin</a></td> + <td><a href="http://boost.sourceforge.net/photos/hubert_holin.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/hubert_holin_small.jpg" alt="http://boost.sourceforge.net/photos/hubert_holin.jpg (xxx bytes)" width="100" height="120"></a></td> + </tr> + <tr> + <td><a href="http://www.josuttis.com">Nicolai Josuttis</a></td> + <td><a href="http://boost.sourceforge.net/photos/nicolai_josuttis.jpg"> <img src="http://boost.sourceforge.net/photos/nicolai_josuttis_small.jpg" alt="http://boost.sourceforge.net/photos/nicolai_josuttis.jpg (40745 bytes)" border="0" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="jaakko_jarvi.htm">Jaakko Järvi</a></td> + <td><a href="http://boost.sourceforge.net/photos/jaakko_jarvi.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/jaakko_jarvi_small.jpg" alt="http://boost.sourceforge.net/photos/jaakko_jarvi.jpg (25365 bytes)" width="100" height="82"></a></td> + </tr> + <tr> + <td><a href="vesa_karvonen.htm">Vesa Karvonen</a></td> + <td><img border="0" src="http://boost.sourceforge.net/photos/vesa_karvonen.jpg" width="100" height="133"></td> + </tr> + <tr> + <td><a href="william_kempf.htm">William Kempf</a></td> + <td><a href="http://boost.sourceforge.net/photos/william_kempf.jpg"><img border="0" src="http://boost.sourceforge.net/photos/william_kempf_small.jpg" alt="http://boost.sourceforge.net/photos/william_kempf.jpg (10935 bytes)" width="100"></a></td> + </tr> + <tr> + <td><a href="samuel_krempp.htm">Samuel Krempp</a></td> + <td><a href="http://boost.sourceforge.net/photos/samuel_krempp.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/samuel_krempp_small.jpg" xthumbnail-orig-image="http://boost.sourceforge.net/photos/samuel_krempp.jpg" width="100" height="76"></a></td> + </tr> + <tr> + <td><a href="dietmar_kuehl.htm">Dietmar Kühl</a></td> + <td><a href="http://boost.sourceforge.net/photos/dietmar_kuehl.jpg"> <img src="http://boost.sourceforge.net/photos/dietmar_kuehl_small.jpg" alt="http://boost.sourceforge.net/photos/dietmar_kuehl.jpg (57821 bytes)" border="0" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="liequan_lee.htm">Lie-Quan Lee</a></td> + <td><a href="http://boost.sourceforge.net/photos/liequan_lee.jpg"><img border="0" src="http://boost.sourceforge.net/photos/liequan_lee_small.jpg" alt="http://boost.sourceforge.net/photos/liequan_lee.jpg (24165 bytes)" width="93" height="133"></a></td> + </tr> + <tr> + <td><a href="john_maddock.htm">John Maddock</a></td> + <td><a href="http://boost.sourceforge.net/photos/john_maddock.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/john_maddock_small.jpg" alt="http://boost.sourceforge.net/photos/john_maddock.jpg (14611 bytes)" width="100" height="132"></a></td> + </tr> + <tr> + <td><a href="mat_marcus.htm">Mat Marcus</a></td> + <td><a href="http://boost.sourceforge.net/photos/mat_marcus.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/mat_marcus_small.jpg" xthumbnail-orig-image="http://boost.sourceforge.net/photos/mat_marcus.jpg" width="95" height="133"></a></td> + </tr> + <tr> + <td><a href="jens_maurer.htm">Jens Maurer</a></td> + <td><a href="http://boost.sourceforge.net/photos/jens_maurer.jpg"><img border="0" src="http://boost.sourceforge.net/photos/jens_maurer_small.jpg" width="100" height="124"></a></td> + </tr> + <tr> + <td><a href="paul_mensonides.htm">Paul Mensonides</a></td> + <td><a href="http://boost.sourceforge.net/photos/paul_mensonides.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/paul_mensonides_small.jpg" alt="http://boost.sourceforge.net/photos/paul_mensonides.jpg (286309 bytes)" width="100" height="131"></a></td> + </tr> + <tr> + <td><a href="paul_moore.htm">Paul Moore</a></td> + <td><a href="http://boost.sourceforge.net/photos/paul_moore.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/paul_moore_small.jpg" alt="http://boost.sourceforge.net/photos/paul_moore.jpg (12023 bytes)" width="100" height="81"></a></td> + </tr> + <tr> + <td><a href="mac_murrett.htm">Mac Murrett</a></td> + <td><a href="http://boost.sourceforge.net/photos/mac_murrett.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/mac_murrett_small.jpg" xthumbnail-orig-image="http://boost.sourceforge.net/photos/mac_murrett.jpg" width="100" height="141"></a></td> + </tr> + <tr> + <td><a href="gary_powell.htm">Gary Powell</a></td> + <td><a href="http://boost.sourceforge.net/photos/gary_powell.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/gary_powell_small.jpg" alt="http://boost.sourceforge.net/photos/gary_powell.jpg (13577 bytes)" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="mark_rodgers.htm">Mark Rodgers</a></td> + <td><a href="http://boost.sourceforge.net/photos/mark_rodgers.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/mark_rodgers_small.jpg" alt="http://boost.sourceforge.net/photos/mark_rodgers.jpg (23035 bytes)" width="100" height="75"></a></td> + </tr> + <tr> + <td><a href="jeremy_siek.htm">Jeremy Siek</a></td> + <td><a href="http://boost.sourceforge.net/photos/jeremy_siek.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/jeremy_siek_small.jpg" alt="http://boost.sourceforge.net/photos/jeremy_siek.jpg (12867 bytes)" width="100" height="133"></a></td> + </tr> + <tr> + <td><a href="daryle_walker.html">Daryle Walker</a></td> + <td><img border="0" src="http://boost.sourceforge.net/photos/daryle_walker.jpg" width="100" height="127"></td> + </tr> + </table> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 09 August, 2002<!--webbot bot="Timestamp" endspan i-checksum="34422" --> + </p> + </body> +</html> diff --git a/people/peter_dimov.htm b/people/peter_dimov.htm new file mode 100644 index 0000000000..f5fc7d043a --- /dev/null +++ b/people/peter_dimov.htm @@ -0,0 +1,27 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>Peter Dimov</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/peter_dimov.jpg"><img border="0" src="http://boost.sourceforge.net/photos/peter_dimov_small.jpg" alt="peter_dimov.jpg (16507 bytes)" align="left" hspace="10" vspace="5" width="100" height="131"><br> + <br> + </a><a href="http://www.mmltd.net/pdimov/">Peter Dimov</a> is a software + developer from Plovdiv, Bulgaria. He is working at Multi Media (<a href="http://www.mmltd.net">www.mmltd.net</a>) + - a company that really deserves a better web site.</p> + <p>He likes C++. Not to the extent to donate a kidney for every proposed + extension, but close.</p> + </body> +</html> diff --git a/people/ralf_w_grosse_kunstleve.htm b/people/ralf_w_grosse_kunstleve.htm new file mode 100644 index 0000000000..15e10a9b25 --- /dev/null +++ b/people/ralf_w_grosse_kunstleve.htm @@ -0,0 +1,52 @@ +<html> + <head> + <title>Ralf W. Grosse-Kunstleve</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/ralf_w_grosse_kunstleve.jpg"><img src="http://boost.sourceforge.net/photos/ralf_w_grosse_kunstleve_sm.jpg" alt="ralf_w_grosse_kunstleve.jpg" border="0" align="left" hspace="10" vspace="5" width="100" height="134"></a> + Ralf is a crystallographer. He has a degree in Mineralogy (<a href="http://www.mineralogie.ruhr-uni-bochum.de/englisch/mineralogie_v2.0_eng.htm">Bochum, + Germany</a>), and a Ph.D. in Crystallography (<a href="http://www.kristall.ethz.ch/LFK/">ETH + Zurich</a> + , Switzerland). Real Mineralogists and Crystallographers run experiments with + x-rays and hardware that is not normally associated with C++ and Boost. + However, when Ralf kept breaking the expensive experimental equipment too + often, he decided that he would cause less damage as a computational + crystallographer. + <p> + Being a scientist, Ralf spent most of his life programming in Fortran, the + great grand-father of all good programming languages (if you know Backus-Naur + you know the name of the <a href="http://www.digitalcentury.com/encyclo/update/backus.html"> + inventor of Fortran</a>). Ralf is a co-author of the <a href="http://cns.csb.yale.edu/"> + CNS</a> Fortran program that is very popular in structural biology. When he + learned that a real programmer can write Fortran in any language, Ralf knew + that it was time for him to learn C++. Of course, absorbing four decades of + progress in the field of computer science all at once crashed his brain. To be + able to deal with the challenge, he spawned two child processes and named them + Lisa and Anna. To see Lisa, click on the picture and turn your monitor by 180 + degrees around the view axis. (Other pictures of <a href="http://cci.lbl.gov/~rwgk/Lisa-Roza-Illes/"> + Lisa</a> and <a href="http://cci.lbl.gov/~rwgk/Anna-Rhona-Illes/">Anna</a> + do not require gymnastics with the monitor.) + <p> + Right now, Ralf is working for the <a href="http://cci.lbl.gov/">Computational + Crystallography Initiative</a> at the <a href="http://www.lbl.gov/">Lawrence + Berkeley National Laboratory</a> in California. The goal of this initiative + is to write a software system for high-throughput protein crystal structure + determination, also known as <a href="http://www.nigms.nih.gov/news/announcements/psi.html"> + Structural Genomics</a>. Surprisingly, the gestation period for such a system + turns out to be much longer than it was for Lisa and Anna. However, pre-natal + diagnosis already revealed that Python and C++ are the parents-to-be. For an + ultra-sound image of the new system at its early developmental stage <a href="http://cctbx.sourceforge.net/"> + click here</a> + . + </body> +</html> diff --git a/people/ronald_garcia.htm b/people/ronald_garcia.htm new file mode 100644 index 0000000000..b57efac4c4 --- /dev/null +++ b/people/ronald_garcia.htm @@ -0,0 +1,31 @@ +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <title>Ronald Garcia</title> + </head> + <body bgcolor="#FFFFFF"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/ronald_garcia.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/ronald_garcia_small.jpg" align="left" hspace="10" vspace="5" xthumbnail-orig-image="ronald_garcia.jpg" width="100" height="144"></a>Ronald + Garcia is a Ph.D. student at Indiana University in Bloomington, Indiana. He is + the author of the Boost Multidimensional Array Library (<a href="../libs/multi_array/doc/index.html">MultiArray</a>). + His research interests include software engineering tools and techniques, + programming languages, generic and generative programming and high performance + scientific computing. + </p> + <p>When he's not in front of a computer, Ron's interests include playing ultimate + frisbee, bass guitar, drumset, and West African percussion. + </p> + </body> +</html> diff --git a/people/samuel_krempp.htm b/people/samuel_krempp.htm new file mode 100644 index 0000000000..5070db5d7f --- /dev/null +++ b/people/samuel_krempp.htm @@ -0,0 +1,31 @@ +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <title>Samuel Krempp</title> + </head> + <body bgcolor="#FFFFFF"> + <table cellPadding="2" bgColor="#007f7f" border="1"> + <tr> + <td bgColor="#ffffff"> + <img alt="c++boost.gif (8819 bytes)" src="../c++boost.gif" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#ffffff"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#ffffff"><big> Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#ffffff"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#ffffff"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#ffffff"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/samuel_krempp.jpg"> <img border="0" src="http://boost.sourceforge.net/photos/samuel_krempp_small.jpg" xthumbnail-orig-image="samuel_krempp.jpg" align="left" hspace="10" vspace="5" width="100" height="65"></a>Samuel + Krempp is a PhD student in mathematics, at the CMLA in the 'Ecole Normale + Supérieure' de Cachan (France). He spends most of his time implementing + complicated image recognition algorithms, and thus had to get acquainted with + C++.</p> + <p>He enjoys many other things - one of them is diving in wonderful, warm, sunny + seas when he can afford it. And obviously, another is eating camembert and + bread, drinking wine... and other activities typical of a French guy :)</p> + <p>He's the author of the <a href="../libs/format/index.htm">Boost Format library</a>.</p> + </body> +</html> diff --git a/people/vesa_karvonen.htm b/people/vesa_karvonen.htm new file mode 100644 index 0000000000..89a5f95321 --- /dev/null +++ b/people/vesa_karvonen.htm @@ -0,0 +1,65 @@ +<html> + <head> + <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <title>Vesa Karvonen</title> + </head> + <body bgcolor="#FFFFFF"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><img border="0" src="http://boost.sourceforge.net/photos/vesa_karvonen.jpg" align="left" hspace="10" vspace="5" width="100" height="133">If + we are to believe MBTI tests, Vesa is an <a href="http://fuzzy.snakeden.org/intj/"> + INTJ</a>. He has been like that probably since late 1978-1979, because, + according to some sources, it takes 2-3 years to develop the basic temperament. + Previously he saw himself mostly as a "builder of systems" and + "applier of theoretical models", but nowadays he is beginning to see + the "mastermind" aspect of his personality. As a + "Free-Thinker", his mind hardly ever rests.</p> + <p>Vesa enjoys healthy and sustainable ways of life. He is a vegetarian and likes + cooking. Exercise is a daily part of his life - he needs to be in good shape in + order to sit all day in work. He likes going to the gym, swimming, spinning, + running, roller skating, etc... He also practices dancing.</p> + <p>For the past years, he has been working in a small <a hreF="http://www.housemarque.com"> + company</a> that develops console games. His role is the development of + software technology, such as class libraries, frameworks and tools, for making + games. He doesn't see himself as a game or a graphics programmer, although he + has been involved in quite a few such projects. For the past few years, most of + his programming has been in C++, but recently he has also enjoyed writing some + Ocaml.</p> + <p>He likes buying technical books using the company credit card, but lately he + hasn't had the time to read as much as he would like (hopefully this changes + soon). He likes reading (a lot) computer science and software engineering, but + also psychology, philosophy and various self-help books, because he knows that + all the really hard problems are social - not technical. Fantasy is also close + to his heart.</p> + <p>Vesa is a bit ambivalent about his university studies. He is a self-educated + programmer and has experience ranging from bit twiddling to generative + programming and also leading of small teams. Like many of his close colleagues, + he sees that the depth of computer science education, at least in Finland, is, + frankly, insufficient. He'll probably complete his studies some day, because + sadly most people respect authority by rank, title or publication far more than + he does.</p> + <p>Vesa is an eXtreme Programmer. He has found out that in order for pair + programming to work, both pairs must share a similar level of experience and + must be both willing and able to externalize their thoughts. If he is sometimes + forced to stop refactoring, he'll probably quit his job. He thinks that + optimization, including improving readability and simplifying structure, is the + root of all fun in programming. He dislikes writing documentation and reports + that are never read.</p> + <p>One of his friends coerced him to use the image that you see on this page. The + image was scanned from a rather worn out picture taken by an ex-girlfriend and + is probably the only picture of Vesa having his natural smile. Vesa is neither + married nor engaged, but just recently he met a very nice girl... While + programming is interesting and fun, it is love that really makes him happy. ;)</p> + </body> +</html> diff --git a/people/william_kempf.htm b/people/william_kempf.htm new file mode 100644 index 0000000000..a020f4f7f5 --- /dev/null +++ b/people/william_kempf.htm @@ -0,0 +1,30 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + <title>William Kempf</title> + </head> + <body bgcolor="#FFFFFF" text="#000000"> + <table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> + </table> + <p><a href="http://boost.sourceforge.net/photos/william_kempf.jpg"><img border="0" src="http://boost.sourceforge.net/photos/william_kempf_small.jpg" alt="william_kempf.jpg (10935 bytes)" align="left" hspace="10" vspace="5" width="107" height="130"></a> + Bill Kempf lives in Omaha, NE with his wife Bonnie, his cat Dexter and his two + Chinchillas, Chimney and Minuet. He married on Oct. 30, 1999 where he and his + wife held a Halloween costume reception. If that doesn't give you an idea of + what kind of guy he is, nothing will.</p> + <p>Bill graduated from Doane, a small private college in Nebraska in 1992 with a + B.S. in Computer Science/Math. Being in the wrong place at the wrong time he + had to take a job as the only person in an IS shop for a local affiliate of the + Bunge Grain Company. In 1995 he moved on to a job as a software engineer for + First Data Resources where he worked on client/server financial applications.</p> + </body> +</html> diff --git a/project-root.jam b/project-root.jam new file mode 100644 index 0000000000..ea64b4409a --- /dev/null +++ b/project-root.jam @@ -0,0 +1,5 @@ + +import gcc ; +import lex ; +import bison ; +import testing ; diff --git a/status/.cvsignore b/status/.cvsignore new file mode 100644 index 0000000000..d265891d55 --- /dev/null +++ b/status/.cvsignore @@ -0,0 +1,5 @@ +*.log +boosttmp.* +regression +rng.saved +rng.tmp diff --git a/status/Jamfile b/status/Jamfile new file mode 100644 index 0000000000..e53c9243f1 --- /dev/null +++ b/status/Jamfile @@ -0,0 +1,346 @@ +# Boost regression-testing Jamfile +# (C) Copyright David Abrahams 2002. Permission to copy, use, modify, sell and +# distribute this software is granted provided this copyright notice appears in +# all copies. This software is provided "as is" without express or implied +# warranty, and with no claim as to its suitability for any purpose. + +subproject status ; + +# bring in the rules for testing +SEARCH on testing.jam = $(BOOST_BUILD_PATH) ; +include testing.jam ; + +# Make tests run by default. +DEPENDS all : test ; + +# Tests from Jamfiles in individual library test subdirectories +# Please keep these in alphabetic order by test-suite name + +subinclude libs/bind/test ; # test-suite bind +subinclude libs/date_time/test ; # test-suite date_time +subinclude libs/filesystem/test ; # test-suite filesystem +subinclude libs/format/test ; # test-suite format +subinclude libs/function/test ; # test-suite function +subinclude libs/math/test ; # test-suite math +subinclude libs/numeric/interval/test ; # test-suite interval +subinclude libs/optional/test ; # test-suite optional +subinclude libs/regex/test ; # test-suite regex +subinclude libs/regex/example ; # test-suite regex-examples +subinclude libs/signals/test ; # test-suite signals +subinclude libs/smart_ptr/test ; # test-suite smart_ptr +subinclude libs/static_assert ; # test-suite static_assert +subinclude libs/thread/test ; # test-suite thread +subinclude libs/type_traits/test ; # test-suite type_traits + + +# Tests specified in this Jamfile +{ + # look in BOOST_ROOT for sources first, just in this Jamfile + local SEARCH_SOURCE = $(BOOST_ROOT) $(SEARCH_SOURCE) ; + + test-suite config + : [ run libs/config/test/config_test.cpp <lib>../libs/test/build/boost_test_exec_monitor + : #args + : #input-files + : #requirements + <threading>multi + std::facet-support + ] + [ run libs/config/test/config_info.cpp : : : <test-info>always_show_run_output ] + [ run libs/config/test/limits_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + + run libs/any/any_test.cpp ; + + test-suite array + : [ run libs/array/array1.cpp ] + [ run libs/array/array2.cpp ] + [ run libs/array/array3.cpp ] + [ run libs/array/array4.cpp ] + [ run libs/array/array5.cpp ] + ; + + test-suite concept_check + : [ compile libs/concept_check/concept_check_test.cpp ] + [ compile libs/concept_check/class_concept_check_test.cpp ] + [ compile-fail libs/concept_check/concept_check_fail_expected.cpp ] + [ compile-fail libs/concept_check/class_concept_fail_expected.cpp ] + ; + + test-suite conversion + : [ run libs/conversion/cast_test.cpp ] + [ run libs/conversion/lexical_cast_test.cpp ] + ; + + run libs/crc/crc_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ; + + + test-suite disjoint_sets + : [ run libs/disjoint_sets/disjoint_set_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + + test-suite dynamic_bitset + : [ run libs/dynamic_bitset/dyn_bitset_unit_tests1.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/dynamic_bitset/dyn_bitset_unit_tests2.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/dynamic_bitset/dyn_bitset_unit_tests3.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + + + run libs/functional/function_test.cpp ; + + run libs/graph/test/graph.cpp ; + + + test-suite integer + : [ run libs/integer/cstdint_test.cpp ] + [ run libs/integer/integer_test.cpp ] + [ run libs/integer/integer_traits_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + + run + libs/io/test/ios_state_test.cpp <lib>../libs/test/build/boost_test_exec_monitor # sources + : # args + : # input-files + : std::locale-support std::facet-support + ; + + test-suite lambda + : [ run libs/lambda/test/bind_tests_simple.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/bind_tests_advanced.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/bind_tests_simple_f_refs.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/bll_and_function.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/cast_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/constructor_tests.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/control_structures.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/exception_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/extending_rt_traits.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/is_instance_of_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/member_pointer_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/operator_tests_simple.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/phoenix_control_structures.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/lambda/test/switch_construct.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + + + run libs/pool/test/test_pool_alloc.cpp <lib>../libs/test/build/boost_test_exec_monitor ; + + test-suite preprocessor + : [ compile libs/preprocessor/test/arithmetic.cpp ] + [ compile libs/preprocessor/test/array.cpp ] + [ compile libs/preprocessor/test/comparison.cpp ] + [ compile libs/preprocessor/test/control.cpp ] + [ compile libs/preprocessor/test/debug.cpp ] + [ compile libs/preprocessor/test/facilities.cpp ] + [ compile libs/preprocessor/test/iteration.cpp ] + [ compile libs/preprocessor/test/list.cpp ] + [ compile libs/preprocessor/test/logical.cpp ] + [ compile libs/preprocessor/test/repetition.cpp ] + [ compile libs/preprocessor/test/selection.cpp ] + [ compile libs/preprocessor/test/slot.cpp ] + [ compile libs/preprocessor/test/tuple.cpp ] + ; + + test-suite property_map + : [ compile libs/property_map/property_map_cc.cpp ] + ; + + test-suite rational + : [ run libs/rational/rational_example.cpp ] + [ run libs/rational/rational_test.cpp ] + ; + + test-suite random + : [ run libs/random/random_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/random/random_demo.cpp ] + ; + + subinclude libs/test/test ; + + compile libs/timer/timer_test.cpp ; + + test-suite tokenizer + : [ run libs/tokenizer/examples.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/tokenizer/simple_example_1.cpp ] + [ run libs/tokenizer/simple_example_2.cpp ] + [ run libs/tokenizer/simple_example_3.cpp ] + [ run libs/tokenizer/simple_example_4.cpp ] + [ run libs/tokenizer/simple_example_5.cpp ] + ; + + test-suite tuple + : [ run libs/tuple/test/tuple_test_bench.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/tuple/test/io_test.cpp <lib>../libs/test/build/boost_test_exec_monitor : : : std::facet-support ] + ; + + + test-suite iterator_adaptors + : [ run libs/utility/counting_iterator_test.cpp : # args + : # input files + : # requirements + + # borland warns incorrectly in this case, so often that + # successful compilation is prevented. + <borland><*><cxxflags>"-w-8091 -w-8092" + ] + + [ run libs/utility/iterator_adaptor_test.cpp ] + [ compile-fail libs/utility/iter_adaptor_fail_expected1.cpp ] + [ compile-fail libs/utility/iter_adaptor_fail_expected2.cpp ] + [ run libs/utility/transform_iterator_test.cpp ] + [ run libs/utility/indirect_iterator_test.cpp ] + [ run libs/utility/iter_traits_gen_test.cpp ] + + [ run libs/utility/iterator_adaptor_examples.cpp ] + [ run libs/utility/counting_iterator_example.cpp ] + [ run libs/utility/filter_iterator_example.cpp ] + [ run libs/utility/fun_out_iter_example.cpp ] + [ run libs/utility/indirect_iterator_example.cpp ] + [ run libs/utility/projection_iterator_example.cpp ] + [ run libs/utility/reverse_iterator_example.cpp ] + [ run libs/utility/transform_iterator_example.cpp ] + ; + + test-suite ublas + : [ run libs/numeric/ublas/test1/test1.cpp + libs/numeric/ublas/test1/test11.cpp + libs/numeric/ublas/test1/test12.cpp + libs/numeric/ublas/test1/test13.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/test2/test2.cpp + libs/numeric/ublas/test2/test21.cpp + libs/numeric/ublas/test2/test22.cpp + libs/numeric/ublas/test2/test23.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/test3/test3.cpp + libs/numeric/ublas/test3/test31.cpp + libs/numeric/ublas/test3/test32.cpp + libs/numeric/ublas/test3/test33.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/test4/test4.cpp + libs/numeric/ublas/test4/test41.cpp + libs/numeric/ublas/test4/test42.cpp + libs/numeric/ublas/test4/test43.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/test5/test5.cpp + libs/numeric/ublas/test5/test51.cpp + libs/numeric/ublas/test5/test52.cpp + libs/numeric/ublas/test5/test53.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/test6/test6.cpp + libs/numeric/ublas/test6/test61.cpp + libs/numeric/ublas/test6/test62.cpp + libs/numeric/ublas/test6/test63.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + [ run libs/numeric/ublas/concepts.cpp + : # args + : # input files + : # requirements + + # borland warns so often that successful compilation is prevented. + <borland><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + <kylix><*><cxxflags>"-w-8026 -w-8027 -w-8057 -w-8084 -w-8092" + ] + ; + + + test-suite multi_array + : [ run libs/multi_array/test/constructors.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/access.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/compare.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/iterators.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/slice.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/assign.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/index_bases.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/storage_order.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/reshape.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/range1.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/idxgen1.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/multi_array/test/stl_interaction.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ compile libs/multi_array/test/concept_checks.cpp ] + [ compile-fail libs/multi_array/test/fail_cbracket.cpp ] + [ compile-fail libs/multi_array/test/fail_cdata.cpp ] + [ compile-fail libs/multi_array/test/fail_citerator.cpp ] + [ compile-fail libs/multi_array/test/fail_cparen.cpp ] + [ compile-fail libs/multi_array/test/fail_criterator.cpp ] + [ compile-fail libs/multi_array/test/fail_csubarray.cpp ] + [ compile-fail libs/multi_array/test/fail_csubarray2.cpp ] + [ compile-fail libs/multi_array/test/fail_csubarray3.cpp ] + [ compile-fail libs/multi_array/test/fail_cview.cpp ] + [ compile-fail libs/multi_array/test/fail_cview2.cpp ] + [ compile-fail libs/multi_array/test/fail_cview3.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cbracket.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cdata.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_citerator.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cparen.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_criterator.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_csubarray.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_csubarray2.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_csubarray3.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cview.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cview2.cpp ] + [ compile-fail libs/multi_array/test/fail_ref_cview3.cpp ] + ; + + test-suite utility + : + [ run libs/utility/iterator_traits_test.cpp ] + [ run libs/utility/iterators_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ compile-fail libs/utility/noncopyable_test.cpp ] + [ run libs/utility/numeric_traits_test.cpp ] + [ run libs/utility/operators_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/utility/tie_example.cpp ] + [ run libs/utility/binary_search_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/utility/call_traits_test.cpp : -u ] + [ compile-fail libs/utility/checked_delete_test.cpp ] + [ run libs/utility/compressed_pair_test.cpp <lib>../libs/test/build/boost_test_exec_monitor : -u ] + [ run libs/utility/addressof_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + [ run libs/utility/ref_test.cpp <lib>../libs/test/build/boost_test_exec_monitor ] + ; + +} + + + + diff --git a/status/borland_logo.gif b/status/borland_logo.gif Binary files differnew file mode 100644 index 0000000000..0165fb44ef --- /dev/null +++ b/status/borland_logo.gif diff --git a/status/compiler_status.html b/status/compiler_status.html new file mode 100644 index 0000000000..05e2d813ab --- /dev/null +++ b/status/compiler_status.html @@ -0,0 +1,238 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<title>Boost Compiler Status Report</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial">Home</font></a></td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" + size="4" face="Arial">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial">People</font></a></td> + <td><a href="../more/faq.htm"><font color="#FFFFFF" + size="4" face="Arial">FAQ</font></a></td> + <td><a href="../more/index.htm"><font color="#FFFFFF" + size="4" face="Arial">More</font></a></td> + </tr> +</table> + +<h1>Compiler Status Tables</h1> + +<p><a href="http://boost.sourceforge.net/regression-logs/">Compiler Status +Summary</a> (on SourceForge) of Boost regression test results.<br> +<a href="#Introduction">Introduction</a><br> +<a href="#Understanding">Understanding the Tables</a><br> +<a href="#Acknowledgements">Acknowledgements</a></p> + +<h2><a name="Introduction">Introduction</a></h2> + +<p>Will all Boost libraries work with your compiler? +Unfortunately, the answer is "it depends". See the +<a href="http://boost.sourceforge.net/regression-logs/">Compiler Status Summary</a> +to see exactly what works and what doesn't.</p> + +<p>Boost libraries rely on modern C++ features such as templates +and the C++ Standard Library. Most modern compilers support +those major features fairly well. But even today, years after the +adoption of the C++ Standard, some compilers still don't support +important minor features like partial template specialization.</p> + +<p>Boost library authors often expend a great deal of effort +trying to work around compiler deficiencies. Nevertheless, +some libraries will not compile at all with certain compilers or +may have crippled functionality. Even if the current +release of a compiler supports a boost library, older versions of +the compiler may not work properly.</p> + +<p>Boost releases are run through <a href="../more/regression.html">regression +tests</a> which +automatically generates Compiler Status Tables for various +platforms. Unless otherwise indicated, the C++ Standard Library +implementation is the one shipped with the compiler.</p> + +<p><b>Warnings:</b></p> + +<ul> + <li>These tables are not a good indication of a +particular compiler's compliance with the C++ Standard. The +Boost libraries often contain workarounds which mask compiler +deficiencies.<br> + </li> + <li>Some regression tests are run only occasionally, and so are relatively + out-of-date. Check the date for each table.</li> +</ul> + +<p><a name="quick-reference"></a>The +<a href="http://boost.sourceforge.net/regression-logs/">Compiler Status Summary</a> +includes table summaries for specific releases, as well as table summaries for +recent <a href="../more/download.html#CVS">CVS</a> snapshots. Release tables are +identified by the release number appended to the table name. CVS snapshot tables +do not have a release number appended.</p> + +<p>The <a href="../more/download.html#CVS">CVS</a> +code is being updated several times a day, so it may contain bug fixes, compiler +workarounds, new features, and even whole new libraries. It may be unstable, +however.</p> + +<h2><a name="Understanding">Understanding</a> the Tables</h2> + +<p>A table might look like this:</p> + +<blockquote> + <p><b>Run Date:</b> 21 Sep 2001 15:31 GMT</p> + <p><b>System Configuration:</b> Microsoft Windows 32bit </p> + <table border="1" cellpadding="5" cellspacing="0"> +<tbody> <tr> + <td>Program</td> + <td>Test<br> + Type</td> + <td>BelchFire<br> + Rev 5280</td> + <td>WorkHorse<br> + 5.3</td> + </tr> + <tr> + <td>libs/foo/test/foo_test.cpp</td> + <td>compile</td> + <td>Pass</td> + <td>Pass</td> + </tr> + <tr> + <td>libs/bar/bar_test.cpp</td> + <td>run</td> + <td><u><font color="#FF0000">Fail</font></u></td> + <td>Pass</td> + </tr> +</tbody> </table> +</blockquote> + +<p>The <i>Run Date</i> is important because the regression tests +which create the status tables are run asynchronously, and thus +may not represent the most current Boost release.</p> + +<p>The <i>Program</i> column identifies the actual source file +for the test. Each row in the table represents a different +test.</p> + +<p>The <a name="test-type"><i>Test Type</i></a> column identifies +the type of test performed:</p> + +<table border="1" cellpadding="5" cellspacing="0"> + <tr> + <td><b>Test Type</b></td> + <td><b>Action</b></td> + <td><b>Required to </b><b><i>Pass</i></b></td> + <td><b>Description and Use</b></td> + </tr> + <tr> + <td>compile</td> + <td>compile only</td> + <td>Compiler returns 0.</td> + <td>Verify that a source file will compile correctly, but + without any attempt to link or execute. Used when + factors such as possible object library unavailability + make a run test impractical.</td> + </tr> + <tr> + <td>compile-fail</td> + <td>compile only</td> + <td>Compiler must return non-zero.</td> + <td>Verify that a source file fails to compile. Used to + verify that an expected compile-time error was detected.</td> + </tr> + <tr> + <td>link</td> + <td>compile, link</td> + <td>Both compiler & linker return 0.</td> + <td>Verify that a source file will compile and link + correctly, but without any attempt to execute the result. + Used when factors such as possible data file + unavailability make a run test impractical.</td> + </tr> + <tr> + <td>link-fail</td> + <td>compile, link</td> + <td>Either the compiler or linker must return non-zero.</td> + <td>Verify that a source file fails to compile and link. + Used to verify that error detect which depends on + unresolved externals works correctly.</td> + </tr> + <tr> + <td>run</td> + <td>compile, link, execute</td> + <td>Compiler, linker, and executable must all return 0.</td> + <td>Verify that a source file compiles, links, and the + resulting program executes correctly (as indicated by a + zero return code.) This is the primary test type + for most uses.</td> + </tr> + <tr> + <td>run-fail</td> + <td>compile, link, execute</td> + <td>Both compiler and linker must return 0, and the + executable must return non-zero.</td> + <td>Verify that a source file compiles and links + correctly, and that execution of the resulting program + detects some error. Used to verify runtime error + detection code works properly.</td> + </tr> +</table> + +<p>Each remaining column in the table represents the individual +compiler indicated. Unless otherwise indicated, the C++ Standard +Library implementation is the one shipped with the compiler. A <i>Pass</i> +entry indicates success for the indicated <i>Test Type</i>, while +a <font color="#FF0000"><i>Fail</i></font> entry indicates +failure. See <i>Required to Pass</i> in the above table for specifics.</p> + +<p>When possible, <font color="#FF0000"><i>Fail</i></font> entries are linked to +error messages indicating the reason for the failure. Note that the web page +containing error messages may be as much as one megabyte in size.</p> + +<h2><a name="Acknowledgements">Acknowledgements</a></h2> + +<p>The compiler status tables have been prepared with resources +donated by a number of individuals, educational institutions, and +companies. Boost would like to thank them for their support. </p> + +<ul> + <li><a href="http://www.borland.com/"><img border="0" src="borland_logo.gif" align="center" width="70" height="33">Borland</a>, + California, USA</li> + <li><a href="http://www.intel.com/software/products"><img + src="intel_logo.gif" align="center" border="0" width="72" + height="36">Intel Corporation</a>, California, USA </li> + <li><a href="http://www.kai.com/"><img src="kai_logo.gif" + align="center" border="0" width="60" height="25"> KAI + Software</a>, Illinois, USA<br> + </li> + <li><a href="http://www.hp.com/">Hewlett-Packard Company</a>, + USA</li> + <li><a href="http://www.lbl.gov">Lawrence Berkeley National + Laboratory</a>, California, USA</li> + <li><a href="http://www.nd.edu/">University of Notre Dame</a>, + Indiana, USA</li> +</ul> + +<p>Note, however, that Boost does not endorse any product or +service, nor does Boost guarantee that some or all of its +libraries work with any of the products or services mentioned +above. </p> + +<hr> + +<p>Revised +<!--webbot bot="Timestamp" s-type="EDITED" +s-format="%d %B %Y" startspan -->04 February 2003<!--webbot bot="Timestamp" endspan i-checksum="40865" --></p> +</body> +</html>
\ No newline at end of file diff --git a/status/index.html b/status/index.html new file mode 100644 index 0000000000..ef88d3195f --- /dev/null +++ b/status/index.html @@ -0,0 +1,9 @@ +<html> +<head> +<meta http-equiv="refresh" content="0; URL=compiler_status.html#quick-reference"> +</head> +<body> +Automatic redirection failed, please go to +<a href="compiler_status.html">compiler_status.html</a>. +</body> +</html>
\ No newline at end of file diff --git a/status/intel_logo.gif b/status/intel_logo.gif Binary files differnew file mode 100644 index 0000000000..47f9ded887 --- /dev/null +++ b/status/intel_logo.gif diff --git a/status/kai_logo.gif b/status/kai_logo.gif Binary files differnew file mode 100644 index 0000000000..eb2424c1fd --- /dev/null +++ b/status/kai_logo.gif diff --git a/tools/build b/tools/build new file mode 160000 +Subproject 43585b45d04c411ae8e80136c463036c24c4a86 diff --git a/tools/index.html b/tools/index.html new file mode 100644 index 0000000000..b0ebf024de --- /dev/null +++ b/tools/index.html @@ -0,0 +1,54 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<title>Boost Tools</title> +</head> + +<body bgcolor="#FFFFFF"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial">Home</font></a></td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" + size="4" face="Arial">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial">People</font></a></td> + <td><a href="../more/faq.htm"><font color="#FFFFFF" + size="4" face="Arial">FAQ</font></a></td> + <td><a href="../more/index.htm"><font color="#FFFFFF" + size="4" face="Arial">More</font></a></td> + </tr> +</table> + +<h1>Boost Tools</h1> +<p>Boost developers, testers, and maintainers have developed various programs to +help with the administration of the Boost Libraries. Like everything else about +Boost, these tools are available in source form, and are part of the regular +Boost distribution.</p> +<p>Users may find these tools useful when porting Boost libraries to a new +platform, or for use with their own applications.</p> +<ul> + <li><a href="build/index.html">Boost.Build</a> - The Boost build system, + including the full Boost version of the jam sources.<br> + </li> + <li><a href="regression/index.htm">Regression</a> - The Boost regression + testing system reporting sources.<br> + </li> + <li><a href="inspect/index.html">Inspect </a>- The inspection tool used to + detect errors in the Boost directory hierarchy.</li> +</ul> +<hr> +<p>Revised +<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->07 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38578" --></p> + +</body> + +</html> diff --git a/tools/inspect b/tools/inspect new file mode 160000 +Subproject 9c684417301bad6704d3dd324404532dd7e3339 diff --git a/tools/make-cputime-page.pl b/tools/make-cputime-page.pl new file mode 100644 index 0000000000..2f07b577a2 --- /dev/null +++ b/tools/make-cputime-page.pl @@ -0,0 +1,49 @@ +#!/usr/bin/perl -w + +use strict; + +my $filename; +my $compiler; +my $time = 0; +my $ct = 0; +my $first = 2; + +print "<html>\n<head>\n<title>\nCompile Times</title>\n</head>\n\n"; +print "<body bgcolor=\"#ffffff\" text=\"#000000\">\n"; +print "<img border=\"0\" src=\"c++boost.gif\" width=\"277\" height=\"86\">"; +print "<p>\n"; +print "Compile time for each successful regression test in seconds.\n"; +print "<p>\n"; + +print "<table border=\"1\">\n"; +print "<tr><td>Test</td>\n"; + +while(<>) { + if(/^\*\*\* (.*) \*\*\*$/) { + $filename = $1; + $first = ($first == 0 ? 0 : $first-1); + if($first == 0) { + print "</tr>\n\n<tr align=right>\n<td align=left><a href=\"http://www.boost.org/$filename\">$filename</a></td>\n"; + } + } elsif(/^\*\* (.*)/) { + $compiler = $1; + if($first) { + print "<td>$compiler</td>\n"; + } else { + $ct = 1; + } + } elsif($ct && /^CPU time: ([.0-9]*) s user, ([.0-9]*) s system/) { + $time = $1 + $2; + } elsif($ct && /^Pass$/) { + printf "<td>%.02f</td>\n", $time; + $ct = 0; + } elsif($ct && /^Fail$/) { + print "<td>-</td>\n"; + $ct = 0; + } +} + +print "</tr>\n"; +print "</table>\n"; +print "</body>\n</html>\n"; + diff --git a/tools/regression/build/Jamfile b/tools/regression/build/Jamfile new file mode 100644 index 0000000000..237a27b52f --- /dev/null +++ b/tools/regression/build/Jamfile @@ -0,0 +1,33 @@ +# Regression test status reporting tools build Jamfile + +subproject tools/regression/build ; + +exe process_jam_log + : + ../process_jam_log.cpp ../detail/tiny_xml.cpp + <lib>../../../libs/filesystem/build/boost_filesystem + : + <sysinclude>$(BOOST_ROOT) + : + release + ; + +exe compiler_status + : + ../compiler_status.cpp ../detail/tiny_xml.cpp + <lib>../../../libs/filesystem/build/boost_filesystem + : + <sysinclude>$(BOOST_ROOT) + : + release + ; + +stage run + : + <exe>process_jam_log + <exe>compiler_status + : + : + release + <suppress>true + ; diff --git a/tools/regression/compiler_status.cpp b/tools/regression/compiler_status.cpp new file mode 100644 index 0000000000..f879dbc4a6 --- /dev/null +++ b/tools/regression/compiler_status.cpp @@ -0,0 +1,680 @@ +// Generate Compiler Status HTML from jam regression test output -----------// + +// (C) Copyright Beman Dawes 2002. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +/******************************************************************************* + + This program was designed to work unchanged on all platforms and + configurations. All output which is platform or configuration dependent + is obtained from external sources such as the .xml file from + process_jam_log execution, the tools/build/xxx-tools.jam files, or the + output of the config_info tests. + + Please avoid adding platform or configuration dependencies during + program maintenance. + +*******************************************************************************/ + +#include "boost/filesystem/operations.hpp" +#include "boost/filesystem/fstream.hpp" +#include "detail/tiny_xml.hpp" +namespace fs = boost::filesystem; +namespace xml = boost::tiny_xml; + +#include <cstdlib> // for abort +#include <string> +#include <vector> +#include <set> +#include <algorithm> +#include <iostream> +#include <fstream> +#include <ctime> +#include <stdexcept> + +using std::string; + +const string pass_msg( "Pass" ); +const string warn_msg( "<font color=\"#FF9900\"><i>Warn</i></font>" ); +const string fail_msg( "<font color=\"#FF0000\">" + "<big><i>Fail</i></big>" + "</font>" ); +const string missing_residue_msg( "<i>Missing</i>" ); + +const std::size_t max_compile_msg_size = 10000; + +namespace +{ + fs::path boost_root; // boost-root complete path + fs::path locate_root; // locate-root (AKA ALL_LOCATE_TARGET) complete path + + bool ignore_pass; + bool no_warn; + bool no_links; + + fs::directory_iterator end_itr; + + // It's immportant for reliability that we find the same compilers for each + // test, and that they match the column header. So save the names at the + // time column headings are generated. + std::vector<string> toolsets; + + fs::ifstream jamfile; + fs::ofstream report; + fs::ofstream links_file; + string links_name; + + string specific_compiler; // if running on one toolset only + + const string empty_string; + +// relative path between two paths -----------------------------------------// + + void relative_path( const fs::path & from, const fs::path & to, + fs::path & target ) + { + if ( from.string().size() <= to.string().size() ) return; + target /= ".."; + relative_path( from.branch_path(), to, target ); + return; + } + +// extract test name from target directory string --------------------------// + + string extract_test_name( const string & s ) + { + string t( s ); + string::size_type pos = t.find( "/bin/" ); + if ( pos != string::npos ) pos += 5; + else return ""; + return t.substr( pos, t.find( ".", pos ) - pos ); + } + +// find_file ---------------------------------------------------------------// +// given a directory to recursively search + + bool find_file( const fs::path & dir_path, const string & name, + fs::path & path_found, const string & ignore_dir_named="" ) + { + if ( !fs::exists( dir_path ) ) return false; + for ( fs::directory_iterator itr( dir_path ); itr != end_itr; ++itr ) + if ( fs::is_directory( *itr ) + && itr->leaf() != ignore_dir_named ) + { + if ( find_file( *itr, name, path_found ) ) return true; + } + else if ( itr->leaf() == name ) + { + path_found = *itr; + return true; + } + return false; + } + +// platform_desc -----------------------------------------------------------// +// from locate_root/status/bin/config_info.test/xxx/.../config_info.output + + string platform_desc() + { + string result; + fs::path dot_output_path; + + // the gcc config_info "Detected Platform" sometimes reports "cygwin", so + // prefer any of the other compilers. + if ( find_file( locate_root / "status/bin/config_info.test", + "config_info.output", dot_output_path, "gcc" ) + || find_file( locate_root / "status/bin/config_info.test", + "config_info.output", dot_output_path ) ) + { + fs::ifstream file( dot_output_path ); + if ( file ) + { + while( std::getline( file, result ) ) + { + if ( result.find( "Detected Platform: " ) == 0 ) + { + result.erase( 0, 19 ); + return result; + } + } + result.clear(); + } + } + return result; + } + +// version_desc ------------------------------------------------------------// +// from locate-root/status/bin/config_info.test/xxx/.../config_info.output + + string version_desc( const string & compiler_name ) + { + string result; + fs::path dot_output_path; + if ( find_file( locate_root / "status/bin/config_info.test" + / compiler_name, "config_info.output", dot_output_path ) ) + { + fs::ifstream file( dot_output_path ); + if ( file ) + { + if( std::getline( file, result ) ) + { + string::size_type pos = result.find( "version " ); + if ( pos != string::npos ) + { + result.erase( 0, pos+8 ); + } + else result.clear(); + } + } + } + return result; + } + +// compiler_desc -----------------------------------------------------------// +// from boost-root/tools/build/xxx-tools.jam + + string compiler_desc( const string & compiler_name ) + { + string result; + fs::path tools_path( boost_root / "tools/build" / (compiler_name + + "-tools.jam") ); + fs::ifstream file( tools_path ); + if ( file ) + { + while( std::getline( file, result ) ) + { + if ( result.substr( 0, 3 ) == "#//" ) + { + result.erase( 0, 3 ); + return result; + } + } + result.clear(); + } + return result; + } + +// target_directory --------------------------------------------------------// +// this amounts to a request to find a unique leaf directory + + fs::path target_directory( const fs::path & root ) + { + if ( !fs::exists( root ) ) return fs::path("no-such-path"); + fs::path child; + for ( fs::directory_iterator itr( root ); itr != end_itr; ++itr ) + { + if ( fs::is_directory( *itr ) ) + { + if ( child.empty() ) child = *itr; + else + { + std::cout << "Warning: only first of two target possibilities will be reported for: \n " + << root.string() << ": " << child.leaf() + << " and " << (*itr).leaf() << "\n"; + } + } + } + if ( child.empty() ) return root; // this dir has no children + return target_directory( child ); + } + +// element_content ---------------------------------------------------------// + + const string & element_content( + const xml::element_ptr & root, const string & name ) + { + static string empty_string; + xml::element_list::iterator itr; + for ( itr = root->elements.begin(); + itr != root->elements.end() && (*itr)->name != name; + ++itr ) {} + return itr != root->elements.end() ? (*itr)->content : empty_string; + } + +// find_attribute ----------------------------------------------------------// + +const string & attribute_value( const xml::element_ptr & element, + const string & attribute_name ) +{ + static const string empty_string; + xml::attribute_list::iterator atr; + for ( atr = element->attributes.begin(); + atr != element->attributes.end() && atr->name != attribute_name; + ++atr ) {} + return atr == element->attributes.end() ? empty_string : atr->value; +} + +// generate_report ---------------------------------------------------------// + + // return 0 if nothing generated, 1 otherwise, except 2 if compiler msgs + int generate_report( const xml::element_ptr & db, + const string & test_name, + const string & toolset, + bool pass, + bool always_show_run_output = false ) + { + // compile msgs sometimes modified, so make a local copy + string compile( (pass && no_warn) + ? empty_string : element_content( db, "compile" ) ); + + const string & link( pass ? empty_string : element_content( db, "link" ) ); + const string & run( (pass && !always_show_run_output) + ? empty_string : element_content( db, "run" ) ); + string lib( pass ? empty_string : element_content( db, "lib" ) ); + + // some compilers output the filename even if there are no errors or + // warnings; detect this if one line of output and it contains no space. + string::size_type pos = compile.find( '\n', 1 ); + if ( pos != string::npos && compile.size()-pos <= 2 + && compile.find( ' ' ) == string::npos ) compile.clear(); + + if ( lib.empty() && compile.empty() && link.empty() && run.empty() ) + return 0; + + int result = 1; // some kind of msg for sure + + // limit compile message length + if ( compile.size() > max_compile_msg_size ) + { + compile.erase( max_compile_msg_size ); + compile += "...\n (remainder deleted because of excessive size)\n"; + } + + links_file << "<h2><a name=\"" + << test_name << "-" << toolset << "\">" + << test_name << " / " << toolset << "</a></h2>\n"; + + if ( !compile.empty() ) + { + ++result; + links_file << "<h3>Compiler output:</h3><pre>" + << compile << "</pre>\n"; + } + if ( !link.empty() ) + links_file << "<h3>Linker output:</h3><pre>" << link << "</pre>\n"; + if ( !run.empty() ) + links_file << "<h3>Run output:</h3><pre>" << run << "</pre>\n"; + + static std::set< string > failed_lib_target_dirs; + if ( !lib.empty() ) + { + if ( lib[0] == '\n' ) lib.erase( 0, 1 ); + string lib_test_name( extract_test_name( lib ) ); + links_file << "<h3>Library build failure: </h3>\n" + "See <a href=\"#" << lib_test_name << "-" << toolset << "\">" + << lib_test_name << " / " << toolset << "</a>"; + + if ( failed_lib_target_dirs.find( lib ) == failed_lib_target_dirs.end() ) + { + failed_lib_target_dirs.insert( lib ); + fs::path pth( boost_root / lib / "test_log.xml" ); + fs::ifstream file( pth ); + if ( file ) + { + xml::element_ptr db = xml::parse( file, pth.string() ); + generate_report( db, lib_test_name, toolset, false ); + } + else + { + links_file << "<h2><a name=\"" + << lib_test_name << "-" << toolset << "\">" + << lib_test_name << " / " << toolset << "</a></h2>\n" + "test_log.xml not found\n"; + } + } + } + return result; + } + + // do_cell -----------------------------------------------------------------// + + bool do_cell( const fs::path & test_dir, + const string & test_name, + const string & toolset, + string & target, + bool always_show_run_output ) + // return true if any results except pass_msg + { + fs::path target_dir( target_directory( test_dir / toolset ) ); + bool pass = false; + + // missing jam residue + if ( fs::exists( target_dir / (test_name + ".test") ) ) pass = true; + else if ( !fs::exists( target_dir / "test_log.xml" ) ) + { + target += "<td>" + missing_residue_msg + "</td>"; + return true; + } + + int anything_generated = 0; + + if ( !no_links ) + { + fs::path pth( target_dir / "test_log.xml" ); + fs::ifstream file( pth ); + if ( !file ) // missing jam_log.xml + { + std::cerr << "Missing jam_log.xml in target:\n " + << target_dir.string() << "\n"; + target += "<td>"; + target += pass ? pass_msg : fail_msg; + target += "</td>"; + return pass; + } + xml::element_ptr db = xml::parse( file, pth.string() ); + + // generate bookmarked report of results, and link to it + anything_generated + = generate_report( db, test_name, toolset, pass, always_show_run_output ); + } + + target += "<td>"; + if ( anything_generated != 0 ) + { + target += "<a href=\""; + target += links_name; + target += "#"; + target += test_name; + target += "-"; + target += toolset; + target += "\">"; + target += pass ? (anything_generated < 2 ? pass_msg : warn_msg) : fail_msg; + target += "</a>"; + } + else target += pass ? pass_msg : fail_msg; + target += "</td>"; + return (anything_generated != 0) || !pass; + } + +// do_row ------------------------------------------------------------------// + + void do_row( + const fs::path & test_dir, // locate_root / "status/bin/any_test.test" + const string & test_name, // "any_test" + string & target ) + { + // get library name, test-type, test-program path, etc., from the .xml file + string lib_name; + string test_path( test_name ); // test_name is default if missing .test + string test_type( "unknown" ); + bool always_show_run_output( false ); + fs::path xml_file_path; + if ( find_file( test_dir, "test_log.xml", xml_file_path ) ) + { + fs::ifstream file( xml_file_path ); + if ( file ) + { + xml::element_ptr db = xml::parse( file, xml_file_path.string() ); + test_path = attribute_value( db, "test-program" ); + lib_name = attribute_value( db, "library" ); + test_type = attribute_value( db, "test-type" ); + always_show_run_output + = attribute_value( db, "show-run-output" ) == "true"; + } + } + + // path to docs + fs::path rel; + relative_path( fs::initial_path(), boost_root, rel ); + string lib_docs_path( rel.string() + "/libs/" + lib_name ); + + // generate the library name, test name, and test type table data + string::size_type row_start_pos = target.size(); + target += "<tr><td><a href=\"" + lib_docs_path + "\">" + lib_name + "</a></td>"; + target += "<td><a href=\"" + (rel / test_path).string() + "\">" + test_name + "</a></td>"; + target += "<td>" + test_type + "</td>"; + + bool no_warn_save = no_warn; + if ( test_type.find( "fail" ) != string::npos ) no_warn = true; + + // for each compiler, generate <td>...</td> html + bool anything_to_report = false; + for ( std::vector<string>::const_iterator itr=toolsets.begin(); + itr != toolsets.end(); ++itr ) + { + anything_to_report |= do_cell( test_dir, test_name, *itr, target, + always_show_run_output ); + } + + target += "</tr>"; + if ( ignore_pass && !anything_to_report ) target.erase( row_start_pos ); + no_warn = no_warn_save; + } + +// do_rows_for_sub_tree ----------------------------------------------------// + + void do_rows_for_sub_tree( + const fs::path & bin_dir, std::vector<string> & results ) + { + for ( fs::directory_iterator itr( bin_dir ); itr != end_itr; ++itr ) + { + if ( fs::is_directory( *itr ) + && itr->string().find( ".test" ) == (itr->string().size()-5) ) + { + results.push_back( std::string() ); + do_row( *itr, + itr->leaf().substr( 0, itr->leaf().size()-5 ), + results[results.size()-1] ); + } + } + } + +// do_table_body -----------------------------------------------------------// + + void do_table_body( const fs::path & bin_dir ) + { + // rows are held in a vector so they can be sorted, if desired. + std::vector<string> results; + + // do primary bin directory + do_rows_for_sub_tree( bin_dir, results ); + + // do subinclude bin directories + jamfile.clear(); + jamfile.seekg(0); + string line; + while( std::getline( jamfile, line ) ) + { + string::size_type pos( line.find( "subinclude" ) ); + if ( pos != string::npos + && line.find( '#' ) > pos ) + { + pos = line.find_first_not_of( " \t", pos+10 ); + if ( pos == string::npos ) continue; + string subinclude_bin_dir( + line.substr( pos, line.find_first_of( " \t", pos )-pos ) ); +// std::cout << "subinclude: " << subinclude_bin_dir << '\n'; + fs::path subinclude_path( locate_root / subinclude_bin_dir / "/bin" ); + if ( fs::exists( subinclude_path ) ) + { do_rows_for_sub_tree( subinclude_path, results ); } + } + } + + + std::sort( results.begin(), results.end() ); + + for ( std::vector<string>::iterator v(results.begin()); + v != results.end(); ++v ) + { report << *v << "\n"; } + } + +// do_table ----------------------------------------------------------------// + + void do_table() + { + string relative( fs::initial_path().string() ); + relative.erase( 0, boost_root.string().size()+1 ); + fs::path bin_path( locate_root / relative / "bin" ); + + report << "<table border=\"1\" cellspacing=\"0\" cellpadding=\"5\">\n"; + + // generate the column headings + + report << "<tr><td>Library</td><td>Test Name</td>\n" + "<td><a href=\"compiler_status.html#test-type\">Test Type</a></td>\n"; + + fs::directory_iterator itr( bin_path ); + while ( itr != end_itr && !fs::is_directory( *itr ) + && itr->string().find( ".test" ) != (itr->string().size()-5) ) + ++itr; // bypass chaff + if ( itr != end_itr ) + { + fs::directory_iterator compiler_itr( *itr ); + if ( specific_compiler.empty() ) + std::clog << "Using " << itr->string() << " to determine compilers\n"; + for (; compiler_itr != end_itr; ++compiler_itr ) + { + if ( fs::is_directory( *compiler_itr ) // check just to be sure + && compiler_itr->leaf() != "test" ) // avoid strange directory (Jamfile bug?) + { + if ( specific_compiler.size() != 0 + && specific_compiler != compiler_itr->leaf() ) continue; + toolsets.push_back( compiler_itr->leaf() ); + string desc( compiler_desc( compiler_itr->leaf() ) ); + string vers( version_desc( compiler_itr->leaf() ) ); + report << "<td>" + << (desc.size() ? desc : compiler_itr->leaf()) + << (vers.size() ? (string( "<br>" ) + vers ) : string( "" )) + << "</td>\n"; + } + } + } + + report << "</tr>\n"; + + // now the rest of the table body + + do_table_body( bin_path ); + + report << "</table>\n"; + } + +} // unnamed namespace + +// main --------------------------------------------------------------------// + +#define BOOST_NO_CPP_MAIN_SUCCESS_MESSAGE +#include <boost/test/included/prg_exec_monitor.hpp> + +int cpp_main( int argc, char * argv[] ) // note name! +{ + while ( argc > 1 && *argv[1] == '-' ) + { + if ( argc > 2 && std::strcmp( argv[1], "--compiler" ) == 0 ) + { specific_compiler = argv[2]; --argc; ++argv; } + else if ( argc > 2 && std::strcmp( argv[1], "--locate-root" ) == 0 ) + { locate_root = fs::path( argv[2], fs::native ); --argc; ++argv; } + else if ( std::strcmp( argv[1], "--ignore-pass" ) == 0 ) ignore_pass = true; + else if ( std::strcmp( argv[1], "--no-warn" ) == 0 ) no_warn = true; + else { std::cerr << "Unknown option: " << argv[1] << "\n"; argc = 1; } + --argc; + ++argv; + } + + if ( argc != 3 && argc != 4 ) + { + std::cerr << + "Usage: compiler_status [options...] boost-root status-file [links-file]\n" + " boost-root is the path to the boost tree root directory.\n" + " status-file and links-file are paths to the output files.\n" + "Must be run from directory containing Jamfile\n" + " options: --compiler name Run for named compiler only\n" + " --ignore-pass Do not report tests which pass all compilers\n" + " --no-warn Warnings not reported if test passes\n" + " --locate-root path Path to ALL_LOCATE_TARGET for bjam;\n" + " default boost-root.\n" + "example: compiler_status --compiler gcc /boost-root cs.html cs-links.html\n"; + return 1; + } + + boost_root = fs::path( argv[1], fs::native ); + if ( locate_root.empty() ) locate_root = boost_root; + + fs::path jamfile_path( fs::initial_path() / "Jamfile" ); + jamfile.open( jamfile_path ); + if ( !jamfile ) + { + std::cerr << "Could not open Jamfile: " << jamfile_path.native_file_string() << std::endl; + return 1; + } + + report.open( fs::path( argv[2], fs::native ) ); + if ( !report ) + { + std::cerr << "Could not open report output file: " << argv[2] << std::endl; + return 1; + } + + if ( argc == 4 ) + { + fs::path links_path( argv[3], fs::native ); + links_name = links_path.leaf(); + links_file.open( links_path ); + if ( !links_file ) + { + std::cerr << "Could not open links output file: " << argv[3] << std::endl; + return 1; + } + } + else no_links = true; + + char run_date[128]; + std::time_t tod; + std::time( &tod ); + std::strftime( run_date, sizeof(run_date), + "%X UTC, %A %d %B %Y", std::gmtime( &tod ) ); + + report << "<html>\n" + "<head>\n" + "<title>Boost Compiler Status Automatic Test</title>\n" + "</head>\n" + "<body bgcolor=\"#ffffff\" text=\"#000000\">\n" + "<table border=\"0\">\n" + "<tr>\n" + "<td><img border=\"0\" src=\"../c++boost.gif\" width=\"277\" " + "height=\"86\"></td>\n" + "<td>\n" + "<h1>Compiler Status: " + platform_desc() + "</h1>\n" + "<b>Run Date:</b> " + << run_date + << "\n</td>\n</table>\n<br>\n" + ; + + if ( !no_links ) + { + links_file + << "<html>\n" + "<head>\n" + "<title>Boost Compiler Status Error Log</title>\n" + "</head>\n" + "<body bgcolor=\"#ffffff\" text=\"#000000\">\n" + "<table border=\"0\">\n" + "<tr>\n" + "<td><img border=\"0\" src=\"../c++boost.gif\" width=\"277\" " + "height=\"86\"></td>\n" + "<td>\n" + "<h1>Compiler Status: " + platform_desc() + "</h1>\n" + "<b>Run Date:</b> " + << run_date + << "\n</td>\n</table>\n<br>\n" + ; + } + + do_table(); + + report << "</body>\n" + "</html>\n" + ; + + if ( !no_links ) + { + links_file + << "</body>\n" + "</html>\n" + ; + } + return 0; +} diff --git a/tools/regression/detail/tiny_xml.cpp b/tools/regression/detail/tiny_xml.cpp new file mode 100644 index 0000000000..25ea9f6f2f --- /dev/null +++ b/tools/regression/detail/tiny_xml.cpp @@ -0,0 +1,160 @@ +// tiny XML sub-set tools implementation -----------------------------------// + +// (C) Copyright Beman Dawes 2002. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +#include "tiny_xml.hpp" +#include <cassert> + +namespace +{ + + void eat_whitespace( char & c, std::istream & in ) + { + while ( c == ' ' || c == '\r' || c == '\n' || c == '\t' ) + in.get( c ); + } + + std::string get_name( char & c, std::istream & in ) + { + std::string result; + eat_whitespace( c, in ); + while ( std::strchr( + "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.", c ) + != 0 ) + { + result += c; + in.get( c ); + } + return result; + } + + void eat_delim( char & c, std::istream & in, + char delim, const std::string & msg ) + { + eat_whitespace( c, in ); + if ( c != delim ) + throw std::string("xml syntax error, expected ") + delim + + " (" + msg + ")"; + in.get( c ); + } + + std::string get_value( char & c, std::istream & in ) + { + std::string result; + while ( c != '\"' ) + { + result += c; + in.get( c ); + } + in.get( c ); + return result; + } + +} + +namespace boost +{ + namespace tiny_xml + { + + // parse -----------------------------------------------------------------// + + element_ptr parse( std::istream & in, const std::string & msg ) + { + char c = 0; // current character + element_ptr e( new element ); + + in.get( c ); + if ( c == '<' ) in.get( c ); + + e->name = get_name( c, in ); + eat_whitespace( c, in ); + + // attributes + while ( c != '>' ) + { + attribute a; + a.name = get_name( c, in ); + + eat_delim( c, in, '=', msg ); + eat_delim( c, in, '\"', msg ); + + a.value = get_value( c, in ); + + e->attributes.push_back( a ); + eat_whitespace( c, in ); + } + in.get( c ); // next after '>' + eat_whitespace( c, in ); + + // sub-elements + while ( c == '<' ) + { + if ( in.peek() == '/' ) break; + e->elements.push_back( parse( in, msg ) ); + in.get( c ); // next after '>' + eat_whitespace( c, in ); + } + + // content + if ( c != '<' ) + { + e->content += '\n'; + while ( c != '<' ) + { + e->content += c; + in.get( c ); + } + } + + assert( c == '<' ); + in.get( c ); // next after '<' + + eat_delim( c, in, '/', msg ); + std::string end_name( get_name( c, in ) ); + if ( e->name != end_name ) + throw std::string("xml syntax error: beginning name ") + + e->name + " did not match end name " + end_name + + " (" + msg + ")"; + + eat_delim( c, in, '>', msg ); + return e; + } + + // write ---------------------------------------------------------------// + + void write( const element & e, std::ostream & out ) + { + out << "<" << e.name; + if ( !e.attributes.empty() ) + { + for( attribute_list::const_iterator itr = e.attributes.begin(); + itr != e.attributes.end(); ++itr ) + { + out << " " << itr->name << "=\"" << itr->value << "\""; + } + } + out << ">"; + if ( !e.elements.empty() ) + { + out << "\n"; + for( element_list::const_iterator itr = e.elements.begin(); + itr != e.elements.end(); ++itr ) + { + write( **itr, out ); + } + } + if ( !e.content.empty() ) + { + out << e.content; + } + out << "</" << e.name << ">\n"; + } + + } // namespace tiny_xml +} // namespace boost + diff --git a/tools/regression/detail/tiny_xml.hpp b/tools/regression/detail/tiny_xml.hpp new file mode 100644 index 0000000000..e6fce847e6 --- /dev/null +++ b/tools/regression/detail/tiny_xml.hpp @@ -0,0 +1,72 @@ +// tiny XML sub-set tools --------------------------------------------------// + +// (C) Copyright Beman Dawes 2002. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +// Provides self-contained tools for this XML sub-set: +// +// element ::= { "<" name { name "=" "\"" value "\"" } ">" +// {element} [contents] "</" name ">" } +// +// The point of "self-contained" is to minimize tool-chain dependencies. + +#ifndef BOOST_TINY_XML_H +#define BOOST_TINY_XML_H + +#include "boost/smart_ptr.hpp" // for shared_ptr +#include "boost/utility.hpp" // for noncopyable +#include <list> +#include <iostream> +#include <string> + +namespace boost +{ + namespace tiny_xml + { + class element; + struct attribute + { + std::string name; + std::string value; + + attribute(){} + attribute( const std::string & name, const std::string & value ) + : name(name), value(value) {} + }; + typedef boost::shared_ptr< element > element_ptr; + typedef std::list< element_ptr > element_list; + typedef std::list< attribute > attribute_list; + + class element + : boost::noncopyable // because deep copy sematics would be required + { + public: + std::string name; + attribute_list attributes; + element_list elements; + std::string content; + + element() {} + explicit element( const std::string & name ) : name(name) {} + }; + + element_ptr parse( std::istream & in, const std::string & msg ); + // Precondition: stream positioned at either the initial "<" + // or the first character after the initial "<". + // Postcondition: stream positioned at the first character after final + // ">" (or eof). + // Returns: an element_ptr to an element representing the parsed stream. + // Throws: std::string on syntax error. msg appended to what() string. + + void write( const element & e, std::ostream & out ); + + } +} + +#endif // BOOST_TINY_XML_H + + + diff --git a/tools/regression/detail/tiny_xml_test.cpp b/tools/regression/detail/tiny_xml_test.cpp new file mode 100644 index 0000000000..6165c5c18e --- /dev/null +++ b/tools/regression/detail/tiny_xml_test.cpp @@ -0,0 +1,19 @@ +// tiny XML test program ---------------------------------------------------// + +// (C) Copyright Beman Dawes 2002. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +#include "tiny_xml.hpp" + +#include <iostream> + +int main() +{ + boost::tiny_xml::element_ptr tree( boost::tiny_xml::parse( std::cin ) ); + boost::tiny_xml::write( *tree, std::cout ); + return 0; +} + diff --git a/tools/regression/detail/tiny_xml_test.txt b/tools/regression/detail/tiny_xml_test.txt new file mode 100644 index 0000000000..25bc531e0b --- /dev/null +++ b/tools/regression/detail/tiny_xml_test.txt @@ -0,0 +1,12 @@ +<root> +<element-1 at-1="abcd" at-2 = "defg" > +<element-1a> +It's Howdy Doody time! +</element-1a> +<element-1b>It's not Howdy Doody time!</element-1b> +</element-1> +<element-2> +It's +Eastern Standard time! +</element-2> +</root> diff --git a/tools/regression/index.htm b/tools/regression/index.htm new file mode 100644 index 0000000000..5c436b4ace --- /dev/null +++ b/tools/regression/index.htm @@ -0,0 +1,44 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> +<title>Regression Test Reporting Tools</title> +</head> + +<body bgcolor="#FFFFFF"> + +<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" +align="center" width="277" height="86"> Regression Test Reporting +Tools</h1> + +<p>Boost regression testing uses <a href="../build/index.html">Boost.Build</a> +to run the actual builds and tests. A separate set of tools is +used to generate the actual status reports.</p> + +<ul> + <li>Regression test <a href="../../more/regression.html">user + documentation</a>.</li> + <li><a href="process_jam_log.cpp">process_jam_log.cpp</a> - + Processes the bjam outputs, creating a file named + test_log.xml for each test encountered.</li> + <li><a href="compiler_status.cpp">compiler_status.cpp</a> - + Generates HTML status tables from test_log.xml and other + files.</li> + <li><a href="build/Jamfile">Jamfile</a> - Builds + process_jam_log and compiler_status executables.</li> + <li><a href="run_tests.sh">run_tests.sh</a> - An example + shell script for running the tests and generating HTML + reports.</li> +</ul> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" startspan s-type="EDITED" +s-format="%d %B, %Y" -->09 January, 2003<!--webbot bot="Timestamp" +i-checksum="38582" endspan --></p> +</body> +</html> diff --git a/tools/regression/index.shtml b/tools/regression/index.shtml new file mode 100644 index 0000000000..f6fa0e9e5f --- /dev/null +++ b/tools/regression/index.shtml @@ -0,0 +1,25 @@ +<!-- +This is the page wrapper for the summary table of regression tests. +This calls the script "regression-logs.pl" to generate the summary +table. This file should be place at: + http://boost.sourceforge.net/regression-logs/index.shtml +Which is at this location in the shell SourceForge services: + /home/groups/b/bo/boost/htdocs/regression-logs/index.shtml +--> +<html> +<head> +<title>Boost Regression Tests</title> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> +<table border="0"> +<tr> +<td><img border="0" src="../c++boost.gif" width="277" height="86"></td> +<td> +<h1>Boost Regression Tests</h1> +</td> +</table> +<!--#include virtual="/cgi-bin/regression-logs.pl" --> +</body> +</html> diff --git a/tools/regression/process_jam_log.cpp b/tools/regression/process_jam_log.cpp new file mode 100644 index 0000000000..0c33e975b5 --- /dev/null +++ b/tools/regression/process_jam_log.cpp @@ -0,0 +1,546 @@ +// process jam regression test output into XML -----------------------------// + +// (C) Copyright Beman Dawes 2002. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +#include "detail/tiny_xml.hpp" +#include "boost/filesystem/operations.hpp" +#include "boost/filesystem/fstream.hpp" +#include "boost/filesystem/exception.hpp" + +#include <iostream> +#include <string> +#include <map> +#include <utility> // for make_pair +#include <ctime> +#include <cctype> // for tolower + +using std::string; +namespace xml = boost::tiny_xml; +namespace fs = boost::filesystem; + +#define BOOST_NO_CPP_MAIN_SUCCESS_MESSAGE +#include <boost/test/included/prg_exec_monitor.hpp> + +namespace +{ + struct test_info + { + string file_path; // relative boost-root + string type; + bool always_show_run_output; + }; + typedef std::map< string, test_info > test2info_map; // key is test-name + test2info_map test2info; + + fs::path boost_root; + fs::path locate_root; // ALL_LOCATE_TARGET (or boost_root if none) + +// append_html -------------------------------------------------------------// + + void append_html( const string & src, string & target ) + { + // there are a few lines we want to ignore + if ( src.find( "th target..." ) != string::npos + || src.find( "cc1plus.exe: warning: changing search order for system directory" ) != string::npos + || src.find( "cc1plus.exe: warning: as it has already been specified as a non-system directory" ) != string::npos + ) return; + + for ( string::size_type pos = 0; pos < src.size(); ++pos ) + { + if ( src[pos] == '<' ) target += "<"; + else if ( src[pos] == '>' ) target += ">"; + else if ( src[pos] == '&' ) target += "&"; + else target += src[pos]; + } + } + + // timestamp ---------------------------------------------------------------// + + string timestamp() + { + char run_date[128]; + std::time_t tod; + std::time( &tod ); + std::strftime( run_date, sizeof(run_date), + "%Y-%m-%d %X UTC", std::gmtime( &tod ) ); + return string( run_date ); + } + +// convert path separators to forward slashes ------------------------------// + + void convert_path_separators( string & s ) + { + for ( string::iterator itr = s.begin(); itr != s.end(); ++itr ) + if ( *itr == '\\' || *itr == '!' ) *itr = '/'; + } + +// extract a target directory path from a jam target string ----------------// +// s may be relative to the initial_path: +// ..\..\..\libs\foo\build\bin\libfoo.lib\vc7\debug\runtime-link-dynamic\boo.obj +// s may be absolute: +// d:\myboost\libs\foo\build\bin\libfoo.lib\vc7\debug\runtime-link-dynamic\boo.obj +// return path is always relative to the boost directory tree: +// libs/foo/build/bin/libfs.lib/vc7/debug/runtime-link-dynamic + + string target_directory( const string & s ) + { + string temp( s ); + convert_path_separators( temp ); + temp.erase( temp.find_last_of( "/" ) ); // remove leaf + string::size_type pos = temp.find_last_of( " " ); // remove leading spaces + if ( pos != string::npos ) temp.erase( 0, pos+1 ); + if ( temp[0] == '.' ) temp.erase( 0, temp.find_first_not_of( "./" ) ); + else temp.erase( 0, locate_root.string().size()+1 ); +//std::cout << "\"" << s << "\", \"" << temp << "\"" << std::endl; + return temp; + } + + string toolset( const string & s ) + { + string t( s ); + string::size_type pos = t.find( "/bin/" ); + if ( pos != string::npos ) pos += 5; + else return ""; + pos = t.find( "/", pos ); + if ( pos != string::npos ) pos += 1; + else return ""; + return t.substr( pos, t.find( "/", pos ) - pos ); + } + + string test_name( const string & s ) + { + string t( s ); + string::size_type pos = t.find( "/bin/" ); + if ( pos != string::npos ) pos += 5; + else return ""; + return t.substr( pos, t.find( ".", pos ) - pos ); + } + + // the format of paths is really kinky, so convert to normal form + // first path is missing the leading "..\". + // first path is missing "\bin" after "status". + // second path is missing the leading "..\". + // second path is missing "\bin" after "build". + // second path uses "!" for some separators. + void parse_skipped_msg( const string & msg, + string & first_dir, string & second_dir ) + { + first_dir.clear(); + second_dir.clear(); + string::size_type start_pos( msg.find( '<' ) ); + if ( start_pos == string::npos ) return; + ++start_pos; + string::size_type end_pos( msg.find( '>', start_pos ) ); + first_dir += msg.substr( start_pos, end_pos - start_pos ); + start_pos = first_dir.rfind( '!' ); + convert_path_separators( first_dir ); + first_dir.insert( first_dir.find( '/', start_pos + 1), "/bin" ); +//std::cout << first_dir << std::endl; + + start_pos = msg.find( '<', end_pos ); + if ( start_pos == string::npos ) return; + ++start_pos; + end_pos = msg.find( '>', start_pos ); + second_dir += msg.substr( start_pos, end_pos - start_pos ); + start_pos = second_dir.rfind( '!' ); + convert_path_separators( second_dir ); + second_dir.insert( second_dir.find( '/', start_pos + 1), "/bin" ); +//std::cout << second_dir << std::endl; + } + +// test_log hides database details -----------------------------------------// + + class test_log + : boost::noncopyable + { + const string & m_target_directory; + xml::element_ptr m_root; + public: + test_log( const string & target_directory, + const string & test_name, + const string & toolset ) + : m_target_directory( target_directory ) + { + fs::path pth( locate_root / target_directory / "test_log.xml" ); + fs::ifstream file( pth ); + if ( file ) // existing file + { + try + { + m_root = xml::parse( file, pth.string() ); + return; + } + catch(...) + { + // unable to parse existing XML file, fall through + } + } + + test_info info; + string library_name; + test2info_map::iterator itr( test2info.find( test_name ) ); + if ( itr != test2info.end() ) + { + info = itr->second; + string::size_type start_pos( info.file_path.find( "libs/" ) ); + if ( start_pos != string::npos ) + { + start_pos += 5; + string::size_type end_pos( info.file_path.find( '/', start_pos ) ); + library_name = info.file_path.substr( start_pos, + end_pos - start_pos ); + + if ( fs::exists( boost_root / "libs" / library_name / "sublibs" ) ) + { + library_name += info.file_path.substr( end_pos, + info.file_path.find( '/', end_pos+1 ) - end_pos ); + } + } + } + m_root.reset( new xml::element( "test-log" ) ); + m_root->attributes.push_back( + xml::attribute( "library", library_name ) ); + m_root->attributes.push_back( + xml::attribute( "test-name", test_name ) ); + m_root->attributes.push_back( + xml::attribute( "test-type", info.type ) ); + m_root->attributes.push_back( + xml::attribute( "test-program", info.file_path ) ); + m_root->attributes.push_back( + xml::attribute( "target-directory", target_directory ) ); + m_root->attributes.push_back( + xml::attribute( "toolset", toolset ) ); + m_root->attributes.push_back( + xml::attribute( "show-run-output", + info.always_show_run_output ? "true" : "false" ) ); + } + + ~test_log() + { + fs::path pth( locate_root / m_target_directory / "test_log.xml" ); + fs::ofstream file( pth ); + if ( !file ) + throw fs::filesystem_error( "process_jam_long.cpp", + pth, "can't open output file" ); + xml::write( *m_root, file ); + } + + const string & target_directory() const { return m_target_directory; } + + void remove_action( const string & action_name ) + // no effect if action_name not found + { + xml::element_list::iterator itr; + for ( itr = m_root->elements.begin(); + itr != m_root->elements.end() && (*itr)->name != action_name; + ++itr ) {} + if ( itr != m_root->elements.end() ) m_root->elements.erase( itr ); + } + + void add_action( const string & action_name, + const string & result, + const string & timestamp, + const string & content ) + { + remove_action( action_name ); + xml::element_ptr action( new xml::element(action_name) ); + m_root->elements.push_back( action ); + action->attributes.push_back( xml::attribute( "result", result ) ); + action->attributes.push_back( xml::attribute( "timestamp", timestamp ) ); + action->content = content; + } + }; + +// message_manager maps input messages into test_log actions ---------------// + + class message_manager + : boost::noncopyable + { + string m_action_name; // !empty() implies action pending + // IOW, a start_message awaits stop_message + string m_target_directory; + string m_test_name; + string m_toolset; + + bool m_note; // if true, run result set to "note" + // set false by start_message() + + // data needed to stop further compile action after a compile failure + // detected in the same target directory + string m_previous_target_directory; + bool m_compile_failed; + + public: + message_manager() : m_note(false) {} + ~message_manager() { /*assert( m_action_name.empty() );*/ } + + bool note() const { return m_note; } + void note( bool value ) { m_note = value; } + + void start_message( const string & action_name, + const string & target_directory, + const string & test_name, + const string & toolset, + const string & prior_content ) + { + if ( !m_action_name.empty() ) stop_message( prior_content ); + m_action_name = action_name; + m_target_directory = target_directory; + m_test_name = test_name; + m_toolset = toolset; + m_note = false; + if ( m_previous_target_directory != target_directory ) + { + m_previous_target_directory = target_directory; + m_compile_failed = false; + } + } + + void stop_message( const string & content ) + { + if ( m_action_name.empty() ) return; + stop_message( m_action_name, m_target_directory, + "succeed", timestamp(), content ); + } + + void stop_message( const string & action_name, + const string & target_directory, + const string & result, + const string & timestamp, + const string & content ) + // the only valid action_names are "compile", "link", "run", "lib" + { + // My understanding of the jam output is that there should never be + // a stop_message that was not preceeded by a matching start_message. + // That understanding is built into message_manager code. + assert( m_action_name == action_name ); + assert( m_target_directory == target_directory ); + assert( result == "succeed" || result == "fail" ); + + // if test_log.xml entry needed, create it + if ( !m_compile_failed + || action_name != "compile" + || m_previous_target_directory != target_directory ) + { + if ( action_name == "compile" + && result == "fail" ) m_compile_failed = true; + + test_log tl( target_directory, m_test_name, m_toolset ); + + // dependency removal + if ( action_name == "lib" ) + { + tl.remove_action( "compile" ); + tl.remove_action( "link" ); + tl.remove_action( "run" ); + } + else if ( action_name == "compile" ) + { + tl.remove_action( "link" ); + tl.remove_action( "run" ); + if ( result == "fail" ) m_compile_failed = true; + } + else if ( action_name == "link" ) { tl.remove_action( "run" ); } + + // dependency removal won't work right with random names, so assert + else { assert( action_name == "run" ); } + + // add the "run" stop_message action + tl.add_action( action_name, + result == "succeed" && note() ? "note" : result, + timestamp, content ); + } + + m_action_name = ""; // signal no pending action + m_previous_target_directory = target_directory; + } + }; +} + +// main --------------------------------------------------------------------// + +int cpp_main( int argc, char ** argv ) +{ + if ( argc <= 1 ) + std::cout << "Usage: bjam [bjam-args] | process_jam_log [locate-root]\n" + " locate-root is the same as the bjam ALL_LOCATE_TARGET\n" + " parameter, if any. Default is boost-root.\n"; + + boost_root = fs::initial_path(); + + while ( !boost_root.empty() + && !fs::exists( boost_root / "libs" ) ) + { + boost_root /= ".."; + } + + if ( boost_root.empty() ) + { + std::cout << "must be run from within the boost-root directory tree\n"; + return 1; + } + + locate_root = argc > 1 + ? fs::path( argv[1], fs::native ) + : boost_root; + + std::cout << "boost_root: " << boost_root.string() << '\n' + << "locate_root: " << locate_root.string() << '\n'; + + message_manager mgr; + + string line; + string content; + bool capture_lines = false; + + // This loop looks at lines for certain signatures, and accordingly: + // * Calls start_message() to start capturing lines. (start_message() will + // automatically call stop_message() if needed.) + // * Calls stop_message() to stop capturing lines. + // * Capture lines if line capture on. + + while ( std::getline( std::cin, line ) ) + { + // std::cout << line << "\n"; + + // create map of test-name to test-info + if ( line.find( "boost-test(" ) == 0 ) + { + string::size_type pos = line.find( '"' ); + string test_name( line.substr( pos+1, line.find( '"', pos+1)-pos-1 ) ); + test_info info; + info.always_show_run_output + = line.find( "\"always_show_run_output\"" ) != string::npos; + info.type = line.substr( 11, line.find( ')' )-11 ); + for (unsigned int i = 0; i!=info.type.size(); ++i ) + { info.type[i] = std::tolower( info.type[i] ); } + pos = line.find( ':' ); + info.file_path = line.substr( pos+3, + line.find( "\"", pos+3 )-pos-3 ); + convert_path_separators( info.file_path ); + if ( info.file_path.find( "libs/libs/" ) == 0 ) info.file_path.erase( 0, 5 ); + test2info.insert( std::make_pair( test_name, info ) ); +// std::cout << test_name << ", " << info.type << ", " << info.file_path << "\n"; + continue; + } + + // these actions represent both the start of a new action + // and the end of a failed action + else if ( line.find( "C++-action " ) != string::npos + || line.find( "vc-C++ " ) != string::npos + || line.find( "C-action " ) != string::npos + || line.find( "Cc-action " ) != string::npos + || line.find( "vc-Cc " ) != string::npos + || line.find( "Link-action " ) != string::npos + || line.find( "vc-Link " ) != string::npos ) + { + string action( ( line.find( "Link-action " ) != string::npos + || line.find( "vc-Link " ) != string::npos ) + ? "link" : "compile" ); + if ( line.find( "...failed " ) != string::npos ) + mgr.stop_message( action, target_directory( line ), + "fail", timestamp(), content ); + else + { + string target_dir( target_directory( line ) ); + mgr.start_message( action, target_dir, + test_name( target_dir ), toolset( target_dir ), content ); + } + content = "\n"; + capture_lines = true; + } + + // these actions are only used to stop the previous action + else if ( line.find( "-Archive" ) != string::npos + || line.find( "MkDir" ) == 0 ) + { + mgr.stop_message( content ); + content.clear(); + capture_lines = false; + } + + else if ( line.find( "execute-test" ) != string::npos ) + { + if ( line.find( "...failed " ) != string::npos ) + { + mgr.stop_message( "run", target_directory( line ), + "fail", timestamp(), content ); + content = "\n"; + capture_lines = true; + } + else + { + string target_dir( target_directory( line ) ); + mgr.start_message( "run", target_dir, + test_name( target_dir ), toolset( target_dir ), content ); + + // contents of .output file for content + capture_lines = false; + content = "\n"; + fs::ifstream file( locate_root / target_dir + / (test_name(target_dir) + ".output") ); + if ( file ) + { + string ln; + while ( std::getline( file, ln ) ) + { + if ( ln.find( "<note>" ) != string::npos ) mgr.note( true ); + append_html( ln, content ); + content += "\n"; + } + } + } + } + + // bjam indicates some prior dependency failed by a "...skipped" message + else if ( line.find( "...skipped <" ) != string::npos ) + { + mgr.stop_message( content ); + content.clear(); + capture_lines = false; + + if ( line.find( " for lack of " ) != string::npos + && line.find( ".run for lack of " ) == string::npos ) + { + capture_lines = true; + + string target_dir; + string lib_dir; + + parse_skipped_msg( line, target_dir, lib_dir ); + + if ( target_dir != lib_dir ) // it's a lib problem + { + mgr.start_message( "lib", target_dir, + test_name( target_dir ), toolset( target_dir ), content ); + content = lib_dir; + mgr.stop_message( "lib", target_dir, "fail", timestamp(), content ); + content = "\n"; + } + } + + } + + else if ( line.find( "**passed**" ) != string::npos + || line.find( "failed-test-file " ) != string::npos + || line.find( "command-file-dump" ) != string::npos ) + { + mgr.stop_message( content ); + content = "\n"; + capture_lines = true; + } + + else if ( capture_lines ) // hang onto lines for possible later use + { + append_html( line, content );; + content += "\n"; + } + } + + mgr.stop_message( content ); + return 0; +} diff --git a/tools/regression/regression-logs.pl b/tools/regression/regression-logs.pl new file mode 100644 index 0000000000..7cf1889481 --- /dev/null +++ b/tools/regression/regression-logs.pl @@ -0,0 +1,165 @@ +#!/usr/bin/perl +# Copyright (C) 2003, Rene Rivera. Permission to copy, use, modify, sell and +# distribute this software is granted provided this copyright notice appears in +# all copies. This software is provided "as is" without express or implied +# warranty, and with no claim as to its suitability for any purpose. + +# This the cgi script that generates the live summary page for the regression +# logs located at http://boost.sourceforge.net/regression-logs +# +# Per SourceForge requirements this script needs to be located in the cgi-bin +# directory (/home/groups/b/bo/boost/cgi-bin) for it to be recognized as a script. +# +# This script only generates the summary table of the test. It doesn not generate +# the entire HTML page. For the complete page this script is called, with SSI, from +# the "index.shtml" page which contains the wrapping page. This makes it easier to +# mainting the table independently of the rest of the page. + +use FileHandle; +use Time::Local; + +print "Content-type: text/html\r\n\r\n"; + +# Generate an individual result item, Pass, Warn, and Fail columns. +# Use as: result_info(html-color,result-count,total-count) +# +sub result_info +{ + my ($color,$result,$total) = @_; + my $percent = int (($result/$total)*100+0.5); + return "<font color=\"$color\"><font size=\"+1\">$percent%</font><br>($result)</font>"; +} + +# Generate an age highlighted run date string. +# Use as: data_info(run-date-html) +# +sub date_info +{ + my %m = ('January',0,'February',1,'March',2,'April',3,'May',4,'June',5, + 'July',6,'August',7,'September',8,'October',9,'November',10,'December',11); + my @d = split(/ |:/,$_[0]); + my ($hour,$min,$sec,$day,$month,$year) = ($d[0],$d[1],$d[2],$d[4],$m{$d[5]},$d[6]); + #print "<!-- $hour.$min.$sec.$day.$month.$year -->\n"; + my $test_t = timegm($sec,$min,$hour,$day,$month,$year); + my $age = time-$test_t; + my $age_days = $age/(60*60*24); + #print "<!-- $age_days days old -->\n"; + my $age = "<font>"; + if ($age_days <= 2) { } + elsif ($age_days <= 14) { $age = "<font color=\"#FF9900\">"; } + else { $age = "<font color=\"#FF0000\">"; } + return $age.$_[0]."</font>"; +} + +# Generate an age string based on the run date. +# Use as: age_info(run-date-html) +# +sub age_info +{ + my %m = ('January',0,'February',1,'March',2,'April',3,'May',4,'June',5, + 'July',6,'August',7,'September',8,'October',9,'November',10,'December',11); + my @d = split(/ |:/,$_[0]); + my ($hour,$min,$sec,$day,$month,$year) = ($d[0],$d[1],$d[2],$d[4],$m{$d[5]},$d[6]); + #print "<!-- $hour.$min.$sec.$day.$month.$year -->\n"; + my $test_t = timegm($sec,$min,$hour,$day,$month,$year); + my $age = time-$test_t; + my $age_days = $age/(60*60*24); + #print "<!-- $age_days days old -->\n"; + my $age = "<font>"; + if ($age_days <= 2) { } + elsif ($age_days <= 14) { $age = "<font color=\"#FF9900\">"; } + else { $age = "<font color=\"#FF0000\">"; } + if ($age_days <= 1) { $age = $age."today"; } + elsif ($age_days <= 2) { $age = $age."yesterday"; } + elsif ($age_days < 14) { my $days = int $age_days; $age = $age.$days." days"; } + elsif ($age_days < 7*8) { my $weeks = int $age_days/7; $age = $age.$weeks." weeks"; } + else { my $months = int $age_days/28; $age = $age.$months." months"; } + return $age."</font>"; +} + +opendir LOGS, "/home/groups/b/bo/boost/htdocs/regression-logs"; +my @logs = grep /.*links[^.]*\.html$/, readdir LOGS; +closedir LOGS; +my @bgcolor = ( "bgcolor=\"#EEEEFF\"", "" ); +my $row = 0; +print "<table>\n"; +print "<tr>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Platform</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Run Date</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Age</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Compilers</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Pass</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Warn</th>\n", + "<th align=\"left\" bgcolor=\"#DDDDDD\">Fail</th>\n", + "</tr>\n"; +foreach $l (sort { lc($a) cmp lc($b) } @logs) +{ + my $log = $l; + $log =~ s/-links//s; + my ($spec) = ($log =~ /cs-([^\.]+)/); + my $fh = new FileHandle; + if ($fh->open("</home/groups/b/bo/boost/htdocs/regression-logs/$log")) + { + my $content = join('',$fh->getlines()); + $fh->close; + my ($status) = ($content =~ /(<h1>Compiler(.(?!<\/td>))+.)/si); + my ($platform) = ($status =~ /Status: ([^<]+)/si); + my ($run_date) = ($status =~ /Date:<\/b> ([^<]+)/si); + $run_date =~ s/, /<br>/g; + my ($compilers) = ($content =~ /Test Type<\/a><\/td>((.(?!<\/tr>))+.)/si); + if ($compilers eq "") { next; } + $compilers =~ s/-<br>//g; + $compilers =~ s/<\/td>//g; + my @compiler = ($compilers =~ /<td>(.*)$/gim); + my $count = @compiler; + my @results = ($content =~ /(>Pass<|>Warn<|>Fail<)/gi); + my $test_count = (scalar @results)/$count; + my @pass = map { 0 } (1..$count); + my @warn = map { 0 } (1..$count); + my @fail = map { 0 } (1..$count); + my @total = map { 0 } (1..$count); + for my $t (1..$test_count) + { + my @r = @results[(($t-1)*$count)..(($t-1)*$count+$count-1)]; + for my $c (1..$count) + { + if ($r[$c-1] =~ /Pass/i) { ++$pass[$c-1]; } + elsif ($r[$c-1] =~ /Warn/i) { ++$warn[$c-1]; } + elsif ($r[$c-1] =~ /Fail/i) { ++$fail[$c-1]; } + ++$total[$c-1]; + } + } + for my $comp (1..(scalar @compiler)) + { + my @lines = split(/<br>/,$compiler[$comp-1]); + if (@lines > 2) { $compiler[$comp-1] = join(' ',@lines[0..(scalar @lines)-2])."<br>".$lines[(scalar @lines)-1]; } + } + print + "<tr>\n", + "<td rowspan=\"$count\" valign=\"top\"><font size=\"+1\">$platform</font><br>(<a href=\"../regression-logs/$log\">$spec</a>)</td>\n", + "<td rowspan=\"$count\" valign=\"top\">",$run_date,"</td>\n", + "<td rowspan=\"$count\" valign=\"top\">",age_info($run_date),"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",$compiler[0],"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#000000",$pass[0],$total[0]),"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#FF9900",$warn[0],$total[0]),"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#FF0000",$fail[0],$total[0]),"</td>\n", + "</tr>\n"; + $row = ($row+1)%2; + foreach my $c (1..($count-1)) + { + print + "<tr>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",$compiler[$c],"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#000000",$pass[$c],$total[$c]),"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#FF9900",$warn[$c],$total[$c]),"</td>\n", + "<td valign=\"top\" ",$bgcolor[$row],">",result_info("#FF0000",$fail[$c],$total[$c]),"</td>\n", + "</tr>\n"; + $row = ($row+1)%2; + } + print + "<tr>\n", + "<td colspan=\"7\"><hr size=\"1\" noshade></td>\n", + "</tr>\n"; + } +} +print "</table>\n"; diff --git a/tools/regression/run_tests.sh b/tools/regression/run_tests.sh new file mode 100644 index 0000000000..218452f907 --- /dev/null +++ b/tools/regression/run_tests.sh @@ -0,0 +1,172 @@ +#!/bin/sh +# +# shell script for running the boost regression test suite and generating +# a html table of results. + +# Set the following variables to configure the operation. Variables you +# should set, i.e. usually required are listed first. Optional variables +# have reasonable defaults for most situations. + + +### THESE SHOULD BE CHANGED! + +# +# "boost_root" points to the root of you boost installation: +# This can be either a non-exitent directory or an already complete Boost +# source tree. +# +boost_root=$HOME/CVSROOTs/Boost/boost_regression + +# +# Wether to fetch the most current Boost code from CVS (yes/no): +# There are two contexts to use this script in: on an active Boost CVS +# tree, and on a fresh Boost CVS tree. If "yes" is specified here an attempt +# to fetch the latest CVS Boost files is made. For an active Boost CVS +# the CVS connection information is used. If an empty tree is detected +# the code is fetched with the anonymous read only information. +# +cvs_update=no + +# +# "test_tools" are the Boost.Build toolsets to use for building and running the +# regression tests. Specify a space separated list, of the Boost.Build toolsets. +# Each will be built and tested in sequence. +# +test_tools=gcc + +# +# "toolset" is the Boost.Build toolset to use for building the helper programs. +# This is usually different than the toolsets one is testing. And this is +# normally a toolset that corresponds to the compiler built into your platform. +# +toolset=gcc + + +### DEFAULTS ARE OK FOR THESE. + +# +# "exe_suffix" the suffix used by exectable files: +# In case your platform requires use of a special suffix for executables specify +# it here, including the "." if needed. This should not be needed even in Windows +# like platforms as they will execute without the suffix anyway. +# +exe_suffix= + +# +# "bjam" points to your built bjam executable: +# The location of the binary for running bjam. The default should work +# under most circumstances. +# +bjam=$boost_root/tools/build/jam_src/bin/bjam$exe_suffix + +# +# "process_jam_log", and "compiler_status" paths to built helper programs: +# The location of the executables of the regression help programs. These +# are built locally so the default should work in most situations. +# +process_jam_log=$boost_root/tools/regression/build/run/process_jam_log$exe_suffix +compiler_status=$boost_root/tools/regression/build/run/compiler_status$exe_suffix + +# +# "boost_build_path" can point to additional locations to find toolset files. +# +boost_build_path=$HOME/.boost-build + + +### NO MORE CONFIGURABLE PARTS. + +# +# Some setup. +# +boost_dir=`basename $boost_root` +export BOOST_BUILD_PATH=$boost_build_path $BOOST_BUILD_PATH + +# +# STEP 0: +# +# Get the source code: +# +if test ! -d $boost_root ; then + mkdir -p $boost_root + if test $? -ne 0 ; then + echo "creation of $boost_root directory failed." + exit 256 + fi +fi +if test $cvs_update = yes ; then + echo fetching Boost: + echo "/1 :pserver:anonymous@cvs.sourceforge.net:2401/cvsroot/boost A" >> $HOME/.cvspass + cat $HOME/.cvspass | sort | uniq > $HOME/.cvspass + cd `dirname $boost_root` + if test -f boost/CVS/Root ; then + cvs -z3 -d `cat $boost_dir/CVS/Root` co -d $boost_dir boost + else + cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:2401/cvsroot/boost co -d $boost_dir boost + fi +fi + +# +# STEP 1: +# rebuild bjam if required: +# +echo building bjam: +cd $boost_root/tools/build/jam_src && \ +LOCATE_TARGET=bin sh ./build.sh +if test $? != 0 ; then + echo "bjam build failed." + exit 256 +fi + +# +# STEP 2: +# rebuild the regression test helper programs if required: +# +echo building regression test helper programs: +cd $boost_root/tools/regression/build && \ +$bjam -sTOOLS=$toolset -sBUILD=release run +if test $? != 0 ; then + echo "helper program build failed." + exit 256 +fi + +# +# STEP 5: +# repeat steps 3 and 4 for each additional toolset: +# +for tool in $test_tools ; do + +# +# STEP 3: +# run the regression tests: +# +echo running the $tool regression tests: +cd $boost_root/status +$bjam -sTOOLS=$tool --dump-tests test 2>&1 | tee regress.log + +# +# STEP 4: +# post process the results: +# +echo processing the regression test results for $tool: +cat regress.log | $process_jam_log +if test $? != 0 ; then + echo "Failed regression log post processing." + exit 256 +fi + +done + +# +# STEP 6: +# create the html table: +# +uname=`uname` +echo generating html tables: +$compiler_status $boost_root cs-$uname.html cs-$uname-links.html +if test $? != 0 ; then + echo "Failed HTML result table generation." + exit 256 +fi + +echo "done!" + diff --git a/tools/regression/xsl_reports/empty_expected_results.xml b/tools/regression/xsl_reports/empty_expected_results.xml new file mode 100644 index 0000000000..43e72ca406 --- /dev/null +++ b/tools/regression/xsl_reports/empty_expected_results.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<root> +<expected-failures> +</expected-failures> +</root>
\ No newline at end of file diff --git a/tools/regression/xsl_reports/report.py b/tools/regression/xsl_reports/report.py new file mode 100644 index 0000000000..36c5a0aa95 --- /dev/null +++ b/tools/regression/xsl_reports/report.py @@ -0,0 +1,312 @@ +# (C) Copyright MetaCommunications, Inc. 2003. +# +# Permission to use, copy, modify, distribute and sell this software +# and its documentation for any purpose is hereby granted without fee, +# provided that the above copyright notice appears in all copies and +# that both the copyright notice and this permission notice appear in +# supporting documentation. No representations are made about the +# suitability of this software for any purpose. It is provided "as is" +# without express or implied warranty. + +import shutil +import sys +import os +import os.path +import string +import time +import inspect +import getopt + +if __name__ == "__main__": + run_dir = os.path.abspath( os.path.dirname( sys.argv[ 0 ] ) ) +else: + run_dir = os.path.abspath( os.path.dirname( sys.modules[ __name__ ].__file__ ) ) + +class failure_exception: + def __init__( self, rc ): + self.rc_ = rc + +def log_level(): + frames = inspect.stack() + level = 0 + for i in frames[ 3: ]: + if i[0].f_locals.has_key( "__log__" ): + level = level + i[0].f_locals[ "__log__" ] + return level + + +def stdlog( message ): + sys.stderr.write( "# " + " " * log_level() + message + "\n" ); + sys.stderr.flush() + +log = stdlog +# log = lambda x: x + +def system( commands ): + f = open( "tmp.cmd", "w" ) + f.write( string.join( commands, "\n" ) ) + f.close() + rc = os.system( "tmp.cmd" ) + return rc + + +def checked_system( commands ): + rc = system( commands ) + if 0 != rc : raise failure_exception( rc ) + return rc + + +def set_char( str, index, char ): + return str[ 0 : index ] + char + str[ index + 1: ] + + +def process_xml_file( input_file, output_file ): + log( "Processing test log \"%s\"" % input_file ) + + f = open( input_file, "r" ) + xml = f.readlines(); + f.close() + + ascii_chars = ''.join(map(chr, range(0,128))) + nonascii_chars = ''.join(map(chr, range(128,256))) + translated_ascii_chars = ''.join( map( lambda x: "?", range(128,256))) + for i in string.printable: + if ( ord( i ) < 128 and ord(i) not in ( 12, ) ): + translated_ascii_chars = set_char( translated_ascii_chars, ord(i), i ) + + translated_nonascii_chars = ''.join( map( lambda x: "?", range(128,256) ) ) + + mask_nonascii_translation_table = string.maketrans( ascii_chars + nonascii_chars + , translated_ascii_chars + translated_nonascii_chars + ) + for i in range( 0, len(xml)): + xml[i] = string.translate( xml[i], mask_nonascii_translation_table ) + output_file.writelines( xml ) + + +def process_test_log_files( output_file, dir, names ): + for file in names: + if os.path.basename( file ) == "test_log.xml": + process_xml_file( os.path.join( dir, file ), output_file ) + + +def collect_test_logs( input_dirs, output_file ): + __log__ = 1 + log( "Collecting test logs ..." ) + f = open( output_file, "w+" ) + f.write( "<tests>\n" ); + for input_dir in input_dirs: + os.path.walk( input_dir, process_test_log_files, f ); + f.write( "</tests>\n" ); + f.close() + + +def xalan( xml_file, xsl_file,output_file, parameters = None ): + transform_command = "xalan" + transform_command = transform_command + ' -o "%s" ' % output_file + if parameters is not None: + for i in parameters: + transform_command = transform_command + ' -p %s "\'%s\'" ' % ( i, parameters[ i ] ) + transform_command = transform_command + ' "%s"' % xml_file + transform_command = transform_command + ' "%s"' % xsl_file + log( transform_command ) + os.system( transform_command ) + + +def msxsl( xml_file, xsl_file, output_file, parameters = None ): + transform_command = "msxsl" + transform_command = transform_command + ' "%s"' % xml_file + transform_command = transform_command + ' "%s"' % xsl_file + transform_command = transform_command + ' -o "%s" ' % output_file + + if parameters is not None: + for i in parameters: + transform_command = transform_command + ' %s="%s" ' % ( i, parameters[ i ] ) + + log( transform_command ) + os.system( transform_command ) + +def libxslt( xml_file, xsl_file, output_file, parameters = None ): + transform_command = "xsltproc" + transform_command = transform_command + ' -o ' + "%s" % output_file + + if parameters is not None: + for i in parameters: + transform_command = transform_command + ' --param %s "\'%s\'" ' % ( i, parameters[ i ] ) + + transform_command = transform_command + ' "%s" ' % xsl_file + transform_command = transform_command + ' "%s" ' % xml_file + log( transform_command ) + os.system( transform_command ) + + +registered_xsltprocs = { "msxsl": msxsl + , "xalan": xalan + , "libxslt": libxslt + } + +def map_path( path ): + return os.path.join( run_dir, path ) + +def xsl_path( xsl_file_name ): + return map_path( os.path.join( "xsl", xsl_file_name ) ) + +def make_result_pages( test_results_file + , expected_results_file + , source + , run_date + , comment_file + , results_dir + , result_prefix + , xslt_proc_name + ): + log( "Producing the reports..." ) + __log__ = 1 + + output_dir = os.path.join( results_dir, result_prefix ) + if not os.path.exists( output_dir ): + os.makedirs( output_dir ) + + xslt_proc = registered_xsltprocs[ xslt_proc_name ] + + if comment_file != "": + comment_file = os.path.abspath( comment_file ) + + if expected_results_file != "": + expected_results_file = os.path.abspath( expected_results_file ) + else: + expected_results_file = os.path.abspath( map_path( "empty_expected_results.xml" ) ) + + + extended_test_results = os.path.join( output_dir, "extended_test_results.xml" ) + log( " Merging with expected results..." ) + xslt_proc( test_results_file + , xsl_path( "add_expected_results.xsl" ) + , extended_test_results + , { "expected_results_file": expected_results_file } + ) + + links = os.path.join( output_dir, "links.html" ) + log( " Making -links file..." ) + xslt_proc( extended_test_results + , xsl_path( "links_page.xsl" ) + , links + , { + "source": source + , "run_date": run_date + , "comment_file": comment_file + } + ) + + log( " Making detailed reports..." ) + for mode in ( "developer", "user" ): + xslt_proc( extended_test_results + , xsl_path( "result_page.xsl" ) + , os.path.join( output_dir, "%s_%s" % ( mode, "result_page.html" ) ) + , { "links_file": "links.html" + , "mode": mode + , "source": source + , "run_date": run_date + , "comment_file": comment_file + , "expected_results_file": expected_results_file + } + ); + + log( " Making summary reports..." ) + for mode in ( "developer", "user" ): + xslt_proc( extended_test_results + , xsl_path( "summary_page.xsl" ) + , os.path.join( output_dir, "%s_%s" % ( mode, "summary_page.html" ) ) + , { "mode" : mode + , "source": source + , "run_date": run_date + , "comment_file": comment_file + } + ); + + log( " Generating expected_results ..." ) + xslt_proc( extended_test_results + , xsl_path( "produce_expected_results.xsl" ) + , os.path.join( output_dir, "expected_results.xml" ) + ) + + shutil.copyfile( xsl_path( "master.css" ), os.path.join( output_dir, "master.css" ) ) + + +def build_experimental_reports( locate_root_dir + , source + , expected_results_file + , comment_file + , results_dir + , result_file_prefix + , xslt_proc_name + ): + ( run_date ) = time.strftime("%a, %d %b %Y %H:%M:%S +0000", time.gmtime() ) + test_results_file = os.path.join( results_dir, "test_results.xml" ) + collect_test_logs( [ os.path.join( locate_root_dir, "libs" ), os.path.join( locate_root_dir, "status" ) ] + , test_results_file + ) + + make_result_pages( test_results_file + , expected_results_file + , source + , run_date + , comment_file + , results_dir + , result_file_prefix + , xslt_proc_name + ) + + +def accept_args( args ): + ( option_pairs, rest_args ) = getopt.getopt( sys.argv[1:], "", [ "locate-root=" + , "tag=" + , "expected-results=" + , "comment=" + , "results-dir=" + , "results-prefix=" + , "xsltproc=" + , "help" + ] ) + options = { "--comment": "" + , "--expected-results": "" } + + map( lambda x: options.__setitem__( x[0], x[1] ), option_pairs ) + + if ( options.has_key( "--help" ) or len( options.keys() ) == 2 ): + usage() + sys.exit( 1 ) + + if not options.has_key( "--results-dir" ): + options[ "--results-dir" ] = options[ "--locate-root" ] + + return ( options[ "--locate-root" ] + , options[ "--tag" ] + , options[ "--expected-results" ] + , options[ "--comment" ] + , options[ "--results-dir" ] + , options[ "--results-prefix" ] + , options[ "--xsltproc" ] + ) + +def usage(): + print "Usage: %s [options]" % os.path.basename( sys.argv[0] ) + print """ +\t--locate-root the same as --locate-root in compiler_status +\t--tag the tag for the results (i.e. "CVS main trunk") +\t--expected-results the file with the results to be compared with +\t the current run +\t--comment an html comment file (will be inserted in the reports) +\t--results-dir the directory containing -links.html, -fail.html +\t files produced by compiler_status (by default the +\t same as specified in --locate-root) +\t--results-prefix the prefix of -links.html, -fail.html +\t files produced by compiler_status +\t--xsltproc the name of xslt processor (msxsl, xalan, libxslt) + """ + +def main(): + apply( build_experimental_reports, accept_args( sys.argv[ 1 : ] ) ) + +if __name__ == '__main__': + main() diff --git a/tools/regression/xsl_reports/xsl/add_expected_results.xsl b/tools/regression/xsl_reports/xsl/add_expected_results.xsl new file mode 100644 index 0000000000..1acbe907b1 --- /dev/null +++ b/tools/regression/xsl_reports/xsl/add_expected_results.xsl @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + (C) Copyright MetaCommunications, Inc. 2003. + + Permission to use, copy, modify, distribute and sell this software + and its documentation for any purpose is hereby granted without fee, + provided that the above copyright notice appears in all copies and + that both the copyright notice and this permission notice appear in + supporting documentation. No representations are made about the + suitability of this software for any purpose. It is provided "as is" + without express or implied warranty. + +--> + +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:output method="xml" encoding="utf-8"/> + + <xsl:param name="expected_results_file"/> + <xsl:variable name="expected_results" select="document( $expected_results_file )" /> + + <xsl:template match="/"> + <xsl:apply-templates/> + </xsl:template> + + <xsl:template match="test-log"> + <xsl:variable name="library" select="@library"/> + <xsl:variable name="test-name" select="@test-name"/> + <xsl:variable name="toolset" select="@toolset"/> + + <xsl:element name="{local-name()}"> + <xsl:apply-templates select="@*"/> + + <xsl:variable name="actual_result"> + <xsl:choose> + <xsl:when test="./*/@result = 'fail'" > + <xsl:text>fail</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>success</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="expected_results_test_case" select="$expected_results//*/test-result[ @library=$library and ( @test-name=$test-name or @test-name='*' ) and @toolset = $toolset]"/> + + <xsl:variable name="expected_result"> + <xsl:choose> + <xsl:when test="$expected_results_test_case and $expected_results_test_case/@result = 'fail'"> + <xsl:text>fail</xsl:text> + </xsl:when> + <xsl:otherwise>success</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="status"> + <xsl:choose> + <xsl:when test="$expected_result = $actual_result">expected</xsl:when> + <xsl:otherwise>unexpected</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="is_new"> + <xsl:choose> + <xsl:when test="$expected_results_test_case"> + <xsl:text>no</xsl:text> + </xsl:when> + <xsl:otherwise>yes</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="notes"> + <xsl:for-each select="$expected_results_test_case/note"> + <xsl:choose> + <xsl:when test="@ref"> + <xsl:variable name="note-ref"> + <xsl:value-of select="@ref"/> + </xsl:variable> + <xsl:copy-of select="$expected_results//*/note[@id=$note-ref]"/> + </xsl:when> + <xsl:otherwise> + <xsl:copy-of select="."/> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + <!-- <xsl:copy-of select="$expected_results_test_case/node()"/>--> + </xsl:variable> + + <xsl:attribute name="result"><xsl:value-of select="$actual_result"/></xsl:attribute> + <xsl:attribute name="expected-result"><xsl:value-of select="$expected_result"/></xsl:attribute> + <xsl:attribute name="status"><xsl:value-of select="$status"/></xsl:attribute> + <xsl:attribute name="is-new"><xsl:value-of select="$is_new"/></xsl:attribute> + <xsl:element name="notes"><xsl:copy-of select="$notes"/></xsl:element> + <xsl:apply-templates select="node()" /> + </xsl:element> + </xsl:template> + + <xsl:template match="*"> + <xsl:element name="{local-name()}"> + <xsl:apply-templates select="@*"/> + <xsl:apply-templates select="node()" /> + </xsl:element> + </xsl:template> + + <xsl:template match="@*"> + <xsl:copy-of select="." /> + </xsl:template> + +</xsl:stylesheet> diff --git a/tools/regression/xsl_reports/xsl/links_page.xsl b/tools/regression/xsl_reports/xsl/links_page.xsl new file mode 100644 index 0000000000..56b7fc9c52 --- /dev/null +++ b/tools/regression/xsl_reports/xsl/links_page.xsl @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + (C) Copyright MetaCommunications, Inc. 2003. + + Permission to use, copy, modify, distribute and sell this software + and its documentation for any purpose is hereby granted without fee, + provided that the above copyright notice appears in all copies and + that both the copyright notice and this permission notice appear in + supporting documentation. No representations are made about the + suitability of this software for any purpose. It is provided "as is" + without express or implied warranty. + + --> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + + <xsl:output method="html" + doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN" + encoding="utf-8" + indent="yes" + /> + + <xsl:param name="source"/> + <xsl:param name="run_date"/> + <xsl:param name="comment_file"/> + <xsl:param name="expected_results_file"/> + + <xsl:template match="/"> + <html> + <head> + <link rel="stylesheet" type="text/css" href="master.css" title="master" /> + <title>Boost regression - test run output: <xsl:value-of select="$source"/></title> + </head> + <body> + <div> + <table border="0"> + <tr> + <td><img border="0" src="../c++boost.gif" width="277" height="86" alt="Boost logo"></img></td> + <td> + <h1 class="page-title"> + <xsl:text>Regression Tests Log: </xsl:text> + <xsl:value-of select="$source"/> + </h1> + + <b>Report Time: </b> <xsl:value-of select="$run_date"/> + <xsl:if test="$comment_file != ''"> + <xsl:copy-of select="document( $comment_file )"/> + </xsl:if> + </td> + </tr> + </table> + <table border="0" class="header-table"> + <tr> + <td class="header-item">Purpose</td> + <td class="header-item-content"> + Provides notes, compiler, linker and run output of the + regression tests. + </td> + </tr> + </table> + </div> + <div> + <xsl:apply-templates select="//test-log[@result = 'fail']"/> + </div> + </body> + </html> + </xsl:template> + + <xsl:template match="test-log"> + <div> + <xsl:variable name="test-anchor"> + <xsl:value-of select="concat( @test-name, '-', @toolset )"/> + </xsl:variable> + <div class="log-test-title"> + <a name="{$test-anchor}"><xsl:value-of select="concat( @test-name, ' / ', @toolset )"/></a> + </div> + + <xsl:if test="notes/note"> + <p> + <div class="log-notes-title">Notes:</div> + <div class="log-notes"> + <xsl:for-each select="notes/note"> + <xsl:copy-of select="."/> + </xsl:for-each> + </div> + </p> + </xsl:if> + + <xsl:if test="compile"> + <p> + <div class="log-compiler-output-title">Compiler output:</div> + <pre> + <xsl:copy-of select="compile/node()"/> + </pre> + </p> + </xsl:if> + + <xsl:if test="link"> + <p> + <div class="log-linker-output-title">Linker output:</div> + <pre> + <xsl:copy-of select="link/node()"/> + </pre> + </p> + </xsl:if> + + <xsl:if test="lib"> + <p> + <div class="log-linker-output-title">Lib  output:</div> + <pre> + <xsl:copy-of select="lib/node()"/> + </pre> + </p> + </xsl:if> + + <xsl:if test="run"> + <p> + <div class="log-run-output-title">Run output:</div> + <pre> + <xsl:copy-of select="run/node()"/> + </pre> + </p> + </xsl:if> + + </div> + + </xsl:template> +</xsl:stylesheet> diff --git a/tools/regression/xsl_reports/xsl/master.css b/tools/regression/xsl_reports/xsl/master.css new file mode 100644 index 0000000000..c94e5e5f98 --- /dev/null +++ b/tools/regression/xsl_reports/xsl/master.css @@ -0,0 +1,249 @@ +body +{ + background-color: white; +} + +h1.page-title +{ + text-align: left; + text-transform: capitalize; + margin-bottom: 10pt; +} + +div.acknowledgement +{ + text-align: left; + margin-top: 10pt; + margin-left: 5pt; + margin-bottom: 10pt; +} + +div.purpose +{ + text-align: left; + margin-left: 5pt; + margin-top: 10pt; +} + +div.legend +{ + text-align: left; + margin-left: 15pt; +} + +table.header-table +{ + margin-left: 10pt; + margin-top: 20pt; + margin-bottom: 10pt; + width: 800px; +} + +td.header-item +{ + text-align: left; + vertical-align: top; + font-weight: bold; +} + +td.header-item-content +{ + padding-left: 20pt; + padding-bottom: 10pt; +} + +td.legend-item +{ + padding-left: 5pt; + padding-top: 2pt; +} + +div.toc +{ + margin: 5pt; +} + +li.toc-entry +{ + margin-left: 5pt; + list-style-type: square; +} + +div.library-name +{ + margin-top: 20pt; + margin-bottom: 10pt; + text-align: left; + font-size: 125%; + font-weight: bold; +} + +div.footer +{ + margin: 5px; +} + + table.summary-table +,table.detail-table +{ + border-collapse: collapse; + border: 2px solid black; + margin: 5px; +} + + table.summary-table td +,table.detail-table td +{ + text-align: center; + border-left: 1px solid black; + border-right: 1px solid black; +} + + + a.log-link:link +,a.log-link:visited +{ + color: black; +/* text-decoration: none; */ +} + + a.log-link:active +,a.log-link:hover +,a.legend-link:link +,a.legend-link:visited +,a.legend-link:active +,a.legend-link:hover +{ + color: black; + text-decoration: underline; +} + +table.summary-table td.library-name +{ + width: 100pt; + padding: 0pt; +} + +table.detail-table td.test-name +{ + width: 150pt; + padding: 0pt; + border-right: 0; +} + +table.detail-table td.test-type +{ + padding-right: 5px; + border-left: 0; + border-right: 0; + text-align: right; +} + + td.result-success-expected +,td.result-fail-expected +,td.result-user-success +,td.summary-expected +,td.summary-user-fail-expected +,td.summary-user-success +{ + width: 60pt; + text-align: center; + background-color: lightgreen; + color: black; + border: 0px solid black; +} + + td.result-success-unexpected +,td.summary-success-unexpected +{ + width: 60pt; + text-align: center; + background-color: green; + font-weight: bold; + color: white; + border: 0px; +} + + td.summary-fail-unexpected +,td.summary-user-fail-unexpected +,td.result-user-fail-unexpected +{ + width: 60pt; + text-align: center; + background-color: red; + color: black; + border: 2px solid black; +} + +td.summary-user-fail-unexpected +{ + width: 60pt; + text-align: center; + background-color: yellow; + color: black; + border: 2px solid black; +} + +td.result-fail-unexpected +{ + width: 60pt; + text-align: center; + background-color: red; + font-weight: bold; + color: black; + border: 2px solid black; +} + +td.summary-fail-unexpected-new +, td.result-fail-unexpected-new +{ + width: 60pt; + text-align: center; + background-color: yellow; + color: black; + border: 2px solid black; +} + +td.result-user-fail-expected +{ + width: 60pt; + text-align: center; + background-color: yellow; + color: black; + border: 0px solid black; +} + +div.log-test-title +{ + font-size: 1.5em; + font-weight: bold; + border-bottom: 1px solid black; +} + +div.log-notes-title +{ + font-weight: bold; + background-color:#FFFFCC; +} + + +div.log-notes +{ + padding: 3pt; + background-color:#FFFFCC; +} + +div.log-compiler-output-title +{ + font-weight: bold; +} + +div.log-linker-output-title +{ + font-weight: bold; +} + +div.log-run-output-title +{ + font-weight: bold; +} diff --git a/tools/regression/xsl_reports/xsl/produce_expected_results.xsl b/tools/regression/xsl_reports/xsl/produce_expected_results.xsl new file mode 100644 index 0000000000..68f9e4e336 --- /dev/null +++ b/tools/regression/xsl_reports/xsl/produce_expected_results.xsl @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + + <xsl:output method="xml" encoding="utf-8"/> + + <xsl:template match="/"> + <root> + <expected-failures> + <xsl:apply-templates select="*/test-log"/> + </expected-failures> + </root> + </xsl:template> + + <xsl:template match="test-log"> + <test-result library="{@library}" test-name="{@test-name}" toolset="{@toolset}" result="{@result}" /> + </xsl:template> + +</xsl:stylesheet> diff --git a/tools/regression/xsl_reports/xsl/result_page.xsl b/tools/regression/xsl_reports/xsl/result_page.xsl new file mode 100644 index 0000000000..e89c508ba4 --- /dev/null +++ b/tools/regression/xsl_reports/xsl/result_page.xsl @@ -0,0 +1,374 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + (C) Copyright MetaCommunications, Inc. 2003. + + Permission to use, copy, modify, distribute and sell this software + and its documentation for any purpose is hereby granted without fee, + provided that the above copyright notice appears in all copies and + that both the copyright notice and this permission notice appear in + supporting documentation. No representations are made about the + suitability of this software for any purpose. It is provided "as is" + without express or implied warranty. + +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + + <xsl:output method="html" + doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN" + encoding="utf-8" + indent="yes" + /> + + <xsl:param name="links_file"/> + <xsl:param name="mode"/> + <xsl:param name="source"/> + <xsl:param name="run_date"/> + <xsl:param name="comment_file"/> + <xsl:param name="expected_results_file"/> + + <!-- the author-specified expected test results --> + <xsl:variable name="expected_results" select="document( $expected_results_file )" /> + + <!-- necessary indexes --> + <xsl:key + name="test_name_key" + match="test-log" + use="concat( @library, '>@<', @test-name )"/> + <xsl:key + name="library_key" + match="test-log" + use="@library"/> + <xsl:key name="toolset_key" match="test-log" use="@toolset"/> + + <!-- --> + <xsl:variable name="toolsets" select="//test-log[generate-id(.) = generate-id( key('toolset_key',@toolset)[1] )]/@toolset"/> + <xsl:variable name="libraries" select="//test-log[ generate-id(.) = generate-id( key('library_key',@library)[1] ) and @library != '' ]/@library"/> + + <xsl:template name="toolsets_row"> + <tr> + <td class="head" colspan="2">test / toolset</td> + <xsl:for-each select="$toolsets"> + <xsl:sort select="." order="ascending" /> + <td class="toolset-name"><xsl:value-of select="."/></td> + </xsl:for-each> + <td class="head">toolset / test</td> + </tr> + </xsl:template> + + <xsl:template name="test_type_col"> + <td class="test-type"> + <a href="#legend" class="legend-link"> + <xsl:variable name="test_type" select="./@test-type"/> + <xsl:choose> + <xsl:when test="$test_type='run'"> + <xsl:text>r</xsl:text> + </xsl:when> + <xsl:when test="$test_type='run_fail'"> + <xsl:text>rf</xsl:text> + </xsl:when> + <xsl:when test="$test_type='compile'"> + <xsl:text>c</xsl:text> + </xsl:when> + <xsl:when test="$test_type='compile_fail'"> + <xsl:text>cf</xsl:text> + </xsl:when> + </xsl:choose> + </a> + </td> + </xsl:template> + + + <xsl:template match="/"> + <html> + <head> + <link rel="stylesheet" type="text/css" href="master.css" title="master" /> + <title>Boost regression - <xsl:value-of select="$mode"/> detailed report: <xsl:value-of select="$source"/></title> + </head> + <body> + + <!-- header --> + + <xsl:variable name="legend"> + <xsl:choose> + <xsl:when test="$mode='user'"> + <tr> + <td class="header-item">Legend</td> + <td class="header-item-content"> + + <table border="0" class="legend-table"> + <tr> + <td><table><tr><td class="result-user-success">pass</td></tr></table></td> + <td class="legend-item">the test passes</td> + </tr> + <tr> + <td><table><tr><td class="result-user-fail-expected">fail</td></tr></table></td> + <td class="legend-item"> + a known test failure; click on the link to see the log + </td> + </tr> + <tr> + <td><table><tr><td class="result-user-fail-unexpected">unexp.</td></tr></table></td> + <td class="legend-item"> + the test is known to pass, but is currently failing; + click on the link to see the log + </td> + </tr> + </table> + + </td> + </tr> + </xsl:when> + <xsl:when test="$mode='developer'"> + <tr> + <td class="header-item">Legend</td> + <td class="header-item-content"> + <table border="0" class="legend-table"> + <tr> + <td><table><tr><td class="result-success-expected">pass</td></tr></table></td> + <td> + success + </td> + </tr> + <tr> + <td><table><tr><td class="result-success-unexpected">pass</td></tr></table></td> + <td> + unexpected success + </td> + </tr> + <tr> + <td><table><tr><td class="result-fail-expected">fail</td></tr></table></td> + <td> + expected failure + </td> + </tr> + <tr> + <td><table><tr><td class="result-fail-unexpected-new">fail</td></tr></table></td> + <td class="legend-item"> + failure on a newly added test/compiler + </td> + </tr> + <tr> + <td><table><tr><td class="result-fail-unexpected">fail</td></tr></table></td> + <td>unexpected failure</td> + </tr> + </table> + </td> + </tr> + </xsl:when> + </xsl:choose> + </xsl:variable> + + <div> + <table border="0"> + <tr> + <td><img border="0" src="../c++boost.gif" width="277" height="86" alt="Boost logo"></img></td> + <td> + <h1 class="page-title"> + <xsl:value-of select="$mode"/> + <xsl:text> detailed report: </xsl:text> + <xsl:value-of select="$source"/> + </h1> + + <b>Report Time: </b> <xsl:value-of select="$run_date"/> + <xsl:if test="$comment_file != ''"> + <xsl:copy-of select="document( $comment_file )"/> + </xsl:if> + </td> + </tr> + </table> + <table border="0" class="header-table"> + <tr> + <td class="header-item">Purpose</td> + <td class="header-item-content"> + Provides detailed explanation of the results reported on the + <a href="{$mode}_summary_page.html"><xsl:value-of select="$mode"/> summary</a> page. + </td> + </tr> + <xsl:copy-of select="$legend"/> + </table> + <div class="legend"> + To specify the expected failures for specific test cases create an .xml file + "boost/status/<your library>/expected_results.xml" along these lines: +<pre> +<expected-failures> +<!-- Example: +<test-result library="mpl" test-name="is_sequence" toolset="bcc-5.5.1" /> +<test-result library="mpl" test-name="is_sequence" toolset="cwpro-8.3" /> +--> + +</expected-failures> +</pre> + </div> + </div> + + <!-- TOC --> + <div class="toc"> + <a name="toc"></a> + <ul> + <xsl:for-each select="$libraries"> + <xsl:sort select="." order="ascending" /> + <li class="toc-entry"> + <a href="#{.}" class="toc-entry"> + <xsl:value-of select="."/> + </a> + </li> + </xsl:for-each> + </ul> + </div> + + <!-- for each library --> + <xsl:for-each select="$libraries"> + <xsl:sort select="." order="ascending" /> + <xsl:variable name="library" select="." /> + <div class="library-name"> + <a name="{$library}" href="../libs/{$library}" class="library-link"> + <xsl:value-of select="$library" /> + </a> + </div> + + <table border="1" cellspacing="0" cellpadding="0" class="detail-table"> + + <thead><xsl:call-template name="toolsets_row"/></thead> + <tfoot><xsl:call-template name="toolsets_row"/></tfoot> + + <tbody> + <xsl:variable name="lib_tests" select="//test-log[@library = $library]" /> + <xsl:variable name="lib_unique_test_names" + select="$lib_tests[ generate-id(.) = generate-id( key('test_name_key', concat( @library, '>@<', @test-name ) ) ) ]" /> + + <xsl:for-each select="$lib_unique_test_names"> + <xsl:variable name="test_name" select="./@test-name"/> + <xsl:variable name="test_program" select="./@test-program"/> + <xsl:variable name="test_header"> + <td class="test-name"> + <a href="../{$test_program}" class="test-link"> + <xsl:value-of select="$test_name"/> + </a> + </td> + </xsl:variable> + <tr> + <xsl:copy-of select="$test_header"/> + <xsl:call-template name="test_type_col"/> + + <xsl:for-each select="$lib_tests[ @test-name = $test_name ]"> + <xsl:sort select="@toolset" order="ascending" /> + <xsl:variable name="toolset" select="@toolset" /> + + <xsl:choose> + <xsl:when test="$mode='user'"> + <xsl:call-template name="insert_cell_user"> + <xsl:with-param name="test_log" select="."/> + <xsl:with-param name="log_link" select="concat( $links_file, '#', $test_name, '-', $toolset )"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$mode='developer'"> + <xsl:call-template name="insert_cell_developer"> + <xsl:with-param name="test_log" select="."/> + <xsl:with-param name="log_link" select="concat( $links_file, '#', $test_name, '-', $toolset )"/> + </xsl:call-template> + </xsl:when> + </xsl:choose> + + </xsl:for-each> + <xsl:copy-of select="$test_header"/> + </tr> + </xsl:for-each> + </tbody> + </table> + <div class="footer"> + <a href="#toc" class="back-link">toc</a> + <xsl:text> | </xsl:text> + <a href="{$mode}_summary_page.html" class="back-link">summary</a> + </div> + </xsl:for-each> + <div> + <a href="http://validator.w3.org/check/referer"> + <img border="0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" height="31" width="88"/> + </a> + </div> + + </body> + </html> + + </xsl:template> + + + <!-- report developer status --> + <xsl:template name="insert_cell_developer"> + <xsl:param name="test_log"/> + <xsl:param name="log_link"/> + + <xsl:variable name="is_new"> + <xsl:if test="$test_log/@is-new = 'yes' and $test_log/@status = 'unexpected' and $test_log/@result != 'success'"> + <xsl:value-of select="'-new'"/> + </xsl:if> + </xsl:variable> + <td class="result-{$test_log/@result}-{$test_log/@status}{$is_new}"> + <xsl:choose> + <xsl:when test="$test_log/@result != 'success' and $test_log/@status = 'expected'"> + <a href="{$log_link}" class="log-link"> + fail + </a> + </xsl:when> + <xsl:when test="$test_log/@result != 'success' and $test_log/@status = 'unexpected'"> + <a href="{$log_link}" class="log-link"> + fail + </a> + </xsl:when> + <xsl:when test="$test_log/@result = 'success' and $test_log/@status = 'unexpected'"> + pass + </xsl:when> + <xsl:otherwise> + <xsl:text>pass</xsl:text> + </xsl:otherwise> + </xsl:choose> + </td> + </xsl:template> + + <!-- report user status --> + <xsl:template name="insert_cell_user"> + <xsl:param name="test_log"/> + <xsl:param name="log_link"/> + + <xsl:variable name="class"> + <xsl:choose> + <xsl:when test="$test_log[@result='fail' and @status='unexpected']"> + <xsl:text>result-user-fail-unexpected</xsl:text> + </xsl:when> + <xsl:when test="$test_log[ @result='fail' and @status='expected' ]"> + <xsl:text>result-user-fail-expected</xsl:text> + </xsl:when> + <xsl:when test="$test_log[ @result='success']"> + <xsl:text>result-user-success</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"> + Unknown status + </xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <td class="{$class}"> + <xsl:choose> + <xsl:when test="$test_log/@result != 'success' and $test_log/@status = 'expected'"> + <a href="{$log_link}" class="log-link"> + fail + </a> + </xsl:when> + <xsl:when test="$test_log/@result != 'success'"> + <a href="{$log_link}" class="log-link"> + unexp. + </a> + </xsl:when> + <xsl:otherwise> + <xsl:text>pass</xsl:text> + </xsl:otherwise> + </xsl:choose> + </td> + </xsl:template> + + +</xsl:stylesheet> diff --git a/tools/regression/xsl_reports/xsl/summary_page.xsl b/tools/regression/xsl_reports/xsl/summary_page.xsl new file mode 100644 index 0000000000..bf8c6074ff --- /dev/null +++ b/tools/regression/xsl_reports/xsl/summary_page.xsl @@ -0,0 +1,322 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + (C) Copyright MetaCommunications, Inc. 2003. + + Permission to use, copy, modify, distribute and sell this software + and its documentation for any purpose is hereby granted without fee, + provided that the above copyright notice appears in all copies and + that both the copyright notice and this permission notice appear in + supporting documentation. No representations are made about the + suitability of this software for any purpose. It is provided "as is" + without express or implied warranty. + +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + + <xsl:output method="html" + doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN" + encoding="utf-8" + indent="yes" + /> + + <xsl:param name="mode"/> + <xsl:param name="source"/> + <xsl:param name="run_date"/> + <xsl:param name="comment_file"/> + + <xsl:variable name="alternate_mode"> + <xsl:choose> + <xsl:when test="$mode='user'">developer</xsl:when> + <xsl:otherwise>user</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <!-- necessary indexes --> + <xsl:key + name="test_name_key" + match="test-log" + use="concat( @library, '>@<', @test-name )"/> + <xsl:key + name="library_key" + match="test-log" + use="@library"/> + <xsl:key name="toolset_key" match="test-log" use="@toolset"/> + + <!-- --> + <xsl:variable name="toolsets" select="//test-log[ generate-id(.) = generate-id( key('toolset_key',@toolset)[1] ) ]/@toolset"/> + <xsl:variable name="libraries" select="//test-log[ generate-id(.) = generate-id( key('library_key',@library)[1] ) and @library != '' ]/@library"/> + + <xsl:template name="toolsets_row"> + <tr> + <td class="head">library / toolset</td> + <xsl:for-each select="$toolsets"> + <xsl:sort select="." order="ascending" /> + <td class="toolset-name"><xsl:value-of select="."/></td> + </xsl:for-each> + <td class="head">toolset / library</td> + </tr> + </xsl:template> + + <xsl:template match="/"> + <html> + <head> + <link rel="stylesheet" type="text/css" href="master.css" title="master" /> + <title>Boost regression - <xsl:value-of select="$mode"/> summary: <xsl:value-of select="$source"/></title> + </head> + <body> + + <!-- header --> + + <xsl:variable name="legend"> + <xsl:choose> + <xsl:when test="$mode='user'"> + <tr> + <td class="header-item">Purpose</td> + <td class="header-item-content"> + The purpose of this page and the <a href="{$mode}_result_page.html">detailed user report</a> + is to help a user to find out whether a particular library works on the particular compiler(s). + For CVS "health report", see <a href="{$alternate_mode}_summary_page.html">developer summary</a>. + </td> + </tr> + <tr> + <td class="header-item">Legend</td> + <td class="header-item-content"> + <table border="0" class="legend-table"> + <tr> + <td><table><tr><td class="summary-user-success"> </td></tr></table></td> + <td class="legend-item">all library tests are passing</td> + </tr> + <tr> + <td><table><tr><td class="summary-user-fail-expected">details</td></tr></table></td> + <td class="legend-item"> + there are some known failures in the tests, see the detailed report + </td> + </tr> + <tr> + <td><table><tr><td class="summary-user-fail-unexpected">unexp.</td></tr></table></td> + <td class="legend-item"> + some tests that the library author expects to pass are currently failing, + see the detailed report + </td> + </tr> + </table> + </td> + </tr> + </xsl:when> + <xsl:when test="$mode='developer'"> + <tr> + <td class="header-item">Purpose</td> + <td class="header-item-content"> + The purpose of this page is to provide boost developers with visual indication + of the CVS "health". + <a href="{$mode}_result_page.html">Detailed report</a> is available. + For user-level report, see <a href="{$alternate_mode}_summary_page.html">user summary</a>. + </td> + </tr> + <tr> + <td class="header-item">Legend</td> + <td class="header-item-content"> + <table border="0" class="legend-table"> + <tr> + <td><table><tr><td class="summary-expected">OK</td></tr></table></td> + <td class="legend-item">all expected tests pass</td> + </tr> + <tr> + <td><table><tr><td class="summary-success-unexpected">OK</td></tr></table></td> + <td class="legend-item"> + all expected tests pass, and some other tests that were expected to fail + unexpectedly pass as well + </td> + </tr> + <tr> + <td><table><tr><td class="summary-fail-unexpected-new">fail</td></tr></table></td> + <td class="legend-item"> + there are some failures on the newly added tests/compiler(s) + </td> + </tr> + <tr> + <td><table><tr><td class="summary-fail-unexpected">broken</td></tr></table></td> + <td class="legend-item"> + tests that the library author expects to pass are currently failing + </td> + </tr> + </table> + </td> + </tr> + </xsl:when> + </xsl:choose> + </xsl:variable> + + <div> + <table border="0"> + <tr> + <td><img border="0" src="../c++boost.gif" width="277" height="86" alt="Boost logo"></img></td> + <td> + <h1 class="page-title"> + <xsl:value-of select="$mode"/> + <xsl:text> summary: </xsl:text> + <xsl:value-of select="$source"/> + </h1> + <b>Report Time: </b> <xsl:value-of select="$run_date"/> + <xsl:if test="$comment_file != ''"> + <xsl:copy-of select="document( $comment_file )"/> + </xsl:if> + </td> + </tr> + </table> + <table border="0" class="header-table"> + <xsl:copy-of select="$legend"/> + </table> + </div> + + <!-- summary table --> + + <table border="1" cellspacing="0" cellpadding="0" class="summary-table"> + + <thead><xsl:call-template name="toolsets_row"/></thead> + <tfoot><xsl:call-template name="toolsets_row"/></tfoot> + + <tbody> + <!-- for each library --> + <xsl:for-each select="$libraries"> + <xsl:sort select="." order="ascending" /> + <xsl:variable name="library" select="."/> + <xsl:variable name="current_row" select="//test-log[ @library=$library]"/> + + <xsl:variable name="library_header"> + <td class="library-name"> + <a href="{$mode}_result_page.html#{.}" class="library-link"> + <xsl:value-of select="."/> + </a> + </td> + </xsl:variable> + + <tr class="summary-row"> + <xsl:copy-of select="$library_header"/> + + <xsl:for-each select="$toolsets"> + <xsl:sort select="." order="ascending" /> + <xsl:variable name="toolset" select="."/> + + <xsl:variable name="current_cell" select="$current_row[ @toolset=$toolset ]"/> + <xsl:choose> + <xsl:when test="$mode='user'"> + <xsl:call-template name="insert_cell_user"> + <xsl:with-param name="current_cell" select="$current_cell"/> + <xsl:with-param name="library" select="$library"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$mode='developer'"> + <xsl:call-template name="insert_cell_developer"> + <xsl:with-param name="current_cell" select="$current_cell"/> + <xsl:with-param name="library" select="$library"/> + </xsl:call-template> + </xsl:when> + </xsl:choose> + </xsl:for-each> + + <xsl:copy-of select="$library_header"/> + </tr> + </xsl:for-each> + </tbody> + </table> + <div> + <a href="http://validator.w3.org/check/referer"> + <img border="0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" height="31" width="88"/> + </a> + </div> + </body> + </html> +</xsl:template> + +<!-- report developer status --> +<xsl:template name="insert_cell_developer"> + <xsl:param name="current_cell"/> + <xsl:param name="library"/> + <xsl:variable name="class"> + <xsl:choose> + <xsl:when test="count( $current_cell[@result='fail' and @status='unexpected' and @is-new='no'] )"> + <xsl:text>summary-fail-unexpected</xsl:text> + </xsl:when> + <xsl:when test="count( $current_cell[@result='fail' and @status='unexpected' and @is-new='yes'] )"> + <xsl:text>summary-fail-unexpected-new</xsl:text> + </xsl:when> + <xsl:when test="count( $current_cell[@result='success' and @status='unexpected'] )"> + <xsl:text>summary-success-unexpected</xsl:text> + </xsl:when> + <xsl:when test="count( $current_cell[@status='expected'] )"> + <xsl:text>summary-expected</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:variable> + + <td class="{$class}"> + <xsl:choose> + <xsl:when test="$class='summary-fail-unexpected' or $class='summary-fail-unexpected-new' "> + <a href="{$mode}_result_page.html#{$library}" class="log-link"> + <xsl:text>broken</xsl:text> + </a> + </xsl:when> + <xsl:when test="$class='summary-fail-unexpected-new' "> + <a href="{$mode}_result_page.html#{$library}" class="log-link"> + <xsl:text>fail</xsl:text> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:text>OK</xsl:text> + </xsl:otherwise> + </xsl:choose> + </td> + +</xsl:template> + + +<!-- report user status --> +<xsl:template name="insert_cell_user"> + <xsl:param name="current_cell"/> + <xsl:param name="library"/> + <xsl:variable name="class"> + <xsl:choose> + <xsl:when test="count( $current_cell[@result='fail' and @status='unexpected' ] )"> + <xsl:text>summary-user-fail-unexpected</xsl:text> + </xsl:when> + <xsl:when test="count( $current_cell[ @result='fail'] )"> + <xsl:text>summary-user-fail-expected</xsl:text> + </xsl:when> + <xsl:when test="count( $current_cell[ @result='success'] )"> + <xsl:text>summary-user-success</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:message terminate="yes"> + Unknown status + <xsl:copy-of select="$current_cell"> + </xsl:copy-of> + </xsl:message> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <td class="{$class}"> + <xsl:choose> + <xsl:when test="$class='summary-user-fail-unexpected'"> + <a href="{$mode}_result_page.html#{$library}" class="log-link"> + <xsl:text>unexp.</xsl:text> + </a> + </xsl:when> + <xsl:when test="$class='summary-user-fail-expected'"> + <a href="{$mode}_result_page.html#{$library}" class="log-link"> + <xsl:text>details</xsl:text> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:text> </xsl:text> + </xsl:otherwise> + </xsl:choose> + </td> + +</xsl:template> + +</xsl:stylesheet> |
