libs/range/doc/reference/semantics.qbk
[/
Copyright 2010 Neil Groves
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[section:semantics Semantics]
[heading notation]
[table
[[Type ] [Object] [Describes ]]
[[`X` ] [`x` ] [any type ]]
[[`T` ] [`t` ] [denotes behavior of the primary templates]]
[[`P` ] [`p` ] [denotes `std::pair<iterator,iterator>` ]]
[[`A[sz]`] [`a` ] [denotes an array of type `A` of size `sz`]]
[[`Char*`] [`s` ] [denotes either `char*` or `wchar_t*` ]]
]
[section Metafunctions]
[table
[[Expression] [Return type] [Complexity]]
[
[`range_iterator<X>::type`]
[``
T::iterator
P::first_type
A*
``]
[compile time]
]
[
[`range_iterator<const X>::type`]
[``
T::const_iterator
P::first_type
const A*
``]
[compile time]
]
[
[`range_value<X>::type`]
[`boost::iterator_value<range_iterator<X>::type>::type`]
[compile time]
]
[
[`range_reference<X>::type`]
[`boost::iterator_reference<range_iterator<X>::type>::type`]
[compile time]
]
[
[`range_pointer<X>::type`]
[`boost::iterator_pointer<range_iterator<X>::type>::type`]
[compile time]
]
[
[`range_category<X>::type`]
[`boost::iterator_category<range_iterator<X>::type>::type`]
[compile time]
]
[
[`range_difference<X>::type`]
[`boost::iterator_difference<range_iterator<X>::type>::type`]
[compile time]
]
[
[`range_reverse_iterator<X>::type`]
[`boost::reverse_iterator<range_iterator<X>::type>`]
[compile time]
]
[
[`range_reverse_iterator<const X>::type`]
[`boost::reverse_iterator<range_iterator<const X>::type`]
[compile time]
]
[
[`has_range_iterator<X>::type`]
[`mpl::true_` if `range_mutable_iterator<X>::type` is a valid expression, `mpl::false_` otherwise]
[compile time]
]
[
[`has_range_const_iterator<X>::type`]
[`mpl::true_` if `range_const_iterator<X>::type` is a valid expression, `mpl::false_` otherwise]
[compile time]
]
]
[endsect]
[section Functions]
[table
[[Expression] [Return type] [Returns] [Complexity]]
[
[`begin(x)`]
[`range_iterator<X>::type`]
[
`p.first` if `p` is of type `std::pair<T>`
`a` if `a` is an array
`range_begin(x)` if that expression would invoke a function found by ADL
`t.begin()` otherwise
]
[constant time]
]
[
[`end(x)`]
[`range_iterator<X>::type`]
[
`p.second` if `p` is of type `std::pair<T>`
`a + sz` if `a` is an array of size `sz`
`range_end(x)` if that expression would invoke a function found by ADL
`t.end()` otherwise
]
[constant time]
]
[
[`empty(x)`]
[`bool`]
[`boost::begin(x) == boost::end(x)`]
[constant time]
]
[
[`distance(x)`]
[`range_difference<X>::type`]
[`std::distance(boost::begin(x),boost::end(x))`]
[-]
]
[
[`size(x)`]
[`range_size<X>::type`]
[`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]
[constant time]
]
[
[`rbegin(x)`]
[`range_reverse_iterator<X>::type`]
[`range_reverse_iterator<X>::type(boost::end(x))`]
[constant time]
]
[
[`rend(x)`]
[`range_reverse_iterator<X>::type`]
[`range_reverse_iterator<X>::type(boost::begin(x))`]
[constant time]
]
[
[`const_begin(x)`]
[`range_iterator<const X>::type`]
[`range_iterator<const X>::type(boost::begin(x))`]
[constant time]
]
[
[`const_end(x)`]
[`range_iterator<const X>::type`]
[`range_iterator<const X>::type(boost::end(x))`]
[constant time]
]
[
[`const_rbegin(x)`]
[`range_reverse_iterator<const X>::type`]
[`range_reverse_iterator<const X>::type(boost::rbegin(x))`]
[constant time]
]
[
[`const_rend(x)`]
[`range_reverse_iterator<const X>::type`]
[`range_reverse_iterator<const X>::type(boost::rend(x))`]
[constant time]
]
[
[`as_literal(x)`]
[`iterator_range<U>` where `U` is `Char*` if `x` is a pointer to a string and `U` is `range_iterator<X>::type` otherwise]
[
`[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
]
[
linear time for pointers to a string or arrays of `Char`, constant time otherwise
]
]
[
[`as_array(x)`]
[`iterator_range<X>`]
[`[boost::begin(x),boost::end(x))`]
]
]
The special `const_`-named functions are useful when you want to document clearly that your code is read-only.
`as_literal()` can be used ['*internally*] in string algorithm libraries such that arrays of characters are handled correctly.
`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.
Notice that the above functions should always be called with qualification (`boost::`) to prevent ['*unintended*] Argument Dependent Lookup (ADL).
[endsect]
[endsect]
