### 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-&gt;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&gt;&gt;=().

  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:

  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

emptyText

      public:
      static const IText& emptyText()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IText - Type Definitions

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None