[Boost-commit] svn:boost r77879 - trunk/libs/fusion/doc

Subject: [Boost-commit] svn:boost r77879 - trunk/libs/fusion/doc
From: joel_at_[hidden]
Date: 2012-04-09 22:30:19

Author: djowel
Date: 2012-04-09 22:30:18 EDT (Mon, 09 Apr 2012)
New Revision: 77879
URL: http://svn.boost.org/trac/boost/changeset/77879

Log:
Added deque docs
Text files modified: 
   trunk/libs/fusion/doc/container.qbk |   524 +++++++++++++++++++++++++++++++++++++++ 
   trunk/libs/fusion/doc/fusion.qbk    |     9                                         
   2 files changed, 525 insertions(+), 8 deletions(-)

Modified: trunk/libs/fusion/doc/container.qbk
==============================================================================
--- trunk/libs/fusion/doc/container.qbk	(original)
+++ trunk/libs/fusion/doc/container.qbk	2012-04-09 22:30:18 EDT (Mon, 09 Apr 2012)
@@ -21,10 +21,11 @@
 
 [heading Description]
 
-`vector` is a __random_access_sequence__ of heterogenous typed
-data structured as a simple `struct` where each element is held
-as a member variable. `vector` is the simplest of the Fusion
-sequence container, and in many cases the most efficient.
+`vector` is a __random_access_sequence__ of heterogenous typed data
+structured as a simple `struct` where each element is held as a member
+variable. `vector` is the simplest of the Fusion sequence container (a
+vector with N elements is just a struct with N members), and in many
+cases the most efficient.
 
 [heading Header]
 
@@ -246,7 +247,7 @@
 
 [table
     [[Parameter]            [Description]               [Default]]
-    [[`T0`...`TN`]          [Element types]             [['unspecified-type]]]
+    [[`T0`...`TN`]          [Element types]             [[`unspecified-type`]]]
 ]
 
 [heading Model of]
@@ -289,6 +290,238 @@
 
 [endsect]
 
+[section deque]
+
+[heading Description]
+
+`deque` is a simple __bidirectional_sequence__ that supports
+constant-time insertion and removal of elements at both ends. Like the
+__list__ and __cons__, `deque` is more efficient than __vector__
+(especially at compile time) when the target sequence is constructed
+piecemeal (a data at a time, e.g. when constructing expression
+templates). Like the __list__ and __cons__, runtime cost of access to
+each element is peculiarly constant (see __recursive_inline__).
+
+Element insertion and removal are done by special `deque` helper classes
+__front_extended_deque__ and __back_extended_deque__.
+
+[heading Header]
+
+    #include <boost/fusion/container/deque.hpp>
+    #include <boost/fusion/include/deque.hpp>
+    #include <boost/fusion/container/list/deque_fwd.hpp>
+    #include <boost/fusion/include/deque_fwd.hpp>
+
+[heading C++03 Synopsis]
+
+    template <
+        typename T0 = __unspecified__
+      , typename T1 = __unspecified__
+      , typename T2 = __unspecified__
+        ...
+      , typename TN = __unspecified__
+    >
+    struct deque;
+
+The variadic class interface accepts `0` to `FUSION_MAX_DEQUE_SIZE`
+elements, where `FUSION_MAX_DEQUE_SIZE` is a user definable predefined
+maximum that defaults to `10`. Example:
+
+    deque<int, char, double>
+
+You may define the preprocessor constant `FUSION_MAX_DEQUE_SIZE` before
+including any Fusion header to change the default. Example:
+
+    #define FUSION_MAX_DEQUE_SIZE 20
+
+[heading C++03 Template parameters]
+
+[table
+    [[Parameter]            [Description]               [Default]]
+    [[`T0`...`TN`]          [Element types]             [[`unspecified-type`]]]
+]
+
+[heading C++11 Synopsis]
+
+    template <typename ...Elements>
+    struct deque;
+
+For C++11 compilers, the variadic class interface has no upper bound.
+
+[heading C++11 Template parameters]
+
+[table
+    [[Parameter]            [Description]               [Default]]
+    [[`Elements`]           [Element types]             [[]]]
+]
+
+[heading Model of]
+
+* __bidirectional_sequence__
+
+[variablelist Notation
+    [[`D`]              [A `deque` type]]
+    [[`d`, `d2`]        [Instances of `deque`]]
+    [[`e0`...`en`]      [Heterogeneous values]]
+    [[`s`]              [A __forward_sequence__]]
+    [[`N`]              [An __mpl_integral_constant__]]
+]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is not
+defined in __bidirectional_sequence__.
+
+[table
+    [[Expression]           [Semantics]]
+    [[`D()`]                [Creates a deque with default constructed elements.]]
+    [[`D(e0, e1,... en)`]   [Creates a deque with elements `e0`...`en`.]]
+    [[`D(s)`]               [Copy constructs a deque from a __forward_sequence__, `s`.]]
+    [[`d = s`]              [Assigns to a deque, `d`, from a __forward_sequence__, `s`.]]
+    [[`__at__<N>(d)`]       [The Nth element from the beginning of the sequence; see __at__.]]
+]
+
+[blurb __note__ `__at__<N>(d)` is provided for convenience, despite
+`deque` being a __bidirectional_sequence__ only (`at` is supposed to be
+a __random_access_sequence__ requirement). The runtime complexity of
+__at__ is constant (see __recursive_inline__). `deque` element access
+utilizes operator overloading with argument dependent lookup (ADL) of
+the proper element getter function given a static constant index
+parameter. Interestingly, with modern C++ compilers, this lookup is very
+fast and rivals recursive template instantiations in compile time-speed,
+so much so that `deque` relies on ADL for all element access (indexing)
+as well as iteration.]
+
+[heading Example]
+
+    deque<int, float> d(12, 5.5f);
+    std::cout << __at_c__<0>(d) << std::endl;
+    std::cout << __at_c__<1>(d) << std::endl;
+
+[endsect]
+
+[section front_extended_deque]
+
+[heading Description]
+
+`front_extended_deque` allows a __deque__ to be front extended. It shares
+the same properties as the __deque__.
+
+[heading Header]
+
+    See __deque__
+
+[heading Synopsis]
+
+    template <typename Deque, typename T>
+    struct front_extended_deque;
+
+[heading Template parameters]
+
+[table
+    [[Parameter]            [Description]               [Default]]
+    [[`Deque`]              [Deque type]                []]
+    [[`T`]                  [Element type]              []]
+]
+
+[`Deque` can be a __deque__, a __front_extended_deque__ or a
+__back_extended_deque__]
+
+[heading Model of]
+
+* __bidirectional_sequence__
+
+[variablelist Notation
+    [[`D`]              [A `front_extended_deque` type]]
+    [[`e`]              [Heterogeneous value]]
+    [[`N`]              [An __mpl_integral_constant__]]
+]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is
+not defined in __bidirectional_sequence__.
+
+[table
+    [[Expression]           [Semantics]]
+    [[`D(d, e)`]            [Extend `d` prepending `e` to its front.]]
+    [[`__at__<N>(d)`]       [The Nth element from the beginning of the sequence; see __at__.]]
+]
+
+[blurb __note__ See __deque__ for further details.]
+
+[heading Example]
+
+    typedef deque<int, float> initial_deque;
+    initial_deque d(12, 5.5f);
+    front_extended_deque<initial_deque, int> d2(d, 999);
+    std::cout << __at_c__<0>(d2) << std::endl;
+    std::cout << __at_c__<1>(d2) << std::endl;
+    std::cout << __at_c__<2>(d2) << std::endl;
+
+[endsect]
+
+[section back_extended_deque]
+
+[heading Description]
+
+`back_extended_deque` allows a __deque__ to be back extended. It shares
+the same properties as the __deque__.
+
+[heading Header]
+
+    See __deque__
+
+[heading Synopsis]
+
+    template <typename Deque, typename T>
+    struct back_extended_deque;
+
+[heading Template parameters]
+
+[table
+    [[Parameter]            [Description]               [Default]]
+    [[`Deque`]              [Deque type]                []]
+    [[`T`]                  [Element type]              []]
+]
+
+[`Deque` can be a __deque__, a __back_extended_deque__ or a
+__back_extended_deque__]
+
+[heading Model of]
+
+* __bidirectional_sequence__
+
+[variablelist Notation
+    [[`D`]              [A `back_extended_deque` type]]
+    [[`e`]              [Heterogeneous value]]
+    [[`N`]              [An __mpl_integral_constant__]]
+]
+
+[heading Expression Semantics]
+
+Semantics of an expression is defined only where it differs from, or is
+not defined in __bidirectional_sequence__.
+
+[table
+    [[Expression]           [Semantics]]
+    [[`D(d, e)`]            [Extend `d` prepending `e` to its back.]]
+    [[`__at__<N>(d)`]       [The Nth element from the beginning of the sequence; see __at__.]]
+]
+
+[blurb __note__ See __deque__ for further details.]
+
+[heading Example]
+
+    typedef deque<int, float> initial_deque;
+    initial_deque d(12, 5.5f);
+    back_extended_deque<initial_deque, int> d2(d, 999);
+    std::cout << __at_c__<0>(d2) << std::endl;
+    std::cout << __at_c__<1>(d2) << std::endl;
+    std::cout << __at_c__<2>(d2) << std::endl;
+
+[endsect]
+
 [section set]
 
 [heading Description]
@@ -332,7 +565,7 @@
 
 [table
     [[Parameter]            [Description]               [Default]]
-    [[`T0`...`TN`]          [Element types]             [['unspecified-type]]]
+    [[`T0`...`TN`]          [Element types]             [[`unspecified-type`]]]
 ]
 
 [heading Model of]
@@ -414,7 +647,7 @@
 
 [table
     [[Parameter]            [Description]               [Default]]
-    [[`T0`...`TN`]          [Element types]             [['unspecified-type]]]
+    [[`T0`...`TN`]          [Element types]             [[`unspecified-type`]]]
 ]
 
 [heading Model of]
@@ -617,6 +850,78 @@
 
 [endsect]
 
+[section make_deque]
+
+[heading Description]
+
+Create a __deque__ from one or more values.
+
+[heading C++03 Synopsis]
+
+    template <typename T0, typename T1,... typename TN>
+    typename __result_of_make_deque__<T0, T1,... TN>::type
+    make_deque(T0 const& x0, T1 const& x1... TN const& xN);
+
+The variadic function accepts `0` to `FUSION_MAX_DEQUE_SIZE` elements, where
+`FUSION_MAX_DEQUE_SIZE` is a user definable predefined maximum that defaults
+to `10`. You may define the preprocessor constant `FUSION_MAX_DEQUE_SIZE`
+before including any Fusion header to change the default. Example:
+
+    #define FUSION_MAX_DEQUE_SIZE 20
+
+[heading C++03 Parameters]
+
+[table
+    [[Parameter]        [Requirement]                   [Description]]
+    [[`x0, x1,... xN`]  [Instances of `T0, T1,... TN`]  [The arguments to `make_deque`]]
+]
+
+[heading C++03 Expression Semantics]
+
+    make_deque(x0, x1,... xN);
+
+[*Return type]: __result_of_make_deque__`<T0, T1,... TN>::type`
+
+[*Semantics]: Create a __deque__ from `x0, x1,... xN`.
+
+[heading C++11 Synopsis]
+
+    template <typename ...Elements>
+    typename __result_of_make_deque__<Elements...>::type
+    make_deque(Elements const&... elements);
+
+For C++11 compilers, the variadic function interface has no upper bound.
+
+[heading C++11 Parameters]
+
+[table
+    [[Parameter]            [Description]               [Description]]
+    [[`elements`]           [Instances of `Elements`]   [The arguments to `make_deque`]]
+]
+
+[heading C++11 Expression Semantics]
+
+    make_deque(elements...);
+
+[*Return type]: __result_of_make_deque__`<Elements...>::type`
+
+[*Semantics]: Create a __deque__ from `elements...`.
+
+[heading Header]
+
+    #include <boost/fusion/container/generation/make_deque.hpp>
+    #include <boost/fusion/include/make_deque.hpp>
+
+[heading Example]
+
+    make_deque(123, "hello", 12.5)
+
+[heading See also]
+
+__note_boost_ref__
+
+[endsect]
+
 [section make_set]
 
 [heading Description]
@@ -734,6 +1039,7 @@
 * __list_tie__
 * __vector_tie__
 * __map_tie__
+* __deque_tie__
 
 Example:
 
@@ -914,6 +1220,76 @@
 
 [endsect]
 
+[section deque_tie]
+
+[heading Description]
+
+Constructs a tie using a __deque__ sequence.
+
+[heading C++03 Synopsis]
+
+    template <typename T0, typename T1,... typename TN>
+    __deque__<T0&, T1&,... TN&>
+    deque_tie(T0& x0, T1& x1... TN& xN);
+
+The variadic function accepts `0` to `FUSION_MAX_DEQUE_SIZE` elements, where
+`FUSION_MAX_DEQUE_SIZE` is a user definable predefined maximum that defaults
+to `10`. You may define the preprocessor constant `FUSION_MAX_DEQUE_SIZE`
+before including any Fusion header to change the default. Example:
+
+    #define FUSION_MAX_DEQUE_SIZE 20
+
+[heading C++03 Parameters]
+
+[table
+    [[Parameter]        [Requirement]                       [Description]]
+    [[`x0, x1,... xN`]  [Instances of `T0, T1,... TN`]      [The arguments to `deque_tie`]]
+]
+
+[heading C++03 Expression Semantics]
+
+    deque_tie(x0, x1,... xN);
+
+[*Return type]: __deque__<T0&, T1&,... TN&>
+
+[*Semantics]: Create a __deque__ of references from `x0, x1,... xN`.
+
+[heading C++11 Synopsis]
+
+    template <typename ...Elements>
+    __deque__<Elements&...>
+    deque_tie(Elements&... elements);
+
+For C++11 compilers, the variadic function interface has no upper bound.
+
+[heading C++11 Parameters]
+
+[table
+    [[Parameter]            [Description]               [Description]]
+    [[`elements`]           [Instances of `Elements`]   [The arguments to `deque_tie`]]
+]
+
+[heading C++11 Expression Semantics]
+
+    deque_tie(elements...);
+
+[*Return type]: __deque__<Elements&...>
+
+[*Semantics]: Create a __deque__ of references from `elements...`.
+
+[heading Header]
+
+    #include <boost/fusion/container/generation/deque_tie.hpp>
+    #include <boost/fusion/include/deque_tie.hpp>
+
+[heading Example]
+
+    int i = 123;
+    double d = 123.456;
+    deque_tie(i, d)
+
+[endsect]
+
 [endsect]
 
 [section MetaFunctions]
@@ -1048,6 +1424,74 @@
 
 [endsect]
 
+[section make_deque]
+
+[heading Description]
+
+Returns the result type of __make_deque__.
+
+[heading C++03 Synopsis]
+
+    template <typename T0, typename T1,... typename TN>
+    struct make_deque;
+
+The variadic function accepts `0` to `FUSION_MAX_DEQUE_SIZE` elements, where
+`FUSION_MAX_DEQUE_SIZE` is a user definable predefined maximum that defaults
+to `10`. You may define the preprocessor constant `FUSION_MAX_DEQUE_SIZE`
+before including any Fusion header to change the default. Example:
+
+    #define FUSION_MAX_DEQUE_SIZE 20
+
+[heading C++03 Parameters]
+
+[table
+    [[Parameter]        [Requirement]       [Description]]
+    [[`T0, T1,... TN`]  [Any type]          [Template arguments to `make_deque`]]
+]
+
+[heading C++03 Expression Semantics]
+
+    result_of::make_deque<T0, T1,... TN>::type
+
+[*Return type]: A __deque__ with elements of types converted following the
+rules for __element_conversion__.
+
+[*Semantics]: Create a __deque__ from `T0, T1,... TN`.
+
+[heading C++11 Synopsis]
+
+    template <typename ...Elements>
+    struct make_deque;
+
+For C++11 compilers, the variadic template interface has no upper bound.
+
+[heading C++11 Parameters]
+
+[table
+    [[Parameter]        [Requirement]               [Description]]
+    [[`Elements`]       [Variadic template types]   [Template arguments to `make_deque`]]
+]
+
+[heading C++11 Expression Semantics]
+
+    result_of::make_deque<Elements...>::type
+
+[*Return type]: A __deque__ with elements of types converted following the
+rules for __element_conversion__.
+
+[*Semantics]: Create a __deque__ from `Elements...`.
+
+[heading Header]
+
+    #include <boost/fusion/container/generation/make_deque.hpp>
+    #include <boost/fusion/include/make_deque.hpp>
+
+[heading Example]
+
+    result_of::make_deque<int, const char(&)[7], double>::type
+
+[endsect]
+
 [section make_set]
 
 [heading Description]
@@ -1240,6 +1684,72 @@
 
 [endsect]
 
+[section deque_tie]
+
+[heading Description]
+
+Returns the result type of __deque_tie__.
+
+[heading C++03 Synopsis]
+
+    template <typename T0, typename T1,... typename TN>
+    struct deque_tie;
+
+The variadic function accepts `0` to `FUSION_MAX_DEQUE_SIZE` elements, where
+`FUSION_MAX_DEQUE_SIZE` is a user definable predefined maximum that defaults
+to `10`. You may define the preprocessor constant `FUSION_MAX_DEQUE_SIZE`
+before including any Fusion header to change the default. Example:
+
+    #define FUSION_MAX_DEQUE_SIZE 20
+
+[heading C++03 Parameters]
+
+[table
+    [[Parameter]        [Requirement]       [Description]]
+    [[`T0, T1,... TN`]  [Any type]          [The arguments to `deque_tie`]]
+]
+
+[heading C++03 Expression Semantics]
+
+    result_of::deque_tie<T0, T1,... TN>::type;
+
+[*Return type]: __deque__<T0&, T1&,... TN&>
+
+[*Semantics]: Create a __deque__ of references from `T0, T1,... TN`.
+
+[heading C++11 Synopsis]
+
+    template <typename ...Elements>
+    struct deque_tie;
+
+For C++11 compilers, the variadic template interface has no upper bound.
+
+[heading C++11 Parameters]
+
+[table
+    [[Parameter]        [Requirement]               [Description]]
+    [[`Elements`]       [Variadic template types]   [Template arguments to `deque_tie`]]
+]
+
+[heading C++11 Expression Semantics]
+
+    result_of::deque_tie<Elements...>::type;
+
+[*Return type]: __deque__<Elements&...>
+
+[*Semantics]: Create a __deque__ of references from `Elements...`.
+
+[heading Header]
+
+    #include <boost/fusion/container/generation/deque_tie.hpp>
+    #include <boost/fusion/include/deque_tie.hpp>
+
+[heading Example]
+
+    result_of::deque_tie<int, double>::type
+
+[endsect]
+
 [section map_tie]
 
 [heading Description]

Modified: trunk/libs/fusion/doc/fusion.qbk
==============================================================================
--- trunk/libs/fusion/doc/fusion.qbk	(original)
+++ trunk/libs/fusion/doc/fusion.qbk	2012-04-09 22:30:18 EDT (Mon, 09 Apr 2012)
@@ -11,7 +11,7 @@
     [quickbook 1.3]
     [version 2.2]
     [authors [de Guzman, Joel], [Marsden, Dan], [Schwinger, Tobias]]
-    [copyright 2001 2002 2003 2004 2005 2006 2011 Joel de Guzman, Dan Marsden, Tobias Schwinger]
+    [copyright 2001 2002 2003 2004 2005 2006 2011 2012 Joel de Guzman, Dan Marsden, Tobias Schwinger]
     [purpose Statically Typed Heterogeneous Data Structures and Algorithms]
     [license
         Distributed under the Boost Software License, Version 1.0.
@@ -116,6 +116,9 @@
 [def __vector__                 [link fusion.container.vector `vector`]]
 [def __cons__                   [link fusion.container.cons `cons`]]
 [def __list__                   [link fusion.container.list `list`]]
+[def __deque__                  [link fusion.container.deque `deque`]]
+[def __front_extended_deque__   [link fusion.container.front_extended_deque `front_extended_deque`]]
+[def __back_extended_deque__    [link fusion.container.back_extended_deque `back_extended_deque`]]
 [def __set__                    [link fusion.container.set `set`]]
 [def __map__                    [link fusion.container.map `map`]]
 
@@ -198,12 +201,16 @@
 [def __result_of_make_cons__    [link fusion.container.generation.metafunctions.make_cons `result_of::make_cons`]]
 [def __make_list__              [link fusion.container.generation.functions.make_list `make_list`]]
 [def __result_of_make_list__    [link fusion.container.generation.metafunctions.make_list `result_of::make_list`]]
+[def __make_deque__             [link fusion.container.generation.functions.make_deque `make_deque`]]
+[def __result_of_make_deque__   [link fusion.container.generation.metafunctions.make_deque `result_of::make_deque`]]
 [def __make_set__               [link fusion.container.generation.functions.make_set `make_set`]]
 [def __result_of_make_set__     [link fusion.container.generation.metafunctions.make_set `result_of::make_set`]]
 [def __make_map__               [link fusion.container.generation.functions.make_map `make_map`]]
 [def __result_of_make_map__     [link fusion.container.generation.metafunctions.make_map `result_of::make_map`]]
 [def __list_tie__               [link fusion.container.generation.functions.list_tie `list_tie`]]
 [def __result_of_list_tie__     [link fusion.container.generation.metafunctions.list_tie `result_of::list_tie`]]
+[def __deque_tie__              [link fusion.container.generation.functions.deque_tie `deque_tie`]]
+[def __result_of_deque_tie__    [link fusion.container.generation.metafunctions.deque_tie `result_of::deque_tie`]]
 
 [def __out__                    [link fusion.sequence.operator.i_o.out out]]
 [def __in__                     [link fusion.sequence.operator.i_o.in in]]