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.
- ~IText
public:
~IText()
- Destroys objects of class IText.
- Supported Platforms
| Windows |
OS/2 |
AIX |
| Yes |
Yes |
Yes |
- 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.
- 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 |
- 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 |
- 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.
- 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 |
- 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.
- 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 |
- 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.
- 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 |
- 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.
- 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 |
- 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.
- 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 |
- 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.
- 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.
- 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.
- 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.
- 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 |
- 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.
- 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 |
- 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 |
- 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 |
- 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.
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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.
- 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 |
- 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.
- 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 |
- 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 |
- 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 |
- 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 |
- length
public:
length_type length() const
- Same as size().
- Supported Platforms
| Windows |
OS/2 |
AIX |
| Yes |
Yes |
Yes |
- 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 |
- 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 |
- 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 |
- size
public:
length_type size() const
- Returns the number of characters in the IText.
- Supported Platforms
| Windows |
OS/2 |
AIX |
| Yes |
Yes |
Yes |
- 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.
- 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.
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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.
- 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>>=().
- fromWhere
- The stream from which the IText object is read in.
- Return
- fromWhere.
- Supported Platforms
| Windows |
OS/2 |
AIX |
| Yes |
Yes |
Yes |
- 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
- 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:
- 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.)
- 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
- emptyText
public:
static const IText& emptyText()
- Supported Platforms
| Windows |
OS/2 |
AIX |
| Yes |
Yes |
Yes |
- 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 |
- 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