|
-
|
-
- Four types of objects are currently supported by the library: -
std::pair<iterator,iterator>
- char[],wchar_t[],
- char*, and wchar_t*)
- - Warning: support for null-terminated strings is deprecated and will - disappear in the next Boost release (1.34). -
- -iterator_range implements
- the minimal interface required to make the
- class a Forward Range.
-
-
- - Please also see Range concepts for more details. -
- -- -
-namespace boost -{ - // - // Single Pass Range metafunctions - // - - template< class T > - struct range_value; - - template< class T > - struct range_iterator; - - template< class T > - struct range_const_iterator; - - // - // Forward Range metafunctions - // - - template< class T > - struct range_difference; - - template< class T > - struct range_size; - - // - // Bidirectional Range metafunctions - // - - template< class T > - struct range_reverse_iterator; - - template< class T > - struct range_const_reverse_iterator; - - // - // Special metafunctions - // - - template< class T > - struct range_result_iterator; - - template< class T > - struct range_reverse_result_iterator; - - // - // Single Pass Range functions - // - - template< class T > - typename range_iterator<T>::type - begin( T& c ); - - template< class T > - typename range_const_iterator<T>::type - begin( const T& c ); - - template< class T > - typename range_iterator<T>::type - end( T& c ); - - template< class T > - typename range_const_iterator<T>::type - end( const T& c ); - - template< class T > - bool - empty( const T& c ); - - // - // Forward Range functions - // - - template< class T > - typename range_size<T>::type - size( const T& c ); - - // - // Bidirectional Range functions - // - - template< class T > - typename range_reverse_iterator<T>::type - rbegin( T& c ); - - template< class T > - typename range_const_reverse_iterator<T>::type - rbegin( const T& c ); - - template< class T > - typename range_reverse_iterator<T>::type - rend( T& c ); - - template< class T > - typename range_const_reverse_iterator<T>::type - rend( const T& c ); - - // - // Special const Range functions - // - - template< class T > - typename range_const_iterator<T>::type - const_begin( const T& r ); - - template< class T > - typename range_const_iterator<T>::type - const_end( const T& r ); - - template< class T > - typename range_const_reverse_iterator<T>::type - const_rbegin( const T& r ); - - template< class T > - typename range_const_reverse_iterator<T>::type - const_rend( const T& r ); - -} // namespace 'boost' - -- - -
-
| 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*
- |
- Please notice in tables below that when four lines appear in a cell, the first - line will describe the primary template, the second line pairs of iterators, the - third line arrays and the last line null-terminated strings. -
--
- The special metafunctions range_result_iterator and range_reverse_result_iterator
- are not part of any Range concept, but they are very useful when implementing
- certain Range classes like sub_range because of their
- ability to select iterators based on constness.
-
-
- The special const functions are not part of any Range concept,
- but are very useful when you want to document clearly that your code is
- read-only.
-
- The primary templates in this library are implemented such that standard
- containers will work automatically and so will boost::array. Below is given an overview of
- which member functions and member types a class must specify to
-be useable as a certain Range concept.
-
-
| Member function | -Related concept | -
|---|---|
begin() |
- Single Pass Range | -
end() |
- Single Pass Range | -
size() |
- Forward Range | -
- Notice that rbegin() and rend() member functions
- are not needed even though the container can support bidirectional iteration.
-
- The required member types are: -
--
| Member type | -Related concept | -
|---|---|
value_type |
- Single Pass Range | -
iterator |
- Single Pass Range | -
const_iterator |
- Single Pass Range | -
difference_type |
- Forward Range | -
size_type |
- Forward Range | -
- Again one should notice that member types reverse_iterator and
- const_reverse_iterator are not needed.
-
- (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
- Some examples are given in the accompanying test files: -
-string.cpp
- std::find() that
- works with char[],wchar_t[],char*,wchar_t*.
- - Warning: support for null-terminated strings is deprecated and will - disappear in the next Boost release (1.34). -
- -algorithm_example.cpp
-
- - (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
-
range_iterator<C>::type
- and range_const_iterator<C>::type for std::pair<iterator, iterator>.
-
- In general it is not possible nor desirable to find a corresponding const_iterator.
- When it is possible to come up with one, the client might choose to construct a std::pair<const_iterator,const_iterator>
- object.
-
- Note that an iterator_range
- is somewhat more convenient than a pair and that a sub_range does
- propagate const-ness.
- The library has been kept small because its current interface will - serve most - purposes. If and when a genuine need arises for more functionality, it can be - implemented. -
-- One should always start with a generic algorithm that takes two iterators (or - more) as input. Then use Boost.Range to build handier versions on top of the - iterator based algorithm. Please notice that once the range version of the - algorithm is done, it makes sense not to expose the iterator version in - the public interface. -
-- Even though we speak of incrementable iterators, it would not make - much sense for ranges; for example, we cannot determine the size and - emptiness of a range since we cannot even compare - its iterators. -
-- Note also that incrementable iterators are derived from output - iterators and so there exist no output range. -
-- (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
-
| Header | -Includes | -Related concept | -
|---|---|---|
<boost/range.hpp> |
- everything | -- | -
<boost/range/metafunctions.hpp> |
- every metafunction | -- | -
<boost/range/functions.hpp> |
- every function | -- | -
<boost/range/value_type.hpp> |
- range_value | -Single Pass Range | -
<boost/range/iterator.hpp> |
- range_iterator | -Single Pass Range | -
<boost/range/const_iterator.hpp> |
- range_const_iterator | -Single Pass Range | -
<boost/range/difference_type.hpp> |
- range_difference | -Forward Range | -
<boost/range/size_type.hpp> |
- range_size | -Forward Range | -
<boost/range/result_iterator.hpp> |
- range_result_iterator | -- | -
<boost/range/reverse_iterator.hpp> |
- range_reverse_iterator | -Bidirectional Range | -
<boost/range/const_reverse_iterator.hpp> |
- range_const_reverse_iterator | -Bidirectional Range | -
<boost/range/reverse_result_iterator.hpp> |
- range_reverse_result_iterator | -- | -
<boost/range/begin.hpp> |
- - begin and - const_begin - | -Single Pass Range | -
<boost/range/end.hpp> |
- - end and - const_end - | -Single Pass Range | -
<boost/range/empty.hpp> |
- empty | -Single Pass Range | -
<boost/range/size.hpp> |
- size | -Forward Range | -
<boost/range/rbegin.hpp> |
- - rbegin and - const_rbegin - | -Bidirectional Range | -
<boost/range/rend.hpp> |
- - rend and - const_rend - | -Bidirectional Range | -
<boost/range/iterator_range.hpp> |
- iterator_range | -- | -
<boost/range/sub_range.hpp> |
- sub_range | -- | -
- (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
- The library have been under way for a long time. Dietmar Kühl originally
- intended to submit an array_traits class template which
- had most of the functionality present now, but only for arrays and standard
- containers.
-
- Meanwhile work on algorithms for containers in various contexts showed the - need for handling pairs of iterators, and string libraries needed special - treatment of character arrays. In the end it made sense to formalize the - minimal requirements of these similar concepts. And the results are the - Range concepts found in this library.
- -
- The term Range was adopted because of paragraph 24.1/7 from the
-C++ standard:
- Most of the library's algorithmic templates that operate on data - structures have interfaces that use ranges. A range is a pair of - iterators that designate the beginning and end of the computation. A - range [i, i) is an empty range; in general, a range [i, j) refers to - the elements in the data structure starting with the one pointed to - by i and up to but not including the one pointed to by j. Range [i, - j) is valid if and only if j is reachable from i. The result of the - application of functions in the library to invalid ranges is - undefined. -- -
- Special thanks goes to -
- (C) Copyright Thorsten Ottosen 2003-2005 -
- - |
- Boost.Range |
-
- Generic algorithms have so far been specified in terms of two or more - iterators. Two iterators would together form a range of values that the - algorithm could work on. This leads to a very general interface, but also - to a somewhat clumsy use of the algorithms with redundant specification - of container names. Therefore we would like to raise the abstraction level - for algorithms so they specify their interface in terms of Ranges as much as possible. -
- -- The most common form of ranges we are used to work with is standard library - containers. However, one - often finds it desirable to extend that code to work with other types that - offer - enough functionality to satisfy the needs of the generic code - if a suitable layer of indirection is applied . For - example, raw arrays are often suitable for use with generic code that - works with containers, provided a suitable adapter is used. Likewise, null - terminated strings can be treated as containers of characters, if suitably - adapted. -
- -
- This library therefore provides the means to adapt standard-like
- containers,
- null terminated strings, std::pairs of iterators, and raw
- arrays (and more), such that the same generic code can work with them all.
-The basic idea is to add another layer of indirection using metafunctions and
-free-standing functions so syntactic and/or semantic differences can be removed.
-
- The main advantages are -
- Warning: support for null-terminated strings is deprecated and will - disappear in the next Boost release (1.34). -
-- Below are given a small example (the complete example can be found here - ): -
-- - By using the free-standing functions and metafunctions, the code automatically - works for all the types supported by this library; now and in the future. -Notice that we have to - provide two version of- - // - // example: extracting bounds in a generic algorithm - // - template< class ForwardReadableRange, class T > - inline typename boost::range_iterator< ForwardReadableRange >::type - find( ForwardReadableRange& c, const T& value ) - { - return std::find( boost::begin( c ), boost::end( c ), value ); - } - - template< class ForwardReadableRange, class T > - inline typename boost::range_const_iterator< ForwardReadableRange >::type - find( const ForwardReadableRange& c, const T& value ) - { - return std::find( boost::begin( c ), boost::end( c ), value ); - } - - // - // replace first value and return its index - // - template< class ForwardReadableWriteableRange, class T > - inline typename boost::range_size< ForwardReadableWriteableRange >::type - my_generic_replace( ForwardReadableWriteableRange& c, const T& value, const T& replacement ) - { - typename boost::range_iterator< ForwardReadableWriteableRange >::type found = find( c, value ); - - if( found != boost::end( c ) ) - *found = replacement; - return std::distance( boost::begin( c ), found ); - } - - // - // usage - // - const int N = 5; - std::vector<int> my_vector; - int values[] = { 1,2,3,4,5,6,7,8,9 }; - - my_vector.assign( values, boost::end( values ) ); - typedef std::vector<int>::iterator iterator; - std::pair<iterator,iterator> my_view( boost::begin( my_vector ), - boost::begin( my_vector ) + N ); - char str_val[] = "a string"; - char* str = str_val; - - std::cout << my_generic_replace( my_vector, 4, 2 ) - << my_generic_replace( my_view, 4, 2 ) - << my_generic_replace( str, 'a', 'b' ); - - // prints '3', '5' and '0' --
find() since we cannot forward a non-const
- rvalue with reference arguments (see this article about The
- Forwarding Problem ).
-
-
-
-
- - (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
- A huge effort has been made to port the library to as many compilers as possible. -
- -- Full support for built-in arrays require that the compiler supports class - template partial specialization. For non-conforming compilers there might be a - chance that it works anyway thanks to workarounds in the type traits library. -
-
- Notice also that some compilers cannot do function template ordering properly.
- In that case one must rely of range_result_iterator
- and a single function definition instead of overloaded versions for const and
- non-const arguments.
-
- So if one cares about old compilers, one should not pass rvalues to the
- functions.
-
- For maximum portability you should follow these guidelines: - -
begin(), end() and
- iterator_range Range constructors and assignment operators,
- const_begin()
- and const_end()
- whenever your code by intention is read-only; this will also solve
- most rvalue problems,
- boost.
- - (C) Copyright Thorsten Ottosen 2003-2004 -
- - |
- Boost.Range |
-
- A Range is a concept similar to the STL Container concept. A
- Range provides iterators for accessing a half-open range
-[first,one_past_last) of elements and provides
- information about the number of elements in the Range. However, a Range has
- fewer requirements than a Container.
-
- The motivation for the Range concept is - that there are many useful Container-like types that do not meet the full - requirements of Container, and many algorithms that can be written with this - reduced set of requirements. In particular, a Range does not necessarily - -
- The operations that can be performed on a Range is dependent on the - traversal -category of the underlying iterator type. Therefore - the range concepts are named to reflect which traversal category its - iterators support. See also terminology and style guidelines. - for more information about naming of ranges.
- -The concepts described below specifies associated types as -metafunctions and all -functions as free-standing functions to allow for a layer of indirection.
- - - -X |
- A type that is a model of Single Pass Range. | -
a |
- Object of type X. |
-
- A range X where boost::range_iterator<X>::type is a model of
-Single Pass Iterator
-
-
| Value type | -boost::range_value<X>::type |
- The type of the object stored in a Range. - |
| Iterator type | -boost::range_iterator<X>::type |
- The type of iterator used to iterate through a Range's elements. - The iterator's value type is expected to be the Range's value type. A - conversion from the iterator type to the const iterator type must exist. - |
| Const iterator type | -boost::range_const_iterator<X>::type |
- A type of iterator that may be used to examine, but not to - modify, a Range's elements. | -
- -
| Name | -Expression | -Return type | -
|---|---|---|
| Beginning of range | -boost::begin(a) |
- boost::range_iterator<X>::type if
-a is mutable, boost::range_const_iterator<X>::type
-otherwise |
| End of range | -boost::end(a) |
- boost::range_iterator<X>::type if
-a is mutable, boost::range_const_iterator<X>::type
-otherwise |
-
| Is range empty? | -boost::empty(a) |
- Convertible to bool |
-
| Expression | -Semantics | -Postcondition | -
|---|---|---|
boost::begin(a) |
- Returns an iterator pointing to the first element in the Range. | -boost::begin(a) is either dereferenceable or past-the-end.
- It is past-the-end if and only if boost::size(a) == 0. |
-
boost::end(a) |
- Returns an iterator pointing one past the last element in the - Range. | -boost::end(a) is past-the-end. |
-
boost::empty(a) |
- Equivalent to boost::begin(a) == boost::end(a). (But possibly
- faster.) |
- - | -
boost::begin(a), boost::end(a) and boost::empty(a)
- to be amortized constant time.
-
- | Valid range | -For any Range a, [boost::begin(a),boost::end(a)) is
- a valid range, that is, boost::end(a) is reachable from boost::begin(a)
- in a finite number of increments. |
-
| Completeness | -An algorithm that iterates through the range [boost::begin(a),boost::end(a))
- will pass through every element of a. |
-
- Container -
-implementation of - metafunctions
- - - -X |
- A type that is a model of Forward Range. | -
a |
- Object of type X. |
-
- A range X where boost::range_iterator<X>::type is a model
-of Forward Traversal Iterator
-
| Distance type | -boost::range_difference<X>::type |
- A signed integral type used to represent the distance between - two of the Range's iterators. This type must be the same as the iterator's - distance type. | -
| Size type | -boost::range_size<X>::type |
- An unsigned integral type that can represent any nonnegative - value of the Range's distance type. | -
| Name | -Expression | -Return type | -
|---|---|---|
| Size of range | -boost::size(a) |
- boost::range_size<X>::type |
-
| Expression | -Semantics | -Postcondition | -
|---|---|---|
boost::size(a) |
- Returns the size of the Range, that is, its number
-of elements. Note boost::size(a) == 0u is equivalent to
-boost::empty(a). |
- boost::size(a) >= 0 |
-
boost::size(a) is at most amortized linear time.
-
| Range size | -boost::size(a) is equal to the distance from boost::begin(a)
- to boost::end(a). |
implementation of - metafunctions
- - - -X |
- A type that is a model of Bidirectional Range. | -
a |
- Object of type X. |
-
boost::range_iterator<X>::type iterator must meet all of the requirements
-of Bidirectional Traversal Iterator.
-
- | Reverse Iterator type | -boost::range_reverse_iterator<X>::type |
- The type of iterator used to iterate through a Range's elements - in reverse order. The iterator's value type is expected to be the Range's value - type. A conversion from the reverse iterator type to the const reverse iterator - type must exist. | -
| Const reverse iterator type | -boost::range_const_reverse_iterator<X>::type |
- A type of reverse iterator that may be used to examine, but not - to modify, a Range's elements. | -
| Name | -Expression | -Return type | -Semantics | -
|---|---|---|---|
| Beginning of range | -rboost::begin(a) |
- boost::range_reverse_iterator<X>::type if
-a is mutable, boost::range_const_reverse_iterator<X>::type
-otherwise. |
- Equivalent to
-boost::range_reverse_iterator<X>::type(boost::end(a)). |
| End of range | -rboost::end(a) |
- boost::range_reverse_iterator<X>::type if
-a is mutable, boost::range_const_reverse_iterator<X>::type
-otherwise. |
- Equivalent to
-boost::range_reverse_iterator<X>::type(boost::begin(a)). |
rboost::begin(a) has the same complexity as boost::end(a) and rboost::end(a)
- has the same complexity as boost::begin(a) from Forward Range.
-
- -
| Valid reverse range | -For any Bidirectional Range a, [rboost::begin(a),rboost::end(a))
- is a valid range, that is, rboost::end(a) is reachable from rboost::begin(a)
- in a finite number of increments. |
-
| Completeness | -An algorithm that iterates through the range [rboost::begin(a),rboost::end(a))
- will pass through every element of a. |
-
implementation of metafunctions
- - - -
- A range X where boost::range_iterator<X>::type is a model
-of Random Access Traversal Iterator
-
| Copyright © 2000 | -Jeremy Siek - |
| Copyright © 2004 | -Thorsten Ottosen. - |