sl@0: * Line boundary analysis determines where a text string can be broken sl@0: * when line-wrapping. The mechanism correctly handles punctuation and sl@0: * hyphenated words. sl@0: *
sl@0: * Sentence boundary analysis allows selection with correct sl@0: * interpretation of periods within numbers and abbreviations, and sl@0: * trailing punctuation marks such as quotation marks and parentheses. sl@0: *
sl@0: * Word boundary analysis is used by search and replace functions, as sl@0: * well as within text editing applications that allow the user to sl@0: * select words with a double click. Word selection provides correct sl@0: * interpretation of punctuation marks within and following sl@0: * words. Characters that are not part of a word, such as symbols or sl@0: * punctuation marks, have word-breaks on both sides. sl@0: *
sl@0: * Character boundary analysis allows users to interact with sl@0: * characters as they expect to, for example, when moving the cursor sl@0: * through a text string. Character boundary analysis provides correct sl@0: * navigation of through character strings, regardless of how the sl@0: * character is stored. For example, an accented character might be sl@0: * stored as a base character and a diacritical mark. What users sl@0: * consider to be a character can differ between languages. sl@0: *
sl@0: * Title boundary analysis locates all positions, sl@0: * typically starts of words, that should be set to Title Case sl@0: * when title casing the text. sl@0: *
sl@0: * sl@0: * This is the interface for all text boundaries. sl@0: *
sl@0: * Examples: sl@0: *
sl@0: * Helper function to output text sl@0: *
sl@0: * \code
sl@0: * void printTextRange(UChar* str, int32_t start, int32_t end ) {
sl@0: * UChar* result;
sl@0: * UChar* temp;
sl@0: * const char* res;
sl@0: * temp=(UChar*)malloc(sizeof(UChar) * ((u_strlen(str)-start)+1));
sl@0: * result=(UChar*)malloc(sizeof(UChar) * ((end-start)+1));
sl@0: * u_strcpy(temp, &str[start]);
sl@0: * u_strncpy(result, temp, end-start);
sl@0: * res=(char*)malloc(sizeof(char) * (u_strlen(result)+1));
sl@0: * u_austrcpy(res, result);
sl@0: * printf("%s\n", res);
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Print each element in order:
sl@0: *
sl@0: * \code
sl@0: * void printEachForward( UBreakIterator* boundary, UChar* str) {
sl@0: * int32_t end;
sl@0: * int32_t start = ubrk_first(boundary);
sl@0: * for (end = ubrk_next(boundary)); end != UBRK_DONE; start = end, end = ubrk_next(boundary)) {
sl@0: * printTextRange(str, start, end );
sl@0: * }
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Print each element in reverse order:
sl@0: *
sl@0: * \code
sl@0: * void printEachBackward( UBreakIterator* boundary, UChar* str) {
sl@0: * int32_t start;
sl@0: * int32_t end = ubrk_last(boundary);
sl@0: * for (start = ubrk_previous(boundary); start != UBRK_DONE; end = start, start =ubrk_previous(boundary)) {
sl@0: * printTextRange( str, start, end );
sl@0: * }
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Print first element
sl@0: *
sl@0: * \code
sl@0: * void printFirst(UBreakIterator* boundary, UChar* str) {
sl@0: * int32_t end;
sl@0: * int32_t start = ubrk_first(boundary);
sl@0: * end = ubrk_next(boundary);
sl@0: * printTextRange( str, start, end );
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Print last element
sl@0: *
sl@0: * \code
sl@0: * void printLast(UBreakIterator* boundary, UChar* str) {
sl@0: * int32_t start;
sl@0: * int32_t end = ubrk_last(boundary);
sl@0: * start = ubrk_previous(boundary);
sl@0: * printTextRange(str, start, end );
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Print the element at a specified position
sl@0: *
sl@0: * \code
sl@0: * void printAt(UBreakIterator* boundary, int32_t pos , UChar* str) {
sl@0: * int32_t start;
sl@0: * int32_t end = ubrk_following(boundary, pos);
sl@0: * start = ubrk_previous(boundary);
sl@0: * printTextRange(str, start, end );
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Creating and using text boundaries
sl@0: *
sl@0: * \code
sl@0: * void BreakIterator_Example( void ) {
sl@0: * UBreakIterator* boundary;
sl@0: * UChar *stringToExamine;
sl@0: * stringToExamine=(UChar*)malloc(sizeof(UChar) * (strlen("Aaa bbb ccc. Ddd eee fff.")+1) );
sl@0: * u_uastrcpy(stringToExamine, "Aaa bbb ccc. Ddd eee fff.");
sl@0: * printf("Examining: "Aaa bbb ccc. Ddd eee fff.");
sl@0: *
sl@0: * //print each sentence in forward and reverse order
sl@0: * boundary = ubrk_open(UBRK_SENTENCE, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
sl@0: * printf("----- forward: -----------\n");
sl@0: * printEachForward(boundary, stringToExamine);
sl@0: * printf("----- backward: ----------\n");
sl@0: * printEachBackward(boundary, stringToExamine);
sl@0: * ubrk_close(boundary);
sl@0: *
sl@0: * //print each word in order
sl@0: * boundary = ubrk_open(UBRK_WORD, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
sl@0: * printf("----- forward: -----------\n");
sl@0: * printEachForward(boundary, stringToExamine);
sl@0: * printf("----- backward: ----------\n");
sl@0: * printEachBackward(boundary, stringToExamine);
sl@0: * //print first element
sl@0: * printf("----- first: -------------\n");
sl@0: * printFirst(boundary, stringToExamine);
sl@0: * //print last element
sl@0: * printf("----- last: --------------\n");
sl@0: * printLast(boundary, stringToExamine);
sl@0: * //print word at charpos 10
sl@0: * printf("----- at pos 10: ---------\n");
sl@0: * printAt(boundary, 10 , stringToExamine);
sl@0: *
sl@0: * ubrk_close(boundary);
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: */
sl@0:
sl@0: /** The possible types of text boundaries. @stable ICU 2.0 */
sl@0: typedef enum UBreakIteratorType {
sl@0: /** Character breaks @stable ICU 2.0 */
sl@0: UBRK_CHARACTER,
sl@0: /** Word breaks @stable ICU 2.0 */
sl@0: UBRK_WORD,
sl@0: /** Line breaks @stable ICU 2.0 */
sl@0: UBRK_LINE,
sl@0: /** Sentence breaks @stable ICU 2.0 */
sl@0: UBRK_SENTENCE,
sl@0:
sl@0: #ifndef U_HIDE_DEPRECATED_API
sl@0: /**
sl@0: * Title Case breaks
sl@0: * The iterator created using this type locates title boundaries as described for
sl@0: * Unicode 3.2 only. For Unicode 4.0 and above title boundary iteration,
sl@0: * please use Word Boundary iterator.
sl@0: *
sl@0: * @deprecated ICU 2.8 Use the word break iterator for titlecasing for Unicode 4 and later.
sl@0: */
sl@0: UBRK_TITLE
sl@0: #endif /* U_HIDE_DEPRECATED_API */
sl@0:
sl@0: } UBreakIteratorType;
sl@0:
sl@0: /** Value indicating all text boundaries have been returned.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: #define UBRK_DONE ((int32_t) -1)
sl@0:
sl@0:
sl@0: /**
sl@0: * Enum constants for the word break tags returned by
sl@0: * getRuleStatus(). A range of values is defined for each category of
sl@0: * word, to allow for further subdivisions of a category in future releases.
sl@0: * Applications should check for tag values falling within the range, rather
sl@0: * than for single individual values.
sl@0: * @stable ICU 2.2
sl@0: */
sl@0: typedef enum UWordBreak {
sl@0: /** Tag value for "words" that do not fit into any of other categories.
sl@0: * Includes spaces and most punctuation. */
sl@0: UBRK_WORD_NONE = 0,
sl@0: /** Upper bound for tags for uncategorized words. */
sl@0: UBRK_WORD_NONE_LIMIT = 100,
sl@0: /** Tag value for words that appear to be numbers, lower limit. */
sl@0: UBRK_WORD_NUMBER = 100,
sl@0: /** Tag value for words that appear to be numbers, upper limit. */
sl@0: UBRK_WORD_NUMBER_LIMIT = 200,
sl@0: /** Tag value for words that contain letters, excluding
sl@0: * hiragana, katakana or ideographic characters, lower limit. */
sl@0: UBRK_WORD_LETTER = 200,
sl@0: /** Tag value for words containing letters, upper limit */
sl@0: UBRK_WORD_LETTER_LIMIT = 300,
sl@0: /** Tag value for words containing kana characters, lower limit */
sl@0: UBRK_WORD_KANA = 300,
sl@0: /** Tag value for words containing kana characters, upper limit */
sl@0: UBRK_WORD_KANA_LIMIT = 400,
sl@0: /** Tag value for words containing ideographic characters, lower limit */
sl@0: UBRK_WORD_IDEO = 400,
sl@0: /** Tag value for words containing ideographic characters, upper limit */
sl@0: UBRK_WORD_IDEO_LIMIT = 500
sl@0: } UWordBreak;
sl@0:
sl@0: /**
sl@0: * Enum constants for the line break tags returned by getRuleStatus().
sl@0: * A range of values is defined for each category of
sl@0: * word, to allow for further subdivisions of a category in future releases.
sl@0: * Applications should check for tag values falling within the range, rather
sl@0: * than for single individual values.
sl@0: * @stable ICU 2.8
sl@0: */
sl@0: typedef enum ULineBreakTag {
sl@0: /** Tag value for soft line breaks, positions at which a line break
sl@0: * is acceptable but not required */
sl@0: UBRK_LINE_SOFT = 0,
sl@0: /** Upper bound for soft line breaks. */
sl@0: UBRK_LINE_SOFT_LIMIT = 100,
sl@0: /** Tag value for a hard, or mandatory line break */
sl@0: UBRK_LINE_HARD = 100,
sl@0: /** Upper bound for hard line breaks. */
sl@0: UBRK_LINE_HARD_LIMIT = 200
sl@0: } ULineBreakTag;
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: * Enum constants for the sentence break tags returned by getRuleStatus().
sl@0: * A range of values is defined for each category of
sl@0: * sentence, to allow for further subdivisions of a category in future releases.
sl@0: * Applications should check for tag values falling within the range, rather
sl@0: * than for single individual values.
sl@0: * @stable ICU 2.8
sl@0: */
sl@0: typedef enum USentenceBreakTag {
sl@0: /** Tag value for for sentences ending with a sentence terminator
sl@0: * ('.', '?', '!', etc.) character, possibly followed by a
sl@0: * hard separator (CR, LF, PS, etc.)
sl@0: */
sl@0: UBRK_SENTENCE_TERM = 0,
sl@0: /** Upper bound for tags for sentences ended by sentence terminators. */
sl@0: UBRK_SENTENCE_TERM_LIMIT = 100,
sl@0: /** Tag value for for sentences that do not contain an ending
sl@0: * sentence terminator ('.', '?', '!', etc.) character, but
sl@0: * are ended only by a hard separator (CR, LF, PS, etc.) or end of input.
sl@0: */
sl@0: UBRK_SENTENCE_SEP = 100,
sl@0: /** Upper bound for tags for sentences ended by a separator. */
sl@0: UBRK_SENTENCE_SEP_LIMIT = 200
sl@0: /** Tag value for a hard, or mandatory line break */
sl@0: } USentenceBreakTag;
sl@0:
sl@0:
sl@0: /**
sl@0: * Open a new UBreakIterator for locating text boundaries for a specified locale.
sl@0: * A UBreakIterator may be used for detecting character, line, word,
sl@0: * and sentence breaks in text.
sl@0: * @param type The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD,
sl@0: * UBRK_LINE, UBRK_SENTENCE
sl@0: * @param locale The locale specifying the text-breaking conventions.
sl@0: * @param text The text to be iterated over.
sl@0: * @param textLength The number of characters in text, or -1 if null-terminated.
sl@0: * @param status A UErrorCode to receive any errors.
sl@0: * @return A UBreakIterator for the specified locale.
sl@0: * @see ubrk_openRules
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE UBreakIterator* U_EXPORT2
sl@0: ubrk_open(UBreakIteratorType type,
sl@0: const char *locale,
sl@0: const UChar *text,
sl@0: int32_t textLength,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * Open a new UBreakIterator for locating text boundaries using specified breaking rules.
sl@0: * The rule syntax is ... (TBD)
sl@0: * @param rules A set of rules specifying the text breaking conventions.
sl@0: * @param rulesLength The number of characters in rules, or -1 if null-terminated.
sl@0: * @param text The text to be iterated over. May be null, in which case ubrk_setText() is
sl@0: * used to specify the text to be iterated.
sl@0: * @param textLength The number of characters in text, or -1 if null-terminated.
sl@0: * @param parseErr Receives position and context information for any syntax errors
sl@0: * detected while parsing the rules.
sl@0: * @param status A UErrorCode to receive any errors.
sl@0: * @return A UBreakIterator for the specified rules.
sl@0: * @see ubrk_open
sl@0: * @stable ICU 2.2
sl@0: */
sl@0: U_STABLE UBreakIterator* U_EXPORT2
sl@0: ubrk_openRules(const UChar *rules,
sl@0: int32_t rulesLength,
sl@0: const UChar *text,
sl@0: int32_t textLength,
sl@0: UParseError *parseErr,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * Thread safe cloning operation
sl@0: * @param bi iterator to be cloned
sl@0: * @param stackBuffer user allocated space for the new clone. If NULL new memory will be allocated.
sl@0: * If buffer is not large enough, new memory will be allocated.
sl@0: * Clients can use the U_BRK_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations.
sl@0: * @param pBufferSize pointer to size of allocated space.
sl@0: * If *pBufferSize == 0, a sufficient size for use in cloning will
sl@0: * be returned ('pre-flighting')
sl@0: * If *pBufferSize is not enough for a stack-based safe clone,
sl@0: * new memory will be allocated.
sl@0: * @param status to indicate whether the operation went on smoothly or there were errors
sl@0: * An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were necessary.
sl@0: * @return pointer to the new clone
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE UBreakIterator * U_EXPORT2
sl@0: ubrk_safeClone(
sl@0: const UBreakIterator *bi,
sl@0: void *stackBuffer,
sl@0: int32_t *pBufferSize,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone().
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: #define U_BRK_SAFECLONE_BUFFERSIZE 512
sl@0:
sl@0: /**
sl@0: * Close a UBreakIterator.
sl@0: * Once closed, a UBreakIterator may no longer be used.
sl@0: * @param bi The break iterator to close.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE void U_EXPORT2
sl@0: ubrk_close(UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Sets an existing iterator to point to a new piece of text
sl@0: * @param bi The iterator to use
sl@0: * @param text The text to be set
sl@0: * @param textLength The length of the text
sl@0: * @param status The error code
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE void U_EXPORT2
sl@0: ubrk_setText(UBreakIterator* bi,
sl@0: const UChar* text,
sl@0: int32_t textLength,
sl@0: UErrorCode* status);
sl@0:
sl@0:
sl@0: /**
sl@0: * Sets an existing iterator to point to a new piece of text
sl@0: * @param bi The iterator to use
sl@0: * @param text The text to be set
sl@0: * @param status The error code
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT void U_EXPORT2
sl@0: ubrk_setUText(UBreakIterator* bi,
sl@0: UText* text,
sl@0: UErrorCode* status);
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: * Determine the most recently-returned text boundary.
sl@0: *
sl@0: * @param bi The break iterator to use.
sl@0: * @return The character index most recently returned by \ref ubrk_next, \ref ubrk_previous,
sl@0: * \ref ubrk_first, or \ref ubrk_last.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_current(const UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Determine the text boundary following the current text boundary.
sl@0: *
sl@0: * @param bi The break iterator to use.
sl@0: * @return The character index of the next text boundary, or UBRK_DONE
sl@0: * if all text boundaries have been returned.
sl@0: * @see ubrk_previous
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_next(UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Determine the text boundary preceding the current text boundary.
sl@0: *
sl@0: * @param bi The break iterator to use.
sl@0: * @return The character index of the preceding text boundary, or UBRK_DONE
sl@0: * if all text boundaries have been returned.
sl@0: * @see ubrk_next
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_previous(UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Determine the index of the first character in the text being scanned.
sl@0: * This is not always the same as index 0 of the text.
sl@0: * @param bi The break iterator to use.
sl@0: * @return The character index of the first character in the text being scanned.
sl@0: * @see ubrk_last
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_first(UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Determine the index immediately beyond the last character in the text being
sl@0: * scanned.
sl@0: * This is not the same as the last character.
sl@0: * @param bi The break iterator to use.
sl@0: * @return The character offset immediately beyond the last character in the
sl@0: * text being scanned.
sl@0: * @see ubrk_first
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_last(UBreakIterator *bi);
sl@0:
sl@0: /**
sl@0: * Determine the text boundary preceding the specified offset.
sl@0: * The value returned is always smaller than offset, or UBRK_DONE.
sl@0: * @param bi The break iterator to use.
sl@0: * @param offset The offset to begin scanning.
sl@0: * @return The text boundary preceding offset, or UBRK_DONE.
sl@0: * @see ubrk_following
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_preceding(UBreakIterator *bi,
sl@0: int32_t offset);
sl@0:
sl@0: /**
sl@0: * Determine the text boundary following the specified offset.
sl@0: * The value returned is always greater than offset, or UBRK_DONE.
sl@0: * @param bi The break iterator to use.
sl@0: * @param offset The offset to begin scanning.
sl@0: * @return The text boundary following offset, or UBRK_DONE.
sl@0: * @see ubrk_preceding
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_following(UBreakIterator *bi,
sl@0: int32_t offset);
sl@0:
sl@0: /**
sl@0: * Get a locale for which text breaking information is available.
sl@0: * A UBreakIterator in a locale returned by this function will perform the correct
sl@0: * text breaking for the locale.
sl@0: * @param index The index of the desired locale.
sl@0: * @return A locale for which number text breaking information is available, or 0 if none.
sl@0: * @see ubrk_countAvailable
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE const char* U_EXPORT2
sl@0: ubrk_getAvailable(int32_t index);
sl@0:
sl@0: /**
sl@0: * Determine how many locales have text breaking information available.
sl@0: * This function is most useful as determining the loop ending condition for
sl@0: * calls to \ref ubrk_getAvailable.
sl@0: * @return The number of locales for which text breaking information is available.
sl@0: * @see ubrk_getAvailable
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: ubrk_countAvailable(void);
sl@0:
sl@0:
sl@0: /**
sl@0: * Returns true if the specfied position is a boundary position. As a side
sl@0: * effect, leaves the iterator pointing to the first boundary position at
sl@0: * or after "offset".
sl@0: * @param bi The break iterator to use.
sl@0: * @param offset the offset to check.
sl@0: * @return True if "offset" is a boundary position.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE UBool U_EXPORT2
sl@0: ubrk_isBoundary(UBreakIterator *bi, int32_t offset);
sl@0:
sl@0: /**
sl@0: * Return the status from the break rule that determined the most recently
sl@0: * returned break position. The values appear in the rule source
sl@0: * within brackets, {123}, for example. For rules that do not specify a
sl@0: * status, a default value of 0 is returned.
sl@0: * sl@0: * For word break iterators, the possible values are defined in enum UWordBreak. sl@0: * @stable ICU 2.2 sl@0: */ sl@0: U_STABLE int32_t U_EXPORT2 sl@0: ubrk_getRuleStatus(UBreakIterator *bi); sl@0: sl@0: /** sl@0: * Get the statuses from the break rules that determined the most recently sl@0: * returned break position. The values appear in the rule source sl@0: * within brackets, {123}, for example. The default status value for rules sl@0: * that do not explicitly provide one is zero. sl@0: *
sl@0: * For word break iterators, the possible values are defined in enum UWordBreak. sl@0: * @param bi The break iterator to use sl@0: * @param fillInVec an array to be filled in with the status values. sl@0: * @param capacity the length of the supplied vector. A length of zero causes sl@0: * the function to return the number of status values, in the sl@0: * normal way, without attemtping to store any values. sl@0: * @param status receives error codes. sl@0: * @return The number of rule status values from rules that determined sl@0: * the most recent boundary returned by the break iterator. sl@0: * @draft ICU 3.0 sl@0: */ sl@0: U_DRAFT int32_t U_EXPORT2 sl@0: ubrk_getRuleStatusVec(UBreakIterator *bi, int32_t *fillInVec, int32_t capacity, UErrorCode *status); sl@0: sl@0: /** sl@0: * Return the locale of the break iterator. You can choose between the valid and sl@0: * the actual locale. sl@0: * @param bi break iterator sl@0: * @param type locale type (valid or actual) sl@0: * @param status error code sl@0: * @return locale string sl@0: * @draft ICU 2.8 likely to change after ICU 3.0, based on feedback sl@0: */ sl@0: U_DRAFT const char* U_EXPORT2 sl@0: ubrk_getLocaleByType(const UBreakIterator *bi, ULocDataLocaleType type, UErrorCode* status); sl@0: sl@0: sl@0: #endif /* #if !UCONFIG_NO_BREAK_ITERATION */ sl@0: sl@0: #endif