Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Header Files   Compound Members   File Members  

ubrk.h File Reference

BreakIterator C API. More...


Defines

#define UBRK_DONE
Value indicating all text boundaries have been returned.


Typedefs

typedef void* UBreakIterator
A text-break iterator. More...

typedef enum UBreakIteratorType UBreakIteratorType

Enumerations

enum  UBreakIteratorType { UBRK_CHARACTER, UBRK_WORD, UBRK_LINE, UBRK_SENTENCE }
The possible types of text boundaries. More...


Functions

U_CAPI UBreakIteratorubrk_open (UBreakIteratorType type, const char *locale, const UChar *text, int32_t textLength, UErrorCode *status)
Open a new UBreakIterator for locating text boundaries for a specified locale. More...

U_CAPI UBreakIteratorubrk_openRules (const UChar *rules, int32_t rulesLength, const UChar *text, int32_t textLength, UErrorCode *status)
Open a new UBreakIterator for locating text boundaries using specified breaking rules. More...

U_CAPI void ubrk_close (UBreakIterator *bi)
Close a UBreakIterator. More...

U_CAPI void ubrk_setText (UBreakIterator* bi, const UChar* text, int32_t textLength, UErrorCode* status)
Sets an existing iterator to point to a new piece of text. More...

U_CAPI UTextOffset ubrk_current (const UBreakIterator *bi)
Determine the most recently-returned text boundary. More...

U_CAPI UTextOffset ubrk_next (UBreakIterator *bi)
Determine the text boundary following the current text boundary. More...

U_CAPI UTextOffset ubrk_previous (UBreakIterator *bi)
Determine the text boundary preceding the current text boundary. More...

U_CAPI UTextOffset ubrk_first (UBreakIterator *bi)
Determine the index of the first character in the text being scanned. More...

U_CAPI UTextOffset ubrk_last (UBreakIterator *bi)
Determine the index immediately beyond the last character in the text being scanned. More...

U_CAPI UTextOffset ubrk_preceding (UBreakIterator *bi, UTextOffset offset)
Determine the text boundary preceding the specified offset. More...

U_CAPI UTextOffset ubrk_following (UBreakIterator *bi, UTextOffset offset)
Determine the text boundary following the specified offset. More...

U_CAPI const char* ubrk_getAvailable (int32_t index)
Get a locale for which text breaking information is available. More...

U_CAPI int32_t ubrk_countAvailable (void)
Determine how many locales have text breaking information available. More...


Detailed Description

BreakIterator C API.

The BreakIterator C API defines methods for finding the location of boundaries in text. Pointer to a UBreakIterator maintain a current position and scan over text returning the index of characters where boundaries occur.

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.

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.

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 of through character strings, regardless of how the character is stored. For example, an accented character might be stored as a base character and a diacritical mark. What users consider to be a character can differ between languages.

This is the interface for all text boundaries.

Examples:

Helper function to output text

 .   void printTextRange(UChar* str, UTextOffset start, UTextOffset end ) {
 .        UChar* result;
 .        UChar* temp;
 .        const char* res;
 .        temp=(UChar*)malloc(sizeof(UChar) * ((u_strlen(str)-start)+1));
 .        result=(UChar*)malloc(sizeof(UChar) * ((end-start)+1));
 .        u_strcpy(temp, &str[start]);
 .        u_strncpy(result, temp, end-start);
 .        res=(char*)malloc(sizeof(char) * (u_strlen(result)+1));
 .        u_austrcpy(res, result);
 .        printf("%s\n", res); 
 .   }
 
Print each element in order:
 .   void printEachForward( UBreakIterator* boundary, UChar* str) {
 .      UTextOffset end;
 .      UTextOffset start = ubrk_first(boundary);
 .      for (end = ubrk_next(boundary)); end != UBRK_DONE; start = end, end = ubrk_next(boundary)) {
 .            printTextRange(str, start, end );
 .        }
 .   }
 
Print each element in reverse order:
 .   void printEachBackward( UBreakIterator* boundary, UChar* str) {
 .      UTextOffset start;
 .      UTextOffset end = ubrk_last(boundary);
 .      for (start = ubrk_previous(boundary); start != UBRK_DONE;  end = start, start =ubrk_previous(boundary)) {
 .            printTextRange( str, start, end );
 .        }
 .   }
 
Print first element
 .   void printFirst(UBreakIterator* boundary, UChar* str) {
 .       UTextOffset end;
 .       UTextOffset start = ubrk_first(boundary);
 .       end = ubrk_next(boundary);
 .       printTextRange( str, start, end );
 .   }
 
Print last element
 .   void printLast(UBreakIterator* boundary, UChar* str) {
 .       UTextOffset start;
 .       UTextOffset end = ubrk_last(boundary);
 .       start = ubrk_previous(boundary);
 .       printTextRange(str, start, end );
 .   }
 
Print the element at a specified position
 .   void printAt(UBreakIterator* boundary, UTextOffset pos , UChar* str) {
 .       UTextOffset start;
 .       UTextOffset end = ubrk_following(boundary, pos);
 .       start = ubrk_previous(boundary);
 .       printTextRange(str, start, end );
 .   }
 
Creating and using text boundaries
 .      void BreakIterator_Example( void ) {
 .          UBreakIterator* boundary;
 .          UChar *stringToExamine;
 .          stringToExamine=(UChar*)malloc(sizeof(UChar) * (strlen("Aaa bbb ccc. Ddd eee fff.")+1) );
 .          u_uastrcpy(stringToExamine, "Aaa bbb ccc. Ddd eee fff.");
 .          printf("Examining: "Aaa bbb ccc. Ddd eee fff.");
 .
 .          //print each sentence in forward and reverse order
 .          boundary = ubrk_open(UBRK_SENTENCE, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
 .          printf("----- forward: -----------\n"); 
 .          printEachForward(boundary, stringToExamine);
 .          printf("----- backward: ----------\n");
 .          printEachBackward(boundary, stringToExamine);
 .          ubrk_close(boundary);
 .
 .          //print each word in order
 .          boundary = ubrk_open(UBRK_WORD, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
 .          printf("----- forward: -----------\n"); 
 .          printEachForward(boundary, stringToExamine);
 .          printf("----- backward: ----------\n");
 .          printEachBackward(boundary, stringToExamine);
 .          //print first element
 .          printf("----- first: -------------\n");
 .          printFirst(boundary, stringToExamine);
 .          //print last element
 .          printf("----- last: --------------\n");
 .          printLast(boundary, stringToExamine);
 .          //print word at charpos 10
 .          printf("----- at pos 10: ---------\n");
 .          printAt(boundary, 10 , stringToExamine);
 .
 .          ubrk_close(boundary);
 .      }
 

Define Documentation

#define UBRK_DONE ()

Value indicating all text boundaries have been returned.


Typedef Documentation

typedef void* UBreakIterator

A text-break iterator.

For usage in C programs.

typedef enum UBreakIteratorType UBreakIteratorType


Enumeration Type Documentation

enum UBreakIteratorType

The possible types of text boundaries.

Enumeration values:
UBRK_CHARACTER   Character breaks.
UBRK_WORD   Word breaks.
UBRK_LINE   Line breaks.
UBRK_SENTENCE   Sentence breaks.

Function Documentation

U_CAPI UBreakIterator * ubrk_open (UBreakIteratorType type, const char * locale, const UChar * text, int32_t textLength, UErrorCode * status)

Open a new UBreakIterator for locating text boundaries for a specified locale.

A UBreakIterator may be used for detecting character, line, word, and sentence breaks in text.

Parameters:
type   The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD, UBRK_LINE, UBRK_SENTENCE
locale   The locale specifying the text-breaking conventions.
text   The text to be iterated over.
textLength   The number of characters in text, or -1 if null-terminated.
status   A UErrorCode to receive any errors.
Returns:
A UBreakIterator for the specified locale.
See also:
ubrk_openRules()
Stable:

U_CAPI UBreakIterator * ubrk_openRules (const UChar * rules, int32_t rulesLength, const UChar * text, int32_t textLength, UErrorCode * status)

Open a new UBreakIterator for locating text boundaries using specified breaking rules.

The rule syntax is ... (TBD)

Parameters:
rules   A set of rules specifying the text breaking conventions.
rulesLength   The number of characters in rules, or -1 if null-terminated.
text   The text to be iterated over.
textLength   The number of characters in text, or -1 if null-terminated.
status   A UErrorCode to receive any errors.
Returns:
A UBreakIterator for the specified rules.
See also:
ubrk_open()
Draft:

U_CAPI void ubrk_close (UBreakIterator * bi)

Close a UBreakIterator.

Once closed, a UBreakIterator may no longer be used.

Parameters:
bi   The break iterator to close.
Stable:

U_CAPI void ubrk_setText (UBreakIterator * bi, const UChar * text, int32_t textLength, UErrorCode * status)

Sets an existing iterator to point to a new piece of text.

Stable:

U_CAPI UTextOffset ubrk_current (const UBreakIterator * bi)

Determine the most recently-returned text boundary.

Parameters:
bi   The break iterator to use.
Returns:
The character index most recently returned by \Ref{ubrk_next}, \Ref{ubrk_previous}, \Ref{ubrk_first}, or \Ref{ubrk_last}.
Stable:

U_CAPI UTextOffset ubrk_next (UBreakIterator * bi)

Determine the text boundary following the current text boundary.

Parameters:
bi   The break iterator to use.
Returns:
The character index of the next text boundary, or UBRK_DONE if all text boundaries have been returned.
See also:
ubrk_previous()
Stable:

U_CAPI UTextOffset ubrk_previous (UBreakIterator * bi)

Determine the text boundary preceding the current text boundary.

Parameters:
bi   The break iterator to use.
Returns:
The character index of the preceding text boundary, or UBRK_DONE if all text boundaries have been returned.
See also:
ubrk_next()
Stable:

U_CAPI UTextOffset ubrk_first (UBreakIterator * bi)

Determine the index of the first character in the text being scanned.

This is not always the same as index 0 of the text.

Parameters:
bi   The break iterator to use.
Returns:
The character index of the first character in the text being scanned.
See also:
ubrk_last()
Stable:

U_CAPI UTextOffset ubrk_last (UBreakIterator * bi)

Determine the index immediately beyond the last character in the text being scanned.

This is not the same as the last character.

Parameters:
bi   The break iterator to use.
Returns:
The character offset immediately beyond the last character in the text being scanned.
See also:
ubrk_first()
Stable:

U_CAPI UTextOffset ubrk_preceding (UBreakIterator * bi, UTextOffset offset)

Determine the text boundary preceding the specified offset.

The value returned is always smaller than offset, or UBRK_DONE.

Parameters:
bi   The break iterator to use.
offset   The offset to begin scanning.
Returns:
The text boundary preceding offset, or UBRK_DONE.
See also:
ubrk_following()
Stable:

U_CAPI UTextOffset ubrk_following (UBreakIterator * bi, UTextOffset offset)

Determine the text boundary following the specified offset.

The value returned is always greater than offset, or UBRK_DONE.

Parameters:
bi   The break iterator to use.
offset   The offset to begin scanning.
Returns:
The text boundary following offset, or UBRK_DONE.
See also:
ubrk_preceding()
Stable:

U_CAPI const char * ubrk_getAvailable (int32_t index)

Get a locale for which text breaking information is available.

A UBreakIterator in a locale returned by this function will perform the correct text breaking for the locale.

Parameters:
index   The index of the desired locale.
Returns:
A locale for which number text breaking information is available, or 0 if none.
See also:
ubrk_countAvailable()
Stable:

U_CAPI int32_t ubrk_countAvailable (void)

Determine how many locales have text breaking information available.

This function is most useful as determining the loop ending condition for calls to \Ref{ubrk_getAvailable}.

Returns:
The number of locales for which text breaking information is available.
See also:
ubrk_getAvailable()
Stable:

Generated at Thu Feb 10 15:30:10 2000 for icu by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999