michael@0: * Line boundary analysis determines where a text string can be broken michael@0: * when line-wrapping. The mechanism correctly handles punctuation and michael@0: * hyphenated words. michael@0: *
michael@0: * Sentence boundary analysis allows selection with correct michael@0: * interpretation of periods within numbers and abbreviations, and michael@0: * trailing punctuation marks such as quotation marks and parentheses. michael@0: *
michael@0: * Word boundary analysis is used by search and replace functions, as michael@0: * well as within text editing applications that allow the user to michael@0: * select words with a double click. Word selection provides correct michael@0: * interpretation of punctuation marks within and following michael@0: * words. Characters that are not part of a word, such as symbols or michael@0: * punctuation marks, have word-breaks on both sides. michael@0: *
michael@0: * Character boundary analysis identifies the boundaries of michael@0: * "Extended Grapheme Clusters", which are groupings of codepoints michael@0: * that should be treated as character-like units for many text operations. michael@0: * Please see Unicode Standard Annex #29, Unicode Text Segmentation, michael@0: * http://www.unicode.org/reports/tr29/ for additional information michael@0: * on grapheme clusters and guidelines on their use. michael@0: *
michael@0: * Title boundary analysis locates all positions, michael@0: * typically starts of words, that should be set to Title Case michael@0: * when title casing the text. michael@0: *
michael@0: * The text boundary positions are found according to the rules michael@0: * described in Unicode Standard Annex #29, Text Boundaries, and michael@0: * Unicode Standard Annex #14, Line Breaking Properties. These michael@0: * are available at http://www.unicode.org/reports/tr14/ and michael@0: * http://www.unicode.org/reports/tr29/. michael@0: *
michael@0: * In addition to the plain C API defined in this header file, an michael@0: * object oriented C++ API with equivalent functionality is defined in the michael@0: * file brkiter.h. michael@0: *
michael@0: * Code snippets illustrating the use of the Break Iterator APIs
michael@0: * are available in the ICU User Guide,
michael@0: * http://icu-project.org/userguide/boundaryAnalysis.html
michael@0: * and in the sample program icu/source/samples/break/break.cpp
michael@0: */
michael@0:
michael@0: /** The possible types of text boundaries. @stable ICU 2.0 */
michael@0: typedef enum UBreakIteratorType {
michael@0: /** Character breaks @stable ICU 2.0 */
michael@0: UBRK_CHARACTER = 0,
michael@0: /** Word breaks @stable ICU 2.0 */
michael@0: UBRK_WORD = 1,
michael@0: /** Line breaks @stable ICU 2.0 */
michael@0: UBRK_LINE = 2,
michael@0: /** Sentence breaks @stable ICU 2.0 */
michael@0: UBRK_SENTENCE = 3,
michael@0:
michael@0: #ifndef U_HIDE_DEPRECATED_API
michael@0: /**
michael@0: * Title Case breaks
michael@0: * The iterator created using this type locates title boundaries as described for
michael@0: * Unicode 3.2 only. For Unicode 4.0 and above title boundary iteration,
michael@0: * please use Word Boundary iterator.
michael@0: *
michael@0: * @deprecated ICU 2.8 Use the word break iterator for titlecasing for Unicode 4 and later.
michael@0: */
michael@0: UBRK_TITLE = 4,
michael@0: #endif /* U_HIDE_DEPRECATED_API */
michael@0: UBRK_COUNT = 5
michael@0: } UBreakIteratorType;
michael@0:
michael@0: /** Value indicating all text boundaries have been returned.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: #define UBRK_DONE ((int32_t) -1)
michael@0:
michael@0:
michael@0: /**
michael@0: * Enum constants for the word break tags returned by
michael@0: * getRuleStatus(). A range of values is defined for each category of
michael@0: * word, to allow for further subdivisions of a category in future releases.
michael@0: * Applications should check for tag values falling within the range, rather
michael@0: * than for single individual values.
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: typedef enum UWordBreak {
michael@0: /** Tag value for "words" that do not fit into any of other categories.
michael@0: * Includes spaces and most punctuation. */
michael@0: UBRK_WORD_NONE = 0,
michael@0: /** Upper bound for tags for uncategorized words. */
michael@0: UBRK_WORD_NONE_LIMIT = 100,
michael@0: /** Tag value for words that appear to be numbers, lower limit. */
michael@0: UBRK_WORD_NUMBER = 100,
michael@0: /** Tag value for words that appear to be numbers, upper limit. */
michael@0: UBRK_WORD_NUMBER_LIMIT = 200,
michael@0: /** Tag value for words that contain letters, excluding
michael@0: * hiragana, katakana or ideographic characters, lower limit. */
michael@0: UBRK_WORD_LETTER = 200,
michael@0: /** Tag value for words containing letters, upper limit */
michael@0: UBRK_WORD_LETTER_LIMIT = 300,
michael@0: /** Tag value for words containing kana characters, lower limit */
michael@0: UBRK_WORD_KANA = 300,
michael@0: /** Tag value for words containing kana characters, upper limit */
michael@0: UBRK_WORD_KANA_LIMIT = 400,
michael@0: /** Tag value for words containing ideographic characters, lower limit */
michael@0: UBRK_WORD_IDEO = 400,
michael@0: /** Tag value for words containing ideographic characters, upper limit */
michael@0: UBRK_WORD_IDEO_LIMIT = 500
michael@0: } UWordBreak;
michael@0:
michael@0: /**
michael@0: * Enum constants for the line break tags returned by getRuleStatus().
michael@0: * A range of values is defined for each category of
michael@0: * word, to allow for further subdivisions of a category in future releases.
michael@0: * Applications should check for tag values falling within the range, rather
michael@0: * than for single individual values.
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: typedef enum ULineBreakTag {
michael@0: /** Tag value for soft line breaks, positions at which a line break
michael@0: * is acceptable but not required */
michael@0: UBRK_LINE_SOFT = 0,
michael@0: /** Upper bound for soft line breaks. */
michael@0: UBRK_LINE_SOFT_LIMIT = 100,
michael@0: /** Tag value for a hard, or mandatory line break */
michael@0: UBRK_LINE_HARD = 100,
michael@0: /** Upper bound for hard line breaks. */
michael@0: UBRK_LINE_HARD_LIMIT = 200
michael@0: } ULineBreakTag;
michael@0:
michael@0:
michael@0:
michael@0: /**
michael@0: * Enum constants for the sentence break tags returned by getRuleStatus().
michael@0: * A range of values is defined for each category of
michael@0: * sentence, to allow for further subdivisions of a category in future releases.
michael@0: * Applications should check for tag values falling within the range, rather
michael@0: * than for single individual values.
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: typedef enum USentenceBreakTag {
michael@0: /** Tag value for for sentences ending with a sentence terminator
michael@0: * ('.', '?', '!', etc.) character, possibly followed by a
michael@0: * hard separator (CR, LF, PS, etc.)
michael@0: */
michael@0: UBRK_SENTENCE_TERM = 0,
michael@0: /** Upper bound for tags for sentences ended by sentence terminators. */
michael@0: UBRK_SENTENCE_TERM_LIMIT = 100,
michael@0: /** Tag value for for sentences that do not contain an ending
michael@0: * sentence terminator ('.', '?', '!', etc.) character, but
michael@0: * are ended only by a hard separator (CR, LF, PS, etc.) or end of input.
michael@0: */
michael@0: UBRK_SENTENCE_SEP = 100,
michael@0: /** Upper bound for tags for sentences ended by a separator. */
michael@0: UBRK_SENTENCE_SEP_LIMIT = 200
michael@0: /** Tag value for a hard, or mandatory line break */
michael@0: } USentenceBreakTag;
michael@0:
michael@0:
michael@0: /**
michael@0: * Open a new UBreakIterator for locating text boundaries for a specified locale.
michael@0: * A UBreakIterator may be used for detecting character, line, word,
michael@0: * and sentence breaks in text.
michael@0: * @param type The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD,
michael@0: * UBRK_LINE, UBRK_SENTENCE
michael@0: * @param locale The locale specifying the text-breaking conventions.
michael@0: * @param text The text to be iterated over.
michael@0: * @param textLength The number of characters in text, or -1 if null-terminated.
michael@0: * @param status A UErrorCode to receive any errors.
michael@0: * @return A UBreakIterator for the specified locale.
michael@0: * @see ubrk_openRules
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBreakIterator* U_EXPORT2
michael@0: ubrk_open(UBreakIteratorType type,
michael@0: const char *locale,
michael@0: const UChar *text,
michael@0: int32_t textLength,
michael@0: UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Open a new UBreakIterator for locating text boundaries using specified breaking rules.
michael@0: * The rule syntax is ... (TBD)
michael@0: * @param rules A set of rules specifying the text breaking conventions.
michael@0: * @param rulesLength The number of characters in rules, or -1 if null-terminated.
michael@0: * @param text The text to be iterated over. May be null, in which case ubrk_setText() is
michael@0: * used to specify the text to be iterated.
michael@0: * @param textLength The number of characters in text, or -1 if null-terminated.
michael@0: * @param parseErr Receives position and context information for any syntax errors
michael@0: * detected while parsing the rules.
michael@0: * @param status A UErrorCode to receive any errors.
michael@0: * @return A UBreakIterator for the specified rules.
michael@0: * @see ubrk_open
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: U_STABLE UBreakIterator* U_EXPORT2
michael@0: ubrk_openRules(const UChar *rules,
michael@0: int32_t rulesLength,
michael@0: const UChar *text,
michael@0: int32_t textLength,
michael@0: UParseError *parseErr,
michael@0: UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Thread safe cloning operation
michael@0: * @param bi iterator to be cloned
michael@0: * @param stackBuffer Deprecated functionality as of ICU 52, use NULL.
michael@0: * user allocated space for the new clone. If NULL new memory will be allocated.
michael@0: * If buffer is not large enough, new memory will be allocated.
michael@0: * Clients can use the U_BRK_SAFECLONE_BUFFERSIZE.
michael@0: * @param pBufferSize Deprecated functionality as of ICU 52, use NULL or 1.
michael@0: * pointer to size of allocated space.
michael@0: * If *pBufferSize == 0, a sufficient size for use in cloning will
michael@0: * be returned ('pre-flighting')
michael@0: * If *pBufferSize is not enough for a stack-based safe clone,
michael@0: * new memory will be allocated.
michael@0: * @param status to indicate whether the operation went on smoothly or there were errors
michael@0: * An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were necessary.
michael@0: * @return pointer to the new clone
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBreakIterator * U_EXPORT2
michael@0: ubrk_safeClone(
michael@0: const UBreakIterator *bi,
michael@0: void *stackBuffer,
michael@0: int32_t *pBufferSize,
michael@0: UErrorCode *status);
michael@0:
michael@0: #ifndef U_HIDE_DEPRECATED_API
michael@0:
michael@0: /**
michael@0: * A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone().
michael@0: * @deprecated ICU 52. Do not rely on ubrk_safeClone() cloning into any provided buffer.
michael@0: */
michael@0: #define U_BRK_SAFECLONE_BUFFERSIZE 1
michael@0:
michael@0: #endif /* U_HIDE_DEPRECATED_API */
michael@0:
michael@0: /**
michael@0: * Close a UBreakIterator.
michael@0: * Once closed, a UBreakIterator may no longer be used.
michael@0: * @param bi The break iterator to close.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ubrk_close(UBreakIterator *bi);
michael@0:
michael@0: #if U_SHOW_CPLUSPLUS_API
michael@0:
michael@0: U_NAMESPACE_BEGIN
michael@0:
michael@0: /**
michael@0: * \class LocalUBreakIteratorPointer
michael@0: * "Smart pointer" class, closes a UBreakIterator via ubrk_close().
michael@0: * For most methods see the LocalPointerBase base class.
michael@0: *
michael@0: * @see LocalPointerBase
michael@0: * @see LocalPointer
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUBreakIteratorPointer, UBreakIterator, ubrk_close);
michael@0:
michael@0: U_NAMESPACE_END
michael@0:
michael@0: #endif
michael@0:
michael@0: /**
michael@0: * Sets an existing iterator to point to a new piece of text
michael@0: * @param bi The iterator to use
michael@0: * @param text The text to be set
michael@0: * @param textLength The length of the text
michael@0: * @param status The error code
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ubrk_setText(UBreakIterator* bi,
michael@0: const UChar* text,
michael@0: int32_t textLength,
michael@0: UErrorCode* status);
michael@0:
michael@0:
michael@0: /**
michael@0: * Sets an existing iterator to point to a new piece of text.
michael@0: *
michael@0: * All index positions returned by break iterator functions are
michael@0: * native indices from the UText. For example, when breaking UTF-8
michael@0: * encoded text, the break positions returned by \ref ubrk_next, \ref ubrk_previous, etc.
michael@0: * will be UTF-8 string indices, not UTF-16 positions.
michael@0: *
michael@0: * @param bi The iterator to use
michael@0: * @param text The text to be set.
michael@0: * This function makes a shallow clone of the supplied UText. This means
michael@0: * that the caller is free to immediately close or otherwise reuse the
michael@0: * UText that was passed as a parameter, but that the underlying text itself
michael@0: * must not be altered while being referenced by the break iterator.
michael@0: * @param status The error code
michael@0: * @stable ICU 3.4
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ubrk_setUText(UBreakIterator* bi,
michael@0: UText* text,
michael@0: UErrorCode* status);
michael@0:
michael@0:
michael@0:
michael@0: /**
michael@0: * Determine the most recently-returned text boundary.
michael@0: *
michael@0: * @param bi The break iterator to use.
michael@0: * @return The character index most recently returned by \ref ubrk_next, \ref ubrk_previous,
michael@0: * \ref ubrk_first, or \ref ubrk_last.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_current(const UBreakIterator *bi);
michael@0:
michael@0: /**
michael@0: * Advance the iterator to the boundary following the current boundary.
michael@0: *
michael@0: * @param bi The break iterator to use.
michael@0: * @return The character index of the next text boundary, or UBRK_DONE
michael@0: * if all text boundaries have been returned.
michael@0: * @see ubrk_previous
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_next(UBreakIterator *bi);
michael@0:
michael@0: /**
michael@0: * Set the iterator position to the boundary preceding the current boundary.
michael@0: *
michael@0: * @param bi The break iterator to use.
michael@0: * @return The character index of the preceding text boundary, or UBRK_DONE
michael@0: * if all text boundaries have been returned.
michael@0: * @see ubrk_next
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_previous(UBreakIterator *bi);
michael@0:
michael@0: /**
michael@0: * Set the iterator position to the index of the first character in the text being scanned.
michael@0: * This is not always the same as index 0 of the text.
michael@0: * @param bi The break iterator to use.
michael@0: * @return The character index of the first character in the text being scanned.
michael@0: * @see ubrk_last
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_first(UBreakIterator *bi);
michael@0:
michael@0: /**
michael@0: * Set the iterator position to the index immediately beyond the last character in the text being scanned.
michael@0: * This is not the same as the last character.
michael@0: * @param bi The break iterator to use.
michael@0: * @return The character offset immediately beyond the last character in the
michael@0: * text being scanned.
michael@0: * @see ubrk_first
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_last(UBreakIterator *bi);
michael@0:
michael@0: /**
michael@0: * Set the iterator position to the first boundary preceding the specified offset.
michael@0: * The new position is always smaller than offset, or UBRK_DONE.
michael@0: * @param bi The break iterator to use.
michael@0: * @param offset The offset to begin scanning.
michael@0: * @return The text boundary preceding offset, or UBRK_DONE.
michael@0: * @see ubrk_following
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_preceding(UBreakIterator *bi,
michael@0: int32_t offset);
michael@0:
michael@0: /**
michael@0: * Advance the iterator to the first boundary following the specified offset.
michael@0: * The value returned is always greater than offset, or UBRK_DONE.
michael@0: * @param bi The break iterator to use.
michael@0: * @param offset The offset to begin scanning.
michael@0: * @return The text boundary following offset, or UBRK_DONE.
michael@0: * @see ubrk_preceding
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_following(UBreakIterator *bi,
michael@0: int32_t offset);
michael@0:
michael@0: /**
michael@0: * Get a locale for which text breaking information is available.
michael@0: * A UBreakIterator in a locale returned by this function will perform the correct
michael@0: * text breaking for the locale.
michael@0: * @param index The index of the desired locale.
michael@0: * @return A locale for which number text breaking information is available, or 0 if none.
michael@0: * @see ubrk_countAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE const char* U_EXPORT2
michael@0: ubrk_getAvailable(int32_t index);
michael@0:
michael@0: /**
michael@0: * Determine how many locales have text breaking information available.
michael@0: * This function is most useful as determining the loop ending condition for
michael@0: * calls to \ref ubrk_getAvailable.
michael@0: * @return The number of locales for which text breaking information is available.
michael@0: * @see ubrk_getAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ubrk_countAvailable(void);
michael@0:
michael@0:
michael@0: /**
michael@0: * Returns true if the specfied position is a boundary position. As a side
michael@0: * effect, leaves the iterator pointing to the first boundary position at
michael@0: * or after "offset".
michael@0: * @param bi The break iterator to use.
michael@0: * @param offset the offset to check.
michael@0: * @return True if "offset" is a boundary position.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: ubrk_isBoundary(UBreakIterator *bi, int32_t offset);
michael@0:
michael@0: /**
michael@0: * Return the status from the break rule that determined the most recently
michael@0: * returned break position. The values appear in the rule source
michael@0: * within brackets, {123}, for example. For rules that do not specify a
michael@0: * status, a default value of 0 is returned.
michael@0: *
michael@0: * For word break iterators, the possible values are defined in enum UWordBreak. michael@0: * @stable ICU 2.2 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ubrk_getRuleStatus(UBreakIterator *bi); michael@0: michael@0: /** michael@0: * Get the statuses from the break rules that determined the most recently michael@0: * returned break position. The values appear in the rule source michael@0: * within brackets, {123}, for example. The default status value for rules michael@0: * that do not explicitly provide one is zero. michael@0: *
michael@0: * For word break iterators, the possible values are defined in enum UWordBreak. michael@0: * @param bi The break iterator to use michael@0: * @param fillInVec an array to be filled in with the status values. michael@0: * @param capacity the length of the supplied vector. A length of zero causes michael@0: * the function to return the number of status values, in the michael@0: * normal way, without attemtping to store any values. michael@0: * @param status receives error codes. michael@0: * @return The number of rule status values from rules that determined michael@0: * the most recent boundary returned by the break iterator. michael@0: * @stable ICU 3.0 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ubrk_getRuleStatusVec(UBreakIterator *bi, int32_t *fillInVec, int32_t capacity, UErrorCode *status); michael@0: michael@0: /** michael@0: * Return the locale of the break iterator. You can choose between the valid and michael@0: * the actual locale. michael@0: * @param bi break iterator michael@0: * @param type locale type (valid or actual) michael@0: * @param status error code michael@0: * @return locale string michael@0: * @stable ICU 2.8 michael@0: */ michael@0: U_STABLE const char* U_EXPORT2 michael@0: ubrk_getLocaleByType(const UBreakIterator *bi, ULocDataLocaleType type, UErrorCode* status); michael@0: michael@0: /** michael@0: * Set the subject text string upon which the break iterator is operating michael@0: * without changing any other aspect of the state. michael@0: * The new and previous text strings must have the same content. michael@0: * michael@0: * This function is intended for use in environments where ICU is operating on michael@0: * strings that may move around in memory. It provides a mechanism for notifying michael@0: * ICU that the string has been relocated, and providing a new UText to access the michael@0: * string in its new position. michael@0: * michael@0: * Note that the break iterator never copies the underlying text michael@0: * of a string being processed, but always operates directly on the original text michael@0: * provided by the user. Refreshing simply drops the references to the old text michael@0: * and replaces them with references to the new. michael@0: * michael@0: * Caution: this function is normally used only by very specialized michael@0: * system-level code. One example use case is with garbage collection michael@0: * that moves the text in memory. michael@0: * michael@0: * @param bi The break iterator. michael@0: * @param text The new (moved) text string. michael@0: * @param status Receives errors detected by this function. michael@0: * michael@0: * @stable ICU 49 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ubrk_refreshUText(UBreakIterator *bi, michael@0: UText *text, michael@0: UErrorCode *status); michael@0: michael@0: #endif /* #if !UCONFIG_NO_BREAK_ITERATION */ michael@0: michael@0: #endif