ceph/src/boost/libs/fusion/doc/iterator.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 Iterator]
  10
  11 Like __mpl__ and __stl__, iterators are a fundamental concept in Fusion.
  12 As with __mpl__ and __stl__ iterators describe positions, and
  13 provide access to data within an underlying __sequence__.
  14
  15 [heading Header]
  16     #include <boost/fusion/iterator.hpp>
  17     #include <boost/fusion/include/iterator.hpp>
  18
  19 [section Concepts]
  20
  21 Fusion iterators are divided into different traversal categories.
  22 __forward_iterator__ is the most basic concept. __bidirectional_iterator__
  23 is a refinement of __forward_iterator__. __random_access_iterator__ is a
  24 refinement of __bidirectional_iterator__. __associative_iterator__ is a
  25 refinement of __forward_iterator__, __bidirectional_iterator__ or
  26 __random_access_iterator__.
  27
  28 [section Forward Iterator]
  29
  30 [heading Description]
  31 A Forward Iterator traverses a __sequence__ allowing movement in only one direction through
  32 it's elements, one element at a time.
  33
  34 [variablelist Notation
  35     [[`i`, `j`]         [Forward Iterators]]
  36     [[`I`, `J`]         [Forward Iterator types]]
  37     [[`M`]              [An __mpl__ integral constant]]
  38     [[`N`]              [An integral constant]]
  39 ]
  40
  41 [heading Expression requirements]
  42 A type models Forward Iterator if, in addition to being CopyConstructable,
  43 the following expressions are valid:
  44
  45 [table
  46     [[Expression]        [Return type]                [Runtime Complexity]]
  47     [[`__next__(i)`]         [__forward_iterator__]       [Constant]]
  48     [[`i == j`]          [Convertible to bool]        [Constant]]
  49     [[`i != j`]          [Convertible to bool]        [Constant]]
  50     [[`__advance_c__<N>(i)`] [__forward_iterator__]       [Constant]]
  51     [[`__advance__<M>(i)`] [__forward_iterator__]       [Constant]]
  52     [[`__distance__(i, j)`]  [`__result_of_distance__<I, J>::type`][Constant]]
  53     [[`__deref__(i)`]        [`__result_of_deref__<I>::type`] [Constant]]
  54     [[`*i`]              [`__result_of_deref__<I>::type`] [Constant]]
  55 ]
  56
  57 [heading Meta Expressions]
  58 [table
  59     [[Expression]                       [Compile Time Complexity]]
  60     [[`__result_of_next__<I>::type`]            [Amortized constant time]]
  61     [[`__result_of_equal_to__<I, J>::type`]      [Amortized constant time]]
  62     [[`__result_of_advance_c__<I, N>::type`]     [Linear]]
  63     [[`__result_of_advance__<I ,M>::type`]       [Linear]]
  64     [[`__result_of_distance__<I ,J>::type`]      [Linear]]
  65     [[`__result_of_deref__<I>::type`]       [Amortized constant time]]
  66     [[`__result_of_value_of__<I>::type`]    [Amortized constant time]]
  67 ]
  68
  69 [heading Expression Semantics]
  70 [table
  71     [[Expression]              [Semantics]]
  72     [[`__next__(i)`]               [An iterator to the element following `i`]]
  73     [[`i == j`]                [Iterator equality comparison]]
  74     [[`i != j`]                [Iterator inequality comparison]]
  75     [[`__advance_c__<N>(i)`]       [An iterator n elements after `i` in the sequence]]
  76     [[`__advance__<M>(i)`]         [Equivalent to `advance_c<M::value>(i)`]]
  77     [[`__distance__(i, j)`]        [The number of elements between `i` and `j`]]
  78     [[`__deref__(i)`]    [The element at position`i`]]
  79     [[`*i`]          [Equivalent to `deref(i)`]]
  80 ]
  81
  82 [heading Invariants]
  83 The following invariants always hold:
  84
  85 * `!(i == j) == (i != j)`
  86 * `__next__(i) == __advance_c__<1>(i)`
  87 * `__distance__(i, __advance_c__<N>(i)) == N`
  88 * Using `__next__` to traverse the sequence will never return to a previously seen position
  89 * `__deref__(i)` is equivalent to `*i`
  90 * If `i == j` then `*i` is equivalent to `*j`
  91
  92 [heading Models]
  93 * __std_pair__ iterator
  94 * __boost_array__ iterator
  95 * __vector__ iterator
  96 * __cons__ iterator
  97 * __list__ iterator
  98 * __set__ iterator
  99 * __map__ iterator
 100 * __single_view__ iterator
 101 * __filter_view__ iterator
 102 * __iterator_range__ iterator
 103 * __joint_view__ iterator
 104 * __transform_view__ iterator
 105 * __reverse_view__ iterator
 106
 107 [endsect]
 108
 109 [section Bidirectional Iterator]
 110 [heading Description]
 111 A Bidirectional Iterator traverses a __sequence__ allowing movement in either direction one
 112 element at a time.
 113
 114 [variablelist Notation
 115     [[`i`]         [A Bidirectional Iterator]]
 116     [[`I`]         [A Bidirectional Iterator type]]
 117     [[`M`]         [An __mpl__ integral constant]]
 118     [[`N`]         [An integral constant]]
 119 ]
 120
 121 [heading Refinement of]
 122 __forward_iterator__
 123
 124 [heading Expression requirements]
 125 In addition to the requirements defined in __forward_iterator__,
 126 the following expressions must be valid:
 127
 128 [table
 129     [[Expression]        [Return type]                [Runtime Complexity]]
 130     [[`__next__(i)`]         [__bidirectional_iterator__] [Constant]]
 131     [[`__prior__(i)`]        [__bidirectional_iterator__] [Constant]]
 132     [[`__advance_c__<N>(i)`] [__bidirectional_iterator__] [Constant]]
 133     [[`__advance__<M>(i)`]   [__bidirectional_iterator__] [Constant]]
 134 ]
 135
 136 [heading Meta Expressions]
 137 [table
 138     [[Expression]              [Compile Time Complexity]]
 139     [[`__result_of_prior__<I>::type`]  [Amortized constant time]]
 140 ]
 141
 142 [heading Expression Semantics]
 143 The semantics of an expression are defined only where they differ from, or are not defined
 144 in __forward_iterator__
 145
 146 [table
 147     [[Expression]    [Semantics]]
 148     [[`__prior__(i)`]     [An iterator to the element preceding `i`]]
 149 ]
 150
 151 [heading Invariants]
 152 In addition to the invariants of __forward_iterator__,
 153 the following invariants always hold:
 154
 155 * `__prior__(__next__(i)) == i && __prior__(__next__(i)) == __next__(__prior__(i))`
 156 * `__prior__(i) == __advance_c__<-1>(i)`
 157 * Using `__prior__` to traverse a sequence will never return a previously seen position
 158
 159 [heading Models]
 160 * __std_pair__ iterator
 161 * __boost_array__ iterator
 162 * __vector__ iterator
 163 * __map__ iterator
 164 * __single_view__ iterator
 165 * __iterator_range__ (where adapted sequence is a __bidirectional_sequence__)
 166 * __transform_view__ (where adapted sequence is a __bidirectional_sequence__)
 167 * __reverse_view__
 168
 169 [endsect]
 170
 171 [section Random Access Iterator]
 172 [heading Description]
 173 A Random Access Iterator traverses a __sequence__ moving in either direction,
 174 permitting efficient arbitrary distance movements back and forward through the
 175 sequence.
 176
 177 [variablelist Notation
 178     [[`i`, `j`]         [Random Access Iterators]]
 179     [[`I`, `J`]         [Random Access Iterator types]]
 180     [[`M`]              [An __mpl__ integral constant]]
 181     [[`N`]              [An integral constant]]
 182 ]
 183
 184 [heading Refinement of]
 185 __bidirectional_iterator__
 186
 187 [heading Expression requirements]
 188 In addition to the requirements defined in __bidirectional_iterator__,
 189 the following expressions must be valid:
 190
 191 [table
 192     [[Expression]        [Return type]                [Runtime Complexity]]
 193     [[`__next__(i)`]         [__random_access_iterator__]       [Constant]]
 194     [[`__prior__(i)`]        [__random_access_iterator__]       [Constant]]
 195     [[`__advance_c__<N>(i)`] [__random_access_iterator__]       [Constant]]
 196     [[`__advance__<M>(i)`]   [__random_access_iterator__]       [Constant]]
 197 ]
 198
 199 [heading Meta Expressions]
 200 [table
 201     [[Expression]                       [Compile Time Complexity]]
 202     [[`__result_of_advance_c__<I, N>::type`]  [Amortized constant time]]
 203     [[`__result_of_advance__<I, M>::type`]    [Amortized constant time]]
 204     [[`__result_of_distance__<I ,J>::type`]   [Amortized constant time]]
 205 ]
 206
 207 [heading Models]
 208 * __vector__ iterator
 209 * __map__ iterator
 210 * __std_pair__ iterator
 211 * __boost_array__ iterator
 212 * __single_view__ iterator
 213 * __iterator_range__ iterator (where adapted sequence is a __random_access_sequence__)
 214 * __transform_view__ iterator (where adapted sequence is a __random_access_sequence__)
 215 * __reverse_view__ iterator (where adapted sequence is a __random_access_sequence__)
 216
 217 [endsect]
 218
 219 [section Associative Iterator]
 220 [heading Description]
 221 An Associative Iterator provides additional semantics to obtain the properties
 222 of the element of an associative forward, bidirectional or random access sequence.
 223
 224 [variablelist Notation
 225     [[`i`]         [Associative Iterator]]
 226     [[`I`]         [Associative Iterator type]]
 227 ]
 228
 229 [heading Refinement of]
 230 __forward_iterator__, __bidirectional_iterator__ or __random_access_iterator__
 231
 232 [heading Expression requirements]
 233 In addition to the requirements defined in __forward_iterator__,
 234 __bidirectional_iterator__ or __random_access_iterator__ the following
 235 expressions must be valid:
 236
 237 [table
 238     [[Expression]        [Return type]                [Runtime Complexity]]
 239     [[`__deref_data__(i)`][`__result_of_deref_data__<I>::type`][Constant]]
 240 ]
 241
 242 [heading Meta Expressions]
 243 [table
 244     [[Expression]                       [Compile Time Complexity]]
 245     [[`__result_of_key_of__<I>::type`][Amortized constant time]]
 246     [[`__result_of_value_of_data__<I>::type`][Amortized constant time]]
 247     [[`__result_of_deref_data__<I>::type`][Amortized constant time]]
 248 ]
 249
 250 [heading Models]
 251 * __map__ iterator
 252 * __set__ iterator
 253 * __filter_view__ iterator (where adapted sequence is an __associative_sequence__ and a __forward_sequence__)
 254 * __iterator_range__ iterator (where adapted iterators are __associative_iterator__\ s)
 255 * __joint_view__ iterator (where adapted sequences are __associative_sequence__\ s and __forward_sequence__\ s)
 256 * __reverse_view__ iterator (where adapted sequence is an __associative_sequence__ and a __bidirectional_sequence__)
 257
 258 [endsect]
 259
 260 [section Unbounded Iterator]
 261
 262 [warning In this release, __unbounded_iterator__ concept has no effect. It's reserved for future release.]
 263
 264 [endsect]
 265
 266 [endsect]
 267
 268 [section Functions]
 269 Fusion provides functions for manipulating iterators, analogous to the similar functions
 270 from the __mpl__ library.
 271
 272 [section deref]
 273
 274 [heading Description]
 275 Deferences an iterator.
 276
 277 [heading Synopsis]
 278     template<
 279         typename I
 280         >
 281     typename __result_of_deref__<I>::type deref(I const& i);
 282
 283 [table Parameters
 284     [[Parameter]      [Requirement]    [Description]]
 285     [[`i`]            [Model of __forward_iterator__] [Operation's argument]]
 286 ]
 287
 288 [heading Expression Semantics]
 289     __deref__(i);
 290
 291 [*Return type]: `__result_of_deref__<I>::type`
 292
 293 [*Semantics]: Dereferences the iterator `i`.
 294
 295 [heading Header]
 296     #include <boost/fusion/iterator/deref.hpp>
 297     #include <boost/fusion/include/deref.hpp>
 298
 299 [heading Example]
 300     typedef __vector__<int,int&> vec;
 301
 302     int i(0);
 303     vec v(1,i);
 304     assert(__deref__(__begin__(v)) == 1);
 305     assert(__deref__(__next__(__begin__(v))) == 0);
 306     assert(&(__deref__(__next__(__begin__(v)))) == &i);
 307
 308 [endsect]
 309
 310 [section next]
 311
 312 [heading Description]
 313 Moves an iterator 1 position forwards.
 314
 315 [heading Synopsis]
 316     template<
 317         typename I
 318         >
 319     typename __result_of_next__<I>::type next(I const& i);
 320
 321 [table Parameters
 322     [[Parameter]    [Requirement]   [Description]]
 323     [[`i`]          [Model of __forward_iterator__] [Operation's argument]]
 324 ]
 325
 326 [heading Expression Semantics]
 327     next(i);
 328
 329 [*Return type]: A model of the same iterator concept as `i`.
 330
 331 [*Semantics]: Returns an iterator to the next element after `i`.
 332
 333 [heading Header]
 334     #include <boost/fusion/iterator/next.hpp>
 335     #include <boost/fusion/include/next.hpp>
 336
 337 [heading Example]
 338     typedef __vector__<int,int,int> vec;
 339
 340     vec v(1,2,3);
 341     assert(__deref__(__begin__(v)) == 1);
 342     assert(__deref__(__next__(__begin__(v))) == 2);
 343     assert(__deref__(__next__(__next__(__begin__(v)))) == 3);
 344
 345 [endsect]
 346
 347 [section prior]
 348
 349 [heading Description]
 350 Moves an iterator 1 position backwards.
 351
 352 [heading Synopsis]
 353     template<
 354         typename I
 355         >
 356     typename __result_of_prior__<I>::type prior(I const& i);
 357
 358 [table Parameters
 359     [[Parameter]    [Requirement]   [Description]]
 360     [[`i`]          [Model of __bidirectional_iterator__] [Operation's argument]]
 361 ]
 362
 363 [heading Expression Semantics]
 364     __prior__(i);
 365
 366 [*Return type]: A model of the same iterator concept as `i`.
 367
 368 [*Semantics]: Returns an iterator to the element prior to `i`.
 369
 370 [heading Header]
 371     #include <boost/fusion/iterator/prior.hpp>
 372     #include <boost/fusion/include/prior.hpp>
 373
 374 [heading Example]
 375     typedef __vector__<int,int> vec;
 376
 377     vec v(1,2);
 378     assert(__deref__(__next__(__begin__(v))) == 2);
 379     assert(__deref__(__prior__(__next__(__begin__(v)))) == 1);
 380
 381 [endsect]
 382
 383 [section distance]
 384
 385 [heading Description]
 386 Returns the distance between 2 iterators.
 387
 388 [heading Synopsis]
 389     template<
 390         typename I,
 391         typename J
 392         >
 393     typename __result_of_distance__<I, J>::type distance(I const& i, J const& j);
 394
 395 [table Parameters
 396     [[Parameter]    [Requirement]   [Description]]
 397     [[`i`, `j`]          [Models of __forward_iterator__ into the same sequence] [The start and end points of the distance to be measured]]
 398 ]
 399
 400 [heading Expression Semantics]
 401     __distance__(i,j);
 402
 403 [*Return type]: `int`
 404
 405 [*Semantics]: Returns the distance between iterators `i` and `j`.
 406
 407 [heading Header]
 408     #include <boost/fusion/iterator/distance.hpp>
 409     #include <boost/fusion/include/distance.hpp>
 410
 411 [heading Example]
 412     typedef __vector__<int,int,int> vec;
 413
 414     vec v(1,2,3);
 415     assert(__distance__(__begin__(v), __next__(__next__(__begin__(v)))) == 2);
 416
 417 [endsect]
 418
 419 [section advance]
 420
 421 [heading Description]
 422 Moves an iterator by a specified distance.
 423
 424 [heading Synopsis]
 425     template<
 426         typename M,
 427         typename I
 428         >
 429     typename __result_of_advance__<I, M>::type advance(I const& i);
 430
 431 [table Parameters
 432     [[Parameter]    [Requirement]   [Description]]
 433     [[`i`]          [Model of __forward_iterator__] [Iterator to move relative to]]
 434     [[`M`]          [An __mpl_integral_constant__] [Number of positions to move]]
 435 ]
 436
 437 [heading Expression Semantics]
 438     __advance__<M>(i);
 439
 440 [*Return type]: A model of the same iterator concept as `i`.
 441
 442 [*Semantics]: Returns an iterator to the element `M` positions from `i`. If `i` is a __bidirectional_iterator__ then `M` may be negative.
 443
 444 [heading Header]
 445     #include <boost/fusion/iterator/advance.hpp>
 446     #include <boost/fusion/include/advance.hpp>
 447
 448 [heading Example]
 449     typedef __vector__<int,int,int> vec;
 450
 451     vec v(1,2,3);
 452     assert(__deref__(__advance__<mpl::int_<2> >(__begin__(v))) == 3);
 453
 454 [endsect]
 455
 456 [section advance_c]
 457
 458 [heading Description]
 459 Moves an iterator by a specified distance.
 460
 461 [heading Synopsis]
 462     template<
 463         int N,
 464         typename I
 465         >
 466     typename __result_of_advance_c__<I, N>::type advance_c(I const& i);
 467
 468 [table Parameters
 469     [[Parameter]    [Requirement]   [Description]]
 470     [[`i`]          [Model of __forward_iterator__] [Iterator to move relative to]]
 471     [[`N`]          [Integer constant] [Number of positions to move]]
 472 ]
 473
 474 [heading Expression Semantics]
 475     __advance_c__<N>(i);
 476
 477 [*Return type]: A model of the same iterator concept as `i`.
 478
 479 [*Semantics]: Returns an iterator to the element `N` positions from `i`. If `i` is a __bidirectional_iterator__ then `N` may be negative.
 480
 481 [heading Header]
 482     #include <boost/fusion/iterator/advance.hpp>
 483     #include <boost/fusion/include/advance.hpp>
 484
 485 [heading Example]
 486     typedef __vector__<int,int,int> vec;
 487
 488     vec v(1,2,3);
 489     assert(__deref__(__advance_c__<2>(__begin__(v))) == 3);
 490
 491 [endsect]
 492
 493 [section deref_data]
 494
 495 [heading Description]
 496 Deferences the data property associated with the element referenced by an associative iterator.
 497
 498 [heading Synopsis]
 499     template<
 500         typename I
 501         >
 502     typename __result_of_deref_data__<I>::type deref_data(I const& i);
 503
 504 [table Parameters
 505     [[Parameter]      [Requirement]    [Description]]
 506     [[`i`]            [Model of __associative_iterator__] [Operation's argument]]
 507 ]
 508
 509 [heading Expression Semantics]
 510     __deref_data__(i);
 511
 512 [*Return type]: `__result_of_deref_data__<I>::type`
 513
 514 [*Semantics]: Dereferences the data property associated with the element referenced by an associative iterator `i`.
 515
 516 [heading Header]
 517     #include <boost/fusion/iterator/deref_data.hpp>
 518     #include <boost/fusion/include/deref_data.hpp>
 519
 520 [heading Example]
 521     typedef __map__<__pair__<float, int&> > map;
 522
 523     int i(0);
 524     map m(1.0f,i);
 525     assert(__deref_data__(__begin__(m)) == 0);
 526     assert(&(__deref_data__(__begin__(m))) == &i);
 527
 528 [endsect]
 529
 530 [endsect]
 531
 532 [section Operator]
 533
 534 Overloaded operators are provided to provide a more natural syntax for dereferencing iterators, and comparing them for equality.
 535
 536 [section:operator_unary_star Operator *]
 537
 538 [heading Description]
 539 Dereferences an iterator.
 540
 541 [heading Synopsis]
 542     template<
 543         typename I
 544         >
 545     typename __result_of_deref__<I>::type operator*(I const& i);
 546
 547 [table Parameters
 548     [[Parameter]      [Requirement]    [Description]]
 549     [[`i`]            [Model of __forward_iterator__] [Operation's argument]]
 550 ]
 551
 552 [heading Expression Semantics]
 553     *i
 554
 555 [*Return type]: Equivalent to the return type of `__deref__(i)`.
 556
 557 [*Semantics]: Equivalent to `__deref__(i)`.
 558
 559 [heading Header]
 560     #include <boost/fusion/iterator/deref.hpp>
 561     #include <boost/fusion/include/deref.hpp>
 562
 563 [heading Example]
 564     typedef __vector__<int,int&> vec;
 565
 566     int i(0);
 567     vec v(1,i);
 568     assert(*__begin__(v) == 1);
 569     assert(*__next__(__begin__(v)) == 0);
 570     assert(&(*__next__(__begin__(v))) == &i);
 571
 572 [endsect]
 573
 574 [section:operator_equality Operator ==]
 575
 576 [heading Description]
 577 Compares 2 iterators for equality.
 578
 579 [heading Synopsis]
 580     template<
 581         typename I,
 582         typename J
 583         >
 584     __unspecified__ operator==(I const& i, J const& i);
 585
 586 [table Parameters
 587     [[Parameter]    [Requirement]   [Description]]
 588     [[`i`, `j`]     [Any fusion iterators] [Operation's arguments]]
 589 ]
 590
 591 [heading Expression Semantics]
 592     i == j
 593
 594 [*Return type]: Convertible to `bool`.
 595
 596 [*Semantics]: Equivalent to `__result_of_equal_to__<I,J>::value` where `I` and `J` are the types of `i` and `j` respectively.
 597
 598 [heading Header]
 599     #include <boost/fusion/iterator/equal_to.hpp>
 600     #include <boost/fusion/include/equal_to.hpp>
 601
 602 [endsect]
 603
 604 [section:operator_inequality Operator !=]
 605
 606 [heading Description]
 607 Compares 2 iterators for inequality.
 608
 609 [heading Synopsis]
 610     template<
 611         typename I,
 612         typename J
 613         >
 614     __unspecified__ operator==(I const& i, J const& i);
 615
 616 [table Parameters
 617     [[Parameter]    [Requirement]   [Description]]
 618     [[`i`, `j`]     [Any fusion iterators] [Operation's arguments]]
 619 ]
 620
 621 [heading Expression Semantics]
 622
 623 [*Return type]: Convertible to `bool`.
 624
 625 [*Semantics]: Equivalent to `!__result_of_equal_to__<I,J>::value` where `I` and `J` are the types of `i` and `j` respectively.
 626
 627 [heading Header]
 628     #include <boost/fusion/iterator/equal_to.hpp>
 629     #include <boost/fusion/include/equal_to.hpp>
 630
 631 [endsect]
 632
 633 [endsect]
 634
 635 [section Metafunctions]
 636
 637 [section value_of]
 638
 639 [heading Description]
 640
 641 Returns the type stored at the position of an iterator.
 642
 643 [heading Synopsis]
 644     template<
 645         typename I
 646         >
 647     struct value_of
 648     {
 649         typedef __unspecified__ type;
 650     };
 651
 652 [table Parameters
 653     [[Parameter]    [Requirement]   [Description]]
 654     [[`I`]          [Model of __forward_iterator__] [Operation's argument]]
 655 ]
 656
 657 [heading Expression Semantics]
 658     __result_of_value_of__<I>::type
 659
 660 [*Return type]: Any type
 661
 662 [*Semantics]: Returns the type stored in a sequence at iterator position `I`.
 663
 664 [heading Header]
 665     #include <boost/fusion/iterator/value_of.hpp>
 666     #include <boost/fusion/include/value_of.hpp>
 667
 668 [heading Example]
 669     typedef __vector__<int,int&,const int&> vec;
 670     typedef __result_of_begin__<vec>::type first;
 671     typedef __result_of_next__<first>::type second;
 672     typedef __result_of_next__<second>::type third;
 673
 674     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<first>::type, int>));
 675     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, int&>));
 676     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<third>::type, const int&>));
 677
 678 [endsect]
 679
 680 [section deref]
 681
 682 [heading Description]
 683 Returns the type that will be returned by dereferencing an iterator.
 684
 685 [heading Synopsis]
 686     template<
 687         typename I
 688         >
 689     struct deref
 690     {
 691         typedef __unspecified__ type;
 692     };
 693
 694 [table Parameters
 695     [[Parameter] [Requirement]                   [Description]]
 696     [[`I`]       [Model of __forward_iterator__] [Operation's argument]]
 697 ]
 698
 699 [heading Expression Semantics]
 700     __result_of_deref__<I>::type
 701
 702 [*Return type]: Any type
 703
 704 [*Semantics]: Returns the result of dereferencing an iterator of type `I`.
 705
 706 [heading Header]
 707     #include <boost/fusion/iterator/deref.hpp>
 708     #include <boost/fusion/include/deref.hpp>
 709
 710 [heading Example]
 711     typedef __vector__<int,int&> vec;
 712     typedef const vec const_vec;
 713     typedef __result_of_begin__<vec>::type first;
 714     typedef __result_of_next__<first>::type second;
 715
 716     typedef __result_of_begin__<const_vec>::type const_first;
 717     typedef __result_of_next__<const_first>::type const_second;
 718
 719     BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__<first>::type, int&>));
 720     BOOST_MPL_ASSERT((boost::is_same<__result_of_deref__<second>::type, int&>));
 721
 722 [endsect]
 723
 724 [section next]
 725
 726 [heading Description]
 727 Returns the type of the next iterator in a sequence.
 728
 729 [heading Synopsis]
 730     template<
 731         typename I
 732         >
 733     struct next
 734     {
 735         typedef __unspecified__ type;
 736     };
 737
 738 [table Parameters
 739     [[Parameter]    [Requirement]   [Description]]
 740     [[`I`]          [Model of __forward_iterator__] [Operation's argument]]
 741 ]
 742
 743 [heading Expression Semantics]
 744     __result_of_next__<I>::type
 745
 746 [*Return type]: A model of the same iterator concept as `I`.
 747
 748 [*Semantics]: Returns an iterator to the next element in the sequence after `I`.
 749
 750 [heading Header]
 751     #include <boost/fusion/iterator/next.hpp>
 752     #include <boost/fusion/include/next.hpp>
 753
 754 [heading Example]
 755     typedef __vector__<int,double> vec;
 756     typedef __result_of_next__<__result_of_begin__<vec>::type>::type second;
 757
 758     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, double>));
 759
 760 [endsect]
 761
 762 [section prior]
 763
 764 [heading Description]
 765 Returns the type of the previous iterator in a sequence.
 766
 767 [heading Synopsis]
 768     template<
 769         typename I
 770         >
 771     struct prior
 772     {
 773         typedef __unspecified__ type;
 774     };
 775
 776 [table Parameters
 777     [[Parameter]    [Requirement]   [Description]]
 778     [[`I`]          [Model of __bidirectional_iterator__] [Operation's argument]]
 779 ]
 780
 781 [heading Expression Semantics]
 782     __result_of_prior__<I>::type
 783
 784 [*Return type]: A model of the same iterator concept as `I`.
 785
 786 [*Semantics]: Returns an iterator to the previous element in the sequence before `I`.
 787
 788 [heading Header]
 789     #include <boost/fusion/iterator/prior.hpp>
 790     #include <boost/fusion/include/prior.hpp>
 791
 792 [heading Example]
 793     typedef __vector__<int,double> vec;
 794     typedef __result_of_next__<__result_of_begin__<vec>::type>::type second;
 795
 796     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<second>::type, double>));
 797
 798     typedef __result_of_prior__<second>::type first;
 799     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of__<first>::type, int>));
 800
 801 [endsect]
 802
 803 [section equal_to]
 804
 805 [heading Description]
 806 Returns a true-valued __mpl_integral_constant__ if `I` and `J` are equal.
 807
 808 [heading Synopsis]
 809     template<
 810         typename I,
 811         typename J
 812         >
 813     struct equal_to
 814     {
 815         typedef __unspecified__ type;
 816     };
 817
 818 [table Parameters
 819     [[Parameter]    [Requirement]   [Description]]
 820     [[`I`, `J`]     [Any fusion iterators] [Operation's arguments]]
 821 ]
 822
 823 [heading Expression Semantics]
 824     __result_of_equal_to__<I, J>::type
 825
 826 [*Return type]: A model of __mpl_integral_constant__.
 827
 828 [*Semantics]: Returns `boost::mpl::true_` if `I` and `J` are iterators to the same position. Returns `boost::mpl::false_` otherwise.
 829
 830 [heading Header]
 831     #include <boost/fusion/iterator/equal_to.hpp>
 832     #include <boost/fusion/include/equal_to.hpp>
 833
 834 [heading Example]
 835     typedef __vector__<int,double> vec;
 836     typedef __result_of_begin__<vec>::type first;
 837     typedef __result_of_end__<vec>::type last;
 838     BOOST_MPL_ASSERT((__result_of_equal_to__<first, first>));
 839     BOOST_MPL_ASSERT_NOT((__result_of_equal_to__<first,last>));
 840
 841 [endsect]
 842
 843 [section distance]
 844
 845 [heading Description]
 846 Returns the distance between two iterators.
 847
 848 [heading Synopsis]
 849     template<
 850         typename I,
 851         typename J
 852         >
 853     struct distance
 854     {
 855         typedef __unspecified__ type;
 856     };
 857
 858 [table Parameters
 859     [[Parameter]    [Requirement]   [Description]]
 860     [[`I`, `J`]          [Models of __forward_iterator__ into the same sequence] [The start and end points of the distance to be measured]]
 861 ]
 862
 863 [heading Expression Semantics]
 864     __result_of_distance__<I, J>::type
 865
 866 [*Return type]: A model of __mpl_integral_constant__.
 867
 868 [*Semantics]: Returns the distance between iterators of types `I` and `J`.
 869
 870 [heading Header]
 871     #include <boost/fusion/iterator/distance.hpp>
 872     #include <boost/fusion/include/distance.hpp>
 873
 874 [heading Example]
 875     typedef __vector__<int,double,char> vec;
 876     typedef __result_of_begin__<vec>::type first;
 877     typedef __result_of_next__<first>::type second;
 878     typedef __result_of_next__<second>::type third;
 879     typedef __result_of_distance__<first,third>::type dist;
 880
 881     BOOST_MPL_ASSERT_RELATION(dist::value, ==, 2);
 882
 883 [endsect]
 884
 885 [section advance]
 886
 887 [heading Description]
 888 Moves an iterator a specified distance.
 889
 890 [heading Synopsis]
 891     template<
 892         typename I,
 893         typename M
 894         >
 895     struct advance
 896     {
 897         typedef __unspecified__ type;
 898     };
 899
 900 [table Parameters
 901     [[Parameter]    [Requirement]   [Description]]
 902     [[`I`]          [Model of __forward_iterator__] [Iterator to move relative to]]
 903     [[`M`]          [Model of __mpl_integral_constant__] [Number of positions to move]]
 904 ]
 905
 906 [heading Expression Semantics]
 907     __result_of_advance__<I,M>::type
 908
 909 [*Return type]: A model of the same iterator concept as `I`.
 910
 911 [*Semantics]: Returns an iterator a distance `M` from `I`. If `I` is a __bidirectional_iterator__ then `M` may be negative.
 912
 913 [heading Header]
 914     #include <boost/fusion/iterator/advance.hpp>
 915     #include <boost/fusion/include/advance.hpp>
 916
 917 [heading Example]
 918     typedef __vector__<int,double,char> vec;
 919     typedef __result_of_begin__<vec>::type first;
 920     typedef __result_of_next__<first>::type second;
 921     typedef __result_of_next__<second>::type third;
 922
 923     BOOST_MPL_ASSERT((__result_of_equal_to__<__result_of_advance__<first, boost::mpl::int_<2> >::type, third>));
 924
 925 [endsect]
 926
 927 [section advance_c]
 928
 929 [heading Description]
 930 Moves an iterator by a specified distance.
 931
 932 [heading Synopsis]
 933     template<
 934         typename I,
 935         int N
 936         >
 937     struct advance_c
 938     {
 939         typedef __unspecified__ type;
 940     };
 941
 942 [table Parameters
 943     [[Parameter]    [Requirement]   [Description]]
 944     [[`I`]          [Model of __forward_iterator__] [Iterator to move relative to]]
 945     [[`N`]          [Integer constant] [Number of positions to move]]
 946 ]
 947
 948 [heading Expression Semantics]
 949     __result_of_advance_c__<I, N>::type
 950
 951 [*Return type]: A model of the same iterator concept as `I`.
 952
 953 [*Semantics]: Returns an iterator a distance `N` from `I`. If `I` is a __bidirectional_iterator__ then `N` may be negative. Equivalent to `__result_of_advance__<I, boost::mpl::int_<N> >::type`.
 954
 955 [heading Header]
 956     #include <boost/fusion/iterator/advance.hpp>
 957     #include <boost/fusion/include/advance.hpp>
 958
 959 [heading Example]
 960     typedef __vector__<int,double,char> vec;
 961     typedef __result_of_begin__<vec>::type first;
 962     typedef __result_of_next__<first>::type second;
 963     typedef __result_of_next__<second>::type third;
 964
 965     BOOST_MPL_ASSERT((__result_of_equal_to__<__result_of_advance_c__<first, 2>::type, third>));
 966
 967 [endsect]
 968
 969 [section key_of]
 970
 971 [heading Description]
 972
 973 Returns the key type associated with the element referenced by an associative iterator.
 974
 975 [heading Synopsis]
 976     template<
 977         typename I
 978         >
 979     struct key_of
 980     {
 981         typedef __unspecified__ type;
 982     };
 983
 984 [table Parameters
 985     [[Parameter]    [Requirement]   [Description]]
 986     [[`I`]          [Model of __associative_iterator__] [Operation's argument]]
 987 ]
 988
 989 [heading Expression Semantics]
 990     __result_of_key_of__<I>::type
 991
 992 [*Return type]: Any type
 993
 994 [*Semantics]: Returns the key type associated with the element referenced by an associative iterator `I`.
 995
 996 [heading Header]
 997     #include <boost/fusion/iterator/key_of.hpp>
 998     #include <boost/fusion/include/key_of.hpp>
 999
1000 [heading Example]
1001     typedef __map__<__pair__<float,int> > vec;
1002     typedef __result_of_begin__<vec>::type first;
1003
1004     BOOST_MPL_ASSERT((boost::is_same<__result_of_key_of__<first>::type, float>));
1005
1006 [endsect]
1007
1008 [section value_of_data]
1009
1010 [heading Description]
1011
1012 Returns the type of the data property associated with the element referenced by an associative iterator references.
1013
1014 [heading Synopsis]
1015     template<
1016         typename I
1017         >
1018     struct value_of_data
1019     {
1020         typedef __unspecified__ type;
1021     };
1022
1023 [table Parameters
1024     [[Parameter]    [Requirement]   [Description]]
1025     [[`I`]          [Model of __associative_iterator__] [Operation's argument]]
1026 ]
1027
1028 [heading Expression Semantics]
1029     __result_of_value_of_data__<I>::type
1030
1031 [*Return type]: Any type
1032
1033 [*Semantics]: Returns the type of the data property associated with the element referenced by an associative iterator `I`.
1034
1035 [heading Header]
1036     #include <boost/fusion/iterator/value_of_data.hpp>
1037     #include <boost/fusion/include/value_of_data.hpp>
1038
1039 [heading Example]
1040     typedef __map__<__pair__<float,int> > vec;
1041     typedef __result_of_begin__<vec>::type first;
1042
1043     BOOST_MPL_ASSERT((boost::is_same<__result_of_value_of_data__<first>::type, int>));
1044
1045 [endsect]
1046
1047 [section deref_data]
1048
1049 [heading Description]
1050 Returns the type that will be returned by dereferencing the data property referenced by an associative iterator.
1051
1052 [heading Synopsis]
1053     template<
1054         typename I
1055         >
1056     struct deref_data
1057     {
1058         typedef __unspecified__ type;
1059     };
1060
1061 [table Parameters
1062     [[Parameter] [Requirement]                   [Description]]
1063     [[`I`]       [Model of __associative_iterator__] [Operation's argument]]
1064 ]
1065
1066 [heading Expression Semantics]
1067     __result_of_deref_data__<I>::type
1068
1069 [*Return type]: Any type
1070
1071 [*Semantics]: Returns the result of dereferencing the data property referenced by an associative iterator of type `I`.
1072
1073 [heading Header]
1074     #include <boost/fusion/iterator/deref_data.hpp>
1075     #include <boost/fusion/include/deref_data.hpp>
1076
1077 [heading Example]
1078     typedef map<pair<float, int> > map_type;
1079     typedef boost::fusion::result_of::begin<map_type>::type i_type;
1080     typedef boost::fusion::result_of::deref_data<i_type>::type r_type;
1081     BOOST_STATIC_ASSERT((boost::is_same<r_type, int&>::value));
1082
1083 [endsect]
1084
1085 [endsect]
1086
1087 [endsect]