String Formats

IText provides full interoperability with the char-based string formats char* and IString, allowing you to:

• Construct IText objects from null-terminated char arrays and from IString objects
  (IText also provides constructors that take both null-terminated-terminated with UUnicodeSpecial::kNull-and non-terminated UniChar arrays)
• Return the characters in an IText as a char array or an IString object
• Use IText where char* or IString is called for
• Use char* or IString where IText is called for

This figure shows the IText interfaces supporting compatibility with other string formats:

IText uses the transcoding facility provided by the International Framework to convert data between char and Unicode data. IText assumes the char-based format is the default character encoding set for the host. This varies based on the platform and any locale settings for the system.

String Size and Capacity

IText follows the ANSI convention of using size_t (generally equivalent to unsigned long) to represent text lengths and offsets. IText defines two typedefs equivalent to size_t:

• length_type represents a character count. length_type values always represent the number of characters, not the number of bytes. IText also uses a special length_type value, npos, to represent the number of characters between a specified starting offset and the end of the string. For example, a starting offset of 0 and a length of npos refers to the whole string.
• offset_type represents the position of a character, zero-based from the first character in the string-that is, the position of the first character is at offset_type value 0, and so on.

This figure shows the IText functions you use to access the string's size and the storage capacity of the object:

• length and size are equivalent functions that return a length_type value representing the number of characters currently in the string.
• max_size returns the maximum number of characters that can be stored in an IText object, currently equivalent to npos - 1.
• resize lets you reset the size of the string to a specified number of characters, either deleting characters or padding the end of the string as necessary. The default padding character is UUnicodeSpecial::kNull.
• capacity returns the number of characters for which the IText object has currently allocated storage.
• reserve can be used to indicate that a specified number of characters are about to be added to the string. The function will preallocate storage if needed and if memory conditions permit it.
• empty indicates whether the text object contains any character data.
• c_str and data return UniChar arrays containing the same number of characters as the IText object. c_str always returns a null-terminated array-data may not.