1[/============================================================================== 2 Copyright (C) 2001-2011 Joel de Guzman 3 Copyright (C) 2006 Dan Marsden 4 Copyright (C) 2014 Christoph Weiss 5 6 Use, modification and distribution is subject to the Boost Software 7 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 8 http://www.boost.org/LICENSE_1_0.txt) 9===============================================================================/] 10[section Sequence] 11 12Like __mpl__, the Sequence is a fundamental concept in Fusion. A Sequence 13may or may not actually store or contain data. __containers__ are sequences 14that hold data. __views__, on the other hand, are sequences that do not 15store any data. Instead, they are proxies that impart an alternative 16presentation over another sequence. All models of Sequence have an 17associated __iterator__ type that can be used to iterate through the 18Sequence's elements. 19 20[heading Header] 21 22 #include <boost/fusion/sequence.hpp> 23 #include <boost/fusion/include/sequence.hpp> 24 25[section Concepts] 26 27Fusion Sequences are organized into a hierarchy of concepts. 28 29[heading Traversal] 30 31Fusion's sequence traversal related concepts parallel Fusion's 32__iterator_concepts__. __forward_sequence__ is the most basic concept. 33__bidirectional_sequence__ is a refinement of __forward_sequence__. 34__random_access_sequence__ is a refinement of __bidirectional_sequence__. 35These concepts pertain to sequence traversal. 36 37[heading Associativity] 38 39The __associative_sequence__ concept is orthogonal to traversal. An Associative 40Sequence allows efficient retrieval of elements based on keys. 41 42[heading Boundary] 43 44The __unbounded_sequence__ concept is also orthogonal to traversal and associativity. 45A Unbounded Sequence allows out-of-bounds access. 46 47[section Forward Sequence] 48 49[heading Description] 50 51A Forward Sequence is a Sequence whose elements are arranged in a definite 52order. The ordering is guaranteed not to change from iteration to 53iteration. The requirement of a definite ordering allows the definition of 54element-by-element equality (if the container's element type is Equality 55Comparable) and of lexicographical ordering (if the container's element 56type is LessThan Comparable). 57 58[variablelist Notation 59 [[`s`] [A Forward Sequence]] 60 [[`S`] [A Forward Sequence type]] 61 [[`o`] [An arbitrary object]] 62 [[`e`] [A Sequence element]] 63] 64 65[heading Valid Expressions] 66 67For any Forward Sequence the following expressions must be valid: 68 69[table 70 [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] 71 [[`__begin__(s)`] [__forward_iterator__] [] [Constant]] 72 [[`__end__(s)`] [__forward_iterator__] [] [Constant]] 73 [[`__size__(s)`] [__mpl_integral_constant__. 74 Convertible to int.] [] [Constant]] 75 [[`__empty__(s)`] [__mpl_boolean_constant__. 76 Convertible to bool.] [] [Constant]] 77 [[`__front__(s)`] [Any type] [] [Constant]] 78 [[`__front__(s) = o`] [Any type] [`s` is mutable and 79 `e = o`, where `e` 80 is the first element 81 in the sequence, is 82 a valid expression.] [Constant]] 83] 84 85[heading Result Type Expressions] 86 87[table 88 [[Expression] [Compile Time Complexity]] 89 [[`__result_of_begin__<S>::type`] [Amortized constant time]] 90 [[`__result_of_end__<S>::type`] [Amortized constant time]] 91 [[`__result_of_size__<S>::type`] [Unspecified]] 92 [[`__result_of_empty__<S>::type`] [Constant time]] 93 [[`__result_of_front__<S>::type`] [Amortized constant time]] 94] 95 96[heading Expression Semantics] 97 98[table 99 [[Expression] [Semantics]] 100 [[`__begin__(s)`] [An iterator to the first element of the sequence; see __begin__.]] 101 [[`__end__(s)`] [A past-the-end iterator to the sequence; see __end__.]] 102 [[`__size__(s)`] [The size of the sequence; see __size__.]] 103 [[`__empty__(s)`] [A boolean Integral Constant `c` such that 104 `c::value == true` if and only if the sequence 105 is empty; see __empty__.]] 106 [[`__front__(s)`] [The first element in the sequence; see __front__.]] 107] 108 109[heading Invariants] 110 111For any Forward Sequence s the following invariants always hold: 112 113* `[__begin__(s), __end__(s))` is always a valid range. 114* An __algorithm__ that iterates through the range `[__begin__(s), __end__(s))` 115 will pass through every element of `s` exactly once. 116* `__begin__(s)` is identical to `__end__(s))` if and only if `s` is empty. 117* Two different iterations through `s` will access its elements in 118 the same order. 119 120[heading Models] 121 122* __std_pair__ 123* __boost_array__ 124* __vector__ 125* __cons__ 126* __list__ 127* __set__ 128* __map__ 129* __single_view__ 130* __filter_view__ 131* __iterator_range__ 132* __joint_view__ 133* __transform_view__ 134* __reverse_view__ 135* __zip_view__ 136 137[endsect] 138 139[section Bidirectional Sequence] 140 141[heading Description] 142 143A Bidirectional Sequence is a __forward_sequence__ whose iterators model 144__bidirectional_iterator__. 145 146[heading Refinement of] 147 148__forward_sequence__ 149 150[variablelist Notation 151 [[`s`] [A Bidirectional Sequence]] 152 [[`S`] [A Bidirectional Sequence type]] 153 [[`o`] [An arbitrary object]] 154 [[`e`] [A Sequence element]] 155] 156 157[heading Valid Expressions] 158 159In addition to the requirements defined in __forward_sequence__, for any 160Bidirectional Sequence the following must be met: 161 162[table 163 [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] 164 [[`__begin__(s)`] [__bidirectional_iterator__] [] [Constant]] 165 [[`__end__(s)`] [__bidirectional_iterator__] [] [Constant]] 166 [[`__back__(s)`] [Any type] [] [Constant]] 167 [[`__back__(s) = o`] [Any type] [`s` is mutable and 168 `e = o`, where `e` 169 is the first element 170 in the sequence, is 171 a valid expression.] [Constant]] 172] 173 174[heading Result Type Expressions] 175 176[table 177 [[Expression] [Compile Time Complexity]] 178 [[`__result_of_begin__<S>::type`] [Amortized constant time]] 179 [[`__result_of_end__<S>::type`] [Amortized constant time]] 180 [[`__result_of_back__<S>::type`] [Amortized constant time]] 181] 182 183[heading Expression Semantics] 184 185The semantics of an expression are defined only where they differ from, or 186are not defined in __forward_sequence__. 187 188[table 189 [[Expression] [Semantics]] 190 [[`__back__(s)`] [The last element in the sequence; see __back__.]] 191] 192 193[heading Models] 194 195* __std_pair__ 196* __boost_array__ 197* __vector__ 198* __map__ 199* __reverse_view__ 200* __single_view__ 201* __iterator_range__ (where adapted sequence is a Bidirectional Sequence) 202* __transform_view__ (where adapted sequence is a Bidirectional Sequence) 203* __zip_view__ (where adapted sequences are models of Bidirectional Sequence) 204 205[endsect] 206 207[section Random Access Sequence] 208 209[heading Description] 210 211A Random Access Sequence is a __bidirectional_sequence__ whose iterators 212model __random_access_iterator__. It guarantees constant time access to 213arbitrary sequence elements. 214 215[heading Refinement of] 216 217__bidirectional_sequence__ 218 219[variablelist Notation 220 [[`s`] [A Random Access Sequence]] 221 [[`S`] [A Random Access Sequence type]] 222 [[`M`] [An __mpl__ integral constant]] 223 [[`N`] [An integral constant]] 224 [[`o`] [An arbitrary object]] 225 [[`e`] [A Sequence element]] 226] 227 228[heading Valid Expressions] 229 230In addition to the requirements defined in __bidirectional_sequence__, for 231any Random Access Sequence the following must be met: 232 233[table 234 [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] 235 [[`__begin__(s)`] [__random_access_iterator__] [] [Constant]] 236 [[`__end__(s)`] [__random_access_iterator__] [] [Constant]] 237 [[`__at_c__<N>(s)`] [Any type] [] [Constant]] 238 [[`__at_c__<N>(s) = o`] [Any type] [`s` is mutable and 239 `e = o`, where `e` 240 is the first element 241 in the sequence, is 242 a valid expression.] [Constant]] 243 [[`__at__<M>(s)`] [Any type] [] [Constant]] 244 [[`__at__<M>(s) = o`] [Any type] [`s` is mutable and 245 `e = o`, where `e` 246 is the first element 247 in the sequence, is 248 a valid expression.] [Constant]] 249] 250 251[heading Result Type Expressions] 252 253[table 254 [[Expression] [Compile Time Complexity]] 255 [[`__result_of_begin__<S>::type`] [Amortized constant time]] 256 [[`__result_of_end__<S>::type`] [Amortized constant time]] 257 [[`__result_of_at__<S, M>::type`] [Amortized constant time]] 258 [[`__result_of_at_c__<S, N>::type`] [Amortized constant time]] 259 [[`__result_of_value_at__<S, M>::type`] [Amortized constant time]] 260 [[`__result_of_value_at_c__<S, N>::type`] [Amortized constant time]] 261] 262 263[note `__result_of_at__<S, M>` returns the actual type returned by 264`__at__<M>(s)`. In most cases, this is a reference. Hence, there is no way to 265know the exact element type using `__result_of_at__<S, M>`.The element at `M` 266may actually be a reference to begin with. For this purpose, you can use 267`__result_of_value_at__<S, M>` (Note that, `__result_of_value_at_c__<S, N>` 268is a counterpart of `__result_of_at_c__<S, N>` as well).] 269 270[heading Expression Semantics] 271 272The semantics of an expression are defined only where they differ from, or 273are not defined in __bidirectional_sequence__. 274 275[table 276 [[Expression] [Semantics]] 277 [[`__at__<M>(s)`] [The Mth element from the beginning of the sequence; see __at__.]] 278 [[`__at_c__<N>(s)`] [The Nth element from the beginning of the sequence; see __at_c__.]] 279] 280 281[heading Models] 282 283* __std_pair__ 284* __boost_array__ 285* __vector__ 286* __map__ 287* __reverse_view__ 288* __single_view__ 289* __iterator_range__ (where adapted sequence is a Random Access Sequence) 290* __transform_view__ (where adapted sequence is a Random Access Sequence) 291* __zip_view__ (where adapted sequences are models of Random Access Sequence) 292 293[endsect] 294 295[section Associative Sequence] 296 297[heading Description] 298 299An Associative Sequence allows efficient retrieval of elements based on keys. 300Like associative sequences in __mpl__, and unlike associative containers in 301__stl__, Fusion associative sequences have no implied ordering relation. 302Instead, type identity is used to impose an equivalence relation on keys. 303Keys are not checked for uniqueness. 304 305[variablelist Notation 306 [[`s`] [An Associative Sequence]] 307 [[`S`] [An Associative Sequence type]] 308 [[`K`] [An arbitrary /key/ type]] 309 [[`o`] [An arbitrary object]] 310 [[`e`] [A Sequence element]] 311] 312 313[heading Valid Expressions] 314 315For any Associative Sequence the following expressions must be valid: 316 317[table 318 [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] 319 [[`__has_key__<K>(s)`] [__mpl_boolean_constant__. 320 Convertible to bool.] [] [Constant]] 321 [[`__at_key__<K>(s)`] [Any type] [] [Constant]] 322 [[`__at_key__<K>(s) = o`] [Any type] [`s` is mutable and 323 `e = o`, where `e` 324 is the first element 325 in the sequence, is 326 a valid expression.] [Constant]] 327] 328 329[heading Result Type Expressions] 330 331[table 332 [[Expression] [Compile Time Complexity]] 333 [[`__result_of_has_key__<S, K>::type`] [Amortized constant time]] 334 [[`__result_of_at_key__<S, K>::type`] [Amortized constant time]] 335 [[`__result_of_value_at_key__<S, K>::type`] [Amortized constant time]] 336] 337 338[note `__result_of_at_key__<S, K>` returns the actual type returned 339by `__at_key__<K>(s)`. In most cases, this is a reference. Hence, there is no 340way to know the exact element type using `__result_of_at_key__<S, K>`.The 341element at `K` may actually be a reference to begin with. For this purpose, 342you can use `__result_of_value_at_key__<S, K>`.] 343 344[heading Expression Semantics] 345 346[table 347 [[Expression] [Semantics]] 348 [[`__has_key__<K>(s)`] [A boolean Integral Constant `c` such that 349 `c::value == true` if and only if there is 350 one or more elements with the key `k` in `s`; 351 see __has_key__.]] 352 [[`__at_key__<K>(s)`] [The element associated with the key 353 `K` in the sequence `s`; see __at__.]] 354] 355 356[heading Models] 357 358* __set__ 359* __map__ 360* __filter_view__ (where adapted sequence is an __associative_sequence__ and a __forward_sequence__) 361* __iterator_range__ (where adapted iterators are __associative_iterator__\ s) 362* __joint_view__ (where adapted sequences are __associative_sequence__\ s and __forward_sequence__\ s) 363* __reverse_view__ (where adapted sequence is an __associative_sequence__ and a __bidirectional_sequence__) 364 365[endsect] 366 367[section Unbounded Sequence] 368 369[heading Description] 370 371A Unbounded Sequence allows Out-of-Bounds access: it will achieve something like a __window_function__. 372Most of the sequences do not meet this concept, but some special usecases do. 373 374[important User extending sequences should handle any parameters or be SFINAE-friendly.] 375 376[variablelist Notation 377 [[`s`] [An Fusion Sequence]] 378 [[`S`] [An Fusion Sequence type]] 379 [[`M`] [An __mpl__ integral constant]] 380 [[`N`] [An integral constant]] 381 [[`K`] [An arbitrary /key/ type]] 382 [[`o`] [An arbitrary object]] 383 [[`e`] [A Sequence element]] 384] 385 386[heading Valid Expressions] 387 388[table 389 [[Expression] [Return type] [Type Requirements] [Runtime Complexity]] 390 [[`__at_c__<N>(s)`] [Any type] [] [Depends on its traversability]] 391 [[`__at_c__<N>(s) = o`] [Any type] [] [Depends on its traversability]] 392 [[`__at__<M>(s)`] [Any type] [] [Depends on its traversability]] 393 [[`__at__<M>(s) = o`] [Any type] [] [Depends on its traversability]] 394 [[`__at_key__<K>(s)`] [Any type] [`S` should be __associative_sequence__] [Depends on its traversability]] 395 [[`__at_key__<K>(s) = o`] [Any type] [`S` should be __associative_sequence__] [Depends on its traversability]] 396] 397 398[heading Result Type Expressions] 399 400[table 401 [[Expression] [Compile Time Complexity]] 402 [[`__result_of_at__<S, M>::type`] [Depends on its traversability]] 403 [[`__result_of_at_c__<S, N>::type`] [Depends on its traversability]] 404 [[`__result_of_value_at__<S, M>::type`] [Depends on its traversability]] 405 [[`__result_of_value_at_c__<S, N>::type`] [Depends on its traversability]] 406 [[`__result_of_at_key__<S, K>::type`] [Depends on its traversability]] 407 [[`__result_of_value_at_key__<S, K>::type`] [Depends on its traversability]] 408] 409 410[heading Models] 411 412* none. 413 414[endsect] 415 416[endsect] 417 418[section Intrinsic] 419 420Intrinsic form the essential interface of every Fusion __sequence__. __stl__ 421counterparts of these functions are usually implemented as member 422functions. Intrinsic functions, unlike __algorithms__, are not generic 423across the full __sequence__ repertoire. They need to be implemented for 424each Fusion __sequence__[footnote In practice, many of intrinsic functions 425have default implementations that will work in majority of cases]. 426 427[heading Header] 428 429 #include <boost/fusion/sequence/intrinsic.hpp> 430 #include <boost/fusion/include/intrinsic.hpp> 431 432[section Functions] 433 434[section begin] 435 436[heading Description] 437 438Returns an iterator pointing to the first element in the sequence. 439 440[heading Synopsis] 441 442 template <typename Sequence> 443 typename __result_of_begin__<Sequence>::type 444 begin(Sequence& seq); 445 446 template <typename Sequence> 447 typename __result_of_begin__<Sequence const>::type 448 begin(Sequence const& seq); 449 450[heading Parameters] 451 452[table 453 [[Parameter] [Requirement] [Description]] 454 [[`seq`] [Model of __forward_sequence__] [The sequence we wish to get an iterator from.]] 455] 456 457[heading Expression Semantics] 458 459 begin(seq); 460 461[*Return type]: 462 463* A model of __forward_iterator__ if `seq` is a __forward_sequence__ 464else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ 465else, __random_access_iterator__ if `seq` is a __random_access_sequence__. 466* A model of __associative_iterator__ if `seq` is an __associative_sequence__. 467 468[*Semantics]: Returns an iterator pointing to the first element in the sequence. 469 470[heading Header] 471 472 #include <boost/fusion/sequence/intrinsic/begin.hpp> 473 #include <boost/fusion/include/begin.hpp> 474 475[heading Example] 476 477 __vector__<int, int, int> v(1, 2, 3); 478 assert(__deref__(begin(v)) == 1); 479 480[endsect] 481 482[section end] 483 484[heading Description] 485 486Returns an iterator pointing to one element past the end of the sequence. 487 488[heading Synopsis] 489 490 template <typename Sequence> 491 typename __result_of_end__<Sequence>::type 492 end(Sequence& seq); 493 494 template <typename Sequence> 495 typename __result_of_end__<Sequence const>::type 496 end(Sequence const& seq); 497 498[heading Parameters] 499 500[table 501 [[Parameter] [Requirement] [Description]] 502 [[`seq`] [Model of __forward_sequence__] [The sequence we wish to get an iterator from.]] 503] 504 505[heading Expression Semantics] 506 507 end(seq); 508 509[*Return type]: 510 511* A model of __forward_iterator__ if `seq` is a __forward_sequence__ 512else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ 513else, __random_access_iterator__ if `seq` is a __random_access_sequence__. 514* A model of __associative_iterator__ if `seq` is an __associative_sequence__. 515 516[*Semantics]: Returns an iterator pointing to one element past the end of 517the sequence. 518 519[heading Header] 520 521 #include <boost/fusion/sequence/intrinsic/end.hpp> 522 #include <boost/fusion/include/end.hpp> 523 524[heading Example] 525 526 __vector__<int, int, int> v(1, 2, 3); 527 assert(__deref__(__prior__(end(v))) == 3); 528 529[endsect] 530 531[section empty] 532 533[heading Description] 534 535Returns a type convertible to `bool` that evaluates to `true` if the 536sequence is empty, else, evaluates to `false`. 537 538[heading Synopsis] 539 540 template <typename Sequence> 541 typename __result_of_empty__<Sequence>::type 542 empty(Sequence const& seq); 543 544[heading Parameters] 545 546[table 547 [[Parameter] [Requirement] [Description]] 548 [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] 549] 550 551[heading Expression Semantics] 552 553 empty(seq); 554 555[*Return type]: Convertible to `bool`. 556 557[*Semantics]: Evaluates to `true` if the sequence is empty, else, evaluates 558to `false`. 559 560[heading Header] 561 562 #include <boost/fusion/sequence/intrinsic/empty.hpp> 563 #include <boost/fusion/include/empty.hpp> 564 565[heading Example] 566 567 __vector__<int, int, int> v(1, 2, 3); 568 assert(empty(v) == false); 569 570[endsect] 571 572[section front] 573 574[heading Description] 575 576Returns the first element in the sequence. 577 578[heading Synopsis] 579 580 template <typename Sequence> 581 typename __result_of_front__<Sequence>::type 582 front(Sequence& seq); 583 584 template <typename Sequence> 585 typename __result_of_front__<Sequence const>::type 586 front(Sequence const& seq); 587 588[heading Parameters] 589 590[table 591 [[Parameter] [Requirement] [Description]] 592 [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] 593] 594 595[heading Expression Semantics] 596 597 front(seq); 598 599[*Return type]: Returns a reference to the first element in the sequence 600`seq` if `seq` is mutable and `e = o`, where `e` is the first element in 601the sequence, is a valid expression. Else, returns a type convertible to 602the first element in the sequence. 603 604[*Precondition]: `__empty__(seq) == false` 605 606[*Semantics]: Returns the first element in the sequence. 607 608[heading Header] 609 610 #include <boost/fusion/sequence/intrinsic/front.hpp> 611 #include <boost/fusion/include/front.hpp> 612 613[heading Example] 614 615 __vector__<int, int, int> v(1, 2, 3); 616 assert(front(v) == 1); 617 618[endsect] 619 620[section back] 621 622[heading Description] 623 624Returns the last element in the sequence. 625 626[heading Synopsis] 627 628 template <typename Sequence> 629 typename __result_of_back__<Sequence>::type 630 back(Sequence& seq); 631 632 template <typename Sequence> 633 typename __result_of_back__<Sequence const>::type 634 back(Sequence const& seq); 635 636[heading Parameters] 637 638[table 639 [[Parameter] [Requirement] [Description]] 640 [[`seq`] [Model of __bidirectional_sequence__] [The sequence we wish to investigate.]] 641] 642 643[heading Expression Semantics] 644 645 back(seq); 646 647[*Return type]: Returns a reference to the last element in the sequence 648`seq` if `seq` is mutable and `e = o`, where `e` is the last element in the 649sequence, is a valid expression. Else, returns a type convertible to the 650last element in the sequence. 651 652[*Precondition]: `__empty__(seq) == false` 653 654[*Semantics]: Returns the last element in the sequence. 655 656[heading Header] 657 658 #include <boost/fusion/sequence/intrinsic/back.hpp> 659 #include <boost/fusion/include/back.hpp> 660 661[heading Example] 662 663 __vector__<int, int, int> v(1, 2, 3); 664 assert(back(v) == 3); 665 666[endsect] 667 668[section size] 669 670[heading Description] 671 672Returns a type convertible to `int` that evaluates the number of elements 673in the sequence. 674 675[heading Synopsis] 676 677 template <typename Sequence> 678 typename __result_of_size__<Sequence>::type 679 size(Sequence const& seq); 680 681[heading Parameters] 682 683[table 684 [[Parameter] [Requirement] [Description]] 685 [[`seq`] [Model of __forward_sequence__] [The sequence we wish to investigate.]] 686] 687 688[heading Expression Semantics] 689 690 size(seq); 691 692[*Return type]: Convertible to `int`. 693 694[*Semantics]: Returns the number of elements in the sequence. 695 696[heading Header] 697 698 #include <boost/fusion/sequence/intrinsic/size.hpp> 699 #include <boost/fusion/include/size.hpp> 700 701[heading Example] 702 703 __vector__<int, int, int> v(1, 2, 3); 704 assert(size(v) == 3); 705 706[endsect] 707 708[section at] 709 710[heading Description] 711 712Returns the M-th element from the beginning of the sequence. 713 714[heading Synopsis] 715 716 template <typename M, typename Sequence> 717 typename __result_of_at__<Sequence, N>::type 718 at(Sequence& seq); 719 720 template <typename M, typename Sequence> 721 typename __result_of_at__<Sequence const, N>::type 722 at(Sequence const& seq); 723 724[heading Parameters] 725 726[table 727 [[Parameter] [Requirement] [Description]] 728 [[`seq`] [Model of __random_access_sequence__] [The sequence we wish to investigate.]] 729 [[`M`] [An __mpl_integral_constant__] [An index from the beginning of the 730 sequence.]] 731] 732 733[heading Expression Semantics] 734 735 at<M>(seq); 736 737[*Return type]: Returns a reference to the M-th element from the beginning 738of the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the M-th 739element from the beginning of the sequence, is a valid expression. Else, 740returns a type convertible to the M-th element from the beginning of the 741sequence. 742 743[*Precondition]: `0 <= M::value < __size__(seq)` (where `seq` is not __unbounded_sequence__) 744 745[*Semantics]: Equivalent to 746 747 __deref__(__advance__<M>(__begin__(s))) 748 749[heading Header] 750 751 #include <boost/fusion/sequence/intrinsic/at.hpp> 752 #include <boost/fusion/include/at.hpp> 753 754[heading Example] 755 756 __vector__<int, int, int> v(1, 2, 3); 757 assert(at<mpl::int_<1> >(v) == 2); 758 759[endsect] 760 761[section at_c] 762 763[heading Description] 764 765Returns the N-th element from the beginning of the sequence. 766 767[heading Synopsis] 768 769 template <int N, typename Sequence> 770 typename __result_of_at_c__<Sequence, N>::type 771 at_c(Sequence& seq); 772 773 template <int N, typename Sequence> 774 typename __result_of_at_c__<Sequence const, N>::type 775 at_c(Sequence const& seq); 776 777[heading Parameters] 778 779[table 780 [[Parameter] [Requirement] [Description]] 781 [[`seq`] [Model of __random_access_sequence__] [The sequence we wish to investigate.]] 782 [[`N`] [An integral constant] [An index from the beginning of the 783 sequence.]] 784] 785 786[heading Expression Semantics] 787 788 at_c<N>(seq); 789 790[*Return type]: Returns a reference to the N-th element from the beginning 791of the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the N-th 792element from the beginning of the sequence, is a valid expression. Else, 793returns a type convertible to the N-th element from the beginning of the 794sequence. 795 796[*Precondition]: `0 <= N < __size__(seq)` (where `seq` is not __unbounded_sequence__) 797 798[*Semantics]: Equivalent to 799 800 __deref__(__advance__<N>(__begin__(s))) 801 802[heading Header] 803 804 #include <boost/fusion/sequence/intrinsic/at_c.hpp> 805 #include <boost/fusion/include/at_c.hpp> 806 807[heading Example] 808 809 __vector__<int, int, int> v(1, 2, 3); 810 assert(at_c<1>(v) == 2); 811 812[endsect] 813 814[section has_key] 815 816[heading Description] 817 818Returns a type convertible to `bool` that evaluates to `true` if the 819sequence contains an element associated with a Key, else, evaluates to 820`false`. 821 822[heading Synopsis] 823 824 template <typename Key, typename Sequence> 825 typename __result_of_has_key__<Sequence, Key>::type 826 has_key(Sequence const& seq); 827 828[heading Parameters] 829 830[table 831 [[Parameter] [Requirement] [Description]] 832 [[`seq`] [Model of __associative_sequence__] [The sequence we wish to investigate.]] 833 [[`Key`] [Any type] [The queried key.]] 834] 835 836[heading Expression Semantics] 837 838 has_key<Key>(seq); 839 840[*Return type]: Convertible to `bool`. 841 842[*Semantics]: Evaluates to `true` if the sequence contains an element 843associated with Key, else, evaluates to `false`. 844 845[heading Header] 846 847 #include <boost/fusion/sequence/intrinsic/has_key.hpp> 848 #include <boost/fusion/include/has_key.hpp> 849 850[heading Example] 851 852 __set__<int, char, bool> s(1, 'x', true); 853 assert(has_key<char>(s) == true); 854 855[endsect] 856 857[section at_key] 858 859[heading Description] 860 861Returns the element associated with a Key from the sequence. 862 863[heading Synopsis] 864 865 template <typename Key, typename Sequence> 866 typename __result_of_at_key__<Sequence, Key>::type 867 at_key(Sequence& seq); 868 869 template <typename Key, typename Sequence> 870 typename __result_of_at_key__<Sequence const, Key>::type 871 at_key(Sequence const& seq); 872 873[heading Parameters] 874 875[table 876 [[Parameter] [Requirement] [Description]] 877 [[`seq`] [Model of __associative_sequence__] [The sequence we wish to investigate.]] 878 [[`Key`] [Any type] [The queried key.]] 879] 880 881[heading Expression Semantics] 882 883 at_key<Key>(seq); 884 885[*Return type]: Returns a reference to the element associated with Key from 886the sequence `seq` if `seq` is mutable and `e = o`, where `e` is the 887element associated with Key, is a valid expression. Else, returns a type 888convertible to the element associated with Key. 889 890[*Precondition]: `has_key<Key>(seq) == true` (where `seq` is not __unbounded_sequence__) 891 892[*Semantics]: Returns the element associated with Key. 893 894[heading Header] 895 896 #include <boost/fusion/sequence/intrinsic/at_key.hpp> 897 #include <boost/fusion/include/at_key.hpp> 898 899[heading Example] 900 901 __set__<int, char, bool> s(1, 'x', true); 902 assert(at_key<char>(s) == 'x'); 903 904[endsect] 905 906[section swap] 907 908[heading Description] 909 910Performs an element by element swap of the elements in 2 sequences. 911 912[heading Synopsis] 913 template<typename Seq1, typename Seq2> 914 typename __result_of_swap__<Seq1, Seq2>::type 915 swap(Seq1& seq1, Seq2& seq2); 916 917[heading Parameters] 918 919[table 920 [[Parameters] [Requirement] [Description]] 921 [[`seq1`, `seq2`][Models of __forward_sequence__][The sequences whose elements we wish to swap.]] 922] 923 924[heading Expression Semantics] 925 926 swap(seq1, seq2); 927 928[*Return type]: `void` 929 930[*Precondition]: `__size__(seq1) == __size__(seq2)` 931 932[*Semantics]: Calls `swap(a1, b1)` for corresponding elements in `seq1` and `seq2`. 933 934[heading Header] 935 936 #include <boost/fusion/sequence/intrinsic/swap.hpp> 937 #include <boost/fusion/include/swap.hpp> 938 939[heading Example] 940 __vector__<int, std::string> v1(1, "hello"), v2(2, "world"); 941 swap(v1, v2); 942 assert(v1 == __make_vector__(2, "world")); 943 assert(v2 == __make_vector__(1, "hello")); 944 945[endsect] 946 947[endsect] 948 949[section Metafunctions] 950 951[section begin] 952 953[heading Description] 954Returns the result type of __begin__. 955 956[heading Synopsis] 957 template<typename Seq> 958 struct begin 959 { 960 typedef __unspecified__ type; 961 }; 962 963[table Parameters 964 [[Parameter] [Requirement] [Description]] 965 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 966] 967 968[heading Expression Semantics] 969 result_of::begin<Seq>::type 970 971[*Return type]: 972 973* A model of __forward_iterator__ if `seq` is a __forward_sequence__ 974else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ 975else, __random_access_iterator__ if `seq` is a __random_access_sequence__. 976* A model of __associative_iterator__ if `seq` is an __associative_sequence__. 977 978[*Semantics]: Returns the type of an iterator to the first element of `Seq`. 979 980[heading Header] 981 982 #include <boost/fusion/sequence/intrinsic/begin.hpp> 983 #include <boost/fusion/include/begin.hpp> 984 985[heading Example] 986 typedef __vector__<int> vec; 987 typedef __result_of_begin__<vec>::type it; 988 BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__<it>::type, int&>)) 989 990[endsect] 991 992[section end] 993 994[heading Description] 995Returns the result type of __end__. 996 997[heading Synopsis] 998 template<typename Seq> 999 struct end 1000 { 1001 typedef __unspecified__ type; 1002 }; 1003 1004[table Parameters 1005 [[Parameter] [Requirement] [Description]] 1006 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 1007] 1008 1009[heading Expression Semantics] 1010 result_of::end<Seq>::type 1011 1012[*Return type]: 1013 1014* A model of __forward_iterator__ if `seq` is a __forward_sequence__ 1015else, __bidirectional_iterator__ if `seq` is a __bidirectional_sequence__ 1016else, __random_access_iterator__ if `seq` is a __random_access_sequence__. 1017* A model of __associative_iterator__ if `seq` is an __associative_sequence__. 1018 1019[*Semantics]: Returns the type of an iterator one past the end of `Seq`. 1020 1021[heading Header] 1022 1023 #include <boost/fusion/sequence/intrinsic/end.hpp> 1024 #include <boost/fusion/include/end.hpp> 1025 1026[heading Example] 1027 typedef __vector__<int> vec; 1028 typedef __result_of_prior__<__result_of_end__<vec>::type>::type first; 1029 BOOST_MPL_ASSERT((__result_of_equal_to__<first, __result_of_begin__<vec>::type>)) 1030 1031[endsect] 1032 1033[section empty] 1034 1035[heading Description] 1036Returns the result type of __empty__. 1037 1038[heading Synopsis] 1039 template<typename Seq> 1040 struct empty 1041 { 1042 typedef __unspecified__ type; 1043 }; 1044 1045[table Parameters 1046 [[Parameter] [Requirement] [Description]] 1047 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 1048] 1049 1050[heading Expression Semantics] 1051 result_of::empty<Seq>::type 1052 1053[*Return type]: An __mpl_integral_constant__ 1054 1055[*Semantics]: Returns `mpl::true_` if `Seq` has zero elements, `mpl::false_` otherwise. 1056 1057[heading Header] 1058 1059 #include <boost/fusion/sequence/intrinsic/empty.hpp> 1060 #include <boost/fusion/include/empty.hpp> 1061 1062[heading Example] 1063 typedef __vector__<> empty_vec; 1064 typedef __vector__<int,float,char> vec; 1065 1066 BOOST_MPL_ASSERT((__result_of_empty__<empty_vec>)); 1067 BOOST_MPL_ASSERT_NOT((__result_of_empty__<vec>)); 1068 1069[endsect] 1070 1071[section front] 1072 1073[heading Description] 1074Returns the result type of __front__. 1075 1076[heading Synopsis] 1077 template<typename Seq> 1078 struct front 1079 { 1080 typedef __unspecified__ type; 1081 }; 1082 1083[table Parameters 1084 [[Parameter] [Requirement] [Description]] 1085 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 1086] 1087 1088[heading Expression Semantics] 1089 result_of::front<Seq>::type 1090 1091[*Return type]: Any type 1092 1093[*Semantics]: The type returned by dereferencing an iterator to the first element in `Seq`. Equivalent to `__result_of_deref__<__result_of_begin__<Seq>::type>::type`. 1094 1095[heading Header] 1096 1097 #include <boost/fusion/sequence/intrinsic/front.hpp> 1098 #include <boost/fusion/include/front.hpp> 1099 1100[heading Example] 1101 typedef __vector__<int,char> vec; 1102 BOOST_MPL_ASSERT((boost::is_same<__result_of_front__<vec>::type, int&>)); 1103 1104[endsect] 1105 1106[section back] 1107 1108[heading Description] 1109Returns the result type of __back__. 1110 1111[heading Synopsis] 1112 template<typename Seq> 1113 struct back 1114 { 1115 typedef __unspecified__ type; 1116 }; 1117 1118[table Parameters 1119 [[Parameter] [Requirement] [Description]] 1120 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 1121] 1122 1123[heading Expression Semantics] 1124 result_of::back<Seq>::type 1125 1126[*Return type]: Any type 1127 1128[*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__<Seq>::type>::type>::type`. 1129 1130[heading Header] 1131 1132 #include <boost/fusion/sequence/intrinsic/back.hpp> 1133 #include <boost/fusion/include/back.hpp> 1134 1135[heading Example] 1136 typedef __vector__<int,char> vec; 1137 BOOST_MPL_ASSERT((boost::is_same<__result_of_back__<vec>::type, char&>)); 1138 1139[endsect] 1140 1141[section size] 1142 1143[heading Description] 1144Returns the result type of __size__. 1145 1146[heading Synopsis] 1147 template<typename Seq> 1148 struct size 1149 { 1150 typedef __unspecified__ type; 1151 }; 1152 1153[table Parameters 1154 [[Parameter] [Requirement] [Description]] 1155 [[`Seq`][A model of __forward_sequence__][Argument sequence]] 1156] 1157 1158[heading Expression Semantics] 1159 result_of::size<Seq>::type 1160 1161[*Return type]: An __mpl_integral_constant__. 1162 1163[*Semantics]: Returns the number of elements in `Seq`. 1164 1165[heading Header] 1166 1167 #include <boost/fusion/sequence/intrinsic/size.hpp> 1168 #include <boost/fusion/include/size.hpp> 1169 1170[heading Example] 1171 typedef __vector__<int,float,char> vec; 1172 typedef __result_of_size__<vec>::type size_mpl_integral_constant; 1173 BOOST_MPL_ASSERT_RELATION(size_mpl_integral_constant::value, ==, 3); 1174 1175[endsect] 1176 1177[section at] 1178 1179[heading Description] 1180 1181Returns the result type of __at__[footnote __result_of_at__ reflects the 1182actual return type of the function __at__. __sequence__(s) typically return 1183references to its elements via the __at__ function. If you want to get 1184the actual element type, use __result_of_value_at__]. 1185 1186[heading Synopsis] 1187 template< 1188 typename Seq, 1189 typename M> 1190 struct at 1191 { 1192 typedef __unspecified__ type; 1193 }; 1194 1195[table Parameters 1196 [[Parameter] [Requirement] [Description]] 1197 [[`Seq`][A model of __random_access_sequence__][Argument sequence]] 1198 [[`M`][An __mpl_integral_constant__][Index of element]] 1199] 1200 1201[heading Expression Semantics] 1202 result_of::at<Seq, M>::type 1203 1204[*Return type]: Any type. 1205 1206[*Precondition]: `0 <= M::value < __result_of_size__<Seq>::value` (where `Seq` is not __unbounded_sequence__) 1207 1208[*Semantics]: Returns the result type of using __at__ to access the `M`th element of `Seq`. 1209 1210[heading Header] 1211 1212 #include <boost/fusion/sequence/intrinsic/at.hpp> 1213 #include <boost/fusion/include/at.hpp> 1214 1215[heading Example] 1216 typedef __vector__<int,float,char> vec; 1217 BOOST_MPL_ASSERT((boost::is_same<__result_of_at__<vec, boost::mpl::int_<1> >::type, float&>)); 1218 1219[endsect] 1220 1221[section at_c] 1222 1223[heading Description] 1224 1225Returns the result type of __at_c__[footnote __result_of_at_c__ reflects 1226the actual return type of the function __at_c__. __sequence__(s) typically 1227return references to its elements via the __at_c__ function. If you want to 1228get the actual element type, use __result_of_value_at_c__]. 1229 1230[heading Synopsis] 1231 template< 1232 typename Seq, 1233 int N> 1234 struct at_c 1235 { 1236 typedef __unspecified__ type; 1237 }; 1238 1239[table Parameters 1240 [[Parameter] [Requirement] [Description]] 1241 [[`Seq`][A model of __random_access_sequence__][Argument sequence]] 1242 [[`N`][Positive integer index][Index of element]] 1243] 1244 1245[heading Expression Semantics] 1246 result_of::at_c<Seq, N>::type 1247 1248[*Return type]: Any type 1249 1250[*Precondition]: `0 <= N < __result_of_size__<Seq>::value` (where `Seq` is not __unbounded_sequence__) 1251 1252[*Semantics]: Returns the result type of using __at_c__ to access the `N`th element of `Seq`. 1253 1254[heading Header] 1255 1256 #include <boost/fusion/sequence/intrinsic/at.hpp> 1257 #include <boost/fusion/include/at.hpp> 1258 1259[heading Example] 1260 typedef __vector__<int,float,char> vec; 1261 BOOST_MPL_ASSERT((boost::is_same<__result_of_at_c__<vec, 1>::type, float&>)); 1262 1263[endsect] 1264 1265[section value_at] 1266 1267[heading Description] 1268 1269Returns the actual type at a given index from the __sequence__. 1270 1271[heading Synopsis] 1272 template< 1273 typename Seq, 1274 typename M> 1275 struct value_at 1276 { 1277 typedef __unspecified__ type; 1278 }; 1279 1280[table Parameters 1281 [[Parameter] [Requirement] [Description]] 1282 [[`Seq`][A model of __random_access_sequence__][Argument sequence]] 1283 [[`M`][An __mpl_integral_constant__][Index of element]] 1284] 1285 1286[heading Expression Semantics] 1287 result_of::value_at<Seq, M>::type 1288 1289[*Return type]: Any type. 1290 1291[*Semantics]: Returns the actual type at the `M`th element of `Seq`. 1292 1293[heading Header] 1294 1295 #include <boost/fusion/sequence/intrinsic/value_at.hpp> 1296 #include <boost/fusion/include/value_at.hpp> 1297 1298[heading Example] 1299 typedef __vector__<int,float,char> vec; 1300 BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at__<vec, boost::mpl::int_<1> >::type, float>)); 1301 1302[endsect] 1303 1304[section value_at_c] 1305 1306[heading Description] 1307 1308Returns the actual type at a given index from the __sequence__. 1309 1310[heading Synopsis] 1311 template< 1312 typename Seq, 1313 int N> 1314 struct value_at_c 1315 { 1316 typedef __unspecified__ type; 1317 }; 1318 1319[table Parameters 1320 [[Parameter] [Requirement] [Description]] 1321 [[`Seq`][A model of __random_access_sequence__][Argument sequence]] 1322 [[`N`][Positive integer index][Index of element]] 1323] 1324 1325[heading Expression Semantics] 1326 result_of::value_at_c<Seq, N>::type 1327 1328[*Return type]: Any type 1329 1330[*Semantics]: Returns the actual type at the `N`th element of `Seq`. 1331 1332[heading Header] 1333 1334 #include <boost/fusion/sequence/intrinsic/value_at.hpp> 1335 #include <boost/fusion/include/value_at.hpp> 1336 1337[heading Example] 1338 typedef __vector__<int,float,char> vec; 1339 BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at_c__<vec, 1>::type, float>)); 1340 1341[endsect] 1342 1343[section has_key] 1344 1345[heading Description] 1346Returns the result type of __has_key__. 1347 1348[heading Synopsis] 1349 template< 1350 typename Seq, 1351 typename Key> 1352 struct has_key 1353 { 1354 typedef __unspecified__ type; 1355 }; 1356 1357[table Parameters 1358 [[Parameter] [Requirement] [Description]] 1359 [[`Seq`][A model of __associative_sequence__][Argument sequence]] 1360 [[`Key`][Any type][Key type]] 1361] 1362 1363[heading Expression Semantics] 1364 result_of::has_key<Seq, Key>::type 1365 1366[*Return type]: An __mpl_integral_constant__. 1367 1368[*Semantics]: Returns `mpl::true_` if `Seq` contains an element with key type `Key`, returns `mpl::false_` otherwise. 1369 1370[heading Header] 1371 1372 #include <boost/fusion/sequence/intrinsic/has_key.hpp> 1373 #include <boost/fusion/include/has_key.hpp> 1374 1375[heading Example] 1376 typedef __map__<__pair__<int, char>, __pair__<char, char>, __pair__<double, char> > mymap; 1377 BOOST_MPL_ASSERT((__result_of_has_key__<mymap, int>)); 1378 BOOST_MPL_ASSERT_NOT((__result_of_has_key__<mymap, void*>)); 1379 1380[endsect] 1381 1382[section at_key] 1383 1384[heading Description] 1385 1386Returns the result type of __at_key__[footnote __result_of_at_key__ 1387reflects the actual return type of the function __at_key__. __sequence__(s) 1388typically return references to its elements via the __at_key__ function. If 1389you want to get the actual element type, use __result_of_value_at_key__]. 1390 1391[heading Synopsis] 1392 template< 1393 typename Seq, 1394 typename Key> 1395 struct at_key 1396 { 1397 typedef __unspecified__ type; 1398 }; 1399 1400[table Parameters 1401 [[Parameter] [Requirement] [Description]] 1402 [[`Seq`][A model of __associative_sequence__][Argument sequence]] 1403 [[`Key`][Any type][Key type]] 1404] 1405 1406[heading Expression Semantics] 1407 result_of::at_key<Seq, Key>::type 1408 1409[*Return type]: Any type. 1410 1411[*Precondition]: `has_key<Seq, Key>::type::value == true` (where `Seq` is not __unbounded_sequence__) 1412 1413[*Semantics]: Returns the result of using __at_key__ to access the element with key type `Key` in `Seq`. 1414 1415[heading Header] 1416 1417 #include <boost/fusion/sequence/intrinsic/at_key.hpp> 1418 #include <boost/fusion/include/at_key.hpp> 1419 1420[heading Example] 1421 typedef __map__<__pair__<int, char>, __pair__<char, char>, __pair__<double, char> > mymap; 1422 BOOST_MPL_ASSERT((boost::is_same<__result_of_at_key__<mymap, int>::type, char&>)); 1423 1424[endsect] 1425 1426[section value_at_key] 1427 1428[heading Description] 1429Returns the actual element type associated with a Key from the __sequence__. 1430 1431[heading Synopsis] 1432 template< 1433 typename Seq, 1434 typename Key> 1435 struct value_at_key 1436 { 1437 typedef __unspecified__ type; 1438 }; 1439 1440[table Parameters 1441 [[Parameter] [Requirement] [Description]] 1442 [[`Seq`][A model of __associative_sequence__][Argument sequence]] 1443 [[`Key`][Any type][Key type]] 1444] 1445 1446[heading Expression Semantics] 1447 result_of::value_at_key<Seq, Key>::type 1448 1449[*Return type]: Any type. 1450 1451[*Precondition]: `has_key<Seq, Key>::type::value == true` (where `Seq` is not __unbounded_sequence__) 1452 1453[*Semantics]: Returns the actual element type associated with key type 1454`Key` in `Seq`. 1455 1456[heading Header] 1457 1458 #include <boost/fusion/sequence/intrinsic/value_at_key.hpp> 1459 #include <boost/fusion/include/value_at_key.hpp> 1460 1461[heading Example] 1462 typedef __map__<__pair__<int, char>, __pair__<char, char>, __pair__<double, char> > mymap; 1463 BOOST_MPL_ASSERT((boost::is_same<__result_of_value_at_key__<mymap, int>::type, char>)); 1464 1465[endsect] 1466 1467[section swap] 1468 1469[heading Description] 1470Returns the return type of swap. 1471 1472[heading Synopsis] 1473 template<typename Seq1, typename Seq2> 1474 struct swap 1475 { 1476 typedef void type; 1477 }; 1478 1479[table Parameters 1480 [[Parameters] [Requirement] [Description]] 1481 [[`Seq1`, `Seq2`][Models of __forward_sequence__][The sequences being swapped]] 1482] 1483 1484[heading Expression Semantics] 1485 result_of::swap<Seq1, Seq2>::type 1486 1487[*Return type]: `void` iff both of `Seq1` and `Seq2` are sequence. 1488Otherwise, none. 1489 1490[*Semantics]: Returns the return type of __swap__ for 2 sequences of types `Seq1` and `Seq2`. 1491 1492[heading Header] 1493 1494 #include <boost/fusion/sequence/intrinsic/swap.hpp> 1495 #include <boost/fusion/include/swap.hpp> 1496 1497[endsect] 1498 1499[endsect] 1500 1501[endsect] 1502 1503[section Operator] 1504 1505These operators, like the __algorithms__, work generically on all Fusion 1506sequences. All conforming Fusion sequences automatically get these 1507operators for free. 1508 1509[section I/O] 1510 1511The I/O operators: `<<` and `>>` work generically on all Fusion 1512sequences. The I/O operators are overloaded in namespace `boost::fusion` 1513[footnote __sequence__(s) and __views__ residing in different namespaces 1514will have to either provide their own I/O operators (possibly forwarding 1515to fusion's I/O operators) or hoist fusion's I/O operators (using 1516declaration), in their own namespaces for proper argument dependent 1517lookup.] 1518 1519The `operator<<` has been overloaded for generic output streams such 1520that __sequence__(s) are output by recursively calling `operator<<` for 1521each element. Analogously, the global `operator>>` has been overloaded 1522to extract __sequence__(s) from generic input streams by recursively 1523calling `operator>>` for each element. 1524 1525Please note that, to display your adapted types via fusion IO system, 1526corresponding overloaded operators should be introduced to same namespace 1527of the type. 1528 1529 namespace your_awesome_library 1530 { 1531 using boost::fusion::operators::operator>>; // for input 1532 using boost::fusion::operators::operator<<; // for output 1533 ... 1534 1535The default delimiter between the elements is space, and the __sequence__ 1536is enclosed in parenthesis. For Example: 1537 1538 __vector__<float, int, std::string> a(1.0f, 2, std::string("Howdy folks!"); 1539 cout << a; 1540 1541outputs the __vector__ as: (1.0 2 Howdy folks!) 1542 1543The library defines three manipulators for changing the default behavior: 1544 1545[variablelist Manipulators 1546 [[`tuple_open(arg)`] [Defines the character that is output before the first element.]] 1547 [[`tuple_close(arg)`] [Defines the character that is output after the last element.]] 1548 [[`tuple_delimiter(arg)`] [Defines the delimiter character between elements.]] 1549] 1550 1551The argument to `tuple_open`, `tuple_close` and `tuple_delimiter` may be a 1552`char`, `wchar_t`, a C-string, or a wide C-string. 1553 1554Example: 1555 1556 std::cout << tuple_open('[') << tuple_close(']') << tuple_delimiter(", ") << a; 1557 1558outputs the same __vector__, `a` as: [1.0, 2, Howdy folks!] 1559 1560The same manipulators work with `operator>>` and `istream` as well. Suppose 1561the `std::cin` stream contains the following data: 1562 1563 (1 2 3) [4:5] 1564 1565The code: 1566 1567 __vector__<int, int, int> i; 1568 __vector__<int, int> j; 1569 1570 std::cin >> i; 1571 std::cin >> tuple_open('[') >> tuple_close(']') >> tuple_delimiter(':'); 1572 std::cin >> j; 1573 1574reads the data into the __vector__(s) `i` and `j`. 1575 1576Note that extracting __sequence__(s) with `std::string` or C-style string 1577elements does not generally work, since the streamed __sequence__ 1578representation may not be unambiguously parseable. 1579 1580[heading Header] 1581 1582 #include <boost/fusion/sequence/io.hpp> 1583 #include <boost/fusion/include/io.hpp> 1584 1585[section in] 1586 1587[heading Description] 1588 1589Read a __sequence__ from an input stream. 1590 1591[heading Synopsis] 1592 1593 template <typename IStream, typename Sequence> 1594 IStream& 1595 operator>>(IStream& is, Sequence& seq); 1596 1597[heading Parameters] 1598 1599[table 1600 [[Parameter] [Requirement] [Description]] 1601 [[is] [An input stream.] [Stream to extract information from.]] 1602 [[seq] [A __sequence__.] [The sequence to read.]] 1603] 1604 1605[heading Expression Semantics] 1606 1607 is >> seq 1608 1609[*Return type]: IStream& 1610 1611[*Semantics]: For each element, `e`, in sequence, `seq`, call `is >> e`. 1612 1613[heading Header] 1614 1615 #include <boost/fusion/sequence/io/in.hpp> 1616 #include <boost/fusion/include/in.hpp> 1617 1618[heading Example] 1619 1620 __vector__<int, std::string, char> v; 1621 std::cin >> v; 1622 1623[endsect] 1624 1625[section out] 1626 1627[heading Description] 1628 1629Write a __sequence__ to an output stream. 1630 1631[heading Synopsis] 1632 1633 template <typename OStream, typename Sequence> 1634 OStream& 1635 operator<<(OStream& os, Sequence& seq); 1636 1637[heading Parameters] 1638 1639[table 1640 [[Parameter] [Requirement] [Description]] 1641 [[os] [An output stream.] [Stream to write information to.]] 1642 [[seq] [A __sequence__.] [The sequence to write.]] 1643] 1644 1645[heading Expression Semantics] 1646 1647 os << seq 1648 1649[*Return type]: OStream& 1650 1651[*Semantics]: For each element, `e`, in sequence, `seq`, call `os << e`. 1652 1653[heading Header] 1654 1655 #include <boost/fusion/sequence/io/out.hpp> 1656 #include <boost/fusion/include/out.hpp> 1657 1658[heading Example] 1659 1660 std::cout << __make_vector__(123, "Hello", 'x') << std::endl; 1661 1662[endsect] 1663 1664[endsect] 1665 1666[section Comparison] 1667 1668The Comparison operators: `==`, `!=`, `<`, `<=`, `>=` and `>=` work 1669generically on all Fusion sequences. Comparison operators are "short- 1670circuited": elementary comparisons start from the first elements and are 1671performed only until the result is clear. 1672 1673[heading Header] 1674 1675 #include <boost/fusion/sequence/comparison.hpp> 1676 #include <boost/fusion/include/comparison.hpp> 1677 1678[section equal] 1679 1680[heading Description] 1681 1682Compare two sequences for equality. 1683 1684[heading Synopsis] 1685 1686 template <typename Seq1, typename Seq2> 1687 bool 1688 operator==(Seq1 const& a, Seq2 const& b); 1689 1690[heading Parameters] 1691 1692[table 1693 [[Parameter] [Requirement] [Description]] 1694 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1695] 1696 1697[heading Expression Semantics] 1698 1699 a == b 1700 1701[*Return type]: `bool` 1702 1703[*Requirements]: 1704 1705For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1706sequence `b`, `a == b` is a valid expression returning a type that is 1707convertible to bool. 1708 1709An attempt to compare two Sequences of different lengths results in a 1710compile time error. 1711 1712[*Semantics]: 1713 1714For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1715sequence `b`, `e1 == e2` returns true. For any 2 zero length __sequence__(s), 1716e and f, e == f returns true. 1717 1718[heading Header] 1719 1720 #include <boost/fusion/sequence/comparison/equal_to.hpp> 1721 #include <boost/fusion/include/equal_to.hpp> 1722 1723[heading Example] 1724 1725 __vector__<int, char> v1(5, 'a'); 1726 __vector__<int, char> v2(5, 'a'); 1727 assert(v1 == v2); 1728 1729[endsect] 1730 1731[section not equal] 1732 1733Compare two sequences for inequality. 1734 1735[heading Synopsis] 1736 1737 template <typename Seq1, typename Seq2> 1738 bool 1739 operator!=(Seq1 const& a, Seq2 const& b); 1740 1741[heading Parameters] 1742 1743[table 1744 [[Parameter] [Requirement] [Description]] 1745 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1746] 1747 1748[heading Expression Semantics] 1749 1750 a != b 1751 1752[*Return type]: `bool` 1753 1754[*Requirements]: 1755 1756For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1757sequence `b`, `a == b` is a valid expression returning a type that is 1758convertible to bool. 1759 1760An attempt to compare two Sequences of different lengths results in a 1761compile time error. 1762 1763[*Semantics]: 1764 1765Returns !(a == b). 1766 1767[heading Header] 1768 1769 #include <boost/fusion/sequence/comparison/not_equal_to.hpp> 1770 #include <boost/fusion/include/not_equal_to.hpp> 1771 1772[heading Example] 1773 1774 __vector__<int, char> v3(5, 'b'); 1775 __vector__<int, char> t4(2, 'a'); 1776 assert(v1 != v3); 1777 assert(v1 != t4); 1778 assert(!(v1 != v2)); 1779 1780[endsect] 1781 1782[section less than] 1783 1784Lexicographically compare two sequences. 1785 1786[heading Synopsis] 1787 1788 template <typename Seq1, typename Seq2> 1789 bool 1790 operator<(Seq1 const& a, Seq2 const& b); 1791 1792[heading Parameters] 1793 1794[table 1795 [[Parameter] [Requirement] [Description]] 1796 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1797] 1798 1799[heading Expression Semantics] 1800 1801 a < b 1802 1803[*Return type]: `bool` 1804 1805[*Requirements]: 1806 1807For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1808sequence `b`, `a < b` is a valid expression returning a type that is 1809convertible to bool. 1810 1811An attempt to compare two Sequences of different lengths results in a 1812compile time error. 1813 1814[*Semantics]: Returns the lexicographical comparison of between `a` and `b`. 1815 1816[heading Header] 1817 1818 #include <boost/fusion/sequence/comparison/less.hpp> 1819 #include <boost/fusion/include/less.hpp> 1820 1821[heading Example] 1822 1823 __vector__<int, float> v1(4, 3.3f); 1824 __vector__<short, float> v2(5, 3.3f); 1825 __vector__<long, double> v3(5, 4.4); 1826 assert(v1 < v2); 1827 assert(v2 < v3); 1828 1829[endsect] 1830 1831[section less than equal] 1832 1833Lexicographically compare two sequences. 1834 1835[heading Synopsis] 1836 1837 template <typename Seq1, typename Seq2> 1838 bool 1839 operator<=(Seq1 const& a, Seq2 const& b); 1840 1841[heading Parameters] 1842 1843[table 1844 [[Parameter] [Requirement] [Description]] 1845 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1846] 1847 1848[heading Expression Semantics] 1849 1850 a <= b 1851 1852[*Return type]: `bool` 1853 1854[*Requirements]: 1855 1856For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1857sequence `b`, `a < b` is a valid expression returning a type that is 1858convertible to bool. 1859 1860An attempt to compare two Sequences of different lengths results in a 1861compile time error. 1862 1863[*Semantics]: Returns !(b < a). 1864 1865[heading Header] 1866 1867 #include <boost/fusion/sequence/comparison/less_equal.hpp> 1868 #include <boost/fusion/include/less_equal.hpp> 1869 1870[heading Example] 1871 1872 __vector__<int, float> v1(4, 3.3f); 1873 __vector__<short, float> v2(5, 3.3f); 1874 __vector__<long, double> v3(5, 4.4); 1875 assert(v1 <= v2); 1876 assert(v2 <= v3); 1877 1878[endsect] 1879 1880[section greater than] 1881 1882Lexicographically compare two sequences. 1883 1884[heading Synopsis] 1885 1886 template <typename Seq1, typename Seq2> 1887 bool 1888 operator>(Seq1 const& a, Seq2 const& b); 1889 1890[heading Parameters] 1891 1892[table 1893 [[Parameter] [Requirement] [Description]] 1894 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1895] 1896 1897[heading Expression Semantics] 1898 1899 a > b 1900 1901[*Return type]: `bool` 1902 1903[*Requirements]: 1904 1905For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1906sequence `b`, `a < b` is a valid expression returning a type that is 1907convertible to bool. 1908 1909An attempt to compare two Sequences of different lengths results in a 1910compile time error. 1911 1912[*Semantics]: Returns b < a. 1913 1914[heading Header] 1915 1916 #include <boost/fusion/sequence/comparison/less_equal.hpp> 1917 #include <boost/fusion/include/less_equal.hpp> 1918 1919[heading Example] 1920 1921 __vector__<int, float> v1(4, 3.3f); 1922 __vector__<short, float> v2(5, 3.3f); 1923 __vector__<long, double> v3(5, 4.4); 1924 assert(v2 > v1); 1925 assert(v3 > v2); 1926 1927[endsect] 1928 1929[section greater than equal] 1930 1931Lexicographically compare two sequences. 1932 1933[heading Synopsis] 1934 1935 template <typename Seq1, typename Seq2> 1936 bool 1937 operator>=(Seq1 const& a, Seq2 const& b); 1938 1939[heading Parameters] 1940 1941[table 1942 [[Parameter] [Requirement] [Description]] 1943 [[`a, b`] [Instances of __sequence__] [__sequence__(s) to compare]] 1944] 1945 1946[heading Expression Semantics] 1947 1948 a >= b 1949 1950[*Return type]: `bool` 1951 1952[*Requirements]: 1953 1954For each element, `e1`, in sequence `a`, and for each element, `e2`, in 1955sequence `b`, `a < b` is a valid expression returning a type that is 1956convertible to bool. 1957 1958An attempt to compare two Sequences of different lengths results in a 1959compile time error. 1960 1961[*Semantics]: Returns !(a < b). 1962 1963[heading Header] 1964 1965 #include <boost/fusion/sequence/comparison/greater_equal.hpp> 1966 #include <boost/fusion/include/greater_equal.hpp> 1967 1968[heading Example] 1969 1970 __vector__<int, float> v1(4, 3.3f); 1971 __vector__<short, float> v2(5, 3.3f); 1972 __vector__<long, double> v3(5, 4.4); 1973 assert(v2 >= v1); 1974 assert(v3 >= v2); 1975 1976[endsect] 1977 1978[endsect] 1979 1980[section Hashing] 1981 1982Automatically create a `boost::hash` conforming `hash_value` function. 1983 1984[heading Synopsis] 1985 1986 template <typename Seq> 1987 std::size_t 1988 hash_value(Seq const& seq); 1989 1990[heading Parameters] 1991 1992[table 1993 [[Parameter] [Requirement] [Description]] 1994 [[`seq`] [Instance of __sequence__] [__sequence__ to compute hash value of]] 1995] 1996 1997[*Return type]: `std::size_t` 1998 1999[*Requirements]: 2000 2001For each element `e` in sequence `seq`, `hash_value(seq)` is a valid expression 2002returning a type that is convertible to `std::size_t`. 2003 2004[*Semantics]: Returns a combined hash value for all elements of `seq`. 2005 2006[heading Header] 2007 2008 #include <boost/fusion/sequence/hash.hpp> 2009 #include <boost/fusion/include/hash.hpp> 2010 2011[heading Example] 2012 2013 #include <boost/fusion/include/equal_to.hpp> 2014 #include <boost/fusion/include/hash.hpp> 2015 #include <boost/fusion/include/vector.hpp> 2016 #include <boost/unordered_map.hpp> 2017 2018 void foo() 2019 { 2020 typedef boost::fusion::vector<int, std::string, char> Vec; 2021 const Vec v = {42, "Hello World", 't'}; 2022 // Compute a hash value directly. 2023 std::cout << "hash_value(v) = " << boost::fusion::hash_value(v) << '\n'; 2024 // Or use it to create an unordered_map. 2025 boost::unordered_map<Vec, bool> map; 2026 map[v] = true; 2027 assert(map.size() == 1 && map.count(v) == 1); 2028 } 2029 2030[heading Example] 2031 2032 #include <boost/fusion/include/define_struct.hpp> 2033 #include <boost/fusion/include/equal_to.hpp> 2034 #include <boost/fusion/include/hash.hpp> 2035 #include <boost/unordered_set.hpp> 2036 2037 // We would like to define a struct that we can form unordered_sets of. 2038 BOOST_FUSION_DEFINE_STRUCT( 2039 (demo), Key, 2040 (bool, b) 2041 (std::string, s) 2042 (int, i) 2043 ) 2044 2045 namespace demo { 2046 // Make operator== and hash_value ADL accessible. 2047 using boost::fusion::operator==; 2048 using boost::fusion::hash_value; 2049 typedef boost::unordered_set<demo::Key> Set; 2050 } 2051 2052 void foo() 2053 { 2054 demo::Set set; 2055 demo::Key key; 2056 assert(set.count(key) == 0); 2057 } 2058 2059[heading See also] 2060 2061__boost_func_hash__ 2062 2063[endsect] 2064 2065[endsect] 2066 2067[endsect] 2068 2069