libs/range/doc/reference/semantics.qbk

   1 [/
   2     Copyright 2010 Neil Groves
   3     Distributed under the Boost Software License, Version 1.0.
   4     (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   5 /]
   6 [section:semantics Semantics]
   7
   8 [heading notation]
   9
  10 [table
  11   [[Type   ] [Object] [Describes                                ]]
  12   [[`X`    ] [`x`   ] [any type                                 ]]
  13   [[`T`    ] [`t`   ] [denotes behavior of the primary templates]]
  14   [[`P`    ] [`p`   ] [denotes `std::pair<iterator,iterator>`   ]]
  15   [[`A[sz]`] [`a`   ] [denotes an array of type `A` of size `sz`]]
  16   [[`Char*`] [`s`   ] [denotes either `char*` or `wchar_t*`     ]]
  17 ]
  18
  19 [section Metafunctions]
  20
  21 [table
  22     [[Expression] [Return type] [Complexity]]
  23     [
  24         [`range_iterator<X>::type`]
  25         [``
  26             T::iterator
  27             P::first_type
  28             A*
  29         ``]
  30         [compile time]
  31     ]
  32     [
  33         [`range_iterator<const X>::type`]
  34         [``
  35             T::const_iterator
  36             P::first_type
  37             const A*
  38         ``]
  39         [compile time]
  40     ]
  41     [
  42         [`range_value<X>::type`]
  43         [`boost::iterator_value<range_iterator<X>::type>::type`]
  44         [compile time]
  45     ]
  46     [
  47         [`range_reference<X>::type`]
  48         [`boost::iterator_reference<range_iterator<X>::type>::type`]
  49         [compile time]
  50     ]
  51     [
  52         [`range_pointer<X>::type`]
  53         [`boost::iterator_pointer<range_iterator<X>::type>::type`]
  54         [compile time]
  55     ]
  56     [
  57         [`range_category<X>::type`]
  58         [`boost::iterator_category<range_iterator<X>::type>::type`]
  59         [compile time]
  60     ]
  61     [
  62         [`range_difference<X>::type`]
  63         [`boost::iterator_difference<range_iterator<X>::type>::type`]
  64         [compile time]
  65     ]
  66     [
  67         [`range_reverse_iterator<X>::type`]
  68         [`boost::reverse_iterator<range_iterator<X>::type>`]
  69         [compile time]
  70     ]
  71     [
  72         [`range_reverse_iterator<const X>::type`]
  73         [`boost::reverse_iterator<range_iterator<const X>::type`]
  74         [compile time]
  75     ]
  76     [
  77         [`has_range_iterator<X>::type`]
  78         [`mpl::true_` if `range_mutable_iterator<X>::type` is a valid expression, `mpl::false_` otherwise]
  79         [compile time]
  80     ]
  81     [
  82         [`has_range_const_iterator<X>::type`]
  83         [`mpl::true_` if `range_const_iterator<X>::type` is a valid expression, `mpl::false_` otherwise]
  84         [compile time]
  85     ]
  86 ]
  87
  88 [endsect]
  89
  90 [section Functions]
  91
  92 [table
  93     [[Expression] [Return type] [Returns] [Complexity]]
  94
  95     [
  96         [`begin(x)`]
  97         [`range_iterator<X>::type`]
  98         [
  99             `p.first` if `p` is of type `std::pair<T>`
 100             `a` if `a` is an array
 101             `range_begin(x)` if that expression would invoke a function found by ADL
 102             `t.begin()` otherwise
 103         ]
 104         [constant time]
 105     ]
 106     [
 107         [`end(x)`]
 108         [`range_iterator<X>::type`]
 109         [
 110             `p.second` if `p` is of type `std::pair<T>`
 111             `a + sz` if `a` is an array of size `sz`
 112             `range_end(x)` if that expression would invoke a function found by ADL
 113             `t.end()` otherwise
 114         ]
 115         [constant time]
 116     ]
 117     [
 118         [`empty(x)`]
 119         [`bool`]
 120         [`boost::begin(x) == boost::end(x)`]
 121         [constant time]
 122     ]
 123     [
 124         [`distance(x)`]
 125         [`range_difference<X>::type`]
 126         [`std::distance(boost::begin(x),boost::end(x))`]
 127         [-]
 128     ]
 129     [
 130         [`size(x)`]
 131         [`range_size<X>::type`]
 132         [`range_calculate_size(x)` which by default is `boost::end(x) - boost::begin(x)`. Users may supply alternative implementations by implementing `range_calculate_size(x)` so that it will be found via ADL]
 133         [constant time]
 134     ]
 135     [
 136         [`rbegin(x)`]
 137         [`range_reverse_iterator<X>::type`]
 138         [`range_reverse_iterator<X>::type(boost::end(x))`]
 139         [constant time]
 140     ]
 141     [
 142         [`rend(x)`]
 143         [`range_reverse_iterator<X>::type`]
 144         [`range_reverse_iterator<X>::type(boost::begin(x))`]
 145         [constant time]
 146     ]
 147     [
 148         [`const_begin(x)`]
 149         [`range_iterator<const X>::type`]
 150         [`range_iterator<const X>::type(boost::begin(x))`]
 151         [constant time]
 152     ]
 153     [
 154         [`const_end(x)`]
 155         [`range_iterator<const X>::type`]
 156         [`range_iterator<const X>::type(boost::end(x))`]
 157         [constant time]
 158     ]
 159     [
 160         [`const_rbegin(x)`]
 161         [`range_reverse_iterator<const X>::type`]
 162         [`range_reverse_iterator<const X>::type(boost::rbegin(x))`]
 163         [constant time]
 164     ]
 165     [
 166         [`const_rend(x)`]
 167         [`range_reverse_iterator<const X>::type`]
 168         [`range_reverse_iterator<const X>::type(boost::rend(x))`]
 169         [constant time]
 170     ]
 171     [
 172         [`as_literal(x)`]
 173         [`iterator_range<U>` where `U` is `Char*` if `x` is a pointer to a string and `U` is `range_iterator<X>::type` otherwise]
 174         [
 175             `[s,s + std::char_traits<X>::length(s))` if `s` is a `Char*` or an array of `Char` `[boost::begin(x),boost::end(x))` otherwise
 176         ]
 177         [
 178             linear time for pointers to a string or arrays of `Char`, constant time otherwise
 179         ]
 180     ]
 181     [
 182         [`as_array(x)`]
 183         [`iterator_range<X>`]
 184         [`[boost::begin(x),boost::end(x))`]
 185     ]
 186 ]
 187
 188 The special `const_`-named functions are useful when you want to document clearly that your code is read-only.
 189
 190 `as_literal()` can be used ['*internally*] in string algorithm libraries such that arrays of characters are handled correctly.
 191
 192 `as_array()` can be used with string algorithm libraries to make it clear that arrays of characters are handled like an array and not like a string.
 193
 194 Notice that the above functions should always be called with qualification (`boost::`) to prevent ['*unintended*] Argument Dependent Lookup (ADL).
 195
 196 [endsect]
 197
 198 [endsect]
 199
 200