# ubrk.h File Reference

C API: BreakIterator. More...

`#include "unicode/utypes.h"`
`#include "unicode/uloc.h"`
`#include "unicode/utext.h"`
`#include "unicode/localpointer.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 struct UBreakIterator | UBreakIterator
| A text-break iterator.
## Enumerations
enum | UBreakIteratorType { UBRK_CHARACTER = 0, UBRK_WORD = 1, UBRK_LINE = 2, UBRK_SENTENCE = 3, UBRK_TITLE = 4, UBRK_COUNT = 5 }
| 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
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.
UBreakIterator * | 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.
UBreakIterator * | ubrk_safeClone (const UBreakIterator *bi, void *stackBuffer, int32_t *pBufferSize, UErrorCode *status)
| Thread safe cloning operation.
void | ubrk_close (UBreakIterator *bi)
| Close a UBreakIterator.
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.
void | ubrk_setUText (UBreakIterator *bi, UText *text, UErrorCode *status)
| Sets an existing iterator to point to a new piece of text.
int32_t | ubrk_current (const UBreakIterator *bi)
| Determine the most recently-returned text boundary.
int32_t | ubrk_next (UBreakIterator *bi)
| Determine the text boundary following the current text boundary.
int32_t | ubrk_previous (UBreakIterator *bi)
| Determine the text boundary preceding the current text boundary.
int32_t | ubrk_first (UBreakIterator *bi)
| Determine the index of the first character in the text being scanned.
int32_t | ubrk_last (UBreakIterator *bi)
| Determine the index immediately beyond the last character in the text being scanned.
int32_t | ubrk_preceding (UBreakIterator *bi, int32_t offset)
| Determine the text boundary preceding the specified offset.
int32_t | ubrk_following (UBreakIterator *bi, int32_t offset)
| Determine the text boundary following the specified offset.
const char * | ubrk_getAvailable (int32_t index)
| Get a locale for which text breaking information is available.
int32_t | ubrk_countAvailable (void)
| Determine how many locales have text breaking information available.
UBool | ubrk_isBoundary (UBreakIterator *bi, int32_t offset)
| Returns true if the specfied position is a boundary position.
int32_t | ubrk_getRuleStatus (UBreakIterator *bi)
| Return the status from the break rule that determined the most recently returned break position.
int32_t | ubrk_getRuleStatusVec (UBreakIterator *bi, int32_t *fillInVec, int32_t capacity, UErrorCode *status)
| Get the statuses from the break rules that determined the most recently returned break position.
const char * | 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 identifies the boundaries of "Extended Grapheme Clusters", which are groupings of codepoints that should be treated as character-like units for many text operations. Please see Unicode Standard Annex #29, Unicode Text Segmentation, http://www.unicode.org/reports/tr29/ for additional information on grapheme clusters and guidelines on their use.

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

The text boundary positions are found according to the rules described in Unicode Standard Annex #29, Text Boundaries, and Unicode Standard Annex #14, Line Breaking Properties. These are available at http://www.unicode.org/reports/tr14/ and http://www.unicode.org/reports/tr29/.

In addition to the plain C API defined in this header file, an object oriented C++ API with equivalent functionality is defined in the file brkiter.h.

Code snippets illustrating the use of the Break Iterator APIs are available in the ICU User Guide, http://icu-project.org/userguide/boundaryAnalysis.html and in the sample program icu/source/samples/break/break.cpp

Definition in file ubrk.h.

## Define Documentation

#define U_BRK_SAFECLONE_BUFFERSIZE 512

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

Stable:
  ICU 2.0

Definition at line 270 of file ubrk.h.

#define UBRK_DONE ((int32_t) -1)

Value indicating all text boundaries have been returned.

Stable:
  ICU 2.0

Definition at line 114 of file ubrk.h.

## Typedef Documentation

typedef struct UBreakIterator UBreakIterator

A text-break iterator.

For usage in C programs. Opaque type representing an ICU Break iterator object.

Stable:
  ICU 2.0

Definition at line 26 of file ubrk.h.

## Enumeration Type Documentation

enum UBreakIteratorType

The possible types of text boundaries.

Stable:
  ICU 2.0

Enumerator:

  UBRK_CHARACTER | Character breaks. Stable: ICU 2.0
  UBRK_WORD | Word breaks. Stable: ICU 2.0
  UBRK_LINE | Line breaks. Stable: ICU 2.0
  UBRK_SENTENCE | Sentence breaks. Stable: 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.

Definition at line 87 of file ubrk.h.

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.

Stable:
  ICU 2.8

Enumerator:

  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.

Definition at line 158 of file ubrk.h.

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.

Stable:
  ICU 2.8

Enumerator:

  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.

Definition at line 180 of file ubrk.h.

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.

Stable:
  ICU 2.2

Enumerator:

  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.

Definition at line 125 of file ubrk.h.

## Function Documentation

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:
  ICU 2.0

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 ubrk_getAvailable.

Returns:
  The number of locales for which text breaking information is available.

See also:
  ubrk_getAvailable

Stable:
  ICU 2.0

int32_t 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.

Stable:
  ICU 2.0

int32_t 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:
  ICU 2.0

int32_t 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

Stable:
  ICU 2.0

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:
  ICU 2.0

const char* 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

Stable:
  ICU 2.8

int32_t 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.

Stable:
  ICU 2.2

int32_t ubrk_getRuleStatusVec | ( | UBreakIterator * | bi,
|  | int32_t * | fillInVec,
|  | int32_t | capacity,
|  | UErrorCode * | status |
| ) |  |  |

Get the statuses from the break rules that determined the most recently returned break position.

The values appear in the rule source within brackets, {123}, for example. The default status value for rules that do not explicitly provide one is zero.

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

Parameters:

  | bi | The break iterator to use
  | fillInVec | an array to be filled in with the status values.
  | capacity | the length of the supplied vector. A length of zero causes the function to return the number of status values, in the normal way, without attemtping to store any values.
  | status | receives error codes.

Returns:
  The number of rule status values from rules that determined the most recent boundary returned by the break iterator.

Stable:
  ICU 3.0

UBool 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.

Stable:
  ICU 2.0

int32_t 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:
  ICU 2.0

int32_t 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:
  ICU 2.0

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:
  ICU 2.0

UBreakIterator* 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

Stable:
  ICU 2.2

int32_t 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

Stable:
  ICU 2.0

int32_t 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:
  ICU 2.0

UBreakIterator* 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

Stable:
  ICU 2.0

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.

Parameters:

  | bi | The iterator to use
  | text | The text to be set
  | textLength | The length of the text
  | status | The error code

Stable:
  ICU 2.0

void ubrk_setUText | ( | UBreakIterator * | bi,
|  | UText * | text,
|  | 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. This function makes a shallow clone of the supplied UText. This means that the caller is free to immediately close or otherwise reuse the UText that was passed as a parameter, but that the underlying text itself must not be altered while being referenced by the break iterator.
  | status | The error code

Stable:
  ICU 3.4

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines