ICU 74.1 74.1

Namespaces | Macros | Typedefs | Enumerations | Functions
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.

## Namespaces
| icu
| File coll.h.

## Macros
#define | UBRK_TYPEDEF_UBREAK_ITERATOR
| A text-break iterator. More...
#define | UBRK_DONE ((int32_t) -1)
| Value indicating all text boundaries have been returned. More...
#define | U_BRK_SAFECLONE_BUFFERSIZE 1
| A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone(). More...

## Typedefs
typedef struct UBreakIterator | UBreakIterator
| Opaque type representing an ICU Break iterator object. More...
typedef enum UBreakIteratorType | UBreakIteratorType
| The possible types of text boundaries. More...
typedef enum UWordBreak | UWordBreak
| Enum constants for the word break tags returned by getRuleStatus(). More...
typedef enum ULineBreakTag | ULineBreakTag
| Enum constants for the line break tags returned by getRuleStatus(). More...
typedef enum USentenceBreakTag | USentenceBreakTag
| Enum constants for the sentence break tags returned by getRuleStatus(). More...

## 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
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. More...
U_CAPI 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. More...
U_CAPI UBreakIterator * | ubrk_openBinaryRules (const uint8_t *binaryRules, int32_t rulesLength, const UChar *text, int32_t textLength, UErrorCode *status)
| Open a new UBreakIterator for locating text boundaries using precompiled binary rules. More...
UBreakIterator * | ubrk_safeClone (const UBreakIterator *bi, void *stackBuffer, int32_t *pBufferSize, UErrorCode *status)
| Thread safe cloning operation. More...
U_CAPI UBreakIterator * | ubrk_clone (const UBreakIterator *bi, UErrorCode *status)
| Thread safe cloning operation. 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 void | ubrk_setUText (UBreakIterator *bi, UText *text, UErrorCode *status)
| Sets an existing iterator to point to a new piece of text. More...
U_CAPI int32_t | ubrk_current (const UBreakIterator *bi)
| Determine the most recently-returned text boundary. More...
U_CAPI int32_t | ubrk_next (UBreakIterator *bi)
| Advance the iterator to the boundary following the current boundary. More...
U_CAPI int32_t | ubrk_previous (UBreakIterator *bi)
| Set the iterator position to the boundary preceding the current boundary. More...
U_CAPI int32_t | ubrk_first (UBreakIterator *bi)
| Set the iterator position to zero, the start of the text being scanned. More...
U_CAPI int32_t | ubrk_last (UBreakIterator *bi)
| Set the iterator position to the index immediately beyond the last character in the text being scanned. More...
U_CAPI int32_t | ubrk_preceding (UBreakIterator *bi, int32_t offset)
| Set the iterator position to the first boundary preceding the specified offset. More...
U_CAPI int32_t | ubrk_following (UBreakIterator *bi, int32_t offset)
| Advance the iterator to the first 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...
U_CAPI UBool | ubrk_isBoundary (UBreakIterator *bi, int32_t offset)
| Returns true if the specified position is a boundary position. More...
U_CAPI int32_t | ubrk_getRuleStatus (UBreakIterator *bi)
| Return the status from the break rule that determined the most recently returned break position. More...
U_CAPI 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. More...
U_CAPI const char * | ubrk_getLocaleByType (const UBreakIterator *bi, ULocDataLocaleType type, UErrorCode *status)
| Return the locale of the break iterator. More...
U_CAPI void | ubrk_refreshUText (UBreakIterator *bi, UText *text, UErrorCode *status)
| Set the subject text string upon which the break iterator is operating without changing any other aspect of the state. More...
U_CAPI int32_t | ubrk_getBinaryRules (UBreakIterator *bi, uint8_t *binaryRules, int32_t rulesCapacity, UErrorCode *status)
| Get a compiled binary version of the rules specifying the behavior of a UBreakIterator. More...

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

Note: The locale keyword "lb" can be used to modify line break behavior according to the CSS level 3 line-break options, see http://dev.w3.org/csswg/css-text/#line-breaking. For example: "ja@lb=strict", "zh@lb=loose".

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

Note: The locale keyword "ss" can be used to enable use of segmentation suppression data (preventing breaks in English after abbreviations such as "Mr." or "Est.", for example), as follows: "en@ss=standard".

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, https://unicode-org.github.io/icu/userguide/boundaryanalysis/ and in the sample program icu/source/samples/break/break.cpp

Definition in file ubrk.h.

## Macro Definition Documentation

## ◆ U_BRK_SAFECLONE_BUFFERSIZE

#define U_BRK_SAFECLONE_BUFFERSIZE 1

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

Deprecated:
  ICU 52. Do not rely on ubrk_safeClone() cloning into any provided buffer.

Definition at line 346 of file ubrk.h.

## ◆ UBRK_DONE

#define UBRK_DONE ((int32_t) -1)

Value indicating all text boundaries have been returned.

Stable:
  ICU 2.0

Definition at line 133 of file ubrk.h.

## ◆ UBRK_TYPEDEF_UBREAK_ITERATOR

#define UBRK_TYPEDEF_UBREAK_ITERATOR

A text-break iterator.

For usage in C programs.

Definition at line 26 of file ubrk.h.

## Typedef Documentation

## ◆ UBreakIterator

typedef struct UBreakIterator UBreakIterator

Opaque type representing an ICU Break iterator object.

Stable:
  ICU 2.0

Definition at line 1 of file ubrk.h.

## ◆ UBreakIteratorType

typedef enum UBreakIteratorType UBreakIteratorType

The possible types of text boundaries.

Stable:
  ICU 2.0

## ◆ ULineBreakTag

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.

The numeric values of all of these constants are stable (will not change).

Stable:
  ICU 2.8

## ◆ USentenceBreakTag

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.

The numeric values of all of these constants are stable (will not change).

Stable:
  ICU 2.8

## ◆ UWordBreak

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.

The numeric values of all of these constants are stable (will not change).

Stable:
  ICU 2.2

## Enumeration Type Documentation

## ◆ UBreakIteratorType

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.
UBRK_COUNT | One more than the highest normal UBreakIteratorType value. Deprecated: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 102 of file ubrk.h.

## ◆ ULineBreakTag

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.

The numeric values of all of these constants are stable (will not change).

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 183 of file ubrk.h.

## ◆ USentenceBreakTag

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.

The numeric values of all of these constants are stable (will not change).

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 208 of file ubrk.h.

## ◆ UWordBreak

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.

The numeric values of all of these constants are stable (will not change).

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 147 of file ubrk.h.

## Function Documentation

## ◆ ubrk_clone()

U_CAPI UBreakIterator* ubrk_clone | ( | const UBreakIterator * | bi,
|  | UErrorCode * | status
| ) |  |

Thread safe cloning operation.

Parameters

  bi | iterator to be cloned
  status | to indicate whether the operation went on smoothly or there were errors

Returns
  pointer to the new clone

Stable:
  ICU 69

## ◆ ubrk_close()

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

## ◆ ubrk_countAvailable()

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

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

See also
  ubrk_getAvailable

Stable:
  ICU 2.0

## ◆ ubrk_current()

U_CAPI 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

## ◆ ubrk_first()

U_CAPI int32_t ubrk_first | ( | UBreakIterator * | bi | ) |

Set the iterator position to zero, the start of the text being scanned.

Parameters

  bi | The break iterator to use.

Returns
  The new iterator position (zero).

See also
  ubrk_last

Stable:
  ICU 2.0

## ◆ ubrk_following()

U_CAPI int32_t ubrk_following | ( | UBreakIterator * | bi,
|  | int32_t | offset
| ) |  |

Advance the iterator to the first 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

## ◆ ubrk_getAvailable()

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

## ◆ ubrk_getBinaryRules()

U_CAPI int32_t ubrk_getBinaryRules | ( | UBreakIterator * | bi,
|  | uint8_t * | binaryRules,
|  | int32_t | rulesCapacity,
|  | UErrorCode * | status
| ) |  |

Get a compiled binary version of the rules specifying the behavior of a UBreakIterator.

The binary rules may be used with ubrk_openBinaryRules to open a new UBreakIterator more quickly than using ubrk_openRules. The compiled rules are not compatible across different major versions of ICU, nor across platforms of different endianness or different base character set family (ASCII vs EBCDIC). Supports preflighting (with binaryRules=NULL and rulesCapacity=0) to get the rules length without copying them to the binaryRules buffer. However, whether preflighting or not, if the actual length is greater than INT32_MAX, then the function returns 0 and sets *status to U_INDEX_OUTOFBOUNDS_ERROR.

Parameters

  bi | The break iterator to use.
  binaryRules | Buffer to receive the compiled binary rules; set to NULL for preflighting.
  rulesCapacity | Capacity (in bytes) of the binaryRules buffer; set to 0 for preflighting. Must be >= 0.
  status | Pointer to UErrorCode to receive any errors, such as U_BUFFER_OVERFLOW_ERROR, U_INDEX_OUTOFBOUNDS_ERROR, or U_ILLEGAL_ARGUMENT_ERROR.

Returns
  The actual byte length of the binary rules, if <= INT32_MAX; otherwise 0. If not preflighting and this is larger than rulesCapacity, *status will be set to an error.

See also
  ubrk_openBinaryRules

Stable:
  ICU 59

## ◆ ubrk_getLocaleByType()

U_CAPI 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

## ◆ ubrk_getRuleStatus()

U_CAPI 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

## ◆ ubrk_getRuleStatusVec()

U_CAPI 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 attempting 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

## ◆ ubrk_isBoundary()

U_CAPI UBool ubrk_isBoundary | ( | UBreakIterator * | bi,
|  | int32_t | offset
| ) |  |

Returns true if the specified 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

## ◆ ubrk_last()

U_CAPI int32_t ubrk_last | ( | UBreakIterator * | bi | ) |

Set the iterator position to 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

## ◆ ubrk_next()

U_CAPI int32_t ubrk_next | ( | UBreakIterator * | bi | ) |

Advance the iterator to the boundary following the current 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

## ◆ ubrk_open()

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. Note that locale keys such as "lb" and "ss" may be used to modify text break behavior, see general discussion of BreakIterator C API.
  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.
  status | A UErrorCode to receive any errors.

Returns
  A UBreakIterator for the specified locale.

See also
  ubrk_openRules

Stable:
  ICU 2.0

## ◆ ubrk_openBinaryRules()

U_CAPI UBreakIterator* ubrk_openBinaryRules | ( | const uint8_t * | binaryRules,
|  | int32_t | rulesLength,
|  | const UChar * | text,
|  | int32_t | textLength,
|  | UErrorCode * | status
| ) |  |

Open a new UBreakIterator for locating text boundaries using precompiled binary rules.

Opening a UBreakIterator this way is substantially faster than using ubrk_openRules. Binary rules may be obtained using ubrk_getBinaryRules. The compiled rules are not compatible across different major versions of ICU, nor across platforms of different endianness or different base character set family (ASCII vs EBCDIC).

Parameters

  binaryRules | A set of compiled binary rules specifying the text breaking conventions. Ownership of the storage containing the compiled rules remains with the caller of this function. The compiled rules must not be modified or deleted during the life of the break iterator.
  rulesLength | The length of binaryRules in bytes; must be >= 0.
  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.
  status | Pointer to UErrorCode to receive any errors.

Returns
  UBreakIterator for the specified rules.

See also
  ubrk_getBinaryRules

Stable:
  ICU 59

## ◆ ubrk_openRules()

U_CAPI 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

## ◆ ubrk_preceding()

U_CAPI int32_t ubrk_preceding | ( | UBreakIterator * | bi,
|  | int32_t | offset
| ) |  |

Set the iterator position to the first boundary preceding the specified offset.

The new position 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

## ◆ ubrk_previous()

U_CAPI int32_t ubrk_previous | ( | UBreakIterator * | bi | ) |

Set the iterator position to the boundary preceding the current 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

## ◆ ubrk_refreshUText()

U_CAPI void ubrk_refreshUText | ( | UBreakIterator * | bi,
|  | UText * | text,
|  | UErrorCode * | status
| ) |  |

Set the subject text string upon which the break iterator is operating without changing any other aspect of the state.

The new and previous text strings must have the same content.

This function is intended for use in environments where ICU is operating on strings that may move around in memory. It provides a mechanism for notifying ICU that the string has been relocated, and providing a new UText to access the string in its new position.

Note that the break iterator never copies the underlying text of a string being processed, but always operates directly on the original text provided by the user. Refreshing simply drops the references to the old text and replaces them with references to the new.

Caution: this function is normally used only by very specialized system-level code. One example use case is with garbage collection that moves the text in memory.

Parameters

  bi | The break iterator.
  text | The new (moved) text string.
  status | Receives errors detected by this function.

Stable:
  ICU 49

## ◆ ubrk_safeClone()

UBreakIterator* ubrk_safeClone | ( | const UBreakIterator * | bi,
|  | void * | stackBuffer,
|  | int32_t * | pBufferSize,
|  | UErrorCode * | status
| ) |  |

Thread safe cloning operation.

Parameters

  bi | iterator to be cloned
  stackBuffer | Deprecated functionality as of ICU 52, use NULL. 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.
  pBufferSize | Deprecated functionality as of ICU 52, use NULL or 1. 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 pBufferSize != NULL and any allocations were necessary

Returns
  pointer to the new clone

Deprecated:
  ICU 69 Use ubrk_clone() instead.

## ◆ ubrk_setText()

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.

The break iterator retains a pointer to the supplied text. The caller must not modify or delete the text while the BreakIterator retains the reference.

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

## ◆ ubrk_setUText()

U_CAPI void ubrk_setUText | ( | UBreakIterator * | bi,
|  | UText * | text,
|  | UErrorCode * | status
| ) |  |

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

All index positions returned by break iterator functions are native indices from the UText. For example, when breaking UTF-8 encoded text, the break positions returned by ubrk_next, ubrk_previous, etc. will be UTF-8 string indices, not UTF-16 positions.

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