ceph/src/boost/libs/mpl/doc/src/refmanual/begin.rst

   1 .. Sequences/Intrinsic Metafunctions//begin
   2
   3 begin
   4 =====
   5
   6 Synopsis
   7 --------
   8
   9 .. parsed-literal::
  10
  11     template<
  12           typename X
  13         >
  14     struct begin
  15     {
  16         typedef |unspecified| type;
  17     };
  18
  19
  20
  21 Description
  22 -----------
  23
  24 Returns an iterator that points to the first element of the sequence. If
  25 the argument is not a |Forward Sequence|, returns |void_|.
  26
  27
  28 Header
  29 ------
  30
  31 .. parsed-literal::
  32
  33     #include <boost/mpl/begin_end.hpp>
  34
  35
  36
  37 Model of
  38 --------
  39
  40 |Tag Dispatched Metafunction|
  41
  42
  43 Parameters
  44 ----------
  45
  46 +---------------+-------------------+---------------------------------------------------+
  47 | Parameter     | Requirement       | Description                                       |
  48 +===============+===================+===================================================+
  49 | ``X``         | Any type          | A type whose begin iterator, if any, will be      |
  50 |               |                   | returned.                                         |
  51 +---------------+-------------------+---------------------------------------------------+
  52
  53
  54 Expression semantics
  55 --------------------
  56
  57 For any arbitrary type ``x``:
  58
  59 .. parsed-literal::
  60
  61     typedef begin<x>::type first;
  62
  63 :Return type:
  64     |Forward Iterator| or |void_|.
  65
  66 :Semantics:
  67     If ``x`` is a |Forward Sequence|, ``first`` is an iterator pointing to the
  68     first element of ``s``; otherwise ``first`` is |void_|.
  69
  70 :Postcondition:
  71     If ``first`` is an iterator, it is either dereferenceable or past-the-end; it
  72     is past-the-end if and only if ``size<x>::value == 0``.
  73
  74
  75 Complexity
  76 ----------
  77
  78 Amortized constant time.
  79
  80
  81 Example
  82 -------
  83
  84 .. parsed-literal::
  85
  86     typedef vector< unsigned char,unsigned short,
  87         unsigned int,unsigned long > unsigned_types;
  88
  89     typedef begin<unsigned_types>::type iter;
  90     BOOST_MPL_ASSERT(( is_same< deref<iter>::type, unsigned char > ));
  91
  92     BOOST_MPL_ASSERT(( is_same< begin<int>::type, void\_ > ));
  93
  94
  95 See also
  96 --------
  97
  98 |Iterators|, |Forward Sequence|, |end|, |size|, |empty|
  99
 100
 101 .. copyright:: Copyright ©  2001-2009 Aleksey Gurtovoy and David Abrahams
 102    Distributed under the Boost Software License, Version 1.0. (See accompanying
 103    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)