Class: TStandardText

Declaration: StandardText.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TText

Inherited By:

TTieredText

Purpose:

TStandardText is a concrete class that implements the full text protocol defined by class TText. Each standard text object contains both Unicode character codes and styling information. Common string manipulation functions, like insert and delete, are provided. Whenever you need a text object, you can create a TStandardText object. However, TText reference parameters are preferred over TStandardText reference parameters in the interfaces you provide to your clients. Only use TStandardText instead of TText in situations where a concrete class is required. In this way, other implementations of the text protocol can also exist and be used polymorphically as TText objects.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is not designed for anything more than simple deriving. Developers can provide their own implementation of the text protocol by deriving directly from the abstract base class, TText. Classes that are derived either directly or indirectly from TText should not override Replace, Insert, and Delete. These member functions have been implemented in TText to use the following atomic member functions: HandleDeleteCharacters, HandleInsertCharacterGap, HandleCopyCharacters, HandleDeleteStyles, HandleInsertStylesGap, and HandleCopyStyles. These handle member functions should be overridden to provide the desired behavior.

Concurrency:

Not multithread safe.

Resource Use:

Due to the dynamic nature of the contents of text objects, the variable amount of characters and associated style information is always allocated on the heap. Large text objects allocate most of their storage on the heap even when the text object itself is allocated on the stack.

Member Function: TStandardText::TStandardText

TStandardText ()
TStandardText (TTextCount extraSpace)
TStandardText (const TStandardText & that)
TStandardText (const TStandardText & that, const TTextRange & thatRange, TTextCount extraSpace =0)
TStandardText (const TText & that, const TTextRange & thatRange =TTextRange :: GetMaximumRange (), TTextCount extraSpace =0)
TStandardText (const UniChar that [], TTextCount thatLength, TTextCount extraSpace =0)
TStandardText (UniChar that, TTextCount extraSpace =0)
TStandardText (const char nullTerminatedArray [], TTextCount extraSpace =0)
TStandardText (const TUnicodeArray & that, TTextCount extraSpace =0)

Interface Category:

API.

Purpose:

Default constructor. Constructs an empty text object.
Constructs an empty text object with extra space.
Copy constructor.
Constructs a text object with the specified text string and extra space allocation.
Constructs a text object with the specified text string and extra space allocation.
Constructs a text object with the specified text string and extra space allocation.
Constructs a text object with the specified text string and extra space allocation.
Constructs a text object with the specified text string and extra space allocation.
Constructs a text object with the specified text string and extra space allocation.

Calling Context:

Called by the stream-in operators or to construct an empty text object.
Called to construct a text object.
Called to copy an object.
Called to construct a text object.
Called to construct a text object.
Called to construct a text object.
Called to construct a text object.
Called to construct a text object.
Called to construct a text object.

Parameters:

Takes no parameters.
TTextCount extraSpace -The amount of extra space to allocate.
const TStandardText & that -The object to copy.
const TStandardText & that -The text instance containing the string with which to instantiate this text instance.
const TTextRange & thatRange -The range of text to extract to create this text instance.
TTextCount extraSpace =0 -The amount of extra space to allocate.
const TText & that -The text instance containing the string with which to instantiate this text instance.
const TTextRange & thatRange =TTextRange :: GetMaximumRange () -The range of text to extract to create this text instance.
TTextCount extraSpace =0 -The amount of extra space to allocate.
const UniChar that [] -The UniChar array with which to instantiate this text instance.
TTextCount thatLength -The number of characters to use from the UniChar array.
TTextCount extraSpace =0 -The amount of extra space to allocate.
UniChar that -A single UniChar with which to instantiate this text instance.
TTextCount extraSpace =0 -The amount of extra space to allocate.
const char nullTerminatedArray [] -The char array with which to instantiate this text instance.
TTextCount extraSpace =0 -The amount of extra space to allocate.
const TUnicodeArray & that -The Unicode array with which to instantiate this text instance.
TTextCount extraSpace =0 -The amount of extra space to allocate.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Many of these constructors allocate only enough space for the text you pass in at instantiation. If you want to allocate more space, do so at construction time.

Member Function: TStandardText::~TStandardText

virtual ~ TStandardText ()

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: TStandardText::GetCharacterAt

virtual UniChar GetCharacterAt (TTextIndex index) const

Interface Category:

API.

Purpose:

Gets the character at a specified index.

Calling Context:

Called to get the character stored at a particular index.

Parameters:

TTextIndex index -The index of the character to get.

Return Value:

The character at the specified index.

Exceptions:

Throws the exception TTextException::kInvalidIndex if the index is less than zero or beyond the current length of the text, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use a TCharacterIterator for fast sequential access. Even random access to more than a few characters will benefit from using a TCharacterIterator.

Member Function: TStandardText::SetCharacterAt

virtual void SetCharacterAt (TTextIndex index, const UniChar thatChar)

Interface Category:

API.

Purpose:

Sets the character at a specified index.

Calling Context:

Called to set the character stored at a specified index.

Parameters:

TTextIndex index -The index of the character to set.
const UniChar thatChar -The new character value.

Return Value:

None.

Exceptions:

Throws the exception TTextException::kInvalidIndex if the index is less than zero or beyond the current length of the text, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use a TCharacterIterator for fast sequential access. Even random access to more than a few characters will benefit from using a TCharacterIterator.

Member Function: TStandardText::GetLength

virtual TTextCount GetLength () const

Interface Category:

API.

Purpose:

Gets the length of the text string encapsulated by this text object.

Calling Context:

Called to get the length of the text string encapsulated by this text object.

Parameters:

Takes no parameters.

Return Value:

The length of the text string encapsulated by this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::IsContiguous

virtual bool IsContiguous () const

Interface Category:

API.

Purpose:

Queries whether the text in this text instance is stored contiguously.

Calling Context:

Called to query whether the text in this text instance is stored contiguously.

Parameters:

Takes no parameters.

Return Value:

Returns true if the text is stored contiguously.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::PartialCopy

virtual TText * PartialCopy (const TTextRange & range, TTextCount extraSpace =0, TMemoryHeap * whichHeap =NIL) const

Interface Category:

API.

Purpose:

Creates a copy of any part of any text object polymorphically. Use this member function when polymorphic extraction of a range of text is required. This is a copy function that passes ownership of new storage to the client instead of an extract function with a client-provided text object as an output parameter. Otherwise, it is not possible to extract a range of text polymorphically.

Calling Context:

Called to get a polymorphic copy of any part of a text object.

Parameters:

const TTextRange & range -The text range in this text object to copy.
TTextCount extraSpace =0 -Similar to constructors, the caller can request additional space be allocated with the newly constructed text object.
TMemoryHeap * whichHeap =NIL -The heap to allocate the new object in.

Return Value:

A copy of the specified text range in a newly created text object is returned. The caller gets ownership of the storage for this new object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::Extract

virtual TTextCount Extract (const TTextRange & thisRange, TText & that) const
virtual TTextCount Extract (const TTextRange & thisRange, TUnicodeArray & that) const
virtual TTextCount Extract (const TTextRange & thisRange, UniChar that [], TTextCount thatMaxCount) const
virtual TTextCount Extract (const TTextRange & thisRange, char that [], TTextCount thatMaxCount) const

Interface Category:

API.

Purpose:

Copies text in the specified text range of this text object into the output text object.
Copies text in the specified text range of this text object into the output TUnicodeArray object.
Copies text in the specified text range of this text object into the output UniChar array. The resulting UniChar array is NOT null terminated.
Copies text in the specified text range of this text object into the output character array. The resulting character array is null terminated. This means that the size of the character array must be one byte more than the length of the text to be extracted. In other words, the length of the character array should be one more than thatMaxCount. Otherwise, the extraction may write off the end of the character array, resulting in heap corruption problems.

Calling Context:

When copying text from one text object to another.
When copying text from a text object into a TUnicodeArray object.
When copying text from a text object into a UniChar array.
When copying text from a text object into a character array.

Parameters:

const TTextRange & thisRange -The text range in this text object to be copied to that text object. thisRange is a guideline. If the range is outside the bounds of the text or thatMaxCount, it will be truncated.
TText & that -The output text instance.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
TUnicodeArray & that -The output TUnicodeArray.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
UniChar that [] -The output UniChar array.
TTextCount thatMaxCount -The maximum number of characters to extract.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
char that [] -The output char array.
TTextCount thatMaxCount -The maximum number of characters to extract.

Return Value:

The number of characters extracted; this can differ from the requested length.

Exceptions:

Throws the exception TTextException::kInvalidRange if the first index in the specified range is less than zero or beyond the current length of the text, if the text object to extract from is the same object as the text object to extract into, or if the current length of the text is less than zero. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

For more accurate extraction of 8-bit character data, use TTranscoder. When extracting into a character array, the resulting array is null terminated. This means that the length of the character array must be one more than thatMaxCount. When extracting into a UniChar array, the resulting array is NOT null terminated.

Member Function: TStandardText::ExtractCharacters

virtual TTextCount ExtractCharacters (const TTextRange & thisRange, TText & that) const

Interface Category:

API.

Purpose:

Copies only the characters in the specified text range of this text object into the output text object. Use Extract instead If you are interested in both the character and style information.

Calling Context:

Called to copy characters from one text object to another.

Parameters:

const TTextRange & thisRange -The text range for the characters in this text object to be copied to that text object.
TText & that -The output text object. The current contents of that are replaced by the characters copied from this text object.

Return Value:

The number of characters extracted; this can differ from the requested length.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::IsStyled

virtual bool IsStyled () const

Interface Category:

API.

Purpose:

Determines if this text object has style information associated with it.

Calling Context:

Called directly to check for styles.

Parameters:

Takes no parameters.

Return Value:

Returns true if there are any styles associated with this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any of the style functions can still be called on text that is unstyled. Setter functions convert text from unstyled text to styled text and set the appropriate style information.

Member Function: TStandardText::StylesAt

virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const
virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Fills in a given style set with the styles of the specified kind that are associated with the specified index. When needed, callers can also get the maximal contiguous text range with the same style information that contains the specified index.

Calling Context:

Called directly to get the styles for a specified index.
Called directly to get the styles for a specified index and the maximal contiguous text range that contains the same style information and the index of interest.

Parameters:

TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & set -The output style set to copy the styles for the specified index into.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.
TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & set -The output style set to copy the styles for the specified index into. The styles in the resulting set are owned by the text. Do not delete them.
TTextRange & currentRunRange -The maximal contiguous text range that contains the output styles and overlaps the index of interest too.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

The starting index of the next style run. A style run is the term used to describe a maximal contiguous text range of text with the same style information.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Clients are not required to concern themselves with the underlying association of style information with the character codes. However, clients that take advantage of this knowledge can do some things more efficiently. For example, it is not necessary to make a StylesAt call for every character in a text object when iterating over style information. Rather, you can take advantage of style run information to make only one StylesAt call for each style run and then jump ahead to the next run (using the returned starting index for the next run). This member function is const in the semantic sense; the information available through the API is not changed. However, the internal state of the object may be changed. If information about a particular style kind is requested, then the corresponding TStyleRuns object may be created in order to cache the information.

Member Function: TStandardText::CopyStylesAt

virtual TStyleSet * CopyStylesAt (TTextIndex indexOfInterest, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind (), TMemoryHeap * whichHeap =NIL) const
virtual TStyleSet * CopyStylesAt (TTextIndex indexOfInterest, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind (), TMemoryHeap * whichHeap =NIL) const

Interface Category:

API.

Purpose:

Creates a new style set on the heap with a copy the styles of the specified kind that are associated with the specified index.
Creates a new style set on the heap with a copy of the styles of the specified kind that are associated with the specified index. Also returns the maximal contiguous text range with the same style information that overlaps the specified index.

Calling Context:

Called directly to copy the styles for a specified index.
Called directly to copy the styles for a specified index and get the maximal contiguous text range that contains the same style information and the index of interest.

Parameters:

TTextIndex indexOfInterest -The index to copy styles from.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to copy.
TTextIndex indexOfInterest -The index to copy styles from.
TTextRange & currentRunRange -The maximal contiguous text range that contains the returned styles and also overlaps the index of interest.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to copy.
TMemoryHeap * whichHeap =NIL -The heap to allocate the new object in.

Return Value:

A copy of the styles of the specified kind at the specified index is returned. The caller gets ownership of the storage for this new object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function uses StylesAt to get the styles of interest. Therefore, this member function is const in the semantic sense; the information available through the API is not changed. However, the internal state of the object may be changed. If information about a particular style kind is requested, then the corresponding TStyleRuns object may be created in order to cache the information.

Member Function: TStandardText::StylesExist

virtual bool StylesExist (const TStyleSet & set, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Determines if any of the characters within the specified text range are styled with all of the styles of the specified kind in the specified style set.

Calling Context:

Called directly to check for the existence of the specified styles anywhere within the specified text range.

Parameters:

const TStyleSet & set -The styles to look for.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind are checked.

Return Value:

Returns true if at least one character within the specified text range is styled with all the styles of the specified kind in the specified style set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::StylesContinuous

virtual bool StylesContinuous (const TStyleSet & set, const TTextRange & range) const

Interface Category:

API.

Purpose:

Determines if every character within the specified text range is styled with all the styles in the specified style set.

Calling Context:

Called directly to check for the existence of the specified styles for every character within the specified text range.

Parameters:

const TStyleSet & set -The styles to look for.
const TTextRange & range -The text range to look at.

Return Value:

Returns true if every character within the specified text range is styled with all the styles in the specified style set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::AllStyles

virtual void AllStyles (TSetOf < TStyle > & returnSet, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Gets the maximal set of styles of the specified kind for the specified text range. It is not required that styles in the returned set be continuous throughout the entire text range. It only matters that a style exist on at least one character in the text range for it to be included in this maximal set of styles.

Calling Context:

Called directly to get the maximal set of styles of the specified kind associated with a specified text range.

Parameters:

TSetOf < TStyle > & set -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the styles found.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The styles in the resulting set are owned by the text. Do not delete them.

Member Function: TStandardText::AllContinuousStyles

virtual void AllContinuousStyles (TStyleSet & returnSet, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Gets the maximal set of continuous styles of the specified kind for the specified text range. It is required that styles in the returned set be continuous throughout the entire text range.

Calling Context:

Called directly to get the maximal set of continuous styles of the specified kind associated with a specified text range.

Parameters:

TStyleSet & set -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the styles found.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::AddStyles

virtual void AddStyles (const TStyle & style, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void AddStyles (const TStyleSet & set, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Adds the specified style to each character within the specified text range.
Adds the styles of the specified kind in the specified style set to each character within the specified text range.

Calling Context:

Called directly to add a single style.
Called directly to add multiple styles at once.

Parameters:

const TStyle & style -The style to add.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to add a single style to.
const TStyleSet & set -The set of styles to add.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to add a set of styles to.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to add. The styles other than this kind are ignored.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Consistent with the style set invariant of only one style of the same category and name in a style set, new styles replace existing styles when the category and the name are the same. In the absence of category and name collisions, the new styles are simply added to what was there already.

Member Function: TStandardText::RemoveStyles

virtual void RemoveStyles (const TStyle & style, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void RemoveStyles (const TStyleSet & set, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())
virtual void RemoveStyles (const TStyleCategory & category, const TStyleName & name, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())
virtual void RemoveStyles (const TStyleKind & styleKind, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void RemoveStyles ()

Interface Category:

API.

Purpose:

Removes the specified style from each character within the specified text range.
Removes the specified styles from each character within the specified text range.
Removes the specified style from each character within the specified text range.
Removes all of the styles of the specified kind from each character in the text object.
Removes all styles from each character in the text object.

Calling Context:

Called directly to remove the specified style.
Called directly to remove the styles of the specified kind that are in the specified set of styles.
Called directly to remove the style of the specified category, name, and kind.
Called directly to remove the styles of the specified kind.
Called directly to remove all styles.

Parameters:

const TStyle & style -The style to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleSet & set -The set of styles to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind are removed.
const TStyleCategory & category -The category to look for.
const TStyleName & name -The name to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind are removed.
const TStyleKind & styleKind -The kind of styles to look for. Only styles of this kind are removed.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The input style or style set is used for comparison with the style information currently associated with text in the specified range. Only a category and name comparison is done. Styles are removed from the text that match the names of the input styles.

Member Function: TStandardText::ReplaceStyles

virtual void ReplaceStyles (const TStyle & replacementStyle, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void ReplaceStyles (const TStyleSet & replacementSet, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Replaces existing styles with the specified style. The styles of the same kind as the specified style are replaced. All other styles are not touched.
Replaces the existing styles of the specified kind with the styles of the specified kind in the specified style set.

Calling Context:

Called directly to replace existing styles with the specified style.
Called directly to replace existing styles the specified set of styles.

Parameters:

const TStyle & style -The style to add after removing the existing styles.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to replace styles in.
const TStyleSet & set -The set of styles to add after removing the existing styles.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to replace styles in.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to be replaced. Only styles of this kind are removed and added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::IsEqualStyles

virtual bool IsEqualStyles (const TText & that, const TTextRange & thatRange, const TTextRange & thisRange =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Compares the style information of this text object with the input text object.

Calling Context:

Called to compare styles of the specified kind in a text range in one text object against styles of the specified kind in a different text range in another text object.

Parameters:

const TText & that -The text object to compare against this text object.
const TTextRange & thatRange -The text range in that text object to be compared against text from this text object.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The text range in this text object to be compared against the text from that text object.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to compare. Only compares styles of this kind.

Return Value:

Returns true if the compared styles are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function uses StylesAt to get the styles to be compared. Therefore, this member function is const in the semantic sense; the information available through the API is not changed. However, the internal state of the object may be changed. If information about a particular style kind is requested, then the corresponding TStyleRuns object may be created in order to cache the information.

Member Function: TStandardText::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

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: TStandardText::operator+

TStandardText operator + (const TText & that) const

Interface Category:

API.

Purpose:

Creates a new text object on the stack consisting of a copy of the text object on the left-hand side with the text object on the right-hand side of the + operator appended to it.

Calling Context:

Called to create a local temporary for the result of appending one text object to another.

Parameters:

const TText & that -The right-hand side text object.

Return Value:

A new stack-based text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::operator=

virtual TText & operator =(const TText & that)
virtual TStandardText & operator =(const TStandardText & that)

Interface Category:

API.

Purpose:

Inherited assignment operator from class TText.
Assignment operator.

Calling Context:

Called when a TText object is polymorphically assigned to a TStandardText object.
Called when one TStandardText object is assigned to another TStandardText object.

Parameters:

const TText & that -The text object being assigned to this text object.
const TStandardText & that -The standard text object being assigned to this text object.

Return Value:

Returns a TText reference to this text object.
Returns a TStandardText reference to this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Currently, if this text object is styled and you assign an unstyled text object to it, after the assignment this text object is still considered a styled text object. For example, the function TStandardText::IsStyled returns true. This will be fixed in a later release.

Member Function: TStandardText::operator+=

virtual TText & operator += (const TText & that)
virtual TStandardText & operator += (const TStandardText & that)

Interface Category:

API.

Purpose:

Appends the contents of the input text object to the current contents of this text object.

Calling Context:

Called when a TText object is polymorphically appended to a TStandardText object.
Called when one TStandardText object is appended to another TStandardText object.

Parameters:

const TText & that -The text object being appended to this text object.
const TStandardText & that -The standard text object being appended to this text object.

Return Value:

Returns a TText reference to this text object.
Returns a TStandardText reference to this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::operator>>=

virtual 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:

If you write a simple derived class of TStandardText that adds any instance data, you must override this virtual member function and provide your own streaming operator that calls this one first before streaming your own data.

Member Function: TStandardText::operator<<=

virtual 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 version number that was streamed in is not supported. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TStandardText::PartialStreamOut

virtual void PartialStreamOut (TStream & toStream, const TTextRange & range) const

Interface Category:

API.

Purpose:

Streams out a complete text object for the text contained within the specified text range.

Calling Context:

Called when you want to stream out only part of an existing text object. The standard streaming operators only work on the entire text object.

Parameters:

TStream & toStream -The stream to write data out to.
const TTextRange & range -The text range to be streamed out.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::GetEmptyText

static const TText & GetEmptyText ()

Interface Category:

API.

Purpose:

Returns a const reference to an empty text object.

Calling Context:

Called to save the unnecessary construction of another text object when a const reference to an empty text object is needed.

Parameters:

Takes no parameters.

Return Value:

Returns a const reference to an empty text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Unfortunately, the construction of even the smallest things have enough of a cost to make this optimization worthwhile.

Member Function: TStandardText::HandleCopyStyles

virtual void HandleCopyStyles (const TText & that, TTextOffset thatOffset, TTextCount thatLength, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the text starting at the specified offset. This member function replaces the current styles with the styles to be copied. If there are no styles to be copied, then the specified range of the text that the styles are being copied into becomes unstyled. The behavior of HandleCopyStyles and CopyStyles can be different. For instance, for paragraph-based styles CopyStyles only copies the paragraph-based styles from the first paragraph of the specified range, while HandleCopyStyles copies the styles paragraph-by-paragraph.

Calling Context:

Called to copy the styles from one TText object into another. This member function should only be called when the corresponding text has been changed, so this member function is usually called directly after HandleInsertStylesGap has been called.

Parameters:

const TText & that -The TText object from which the styles are to be copied.
TTextOffset thatOffset -The offset at the beginning of the range of styles to be copied.
TTextCount thatLength -The length of the range of styles to be copied.
TTextOffset thisOffset -The beginning offset where the styles are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::HandleInsertStylesGap

virtual void HandleInsertStylesGap (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when new characters have been inserted into the text.

Calling Context:

Called when new characters have been inserted into the text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of newly inserted characters.
TTextCount length -The length of the range of newly inserted characters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be called after the new characters have been inserted into the text, because the characters can have an affect on how the style runs should be updated. For instance, if a paragraph marker is added, the paragraph-based style runs have to be updated to take this into account.

Member Function: TStandardText::HandleDeleteStyles

virtual void HandleDeleteStyles (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when characters are going to be deleted from the text.

Calling Context:

Called when characters are going to be removed from the text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of characters that are going to be removed.
TTextCount length -The length of the range of characters that are going to be removed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be called before the characters are actually removed from the text, because the characters can have an affect on how the style runs should be updated. For instance, if a paragraph marker is one of the characters being removed, the paragraph-based style runs have to be updated to take this into account.

Member Function: TStandardText::HandleCopyCharacters

virtual void HandleCopyCharacters (const TText & that, TTextOffset thatOffset, TTextCount thatLength, TTextOffset thisOffset)
virtual void HandleCopyCharacters (const UniChar that [], TTextCount thatLength, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the characters from a specified range of a given TText object or UniChar array into the text starting at the specified offset.

Calling Context:

Called to copy the characters from a TText object or UniChar array into another TText object.

Parameters:

const TText & that -The TText object to copy the characters from.
TTextOffset thatOffset -The offset at the beginning of the range of characters to be copied.
TTextCount thatLength -The length of the range of characters to be copied.
TTextOffset thisOffset -The beginning offset where the characters are to be copied into.
const UniChar that [] -The array of characters to copy.
TTextCount thatLength -The length of the array of characters.
TTextOffset thisOffset -The beginning offset where the characters are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the current characters in the text are not to be replaced, then HandleInsertCharacterGap must be called before this member function is used in order to create an opening in the text where the new characters are to be added.

Member Function: TStandardText::HandleInsertCharacterGap

virtual void HandleInsertCharacterGap (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Opens up space in the text where new characters are to be added by calling the HandleCopyCharacters member function. For instance, to insert characters into text, call HandleInsertCharacterGap to create a gap where the new characters are to be added, then call HandleCopyCharacters to fill that gap in with the new characters.

Calling Context:

Called to open a gap in the text where new characters are to be inserted.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range where the gap is to be created.
TTextCount length -The length of the gap to create.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be followed by a call to HandleCopyCharacters in order to initialize the new character values. This member function does not initialize any of the values within the gap that it creates.

Member Function: TStandardText::HandleDeleteCharacters

virtual void HandleDeleteCharacters (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Deletes the characters in the specified range of text, and collapses the character storage to completely remove the gap that is left when the characters are deleted.

Calling Context:

Called to delete the characters from a range of text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of characters to delete.
TTextCount length -The length of the range of characters to delete.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::GetStyleBounds

virtual void GetStyleBounds (TTextIndex indexOfInterest, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

For a specified style kind, this member function determines the maximal contiguous text range with the same style information that contains the specified index. For instance, for paragraph-based styles the resulting range is the range of the paragraph containing the specified index.

Calling Context:

Called directly to obtain boundary information about the styles of a specified kind at a specified index.

Parameters:

TTextIndex indexOfInterest -The index to get the style boundary information for.
TTextRange & currentRunRange -The resulting range.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is const in the semantic sense; the information available through the API is not changed. However, the internal state of the object may be changed. If information about a particular style kind is requested, then the corresponding TStyleRuns object may be created in order to cache the information.

Member Function: TStandardText::GetStyleKinds

virtual void GetStyleKinds (TSetOf < TStyleKind > & returnSet) const

Interface Category:

API.

Purpose:

Generates the complete set of the kinds of styles that are being applied to the text. This member function is used to get all of the styles in a particular range, regardless of kind. For instance, to get all of the styles at a given index, use this member function to get all of the kinds of styles, then iterate through the resulting set calling StylesAt for each kind.

Calling Context:

Called directly to get the complete set of the kinds of styles that are being applied to the text.

Parameters:

TSetOf < TStyleKind > & returnSet -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the kinds of styles that are being applied to the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The TStyleKind objects in the returned set are owned by the text. Do not modify or delete them.

Member Function: TStandardText::CopyStyles

virtual void CopyStyles (const TText & that, const TTextRange & thatRange, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the text starting at the specified offset. The behavior of HandleCopyStyles and CopyStyles can be different. For instance, for paragraph-based styles CopyStyles only copies the paragraph-based styles from the first paragraph of the specified range, while HandleCopyStyles copies the styles paragraph-by-paragraph.

Calling Context:

Called to copy the styles from one TText object into another.

Parameters:

const TText & that -The TText object from which the styles are to be copied.
const TTextRange & thatRange -The range of styles to be copied.
TTextOffset thisOffset -The beginning offset where the styles are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardText::GetConstUniCharChunk

virtual const UniChar * GetConstUniCharChunk (TTextIndex indexOfInterest, TTextIndex & chunkStart, TTextCount & chunkLength) const

Interface Category:

API.

Purpose:

Returns a const pointer to the contiguous block of text storage containing the character at the specified index, and determines the starting index and the length of the storage that is returned. When the specified index is out of bounds, the return value is NIL and the length is 0. Note: There is currently a known bug in TStandardText::GetConstUniCharChunk which is preventing it from returning NIL when the specified index is outside the bounds of the text. This bug is expected to be fixed in the next release.

Calling Context:

Called only by character or text iterators.

Parameters:

TTextIndex indexOfInterest -The index to get the contiguous block of text storage for.
TTextIndex & chunkStart -The output index indicating where the resulting contiguous block of text storage begins.
TTextCount & chunkLength -The output length of the resulting contiguous block of text storage.

Return Value:

Returns a const pointer to the contiguous block of text storage containing the character at the specified index, and fills in the values representing the starting index and the length of the storage that is returned. When the specified index is out of bounds, the return value is NIL and the length is 0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function should only be used by character or text iterators. It is very dangerous, as it exposes the internal storage of the text.

Member Function: TStandardText::GetUniCharChunk

virtual void GetUniCharChunk (TTextIndex indexOfInterest, UniChar * & chunkPtr, TTextIndex & chunkStart, TTextCount & chunkLength)

Interface Category:

API.

Purpose:

Gets a pointer to the contiguous block of text storage containing the character at the specified index, and determines the starting index and the length of the resulting storage. When the specified index is out of bounds, the resulting pointer is NIL and the length is 0.

Calling Context:

This member function should only be used by character or text iterators.

Parameters:

TTextIndex indexOfInterest -The index to get the contiguous block of text storage for.
UniChar * & chunkPtr -The pointer to be set to point to the contiguous block of text storage.
TTextIndex & chunkStart -The output index indicating where the resulting contiguous block of text storage begins.
TTextCount & chunkLength -The output length of the resulting contiguous block of text storage.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function should only be used by character or text iterators. It is very dangerous, as it exposes the internal storage of the text.

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