Spec:o3tl/utilities/range
From Apache OpenOffice Wiki
o3tl::range<> - a Range for C++ Integer Types, Pointers and Random Access Iterators
Specification Status | |
Author | Nikolai Pretzell |
Last Change | 2007-07-11 |
Status | Finished |
Abstract
range<>
is a C++ class that represents a range within integer or pointer types or within two random access iterators.
References
Reference Document | Location (URL) |
Product Requirement, RFE, Issue ID | IssueZilla 76769 |
Test case specification | Unit Tests in module o3tl/qa/test-range.cxx |
Contacts
Role | Name | E-Mail Address |
Developer | Nikolai Pretzell | np@openoffice.org |
Quality Assurance | Thorsten Behrens | thb@openoffice.org |
Documentation | Nikolai Pretzell | np@openoffice.org |
Detailed Specification
The class allows to replace iterator pairs, where constantly both appear together and represent the lower and upper border of a range, by a single object, such clarifying the programmers intention and allowing range specific operations.
Typical Use
bool SelectionIsWithinParagraph( range<TextPtr> i_paragraph, range<TextPtr> i_selection )
{
return i_paragraph.contains(i_selection);
}
Template Type
T: T has to be either an integer type, a pointer type or a random access iterator.
Member Functions
Function | Precondition | Semantic | Postcondition |
---|---|---|---|
range( T i_inclusiveLowerBorder, T i_exclusiveUpperBorder )
|
[i_inclusiveLowerBorder, i_exclusiveUpperBorder] is a valid range. | Creates a range object. | begin() == i_inclusiveLowerBorder; end() == i_exclusiveUpperBorder; size() == end() - begin(); |
T begin() const
|
- | Returns the (inclusive) lower border of the range. | - |
T end() const
|
- | Returns the (exclusive) upper border of the range. | - |
std::size_t size() const
|
- | Returns the size of the range: end() - begin(). | - |
bool contains(T i_value) const
|
- | Returns true, if i_value >= begin() and i_value < end(). | - |
bool contains(const self & i_other) const
|
- | Returns true, if i_other is contained in this. The exact condition is: contains(i_other.begin()) && i_other.end() <= end(). | - |
bool overlaps(const self & i_other) const
|
- | Returns true, if contains(i_other.begin()) || i_other.contains(begin()). | - |
long distance_to( const self & i_other ) const
|
- | Returns i_other.begin() - this->end(). Return value may be negative. | - |
Global Functions
Function | Precondition | Semantic | Postcondition |
---|---|---|---|
template <class T> range<T> make_range(T i1, T i2)
|
[i1, i2] is a valid range. | Creates a range<> object where the template type is deduced from the function parameters. | returnvalue.begin() == i1; returnvalue.end() == i2 returnvalue.size() == i2 - i1; |
template <class T> range<typename T::const_iterator> range_of(const T & i_container)
|
- | Returns a range that includes all elements of i_container. | returnvalue.begin() == i_container.begin(); returnvalue.end() == i_container.end() returnvalue.size() == i_container.size(); |
template <class T> range<typename T::iterator> range_of(T & i_container)
|
- | Returns a range that includes all elements of i_container. | returnvalue.begin() == i_container.begin(); returnvalue.end() == i_container.end() returnvalue.size() == i_container.size(); |