Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r65338 - in sandbox/chrono/libs/type_traits_ext/doc: . html
From: vicente.botet_at_[hidden]
Date: 2010-09-07 12:46:31

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65339 - sandbox/chrono/libs/stopwatches/doc/html"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65337 - in sandbox/chrono/libs/ratio/doc: . html"

Author: viboes
Date: 2010-09-07 12:46:28 EDT (Tue, 07 Sep 2010)
New Revision: 65338
URL: http://svn.boost.org/trac/boost/changeset/65338

Log:
update doc
Text files modified:
   sandbox/chrono/libs/type_traits_ext/doc/html/index.html | 296 ++++++++++++++++++++++++---------------
   sandbox/chrono/libs/type_traits_ext/doc/type_traits_ext.qbk | 143 +++++++++++++++---
   2 files changed, 300 insertions(+), 139 deletions(-)

Modified: sandbox/chrono/libs/type_traits_ext/doc/html/index.html
==============================================================================
--- sandbox/chrono/libs/type_traits_ext/doc/html/index.html (original)
+++ sandbox/chrono/libs/type_traits_ext/doc/html/index.html 2010-09-07 12:46:28 EDT (Tue, 07 Sep 2010)
@@ -1,10 +1,10 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Boost.TypeTraits.Ext</title>
+<title>Boost.TypeTraits.Ext 0.1.0</title>
<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
-<link rel="start" href="index.html" title="Boost.TypeTraits.Ext">
+<link rel="start" href="index.html" title="Boost.TypeTraits.Ext 0.1.0">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -21,7 +21,7 @@
<div class="titlepage">
<div>
<div><h2 class="title">
-<a name="boost_typetraits_ext"></a>Boost.TypeTraits.Ext</h2></div>
+<a name="boost_typetraits_ext"></a>Boost.TypeTraits.Ext 0.1.0</h2></div>
<div><div class="authorgroup">
<div class="author"><h3 class="author">
Howard Hinnant
@@ -162,11 +162,24 @@
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_typetraits_ext.overview.motivation"></a>Motivation
</h3></div></div></div>
-<a name="boost_typetraits_ext.overview.motivation.time"></a><h4>
-<a name="id4948839"></a>
- Time
+<a name="boost_typetraits_ext.overview.motivation.common_type"></a><h4>
+<a name="id4948838"></a>
+ common_type
 </h4>

+ <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Class Template common_type<>"><code class="computeroutput">common_type</code></a> has been a recurring
+ theme in many places for many years. We've previously known it as <code class="computeroutput">promote</code> and examples of it are spread throughout
+ boost. It has been reinvented independently several times, because it is
+ so useful.
+ 
+
+ Andrei Alexandrescu recently pointed us at a D library: std.traits - D Programming
+ Language - Digital Mars, which became the motivation for this particular
+ name, and the variadic nature of <a href="http://www.digitalmars.com/d/2.0/phobos/std_traits.html#CommonType" target="_top">this
+ trait</a>.
+ 
+
 See N2661 - A Foundation to Sleep On which is
 very informative and provides motivation for key design decisions for <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
 Class Template common_type<>"><code class="computeroutput">common_type</code></a>.
@@ -228,7 +241,7 @@
 Installing Boost.TypeTraits.Ext</a>
</h4></div></div></div>
<a name="boost_typetraits_ext.users_guide.getting_started.install.getting_boost_typetraits_ext_"></a><h5>
-<a name="id4949041"></a>
+<a name="id4949089"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.getting_boost_typetraits_ext_">Getting
 Boost.TypeTraits.Ext </a>
 </h5>
@@ -243,7 +256,7 @@
 and follow the instructions there for anonymous SVN access.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.where_to_install_boost_typetraits_ext__"></a><h5>
-<a name="id4949104"></a>
+<a name="id4949151"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.where_to_install_boost_typetraits_ext__">Where
 to install Boost.TypeTraits.Ext? </a>
 </h5>
@@ -259,7 +272,7 @@
 variable. Any help is welcome.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.building_boost_typetraits_ext_"></a><h5>
-<a name="id4949142"></a>
+<a name="id4949190"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.building_boost_typetraits_ext_">Building
 Boost.TypeTraits.Ext </a>
 </h5>
@@ -268,7 +281,7 @@
 library. You don't need to compile it before use.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.requirements"></a><h5>
-<a name="id4949175"></a>
+<a name="id4949222"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.requirements">Requirements</a>
 </h5>

@@ -306,7 +319,7 @@
</dl>
</div>
<a name="boost_typetraits_ext.users_guide.getting_started.install.building_an_executable_that_uses_boost_typetraits_ext_"></a><h5>
-<a name="id4949329"></a>
+<a name="id4949377"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.building_an_executable_that_uses_boost_typetraits_ext_">Building
 an executable that uses Boost.TypeTraits.Ext </a>
 </h5>
@@ -314,7 +327,7 @@
 You don't need to link with any library.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.exceptions_safety_"></a><h5>
-<a name="id4949359"></a>
+<a name="id4949406"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.exceptions_safety_">Exceptions
 safety </a>
 </h5>
@@ -323,7 +336,7 @@
 of exception safety as long as the underlying parameters provide it.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.thread_safety_"></a><h5>
-<a name="id4949386"></a>
+<a name="id4949434"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.thread_safety_">Thread
 safety </a>
 </h5>
@@ -331,7 +344,7 @@
 All functions in the library are thread-unsafe except when noted explicitly.
 
<a name="boost_typetraits_ext.users_guide.getting_started.install.tested_compilers_"></a><h5>
-<a name="id4949412"></a>
+<a name="id4949460"></a>
 <a href="index.html#boost_typetraits_ext.users_guide.getting_started.install.tested_compilers_">Tested
 compilers </a>
 </h5>
@@ -417,8 +430,8 @@
<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.so_what_is__common_type__and_how_can_i_use_it_">So
 What is <code class="computeroutput">common_type</code> and
 How can I use it?</a></dt>
-<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_inter_type_with_explicit_conversions_">How
- to get the common type of inter-type with explicit conversions?</a></dt>
+<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_types_with_explicit_conversions_">How
+ to get the common type of types with explicit conversions?</a></dt>
</dl></dd>
</dl></div>
<div class="section" lang="en">
@@ -431,22 +444,9 @@
<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.so_what_is__common_type__and_how_can_i_use_it_">So
 What is <code class="computeroutput">common_type</code> and
 How can I use it?</a></dt>
-<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_inter_type_with_explicit_conversions_">How
- to get the common type of inter-type with explicit conversions?</a></dt>
+<dt><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_types_with_explicit_conversions_">How
+ to get the common type of types with explicit conversions?</a></dt>
</dl></div>
-
- <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a> has been a recurring
- theme in many places for many years. We've previously known it as promote
- and examples of it are spread throughout boost. It has been reinvented
- independently several times, because it is so useful.
- 
-
- Andrei Alexandrescu recently pointed us at a D library: std.traits - D
- Programming Language - Digital Mars, which became the motivation for this
- particular name, and the variadic nature of <a href="http://www.digitalmars.com/d/2.0/phobos/std_traits.html#CommonType" target="_top">this
- trait</a>.
- 
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
<a name="boost_typetraits_ext.users_guide.tutorial.common_type.so_what_is__common_type__and_how_can_i_use_it_"></a><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.so_what_is__common_type__and_how_can_i_use_it_" title="So
@@ -469,22 +469,16 @@
 Example:
 
<pre class="programlisting">template <class T, class U>
-typename <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><complex<T>, complex<U> >::type
+complex<typename <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Class Template common_type<>"><code class="computeroutput">common_type</code></a><T, U>::type>
operator+(complex<T>, complex<U>);
</pre>

 In the above example, "mixed-mode" complex arithmetic is allowed.
 The return type is described by <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
 Class Template common_type<>"><code class="computeroutput">common_type</code></a>. For example the
- resulting type of adding a <code class="computeroutput">complex<int></code> and <code class="computeroutput">complex<double></code> might be a <code class="computeroutput">complex<double></code>. Another choice for the author might
- be:
+ resulting type of adding a <code class="computeroutput">complex<int></code> and <code class="computeroutput">complex<double></code> might be a <code class="computeroutput">complex<double></code>.
 
-<pre class="programlisting">template <class T, class U>
-complex<typename <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><T, U>::type>
-operator+(complex<T>, complex<U>);
-</pre>

 Here is how someone might produce a variadic comparison function:
 
@@ -501,18 +495,30 @@
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
-<a name="boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_inter_type_with_explicit_conversions_"></a><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_inter_type_with_explicit_conversions_" title="How
- to get the common type of inter-type with explicit conversions?">How
- to get the common type of inter-type with explicit conversions?</a>
+<a name="boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_types_with_explicit_conversions_"></a><a href="index.html#boost_typetraits_ext.users_guide.tutorial.common_type.how_to_get_the_common_type_of_types_with_explicit_conversions_" title="How
+ to get the common type of types with explicit conversions?">How
+ to get the common type of types with explicit conversions?</a>
</h5></div></div></div>

- The default definition of <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Another choice for the author of the preceding operator could be
+ 
+<pre class="programlisting">template <class T, class U>
+typename <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Class Template common_type<>"><code class="computeroutput">common_type</code></a><complex<T>, complex<U> >::type
+operator+(complex<T>, complex<U>);
+</pre>
+
+ As the default definition of <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
 Class Template common_type<>"><code class="computeroutput">common_type</code></a> demands the conversion
- be implicit. However the trait can be specialized for user-defined types
- which want to limit their inter-type conversions to explicit, and yet
- still want to interoperate with the <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a> facility.
+ be implicit, we need to specialize the trait for complex types as follows.
 
+<pre class="programlisting">template <class T, class U>
+struct <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Class Template common_type<>"><code class="computeroutput">common_type</code></a><complex<T>, complex<U> > {
+ typedef complex< <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
+ Class Template common_type<>"><code class="computeroutput">common_type</code></a><T, U> > type;
+};
+</pre>
</div>
</div>
</div>
@@ -685,11 +691,12 @@
 BOOST_COMMON_TYPE_USES_ARRAY_ASSERT: define it if you want to use internal
 static asertions
 </li>
-<li>
- nothing if you don't want static asertions
- </li>
</ul></div>

+ The default vaule behavior is as BOOST_COMMON_TYPE_USES_ARRAY_ASSERT was
+ defined.
+ 
+
 When BOOST_COMMON_TYPE_USES_MPL_ASSERT is not defined the following symbols
 are defined as
 
@@ -869,8 +876,8 @@
 B: Rationale</a>
</h3></div></div></div>

- See [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm N2661 - A Foundation to Sleep On] which is very informative
- and provides motivation for key design decisions.
+ See N2661 - A Foundation to Sleep On which is
+ very informative and provides motivation for key design decisions.
 
</div>
<div class="section" lang="en">
@@ -880,7 +887,7 @@
 C: Implementation Notes</a>
</h3></div></div></div>
<a name="boost_typetraits_ext.appendices.implementation.common_type_c__03_implementation"></a><h4>
-<a name="id4997993"></a>
+<a name="id4998178"></a>
 <a href="index.html#boost_typetraits_ext.appendices.implementation.common_type_c__03_implementation">common_type
 C++03 implementation</a>
 </h4>
@@ -903,12 +910,12 @@

 Jeffrey Lee Hellrung, Jr. has reache dto implement <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
 Class Template common_type<>"><code class="computeroutput">common_type</code></a> without using Boost.TypeOf.
- The idea is that the number of possible types of the expression <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
- Function Template declval<>"><code class="computeroutput">declval</code></a><bool>() ? <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
- Function Template declval<>"><code class="computeroutput">declval</code></a><T>() : <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
- Function Template declval<>"><code class="computeroutput">declval</code></a>() are limited.
- His implementation enumerates the possible types and check if there is only
- one common type.
+ The idea is that the number of possible types of the expression <code class="computeroutput"> <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
+ Function Template declval<>"><code class="computeroutput">declval</code></a><bool>() ? <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
+ Function Template declval<>"><code class="computeroutput">declval</code></a><T>() : <a href="index.html#boost_typetraits_ext.reference.declval_hpp.declval" title="
+ Function Template declval<>"><code class="computeroutput">declval</code></a><U>()</code>
+ are limited. His implementation enumerates the possible types and check if
+ there is only one common type.
 
</div>
<div class="section" lang="en">
@@ -916,18 +923,18 @@
<a name="boost_typetraits_ext.appendices.faq"></a> Appendix D: FAQ
</h3></div></div></div>
<a name="boost_typetraits_ext.appendices.faq.how_important_is_the_order_of_the_common_type_lt__gt__template_arguments_"></a><h4>
-<a name="id4998146"></a>
+<a name="id4998373"></a>
 <a href="index.html#boost_typetraits_ext.appendices.faq.how_important_is_the_order_of_the_common_type_lt__gt__template_arguments_">How
 important is the order of the common_type<> template arguments?</a>
 </h4>

- The order of the template parameters is important. First <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><> is not able
- to find out common type if it is not present and second <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><A,B,C>::type is
- equivalent to <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a>< <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><A,B>::type, C>::type.
+ The order of the template parameters is important.
+ 
+
+ <code class="computeroutput">common_type<A,B,C>::type</code> is not equivalent to <code class="computeroutput">common_type<C,A,B>::type</code>, but to <code class="computeroutput">common_type<common_type<A,B
>::type, C>::type</code>.
+ 
+
+ Consider
 
<pre class="programlisting">struct A {};
struct B {};
@@ -939,59 +946,124 @@
 return *this;
 }
};
+</pre>
+
+ The following doesn't compile
+ 
+<pre class="programlisting">typedef boost::common_type<A, B, C>::type ABC; // Does not compile
+</pre>
+
+ while
+ 
+<pre class="programlisting">typedef boost::common_type<C, A, B>::type ABC;
+</pre>
+
+ compiles.
+ 
+
+ Thus, as <code class="computeroutput">common_type<A,B>::type</code>
+ is undefined, <code class="computeroutput">common_type__<A,B,C>::type</code>
+ is also undefined.
+ 
+
+ It is intended that clients who wish for <code class="computeroutput">common_type<A,
+ B></code>
+ to be well defined to define it themselves:
+ 
+<pre class="programlisting">namespace boost
+{
+
+template <>
+struct common_type<A, B> {typedef C type;};
+
+}
+</pre>
+
+ Now this client can ask for <code class="computeroutput">common_type<A,
+ B, C></code> (and
+ get the same answer).
+ 
+
+ Clients wanting to ask <code class="computeroutput">common_type<A,
+ B, C></code> in
+ any order and get the same result need to add in addition:
+ 
+<pre class="programlisting">namespace boost
+{

-#if 0
-typedef boost:: <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><A, B, C>::type ABC; // DO not compile
-#else
-typedef boost:: <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><C, B, A>::type ABC;
-#endif
-</pre>
-
- Thus, as <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><A,B>::type is
- undefined, <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><A,B,C>::type is
- also undefined.
- 
-<a name="boost_typetraits_ext.appendices.faq.can_you_explain_the_pros_cons_of_common_type_against_boost_typeof_"></a><h4>
-<a name="id4998629"></a>
- <a href="index.html#boost_typetraits_ext.appendices.faq.can_you_explain_the_pros_cons_of_common_type_against_boost_typeof_">Can
- you explain the pros/cons of common_type against Boost.Typeof?</a>
+template <> struct common_type<B, A>
+: public common_type<A, B> {};
+
+}
+</pre>
+
+ This is needed as the specialization of <code class="computeroutput">common_type<A,
+ B></code>
+ is not be used implicitly for <code class="computeroutput">common_type<B,
+ A></code>.
+ 
+<a name="boost_typetraits_ext.appendices.faq.can_the_common_type_of_two_types_be_a_third_type_"></a><h4>
+<a name="id4999364"></a>
+ <a href="index.html#boost_typetraits_ext.appendices.faq.can_the_common_type_of_two_types_be_a_third_type_">Can
+ the common_type of two types be a third type?</a>
 </h4>

- Even if in a first look they sound to be close, <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a> and typeof have different
- purposes. You use typeof to get the type of an expression, while you use
- <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a> to set explicitly the
- type returned of a template function. Both are complementary. For example
- with the preceding declaration and the needed Typeof registrations, you can
- do
+ Given the preceding example, one might expect <code class="computeroutput">common_type<A,B>::type</code> to be <code class="computeroutput">C</code>
+ without any intervention from the user. But the default <code class="computeroutput">common_type<></code> implementation doesn't grant that.
+ It is intended that clients who wish for <code class="computeroutput">common_type<A,
+ B></code>
+ to be well defined to define it themselves:
 
+<pre class="programlisting">namespace boost
+{
+
+template <>
+struct common_type<A, B> {typedef C type;};
+
+template <> struct common_type<B, A>
+: public common_type<A, B> {};
+
+}
+</pre>

- Suppose I have a mixed type vector2 class with a magnitude_squared function
- defined as:
+ Now this client can ask for <code class="computeroutput">common_type<A,
+ B></code>.
 
+<a name="boost_typetraits_ext.appendices.faq.how_common_type_behaves_with_pointers_"></a><h4>
+<a name="id4999693"></a>
+ <a href="index.html#boost_typetraits_ext.appendices.faq.how_common_type_behaves_with_pointers_">How
+ common_type behaves with pointers?</a>
+ </h4>

- template <typename X, typename Y> BOOST_TYPEOF_TPL(X() * X() + Y()
- * Y()) magnitude_squared(const vector2<X, Y> &v) { return v.x *
- v.x + v.y * v.y; }
+ Consider
 
+<pre class="programlisting">struct C { }:
+struct B : C { };
+struct A : C { };
+</pre>

- <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a> is closer in nature
- to promote_args<class ...T> in boost/math/tools/promotion.hpp than
- it is to Boost.Typeof, though it is not exactly the same as promote_args
- either. <a href="index.html#boost_typetraits_ext.reference.common_type_hpp.common_type" title="
- Class Template common_type<>"><code class="computeroutput">common_type</code></a><T1, T2>::type
- simply represents the result of some operation on T1 and T2, and defaults
- to the type obtained by putting T1 and T2 into a conditional statement.
+ Shouldn't <code class="computeroutput">common_type<A*,B*>::type</code>
+ be <code class="computeroutput">C*</code>?
+ I would say yes, but the default implementation make it ill-formed.
+ 
+
+ The library could add a specialization for pointers, as
+ 
+<pre class="programlisting">namespace boost
+{
+
+ template <typename A, typename B>
+ struct common_type<A*, B*> {
+ typedef common_type<A, B>* type;
+ };
+}
+</pre>
+
+ But tin the absence of a motivating use cases, we prefere to don't add more
+ than what the standard specifies.
 

- It is meant to be customizable (via specialization) if this default is not
- appropriate.
+ Of course the user can always make this specialization.
 
</div>
<div class="section" lang="en">
@@ -1246,7 +1318,7 @@
 plans</a>
</h3></div></div></div>
<a name="boost_typetraits_ext.appendices.todo.for_later_releases"></a><h4>
-<a name="id4999257"></a>
+<a name="id5000523"></a>
 <a href="index.html#boost_typetraits_ext.appendices.todo.for_later_releases">For
 later releases</a>
 </h4>
@@ -1258,7 +1330,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: September 05, 2010 at 18:59:19 GMT</td>
+<td align="left">Last revised: September 07, 2010 at 15:13:54 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/chrono/libs/type_traits_ext/doc/type_traits_ext.qbk
==============================================================================
--- sandbox/chrono/libs/type_traits_ext/doc/type_traits_ext.qbk (original)
+++ sandbox/chrono/libs/type_traits_ext/doc/type_traits_ext.qbk 2010-09-07 12:46:28 EDT (Tue, 07 Sep 2010)
@@ -9,6 +9,7 @@

[article Boost.TypeTraits.Ext
 [quickbook 1.5]
+ [version 0.1.0]
 [authors [Hinnant, Howard]]
 [authors [Dawes, Beman]]
 [authors [Botet Escriba, Vicente J.]]
@@ -80,8 +81,11 @@
[section Motivation]
[/=================]

-[heading Time]
+[heading common_type]

+__common_type__ has been a recurring theme in many places for many years. We've previously known it as `promote` and examples of it are spread throughout boost. It has been reinvented independently several times, because it is so useful.
+
+Andrei Alexandrescu recently pointed us at a D library: std.traits - D Programming Language - Digital Mars, which became the motivation for this particular name, and the variadic nature of [@http://www.digitalmars.com/d/2.0/phobos/std_traits.html#CommonType this trait].

See [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*N2661 - A Foundation to Sleep On]] which is very informative and provides motivation for key design decisions for __common_type__.

@@ -238,9 +242,6 @@

[section Common Type]

-__common_type__ has been a recurring theme in many places for many years. We've previously known it as promote and examples of it are spread throughout boost. It has been reinvented independently several times, because it is so useful.
-
-Andrei Alexandrescu recently pointed us at a D library: std.traits - D Programming Language - Digital Mars, which became the motivation for this particular name, and the variadic nature of [@http://www.digitalmars.com/d/2.0/phobos/std_traits.html#CommonType this trait].

[section So What is `common_type` and How can I use it?]

@@ -249,14 +250,13 @@
[*Example:]

 template <class T, class U>
- typename __common_type__<complex<T>, complex >::type
+ complex<typename __common_type__<T, U>::type>
 operator+(complex<T>, complex);

-In the above example, "mixed-mode" complex arithmetic is allowed. The return type is described by __common_type__. For example the resulting type of adding a `complex<int>` and `complex<double>` might be a `complex<double>`. Another choice for the author might be:

- template <class T, class U>
- complex<typename __common_type__<T, U>::type>
- operator+(complex<T>, complex);
+In the above example, "mixed-mode" complex arithmetic is allowed. The return type is described by __common_type__. For example the resulting type of adding a `complex<int>` and `complex<double>` might be a `complex<double>`.
+
+

Here is how someone might produce a variadic comparison function:

@@ -268,9 +268,20 @@

[endsect]

-[section How to get the common type of inter-type with explicit conversions?]
+[section How to get the common type of types with explicit conversions?]
+
+Another choice for the author of the preceding operator could be
+
+ template <class T, class U>
+ typename __common_type__<complex<T>, complex >::type
+ operator+(complex<T>, complex);
+
+As the default definition of __common_type__ demands the conversion be implicit, we need to specialize the trait for complex types as follows.

-The default definition of __common_type__ demands the conversion be implicit. However the trait can be specialized for user-defined types which want to limit their inter-type conversions to explicit, and yet still want to interoperate with the __common_type__ facility.
+ template <class T, class U>
+ struct __common_type__<complex<T>, complex > {
+ typedef complex< __common_type__<T, U> > type;
+ };

[endsect]
@@ -374,7 +385,8 @@
* BOOST_COMMON_TYPE_USES_STATIC_ASSERT: define it if you want to use Boost.StaticAssert
* BOOST_COMMON_TYPE_USES_MPL_ASSERT: define it if you want to use Boost.MPL static asertions
* BOOST_COMMON_TYPE_USES_ARRAY_ASSERT: define it if you want to use internal static asertions
-* nothing if you don't want static asertions
+
+The default vaule behavior is as BOOST_COMMON_TYPE_USES_ARRAY_ASSERT was defined.

When BOOST_COMMON_TYPE_USES_MPL_ASSERT is not defined the following symbols are defined as

@@ -484,7 +496,7 @@
[/======================================]
[section:rationale Appendix B: Rationale]

-See [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*N2661 - A Foundation to Sleep On]] which is very informative and provides motivation for key design decisions.
+See [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*N2661 - A Foundation to Sleep On]] which is very informative and provides motivation for key design decisions.

[endsect]

@@ -498,18 +510,21 @@
* Absence of variadic template: The number of template parameters is limited to 3.
* decltype and rvalue references missing: the default common-type is based on these C++0x features. When these are not present, BoostTypeOf is used instead of decltype, and rvalue references are not used at all, and replaced by the type itself.

-Jeffrey Lee Hellrung, Jr. has reache dto implement __common_type__ without using Boost.TypeOf. The idea is that the number of possible types of the expression __declval__<bool>() ? __declval__<T>() : __declval__() are limited. His implementation enumerates the possible types and check if there is only one common type.
+Jeffrey Lee Hellrung, Jr. has reache dto implement __common_type__ without using Boost.TypeOf. The idea is that the number of possible types of the expression `__declval__<bool>() ? __declval__<T>() : __declval__()` are limited. His implementation enumerates the possible types and check if there is only one common type.

[endsect]

[/======================================================]
[section:faq Appendix D: FAQ]

+
[heading How important is the order of the common_type<> template arguments?]

-The order of the template parameters is important. First __common_type__<> is not able to find out common type if it is not present and second
-__common_type__<A,B,C>::type is equivalent to __common_type__<__common_type__<A,B>::type, C>::type.
+The order of the template parameters is important.

+`common_type<A,B,C>::type` is not equivalent to `common_type<C,A,B>::type`, but to `common_type<common_type<A,B>::type, C>::type`.
+
+Consider

 struct A {};
 struct B {};
@@ -522,15 +537,88 @@
 }
 };

- #if 0
- typedef boost::__common_type__<A, B, C>::type ABC; // DO not compile
- #else
- typedef boost::__common_type__<C, B, A>::type ABC;
- #endif
+The following doesn't compile
+
+ typedef boost::common_type<A, B, C>::type ABC; // Does not compile
+
+while
+
+ typedef boost::common_type<C, A, B>::type ABC;
+
+compiles.
+
+Thus, as `common_type<A,B>::type` is undefined, `common_type__<A,B,C>::type` is also undefined.
+
+It is intended that clients who wish for `common_type<A, B>` to be well
+defined to define it themselves:
+
+ namespace boost
+ {
+
+ template <>
+ struct common_type<A, B> {typedef C type;};
+
+ }
+
+Now this client can ask for `common_type<A, B, C>` (and get
+the same answer).
+
+Clients wanting to ask `common_type<A, B, C>` in any order and get the same result need to add in addition:
+
+ namespace boost
+ {
+
+ template <> struct common_type<B, A>
+ : public common_type<A, B> {};
+
+ }
+
+This is needed as the specialization of `common_type<A, B>` is not be used implicitly for `common_type<B, A>`.
+
+[heading Can the common_type of two types be a third type?]
+
+Given the preceding example, one might expect `common_type<A,B>::type` to be `C` without any intervention from the user. But the default `common_type<>` implementation doesn't grant that. It is intended that clients who wish for `common_type<A, B>` to be well defined to define it themselves:
+
+ namespace boost
+ {
+
+ template <>
+ struct common_type<A, B> {typedef C type;};
+
+ template <> struct common_type<B, A>
+ : public common_type<A, B> {};

+ }

-Thus, as __common_type__<A,B>::type is undefined, __common_type__<A,B,C>::type is also undefined.
+Now this client can ask for `common_type<A, B>`.

+[heading How common_type behaves with pointers?]
+
+Consider
+
+ struct C { }:
+ struct B : C { };
+ struct A : C { };
+
+
+Shouldn't `common_type<A*,B*>::type` be `C*`? I would say yes, but the default implementation make it ill-formed.
+
+The library could add a specialization for pointers, as
+
+ namespace boost
+ {
+
+ template <typename A, typename B>
+ struct common_type<A*, B*> {
+ typedef common_type<A, B>* type;
+ };
+ }
+
+But tin the absence of a motivating use cases, we prefere to don't add more than what the standard specifies.
+
+Of course the user can always make this specialization.
+
+[/
[heading Can you explain the pros/cons of common_type against Boost.Typeof?]

Even if in a first look they sound to be close, __common_type__ and typeof have
@@ -542,16 +630,17 @@

Suppose I have a mixed type vector2 class with a magnitude_squared function defined as:

-template <typename X, typename Y>
-BOOST_TYPEOF_TPL(X() * X() + Y() * Y()) magnitude_squared(const
-vector2<X, Y> &v) {
- return v.x * v.x + v.y * v.y;
-}
+ template <typename X, typename Y>
+ BOOST_TYPEOF_TPL(X() * X() + Y() * Y()) magnitude_squared(const
+ vector2<X, Y> &v) {
+ return v.x * v.x + v.y * v.y;
+ }

__common_type__ is closer in nature to promote_args<class ...T> in boost/math/tools/promotion.hpp than it is to Boost.Typeof, though it is not exactly the same as promote_args either. __common_type__<T1, T2>::type simply represents the result of some operation on T1 and T2, and defaults to the type obtained by putting T1 and T2 into a conditional statement.

It is meant to be customizable (via specialization) if this default is not appropriate.
+]

[endsect]

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65339 - sandbox/chrono/libs/stopwatches/doc/html"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r65337 - in sandbox/chrono/libs/ratio/doc: . html"

Date view	Thread view	Subject view	Author view

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