1 [/==============================================================================
2 Copyright (C) 2001-2011 Joel de Guzman
3 Copyright (C) 2006 Dan Marsden
5 Use, modification and distribution is subject to the Boost Software
6 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7 http://www.boost.org/LICENSE_1_0.txt)
8 ===============================================================================/]
11 Views are sequences that do not actually contain data, but instead impart
12 an alternative presentation over the data from one or more underlying
13 sequences. Views are proxies. They provide an efficient yet purely
14 functional way to work on potentially expensive sequence operations. Views
15 are inherently lazy. Their elements are only computed on demand only when
16 the elements of the underlying sequence(s) are actually accessed. Views'
17 lazy nature make them very cheap to copy and be passed around by value.
21 #include <boost/fusion/view.hpp>
22 #include <boost/fusion/include/view.hpp>
26 `single_view` is a view into a value as a single element sequence.
30 #include <boost/fusion/view/single_view.hpp>
31 #include <boost/fusion/include/single_view.hpp>
38 [heading Template parameters]
41 [[Parameter] [Description] [Default]]
47 * __random_access_sequence__
49 [variablelist Notation
50 [[`S`] [A `single_view` type]]
51 [[`s`, `s2`] [Instances of `single_view`]]
52 [[`x`] [An instance of `T`]]
55 [heading Expression Semantics]
57 Semantics of an expression is defined only where it differs from, or is not
58 defined in __random_access_sequence__.
61 [[Expression] [Semantics]]
62 [[`S(x)`] [Creates a `single_view` from `x`.]]
63 [[`S(s)`] [Copy constructs a `single_view` from another `single_view`, `s`.]]
64 [[`s = s2`] [Assigns to a `single_view`, `s`, from another `single_view`, `s2`.]]
69 single_view<int> view(3);
70 std::cout << view << std::endl;
78 `filter_view` is a view into a subset of its underlying sequence's elements
79 satisfying a given predicate (an __mpl__ metafunction). The `filter_view`
80 presents only those elements for which its predicate evaluates to
85 #include <boost/fusion/view/filter_view.hpp>
86 #include <boost/fusion/include/filter_view.hpp>
90 template <typename Sequence, typename Pred>
93 [heading Template parameters]
96 [[Parameter] [Description] [Default]]
97 [[`Sequence`] [A __forward_sequence__] []]
98 [[`Pred`] [Unary Metafunction
99 returning an `mpl::bool_`] []]
104 * __forward_sequence__
105 * __associative_sequence__ if `Sequence` implements the __associative_sequence__ model.
107 [variablelist Notation
108 [[`F`] [A `filter_view` type]]
109 [[`f`, `f2`] [Instances of `filter_view`]]
110 [[`s`] [A __forward_sequence__]]
113 [heading Expression Semantics]
115 Semantics of an expression is defined only where it differs from, or is not
116 defined in the implemented models.
119 [[Expression] [Semantics]]
120 [[`F(s)`] [Creates a `filter_view` given a sequence, `s`.]]
121 [[`F(f)`] [Copy constructs a `filter_view` from another `filter_view`, `f`.]]
122 [[`f = f2`] [Assigns to a `filter_view`, `f`, from another `filter_view`, `f2`.]]
128 using boost::mpl::not_;
129 using boost::is_class;
131 typedef __vector__<std::string, char, long, bool, double> vector_type;
133 vector_type v("a-string", '@', 987654, true, 6.6);
134 filter_view<vector_type const, not_<is_class<_> > > view(v);
135 std::cout << view << std::endl;
139 [section iterator_range]
141 [heading Description]
143 `iterator_range` presents a sub-range of its underlying sequence delimited
144 by a pair of iterators.
148 #include <boost/fusion/view/iterator_range.hpp>
149 #include <boost/fusion/include/iterator_range.hpp>
153 template <typename First, typename Last>
154 struct iterator_range;
156 [heading Template parameters]
159 [[Parameter] [Description] [Default]]
160 [[`First`] [A fusion __iterator__] []]
161 [[`Last`] [A fusion __iterator__] []]
166 * __forward_sequence__, __bidirectional_sequence__ or
167 __random_access_sequence__ depending on the traversal characteristics (see
168 __traversal_concept__) of its underlying sequence.
169 * __associative_sequence__ if `First` and `Last` implement the __associative_iterator__ model.
171 [variablelist Notation
172 [[`IR`] [An `iterator_range` type]]
173 [[`f`] [An instance of `First`]]
174 [[`l`] [An instance of `Last`]]
175 [[`ir`, `ir2`] [Instances of `iterator_range`]]
178 [heading Expression Semantics]
180 Semantics of an expression is defined only where it differs from, or is not
181 defined in the implemented models.
184 [[Expression] [Semantics]]
185 [[`IR(f, l)`] [Creates an `iterator_range` given iterators, `f` and `l`.]]
186 [[`IR(ir)`] [Copy constructs an `iterator_range` from another `iterator_range`, `ir`.]]
187 [[`ir = ir2`] [Assigns to a `iterator_range`, `ir`, from another `iterator_range`, `ir2`.]]
192 char const* s = "Ruby";
193 typedef __vector__<int, char, double, char const*> vector_type;
194 vector_type vec(1, 'x', 3.3, s);
196 typedef __result_of_begin__<vector_type>::type A;
197 typedef __result_of_end__<vector_type>::type B;
198 typedef __result_of_next__<A>::type C;
199 typedef __result_of_prior__<B>::type D;
204 iterator_range<C, D> range(c, d);
205 std::cout << range << std::endl;
211 [heading Description]
213 `joint_view` presents a view which is a concatenation of two sequences.
217 #include <boost/fusion/view/joint_view.hpp>
218 #include <boost/fusion/include/joint_view.hpp>
222 template <typename Sequence1, typename Sequence2>
225 [heading Template parameters]
228 [[Parameter] [Description] [Default]]
229 [[`Sequence1`] [A __forward_sequence__] []]
230 [[`Sequence2`] [A __forward_sequence__] []]
235 * __forward_sequence__
236 * __associative_sequence__ if `Sequence1` and `Sequence2` implement the __associative_sequence__ model.
238 [variablelist Notation
239 [[`JV`] [A `joint_view` type]]
240 [[`s1`] [An instance of `Sequence1`]]
241 [[`s2`] [An instance of `Sequence2`]]
242 [[`jv`, `jv2`] [Instances of `joint_view`]]
245 [heading Expression Semantics]
247 Semantics of an expression is defined only where it differs from, or is not
248 defined in the implemented models.
251 [[Expression] [Semantics]]
252 [[`JV(s1, s2)`] [Creates a `joint_view` given sequences, `s1` and `s2`.]]
253 [[`JV(jv)`] [Copy constructs a `joint_view` from another `joint_view`, `jv`.]]
254 [[`jv = jv2`] [Assigns to a `joint_view`, `jv`, from another `joint_view`, `jv2`.]]
259 __vector__<int, char> v1(3, 'x');
260 __vector__<std::string, int> v2("hello", 123);
262 __vector__<int, char>
263 , __vector__<std::string, int>
265 std::cout << view << std::endl;
271 [heading Description]
273 `zip_view` presents a view which iterates over a collection of __sequence__(s) in parallel. A `zip_view`
274 is constructed from a __sequence__ of references to the component __sequence__s.
278 #include <boost/fusion/view/zip_view.hpp>
279 #include <boost/fusion/include/zip_view.hpp>
283 template <typename Sequences>
286 [heading Template parameters]
289 [[Parameter] [Description] [Default]]
290 [[`Sequences`] [A __forward_sequence__ of references to other Fusion __sequence__s] []]
295 * __forward_sequence__, __bidirectional_sequence__ or
296 __random_access_sequence__ depending on the traversal characteristics (see
297 __traversal_concept__) of its underlying sequence.
299 [variablelist Notation
300 [[`ZV`] [A `zip_view` type]]
301 [[`s`] [An instance of `Sequences`]]
302 [[`zv1`, `zv2`] [Instances of `ZV`]]
305 [heading Expression Semantics]
307 Semantics of an expression is defined only where it differs from, or is not
308 defined in __forward_sequence__.
311 [[Expression] [Semantics]]
312 [[`ZV(s)`] [Creates a `zip_view` given a sequence of references to the component __sequence__s.]]
313 [[`ZV(zv1)`] [Copy constructs a `zip_view` from another `zip_view`, `zv`.]]
314 [[`zv1 = zv2`] [Assigns to a `zip_view`, `zv`, from another `zip_view`, `zv2`.]]
318 typedef __vector__<int,int> vec1;
319 typedef __vector__<char,char> vec2;
322 typedef __vector__<vec1&, vec2&> sequences;
323 std::cout << zip_view<sequences>(sequences(v1, v2)) << std::endl; // ((1 a) (2 b))
327 [section transform_view]
329 The unary version of `transform_view` presents a view of its underlying
330 sequence given a unary function object or function pointer. The binary
331 version of `transform_view` presents a view of 2 underlying sequences,
332 given a binary function object or function pointer. The `transform_view`
333 inherits the traversal characteristics (see __traversal_concept__) of
334 its underlying sequence or sequences.
338 #include <boost/fusion/view/transform_view.hpp>
339 #include <boost/fusion/include/transform_view.hpp>
345 template <typename Sequence, typename F1>
346 struct transform_view;
350 template <typename Sequence1, typename Sequence2, typename F2>
351 struct transform_view;
353 [heading Template parameters]
356 [[Parameter] [Description] [Default]]
357 [[`Sequence`] [A __forward_sequence__] []]
358 [[`Sequence1`] [A __forward_sequence__] []]
359 [[`Sequence2`] [A __forward_sequence__] []]
360 [[`F1`] [A unary function object or function pointer. `__boost_result_of_call__<F1(E)>::type` is the return type of an instance of `F1` when called with a value of each element type `E` in the input sequence.] []]
361 [[`F2`] [A binary function object or function pointer. `__boost_result_of_call__<F2(E1, E2)>::type` is the return type of an instance of `F2` when called with a value of each corresponding pair of element type `E1` and `E2` in the input sequences.] []]
366 * __forward_sequence__, __bidirectional_sequence__ or
367 __random_access_sequence__ depending on the traversal characteristics (see
368 __traversal_concept__) of its underlying sequence.
370 [variablelist Notation
371 [[`TV`] [A `transform_view` type]]
372 [[`BTV`] [A binary `transform_view` type]]
373 [[`UTV`] [A unary `transform_view` type]]
374 [[`f1`] [An instance of `F1`]]
375 [[`f2`] [An instance of `F2`]]
376 [[`s`] [An instance of `Sequence`]]
377 [[`s1`] [An instance of `Sequence1`]]
378 [[`s2`] [An instance of `Sequence2`]]
379 [[`tv`, `tv2`] [Instances of `transform_view`]]
382 [heading Expression Semantics]
384 Semantics of an expression is defined only where it differs from, or is not
385 defined in __forward_sequence__, __bidirectional_sequence__ or
386 __random_access_sequence__ depending on the traversal characteristics (see
387 __traversal_concept__) of its underlying sequence or sequences.
390 [[Expression] [Semantics]]
391 [[`UTV(s, f1)`] [Creates a unary `transform_view` given sequence,
392 `s` and unary function object or function pointer, `f1`.]]
393 [[`BTV(s1, s2, f2)`] [Creates a binary `transform_view` given sequences, `s1` and `s2`
394 and binary function object or function pointer, `f2`.]]
395 [[`TV(tv)`] [Copy constructs a `transform_view` from another `transform_view`, `tv`.]]
396 [[`tv = tv2`] [Assigns to a `transform_view`, `tv`, from another `transform_view`, `tv2`.]]
403 template<typename Sig>
407 struct result<square(U)>
408 : remove_reference<U>
411 template <typename T>
412 T operator()(T x) const
418 typedef __vector__<int, short, double> vector_type;
419 vector_type vec(2, 5, 3.3);
421 transform_view<vector_type, square> transform(vec, square());
422 std::cout << transform << std::endl;
426 [section reverse_view]
428 `reverse_view` presents a reversed view of underlying sequence. The first
429 element will be its last and the last element will be its first.
433 #include <boost/fusion/view/reverse_view.hpp>
434 #include <boost/fusion/include/reverse_view.hpp>
438 template <typename Sequence>
441 [heading Template parameters]
444 [[Parameter] [Description] [Default]]
445 [[`Sequence`] [A __bidirectional_sequence__] []]
450 * A model of __bidirectional_sequence__ if `Sequence` is a __bidirectional_sequence__
451 else, __random_access_sequence__ if `Sequence` is a __random_access_sequence__.
452 * __associative_sequence__ if `Sequence` implements the __associative_sequence__ model.
454 [variablelist Notation
455 [[`RV`] [A `reverse_view` type]]
456 [[`s`] [An instance of `Sequence`]]
457 [[`rv`, `rv2`] [Instances of `reverse_view`]]
460 [heading Expression Semantics]
462 Semantics of an expression is defined only where it differs from, or is not
463 defined in the implemented models.
466 [[Expression] [Semantics]]
467 [[`RV(s)`] [Creates a unary `reverse_view` given sequence, `s`.]]
468 [[`RV(rv)`] [Copy constructs a `reverse_view` from another `reverse_view`, `rv`.]]
469 [[`rv = rv2`] [Assigns to a `reverse_view`, `rv`, from another `reverse_view`, `rv2`.]]
474 typedef __vector__<int, short, double> vector_type;
475 vector_type vec(2, 5, 3.3);
477 reverse_view<vector_type> reverse(vec);
478 std::cout << reverse << std::endl;
484 [heading Description]
486 `nview` presents a view which iterates over a given __sequence__ in a specified order.
487 An `nview` is constructed from an arbitrary __sequence__ and a list of indices specifying
488 the elements to iterate over.
492 #include <boost/fusion/view/nview.hpp>
493 #include <boost/fusion/include/nview.hpp>
497 template <typename Sequence, typename Indices>
500 template <typename Sequence, int I1, int I2 = -1, ...>
501 typename result_of::nview<Sequence, I1, I2, ...>::type
502 as_nview(Sequence& s);
504 [heading Template parameters]
507 [[Parameter] [Description] [Default]]
508 [[`Sequence`] [An arbitrary Fusion __forward_sequence__]
510 [[`Indices`] [A `mpl::vector_c<int, ...>` holding the indices defining
511 the required iteration order.] []]
512 [[`I1`, `I2`, `I3`...] [A list of integers specifying the required
513 iteration order.] [`INT_MAX` for `I2`, `I3`...]]
518 * __random_access_sequence__ (see __traversal_concept__)
520 [variablelist Notation
521 [[`NV`] [A `nview` type]]
522 [[`s`] [An instance of `Sequences`]]
523 [[`nv1`, `nv2`] [Instances of `NV`]]
526 [heading Expression Semantics]
528 Semantics of an expression is defined only where it differs from, or is not
529 defined in __random_access_sequence__.
532 [[Expression] [Semantics]]
533 [[`NV(s)`] [Creates an `nview` given a sequence and a list of indices.]]
534 [[`NV(nv1)`] [Copy constructs an `nview` from another `nview`, `nv1`.]]
535 [[`nv1 = nv2`] [Assigns to an `nview`, `nv1`, from another `nview`, `nv2`.]]
538 The `nview` internally stores a Fusion __vector__ of references to the elements
539 of the original Fusion __sequence__
542 typedef __vector__<int, char, double> vec;
543 typedef mpl::vector_c<int, 2, 1, 0, 2, 0> indices;
547 std::cout << nview<vec, indices>(v1) << std::endl; // (2.0 c 1 2.0 1)
548 std::cout << as_nview<2, 1, 1, 0>(v1) << std::endl; // (2.0 c c 1)
552 [section repetitive_view]
554 [heading Description]
556 `repetitive_view` presents a view which iterates over a given
557 __sequence__ repeatedly. Because a `repetitive_view`
558 has infinite length, it can only be used when some external
559 condition determines the end. Thus, initializing a fixed
560 length sequence with a `repetitive_view` is okay, but
561 printing a `repetitive_view` to `std::cout` is not.
565 #include <boost/fusion/view/repetitive_view.hpp>
566 #include <boost/fusion/include/repetitive_view.hpp>
570 template <typename Sequence>
571 struct repetitive_view;
573 [heading Template parameters]
576 [[Parameter] [Description] [Default]]
577 [[`Sequence`] [An arbitrary Fusion __forward_sequence__]
581 [variablelist Notation
582 [[`RV`] [A `repetitive_view` type]]
583 [[`s`] [An instance of `Sequences`]]
584 [[`rv`, `rv1`, `rv2`] [Instances of `RV`]]
587 [heading Expression Semantics]
590 [[Expression] [Return Type] [Semantics]]
591 [[`RV(s)`] [] [Creates an `repetitive_view` given the underlying sequence.]]
592 [[`RV(rv1)`] [] [Copy constructs an `repetitive_view` from another `repetitive_view`, `rv1`.]]
593 [[`rv1 = rv2`] [] [Assigns to a `repetitive_view`, `rv1`, from another `repetitive_view`, `rv2`.]]
594 [[`__begin__(rv)`] [__forward_iterator__] []]
595 [[`__end__(rv)`] [__forward_iterator__] [Creates an unreachable iterator (since the sequence is infinite)]]
598 [heading Result Type Expressions]
602 [[`__result_of_begin__<RV>::type`]]
603 [[`__result_of_end__<RV>::type`]]
607 typedef __vector__<int, char, double> vec1;
608 typedef __vector__<int, char, double, int, char> vec2;
610 vec1 v1(1, 'c', 2.0);
611 vec2 v2(repetitive_view<vec1>(v1));
613 std::cout << v2 << std::endl; // 1, 'c', 2.0, 1, 'c'
617 [section flatten_view]
619 [heading Description]
621 `flatten_view` presents a view which iterates over its elements recursively in depth-first order.
625 #include <boost/fusion/view/flatten_view.hpp>
626 #include <boost/fusion/include/flatten_view.hpp>
630 template <typename Sequence>
633 [heading Template parameters]
636 [[Parameter] [Description] [Default]]
637 [[`Sequence`] [A __forward_sequence__] []]
642 * __forward_sequence__
644 [variablelist Notation
645 [[`F`] [A `flatten_view` type]]
646 [[`s`] [An instance of `Sequence`]]
647 [[`f`, `f2`] [Instances of `F`]]
650 [heading Expression Semantics]
652 Semantics of an expression is defined only where it differs from, or is not
653 defined in __forward_sequence__.
656 [[Expression] [Semantics]]
657 [[`F(s)`] [Creates a `flatten_view` given sequence, `s`.]]
658 [[`F(f)`] [Copy constructs a `flatten_view` from another `flatten_view`, `f`.]]
659 [[`f = f2`] [Assigns to a `flatten_view`, `f`, from another `flatten_view`, `f2`.]]
663 typedef __vector__<int, int, __vector__<int, int>, int> sequence_type;
665 __flatten_view__<sequence_type> flattened(seq);
666 __copy__(__make_vector__(1, 2, 3, 4, 5), flattened);
667 assert(seq == __make_vector__(1, 2, __make_vector__(3, 4), 5));