Added deque docs

[SVN r77879]
This commit is contained in:
Joel de Guzman
2012-04-10 02:30:18 +00:00
parent d87b5a8000
commit a3c2258017
2 changed files with 525 additions and 8 deletions

View File

@ -21,10 +21,11 @@ __views__. These containers are more or less counterparts of those in __stl__.
[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 @@ including any Fusion header to change the default. Example:
[table
[[Parameter] [Description] [Default]]
[[`T0`...`TN`] [Element types] [['unspecified-type]]]
[[`T0`...`TN`] [Element types] [[`unspecified-type`]]]
]
[heading Model of]
@ -289,6 +290,238 @@ constant (see __recursive_inline__).]
[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 @@ including any Fusion header to change the default. Example:
[table
[[Parameter] [Description] [Default]]
[[`T0`...`TN`] [Element types] [['unspecified-type]]]
[[`T0`...`TN`] [Element types] [[`unspecified-type`]]]
]
[heading Model of]
@ -414,7 +647,7 @@ including any Fusion header to change the default. Example:
[table
[[Parameter] [Description] [Default]]
[[`T0`...`TN`] [Element types] [['unspecified-type]]]
[[`T0`...`TN`] [Element types] [[`unspecified-type`]]]
]
[heading Model of]
@ -617,6 +850,78 @@ __note_boost_ref__
[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 @@ succeeding sections document the various /tier/ flavors.
* __list_tie__
* __vector_tie__
* __map_tie__
* __deque_tie__
Example:
@ -914,6 +1220,76 @@ including any Fusion header to change the default. Example:
[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 @@ rules for __element_conversion__.
[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 @@ default. Example:
[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]

View File

@ -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]]