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 11Views are sequences that do not actually contain data, but instead impart 12an alternative presentation over the data from one or more underlying 13sequences. Views are proxies. They provide an efficient yet purely 14functional way to work on potentially expensive sequence operations. Views 15are inherently lazy. Their elements are only computed on demand only when 16the elements of the underlying sequence(s) are actually accessed. Views' 17lazy 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 57Semantics of an expression is defined only where it differs from, or is not 58defined 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 79satisfying a given predicate (an __mpl__ metafunction). The `filter_view` 80presents 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`] [A unary __mpl_lambda_expression__] []] 99] 100 101[heading Model of] 102 103* __forward_sequence__ 104* __associative_sequence__ if `Sequence` implements the __associative_sequence__ model. 105 106[variablelist Notation 107 [[`F`] [A `filter_view` type]] 108 [[`f`, `f2`] [Instances of `filter_view`]] 109 [[`s`] [A __forward_sequence__]] 110] 111 112[heading Expression Semantics] 113 114Semantics of an expression is defined only where it differs from, or is not 115defined in the implemented models. 116 117[table 118 [[Expression] [Semantics]] 119 [[`F(s)`] [Creates a `filter_view` given a sequence, `s`.]] 120 [[`F(f)`] [Copy constructs a `filter_view` from another `filter_view`, `f`.]] 121 [[`f = f2`] [Assigns to a `filter_view`, `f`, from another `filter_view`, `f2`.]] 122] 123 124[heading Example] 125 126 using boost::mpl::_; 127 using boost::mpl::not_; 128 using boost::is_class; 129 130 typedef __vector__<std::string, char, long, bool, double> vector_type; 131 132 vector_type v("a-string", '@', 987654, true, 6.6); 133 filter_view<vector_type const, not_<is_class<_> > > view(v); 134 std::cout << view << std::endl; 135 136[endsect] 137 138[section iterator_range] 139 140[heading Description] 141 142`iterator_range` presents a sub-range of its underlying sequence delimited 143by a pair of iterators. 144 145[heading Header] 146 147 #include <boost/fusion/view/iterator_range.hpp> 148 #include <boost/fusion/include/iterator_range.hpp> 149 150[heading Synopsis] 151 152 template <typename First, typename Last> 153 struct iterator_range; 154 155[heading Template parameters] 156 157[table 158 [[Parameter] [Description] [Default]] 159 [[`First`] [A fusion __iterator__] []] 160 [[`Last`] [A fusion __iterator__] []] 161] 162 163[heading Model of] 164 165* __forward_sequence__, __bidirectional_sequence__ or 166__random_access_sequence__ depending on the traversal characteristics (see 167__traversal_concept__) of its underlying sequence. 168* __associative_sequence__ if `First` and `Last` implement the __associative_iterator__ model. 169 170[variablelist Notation 171 [[`IR`] [An `iterator_range` type]] 172 [[`f`] [An instance of `First`]] 173 [[`l`] [An instance of `Last`]] 174 [[`ir`, `ir2`] [Instances of `iterator_range`]] 175] 176 177[heading Expression Semantics] 178 179Semantics of an expression is defined only where it differs from, or is not 180defined in the implemented models. 181 182[table 183 [[Expression] [Semantics]] 184 [[`IR(f, l)`] [Creates an `iterator_range` given iterators, `f` and `l`.]] 185 [[`IR(ir)`] [Copy constructs an `iterator_range` from another `iterator_range`, `ir`.]] 186 [[`ir = ir2`] [Assigns to a `iterator_range`, `ir`, from another `iterator_range`, `ir2`.]] 187] 188 189[heading Example] 190 191 char const* s = "Ruby"; 192 typedef __vector__<int, char, double, char const*> vector_type; 193 vector_type vec(1, 'x', 3.3, s); 194 195 typedef __result_of_begin__<vector_type>::type A; 196 typedef __result_of_end__<vector_type>::type B; 197 typedef __result_of_next__<A>::type C; 198 typedef __result_of_prior__<B>::type D; 199 200 C c(vec); 201 D d(vec); 202 203 iterator_range<C, D> range(c, d); 204 std::cout << range << std::endl; 205 206[endsect] 207 208[section joint_view] 209 210[heading Description] 211 212`joint_view` presents a view which is a concatenation of two sequences. 213 214[heading Header] 215 216 #include <boost/fusion/view/joint_view.hpp> 217 #include <boost/fusion/include/joint_view.hpp> 218 219[heading Synopsis] 220 221 template <typename Sequence1, typename Sequence2> 222 struct joint_view; 223 224[heading Template parameters] 225 226[table 227 [[Parameter] [Description] [Default]] 228 [[`Sequence1`] [A __forward_sequence__] []] 229 [[`Sequence2`] [A __forward_sequence__] []] 230] 231 232[heading Model of] 233 234* __forward_sequence__ 235* __associative_sequence__ if `Sequence1` and `Sequence2` implement the __associative_sequence__ model. 236 237[variablelist Notation 238 [[`JV`] [A `joint_view` type]] 239 [[`s1`] [An instance of `Sequence1`]] 240 [[`s2`] [An instance of `Sequence2`]] 241 [[`jv`, `jv2`] [Instances of `joint_view`]] 242] 243 244[heading Expression Semantics] 245 246Semantics of an expression is defined only where it differs from, or is not 247defined in the implemented models. 248 249[table 250 [[Expression] [Semantics]] 251 [[`JV(s1, s2)`] [Creates a `joint_view` given sequences, `s1` and `s2`.]] 252 [[`JV(jv)`] [Copy constructs a `joint_view` from another `joint_view`, `jv`.]] 253 [[`jv = jv2`] [Assigns to a `joint_view`, `jv`, from another `joint_view`, `jv2`.]] 254] 255 256[heading Example] 257 258 __vector__<int, char> v1(3, 'x'); 259 __vector__<std::string, int> v2("hello", 123); 260 joint_view< 261 __vector__<int, char> 262 , __vector__<std::string, int> 263 > view(v1, v2); 264 std::cout << view << std::endl; 265 266[endsect] 267 268[section zip_view] 269 270[heading Description] 271 272`zip_view` presents a view which iterates over a collection of __sequence__(s) in parallel. A `zip_view` 273is constructed from a __sequence__ of references to the component `__sequence__`s. 274 275[heading Header] 276 277 #include <boost/fusion/view/zip_view.hpp> 278 #include <boost/fusion/include/zip_view.hpp> 279 280[heading Synopsis] 281 282 template <typename Sequences> 283 struct zip_view; 284 285[heading Template parameters] 286 287[table 288 [[Parameter] [Description] [Default]] 289 [[`Sequences`] [A __forward_sequence__ of references to other Fusion `__sequence__`s] []] 290] 291 292[heading Model of] 293 294* __forward_sequence__, __bidirectional_sequence__ or 295__random_access_sequence__ depending on the traversal characteristics (see 296__traversal_concept__) of its underlying sequence. 297 298[variablelist Notation 299 [[`ZV`] [A `zip_view` type]] 300 [[`s`] [An instance of `Sequences`]] 301 [[`zv1`, `zv2`] [Instances of `ZV`]] 302] 303 304[heading Expression Semantics] 305 306Semantics of an expression is defined only where it differs from, or is not 307defined in __forward_sequence__. 308 309[table 310 [[Expression] [Semantics]] 311 [[`ZV(s)`] [Creates a `zip_view` given a sequence of references to the component `__sequence__`s.]] 312 [[`ZV(zv1)`] [Copy constructs a `zip_view` from another `zip_view`, `zv`.]] 313 [[`zv1 = zv2`] [Assigns to a `zip_view`, `zv`, from another `zip_view`, `zv2`.]] 314] 315 316[heading Example] 317 typedef __vector__<int,int> vec1; 318 typedef __vector__<char,char> vec2; 319 vec1 v1(1,2); 320 vec2 v2('a','b'); 321 typedef __vector__<vec1&, vec2&> sequences; 322 std::cout << zip_view<sequences>(sequences(v1, v2)) << std::endl; // ((1 a) (2 b)) 323 324[endsect] 325 326[section transform_view] 327 328The unary version of `transform_view` presents a view of its underlying 329sequence given a unary function object or function pointer. The binary 330version of `transform_view` presents a view of 2 underlying sequences, 331given a binary function object or function pointer. The `transform_view` 332inherits the traversal characteristics (see __traversal_concept__) of 333its underlying sequence or sequences. 334 335[heading Header] 336 337 #include <boost/fusion/view/transform_view.hpp> 338 #include <boost/fusion/include/transform_view.hpp> 339 340[heading Synopsis] 341 342[*Unary Version] 343 344 template <typename Sequence, typename F1> 345 struct transform_view; 346 347[*Binary Version] 348 349 template <typename Sequence1, typename Sequence2, typename F2> 350 struct transform_view; 351 352[heading Template parameters] 353 354[table 355 [[Parameter] [Description] [Default]] 356 [[`Sequence`] [A __forward_sequence__] []] 357 [[`Sequence1`] [A __forward_sequence__] []] 358 [[`Sequence2`] [A __forward_sequence__] []] 359 [[`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.] []] 360 [[`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.] []] 361] 362 363[heading Model of] 364 365* __forward_sequence__, __bidirectional_sequence__ or 366__random_access_sequence__ depending on the traversal characteristics (see 367__traversal_concept__) of its underlying sequence. 368 369[variablelist Notation 370 [[`TV`] [A `transform_view` type]] 371 [[`BTV`] [A binary `transform_view` type]] 372 [[`UTV`] [A unary `transform_view` type]] 373 [[`f1`] [An instance of `F1`]] 374 [[`f2`] [An instance of `F2`]] 375 [[`s`] [An instance of `Sequence`]] 376 [[`s1`] [An instance of `Sequence1`]] 377 [[`s2`] [An instance of `Sequence2`]] 378 [[`tv`, `tv2`] [Instances of `transform_view`]] 379] 380 381[heading Expression Semantics] 382 383Semantics of an expression is defined only where it differs from, or is not 384defined in __forward_sequence__, __bidirectional_sequence__ or 385__random_access_sequence__ depending on the traversal characteristics (see 386__traversal_concept__) of its underlying sequence or sequences. 387 388[table 389 [[Expression] [Semantics]] 390 [[`UTV(s, f1)`] [Creates a unary `transform_view` given sequence, 391 `s` and unary function object or function pointer, `f1`.]] 392 [[`BTV(s1, s2, f2)`] [Creates a binary `transform_view` given sequences, `s1` and `s2` 393 and binary function object or function pointer, `f2`.]] 394 [[`TV(tv)`] [Copy constructs a `transform_view` from another `transform_view`, `tv`.]] 395 [[`tv = tv2`] [Assigns to a `transform_view`, `tv`, from another `transform_view`, `tv2`.]] 396] 397 398[heading Example] 399 400 struct square 401 { 402 template<typename Sig> 403 struct result; 404 405 template<typename U> 406 struct result<square(U)> 407 : remove_reference<U> 408 {}; 409 410 template <typename T> 411 T operator()(T x) const 412 { 413 return x * x; 414 } 415 }; 416 417 typedef __vector__<int, short, double> vector_type; 418 vector_type vec(2, 5, 3.3); 419 420 transform_view<vector_type, square> transform(vec, square()); 421 std::cout << transform << std::endl; 422 423[endsect] 424 425[section reverse_view] 426 427`reverse_view` presents a reversed view of underlying sequence. The first 428element will be its last and the last element will be its first. 429 430[heading Header] 431 432 #include <boost/fusion/view/reverse_view.hpp> 433 #include <boost/fusion/include/reverse_view.hpp> 434 435[heading Synopsis] 436 437 template <typename Sequence> 438 struct reverse_view; 439 440[heading Template parameters] 441 442[table 443 [[Parameter] [Description] [Default]] 444 [[`Sequence`] [A __bidirectional_sequence__] []] 445] 446 447[heading Model of] 448 449* A model of __bidirectional_sequence__ if `Sequence` is a __bidirectional_sequence__ 450else, __random_access_sequence__ if `Sequence` is a __random_access_sequence__. 451* __associative_sequence__ if `Sequence` implements the __associative_sequence__ model. 452 453[variablelist Notation 454 [[`RV`] [A `reverse_view` type]] 455 [[`s`] [An instance of `Sequence`]] 456 [[`rv`, `rv2`] [Instances of `reverse_view`]] 457] 458 459[heading Expression Semantics] 460 461Semantics of an expression is defined only where it differs from, or is not 462defined in the implemented models. 463 464[table 465 [[Expression] [Semantics]] 466 [[`RV(s)`] [Creates a unary `reverse_view` given sequence, `s`.]] 467 [[`RV(rv)`] [Copy constructs a `reverse_view` from another `reverse_view`, `rv`.]] 468 [[`rv = rv2`] [Assigns to a `reverse_view`, `rv`, from another `reverse_view`, `rv2`.]] 469] 470 471[heading Example] 472 473 typedef __vector__<int, short, double> vector_type; 474 vector_type vec(2, 5, 3.3); 475 476 reverse_view<vector_type> reverse(vec); 477 std::cout << reverse << std::endl; 478 479[endsect] 480 481[section nview] 482 483[heading Description] 484 485`nview` presents a view which iterates over a given __sequence__ in a specified order. 486An `nview` is constructed from an arbitrary __sequence__ and a list of indices specifying 487the elements to iterate over. 488 489[heading Header] 490 491 #include <boost/fusion/view/nview.hpp> 492 #include <boost/fusion/include/nview.hpp> 493 494[heading Synopsis] 495 496 template <typename Sequence, typename Indices> 497 struct nview; 498 499 template <typename Sequence, int I1, int I2 = -1, ...> 500 typename result_of::nview<Sequence, I1, I2, ...>::type 501 as_nview(Sequence& s); 502 503[heading Template parameters] 504 505[table 506 [[Parameter] [Description] [Default]] 507 [[`Sequence`] [An arbitrary Fusion __forward_sequence__] 508 []] 509 [[`Indices`] [A `mpl::vector_c<int, ...>` holding the indices defining 510 the required iteration order.] []] 511 [[`I1`, `I2`, `I3`...] [A list of integers specifying the required 512 iteration order.] [`INT_MAX` for `I2`, `I3`...]] 513] 514 515[heading Model of] 516 517* __random_access_sequence__ (see __traversal_concept__) 518 519[variablelist Notation 520 [[`NV`] [A `nview` type]] 521 [[`s`] [An instance of `Sequences`]] 522 [[`nv1`, `nv2`] [Instances of `NV`]] 523] 524 525[heading Expression Semantics] 526 527Semantics of an expression is defined only where it differs from, or is not 528defined in __random_access_sequence__. 529 530[table 531 [[Expression] [Semantics]] 532 [[`NV(s)`] [Creates an `nview` given a sequence and a list of indices.]] 533 [[`NV(nv1)`] [Copy constructs an `nview` from another `nview`, `nv1`.]] 534 [[`nv1 = nv2`] [Assigns to an `nview`, `nv1`, from another `nview`, `nv2`.]] 535] 536 537The `nview` internally stores a Fusion __vector__ of references to the elements 538of the original Fusion __sequence__ 539 540[heading Example] 541 typedef __vector__<int, char, double> vec; 542 typedef mpl::vector_c<int, 2, 1, 0, 2, 0> indices; 543 544 vec v1(1, 'c', 2.0); 545 546 std::cout << nview<vec, indices>(v1) << std::endl; // (2.0 c 1 2.0 1) 547 std::cout << as_nview<2, 1, 1, 0>(v1) << std::endl; // (2.0 c c 1) 548 549[endsect] 550 551[section repetitive_view] 552 553[heading Description] 554 555`repetitive_view` presents a view which iterates over a given 556__sequence__ repeatedly. Because a `repetitive_view` 557has infinite length, it can only be used when some external 558condition determines the end. Thus, initializing a fixed 559length sequence with a `repetitive_view` is okay, but 560printing a `repetitive_view` to `std::cout` is not. 561 562[heading Header] 563 564 #include <boost/fusion/view/repetitive_view.hpp> 565 #include <boost/fusion/include/repetitive_view.hpp> 566 567[heading Synopsis] 568 569 template <typename Sequence> 570 struct repetitive_view; 571 572[heading Template parameters] 573 574[table 575 [[Parameter] [Description] [Default]] 576 [[`Sequence`] [An arbitrary Fusion __forward_sequence__] 577 []] 578] 579 580[variablelist Notation 581 [[`RV`] [A `repetitive_view` type]] 582 [[`s`] [An instance of `Sequences`]] 583 [[`rv`, `rv1`, `rv2`] [Instances of `RV`]] 584] 585 586[heading Expression Semantics] 587 588[table 589 [[Expression] [Return Type] [Semantics]] 590 [[`RV(s)`] [] [Creates an `repetitive_view` given the underlying sequence.]] 591 [[`RV(rv1)`] [] [Copy constructs an `repetitive_view` from another `repetitive_view`, `rv1`.]] 592 [[`rv1 = rv2`] [] [Assigns to a `repetitive_view`, `rv1`, from another `repetitive_view`, `rv2`.]] 593 [[`__begin__(rv)`] [__forward_iterator__] []] 594 [[`__end__(rv)`] [__forward_iterator__] [Creates an unreachable iterator (since the sequence is infinite)]] 595] 596 597[heading Result Type Expressions] 598 599[table 600 [[Expression]] 601 [[`__result_of_begin__<RV>::type`]] 602 [[`__result_of_end__<RV>::type`]] 603] 604 605[heading Example] 606 typedef __vector__<int, char, double> vec1; 607 typedef __vector__<int, char, double, int, char> vec2; 608 609 vec1 v1(1, 'c', 2.0); 610 vec2 v2(repetitive_view<vec1>(v1)); 611 612 std::cout << v2 << std::endl; // 1, 'c', 2.0, 1, 'c' 613 614[endsect] 615 616[section flatten_view] 617 618[heading Description] 619 620`flatten_view` presents a view which iterates over its elements recursively in depth-first order. 621 622[heading Header] 623 624 #include <boost/fusion/view/flatten_view.hpp> 625 #include <boost/fusion/include/flatten_view.hpp> 626 627[heading Synopsis] 628 629 template <typename Sequence> 630 struct flatten_view; 631 632[heading Template parameters] 633 634[table 635 [[Parameter] [Description] [Default]] 636 [[`Sequence`] [A __forward_sequence__] []] 637] 638 639[heading Model of] 640 641* __forward_sequence__ 642 643[variablelist Notation 644 [[`F`] [A `flatten_view` type]] 645 [[`s`] [An instance of `Sequence`]] 646 [[`f`, `f2`] [Instances of `F`]] 647] 648 649[heading Expression Semantics] 650 651Semantics of an expression is defined only where it differs from, or is not 652defined in __forward_sequence__. 653 654[table 655 [[Expression] [Semantics]] 656 [[`F(s)`] [Creates a `flatten_view` given sequence, `s`.]] 657 [[`F(f)`] [Copy constructs a `flatten_view` from another `flatten_view`, `f`.]] 658 [[`f = f2`] [Assigns to a `flatten_view`, `f`, from another `flatten_view`, `f2`.]] 659] 660 661[heading Example] 662 typedef __vector__<int, int, __vector__<int, int>, int> sequence_type; 663 sequence_type seq; 664 __flatten_view__<sequence_type> flattened(seq); 665 __copy__(__make_vector__(1, 2, 3, 4, 5), flattened); 666 assert(seq == __make_vector__(1, 2, __make_vector__(3, 4), 5)); 667 668[endsect] 669 670[endsect] 671