Boost.Range

Range concepts

Range

Description

A Range is a concept similar to the STL Container concept. A Range provides iterators for accessing a range 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 Because of the second requirement, a Range object must be passed by reference in generic code.

Notation

X A type that is a model of Range.
a, b Object of type X.
T The value type of X.

Associated types

Value type value_type_of<X>::type The type of the object stored in a Range.
Iterator type iterator_of<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. The iterator type must at least be an InputIterator.
Const iterator type const_iterator_of<X>::type A type of iterator that may be used to examine, but not to modify, a Range's elements.
Reference type reference_of<X>::type A type that behaves like a reference to the Range's value type. [1]
Distance type difference_type_of<>::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 size_type_of<X>::type An unsigned integral type that can represent any nonnegative value of the Range's distance type.

Valid expressions

The following expressions must be valid.

Name Expression Return type
Beginning of range begin(a) iterator if a is mutable, const_iterator otherwise
End of range end(a) iterator if a is mutable, const_iterator otherwise
Size of range size(a) size_type
Is range empty? empty(a) Convertible to bool

Expression semantics

Expression Semantics Postcondition
begin(a) Returns an iterator pointing to the first element in the Range. begin(a) is either dereferenceable or past-the-end. It is past-the-end if and only if size(a) == 0.
end(a) Returns an iterator pointing one past the last element in the Range. end(a) is past-the-end.
size(a) Returns the size of the Collection, that is, its number of elements. size(a) >= 0
empty(a) Equivalent to size(a) == 0. (But possibly faster.)  - 

Complexity guarantees

All four functions are at most amortized linear time. For most practical purposes, one can expect begin(a), end(a) and empty(a) to be amortized constant time.

Invariants

Valid range For any Range a, [begin(a),end(a)) is a valid range, that is, end(a) is reachable from begin(a) in a finite number of increments.
Range size size(a) is equal to the distance from begin(a) to end(a).
Completeness An algorithm that iterates through the range [begin(a),end(a)) will pass through every element of a.

Models

See also

Container


ReversibleRange

Description

This concept provides access to iterators that traverse in both directions (forward and reverse). The iterator type must meet all of the requirements of BidirectionalIterator except that the reference type does not have to be a real C++ reference.

Refinement of

Range

Associated types

Reverse Iterator type X::reverse_iterator 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. The iterator type must at least be a BidirectionalIterator.
Const reverse iterator type X::const_reverse_iterator A type of reverse iterator that may be used to examine, but not to modify, a Range's elements.

Valid expressions

Name Expression Return type Semantics
Beginning of range rbegin(a) reverse_iterator if a is mutable, const_reverse_iterator otherwise. Equivalent to X::reverse_iterator(end(a)).
End of range rend(a) reverse_iterator if a is mutable, const_reverse_iterator otherwise. Equivalent to X::reverse_iterator(begin(a)).

Complexity guarantees

rbegin(a) has the same complexity as end(a) and rend(a) has the same complexity as begin(a) from Range.

Models

Notes

[1] The reference type does not have to be a real C++ reference. The requirements of the reference type is that it behaves like a real reference. Hence the reference type must be convertible to the value_type and assignment through


Copyright © 2000 Jeremy Siek
Copyright © 2004 Thorsten Ottosen.