Main Page | Class Hierarchy | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

ubrk.h File Reference

C API: BreakIterator. More...

#include "unicode/utypes.h"
#include "unicode/uloc.h"
#include "unicode/parseerr.h"

Go to the source code of this file.

Defines

#define UBRK_DONE   ((int32_t) -1)
 Value indicating all text boundaries have been returned.

#define U_BRK_SAFECLONE_BUFFERSIZE   512
 A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone().


Typedefs

typedef void UBreakIterator
 Opaque type representing an ICU Break iterator object.

typedef enum UBreakIteratorType UBreakIteratorType
 The possible types of text boundaries.

typedef enum UWordBreak UWordBreak
 Enum constants for the word break tags returned by getRuleStatus().

typedef enum ULineBreakTag ULineBreakTag
 Enum constants for the line break tags returned by getRuleStatus().

typedef enum USentenceBreakTag USentenceBreakTag
 Enum constants for the sentence break tags returned by getRuleStatus().


Enumerations

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

enum  UWordBreak {
  UBRK_WORD_NONE = 0, UBRK_WORD_NONE_LIMIT = 100, UBRK_WORD_NUMBER = 100, UBRK_WORD_NUMBER_LIMIT = 200,
  UBRK_WORD_LETTER = 200, UBRK_WORD_LETTER_LIMIT = 300, UBRK_WORD_KANA = 300, UBRK_WORD_KANA_LIMIT = 400,
  UBRK_WORD_IDEO = 400, UBRK_WORD_IDEO_LIMIT = 500
}
 Enum constants for the word break tags returned by getRuleStatus(). More...

enum  ULineBreakTag { UBRK_LINE_SOFT = 0, UBRK_LINE_SOFT_LIMIT = 100, UBRK_LINE_HARD = 100, UBRK_LINE_HARD_LIMIT = 200 }
 Enum constants for the line break tags returned by getRuleStatus(). More...

enum  USentenceBreakTag { UBRK_SENTENCE_TERM = 0, UBRK_SENTENCE_TERM_LIMIT = 100, UBRK_SENTENCE_SEP = 100, UBRK_SENTENCE_SEP_LIMIT = 200 }
 Enum constants for the sentence break tags returned by getRuleStatus(). More...


Functions

U_CAPI UBreakIterator *U_EXPORT2 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.

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

U_CAPI UBreakIterator *U_EXPORT2 ubrk_safeClone (const UBreakIterator *bi, void *stackBuffer, int32_t *pBufferSize, UErrorCode *status)
 Thread safe cloning operation.

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

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

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

U_CAPI int32_t U_EXPORT2 ubrk_next (UBreakIterator *bi)
 Determine the text boundary following the current text boundary.

U_CAPI int32_t U_EXPORT2 ubrk_previous (UBreakIterator *bi)
 Determine the text boundary preceding the current text boundary.

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

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

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

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

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

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

U_CAPI UBool U_EXPORT2 ubrk_isBoundary (UBreakIterator *bi, int32_t offset)
 Returns true if the specfied position is a boundary position.

U_CAPI int32_t U_EXPORT2 ubrk_getRuleStatus (UBreakIterator *bi)
 Return the status from the break rule that determined the most recently returned break position.

U_CAPI const char *U_EXPORT2 ubrk_getLocaleByType (const UBreakIterator *bi, ULocDataLocaleType type, UErrorCode *status)
 Return the locale of the break iterator.


Detailed Description

C API: BreakIterator.

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.

Title boundary analysis locates all positions, typically starts of words, that should be set to Title Case when title casing the text.

This is the interface for all text boundaries.

Examples:

Helper function to output text

 
void printTextRange(UChar* str, int32_t start, int32_t 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) { int32_t end; int32_t 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) { int32_t start; int32_t 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) { int32_t end; int32_t start = ubrk_first(boundary); end = ubrk_next(boundary); printTextRange( str, start, end ); }
Print last element
 
void printLast(UBreakIterator* boundary, UChar* str) { int32_t start; int32_t end = ubrk_last(boundary); start = ubrk_previous(boundary); printTextRange(str, start, end ); }
Print the element at a specified position
 
void printAt(UBreakIterator* boundary, int32_t pos , UChar* str) { int32_t start; int32_t 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 U_BRK_SAFECLONE_BUFFERSIZE   512
 

A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone().

ICU 2.0

#define UBRK_DONE   ((int32_t) -1)
 

Value indicating all text boundaries have been returned.

ICU 2.0


Typedef Documentation

typedef void UBreakIterator
 

Opaque type representing an ICU Break iterator object.

ICU 2.0

typedef enum UBreakIteratorType UBreakIteratorType
 

The possible types of text boundaries.

ICU 2.0

typedef enum ULineBreakTag ULineBreakTag
 

Enum constants for the line break tags returned by getRuleStatus().

A range of values is defined for each category of word, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.8

typedef enum USentenceBreakTag USentenceBreakTag
 

Enum constants for the sentence break tags returned by getRuleStatus().

A range of values is defined for each category of sentence, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.8

typedef enum UWordBreak UWordBreak
 

Enum constants for the word break tags returned by getRuleStatus().

A range of values is defined for each category of word, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.2


Enumeration Type Documentation

enum UBreakIteratorType
 

The possible types of text boundaries.

ICU 2.0

Enumeration values:
UBRK_CHARACTER  Character breaks ICU 2.0.
UBRK_WORD  Word breaks ICU 2.0.
UBRK_LINE  Line breaks ICU 2.0.
UBRK_SENTENCE  Sentence breaks ICU 2.0.
UBRK_TITLE  Title Case breaks The iterator created using this type locates title boundaries as described for Unicode 3.2 only.

For Unicode 4.0 and above title boundary iteration, please use Word Boundary iterator.

Deprecated:
ICU 2.8 Use the word break iterator for titlecasing for Unicode 4 and later.

enum ULineBreakTag
 

Enum constants for the line break tags returned by getRuleStatus().

A range of values is defined for each category of word, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.8

Enumeration values:
UBRK_LINE_SOFT  Tag value for soft line breaks, positions at which a line break is acceptable but not required.
UBRK_LINE_SOFT_LIMIT  Upper bound for soft line breaks.
UBRK_LINE_HARD  Tag value for a hard, or mandatory line break.
UBRK_LINE_HARD_LIMIT  Upper bound for hard line breaks.

enum USentenceBreakTag
 

Enum constants for the sentence break tags returned by getRuleStatus().

A range of values is defined for each category of sentence, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.8

Enumeration values:
UBRK_SENTENCE_TERM  Tag value for for sentences ending with a sentence terminator ('.', '?', '!', etc.) character, possibly followed by a hard separator (CR, LF, PS, etc.).
UBRK_SENTENCE_TERM_LIMIT  Upper bound for tags for sentences ended by sentence terminators.
UBRK_SENTENCE_SEP  Tag value for for sentences that do not contain an ending sentence terminator ('.', '?', '!', etc.) character, but are ended only by a hard separator (CR, LF, PS, etc.) or end of input.
UBRK_SENTENCE_SEP_LIMIT  Upper bound for tags for sentences ended by a separator.

enum UWordBreak
 

Enum constants for the word break tags returned by getRuleStatus().

A range of values is defined for each category of word, to allow for further subdivisions of a category in future releases. Applications should check for tag values falling within the range, rather than for single individual values. ICU 2.2

Enumeration values:
UBRK_WORD_NONE  Tag value for "words" that do not fit into any of other categories.

Includes spaces and most punctuation.

UBRK_WORD_NONE_LIMIT  Upper bound for tags for uncategorized words.
UBRK_WORD_NUMBER  Tag value for words that appear to be numbers, lower limit.
UBRK_WORD_NUMBER_LIMIT  Tag value for words that appear to be numbers, upper limit.
UBRK_WORD_LETTER  Tag value for words that contain letters, excluding hiragana, katakana or ideographic characters, lower limit.
UBRK_WORD_LETTER_LIMIT  Tag value for words containing letters, upper limit.
UBRK_WORD_KANA  Tag value for words containing kana characters, lower limit.
UBRK_WORD_KANA_LIMIT  Tag value for words containing kana characters, upper limit.
UBRK_WORD_IDEO  Tag value for words containing ideographic characters, lower limit.
UBRK_WORD_IDEO_LIMIT  Tag value for words containing ideographic characters, upper limit.


Function Documentation

U_CAPI void U_EXPORT2 ubrk_close UBreakIterator bi  ) 
 

Close a UBreakIterator.

Once closed, a UBreakIterator may no longer be used.

Parameters:
bi The break iterator to close. ICU 2.0

U_CAPI int32_t U_EXPORT2 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 {ubrk_getAvailable}.

Returns:
The number of locales for which text breaking information is available.
See also:
ubrk_getAvailable ICU 2.0

U_CAPI int32_t U_EXPORT2 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 {ubrk_next}, {ubrk_previous}, {ubrk_first}, or {ubrk_last}. ICU 2.0

U_CAPI int32_t U_EXPORT2 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 ICU 2.0

U_CAPI int32_t U_EXPORT2 ubrk_following UBreakIterator bi,
int32_t  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 ICU 2.0

U_CAPI const char* U_EXPORT2 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 ICU 2.0

U_CAPI const char* U_EXPORT2 ubrk_getLocaleByType const UBreakIterator bi,
ULocDataLocaleType  type,
UErrorCode status
 

Return the locale of the break iterator.

You can choose between the valid and the actual locale.

Parameters:
bi break iterator
type locale type (valid or actual)
status error code
Returns:
locale string ICU 2.8 likely to change in ICU 3.0, based on feedback

U_CAPI int32_t U_EXPORT2 ubrk_getRuleStatus UBreakIterator bi  ) 
 

Return the status from the break rule that determined the most recently returned break position.

The values appear in the rule source within brackets, {123}, for example. For rules that do not specify a status, a default value of 0 is returned.

For word break iterators, the possible values are defined in enum UWordBreak. ICU 2.2

U_CAPI UBool U_EXPORT2 ubrk_isBoundary UBreakIterator bi,
int32_t  offset
 

Returns true if the specfied position is a boundary position.

As a side effect, leaves the iterator pointing to the first boundary position at or after "offset".

Parameters:
bi The break iterator to use.
offset the offset to check.
Returns:
True if "offset" is a boundary position. ICU 2.0

U_CAPI int32_t U_EXPORT2 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 ICU 2.0

U_CAPI int32_t U_EXPORT2 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 ICU 2.0

U_CAPI UBreakIterator* U_EXPORT2 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 ICU 2.0

U_CAPI UBreakIterator* U_EXPORT2 ubrk_openRules const UChar *  rules,
int32_t  rulesLength,
const UChar *  text,
int32_t  textLength,
UParseError parseErr,
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. May be null, in which case ubrk_setText() is used to specify the text to be iterated.
textLength The number of characters in text, or -1 if null-terminated.
parseErr Receives position and context information for any syntax errors detected while parsing the rules.
status A UErrorCode to receive any errors.
Returns:
A UBreakIterator for the specified rules.
See also:
ubrk_open ICU 2.2

U_CAPI int32_t U_EXPORT2 ubrk_preceding UBreakIterator bi,
int32_t  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 ICU 2.0

U_CAPI int32_t U_EXPORT2 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 ICU 2.0

U_CAPI UBreakIterator* U_EXPORT2 ubrk_safeClone const UBreakIterator bi,
void *  stackBuffer,
int32_t *  pBufferSize,
UErrorCode status
 

Thread safe cloning operation.

Parameters:
bi iterator to be cloned
stackBuffer user allocated space for the new clone. If NULL new memory will be allocated. If buffer is not large enough, new memory will be allocated. Clients can use the U_BRK_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations.
pBufferSize pointer to size of allocated space. If *pBufferSize == 0, a sufficient size for use in cloning will be returned ('pre-flighting') If *pBufferSize is not enough for a stack-based safe clone, new memory will be allocated.
status to indicate whether the operation went on smoothly or there were errors An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were necessary.
Returns:
pointer to the new clone ICU 2.0

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

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

Parameters:
bi The iterator to use
text The text to be set
textLength The length of the text
status The error code ICU 2.0


Generated on Wed Jul 28 09:15:55 2004 for ICU 2.8 by doxygen 1.3.7