libs/fusion/doc/view.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2006 Dan Marsden
   4
   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 ===============================================================================/]
   9 [section View]
  10
  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.
  18
  19 [heading Header]
  20
  21     #include <boost/fusion/view.hpp>
  22     #include <boost/fusion/include/view.hpp>
  23
  24 [section single_view]
  25
  26 `single_view` is a view into a value as a single element sequence.
  27
  28 [heading Header]
  29
  30     #include <boost/fusion/view/single_view.hpp>
  31     #include <boost/fusion/include/single_view.hpp>
  32
  33 [heading Synopsis]
  34
  35     template <typename T>
  36     struct single_view;
  37
  38 [heading Template parameters]
  39
  40 [table
  41     [[Parameter]            [Description]               [Default]]
  42     [[`T`]                  [Any type]                  []]
  43 ]
  44
  45 [heading Model of]
  46
  47 * __random_access_sequence__
  48
  49 [variablelist Notation
  50     [[`S`]              [A `single_view` type]]
  51     [[`s`, `s2`]        [Instances of `single_view`]]
  52     [[`x`]              [An instance of `T`]]
  53 ]
  54
  55 [heading Expression Semantics]
  56
  57 Semantics of an expression is defined only where it differs from, or is not
  58 defined in __random_access_sequence__.
  59
  60 [table
  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`.]]
  65 ]
  66
  67 [heading Example]
  68
  69     single_view<int> view(3);
  70     std::cout << view << std::endl;
  71
  72 [endsect]
  73
  74 [section filter_view]
  75
  76 [heading Description]
  77
  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
  81 `mpl::true_`.
  82
  83 [heading Header]
  84
  85     #include <boost/fusion/view/filter_view.hpp>
  86     #include <boost/fusion/include/filter_view.hpp>
  87
  88 [heading Synopsis]
  89
  90     template <typename Sequence, typename Pred>
  91     struct filter_view;
  92
  93 [heading Template parameters]
  94
  95 [table
  96     [[Parameter]            [Description]               [Default]]
  97     [[`Sequence`]           [A __forward_sequence__]    []]
  98     [[`Pred`]               [Unary Metafunction
  99                              returning an `mpl::bool_`] []]
 100 ]
 101
 102 [heading Model of]
 103
 104 * __forward_sequence__
 105 * __associative_sequence__ if `Sequence` implements the __associative_sequence__ model.
 106
 107 [variablelist Notation
 108     [[`F`]              [A `filter_view` type]]
 109     [[`f`, `f2`]        [Instances of `filter_view`]]
 110     [[`s`]              [A __forward_sequence__]]
 111 ]
 112
 113 [heading Expression Semantics]
 114
 115 Semantics of an expression is defined only where it differs from, or is not
 116 defined in the implemented models.
 117
 118 [table
 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`.]]
 123 ]
 124
 125 [heading Example]
 126
 127     using boost::mpl::_;
 128     using boost::mpl::not_;
 129     using boost::is_class;
 130
 131     typedef __vector__<std::string, char, long, bool, double> vector_type;
 132
 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;
 136
 137 [endsect]
 138
 139 [section iterator_range]
 140
 141 [heading Description]
 142
 143 `iterator_range` presents a sub-range of its underlying sequence delimited
 144 by a pair of iterators.
 145
 146 [heading Header]
 147
 148     #include <boost/fusion/view/iterator_range.hpp>
 149     #include <boost/fusion/include/iterator_range.hpp>
 150
 151 [heading Synopsis]
 152
 153     template <typename First, typename Last>
 154     struct iterator_range;
 155
 156 [heading Template parameters]
 157
 158 [table
 159     [[Parameter]            [Description]               [Default]]
 160     [[`First`]              [A fusion __iterator__]     []]
 161     [[`Last`]               [A fusion __iterator__]     []]
 162 ]
 163
 164 [heading Model of]
 165
 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.
 170
 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`]]
 176 ]
 177
 178 [heading Expression Semantics]
 179
 180 Semantics of an expression is defined only where it differs from, or is not
 181 defined in the implemented models.
 182
 183 [table
 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`.]]
 188 ]
 189
 190 [heading Example]
 191
 192     char const* s = "Ruby";
 193     typedef __vector__<int, char, double, char const*> vector_type;
 194     vector_type vec(1, 'x', 3.3, s);
 195
 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;
 200
 201     C c(vec);
 202     D d(vec);
 203
 204     iterator_range<C, D> range(c, d);
 205     std::cout << range << std::endl;
 206
 207 [endsect]
 208
 209 [section joint_view]
 210
 211 [heading Description]
 212
 213 `joint_view` presents a view which is a concatenation of two sequences.
 214
 215 [heading Header]
 216
 217     #include <boost/fusion/view/joint_view.hpp>
 218     #include <boost/fusion/include/joint_view.hpp>
 219
 220 [heading Synopsis]
 221
 222     template <typename Sequence1, typename Sequence2>
 223     struct joint_view;
 224
 225 [heading Template parameters]
 226
 227 [table
 228     [[Parameter]            [Description]                   [Default]]
 229     [[`Sequence1`]          [A __forward_sequence__]        []]
 230     [[`Sequence2`]          [A __forward_sequence__]        []]
 231 ]
 232
 233 [heading Model of]
 234
 235 * __forward_sequence__
 236 * __associative_sequence__ if `Sequence1` and `Sequence2` implement the __associative_sequence__ model.
 237
 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`]]
 243 ]
 244
 245 [heading Expression Semantics]
 246
 247 Semantics of an expression is defined only where it differs from, or is not
 248 defined in the implemented models.
 249
 250 [table
 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`.]]
 255 ]
 256
 257 [heading Example]
 258
 259     __vector__<int, char> v1(3, 'x');
 260     __vector__<std::string, int> v2("hello", 123);
 261     joint_view<
 262         __vector__<int, char>
 263       , __vector__<std::string, int>
 264     > view(v1, v2);
 265     std::cout << view << std::endl;
 266
 267 [endsect]
 268
 269 [section zip_view]
 270
 271 [heading Description]
 272
 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.
 275
 276 [heading Header]
 277
 278     #include <boost/fusion/view/zip_view.hpp>
 279     #include <boost/fusion/include/zip_view.hpp>
 280
 281 [heading Synopsis]
 282
 283     template <typename Sequences>
 284     struct zip_view;
 285
 286 [heading Template parameters]
 287
 288 [table
 289     [[Parameter]            [Description]                   [Default]]
 290     [[`Sequences`]          [A __forward_sequence__ of references to other Fusion __sequence__s]        []]
 291 ]
 292
 293 [heading Model of]
 294
 295 * __forward_sequence__, __bidirectional_sequence__ or
 296 __random_access_sequence__ depending on the traversal characteristics (see
 297 __traversal_concept__) of its underlying sequence.
 298
 299 [variablelist Notation
 300     [[`ZV`]             [A `zip_view` type]]
 301     [[`s`]             [An instance of `Sequences`]]
 302     [[`zv1`, `zv2`]             [Instances of `ZV`]]
 303 ]
 304
 305 [heading Expression Semantics]
 306
 307 Semantics of an expression is defined only where it differs from, or is not
 308 defined in __forward_sequence__.
 309
 310 [table
 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`.]]
 315 ]
 316
 317 [heading Example]
 318     typedef __vector__<int,int> vec1;
 319     typedef __vector__<char,char> vec2;
 320     vec1 v1(1,2);
 321     vec2 v2('a','b');
 322     typedef __vector__<vec1&, vec2&> sequences;
 323     std::cout << zip_view<sequences>(sequences(v1, v2)) << std::endl; // ((1 a) (2 b))
 324
 325 [endsect]
 326
 327 [section transform_view]
 328
 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.
 335
 336 [heading Header]
 337
 338     #include <boost/fusion/view/transform_view.hpp>
 339     #include <boost/fusion/include/transform_view.hpp>
 340
 341 [heading Synopsis]
 342
 343 [*Unary Version]
 344
 345     template <typename Sequence, typename F1>
 346     struct transform_view;
 347
 348 [*Binary Version]
 349
 350     template <typename Sequence1, typename Sequence2, typename F2>
 351     struct transform_view;
 352
 353 [heading Template parameters]
 354
 355 [table
 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.]                   []]
 362 ]
 363
 364 [heading Model of]
 365
 366 * __forward_sequence__, __bidirectional_sequence__ or
 367 __random_access_sequence__ depending on the traversal characteristics (see
 368 __traversal_concept__) of its underlying sequence.
 369
 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`]]
 380 ]
 381
 382 [heading Expression Semantics]
 383
 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.
 388
 389 [table
 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`.]]
 397 ]
 398
 399 [heading Example]
 400
 401     struct square
 402     {
 403         template<typename Sig>
 404         struct result;
 405
 406         template<typename U>
 407         struct result<square(U)>
 408         : remove_reference<U>
 409         {};
 410
 411         template <typename T>
 412         T operator()(T x) const
 413         {
 414             return x * x;
 415         }
 416     };
 417
 418     typedef __vector__<int, short, double> vector_type;
 419     vector_type vec(2, 5, 3.3);
 420
 421     transform_view<vector_type, square> transform(vec, square());
 422     std::cout << transform << std::endl;
 423
 424 [endsect]
 425
 426 [section reverse_view]
 427
 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.
 430
 431 [heading Header]
 432
 433     #include <boost/fusion/view/reverse_view.hpp>
 434     #include <boost/fusion/include/reverse_view.hpp>
 435
 436 [heading Synopsis]
 437
 438     template <typename Sequence>
 439     struct reverse_view;
 440
 441 [heading Template parameters]
 442
 443 [table
 444     [[Parameter]            [Description]                           [Default]]
 445     [[`Sequence`]           [A __bidirectional_sequence__]          []]
 446 ]
 447
 448 [heading Model of]
 449
 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.
 453
 454 [variablelist Notation
 455     [[`RV`]             [A `reverse_view` type]]
 456     [[`s`]              [An instance of `Sequence`]]
 457     [[`rv`, `rv2`]      [Instances of `reverse_view`]]
 458 ]
 459
 460 [heading Expression Semantics]
 461
 462 Semantics of an expression is defined only where it differs from, or is not
 463 defined in the implemented models.
 464
 465 [table
 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`.]]
 470 ]
 471
 472 [heading Example]
 473
 474     typedef __vector__<int, short, double> vector_type;
 475     vector_type vec(2, 5, 3.3);
 476
 477     reverse_view<vector_type> reverse(vec);
 478     std::cout << reverse << std::endl;
 479
 480 [endsect]
 481
 482 [section nview]
 483
 484 [heading Description]
 485
 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 indicies specifying
 488 the elements to iterate over.
 489
 490 [heading Header]
 491
 492     #include <boost/fusion/view/nview.hpp>
 493     #include <boost/fusion/include/nview.hpp>
 494
 495 [heading Synopsis]
 496
 497     template <typename Sequence, typename Indicies>
 498     struct nview;
 499
 500     template <typename Sequence, int I1, int I2 = -1, ...>
 501     typename result_of::nview<Sequence, I1, I2, ...>::type
 502     as_nview(Sequence& s);
 503
 504 [heading Template parameters]
 505
 506 [table
 507     [[Parameter]            [Description]                   [Default]]
 508     [[`Sequence`]           [An arbitrary Fusion __forward_sequence__]
 509                                                             []]
 510     [[`Indicies`]           [A `mpl::vector_c<int, ...>` holding the indicies 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`...]]
 514 ]
 515
 516 [heading Model of]
 517
 518 * __random_access_sequence__ (see __traversal_concept__)
 519
 520 [variablelist Notation
 521     [[`NV`]            [A `nview` type]]
 522     [[`s`]             [An instance of `Sequences`]]
 523     [[`nv1`, `nv2`]    [Instances of `NV`]]
 524 ]
 525
 526 [heading Expression Semantics]
 527
 528 Semantics of an expression is defined only where it differs from, or is not
 529 defined in __random_access_sequence__.
 530
 531 [table
 532     [[Expression]           [Semantics]]
 533     [[`NV(s)`]              [Creates an `nview` given a sequence and a list of indicies.]]
 534     [[`NV(nv1)`]            [Copy constructs an `nview` from another `nview`, `nv1`.]]
 535     [[`nv1 = nv2`]          [Assigns to an `nview`, `nv1`, from another `nview`, `nv2`.]]
 536 ]
 537
 538 The `nview` internally stores a Fusion __vector__ of references to the elements
 539 of the original Fusion __sequence__
 540
 541 [heading Example]
 542     typedef __vector__<int, char, double> vec;
 543     typedef mpl::vector_c<int, 2, 1, 0, 2, 0> indicies;
 544
 545     vec v1(1, 'c', 2.0);
 546
 547     std::cout << nview<vec, indicies>(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)
 549
 550 [endsect]
 551
 552 [section repetitive_view]
 553
 554 [heading Description]
 555
 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.
 562
 563 [heading Header]
 564
 565     #include <boost/fusion/view/repetitive_view.hpp>
 566     #include <boost/fusion/include/repetitive_view.hpp>
 567
 568 [heading Synopsis]
 569
 570     template <typename Sequence>
 571     struct repetitive_view;
 572
 573 [heading Template parameters]
 574
 575 [table
 576     [[Parameter]            [Description]                   [Default]]
 577     [[`Sequence`]           [An arbitrary Fusion __forward_sequence__]
 578                                                             []]
 579 ]
 580
 581 [variablelist Notation
 582     [[`RV`]            [A `repetitive_view` type]]
 583     [[`s`]             [An instance of `Sequences`]]
 584     [[`rv`, `rv1`, `rv2`]    [Instances of `RV`]]
 585 ]
 586
 587 [heading Expression Semantics]
 588
 589 [table
 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 sequnce is infinite)]]
 596 ]
 597
 598 [heading Result Type Expressions]
 599
 600 [table
 601     [[Expression]]
 602     [[`__result_of_begin__<RV>::type`]]
 603     [[`__result_of_end__<RV>::type`]]
 604 ]
 605
 606 [heading Example]
 607     typedef __vector__<int, char, double> vec1;
 608     typedef __vector__<int, char, double, int, char> vec2;
 609
 610     vec1 v1(1, 'c', 2.0);
 611     vec2 v2(repetitive_view<vec1>(v1));
 612
 613     std::cout << v2 << std::endl; // 1, 'c', 2.0, 1, 'c'
 614
 615 [endsect]
 616
 617 [section flatten_view]
 618
 619 [heading Description]
 620
 621 `flatten_view` presents a view which iterates over its elements recursively in depth-first order.
 622
 623 [heading Header]
 624
 625     #include <boost/fusion/view/flatten_view.hpp>
 626     #include <boost/fusion/include/flatten_view.hpp>
 627
 628 [heading Synopsis]
 629
 630     template <typename Sequence>
 631     struct flatten_view;
 632
 633 [heading Template parameters]
 634
 635 [table
 636     [[Parameter]            [Description]                   [Default]]
 637     [[`Sequence`]           [A __forward_sequence__]        []]
 638 ]
 639
 640 [heading Model of]
 641
 642 * __forward_sequence__
 643
 644 [variablelist Notation
 645     [[`F`]             [A `flatten_view` type]]
 646     [[`s`]             [An instance of `Sequence`]]
 647     [[`f`, `f2`]       [Instances of `F`]]
 648 ]
 649
 650 [heading Expression Semantics]
 651
 652 Semantics of an expression is defined only where it differs from, or is not
 653 defined in __forward_sequence__.
 654
 655 [table
 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`.]]
 660 ]
 661
 662 [heading Example]
 663     typedef __vector__<int, int, __vector__<int, int>, int> sequence_type;
 664     sequence_type seq;
 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));
 668
 669 [endsect]
 670
 671 [endsect]