Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ubrk.h @ 69:33d812a61356

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