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 188The 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 194Notice 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 201