Spec:o3tl/utilities/range

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();