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