Class: TTextRange

Declaration: TextRange.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MOrderableCollectible

Inherited By:

None.

Purpose:

Specifies a particular subrange of characters within a body of text, using an offset (zero-based) and length. Use TTextRange when specifying a range of text in the protocol defined by class TText. Begin is the TTextOffset before the first item in the range. End is the TTextOffset after the last item in the range. Length is the TTextCount number of elements in the range. For example, a TTextRange containing just the TTextIndex values 3 and 4 has a beginning TTextOffset of 3, an ending TTextOffset of 5 and a TTextCount length of 2.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a primitive class that is never intended for deriving. Text ranges are used pervasively with text and performance is critical.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextRange::TTextRange

TTextRange ()
TTextRange (const TTextRange & range)
TTextRange (TTextOffset begin, TTextOffset end)
TTextRange (TTextOffset begin, TTextCount length)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Constructs a range with the specified beginning and ending offsets.
Constructs a range with the specified beginning offset and length.

Calling Context:

Called by the stream-in operators.
Called to copy an object.
Called to construct a range from two offsets.
Called to construct a range from an offset and a length.

Parameters:

Takes no parameters.
const TTextRange & range -The input range to copy from.
TTextOffset begin -The beginning offset for the new range.
TTextOffset end -The ending offset for the new range.
TTextOffset begin -The beginning offset for the new range.
TTextCount length -The length for the new range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The empty constructor creates a range with a beginning offset, an ending offset, and a length that are all equal to zero.

Member Function: TTextRange::InRange

bool InRange (TTextIndex index) const

Interface Category:

API.

Purpose:

Determines whether the specified index is in this range; that is, it is between the beginning and ending offsets.

Calling Context:

To find out if a particular index is part of this range.

Parameters:

TTextIndex index -The index of interest.

Return Value:

Returns true if the specified index is less than the ending offset and greater than or equal to the beginning offset.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::GetBegin

TTextOffset GetBegin () const

Interface Category:

API.

Purpose:

Returns the beginning offset for this range.

Calling Context:

When you need to know where this range begins.

Parameters:

Takes no parameters.

Return Value:

Returns the beginning offset of this range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::GetEnd

TTextOffset GetEnd () const

Interface Category:

API.

Purpose:

Returns the ending offset for this range.

Calling Context:

When you need to know where this range ends.

Parameters:

Takes no parameters.

Return Value:

Returns the ending offset of this range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::GetLength

TTextCount GetLength () const

Interface Category:

API.

Purpose:

Gets the length of this range.

Calling Context:

When you need to know the number of indexes contained in this range.

Parameters:

Takes no parameters.

Return Value:

Returns the number of indexes contained in this range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::SetBegin

void SetBegin (TTextOffset begin)

Interface Category:

API.

Purpose:

Sets the beginning offset of this range.

Calling Context:

When you need to set the beginning offset of this range.

Parameters:

TTextOffset begin -The new beginning offset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When changing the beginning offset, the ending offset is not changed unless absolutely necessary. However, the invariant that the ending offset never be less than the beginning offset is always preserved. In cases where the new beginning offset is greater than the ending offset, both offsets are set equal to the new beginning offset and the range becomes an empty one.

Member Function: TTextRange::SetEnd

void SetEnd (TTextOffset end)

Interface Category:

API.

Purpose:

Sets the ending offset of this range.

Calling Context:

When you need to set the ending offset of this range.

Parameters:

TTextOffset end -The new ending offset to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When changing the ending offset, the beginning offset is not changed unless absolutely necessary. However, the invariant that the ending offset never be less than the beginning offset is always preserved. In cases where the new ending offset is less than the beginning offset, both offsets are set equal to the new ending offset and the range becomes an empty one.

Member Function: TTextRange::SetBeginAndEnd

void SetBeginAndEnd (TTextOffset begin, TTextOffset end)

Interface Category:

API.

Purpose:

Sets the beginning and ending offsets of this range.

Calling Context:

When you need to set the beginning and ending offsets of this range.

Parameters:

TTextOffset begin -The new beginning offset to set.
TTextOffset end -The new ending offset to set.

Return Value:

None.

Exceptions:

Throws an exception when the new ending offset is less than the new beginning offset. Since blindly setting these two values would violate a class invariant, an exception is raised instead. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::SetBeginAndLength

void SetBeginAndLength (TTextOffset begin, TTextCount length)

Interface Category:

API.

Purpose:

Sets the beginning offset and the length of this range.

Calling Context:

When you need to set the beginning offset and the length of this range.

Parameters:

TTextOffset begin -The new beginning offset to set.
TTextCount length -The new length to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::SetEndAndLength

void SetEndAndLength (TTextOffset end, TTextCount length)

Interface Category:

API.

Purpose:

Sets the ending offset and the length of this range.

Calling Context:

When you need to set the ending offset and the length of this range.

Parameters:

TTextOffset end -The new ending offset to set.
TTextCount length -The new length to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::ShiftBy

void ShiftBy (TTextOffset delta)

Interface Category:

API.

Purpose:

Adds the specified offset to the beginning and ending offsets. The length remains the same.

Calling Context:

When you need to shift a range by some fixed amount and you want to preserve the current range length.

Parameters:

TTextOffset delta -The positive or negative shift amount.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::operator+=

TTextRange & operator += (TTextOffset delta)

Interface Category:

API.

Purpose:

Adds the specified offset to the beginning and ending offsets. The length remains the same.

Calling Context:

When you need to shift a range by some fixed amount and you want to preserve the current range length.

Parameters:

TTextOffset delta -The positive or negative shift amount.

Return Value:

Returns a reference to this range after shifting it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::operator-=

TTextRange & operator -=(TTextOffset delta)

Interface Category:

API.

Purpose:

Subtracts the specified offset from the beginning and ending offsets. The length remains the same.

Calling Context:

When you need to shift a range by some fixed amount and you want to preserve the current range length.

Parameters:

TTextOffset delta -The positive or negative shift amount.

Return Value:

Returns a reference to this range after shifting it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::Intersect

void Intersect (const TTextRange & that)

Interface Category:

API.

Purpose:

Computes the intersection of this range and that range. This range is changed to equal the computed intersection of the two ranges. When there is no overlap, this is converted to an empty range.

Calling Context:

Called to produce the intersection of two ranges.

Parameters:

const TTextRange & that -The range to intersect with this range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::GetMaximumRange

static const TTextRange & GetMaximumRange ()

Interface Category:

API.

Purpose:

Gets a reference to the maximum range.

Calling Context:

When you need to use the maximum range. For example, the TText protocol has many interfaces that take TTextRange references. You could use this maximum range as an input to any text function and the function would be applied to the entire text object.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the maximum range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::GetEmptyRange

static const TTextRange & GetEmptyRange ()

Interface Category:

API.

Purpose:

Gets a reference to an empty range.

Calling Context:

When you need to use an empty range.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to an empty range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TTextRange::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Overrides inherited MCollectible function.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator<=

bool operator <= (const TTextRange & that) const

Interface Category:

API.

Purpose:

Compares whether this object is less than or equal to the input object.

Calling Context:

Called to compare this object to another TTextRange object.

Parameters:

const TTextRange & that -The object to compare to this object.

Return Value:

Returns true if this object is less than or equal to the input object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator>=

bool operator >=(const TTextRange & that) const

Interface Category:

API.

Purpose:

Compares whether this object is greater than or equal to the input object.

Calling Context:

Called to compare this object to another TTextRange object.

Parameters:

const TTextRange & that -The object to compare to this object.

Return Value:

Returns true if this object is greater than or equal to the input object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator!=

bool operator != (const TTextRange & that) const

Interface Category:

API.

Purpose:

Inequality operator.

Calling Context:

Called to compare_ this_ object to another TTextRange object.

Parameters:

const TTextRange & that -The object to compare to this object.

Return Value:

Returns true if the objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator<<=

TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromStream -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator>>=

TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toStream -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator=

TTextRange & operator =(const TTextRange & that)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextRange & that -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::~TTextRange

~ TTextRange ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator<

bool operator < (const TTextRange & that) const

Interface Category:

API.

Purpose:

Compares one range against another to see which is the lesser one.

Calling Context:

Called to determine the relative ordering of two text ranges.

Parameters:

const TTextRange & that -The object to compare with this object.

Return Value:

Returns true if this range is less than that range. Returns false if this range is greater than or equal to that range. Ordering is done by comparing the beginning and ending offsets for two ranges. The one with the lesser beginning offset is considered to be the lesser range regardless of the lengths of the ranges involved. When they have the same beginning offset, the one with the lesser ending text offset is the lesser range. When both beginning and ending offsets are the same, the two ranges are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator>

bool operator >(const TTextRange & that) const

Interface Category:

API.

Purpose:

Compares one range against another to see which is the greater one.

Calling Context:

Called to determine the relative ordering of two text ranges.

Parameters:

const TTextRange & that -The object to compare with this object.

Return Value:

Returns true if this range is greater than that range. Returns false if this range is less than or equal to that range. Ordering is done by comparing the beginning and ending offsets for two ranges. The one with the lesser beginning offset is considered to be the lesser range regardless of the lengths of the ranges involved. When they have the same beginning offset, the one with the lesser ending text offset is the lesser range. When both beginning and ending offsets are the same, the two ranges are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextRange::operator==

bool operator ==(const TTextRange & that) const

Interface Category:

API.

Purpose:

Compares one range against another for equivalence.

Calling Context:

When you need to know if two ranges are equivalent.

Parameters:

const TTextRange & that -The object to compare with this object.

Return Value:

Returns true if this range is equal to that range. Two equal ranges have the same beginning offsets, the same ending offsets, and the same lengths.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.