1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * Copyright (C) 1996-2015, International Business Machines Corporation and others. 6 * All Rights Reserved. 7 ****************************************************************************** 8 */ 9 10 #ifndef UBRK_H 11 #define UBRK_H 12 13 #include "unicode/utypes.h" 14 #include "unicode/uloc.h" 15 #include "unicode/utext.h" 16 17 #if U_SHOW_CPLUSPLUS_API 18 #include "unicode/localpointer.h" 19 #endif // U_SHOW_CPLUSPLUS_API 20 21 /** 22 * A text-break iterator. 23 * For usage in C programs. 24 */ 25 #ifndef UBRK_TYPEDEF_UBREAK_ITERATOR 26 # define UBRK_TYPEDEF_UBREAK_ITERATOR 27 /** 28 * Opaque type representing an ICU Break iterator object. 29 * \xrefitem stable "Stable" "Stable List" ICU 2.0 30 */ 31 typedef struct UBreakIterator UBreakIterator; 32 #endif 33 34 #if !UCONFIG_NO_BREAK_ITERATION 35 36 37 /** 38 * @addtogroup icu4c ICU4C 39 * @{ 40 * \file 41 * \brief C API: BreakIterator 42 * 43 * <h2> BreakIterator C API </h2> 44 * 45 * The BreakIterator C API defines methods for finding the location 46 * of boundaries in text. Pointer to a UBreakIterator maintain a 47 * current position and scan over text returning the index of characters 48 * where boundaries occur. 49 * <p> 50 * Line boundary analysis determines where a text string can be broken 51 * when line-wrapping. The mechanism correctly handles punctuation and 52 * hyphenated words. 53 * <p> 54 * Note: The locale keyword "lb" can be used to modify line break 55 * behavior according to the CSS level 3 line-break options, see 56 * <http://dev.w3.org/csswg/css-text/#line-breaking>. For example: 57 * "ja@lb=strict", "zh@lb=loose". 58 * <p> 59 * Sentence boundary analysis allows selection with correct 60 * interpretation of periods within numbers and abbreviations, and 61 * trailing punctuation marks such as quotation marks and parentheses. 62 * <p> 63 * Note: The locale keyword "ss" can be used to enable use of 64 * segmentation suppression data (preventing breaks in English after 65 * abbreviations such as "Mr." or "Est.", for example), as follows: 66 * "en@ss=standard". 67 * <p> 68 * Word boundary analysis is used by search and replace functions, as 69 * well as within text editing applications that allow the user to 70 * select words with a double click. Word selection provides correct 71 * interpretation of punctuation marks within and following 72 * words. Characters that are not part of a word, such as symbols or 73 * punctuation marks, have word-breaks on both sides. 74 * <p> 75 * Character boundary analysis identifies the boundaries of 76 * "Extended Grapheme Clusters", which are groupings of codepoints 77 * that should be treated as character-like units for many text operations. 78 * Please see Unicode Standard Annex #29, Unicode Text Segmentation, 79 * http://www.unicode.org/reports/tr29/ for additional information 80 * on grapheme clusters and guidelines on their use. 81 * <p> 82 * Title boundary analysis locates all positions, 83 * typically starts of words, that should be set to Title Case 84 * when title casing the text. 85 * <p> 86 * The text boundary positions are found according to the rules 87 * described in Unicode Standard Annex #29, Text Boundaries, and 88 * Unicode Standard Annex #14, Line Breaking Properties. These 89 * are available at http://www.unicode.org/reports/tr14/ and 90 * http://www.unicode.org/reports/tr29/. 91 * <p> 92 * In addition to the plain C API defined in this header file, an 93 * object oriented C++ API with equivalent functionality is defined in the 94 * file brkiter.h. 95 * <p> 96 * Code snippets illustrating the use of the Break Iterator APIs 97 * are available in the ICU User Guide, 98 * https://unicode-org.github.io/icu/userguide/boundaryanalysis/ 99 * and in the sample program icu/source/samples/break/break.cpp 100 */ 101 102 /** The possible types of text boundaries. \xrefitem stable "Stable" "Stable List" ICU 2.0 */ 103 typedef enum UBreakIteratorType { 104 /** Character breaks \xrefitem stable "Stable" "Stable List" ICU 2.0 */ 105 UBRK_CHARACTER = 0, 106 /** Word breaks \xrefitem stable "Stable" "Stable List" ICU 2.0 */ 107 UBRK_WORD = 1, 108 /** Line breaks \xrefitem stable "Stable" "Stable List" ICU 2.0 */ 109 UBRK_LINE = 2, 110 /** Sentence breaks \xrefitem stable "Stable" "Stable List" ICU 2.0 */ 111 UBRK_SENTENCE = 3, 112 113 #ifndef U_HIDE_DEPRECATED_API 114 /** 115 * Title Case breaks 116 * The iterator created using this type locates title boundaries as described for 117 * Unicode 3.2 only. For Unicode 4.0 and above title boundary iteration, 118 * please use Word Boundary iterator. 119 * 120 * \xrefitem deprecated "Deprecated" "Deprecated List" ICU 2.8 Use the word break iterator for titlecasing for Unicode 4 and later. 121 */ 122 UBRK_TITLE = 4, 123 /** 124 * One more than the highest normal UBreakIteratorType value. 125 * \xrefitem deprecated "Deprecated" "Deprecated List" ICU 58 The numeric value may change over time, see ICU ticket #12420. 126 */ 127 UBRK_COUNT = 5 128 #endif // U_HIDE_DEPRECATED_API 129 } UBreakIteratorType; 130 131 /** Value indicating all text boundaries have been returned. 132 * \xrefitem stable "Stable" "Stable List" ICU 2.0 133 */ 134 #define UBRK_DONE ((int32_t) -1) 135 136 137 /** 138 * Enum constants for the word break tags returned by 139 * getRuleStatus(). A range of values is defined for each category of 140 * word, to allow for further subdivisions of a category in future releases. 141 * Applications should check for tag values falling within the range, rather 142 * than for single individual values. 143 * 144 * The numeric values of all of these constants are stable (will not change). 145 * 146 * \xrefitem stable "Stable" "Stable List" ICU 2.2 147 */ 148 typedef enum UWordBreak { 149 /** Tag value for "words" that do not fit into any of other categories. 150 * Includes spaces and most punctuation. */ 151 UBRK_WORD_NONE = 0, 152 /** Upper bound for tags for uncategorized words. */ 153 UBRK_WORD_NONE_LIMIT = 100, 154 /** Tag value for words that appear to be numbers, lower limit. */ 155 UBRK_WORD_NUMBER = 100, 156 /** Tag value for words that appear to be numbers, upper limit. */ 157 UBRK_WORD_NUMBER_LIMIT = 200, 158 /** Tag value for words that contain letters, excluding 159 * hiragana, katakana or ideographic characters, lower limit. */ 160 UBRK_WORD_LETTER = 200, 161 /** Tag value for words containing letters, upper limit */ 162 UBRK_WORD_LETTER_LIMIT = 300, 163 /** Tag value for words containing kana characters, lower limit */ 164 UBRK_WORD_KANA = 300, 165 /** Tag value for words containing kana characters, upper limit */ 166 UBRK_WORD_KANA_LIMIT = 400, 167 /** Tag value for words containing ideographic characters, lower limit */ 168 UBRK_WORD_IDEO = 400, 169 /** Tag value for words containing ideographic characters, upper limit */ 170 UBRK_WORD_IDEO_LIMIT = 500 171 } UWordBreak; 172 173 /** 174 * Enum constants for the line break tags returned by getRuleStatus(). 175 * A range of values is defined for each category of 176 * word, to allow for further subdivisions of a category in future releases. 177 * Applications should check for tag values falling within the range, rather 178 * than for single individual values. 179 * 180 * The numeric values of all of these constants are stable (will not change). 181 * 182 * \xrefitem stable "Stable" "Stable List" ICU 2.8 183 */ 184 typedef enum ULineBreakTag { 185 /** Tag value for soft line breaks, positions at which a line break 186 * is acceptable but not required */ 187 UBRK_LINE_SOFT = 0, 188 /** Upper bound for soft line breaks. */ 189 UBRK_LINE_SOFT_LIMIT = 100, 190 /** Tag value for a hard, or mandatory line break */ 191 UBRK_LINE_HARD = 100, 192 /** Upper bound for hard line breaks. */ 193 UBRK_LINE_HARD_LIMIT = 200 194 } ULineBreakTag; 195 196 197 198 /** 199 * Enum constants for the sentence break tags returned by getRuleStatus(). 200 * A range of values is defined for each category of 201 * sentence, to allow for further subdivisions of a category in future releases. 202 * Applications should check for tag values falling within the range, rather 203 * than for single individual values. 204 * 205 * The numeric values of all of these constants are stable (will not change). 206 * 207 * \xrefitem stable "Stable" "Stable List" ICU 2.8 208 */ 209 typedef enum USentenceBreakTag { 210 /** Tag value for for sentences ending with a sentence terminator 211 * ('.', '?', '!', etc.) character, possibly followed by a 212 * hard separator (CR, LF, PS, etc.) 213 */ 214 UBRK_SENTENCE_TERM = 0, 215 /** Upper bound for tags for sentences ended by sentence terminators. */ 216 UBRK_SENTENCE_TERM_LIMIT = 100, 217 /** Tag value for for sentences that do not contain an ending 218 * sentence terminator ('.', '?', '!', etc.) character, but 219 * are ended only by a hard separator (CR, LF, PS, etc.) or end of input. 220 */ 221 UBRK_SENTENCE_SEP = 100, 222 /** Upper bound for tags for sentences ended by a separator. */ 223 UBRK_SENTENCE_SEP_LIMIT = 200 224 /** Tag value for a hard, or mandatory line break */ 225 } USentenceBreakTag; 226 227 228 /** 229 * Open a new UBreakIterator for locating text boundaries for a specified locale. 230 * A UBreakIterator may be used for detecting character, line, word, 231 * and sentence breaks in text. 232 * @param type The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD, 233 * UBRK_LINE, UBRK_SENTENCE 234 * @param locale The locale specifying the text-breaking conventions. Note that 235 * locale keys such as "lb" and "ss" may be used to modify text break behavior, 236 * see general discussion of BreakIterator C API. 237 * @param text The text to be iterated over. May be null, in which case ubrk_setText() is 238 * used to specify the text to be iterated. 239 * @param textLength The number of characters in text, or -1 if null-terminated. 240 * @param status A UErrorCode to receive any errors. 241 * @return A UBreakIterator for the specified locale. 242 * @see ubrk_openRules 243 * \xrefitem stable "Stable" "Stable List" ICU 2.0 244 */ 245 U_CAPI UBreakIterator* U_EXPORT2 246 ubrk_open(UBreakIteratorType type, 247 const char *locale, 248 const UChar *text, 249 int32_t textLength, 250 UErrorCode *status) __INTRODUCED_IN(31); 251 252 253 254 255 256 257 258 #ifndef U_HIDE_DEPRECATED_API 259 260 261 262 #endif /* U_HIDE_DEPRECATED_API */ 263 264 /** 265 * Thread safe cloning operation. 266 * @param bi iterator to be cloned 267 * @param status to indicate whether the operation went on smoothly or there were errors 268 * @return pointer to the new clone 269 * \xrefitem stable "Stable" "Stable List" ICU 69 270 */ 271 U_CAPI UBreakIterator * U_EXPORT2 272 ubrk_clone(const UBreakIterator *bi, 273 UErrorCode *status) __INTRODUCED_IN(31); 274 275 276 277 #ifndef U_HIDE_DEPRECATED_API 278 279 /** 280 * A recommended size (in bytes) for the memory buffer to be passed to ubrk_saveClone(). 281 * \xrefitem deprecated "Deprecated" "Deprecated List" ICU 52. Do not rely on ubrk_safeClone() cloning into any provided buffer. 282 */ 283 #define U_BRK_SAFECLONE_BUFFERSIZE 1 284 285 #endif /* U_HIDE_DEPRECATED_API */ 286 287 /** 288 * Close a UBreakIterator. 289 * Once closed, a UBreakIterator may no longer be used. 290 * @param bi The break iterator to close. 291 * \xrefitem stable "Stable" "Stable List" ICU 2.0 292 */ 293 U_CAPI void U_EXPORT2 294 ubrk_close(UBreakIterator *bi) __INTRODUCED_IN(31); 295 296 297 298 #if U_SHOW_CPLUSPLUS_API 299 300 U_NAMESPACE_BEGIN 301 302 /** 303 * \class LocalUBreakIteratorPointer 304 * "Smart pointer" class, closes a UBreakIterator via ubrk_close(). 305 * For most methods see the LocalPointerBase base class. 306 * 307 * @see LocalPointerBase 308 * @see LocalPointer 309 * \xrefitem stable "Stable" "Stable List" ICU 4.4 310 */ 311 U_DEFINE_LOCAL_OPEN_POINTER(LocalUBreakIteratorPointer, UBreakIterator, ubrk_close); 312 313 U_NAMESPACE_END 314 315 #endif 316 317 /** 318 * Sets an existing iterator to point to a new piece of text. 319 * The break iterator retains a pointer to the supplied text. 320 * The caller must not modify or delete the text while the BreakIterator 321 * retains the reference. 322 * 323 * @param bi The iterator to use 324 * @param text The text to be set 325 * @param textLength The length of the text 326 * @param status The error code 327 * \xrefitem stable "Stable" "Stable List" ICU 2.0 328 */ 329 U_CAPI void U_EXPORT2 330 ubrk_setText(UBreakIterator* bi, 331 const UChar* text, 332 int32_t textLength, 333 UErrorCode* status) __INTRODUCED_IN(31); 334 335 336 337 338 /** 339 * Sets an existing iterator to point to a new piece of text. 340 * 341 * All index positions returned by break iterator functions are 342 * native indices from the UText. For example, when breaking UTF-8 343 * encoded text, the break positions returned by \ref ubrk_next, \ref ubrk_previous, etc. 344 * will be UTF-8 string indices, not UTF-16 positions. 345 * 346 * @param bi The iterator to use 347 * @param text The text to be set. 348 * This function makes a shallow clone of the supplied UText. This means 349 * that the caller is free to immediately close or otherwise reuse the 350 * UText that was passed as a parameter, but that the underlying text itself 351 * must not be altered while being referenced by the break iterator. 352 * @param status The error code 353 * \xrefitem stable "Stable" "Stable List" ICU 3.4 354 */ 355 U_CAPI void U_EXPORT2 356 ubrk_setUText(UBreakIterator* bi, 357 UText* text, 358 UErrorCode* status) __INTRODUCED_IN(31); 359 360 361 362 363 364 /** 365 * Determine the most recently-returned text boundary. 366 * 367 * @param bi The break iterator to use. 368 * @return The character index most recently returned by \ref ubrk_next, \ref ubrk_previous, 369 * \ref ubrk_first, or \ref ubrk_last. 370 * \xrefitem stable "Stable" "Stable List" ICU 2.0 371 */ 372 U_CAPI int32_t U_EXPORT2 373 ubrk_current(const UBreakIterator *bi) __INTRODUCED_IN(31); 374 375 376 377 /** 378 * Advance the iterator to the boundary following the current boundary. 379 * 380 * @param bi The break iterator to use. 381 * @return The character index of the next text boundary, or UBRK_DONE 382 * if all text boundaries have been returned. 383 * @see ubrk_previous 384 * \xrefitem stable "Stable" "Stable List" ICU 2.0 385 */ 386 U_CAPI int32_t U_EXPORT2 387 ubrk_next(UBreakIterator *bi) __INTRODUCED_IN(31); 388 389 390 391 /** 392 * Set the iterator position to the boundary preceding the current boundary. 393 * 394 * @param bi The break iterator to use. 395 * @return The character index of the preceding text boundary, or UBRK_DONE 396 * if all text boundaries have been returned. 397 * @see ubrk_next 398 * \xrefitem stable "Stable" "Stable List" ICU 2.0 399 */ 400 U_CAPI int32_t U_EXPORT2 401 ubrk_previous(UBreakIterator *bi) __INTRODUCED_IN(31); 402 403 404 405 /** 406 * Set the iterator position to zero, the start of the text being scanned. 407 * @param bi The break iterator to use. 408 * @return The new iterator position (zero). 409 * @see ubrk_last 410 * \xrefitem stable "Stable" "Stable List" ICU 2.0 411 */ 412 U_CAPI int32_t U_EXPORT2 413 ubrk_first(UBreakIterator *bi) __INTRODUCED_IN(31); 414 415 416 417 /** 418 * Set the iterator position to the index immediately <EM>beyond</EM> the last character in the text being scanned. 419 * This is not the same as the last character. 420 * @param bi The break iterator to use. 421 * @return The character offset immediately <EM>beyond</EM> the last character in the 422 * text being scanned. 423 * @see ubrk_first 424 * \xrefitem stable "Stable" "Stable List" ICU 2.0 425 */ 426 U_CAPI int32_t U_EXPORT2 427 ubrk_last(UBreakIterator *bi) __INTRODUCED_IN(31); 428 429 430 431 /** 432 * Set the iterator position to the first boundary preceding the specified offset. 433 * The new position is always smaller than offset, or UBRK_DONE. 434 * @param bi The break iterator to use. 435 * @param offset The offset to begin scanning. 436 * @return The text boundary preceding offset, or UBRK_DONE. 437 * @see ubrk_following 438 * \xrefitem stable "Stable" "Stable List" ICU 2.0 439 */ 440 U_CAPI int32_t U_EXPORT2 441 ubrk_preceding(UBreakIterator *bi, 442 int32_t offset) __INTRODUCED_IN(31); 443 444 445 446 /** 447 * Advance the iterator to the first boundary following the specified offset. 448 * The value returned is always greater than offset, or UBRK_DONE. 449 * @param bi The break iterator to use. 450 * @param offset The offset to begin scanning. 451 * @return The text boundary following offset, or UBRK_DONE. 452 * @see ubrk_preceding 453 * \xrefitem stable "Stable" "Stable List" ICU 2.0 454 */ 455 U_CAPI int32_t U_EXPORT2 456 ubrk_following(UBreakIterator *bi, 457 int32_t offset) __INTRODUCED_IN(31); 458 459 460 461 /** 462 * Get a locale for which text breaking information is available. 463 * A UBreakIterator in a locale returned by this function will perform the correct 464 * text breaking for the locale. 465 * @param index The index of the desired locale. 466 * @return A locale for which number text breaking information is available, or 0 if none. 467 * @see ubrk_countAvailable 468 * \xrefitem stable "Stable" "Stable List" ICU 2.0 469 */ 470 U_CAPI const char* U_EXPORT2 471 ubrk_getAvailable(int32_t index) __INTRODUCED_IN(31); 472 473 474 475 /** 476 * Determine how many locales have text breaking information available. 477 * This function is most useful as determining the loop ending condition for 478 * calls to \ref ubrk_getAvailable. 479 * @return The number of locales for which text breaking information is available. 480 * @see ubrk_getAvailable 481 * \xrefitem stable "Stable" "Stable List" ICU 2.0 482 */ 483 U_CAPI int32_t U_EXPORT2 484 ubrk_countAvailable(void) __INTRODUCED_IN(31); 485 486 487 488 489 /** 490 * Returns true if the specified position is a boundary position. As a side 491 * effect, leaves the iterator pointing to the first boundary position at 492 * or after "offset". 493 * @param bi The break iterator to use. 494 * @param offset the offset to check. 495 * @return True if "offset" is a boundary position. 496 * \xrefitem stable "Stable" "Stable List" ICU 2.0 497 */ 498 U_CAPI UBool U_EXPORT2 499 ubrk_isBoundary(UBreakIterator *bi, int32_t offset) __INTRODUCED_IN(31); 500 501 502 503 /** 504 * Return the status from the break rule that determined the most recently 505 * returned break position. The values appear in the rule source 506 * within brackets, {123}, for example. For rules that do not specify a 507 * status, a default value of 0 is returned. 508 * <p> 509 * For word break iterators, the possible values are defined in enum UWordBreak. 510 * \xrefitem stable "Stable" "Stable List" ICU 2.2 511 */ 512 U_CAPI int32_t U_EXPORT2 513 ubrk_getRuleStatus(UBreakIterator *bi) __INTRODUCED_IN(31); 514 515 516 517 /** 518 * Get the statuses from the break rules that determined the most recently 519 * returned break position. The values appear in the rule source 520 * within brackets, {123}, for example. The default status value for rules 521 * that do not explicitly provide one is zero. 522 * <p> 523 * For word break iterators, the possible values are defined in enum UWordBreak. 524 * @param bi The break iterator to use 525 * @param fillInVec an array to be filled in with the status values. 526 * @param capacity the length of the supplied vector. A length of zero causes 527 * the function to return the number of status values, in the 528 * normal way, without attempting to store any values. 529 * @param status receives error codes. 530 * @return The number of rule status values from rules that determined 531 * the most recent boundary returned by the break iterator. 532 * \xrefitem stable "Stable" "Stable List" ICU 3.0 533 */ 534 U_CAPI int32_t U_EXPORT2 535 ubrk_getRuleStatusVec(UBreakIterator *bi, int32_t *fillInVec, int32_t capacity, UErrorCode *status) __INTRODUCED_IN(31); 536 537 538 539 540 541 542 543 544 545 546 #endif /* #if !UCONFIG_NO_BREAK_ITERATION */ 547 548 #endif 549 550 /** @} */ // addtogroup 551