From a3c225801743386df2bad2faf55d76cfcc43c5a3 Mon Sep 17 00:00:00 2001 From: Joel de Guzman Date: Tue, 10 Apr 2012 02:30:18 +0000 Subject: [PATCH] Added deque docs [SVN r77879] --- doc/container.qbk | 524 +++++++++++++++++++++++++++++++++++++++++++++- doc/fusion.qbk | 9 +- 2 files changed, 525 insertions(+), 8 deletions(-) diff --git a/doc/container.qbk b/doc/container.qbk index f8a13e03..51ad2230 100644 --- a/doc/container.qbk +++ b/doc/container.qbk @@ -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 + #include + #include + #include + +[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 + +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 + 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__(d)`] [The Nth element from the beginning of the sequence; see __at__.]] +] + +[blurb __note__ `__at__(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 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 + 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__(d)`] [The Nth element from the beginning of the sequence; see __at__.]] +] + +[blurb __note__ See __deque__ for further details.] + +[heading Example] + + typedef deque initial_deque; + initial_deque d(12, 5.5f); + front_extended_deque 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 + 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__(d)`] [The Nth element from the beginning of the sequence; see __at__.]] +] + +[blurb __note__ See __deque__ for further details.] + +[heading Example] + + typedef deque initial_deque; + initial_deque d(12, 5.5f); + back_extended_deque 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 __result_of_make_deque__::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__`::type` + +[*Semantics]: Create a __deque__ from `x0, x1,... xN`. + +[heading C++11 Synopsis] + + template + typename __result_of_make_deque__::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__`::type` + +[*Semantics]: Create a __deque__ from `elements...`. + +[heading Header] + + #include + #include + +[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 + __deque__ + 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__ + +[*Semantics]: Create a __deque__ of references from `x0, x1,... xN`. + +[heading C++11 Synopsis] + + template + __deque__ + 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__ + +[*Semantics]: Create a __deque__ of references from `elements...`. + +[heading Header] + + #include + #include + +[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 + 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::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 + 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::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 + #include + +[heading Example] + + result_of::make_deque::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 + 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::type; + +[*Return type]: __deque__ + +[*Semantics]: Create a __deque__ of references from `T0, T1,... TN`. + +[heading C++11 Synopsis] + + template + 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::type; + +[*Return type]: __deque__ + +[*Semantics]: Create a __deque__ of references from `Elements...`. + +[heading Header] + + #include + #include + +[heading Example] + + result_of::deque_tie::type + +[endsect] + [section map_tie] [heading Description] diff --git a/doc/fusion.qbk b/doc/fusion.qbk index ce0141b8..28e1f140 100644 --- a/doc/fusion.qbk +++ b/doc/fusion.qbk @@ -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]]