Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
None.
Purpose:
Provides support for handling discontiguous text selections. In particular, this class implements the math needed to provide a user interface for discontiguous selections: Add, Subtract, Intersect, ExclusiveOr, and Invert.
An invariant of TTextRegion is that it cannot contain a TTextRange of length 0.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
This class is not designed for deriving. Text regions are used pervasively with text and performance is critical.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TTextRegion (const TTextRegion & region)
- TTextRegion (const TTextRange & range)
- TTextRegion ()
Interface Category:
API.
Purpose:
- Copy constructor.
- Constructs a contiguous region from a single range.
- Default constructor. Constructs an empty region.
Calling Context:
- Called to copy an object.
- Called to create a contiguous region from a range.
- Called by the stream-in operators.
Parameters:
- const TTextRegion & region -The input region to copy from.
- const TTextRange & range -The input range to copy from.
- Takes no parameters.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::GetCount
TTextCount GetCount () const
Interface Category:
API.
Purpose:
Gets the number of indexes contained within this region.
Calling Context:
When you want to know how many indexes are contained within this region.
Parameters:
Return Value:
Returns the number of indexes contained within this region.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::GetBounds
void GetBounds (TTextRange & bounds) const
Interface Category:
API.
Purpose:
Gets the minimal TTextRange that still contains all the indexes contained within this region.
Calling Context:
When you want to know the bounding offsets for all indexes within this region.
Parameters:
- TTextRange & bounds -The output range set with the bounding offsets for all indexes within this region.
Return Value:
None. See the output range for the bounds information.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
You can not assume that all the indexes contained within the output bounds are part of the region unless the region is contiguous.
Member Function: TTextRegion::IsEmpty
bool IsEmpty () const
Interface Category:
API.
Purpose:
Determines whether this region is an empty one.
Calling Context:
When you want to find out if this region is empty.
Parameters:
Return Value:
Returns true if this region is empty. An empty region is one that contains no indexes.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::IsDiscontiguous
bool IsDiscontiguous () const
Interface Category:
API.
Purpose:
Determines whether the indexes contained within this region are part of multiple discontiguous ranges or part of one contiguous range.
Calling Context:
When you want to know whether this region contains multiple discontiguous ranges or a single contiguous range.
Parameters:
Return Value:
Returns true if the indexes contained within this region are part of multiple discontiguous ranges.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::InRegion
bool InRegion (TTextIndex index) const
Interface Category:
API.
Purpose:
Determines whether a particular index is contained within this region.
Calling Context:
When you want to know whether a particular index is contained within this region.
Parameters:
Return Value:
Returns true if the specified index is contained within this region.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::ShiftBy
void ShiftBy (TTextOffset delta)
Interface Category:
API.
Purpose:
Shifts all indexes in this region by adding the specified amount to each one.
Calling Context:
When you want to shift all the indexes in a region by adding a fixed amount to each one.
Parameters:
- TTextOffset delta -The positive or negative amount to add.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::operator+=
TTextRegion & operator += (TTextOffset delta)
Interface Category:
API.
Purpose:
Shifts all indexes in this region by adding the specified amount to each one.
Calling Context:
When you want to shift all the indexes in a region by adding a fixed amount to each one.
Parameters:
- TTextOffset delta -The positive or negative amount to add.
Return Value:
A reference to this region after it has been shifted.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::operator-=
TTextRegion & operator -=(TTextOffset delta)
Interface Category:
API.
Purpose:
Shifts all indexes in this region by subtracting the specified amount from each one.
Calling Context:
When you want to shift all the indexes in a region by subtracting a fixed amount from each one.
Parameters:
- TTextOffset delta -The positive or negative amount to subtract.
Return Value:
A reference to this region after it has been shifted.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::SetToEmpty
void SetToEmpty ()
Interface Category:
API.
Purpose:
Converts any region into an empty one.
Calling Context:
When you want to make to sure that a region is empty.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
void Add (const TTextRegion & that)
Interface Category:
API.
Purpose:
Adds the input region to this region. This function produces the union of two regions. Afterwards, every index that was in this region or that region is now a part of this region.
Calling Context:
When you need to add one region to another.
Parameters:
- const TTextRegion & that -The region being added to this region.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::Subtract
void Subtract (const TTextRegion & that)
Interface Category:
API.
Purpose:
Subtracts the input region from this region. This function removes the intersecting portion of the two regions from this region. Afterwards, every index that was in this region and in that region is no longer a part of this region.
Calling Context:
When you need to subtract one region from another.
Parameters:
- const TTextRegion & that -The region being subtracted from this region.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::Intersect
void Intersect (const TTextRegion & that)
Interface Category:
API.
Purpose:
Changes this region to contain only the indexes that are part of both this region and the input region. This function removes everything but the overlapping portion of the two regions from this region.
Calling Context:
When you need to find the overlap between two regions.
Parameters:
- const TTextRegion & that -The region being intersected with this region.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::ExclusiveOr
void ExclusiveOr (const TTextRegion & that)
Interface Category:
API.
Purpose:
Changes this region to contain the result of adding the input region to this region and then subtracting the intersection of the input region with this region. This function produces the union of two regions minus their intersection. Afterwards, every index that was a part of this region or that region except for the indexes that were part of both this region and that region are now a part of this region.
Calling Context:
When you need to know the resulting region from doing an exclusive OR of any two regions.
Parameters:
- const TTextRegion & that -The region to exclusive OR with this region.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::Invert
void Invert ()
Interface Category:
API.
Purpose:
Changes this region to contain every index from zero through the maximum index except for the indexes that were originally in this region. Inverting a region is the equivalent of subtracting this region from another region consisting of one contiguous range that spans the domain. Afterwards, every index that was in this region is not anymore and every index that wasn't in this region now is.
Calling Context:
When you want to invert a region.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::Hash
long Hash () const
Interface Category:
API.
Purpose:
Overrides inherited MCollectible function.
Calling Context:
Same as for base class.
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: TTextRegion::operator!=
bool operator != (const TTextRegion & that) const
Interface Category:
API.
Purpose:
Inequality operator.
Calling Context:
Compare this object to another TTextRegion object.
Parameters:
- const TTextRegion & 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: TTextRegion::operator==
bool operator ==(const TTextRegion & that) const
Interface Category:
API.
Purpose:
Equality operator.
Calling Context:
Compare this object to another TTextRegion object.
Parameters:
- const TTextRegion & that -The object to compare to this object.
Return Value:
Returns true if the objects are equal.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::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 the exception TTextException::kInvalidVersionNumber when the streamed in version number cannot be handled.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTextRegion::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: TTextRegion::operator=
- TTextRegion & operator =(const TTextRegion & that)
- TTextRegion & operator =(const TTextRange & that)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TTextRegion & that -The source object for the assignment.
- 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.
~ TTextRegion ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
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.
Copyright©1995 Taligent,Inc. All rights reserved.