IText

The IText class provides a variable length, styled Unicode text storage object.

This class mnages the storage automatically, and provides a protocol to access and change the characters and styles. The protocol is a superset of the ANSI standard basic_string protocol; the protocol always represents the characters using Unicode.

Generally, ITexts are created on the stack rather than the heap. An IText is merely a smart pointer to a separate internal storage object which is allocated on the heap, so it's generally not necessary to allocate the IText there as well. Also, because IText is just a smart pointer, copy and assignment performance are guaranteed to be good enough to allow IText to be used with value semantics when used as a function parameter or return value.

Do not derive from this class.

Subclassing


IText - Member Functions and Data by Group

Constructors & Destructor

Use the constructors and destructor in this group to create and destroy objects of class IText.


[view class]
~IText
public:
~IText()
Destroys objects of class IText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IText


Overload 1
Constructs and initializes an IText from a null-terminated array of UniChar data.
public:
IText(const UniChar* that)

that
A pointer to the characters to copy into the new IText (which will be unstyled). "that" is considered to point to a null-terminated Unicode string; the length of "that" is determined by searching for UUnicodeSpecial::kNull.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Constructs and initializes an IText to a string that is the character specified by "that" repeated "thatCopies" times.
public:
IText(length_type thatCopies, UniChar that)

thatCopies
The number of times to repeat "that" in the new IText.
that
The character to repeat.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Constructs and initializes an IText from a null-terminated array of char.
public:
IText(const char* that)
The incoming char data is assumed to be encoded according to the current code page. For text following any other encoding standard, use a transcoder.

that
The null-terminated array of chars used to initialize the object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Constructs and initializes an IText from an IString.
public:
IText(const IString& that)
The incoming IString is assumed to be encoded according to the current code page. If it uses any other encoding standard, use a transcoder.

that
The string of characters used to initialize the text object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Constructs and initializes an IText from a substring of another IText.
public:
IText( const IText& that, offset_type thatPos, length_type thatLength )

that
The IText containing the text to copy (both characters and styles are copied).
thatPos
The position of the first character in "that" to copy into the new IText.
thatLength
The number of characters in the subrange of "that" to copy into the new IText, or npos, which specifies all characters in "that" from thatPos to the end.

Exception

IInvalidParameter if thatPos > that.length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
Constructs and initializes an IText from an array of raw UniChar data.
public:
IText(const UniChar that [ ], length_type thatLength)

that
A pointer to the characters to copy into the new IText (which will be unstyled).
thatLength
The number of characters in the buffer pointed to by "that".

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
Constructs and initializes an IText from another IText (copy constructor).
public:
IText(const IText& that)
Because an IText is merely a pointer to a separate storage object, which can be shared among ITexts, copy constructor performance is guaranteed to be fast enough to allow IText to be used with value semantics when used as a function parameter or return value.

that
The IText to copy (both characters and styles are copied).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
Constructs and initializes an IText from a single UniChar.
public:
IText(UniChar that)

that
The characters to copy into the new IText object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
Creates an empty IText
public:
IText()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 10
Constructs and initializes an IText from a substring of another IText.
public:
IText(ITextIterator thatFrom, ITextIterator thatTo)

thatFrom
refers to the first character to copy
thatTo
refers to the character after the last character to copy

Exception

IInvalidParameter if thatFrom or thatTo don't form a proper range

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Accessing Characters

Use the functions in this group to obtain a reference to a character or replace a character in the current IText object.


[view class]
at
Same as operator[](pos).


Overload 1
public:
UniChar at(offset_type pos) const

pos
The given position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
ICharacterReference at(offset_type pos)

pos
The given position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
at_put
public:
void at_put(offset_type pos, UniChar newChar)
Replaces the character at the specified position with the specified character. The new character does not take on the styles of the characters around it, or the styles of the character it replaces.

pos
The position of the character the be replaced.
newChar
The replacement character.

Exception

IInvalidParameter if pos >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator []
Returns a reference to the character at the specified position in the IText.


Overload 1
Returns the character at the specified position in the IText.
public:
UniChar operator [](offset_type pos) const

pos
The given position.

Return
If pos == length(), UUnicodeSpecial::kNull; otherwise, the specified character

Exception

IInvalidParameter if pos > length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
ICharacterReference operator [](offset_type pos)

pos
The given position.

Return
An ICharacterReference referring to the specified character. The ICharacterReference returned by this function is only guaranteed to refer to the correct character until the next call to c_str(), data(), or a non-const member of this IText. (ICharacterReference is semantically equivalent to a live UniChar&, but safer.)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Adding and Removing Styles

Use the functions in this group to add and remove styles from the IText object.


[view class]
addStyles
Applies the specified style to the specified range. The specified styles supercede any of the same class already applied anywhere within the specified range. If the specified styles include paragraph styles, they are applied to the whole paragraphs containing the specified range.


Overload 1
public:
void addStyles( const ITextStyle& style, offset_type starting = 0, length_type count = npos )
This version of the function applies a single style to the specified range.

style
The style to apply.
starting
The offset of the first character in the range to apply the style to.
count
The number of characters in the range to apply the style to. npos may be used for this parameter, and means "add these styles to all characters from starting to the end"

Exception

IInvalidParameter if starting >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Applies the specified styles to the specified range.
public:
void addStyles( const ITextStyleSet& styles, offset_type starting = 0, length_type count = npos )
This version of the function allows the user to apply multiple styles in a single step. It is equivalent to calling addStyles() repeatedly, once for each style in the style set.

style
A style set containing the styles to apply.
starting
The offset of the first character in the range to apply the styles to.
count
The number of characters in the range to apply the styles to. npos may be used for this parameter, and means "add these styles to all characters from starting to the end"

Exception

IInvalidParameter if starting >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeStyles
Removes any styles matching the classes of the specified style or styles from the specified range. Only the classes of the specified styles are significant; their values are ignored. If the specfied styles include paragraph styles, the matching paragraph styles are removed from the whole paragraphs containing the specified range.


Overload 1
public:
void removeStyles( offset_type starting = 0, length_type count = npos )
This version removes ALL styles applied to the specified range of text (which means it removes all paragraph styles from the paragraphs containing the specified range).

starting
The offset of the first character in the range to remove the styles from.
count
The number of characters in the range to remove the styles from. npos may be used for this parameter, and means "remove these styles from all characters from starting to the end"

Exception

IInvalidParameter if starting >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
void removeStyles( const ITextStyleSet& styles, offset_type starting = 0, length_type count = npos )
This version allows the user to remove several styles in a single step. It is equivalent to calling removeStyles() repeatedly, once for each style in the style set.

style
A style set containing the styles to remove (all styles matching the class of a style in this set are removed; it doesn't matter if their values also match).
starting
The offset of the first character in the range to remove the styles from.
count
The number of characters in the range to remove the styles from.
count
npos may be used for this parameter, and means "remove these styles from all characters from starting to the end"

Exception

IInvalidParameter if starting >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
void removeStyles( const ITextStyle& style, offset_type starting = 0, length_type count = npos )

style
The style to remove (all styles matching this style's class are removed; it doesn't matter if their values match this style's value).
starting
The offset of the first character in the range to remove the style from.
count
The number of characters in the range to remove the style from. npos may be used for this parameter, and means "remove these styles from all characters from starting to the end"

Exception

IInvalidParameter if starting >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Appending Characters

Use the functions in this group to append characters to the IText object.


[view class]
append
Appends characters at the end of the IText. The new characters retain their character styles (raw UniChars are considered unstyled), and paragraph styles are propagated. It is legal to append characters from an IText into itself.


Overload 1
public:
IText& append( const UniChar that [ ], length_type thatLength )

that
A pointer to the characters to append. The characters are appended as unstyled text; they don't automatically take on any styles.
thatLength
The number of characters in the buffer pointed to by "that".

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IText& append(length_type thatCopies, UniChar that)
This version appends a single character thatCopies times.

that
character to repeat
thatCopies
number of times to repeat "that"

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IText& append(const UniChar* that)

that
A pointer to the string to append, which is a null-terminated Unicode string. The length of "that" is determined by searching for UUnicodeSpecial::kNull The characters are appended as unstyled text; they don't automatically take on any styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IText& append(const IText& that)

that
The text to append (both styles and characters are appended). May be the same as *this.

Exception

IInvalidRequest if the resulting length would be greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IText& append( const IText& that, offset_type thatPos, length_type thatLength )

that
The IText containing the text to append (both styles and characters are appended). May be the same as *this.
thatPos
The position of the first character in "that" to append.
thatLength
The number of characters in "that" which we want to append, or npos, which specifies all characters in "that" from thatPos to the end.

Exception

IInvalidParameter if thatPos > that.length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IText& append(ITextIterator thatFrom, ITextIterator thatTo)

thatFrom
iterator referring to the first character in the source string (both characters and styles are appended)
thatTo
iterator referring to the position AFTER the last character in source string

Exception

IInvalidParameter if thatFrom and thatTo do not form a proper range

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator +=


Overload 1
public:
IText& operator +=(UniChar that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IText& operator +=(const UniChar* that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IText& operator +=(const IText& that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment Operators and Functions

Use the operators and functions in this group to replace the IText contents--its characters and styles--with the given values.


[view class]
assign
Replaces the entire contents of *this (characters and styles) with the specified text.


Overload 1
public:
IText& assign(length_type thatCopies, UniChar that)
This version replaces the entire contents of *this with a single Unicode character repeated thatCopies times. *this will be unstyled after this operation.

that
character to repeat
thatCopies
number of times to repeat "that"

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IText& assign( const IText& that, offset_type thatPos, length_type thatLength )

that
An IText containing the new text. May be the same as *this.
thatPos
The position of the first character in "that" to copy into *this.
thatLength
The number of characters from "that" to copy into *this, or npos, which specifies all characters in "that" from thatPos to the end.

Exception

IInvalidParameter if thatPos > that.length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IText& assign(const IText& that)

that
The new text. May be the same as *this (which would do nothing).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IText& assign( const UniChar that [ ], length_type thatLength )

that
A pointer to the characters to copy into *this. Note that *this will be unstyled after this operation.
thatLength
The number of characters in the buffer pointed to by "that".

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IText& assign(ITextIterator thatFrom, ITextIterator thatTo)

thatFrom
An iterator referring to the first character in the source string
thatTo
An iterator referring to th position AFTER the last character in the source string

Exception

IInvalidParameter if thatFrom and thatTo do not form a proper range

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IText& assign(const UniChar* that)

that
A pointer to a null-terminated Unicode string containing the characters to copy into *this. The length of "that" is determined by searching for UUnicodeSpecial::kNull. *this will be unstyled after this operation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =


Overload 1
public:
IText& operator =(UniChar that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IText& operator =(const UniChar* that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IText& operator =(const IText& that)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparing the IText Object with Other Entities

Use the functions in this group to compare the current IText object with the given entities and values.


[view class]
compare
This function compares this IText to another IText. This is a bitwise lexicographic compare: The result of the comparison is the result of comparing the numeric (Unicode) values of the first pair of nonmatching characters between the strings. If one string is a proper substring of the other, the shorter string compares less. Styles are not taken into account by the compare() functions.


Overload 1
Compares a subrange of this IText to another IText.
public:
int compare( offset_type thisPos, length_type thisLength, const IText& that ) const

thisPos
The offset of the first character from *this to use in the comparison.
thisLength
The length of the subrange of *this to use in the comparison, or npos, which specifies all characters in *this from thisPos to the end.

Return
0 if the two strings are equal, -1 if the specified subrange of *this is less than "that," and 1 if the specified subrange of *this is greater than "that."

Exception

IInvalidParameter if thisPos > this->length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Compares a subrange of this IText to a subrange of another IText.
public:
int compare( offset_type thisPos, length_type thisLength, const IText& that, offset_type thatPos, length_type thatLength ) const

thisPos
The offset of the first character from *this to use in the comparison.
thisLength
The length of the subrange of *this to use in the comparison, or npos, which specifies all characters in *this from thisPos to the end.
that
The IText containing the characters to compare against. May be the same as *this.
thatPos
The offset of the first character from "that" to use in the comparison.
thatLength
The length of the subrange of "that" to use in the comparison, or npos, which specifies all characters in "that" from thatPos to the end.

Return
0 if the two strings are equal, -1 if the specified subrange of *this is less than the specified subrange of "that," and 1 if the specified subrange of *this is greater than the specified subrange of "that."

Exception

IInvalidParameter if thisPos > this->length() or thatPos > that.length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Compares this IText to a null-terminated Unicode string.
public:
int compare(const UniChar* that) const

that
A pointer to the characters to compare against. "that" is considered to point to a null-terminated Unicode string; i.e., the length of "that" is determined by searching for UUnicodeSpecial::kNull.

Return
0 if the two strings are equal, -1 if *this is less than "that," and 1 if *this is greater than "that."

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Compares a subrange of this IText to a sequence of Unicode characters.
public:
int compare( offset_type thisPos, length_type thisLength, const UniChar that [ ], length_type thatLength ) const

thisPos
The offset of the first character from *this to use in the comparison.
thisLength
The length of the subrange of *this to use in the comparison, or npos, which specifies all characters in *this from thisPos to the end.
that
A pointer to the characters to compare against.
thatLength
The number of characters in the buffer pointed to by "that".

Return
0 if the two strings are equal, -1 if the specified subrange of *this is less than "that," and 1 if the specified subrange of *this is greater than "that."

Exception

IInvalidParameter if thisPos > this->length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Compares this IText to another IText.
public:
int compare(const IText& that) const

that
The IText to compare against.

Return
0 if the two strings are equal, -1 if *this is less than "that," and 1 if *this is greater than "that."

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hash
public:
long hash() const
Generates a hash value for the characters in the IText. Styles are not significant when computing a hash value. The hash value is cached for performance.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Converting Text

Use the functions in this group to return converted text.


[view class]
operator const char *
public:
operator const char *() const
Returns a pointer to an array of char that is equivalent to the contents of "this" transcoded into the current code page. To convert the text to any other encoding standard, use a transcoder. The storage is owned by the IText, and the pointer is guaranteed to be good only until the next call to c_str(), data(), or a non-const member of the IText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator const UniChar *
public:
operator const UniChar *() const
Same as c_str().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Debugging

Use the functions in this group to debug the IText object.


[view class]
printDebugInfo
public:
void printDebugInfo() const
Dumps the characters (transcoded to ISO 8859-1) and styles, potentially along with some other internal values, in human-readable form suitable for debugging.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Deleting Characters

Use the functions in this group to delete characters from the IText object.


[view class]
erase
The characters following the deleted ones are moved up to "fill up the hole," and styles are re-propagated.


Overload 1
Removes characters from an IText.
public:
IText& erase( offset_type pos = 0, length_type numChars = npos )

pos
The offset of the first character to delete.
numChars
The number of characters to delete, or npos, which causes all characters from "pos" to the end to be deleted.

Exception

IInvalidParameter if pos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Removes a single character from an IText.
public:
ITextIterator erase(ITextIterator pos)

pos
An iterator referring to the character to delete.

Return
pos (which is not changed, and now refers to the first character after the deleted one)

Exception

IInvalidParameter if pos doesn't refer to a valid character in *this

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Removes characters from an IText.
public:
ITextIterator erase(ITextIterator from, ITextIterator to)

from
An iterator referring to the first character to delete.
to
An iterator referring to the first character AFTER the range to delete (This character is not deleted, and will be at the position referred to by "from".)

Return
"from" (which is not changed, and now refers to the first character after the deleted ones)

Exception

IInvaidParameter if "from" and "to" do not form a proper range on *this.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Extracting a Substring

Use the function in this group to obtain an IText object containing the substring extracted from the current IText object.


[view class]
substr
public:
IText substr( offset_type pos = 0, length_type length = npos ) const
Returns a new IText whose contents are equal to the specified subrange of the original IText. (a.substr(x, y) is the same as IText(a, x, y) )

pos
Position of first character to extract.
length
Number of characters to extract. "npos" can be used to mean "all characters from pos to the end"

Exception

IInvalidParameter if pos >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Extracting and Swaping Text

Use the functions in this group to extract a range of text from an IText object as a UniChar array or to exchange the contents of two IText objects.


[view class]
copy
public:
length_type copy( UniChar that [ ], length_type maxChars, offset_type startPos = 0 ) const
Extracts a subrange of an IText into an array of UniChar.

that
A pointer to an array of UniChar that will receive the extracted characters
maxChars
The maximum number of characters to copy. This will generaly be either the length of the substring the caller is interested in, or the number of characters the caller has allocated storage for.

Return
the number of characters copied (which will be less than or equal to maxChars).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
swap
public:
void swap(IText& that)
Exchanges the contents of two ITexts.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting Iterators

Use the functions in this group to obtain iterators that refer to various positions within the IText object.


[view class]
begin
Returns an iterator that refers to the first character in the IText.


Overload 1
public:
IConstTextIterator begin() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
ITextIterator begin()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
end
Returns the past-the-end iterator for the IText (i.e., an iterator that refers to the position immediately beyond the last character).


Overload 1
Returns the past-the-end iterator for the IText.
public:
ITextIterator end()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns the past-the-end iterator for the IText.
public:
IConstTextIterator end() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rbegin
Returns a reverse iterator referring to the last character in the IText.


Overload 1
public:
IReverseConstTextIterator rbegin() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IReverseTextIterator rbegin()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rend
Returns the past-the-beginning reverse iterator for the IText.


Overload 1
public:
IReverseTextIterator rend()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IReverseConstTextIterator rend() const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting Style Information

Use the functions in this group to obtain current style and style run information for positions or ranges within the ITextObject.


[view class]
continuousStylesOver


Overload 1
Returns all the styles which are present and have the same value across the entire specified range.
public:
bool continuousStylesOver( offset_type starting, length_type count, ITextStyleSet& styles ) const

starting
Starting offset of the range of interest
count
Length of the range of interest
styles
Receives copies of all styles that are present and have a consistent value across the entire range specified by "starting" and "count." This style set is emptied out before being filled in with these styles.

Return
True if there are any styles that exist and have a consistent value across the entire range of interest, false if there aren't.

Exception

IInvalidParameter if "starting" >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns all the styles of the specified propagation type which are consistent across the entire specified range.
public:
bool continuousStylesOver( offset_type starting, length_type count, ITextStyleSet& styles, ITextStyle::EStylePropagation propagationToMatch ) const

starting
Starting offset of the range of interest
count
Length of the range of interest
styles
Receives copies of all styles of the specified propagation type that are present and have a consistent value across the entire range specified by "starting" and "count." This style set is emptied out before being filled in with these styles.
propagationToMatch
Propagation type of interest. ITextStyle::kMaximumPropagation matches styles of all propagation types.

Return
True if there are any styles of the specified propagation type that exist and have a consistent value across the entire range of interest, false if there aren't.

Exception

IInvalidParameter if "starting" >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isStyled
Returns true if any styles are applied to any part of the IText.
public:
bool isStyled() const
Returns true if there are any styles aplied to any part of the IText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maximumStyleSpan
Returns the maximum range over which the specified style has the specified value. Returns the maximum range over which the specified styles have the specified values.


Overload 1
Returns the maximum range over which the specified styles have the specified values.
public:
bool maximumStyleSpan( offset_type position, const ITextStyleSet& set, offset_type& starting, length_type& count ) const
Checks the styles at "position." If they include all of the styles in "set," and all of their values match the values of the style in "set," returns true, and "starting" and "count" represent the range over which those styles have those values (even if other styles vary). If the styles at "position" don't include all of the styles in "set," or if any corresponding styles don't have the same value, returns false, and "starting" and "count" represent the range over which the styles in the text don't match the styles in "set."

position
The position at which to check styles.
set
The style set containing the sought styles.
starting
If the return value is true, receives starting offset of the range over which the specified styles have the specified values. If the return value is false, receives starting offset of the range over which the specified styles do not have the specified values.
count
If the return value is true, receives length of the range over which the specified styles have the specified values. If the return value is false, receives the length of the range over which the specified styles do not have the specified values.

Return
True if all of the styles in "set" match styles in effect at "position" in both class and value, false otherwise.

Exception

IInvalidParameter if "position" >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool maximumStyleSpan( offset_type position, const ITextStyle& style, offset_type& starting, length_type& count ) const
Checks the styles at "position." If they include the style specified by "style" and that style has the same value as "style," returns true, and "starting" and "count" represent the range over which that style has that value (even if other styles vary). If the styles at "position" don't include "style," or "style" has a different value than the corresponding style in effect at "position," returns false, and "starting" and "count" represent the range over which that style either doesn't exist or has a different value.

position
The position at which to check styles.
style
The style to search for
starting
If the return value is true, receives the starting offset of the range over which the specified style has the specified value. If the return value is false, receives the starting offset of the range over which the specified style does not have the specified value.
count
If the return value is true, receives the length of the range over which the specified style has the specifid value. If the return value is false, receives the length of the range over which the specified style does not have the specified value.

Return
True if "style" matches one of the styles in effect at "position" in both class and value, false if it doesn't.

Exception

IInvalidParameter if "position" >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sameCharacters
Returns TRUE if the characters in *this and "other" match exactly.
public:
bool sameCharacters(const IText& other) const
Returns true if the characters in *this and "other" match exactly. (same as operator==() )

other
A constant reference to the IText object to be compared with this one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sameStyledText
Returns TRUE if both the characters and styles in *this and "other" match exactly.
public:
bool sameStyledText(const IText& other) const
Returns true if both the characters and styles in *this and "other" match exactly.

other
A constant reference to the IText object to be compared with this one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stylesAt
Returns style-run information for the specified position.


Overload 1
public:
const ITextStyleSet* stylesAt( offset_type position, offset_type& starting, length_type& count ) const

position
The position we're interested in getting style information for
starting
Receives the starting offset of the style run containing the specified position
count
Receives the length of the style run containing the specified position

Return
A pointer to a style set containing the styles in effect at the given position. If the text is unstyled at the given position, this set will be empty. "starting" and "count" represent the range over which the same styles (and no others) are applied to the text. This pointer is guaranteed to be good only until the next call to a non-const member of IText.

Exception

IInvalidParameter if "position" >= length()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
void stylesAt( offset_type position, ITextStyleSet& set, offset_type& starting, length_type& count, ITextStyle::EStylePropagation propagationToMatch = ITextStyle::kMaximumPropagation ) const
Use this version of stylesAt() to narrow the function to consider only styles of a given propagation type. It also copies the styles into a fill-in parameter rather than returning a const pointer to a style set.

position
The position to get style information for
set
Receives the styles in effect at the specified position ("set" is cleared first). If the caller specifies a propagation type, then "set" receives only the styles of the specified propagation type that are in effect at the given position.
starting
Receives the starting offset of the style run containing the specified position (i.e., the first offset where the styles of the given propagation type are the same as those in effect at the specified position).
count
Receives the length of the style run containing the specified position (i.e., the length of the range over which the styles of the given propagation type are the same as those in effect at the specified position).
propagationToMatch
The propagation type we're interested in. Only styles of the given propagation type will be returned in "set," and only styles of the given propagation type will be considered in determining the values returned in "starting" and "count." If the caller passes ITextStyle::kMaximumPropagation, styles of all propagation types are considered.

Exception

IInvalidParameter if "position" >= length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Inserting Characters

Use the functions in this group to insert one or more characters into the IText object.


[view class]
insert
The original characters following the insertion position are moved to follow the new characters. It is legal to insert characters from an IText into itself. The new characters retain their character styles (raw UniChars are considered unstyled), and paragraph styles are propagated.


Overload 1
Inserts a single character into the IText.
public:
ITextIterator insert(ITextIterator insertPos, UniChar that)

insertPos
an iterator referring to the insertion position
that
The character to insert.

Return
insertPos (which will now refer to the inserted character)

Exception

IInvalidParameter if insertPos isn't a valid iterator on *this

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Inserts characters into the IText.
public:
IText& insert(offset_type insertPos, const UniChar* that)

insertPos
The character offset where the first character of inserted text should go. A value equal to length() appends characters at the end.
that
A pointer to the characters to insert. "that" is considered to point to a null-terminated Unicode string; the length of the string pointed to by "that" is determined by searching for UUnicodeSpecial::kNull.

Exception

IInvalidRequest if the resulting length would be bigger then max_size().
IInvalidParameter if insertPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Inserts a single character into the IText multiple times.
public:
void insert( ITextIterator insertPos, length_type thatCopies, UniChar that )

insertPos
An iterator referring to the insertion position.
that
The character to repeat.
thatCopies
The number of times to repeat "that".

Exception

IInvalidParameter if insertPos isn't a valid iterator on *this

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Inserts characters into the IText object.
public:
IText& insert(offset_type insertPos, const IText& that)

insertPos
The character offset where the first character of inserted text should go. A value equal to length() appends characters at the end.
that
The text to insert (both the characters and styles are copied). May be equal to *this.

Exception

IInvalidRequest if the resulting length would be bigger then max_size().
IInvalidParameter if insertPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Inserts characters into the IText.
public:
void insert( ITextIterator insertPos, ITextIterator thatFrom, ITextIterator thatTo )

insertPos
An iterator referring to the insertion position.
thatFrom
An iterator referring to the first character in the source string.
thatTo
An iterator referring to the position AFTER last character in the source string.

Exception

IInvalidParameter if insertPos isn't a valid iterator on *this
IInvalidParameter if thatFrom and thatTo do not form a proper range

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
Inserts a single character into the IText multiple times.
public:
IText& insert( offset_type insertPos, length_type thatCopies, UniChar that )

insertPos
The character offset where the first character of inserted text should go. A value equal to length() appends characters at the end.
that
The character to repeat
thatCopies
The number of times to repeat "that"

Exception

IInvalidRequest if the resulting length would be bigger then max_size().
IInvalidParameter if insertPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
Inserts characters into the IText object.
public:
IText& insert( offset_type insertPos, const IText& that, offset_type thatPos, length_type thatLength )

insertPos
The character offset where the first character of inserted text should go. A value equal to length() appends characters at the end.
that
An IText containing the text to insert (both character and styles will be copied). May be equal to *this.
thatPos
The offset of the first character from "that" to insert.
thatLength
The number of characters from "that" to insert, or npos, which specifies all characters in "that" from thatPos to the end.

Exception

IInvalidRequest if the resulting length would be bigger then max_size().
IInvalidParameter if thatPos > that.length()
IInvalidParameter if insertPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
Inserts characters into the IText object.
public:
IText& insert( offset_type insertPos, const UniChar that [ ], length_type thatLength )

insertPos
The character offset where the first character of inserted text should go. A value equal to length() appends characters at the end.
that
A pointer to the characters to insert.
thatLength
The number of characters in the buffer pointed to by "that".

Exception

IInvalidRequest if the resulting length would be bigger then max_size().
IInvalidParameter if insertPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
insert_and_propagate_styles
Inserts characters into the IText, and propagates styles over them. Same as the corresponding version of insert(), except that instead of going in as unstyled, the new characters take on the styles of the character preceding them (or, if they're inserted at the very beginning, the styles of the character following them).


Overload 1
Inserts characters into the IText object, and propagates styles over them.
public:
IText& insert_and_propagate_styles( offset_type insertPos, length_type thatCopies, UniChar that )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Inserts characters into the IText object, and propagates styles over them.
public:
IText& insert_and_propagate_styles( offset_type insertPos, const UniChar that [ ], length_type thatLength )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Obtaining Information About the IText Object

Use the functions in this group to obtain information about the IText object such as its size, its maximum capacity, and the number of characters it currently contains.


[view class]
c_str
public:
const UniChar* c_str() const
Returns a pointer to a null-terminated array of UniChar containing the same characters as contained by the IText. This pointer is guaranteed to be valid only until a subsequent call to c_str(), data(), or any non-const member function on the same IText. The calling code must not alter the contents of the array returned by c_str().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
capacity
public:
length_type capacity() const
Returns the number of characters the IText currently has space allocated for.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
data
public:
const UniChar* data() const
Same as c_str(), but the array returned is not required to be null-terminated. A valid pointer is required to be returned even when the IText is empty, however. The calling code must not ater the contents of the array returned by data(). (The default implementation of IText will return the same thing for both c_str() and data().)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
empty
Returns true if this->length() == 0.
public:
bool empty() const
Returns true if this->length() == 0.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
length
public:
length_type length() const
Same as size().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
max_size
public:
length_type max_size() const
Returns the maximum number of characters an IText can hold. Currently, this will always be ULONG_MAX - 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reserve
public:
void reserve(length_type numChars)
Acts as a signal to the IText that characters are about to be added. IText can use this hint as a signal to preallocate space for the new characters. The preallocation is not actually guaranteed to happen, however. If it does, capacity() will return a value greater than or equal to the value passed to reserve(). Otherwise, nothing about the IText is changed. reserve() cannot be used to make the allocated storage of the IText smaller. If numChars is less than capacity(), nothing happens. (The default implementation of reserve() will always allocate the extra memory, except in serious low-memory conditions.)

numChars
The number of characters for which space is reserved.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resize
Sets the size of the IText to a specified number. (i.e., after the user calls resize(), calls to size() will return the value passed to resize()). If the new size is smaller than the IText's current size, characters at the end of the IText are deleted. If the new size is larger than the IText's current size, an appropriate number of copies of the specified pad character are added at the end.


Overload 1
public:
void resize(length_type numChars)
Same as calling the other overload with fillChar == UUnicodeSpecial::kNull.

numChars
The size for the IText object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
void resize(length_type numChars, UniChar fillChar)

numChars
The size for the IText object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
size
public:
length_type size() const
Returns the number of characters in the IText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
storage_chunk
public:
const UniChar* storage_chunk( offset_type searchPos, offset_type& chunkPos, length_type& chunkLength ) const
Returns a pointer to the block of character storage containing the specified position. The pointer returned by this function is not guaranteed to be good after the next call to c_str(), data(), or a non-const member of this IText.

searchPos
The character offset of interest.
chunkPos
Receives the character offset of the first character in the storage chunk returned by this function. (output parameter only)
chunkLength
Receives the number of characters in the storage chunk returned. (output parameter only)

Return
A pointer to the block of character storage containing searchPos. This pointer is not guaranteed to be null-terminated.

Exception

IInvalidParameter if searchPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Replacing Characters

Use the functions in this group to replace characters in the IText object with those of the given entity.


[view class]
replace
Replaces characters in an IText object.


Overload 1
Replaces characters in an IText with characters from a null-terminated Unicode string.
public:
IText& replace( offset_type thisPos, length_type thisLength, const UniChar* that )

thisPos
The character offset of first character to replace
thisLength
The number of characters to replace (npos may be used to say "replace all characters from thisPos to the end")
that
A pointer to the new characters. "that" is considered a pointer to a null-terminated Unicode string; its length is determined by searching for UUnicodeSpecial::kNull.

Exception

IInvalidParameter if thisPos > this->length()
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Replaces characters in an IText with a single character repeated some number of times.
public:
IText& replace( offset_type thisPos, length_type thisLength, length_type thatCopies, UniChar that )

thisPos
The character offset of first character to replace.
thisLength
The number of characters to replace (npos may be used to say "replace all characters from thisPos to the end").
that
The new character.
thatCopies
The number of times to repeat "that".

Exception

IInvalidParameter if thisPos > this->length()
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Replaces characters in an IText with characters from another IText.
public:
IText& replace( offset_type thisPos, length_type thisLength, const IText& that, offset_type thatPos, length_type thatLength )

thisPos
The character offset of first character to replace.
thisLength
The number of characters to replace (npos may be used to say "replace all characters from thisPos to the end").
that
The IText containing the new text (both characters and styles are copied). May be the same as *this.
thatPos
The offset of first character in "that" to use as part of the replacement string.
thatLength
The number of characters from "that" to use as replacement string.

Exception

IInvalidParameter if thisPos > this->length() or thatPos > that.length()
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Replaces characters in an IText with the contents of another IText.
public:
IText& replace( offset_type thisPos, length_type thisLength, const IText& that )

thisPos
The character offset of first character to replace.
thisLength
The number of characters to replace (npos may be used to say "replace all characters from thisPos to the end").
that
The new text (both characters and styles are copied). May be the same as *this.

Exception

IInvalidParameter if thisPos > this->length()
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Replaces characters in an IText with characters from a raw UniChar buffer.
public:
IText& replace( ITextIterator thisFrom, ITextIterator thisTo, const UniChar that [ ], length_type thatLength )

thisFrom
An iterator referring to first character to replace.
thisTo
An iterator referring to first character AFTER the last one to be replaced.
that
A pointer to the new characters.
thatLength
The number of characters pointed to by "that".

Exception

IInvalidParameter if thisFrom and thisTo don't form a proper range on *this
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
Replaces characters in an IText with characters from another IText.
public:
IText& replace( ITextIterator thisFrom, ITextIterator thisTo, ITextIterator thatFrom, ITextIterator thatTo )

thisFrom
An iterator referring to first character to replace.
thisTo
An iterator referring to first character AFTER the last one to be replaced.
thatFrom
An iterator referring to first character to use in replacement string.
thatTo
An iterator referring to position after the last character to use in replacement string.

Exception

IInvalidParameter if thisFrom and thisTo don't form a proper range on *this
IInvalidParameter if thatFrom and thatTo don't form a proper range
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
Replaces characters in an IText with characters from another IText.
public:
IText& replace( ITextIterator thisFrom, ITextIterator thisTo, const IText& that )
Use this function to replace characters in an IText with characters from a null-terminated Unicode string If the original and replacement strings are not the same length, characters are inserted or deleted as necessary to make sure the characters on either side of the text being replaced are not disturbed. It is legal to replace characters in an IText with characters from the same IText, even if the

thisFrom
An iterator referring to first character to replace.
thisTo
An iterator referring to first character AFTER the last one to be replaced.
that
The new text (both characters and styles are copied). May be the same as *this.

Exception

IInvalidParameter if thisFrom and thisTo don't form a proper range on *this
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
Replaces characters in an IText with characters from a raw Unicode buffer
public:
IText& replace( offset_type thisPos, length_type thisLength, const UniChar that [ ], length_type thatLength )

thisPos
The character offset of first character to replace.
thisLength
The number of characters to replace (npos may be used to say "replace all characters from thisPos to the end").
that
A pointer to the new characters.
thatLength
The number of characters pointed to by "that".

Exception

IInvalidParameter if thisPos > this->length()
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 9
Replaces characters in an IText with characters from a null-terminated Unicode string.
public:
IText& replace( ITextIterator thisFrom, ITextIterator thisTo, const UniChar* that )

thisFrom
iterator referring to first character to replace
thisTo
An iterator referring to first character AFTER the last one to be replaced
that
A pointer to the new characters. "that" is considered a pointer to a null-terminated Unicode string; its length is determined by searching for UUnicodeSpecial::kNull.

Exception

IInvalidParameter if thisFrom and thisTo don't form a proper range on *this
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 10
Replaces characters in an IText with a single character repeated some number of times.
public:
IText& replace( ITextIterator thisFrom, ITextIterator thisTo, length_type thatCopies, UniChar that )

thisFrom
An iterator referring to first character to replace.
thisTo
An iterator referring to first character AFTER the last one to be replaced.
that
The new character.
thatCopies
The number of times to repeat "that".

Exception

IInvalidParameter if thisFrom and thisTo don't form a proper range on *this
IInvalidRequest if the resulting string would have a length greater than max_size()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Searching the IText Object

Use the functions in this group to search the IText object for one or more characters.


[view class]
find
This is a bitwise search, and styles are ignored.


Overload 1
Searches the IText for the specfied string.
public:
offset_type find( const UniChar key [ ], offset_type startPos, length_type keyLength ) const

startPos
position of first character to examine in the search
key
Pointer to an array of UniChar containing the string to search for,
keyLength
Number of characters in the string pointed to by "key".

Return
offset of the first character of the first instance of "key" found in the IText at or after startPos, or npos if "key" is not found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Searches the IText for the specfied character.
public:
offset_type find( UniChar key, offset_type startPos = 0 ) const

startPos
position of first character to examine in the search
key
The character to search for.

Return
offset of the first instance of "key" found in the IText at or after startPos, or npos if "key" is not found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Searches the IText for the specfied string.
public:
offset_type find( const UniChar* key, offset_type startPos = 0 ) const

startPos
position of first character to examine in the search
key
Pointer to string to search for, expressed as a null-terminated Unicode string (its length is determined by searching for UUnicodeSpecial::kNull).

Return
offset of the first character of the first instance of "key" found in the IText at or after startPos, or npos if "key" is not found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Searches the IText for the specfied string.
public:
offset_type find( const IText& key, offset_type startPos = 0 ) const

key
String to search for
startPos
position of first character to examine in the search

Return
offset of the first character of the first instance of "key" found in the IText at or after startPos, or npos if "key" is not found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
find_first_not_of
Searches the IText for characters not in the specified set Searches the IText for characters that don't match the specified one. Searches the IText for characters not in the specified set (This is a bitwise search, and styles are ignored.)


Overload 1
public:
offset_type find_first_not_of( const UniChar keys [ ], offset_type startPos, length_type numKeys ) const

startPos
position of first character to examine in the search
keys
A pointer to the characters to search for.
numKeys
The number of characters in the buffer pointed to by "keys".

Return
offset of the first character in the IText at or after startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Searches the IText for characters that don't match the specified one.
public:
offset_type find_first_not_of( UniChar key, offset_type startPos = 0 ) const

key
The character to search for.
startPos
position of first character to examine in the search

Return
offset of the first character in the IText at or after startPos that does not match "key," or npos if no non-matching characters are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Searches the IText for characters not in the specified set.
public:
offset_type find_first_not_of( const UniChar* keys, offset_type startPos = 0 ) const

startPos
position of first character to examine in the search
keys
A pointer to a null-terminated Unicode string containing the characters to search for. The length of this string is determined by searching for UUnicodeSpecial::kNull.

Return
offset of the first character in the IText at or after startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
offset_type find_first_not_of( const IText& keys, offset_type startPos = 0 ) const

keys
An IText containing the characters to search for.
startPos
position of first character to examine in the search

Return
offset of the first character in the IText at or after startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
find_first_of
Searches the IText for the specified set of characters. Searches the IText for the specified character. (This is a bitwise search, and styles are ignored.)


Overload 1
Searches the IText for the specified character.
public:
offset_type find_first_of( UniChar key, offset_type startPos = 0 ) const

key
The character to search for.
startPos
position of first character to examine in the search

Return
offset of the first character in the IText at or after startPos that matches "key," or npos if no characters match "key"

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
offset_type find_first_of( const UniChar* keys, offset_type startPos = 0 ) const

startPos
position of first character to examine in the search
keys
A pointer to a null-terminated Unicode string containing the characters to search for. The length of this string is determined by searching for UUnicodeSpecial::kNull.

Return
offset of the first character in the IText at or after startPos that occurs in "keys," or npos if no characters in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
offset_type find_first_of( const UniChar keys [ ], offset_type startPos, length_type numKeys ) const

startPos
position of first character to examine in the search
keys
A pointer to the characters to search for.
numKeys
The number of characters in the buffer pointed to by "keys".

Return
offset of the first character in the IText at or after startPos that occurs in "keys," or npos if no characters in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
offset_type find_first_of( const IText& keys, offset_type startPos = 0 ) const

keys
An IText containing the characters to search for.
startPos
position of first character to examine in the search

Return
offset of the first character in the IText at or after startPos that occurs in "keys," or npos if no characters in "keys" are found

Exception

IInvalidParameter if startPos > length().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
find_last_not_of
Searches backwards through the IText for characters not in the specified set (This is a bitwise search, and styles are ignored.)


Overload 1
public:
offset_type find_last_not_of( UniChar key, offset_type startPos = npos ) const

key
The character to search for.
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the last character in the IText before startPos that does not match "key," or npos if no non-matching characters are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
offset_type find_last_not_of( const UniChar* keys, offset_type startPos = npos ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
keys
A pointer to a null-terminated Unicode string containing the characters to search for. The length of this string is determined by searching for UUnicodeSpecial::kNull.

Return
offset of the last character in the IText before startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
offset_type find_last_not_of( const UniChar keys [ ], offset_type startPos, length_type numKeys ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
keys
A pointer to the characters to search for.
numKeys
The number of characters in the buffer pointed to by "keys".

Return
offset of the last character in the IText before startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
offset_type find_last_not_of( const IText& keys, offset_type startPos = npos ) const

keys
An IText containing the characters to search for.
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the last character in the IText before startPos that does not occur in "keys," or npos if no characters that aren't in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
find_last_of
Searches backwards through the IText for the specified set of characters. Searches backwards through the IText for the specified character. Searches backwards through the IText for the specified set of characters. (This is a bitwise search, and styles are ignored.)


Overload 1
public:
offset_type find_last_of( const UniChar* keys, offset_type startPos = npos ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
keys
A pointer to a null-terminated Unicode string containing the characters to search for. The length of this string is determined by searching for UUnicodeSpecial::kNull.

Return
offset of the last character in the IText before startPos that occurs in "keys," or npos if no characters in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Searches backwards through the IText for the specified character.
public:
offset_type find_last_of( UniChar key, offset_type startPos = npos ) const

key
The character to search for.
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the last character in the IText before startPos that matches "key," or npos if no characters match "key"

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
offset_type find_last_of( const IText& keys, offset_type startPos = npos ) const

keys
An IText containing the characters to search for.
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the last character in the IText before startPos that occurs in "keys," or npos if no characters in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
offset_type find_last_of( const UniChar keys [ ], offset_type startPos, length_type numKeys ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
keys
A pointer to the characters to search for.
numKeys
The number of characters in the buffer pointed to by "keys".

Return
offset of the last character in the IText before startPos that occurs in "keys," or npos if no characters in "keys" are found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rfind
Searches backwards through the IText for the specified character. Searches backwards through the IText for the specified string. (This is a bitwise search, and styles are ignored.)


Overload 1
Searches backwards through the IText for the specified string.
public:
offset_type rfind( const UniChar* key, offset_type startPos = npos ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
key
Pointer to string to search for, expressed as a null-terminated Unicode string (its length is determined by searching for UUnicodeSpecial::kNull).

Return
offset of the first character of the last instance of "key" found in the IText before startPos, or npos if "key" is not found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Searches backwards through the IText for the specified string.
public:
offset_type rfind( const UniChar key [ ], offset_type startPos, length_type keyLength ) const

startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)
key
Pointer to an array of UniChar containing the string to search for,
keyLength
Number of characters in the string pointed to by "key".

Return
offset of the first character of the last instance of "key" found in the IText before startPos, or npos if "key" is not found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Searches backwards through the IText for the specified string.
public:
offset_type rfind( const IText& key, offset_type startPos = npos ) const

key
String to search for
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the first character of the last instance of "key" found in the IText before startPos, or npos if "key" is not found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
offset_type rfind( UniChar key, offset_type startPos = npos ) const

key
The character to search for.
startPos
position AFTER the first character to examine in the search (npos may be used to tell the function to search the whole string)

Return
offset of the last instance of "key" found in the IText before startPos, or npos if "key" is not found

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Streaming the IText Object In and Out

Use the operators in this group to write the IText object out to the specified stream and read it in from it.


[view class]
operator <<=
public:
void operator <<=(IDataStream& fromWhere)
Reads the contents of the IText (both characters and styles) from fromWhere. The text read from the stream replaces any text already in the IText. This function depends on the data being in the same stream format as written by operator&gt;&gt;=().

fromWhere
The stream from which the IText object is read in.

Return
fromWhere.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >>=
public:
void operator >>=(IDataStream& toWhere) const
Writes the contents of the IText (both characters and styles) to toWhere. The streaming is optimized: the character and style data are both compressed, the style data takes up zero bytes when the IText is unstyled, and overhead is kept to a bare minimum.

toWhere
The stream to which the IText object is written out.

Return
toWhere.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Typedefs and Constant Definitions


[view class]
npos
public:
static const length_type _IMPORT npos

"To the end" length, or "not found" flag. This is a special value that is used in the interface to IText for two purposes:

  1. In length parameters, specifies all characters between the specified starting offset and the end of the string. (A starting offset of 0 and a length of npos refers to the whole string.)
  2. Returned by the find functions when they fail to find the search string.

npos is equal to (unsigned long)(-1). For example, the largest possible unsigned long.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Miscellaneous Members


[view class]
emptyText
public:
static const IText& emptyText()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IText - Type Definitions


[view class]
offset_type
typedef size_t offset_type
Type used for specifying character offsets. Always typedefed to size_t because the ANSI standard uses size_t. All offset_type parameters are zero-based: 0 refers to the position of the first character in a string, and length() returns the offset of the first character position beyond the end of the string. There is no concept of "insertion position" (i.e., numbering the "cracks" between the characters rather than the characters themselves) in the standard, as there was in the old Standard Text library; by convention, insertions take place before the character whose offset is specified as an insertion position (which has the same effective result as numbering the cracks between characters). You add at the end by specifying the past-the-end offset (i.e., the value returned by length()) as the insertion position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
length_type
typedef size_t length_type
Type used for specifying character counts. Always typedefed to size_t because the ANSI standard uses size_t. Always represents character counts, not byte counts.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IText - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data