[/============================================================================== Copyright (C) 2001-2011 Joel de Guzman Copyright (C) 2006 Dan Marsden Copyright (C) 2014 Christoph Weiss Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ===============================================================================/] [section Sequence] Like __mpl__, the Sequence is a fundamental concept in Fusion. A Sequence may or may not actually store or contain data. __containers__ are sequences that hold data. __views__, on the other hand, are sequences that do not store any data. Instead, they are proxies that impart an alternative presentation over another sequence. All models of Sequence have an associated __iterator__ type that can be used to iterate through the Sequence's elements. [heading Header] #include #include [section Concepts] Fusion Sequences are organized into a hierarchy of concepts. [heading Traversal] Fusion's sequence traversal related concepts parallel Fusion's __iterator_concepts__. __forward_sequence__ is the most basic concept. __bidirectional_sequence__ is a refinement of __forward_sequence__. __random_access_sequence__ is a refinement of __bidirectional_sequence__. These concepts pertain to sequence traversal. [heading Associativity] The __associative_sequence__ concept is orthogonal to traversal. An Associative Sequence allows efficient retrieval of elements based on keys. [heading Boundary] The __unbounded_sequence__ concept is also orthogonal to traversal and associativity. A Unbounded Sequence allows out-of-bounds access. [section Forward Sequence] [heading Description] A Forward Sequence is a Sequence whose elements are arranged in a definite order. The ordering is guaranteed not to change from iteration to iteration. The requirement of a definite ordering allows the definition of element-by-element equality (if the container's element type is Equality Comparable) and of lexicographical ordering (if the container's element type is LessThan Comparable). [variablelist Notation [[`s`] [A Forward Sequence]] [[`S`] [A Forward Sequence type]] [[`o`] [An arbitrary object]] [[`e`] [A Sequence element]] ] [heading Valid Expressions] For any Forward Sequence the following expressions must be valid: [table [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] [[`__begin__(s)`] [__forward_iterator__] [] [Constant]] [[`__end__(s)`] [__forward_iterator__] [] [Constant]] [[`__size__(s)`] [__mpl_integral_constant__. Convertible to int.] [] [Constant]] [[`__empty__(s)`] [__mpl_boolean_constant__. Convertible to bool.] [] [Constant]] [[`__front__(s)`] [Any type] [] [Constant]] [[`__front__(s) = o`] [Any type] [`s` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression.] [Constant]] ] [heading Result Type Expressions] [table [[Expression] [Compile Time Complexity]] [[`__result_of_begin__::type`] [Amortized constant time]] [[`__result_of_end__::type`] [Amortized constant time]] [[`__result_of_size__::type`] [Unspecified]] [[`__result_of_empty__::type`] [Constant time]] [[`__result_of_front__::type`] [Amortized constant time]] ] [heading Expression Semantics] [table [[Expression] [Semantics]] [[`__begin__(s)`] [An iterator to the first element of the sequence; see __begin__.]] [[`__end__(s)`] [A past-the-end iterator to the sequence; see __end__.]] [[`__size__(s)`] [The size of the sequence; see __size__.]] [[`__empty__(s)`] [A boolean Integral Constant `c` such that `c::value == true` if and only if the sequence is empty; see __empty__.]] [[`__front__(s)`] [The first element in the sequence; see __front__.]] ] [heading Invariants] For any Forward Sequence s the following invariants always hold: * `[__begin__(s), __end__(s))` is always a valid range. * An __algorithm__ that iterates through the range `[__begin__(s), __end__(s))` will pass through every element of `s` exactly once. * `__begin__(s)` is identical to `__end__(s))` if and only if `s` is empty. * Two different iterations through `s` will access its elements in the same order. [heading Models] * __std_pair__ * __boost_array__ * __vector__ * __cons__ * __list__ * __set__ * __map__ * __single_view__ * __filter_view__ * __iterator_range__ * __joint_view__ * __transform_view__ * __reverse_view__ * __zip_view__ [endsect] [section Bidirectional Sequence] [heading Description] A Bidirectional Sequence is a __forward_sequence__ whose iterators model __bidirectional_iterator__. [heading Refinement of] __forward_sequence__ [variablelist Notation [[`s`] [A Bidirectional Sequence]] [[`S`] [A Bidirectional Sequence type]] [[`o`] [An arbitrary object]] [[`e`] [A Sequence element]] ] [heading Valid Expressions] In addition to the requirements defined in __forward_sequence__, for any Bidirectional Sequence the following must be met: [table [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] [[`__begin__(s)`] [__bidirectional_iterator__] [] [Constant]] [[`__end__(s)`] [__bidirectional_iterator__] [] [Constant]] [[`__back__(s)`] [Any type] [] [Constant]] [[`__back__(s) = o`] [Any type] [`s` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression.] [Constant]] ] [heading Result Type Expressions] [table [[Expression] [Compile Time Complexity]] [[`__result_of_begin__::type`] [Amortized constant time]] [[`__result_of_end__::type`] [Amortized constant time]] [[`__result_of_back__::type`] [Amortized constant time]] ] [heading Expression Semantics] The semantics of an expression are defined only where they differ from, or are not defined in __forward_sequence__. [table [[Expression] [Semantics]] [[`__back__(s)`] [The last element in the sequence; see __back__.]] ] [heading Models] * __std_pair__ * __boost_array__ * __vector__ * __map__ * __reverse_view__ * __single_view__ * __iterator_range__ (where adapted sequence is a Bidirectional Sequence) * __transform_view__ (where adapted sequence is a Bidirectional Sequence) * __zip_view__ (where adapted sequences are models of Bidirectional Sequence) [endsect] [section Random Access Sequence] [heading Description] A Random Access Sequence is a __bidirectional_sequence__ whose iterators model __random_access_iterator__. It guarantees constant time access to arbitrary sequence elements. [heading Refinement of] __bidirectional_sequence__ [variablelist Notation [[`s`] [A Random Access Sequence]] [[`S`] [A Random Access Sequence type]] [[`M`] [An __mpl__ integral constant]] [[`N`] [An integral constant]] [[`o`] [An arbitrary object]] [[`e`] [A Sequence element]] ] [heading Valid Expressions] In addition to the requirements defined in __bidirectional_sequence__, for any Random Access Sequence the following must be met: [table [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] [[`__begin__(s)`] [__random_access_iterator__] [] [Constant]] [[`__end__(s)`] [__random_access_iterator__] [] [Constant]] [[`__at_c__(s)`] [Any type] [] [Constant]] [[`__at_c__(s) = o`] [Any type] [`s` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression.] [Constant]] [[`__at__(s)`] [Any type] [] [Constant]] [[`__at__(s) = o`] [Any type] [`s` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression.] [Constant]] ] [heading Result Type Expressions] [table [[Expression] [Compile Time Complexity]] [[`__result_of_begin__::type`] [Amortized constant time]] [[`__result_of_end__::type`] [Amortized constant time]] [[`__result_of_at__::type`] [Amortized constant time]] [[`__result_of_at_c__::type`] [Amortized constant time]] [[`__result_of_value_at__::type`] [Amortized constant time]] [[`__result_of_value_at_c__::type`] [Amortized constant time]] ] [note `__result_of_at__` returns the actual type returned by `__at__(s)`. In most cases, this is a reference. Hence, there is no way to know the exact element type using `__result_of_at__`.The element at `M` may actually be a reference to begin with. For this purpose, you can use `__result_of_value_at__` (Note that, `__result_of_value_at_c__` is a counterpart of `__result_of_at_c__` as well).] [heading Expression Semantics] The semantics of an expression are defined only where they differ from, or are not defined in __bidirectional_sequence__. [table [[Expression] [Semantics]] [[`__at__(s)`] [The Mth element from the beginning of the sequence; see __at__.]] [[`__at_c__(s)`] [The Nth element from the beginning of the sequence; see __at_c__.]] ] [heading Models] * __std_pair__ * __boost_array__ * __vector__ * __map__ * __reverse_view__ * __single_view__ * __iterator_range__ (where adapted sequence is a Random Access Sequence) * __transform_view__ (where adapted sequence is a Random Access Sequence) * __zip_view__ (where adapted sequences are models of Random Access Sequence) [endsect] [section Associative Sequence] [heading Description] An Associative Sequence allows efficient retrieval of elements based on keys. Like associative sequences in __mpl__, and unlike associative containers in __stl__, Fusion associative sequences have no implied ordering relation. Instead, type identity is used to impose an equivalence relation on keys. Keys are not checked for uniqueness. [variablelist Notation [[`s`] [An Associative Sequence]] [[`S`] [An Associative Sequence type]] [[`K`] [An arbitrary /key/ type]] [[`o`] [An arbitrary object]] [[`e`] [A Sequence element]] ] [heading Valid Expressions] For any Associative Sequence the following expressions must be valid: [table [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] [[`__has_key__(s)`] [__mpl_boolean_constant__. Convertible to bool.] [] [Constant]] [[`__at_key__(s)`] [Any type] [] [Constant]] [[`__at_key__(s) = o`] [Any type] [`s` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression.] [Constant]] ] [heading Result Type Expressions] [table [[Expression] [Compile Time Complexity]] [[`__result_of_has_key__::type`] [Amortized constant time]] [[`__result_of_at_key__::type`] [Amortized constant time]] [[`__result_of_value_at_key__::type`] [Amortized constant time]] ] [note `__result_of_at_key__` returns the actual type returned by `__at_key__(s)`. In most cases, this is a reference. Hence, there is no way to know the exact element type using `__result_of_at_key__`.The element at `K` may actually be a reference to begin with. For this purpose, you can use `__result_of_value_at_key__`.] [heading Expression Semantics] [table [[Expression] [Semantics]] [[`__has_key__(s)`] [A boolean Integral Constant `c` such that `c::value == true` if and only if there is one or more elements with the key `k` in `s`; see __has_key__.]] [[`__at_key__(s)`] [The element associated with the key `K` in the sequence `s`; see __at__.]] ] [heading Models] * __set__ * __map__ * __filter_view__ (where adapted sequence is an __associative_sequence__ and a __forward_sequence__) * __iterator_range__ (where adapted iterators are __associative_iterator__\ s) * __joint_view__ (where adapted sequences are __associative_sequence__\ s and __forward_sequence__\ s) * __reverse_view__ (where adapted sequence is an __associative_sequence__ and a __bidirectional_sequence__) [endsect] [section Unbounded Sequence] [heading Description] A Unbounded Sequence allows Out-of-Bounds access: it will achieve something like a __window_function__. Most of the sequences do not meet this concept, but some special usecases do. [important User extending sequences should handle any parameters or be SFINAE-friendly.] [variablelist Notation [[`s`] [An Fusion Sequence]] [[`S`] [An Fusion Sequence type]] [[`M`] [An __mpl__ integral constant]] [[`N`] [An integral constant]] [[`K`] [An arbitrary /key/ type]] [[`o`] [An arbitrary object]] [[`e`] [A Sequence element]] ] [heading Valid Expressions] [table [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] [[`__at_c__(s)`] [Any type] [] [Depends on its traversability]] [[`__at_c__(s) = o`] [Any type] [] [Depends on its traversability]] [[`__at__(s)`] [Any type] [] [Depends on its traversability]] [[`__at__(s) = o`] [Any type] [] [Depends on its traversability]] [[`__at_key__(s)`] [Any type] [`S` should be __associative_sequence__] [Depends on its traversability]] [[`__at_key__(s) = o`] [Any type] [`S` should be __associative_sequence__] [Depends on its traversability]] ] [heading Result Type Expressions] [table [[Expression] [Compile Time Complexity]] [[`__result_of_at__::type`] [Depends on its traversability]] [[`__result_of_at_c__::type`] [Depends on its traversability]] [[`__result_of_value_at__::type`] [Depends on its traversability]] [[`__result_of_value_at_c__::type`] [Depends on its traversability]] [[`__result_of_at_key__::type`] [Depends on its traversability]] [[`__result_of_value_at_key__::type`] [Depends on its traversability]] ] [heading Models] * none. [endsect] [endsect] [section Intrinsic] Intrinsic form the essential interface of every Fusion __sequence__. __stl__ counterparts of these functions are usually implemented as member functions. Intrinsic functions, unlike __algorithms__, are not generic across the full __sequence__ repertoire. They need to be implemented for each Fusion __sequence__[footnote In practice, many of intrinsic functions have default implementations that will work in majority of cases]. [heading Header] #include #include [section Functions] [section begin] [heading Description] Returns an iterator pointing to the first element in the sequence. [heading Synopsis] template typename __result_of_begin__::type begin(Sequence& seq); template typename __result_of_begin__::type begin(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __forward_sequence__] [The sequence we wish to get an iterator from.]] ] [heading Expression Semantics] begin(seq); [*Return type]: * A model of __forward_iterator__ if `seq` is a __forward_sequence__ else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ else, __random_access_iterator__ if `seq` is a __random_access_sequence__. * A model of __associative_iterator__ if `seq` is an __associative_sequence__. [*Semantics]: Returns an iterator pointing to the first element in the sequence. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(__deref__(begin(v)) == 1); [endsect] [section end] [heading Description] Returns an iterator pointing to one element past the end of the sequence. [heading Synopsis] template typename __result_of_end__::type end(Sequence& seq); template typename __result_of_end__::type end(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __forward_sequence__] [The sequence we wish to get an iterator from.]] ] [heading Expression Semantics] end(seq); [*Return type]: * A model of __forward_iterator__ if `seq` is a __forward_sequence__ else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ else, __random_access_iterator__ if `seq` is a __random_access_sequence__. * A model of __associative_iterator__ if `seq` is an __associative_sequence__. [*Semantics]: Returns an iterator pointing to one element past the end of the sequence. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(__deref__(__prior__(end(v))) == 3); [endsect] [section empty] [heading Description] Returns a type convertible to `bool` that evaluates to `true` if the sequence is empty, else, evaluates to `false`. [heading Synopsis] template typename __result_of_empty__::type empty(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] ] [heading Expression Semantics] empty(seq); [*Return type]: Convertible to `bool`. [*Semantics]: Evaluates to `true` if the sequence is empty, else, evaluates to `false`. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(empty(v) == false); [endsect] [section front] [heading Description] Returns the first element in the sequence. [heading Synopsis] template typename __result_of_front__::type front(Sequence& seq); template typename __result_of_front__::type front(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] ] [heading Expression Semantics] front(seq); [*Return type]: Returns a reference to the first element in the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the first element in the sequence, is a valid expression. Else, returns a type convertible to the first element in the sequence. [*Precondition]: `__empty__(seq) == false` [*Semantics]: Returns the first element in the sequence. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(front(v) == 1); [endsect] [section back] [heading Description] Returns the last element in the sequence. [heading Synopsis] template typename __result_of_back__::type back(Sequence& seq); template typename __result_of_back__::type back(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __bidirectional_sequence__] [The sequence we wish to investigate.]] ] [heading Expression Semantics] back(seq); [*Return type]: Returns a reference to the last element in the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the last element in the sequence, is a valid expression. Else, returns a type convertible to the last element in the sequence. [*Precondition]: `__empty__(seq) == false` [*Semantics]: Returns the last element in the sequence. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(back(v) == 3); [endsect] [section size] [heading Description] Returns a type convertible to `int` that evaluates the number of elements in the sequence. [heading Synopsis] template typename __result_of_size__::type size(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] ] [heading Expression Semantics] size(seq); [*Return type]: Convertible to `int`. [*Semantics]: Returns the number of elements in the sequence. [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(size(v) == 3); [endsect] [section at] [heading Description] Returns the M-th element from the beginning of the sequence. [heading Synopsis] template typename __result_of_at__::type at(Sequence& seq); template typename __result_of_at__::type at(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __random_access_sequence__] [The sequence we wish to investigate.]] [[`M`] [An __mpl_integral_constant__] [An index from the beginning of the sequence.]] ] [heading Expression Semantics] at(seq); [*Return type]: Returns a reference to the M-th element from the beginning of the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the M-th element from the beginning of the sequence, is a valid expression. Else, returns a type convertible to the M-th element from the beginning of the sequence. [*Precondition]: `0 <= M::value < __size__(seq)` (where `seq` is not __unbounded_sequence__) [*Semantics]: Equivalent to __deref__(__advance__(__begin__(s))) [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(at >(v) == 2); [endsect] [section at_c] [heading Description] Returns the N-th element from the beginning of the sequence. [heading Synopsis] template typename __result_of_at_c__::type at_c(Sequence& seq); template typename __result_of_at_c__::type at_c(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __random_access_sequence__] [The sequence we wish to investigate.]] [[`N`] [An integral constant] [An index from the beginning of the sequence.]] ] [heading Expression Semantics] at_c(seq); [*Return type]: Returns a reference to the N-th element from the beginning of the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the N-th element from the beginning of the sequence, is a valid expression. Else, returns a type convertible to the N-th element from the beginning of the sequence. [*Precondition]: `0 <= N < __size__(seq)` (where `seq` is not __unbounded_sequence__) [*Semantics]: Equivalent to __deref__(__advance__(__begin__(s))) [heading Header] #include #include [heading Example] __vector__ v(1, 2, 3); assert(at_c<1>(v) == 2); [endsect] [section has_key] [heading Description] Returns a type convertible to `bool` that evaluates to `true` if the sequence contains an element associated with a Key, else, evaluates to `false`. [heading Synopsis] template typename __result_of_has_key__::type has_key(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __associative_sequence__] [The sequence we wish to investigate.]] [[`Key`] [Any type] [The queried key.]] ] [heading Expression Semantics] has_key(seq); [*Return type]: Convertible to `bool`. [*Semantics]: Evaluates to `true` if the sequence contains an element associated with Key, else, evaluates to `false`. [heading Header] #include #include [heading Example] __set__ s(1, 'x', true); assert(has_key(s) == true); [endsect] [section at_key] [heading Description] Returns the element associated with a Key from the sequence. [heading Synopsis] template typename __result_of_at_key__::type at_key(Sequence& seq); template typename __result_of_at_key__::type at_key(Sequence const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Model of __associative_sequence__] [The sequence we wish to investigate.]] [[`Key`] [Any type] [The queried key.]] ] [heading Expression Semantics] at_key(seq); [*Return type]: Returns a reference to the element associated with Key from the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the element associated with Key, is a valid expression. Else, returns a type convertible to the element associated with Key. [*Precondition]: `has_key(seq) == true` (where `seq` is not __unbounded_sequence__) [*Semantics]: Returns the element associated with Key. [heading Header] #include #include [heading Example] __set__ s(1, 'x', true); assert(at_key(s) == 'x'); [endsect] [section swap] [heading Description] Performs an element by element swap of the elements in 2 sequences. [heading Synopsis] template typename __result_of_swap__::type swap(Seq1& seq1, Seq2& seq2); [heading Parameters] [table [[Parameters] [Requirement] [Description]] [[`seq1`, `seq2`][Models of __forward_sequence__][The sequences whose elements we wish to swap.]] ] [heading Expression Semantics] swap(seq1, seq2); [*Return type]: `void` [*Precondition]: `__size__(seq1) == __size__(seq2)` [*Semantics]: Calls `swap(a1, b1)` for corresponding elements in `seq1` and `seq2`. [heading Header] #include #include [heading Example] __vector__ v1(1, "hello"), v2(2, "world"); swap(v1, v2); assert(v1 == __make_vector__(2, "world")); assert(v2 == __make_vector__(1, "hello")); [endsect] [endsect] [section Metafunctions] [section begin] [heading Description] Returns the result type of __begin__. [heading Synopsis] template struct begin { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::begin::type [*Return type]: * A model of __forward_iterator__ if `seq` is a __forward_sequence__ else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ else, __random_access_iterator__ if `seq` is a __random_access_sequence__. * A model of __associative_iterator__ if `seq` is an __associative_sequence__. [*Semantics]: Returns the type of an iterator to the first element of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; typedef __result_of_begin__::type it; BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__::type, int&>)) [endsect] [section end] [heading Description] Returns the result type of __end__. [heading Synopsis] template struct end { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::end::type [*Return type]: * A model of __forward_iterator__ if `seq` is a __forward_sequence__ else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ else, __random_access_iterator__ if `seq` is a __random_access_sequence__. * A model of __associative_iterator__ if `seq` is an __associative_sequence__. [*Semantics]: Returns the type of an iterator one past the end of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; typedef __result_of_prior__<__result_of_end__::type>::type first; BOOST_MPL_ASSERT((__result_of_equal_to__::type>)) [endsect] [section empty] [heading Description] Returns the result type of __empty__. [heading Synopsis] template struct empty { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::empty::type [*Return type]: An __mpl_integral_constant__ [*Semantics]: Returns `mpl::true_` if `Seq` has zero elements, `mpl::false_` otherwise. [heading Header] #include #include [heading Example] typedef __vector__<> empty_vec; typedef __vector__ vec; BOOST_MPL_ASSERT((__result_of_empty__)); BOOST_MPL_ASSERT_NOT((__result_of_empty__)); [endsect] [section front] [heading Description] Returns the result type of __front__. [heading Synopsis] template struct front { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::front::type [*Return type]: Any type [*Semantics]: The type returned by dereferencing an iterator to the first element in `Seq`. Equivalent to `__result_of_deref__<__result_of_begin__::type>::type`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_front__::type, int&>)); [endsect] [section back] [heading Description] Returns the result type of __back__. [heading Synopsis] template struct back { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::back::type [*Return type]: Any type [*Semantics]: The type returned by dereferencing an iterator to the last element in the sequence. Equivalent to `__result_of_deref__<__result_of_prior__<__result_of_end__::type>::type>::type`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_back__::type, char&>)); [endsect] [section size] [heading Description] Returns the result type of __size__. [heading Synopsis] template struct size { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __forward_sequence__][Argument sequence]] ] [heading Expression Semantics] result_of::size::type [*Return type]: An __mpl_integral_constant__. [*Semantics]: Returns the number of elements in `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; typedef __result_of_size__::type size_mpl_integral_constant; BOOST_MPL_ASSERT_RELATION(size_mpl_integral_constant::value, ==, 3); [endsect] [section at] [heading Description] Returns the result type of __at__[footnote __result_of_at__ reflects the actual return type of the function __at__. __sequence__(s) typically return references to its elements via the __at__ function. If you want to get the actual element type, use __result_of_value_at__]. [heading Synopsis] template< typename Seq, typename M> struct at { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __random_access_sequence__][Argument sequence]] [[`M`][An __mpl_integral_constant__][Index of element]] ] [heading Expression Semantics] result_of::at::type [*Return type]: Any type. [*Precondition]: `0 <= M::value < __result_of_size__::value` (where `Seq` is not __unbounded_sequence__) [*Semantics]: Returns the result type of using __at__ to access the `M`th element of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_at__ >::type, float&>)); [endsect] [section at_c] [heading Description] Returns the result type of __at_c__[footnote __result_of_at_c__ reflects the actual return type of the function __at_c__. __sequence__(s) typically return references to its elements via the __at_c__ function. If you want to get the actual element type, use __result_of_value_at_c__]. [heading Synopsis] template< typename Seq, int N> struct at_c { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __random_access_sequence__][Argument sequence]] [[`N`][Positive integer index][Index of element]] ] [heading Expression Semantics] result_of::at_c::type [*Return type]: Any type [*Precondition]: `0 <= N < __result_of_size__::value` (where `Seq` is not __unbounded_sequence__) [*Semantics]: Returns the result type of using __at_c__ to access the `N`th element of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_at_c__::type, float&>)); [endsect] [section value_at] [heading Description] Returns the actual type at a given index from the __sequence__. [heading Synopsis] template< typename Seq, typename M> struct value_at { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __random_access_sequence__][Argument sequence]] [[`M`][An __mpl_integral_constant__][Index of element]] ] [heading Expression Semantics] result_of::value_at::type [*Return type]: Any type. [*Semantics]: Returns the actual type at the `M`th element of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at__ >::type, float>)); [endsect] [section value_at_c] [heading Description] Returns the actual type at a given index from the __sequence__. [heading Synopsis] template< typename Seq, int N> struct value_at_c { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __random_access_sequence__][Argument sequence]] [[`N`][Positive integer index][Index of element]] ] [heading Expression Semantics] result_of::value_at_c::type [*Return type]: Any type [*Semantics]: Returns the actual type at the `N`th element of `Seq`. [heading Header] #include #include [heading Example] typedef __vector__ vec; BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at_c__::type, float>)); [endsect] [section has_key] [heading Description] Returns the result type of __has_key__. [heading Synopsis] template< typename Seq, typename Key> struct has_key { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __associative_sequence__][Argument sequence]] [[`Key`][Any type][Key type]] ] [heading Expression Semantics] result_of::has_key::type [*Return type]: An __mpl_integral_constant__. [*Semantics]: Returns `mpl::true_` if `Seq` contains an element with key type `Key`, returns `mpl::false_` otherwise. [heading Header] #include #include [heading Example] typedef __map__<__pair__, __pair__, __pair__ > mymap; BOOST_MPL_ASSERT((__result_of_has_key__)); BOOST_MPL_ASSERT_NOT((__result_of_has_key__)); [endsect] [section at_key] [heading Description] Returns the result type of __at_key__[footnote __result_of_at_key__ reflects the actual return type of the function __at_key__. __sequence__(s) typically return references to its elements via the __at_key__ function. If you want to get the actual element type, use __result_of_value_at_key__]. [heading Synopsis] template< typename Seq, typename Key> struct at_key { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __associative_sequence__][Argument sequence]] [[`Key`][Any type][Key type]] ] [heading Expression Semantics] result_of::at_key::type [*Return type]: Any type. [*Precondition]: `has_key::type::value == true` (where `Seq` is not __unbounded_sequence__) [*Semantics]: Returns the result of using __at_key__ to access the element with key type `Key` in `Seq`. [heading Header] #include #include [heading Example] typedef __map__<__pair__, __pair__, __pair__ > mymap; BOOST_MPL_ASSERT((boost::is_same<__result_of_at_key__::type, char&>)); [endsect] [section value_at_key] [heading Description] Returns the actual element type associated with a Key from the __sequence__. [heading Synopsis] template< typename Seq, typename Key> struct value_at_key { typedef __unspecified__ type; }; [table Parameters [[Parameter] [Requirement] [Description]] [[`Seq`][A model of __associative_sequence__][Argument sequence]] [[`Key`][Any type][Key type]] ] [heading Expression Semantics] result_of::value_at_key::type [*Return type]: Any type. [*Precondition]: `has_key::type::value == true` (where `Seq` is not __unbounded_sequence__) [*Semantics]: Returns the actual element type associated with key type `Key` in `Seq`. [heading Header] #include #include [heading Example] typedef __map__<__pair__, __pair__, __pair__ > mymap; BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at_key__::type, char>)); [endsect] [section swap] [heading Description] Returns the return type of swap. [heading Synopsis] template struct swap { typedef void type; }; [table Parameters [[Parameters] [Requirement] [Description]] [[`Seq1`, `Seq2`][Models of __forward_sequence__][The sequences being swapped]] ] [heading Expression Semantics] result_of::swap::type [*Return type]: `void` iff both of `Seq1` and `Seq2` are sequence. Otherwise, none. [*Semantics]: Returns the return type of __swap__ for 2 sequences of types `Seq1` and `Seq2`. [heading Header] #include #include [endsect] [endsect] [endsect] [section Operator] These operators, like the __algorithms__, work generically on all Fusion sequences. All conforming Fusion sequences automatically get these operators for free. [section I/O] The I/O operators: `<<` and `>>` work generically on all Fusion sequences. The I/O operators are overloaded in namespace `boost::fusion` [footnote __sequence__(s) and __views__ residing in different namespaces will have to either provide their own I/O operators (possibly forwarding to fusion's I/O operators) or hoist fusion's I/O operators (using declaration), in their own namespaces for proper argument dependent lookup.] The `operator<<` has been overloaded for generic output streams such that __sequence__(s) are output by recursively calling `operator<<` for each element. Analogously, the global `operator>>` has been overloaded to extract __sequence__(s) from generic input streams by recursively calling `operator>>` for each element. Please note that, to display your adapted types via fusion IO system, corresponding overloaded operators should be introduced to same namespace of the type. namespace your_awesome_library { using boost::fusion::operators::operator>>; // for input using boost::fusion::operators::operator<<; // for output ... The default delimiter between the elements is space, and the __sequence__ is enclosed in parenthesis. For Example: __vector__ a(1.0f, 2, std::string("Howdy folks!"); cout << a; outputs the __vector__ as: (1.0 2 Howdy folks!) The library defines three manipulators for changing the default behavior: [variablelist Manipulators [[`tuple_open(arg)`] [Defines the character that is output before the first element.]] [[`tuple_close(arg)`] [Defines the character that is output after the last element.]] [[`tuple_delimiter(arg)`] [Defines the delimiter character between elements.]] ] The argument to `tuple_open`, `tuple_close` and `tuple_delimiter` may be a `char`, `wchar_t`, a C-string, or a wide C-string. Example: std::cout << tuple_open('[') << tuple_close(']') << tuple_delimiter(", ") << a; outputs the same __vector__, `a` as: [1.0, 2, Howdy folks!] The same manipulators work with `operator>>` and `istream` as well. Suppose the `std::cin` stream contains the following data: (1 2 3) [4:5] The code: __vector__ i; __vector__ j; std::cin >> i; std::cin >> tuple_open('[') >> tuple_close(']') >> tuple_delimiter(':'); std::cin >> j; reads the data into the __vector__(s) `i` and `j`. Note that extracting __sequence__(s) with `std::string` or C-style string elements does not generally work, since the streamed __sequence__ representation may not be unambiguously parseable. [heading Header] #include #include [section in] [heading Description] Read a __sequence__ from an input stream. [heading Synopsis] template IStream& operator>>(IStream& is, Sequence& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[is] [An input stream.] [Stream to extract information from.]] [[seq] [A __sequence__.] [The sequence to read.]] ] [heading Expression Semantics] is >> seq [*Return type]: IStream& [*Semantics]: For each element, `e`, in sequence, `seq`, call `is >> e`. [heading Header] #include #include [heading Example] __vector__ v; std::cin >> v; [endsect] [section out] [heading Description] Write a __sequence__ to an output stream. [heading Synopsis] template OStream& operator<<(OStream& os, Sequence& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[os] [An output stream.] [Stream to write information to.]] [[seq] [A __sequence__.] [The sequence to write.]] ] [heading Expression Semantics] os << seq [*Return type]: OStream& [*Semantics]: For each element, `e`, in sequence, `seq`, call `os << e`. [heading Header] #include #include [heading Example] std::cout << __make_vector__(123, "Hello", 'x') << std::endl; [endsect] [endsect] [section Comparison] The Comparison operators: `==`, `!=`, `<`, `<=`, `>=` and `>=` work generically on all Fusion sequences. Comparison operators are "short- circuited": elementary comparisons start from the first elements and are performed only until the result is clear. [heading Header] #include #include [section equal] [heading Description] Compare two sequences for equality. [heading Synopsis] template bool operator==(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a == b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a == b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `e1 == e2` returns true. For any 2 zero length __sequence__(s), e and f, e == f returns true. [heading Header] #include #include [heading Example] __vector__ v1(5, 'a'); __vector__ v2(5, 'a'); assert(v1 == v2); [endsect] [section not equal] Compare two sequences for inequality. [heading Synopsis] template bool operator!=(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a != b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a == b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: Returns !(a == b). [heading Header] #include #include [heading Example] __vector__ v3(5, 'b'); __vector__ t4(2, 'a'); assert(v1 != v3); assert(v1 != t4); assert(!(v1 != v2)); [endsect] [section less than] Lexicographically compare two sequences. [heading Synopsis] template bool operator<(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a < b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a < b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: Returns the lexicographical comparison of between `a` and `b`. [heading Header] #include #include [heading Example] __vector__ v1(4, 3.3f); __vector__ v2(5, 3.3f); __vector__ v3(5, 4.4); assert(v1 < v2); assert(v2 < v3); [endsect] [section less than equal] Lexicographically compare two sequences. [heading Synopsis] template bool operator<=(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a <= b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a < b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: Returns !(b < a). [heading Header] #include #include [heading Example] __vector__ v1(4, 3.3f); __vector__ v2(5, 3.3f); __vector__ v3(5, 4.4); assert(v1 <= v2); assert(v2 <= v3); [endsect] [section greater than] Lexicographically compare two sequences. [heading Synopsis] template bool operator>(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a > b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a < b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: Returns b < a. [heading Header] #include #include [heading Example] __vector__ v1(4, 3.3f); __vector__ v2(5, 3.3f); __vector__ v3(5, 4.4); assert(v2 > v1); assert(v3 > v2); [endsect] [section greater than equal] Lexicographically compare two sequences. [heading Synopsis] template bool operator>=(Seq1 const& a, Seq2 const& b); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] ] [heading Expression Semantics] a >= b [*Return type]: `bool` [*Requirements]: For each element, `e1`, in sequence `a`, and for each element, `e2`, in sequence `b`, `a < b` is a valid expression returning a type that is convertible to bool. An attempt to compare two Sequences of different lengths results in a compile time error. [*Semantics]: Returns !(a < b). [heading Header] #include #include [heading Example] __vector__ v1(4, 3.3f); __vector__ v2(5, 3.3f); __vector__ v3(5, 4.4); assert(v2 >= v1); assert(v3 >= v2); [endsect] [endsect] [section Hashing] Automatically create a `boost::hash` conforming `hash_value` function. [heading Synopsis] template std::size_t hash_value(Seq const& seq); [heading Parameters] [table [[Parameter] [Requirement] [Description]] [[`seq`] [Instance of __sequence__] [__sequence__ to compute hash value of]] ] [*Return type]: `std::size_t` [*Requirements]: For each element `e` in sequence `seq`, `hash_value(seq)` is a valid expression returning a type that is convertible to `std::size_t`. [*Semantics]: Returns a combined hash value for all elements of `seq`. [heading Header] #include #include [heading Example] #include #include #include #include void foo() { typedef boost::fusion::vector Vec; const Vec v = {42, "Hello World", 't'}; // Compute a hash value directly. std::cout << "hash_value(v) = " << boost::fusion::hash_value(v) << '\n'; // Or use it to create an unordered_map. boost::unordered_map map; map[v] = true; assert(map.size() == 1 && map.count(v) == 1); } [heading Example] #include #include #include #include // We would like to define a struct that we can form unordered_sets of. BOOST_FUSION_DEFINE_STRUCT( (demo), Key, (bool, b) (std::string, s) (int, i) ) namespace demo { // Make operator== and hash_value ADL accessible. using boost::fusion::operator==; using boost::fusion::hash_value; typedef boost::unordered_set Set; } void foo() { demo::Set set; demo::Key key; assert(set.count(key) == 0); } [heading See also] __boost_func_hash__ [endsect] [endsect] [endsect]