sequence.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

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.

The default delimiter between the elements is space, and the __sequence__
is enclosed in parenthesis. For Example:

    __vector__<float, int, std::string> 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__<int, int, int> i;
    __vector__<int, int> j;

    std::cin >> i;
    std::cin >> set_open('[') >> set_close(']') >> set_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 <boost/fusion/sequence/io.hpp>
    #include <boost/fusion/include/io.hpp>

[section in]

[heading Description]

Read a __sequence__ from an input stream.

[heading Synopsis]

    template <typename IStream, typename Sequence>
    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 <boost/fusion/sequence/io/in.hpp>
    #include <boost/fusion/include/in.hpp>

[heading Example]

    __vector__<int, std::string, char> v;
    std::cin >> v;

[endsect]

[section out]

[heading Description]

Write a __sequence__ to an output stream.

[heading Synopsis]

    template <typename OStream, typename Sequence>
    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 <boost/fusion/sequence/io/out.hpp>
    #include <boost/fusion/include/out.hpp>

[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 <boost/fusion/sequence/comparison.hpp>
    #include <boost/fusion/include/comparison.hpp>

[section equal]

[heading Description]

Compare two sequences for equality.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/equal_to.hpp>
    #include <boost/fusion/include/equal_to.hpp>

[heading Example]

    __vector__<int, char> v1(5, 'a');
    __vector__<int, char> v2(5, 'a');
    assert(v1 == v2);

[endsect]

[section not equal]

Compare two sequences for inequality.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/not_equal_to.hpp>
    #include <boost/fusion/include/not_equal_to.hpp>

[heading Example]

    __vector__<int, char> v3(5, 'b');
    __vector__<int, char> t4(2, 'a');
    assert(v1 != v3);
    assert(v1 != t4);
    assert(!(v1 != v2));

[endsect]

[section less than]

Lexicographically compare two sequences.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/less.hpp>
    #include <boost/fusion/include/less.hpp>

[heading Example]

    __vector__<int, float> v1(4, 3.3f);
    __vector__<short, float> v2(5, 3.3f);
    __vector__<long, double> v3(5, 4.4);
    assert(v1 < v2);
    assert(v2 < v3);

[endsect]

[section less than equal]

Lexicographically compare two sequences.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/less_equal.hpp>
    #include <boost/fusion/include/less_equal.hpp>

[heading Example]

    __vector__<int, float> v1(4, 3.3f);
    __vector__<short, float> v2(5, 3.3f);
    __vector__<long, double> v3(5, 4.4);
    assert(v1 <= v2);
    assert(v2 <= v3);

[endsect]

[section greater than]

Lexicographically compare two sequences.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/less_equal.hpp>
    #include <boost/fusion/include/less_equal.hpp>

[heading Example]

    __vector__<int, float> v1(4, 3.3f);
    __vector__<short, float> v2(5, 3.3f);
    __vector__<long, double> v3(5, 4.4);
    assert(v2 > v1);
    assert(v3 > v2);

[endsect]

[section greater than equal]

Lexicographically compare two sequences.

[heading Synopsis]

    template <typename Seq1, typename Seq2>
    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 <boost/fusion/sequence/comparison/greater_equal.hpp>
    #include <boost/fusion/include/greater_equal.hpp>

[heading Example]

    __vector__<int, float> v1(4, 3.3f);
    __vector__<short, float> v2(5, 3.3f);
    __vector__<long, double> v3(5, 4.4);
    assert(v2 >= v1);
    assert(v3 >= v2);

[endsect]

[endsect]

[endsect]

[endsect]