ITextBoundary

The ITextBoundary class implements methods for finding the location of boundaries in text. ITextBoundary is an abstract base class. Instances of ITextBoundary maintain a current position and scan over text returning the index of characters where boundaries occur.

Character boundary analysis allows users to interact with characters as they expect to, for example, when moving the cursor through a text string. Character boundary analysis provides correct navigation through strings regardless of how a character is represented. For example, an accented character might be stored as a base character and a diacritical mark, or a single combined character. What users consider to be a character can differ between languages.

Word boundary analysis is used by search and replace functions, as well as within text editing applications that allow the user to select words with a double click. Word selection provides correct interpretation of punctuation marks within and following words. Characters that are not part of a word, such as symbols or punctuation marks, have word breaks on both sides.

Line boundary analysis determines where a text string can be broken when line-wrapping. The mechanism correctly handles punctuation and hyphenated words.

Sentence boundary analysis allows selection with correct interpretation of periods within numbers and abbreviations, and trailing punctuation marks such as quotation marks and parentheses.

This is the interface for all text boundaries.

Examples:

Print each word of the text in order

void printEachWordForward(const IText& text) {
    ITextBoundary* wordBoundary = ITextBoundary::createWordBreak();
    words->setText(text);
    for (ITextBoundary::offset_type start = wordBoundary->first(),
         end = wordBoundary->next();
         end != ITextBoundary::kDone;
         start = end, end = wordBoundary->next()) {

printf(text.substr(start, end - start)); } delete wordBoundary; }

Print each line of the text in reverse order

void printEachLineBackward(const IText& text) {
    ITextBoundary* lineBoundary = ITextBoundary::createLineBreak();
    lineBoundary->setText(text);
    for (ITextBoundary::offset_type end = lineBoundary->last(),
         start = lineBoundary->previous();
         start != ITextBoundary::kDone;
         end = start, start = lineBoundary->previous()) {

printf(text.substr(start, end - start)); } delete lineBoundary; }


ITextBoundary - Member Functions and Data by Group

Constructors & Destructor

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


[view class]
~ITextBoundary
public:
virtual ~ITextBoundary()
Destructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITextBoundary
Default constructor for subclassing.
protected:
ITextBoundary()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparing Two ITextBoundary Objects for Equality and Inequality

Use the operators in this group to compare the contents of the given ITextBoundary object with the current one for equality or inequality.


[view class]
operator !=
public:
bool operator !=(const ITextBoundary& rhs) const
Return the negation of operator==.

rhs
A constant reference to the ITextBoundary object to be compared with the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
Returns true if this ITextBoundary is at the same position in the same text.
public:
virtual bool operator ==(const ITextBoundary&) const = 0
This function returns true if this ITextBoundary object is at the same position in the same text and is the same class and type (word, line, etc.) of ITextBoundary, as the argument. Text is considered the same if it contains the same characters, it need not be the same object, and styles are not considered.

ITextBoundary
A constant reference to the ITextBoundary object to be compared with the current one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting a Polymorphic Copy

Use the function in this group to obtain a polymorphic copy of the ITextBoundary object.


[view class]
clone
public:
virtual ITextBoundary* clone() const = 0
Returns a polymorphic copy of this ITextBoundary.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting and Setting the Text

Use the functions in this group to get and set the text operated on.


[view class]
setText
Change the text over which this operates.
public:
virtual void setText(const IText&) = 0
The text boundary is reset to the start.

IText
A constant reference to the IText object containing the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
virtual IText text() const = 0
Return the text over which this operates.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting Text Boundary Indexes

Use the functions in this group to get indexes to various text boundaries.


[view class]
current
public:
virtual offset_type current() const = 0
Returns the character index of the text boundary that was most recently returned by next(), previous(), first(), last(), or nthFromCurrent().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
first
public:
virtual offset_type first() = 0
Return the index of the first character in the text being scanned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
last
public:
virtual offset_type last() = 0
Return the index following the last character in the text being scanned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
next
public:
virtual offset_type next() = 0
Returns the character index of the next text boundary, or kDone if all boundaries have been returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nextAfter
Return the first boundary after the specified offset.
public:
virtual offset_type nextAfter(offset_type offset) = 0
The value returned is always greater than the offset, or is kDone.

offset
The offset to begin scanning.

Return
The first boundary after the specified offset.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nthFromCurrent
public:
virtual offset_type nthFromCurrent(int n) = 0
Return the nth boundary from the current boundary.

n
The signed number of boundaries to traverse. Negative values move to previous boundaries and positive values move to later boundaries. A value of 0 does nothing. This function does affect the internal interation state of the text boundary, so if you call current() after calling nthFromCurrent(), current() will return the same value nthFromCurrent(0 just did; and repeated calls to nthFromCurrent will advance through the text.

Return
The character index of the nth boundary from the current position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
previous
Return the character index of the previous text boundary, or kDone if all boundaries have been returned.
public:
virtual offset_type previous() = 0
boundaries have been returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting the User-Displayable Name

Use the function in this group to get the user-displayable name in the locale's language.


[view class]
getDisplayName
public:
static IText getDisplayName( const ILocaleKey& objectLocale = ILocaleKey::defaultLocale ( ), const ILocaleKey& displayLocale = ILocaleKey::defaultLocale ( ) )
Gets a user-displayable name in the language of the display locale that refers to ITextBoundary objects for the object locale.

objectLocale
A locale used to obtain an ITextBoundary, as used in createWordBreak, createLineBreak, and so forth.
displayLocale
The locale identifying the language to use for the returned name.

Return
A user-displayable name in the language of the displayLocale that refers to ITextBoundary objects for the objectLocale.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Locating Line, Word, and Sentance Breaks

Use the functions in this group to create instances of ITextBoundary objects that locate sentence, line, and word breaks.


[view class]
createCharacterBreak
Create an instance of ITextBoundary that locates character breaks.
public:
static ITextBoundary* createCharacterBreak( const ILocaleKey& locale = ILocaleKey::defaultLocale ( ) )
Character breaks are boundaries of combining character sequences. These are useful for determining possible places for caret placement or cursor movement.

locale
the locale. If an ITextBoundary for character breaks is not avaliable for the specified locale, a default ITextBoundary for character breaks is returned.

Return
A new instance of ITextBoundary that locates character breaks

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createLineBreak
Create an instance of ITextBoundary that locates line breaks.
public:
static ITextBoundary* createLineBreak( const ILocaleKey& locale = ILocaleKey::defaultLocale ( ) )
Line breaks are useful for locating places where a line may be broken when flowing text into a container. This locates all logically possible line breaks. Clients can select from these to determine which line break to use based on a maximum line width, for example.

locale
the locale. If an ITextBoundary for line breaks is not avaliable for the specified locale, a default ITextBoundary for line breaks is returned.

Return
A new instance of ITextBoundary that locates line breaks

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createSentenceBreak
Create an instance of ITextBoundary that locates sentence breaks.
public:
static ITextBoundary* createSentenceBreak( const ILocaleKey& locale = ILocaleKey::defaultLocale ( ) )
Sentence breaks are useful for sentence selection.

locale
the locale. If an ITextBoundary for sentence breaks is not avaliable for the specified locale, a default ITextBoundary for sentence breaks is returned.

Return
A new instance of ITextBoundary that locates sentence breaks

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createWordBreak
Create an instance of ITextBoundary that locates word breaks.
public:
static ITextBoundary* createWordBreak( const ILocaleKey& locale = ILocaleKey::defaultLocale ( ) )
Word breaks are useful for word selection (eg. double click).

locale
the locale. If an ITextBoundary for word breaks is not avaliable for the specified locale, a default ITextBoundary for word breaks is returned.

Return
A new instance of ITextBoundary that locates word breaks

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Miscellaneous Members


[view class]
kDone
This value is returned by previous() and next() after all valid
public:
static offset_type _IMPORT kDone
boundaries have been returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITextBoundary - Type Definitions


[view class]
offset_type
typedef IText::offset_type offset_type
A convenient name for the type representing offsets into the text. OPTIONS.ODYDELIMITERA convenient name for the type representing offsets into the text. OPTIONS.ODYDELIMITER

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITextBoundary - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data