intl/icu/source/common/unicode/normlzr.h

Wed, 31 Dec 2014 06:09:35 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Wed, 31 Dec 2014 06:09:35 +0100
changeset 0
6474c204b198
permissions
-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

michael@0 1 /*
michael@0 2 ********************************************************************
michael@0 3 * COPYRIGHT:
michael@0 4 * Copyright (c) 1996-2011, International Business Machines Corporation and
michael@0 5 * others. All Rights Reserved.
michael@0 6 ********************************************************************
michael@0 7 */
michael@0 8
michael@0 9 #ifndef NORMLZR_H
michael@0 10 #define NORMLZR_H
michael@0 11
michael@0 12 #include "unicode/utypes.h"
michael@0 13
michael@0 14 /**
michael@0 15 * \file
michael@0 16 * \brief C++ API: Unicode Normalization
michael@0 17 */
michael@0 18
michael@0 19 #if !UCONFIG_NO_NORMALIZATION
michael@0 20
michael@0 21 #include "unicode/chariter.h"
michael@0 22 #include "unicode/normalizer2.h"
michael@0 23 #include "unicode/unistr.h"
michael@0 24 #include "unicode/unorm.h"
michael@0 25 #include "unicode/uobject.h"
michael@0 26
michael@0 27 U_NAMESPACE_BEGIN
michael@0 28 /**
michael@0 29 * The Normalizer class supports the standard normalization forms described in
michael@0 30 * <a href="http://www.unicode.org/unicode/reports/tr15/" target="unicode">
michael@0 31 * Unicode Standard Annex #15: Unicode Normalization Forms</a>.
michael@0 32 *
michael@0 33 * Note: This API has been replaced by the Normalizer2 class and is only available
michael@0 34 * for backward compatibility. This class simply delegates to the Normalizer2 class.
michael@0 35 * There is one exception: The new API does not provide a replacement for Normalizer::compare().
michael@0 36 *
michael@0 37 * The Normalizer class consists of two parts:
michael@0 38 * - static functions that normalize strings or test if strings are normalized
michael@0 39 * - a Normalizer object is an iterator that takes any kind of text and
michael@0 40 * provides iteration over its normalized form
michael@0 41 *
michael@0 42 * The Normalizer class is not suitable for subclassing.
michael@0 43 *
michael@0 44 * For basic information about normalization forms and details about the C API
michael@0 45 * please see the documentation in unorm.h.
michael@0 46 *
michael@0 47 * The iterator API with the Normalizer constructors and the non-static functions
michael@0 48 * use a CharacterIterator as input. It is possible to pass a string which
michael@0 49 * is then internally wrapped in a CharacterIterator.
michael@0 50 * The input text is not normalized all at once, but incrementally where needed
michael@0 51 * (providing efficient random access).
michael@0 52 * This allows to pass in a large text but spend only a small amount of time
michael@0 53 * normalizing a small part of that text.
michael@0 54 * However, if the entire text is normalized, then the iterator will be
michael@0 55 * slower than normalizing the entire text at once and iterating over the result.
michael@0 56 * A possible use of the Normalizer iterator is also to report an index into the
michael@0 57 * original text that is close to where the normalized characters come from.
michael@0 58 *
michael@0 59 * <em>Important:</em> The iterator API was cleaned up significantly for ICU 2.0.
michael@0 60 * The earlier implementation reported the getIndex() inconsistently,
michael@0 61 * and previous() could not be used after setIndex(), next(), first(), and current().
michael@0 62 *
michael@0 63 * Normalizer allows to start normalizing from anywhere in the input text by
michael@0 64 * calling setIndexOnly(), first(), or last().
michael@0 65 * Without calling any of these, the iterator will start at the beginning of the text.
michael@0 66 *
michael@0 67 * At any time, next() returns the next normalized code point (UChar32),
michael@0 68 * with post-increment semantics (like CharacterIterator::next32PostInc()).
michael@0 69 * previous() returns the previous normalized code point (UChar32),
michael@0 70 * with pre-decrement semantics (like CharacterIterator::previous32()).
michael@0 71 *
michael@0 72 * current() returns the current code point
michael@0 73 * (respectively the one at the newly set index) without moving
michael@0 74 * the getIndex(). Note that if the text at the current position
michael@0 75 * needs to be normalized, then these functions will do that.
michael@0 76 * (This is why current() is not const.)
michael@0 77 * It is more efficient to call setIndexOnly() instead, which does not
michael@0 78 * normalize.
michael@0 79 *
michael@0 80 * getIndex() always refers to the position in the input text where the normalized
michael@0 81 * code points are returned from. It does not always change with each returned
michael@0 82 * code point.
michael@0 83 * The code point that is returned from any of the functions
michael@0 84 * corresponds to text at or after getIndex(), according to the
michael@0 85 * function's iteration semantics (post-increment or pre-decrement).
michael@0 86 *
michael@0 87 * next() returns a code point from at or after the getIndex()
michael@0 88 * from before the next() call. After the next() call, the getIndex()
michael@0 89 * might have moved to where the next code point will be returned from
michael@0 90 * (from a next() or current() call).
michael@0 91 * This is semantically equivalent to array access with array[index++]
michael@0 92 * (post-increment semantics).
michael@0 93 *
michael@0 94 * previous() returns a code point from at or after the getIndex()
michael@0 95 * from after the previous() call.
michael@0 96 * This is semantically equivalent to array access with array[--index]
michael@0 97 * (pre-decrement semantics).
michael@0 98 *
michael@0 99 * Internally, the Normalizer iterator normalizes a small piece of text
michael@0 100 * starting at the getIndex() and ending at a following "safe" index.
michael@0 101 * The normalized results is stored in an internal string buffer, and
michael@0 102 * the code points are iterated from there.
michael@0 103 * With multiple iteration calls, this is repeated until the next piece
michael@0 104 * of text needs to be normalized, and the getIndex() needs to be moved.
michael@0 105 *
michael@0 106 * The following "safe" index, the internal buffer, and the secondary
michael@0 107 * iteration index into that buffer are not exposed on the API.
michael@0 108 * This also means that it is currently not practical to return to
michael@0 109 * a particular, arbitrary position in the text because one would need to
michael@0 110 * know, and be able to set, in addition to the getIndex(), at least also the
michael@0 111 * current index into the internal buffer.
michael@0 112 * It is currently only possible to observe when getIndex() changes
michael@0 113 * (with careful consideration of the iteration semantics),
michael@0 114 * at which time the internal index will be 0.
michael@0 115 * For example, if getIndex() is different after next() than before it,
michael@0 116 * then the internal index is 0 and one can return to this getIndex()
michael@0 117 * later with setIndexOnly().
michael@0 118 *
michael@0 119 * Note: While the setIndex() and getIndex() refer to indices in the
michael@0 120 * underlying Unicode input text, the next() and previous() methods
michael@0 121 * iterate through characters in the normalized output.
michael@0 122 * This means that there is not necessarily a one-to-one correspondence
michael@0 123 * between characters returned by next() and previous() and the indices
michael@0 124 * passed to and returned from setIndex() and getIndex().
michael@0 125 * It is for this reason that Normalizer does not implement the CharacterIterator interface.
michael@0 126 *
michael@0 127 * @author Laura Werner, Mark Davis, Markus Scherer
michael@0 128 * @stable ICU 2.0
michael@0 129 */
michael@0 130 class U_COMMON_API Normalizer : public UObject {
michael@0 131 public:
michael@0 132 /**
michael@0 133 * If DONE is returned from an iteration function that returns a code point,
michael@0 134 * then there are no more normalization results available.
michael@0 135 * @stable ICU 2.0
michael@0 136 */
michael@0 137 enum {
michael@0 138 DONE=0xffff
michael@0 139 };
michael@0 140
michael@0 141 // Constructors
michael@0 142
michael@0 143 /**
michael@0 144 * Creates a new <code>Normalizer</code> object for iterating over the
michael@0 145 * normalized form of a given string.
michael@0 146 * <p>
michael@0 147 * @param str The string to be normalized. The normalization
michael@0 148 * will start at the beginning of the string.
michael@0 149 *
michael@0 150 * @param mode The normalization mode.
michael@0 151 * @stable ICU 2.0
michael@0 152 */
michael@0 153 Normalizer(const UnicodeString& str, UNormalizationMode mode);
michael@0 154
michael@0 155 /**
michael@0 156 * Creates a new <code>Normalizer</code> object for iterating over the
michael@0 157 * normalized form of a given string.
michael@0 158 * <p>
michael@0 159 * @param str The string to be normalized. The normalization
michael@0 160 * will start at the beginning of the string.
michael@0 161 *
michael@0 162 * @param length Length of the string, or -1 if NUL-terminated.
michael@0 163 * @param mode The normalization mode.
michael@0 164 * @stable ICU 2.0
michael@0 165 */
michael@0 166 Normalizer(const UChar* str, int32_t length, UNormalizationMode mode);
michael@0 167
michael@0 168 /**
michael@0 169 * Creates a new <code>Normalizer</code> object for iterating over the
michael@0 170 * normalized form of the given text.
michael@0 171 * <p>
michael@0 172 * @param iter The input text to be normalized. The normalization
michael@0 173 * will start at the beginning of the string.
michael@0 174 *
michael@0 175 * @param mode The normalization mode.
michael@0 176 * @stable ICU 2.0
michael@0 177 */
michael@0 178 Normalizer(const CharacterIterator& iter, UNormalizationMode mode);
michael@0 179
michael@0 180 /**
michael@0 181 * Copy constructor.
michael@0 182 * @param copy The object to be copied.
michael@0 183 * @stable ICU 2.0
michael@0 184 */
michael@0 185 Normalizer(const Normalizer& copy);
michael@0 186
michael@0 187 /**
michael@0 188 * Destructor
michael@0 189 * @stable ICU 2.0
michael@0 190 */
michael@0 191 virtual ~Normalizer();
michael@0 192
michael@0 193
michael@0 194 //-------------------------------------------------------------------------
michael@0 195 // Static utility methods
michael@0 196 //-------------------------------------------------------------------------
michael@0 197
michael@0 198 /**
michael@0 199 * Normalizes a <code>UnicodeString</code> according to the specified normalization mode.
michael@0 200 * This is a wrapper for unorm_normalize(), using UnicodeString's.
michael@0 201 *
michael@0 202 * The <code>options</code> parameter specifies which optional
michael@0 203 * <code>Normalizer</code> features are to be enabled for this operation.
michael@0 204 *
michael@0 205 * @param source the input string to be normalized.
michael@0 206 * @param mode the normalization mode
michael@0 207 * @param options the optional features to be enabled (0 for no options)
michael@0 208 * @param result The normalized string (on output).
michael@0 209 * @param status The error code.
michael@0 210 * @stable ICU 2.0
michael@0 211 */
michael@0 212 static void U_EXPORT2 normalize(const UnicodeString& source,
michael@0 213 UNormalizationMode mode, int32_t options,
michael@0 214 UnicodeString& result,
michael@0 215 UErrorCode &status);
michael@0 216
michael@0 217 /**
michael@0 218 * Compose a <code>UnicodeString</code>.
michael@0 219 * This is equivalent to normalize() with mode UNORM_NFC or UNORM_NFKC.
michael@0 220 * This is a wrapper for unorm_normalize(), using UnicodeString's.
michael@0 221 *
michael@0 222 * The <code>options</code> parameter specifies which optional
michael@0 223 * <code>Normalizer</code> features are to be enabled for this operation.
michael@0 224 *
michael@0 225 * @param source the string to be composed.
michael@0 226 * @param compat Perform compatibility decomposition before composition.
michael@0 227 * If this argument is <code>FALSE</code>, only canonical
michael@0 228 * decomposition will be performed.
michael@0 229 * @param options the optional features to be enabled (0 for no options)
michael@0 230 * @param result The composed string (on output).
michael@0 231 * @param status The error code.
michael@0 232 * @stable ICU 2.0
michael@0 233 */
michael@0 234 static void U_EXPORT2 compose(const UnicodeString& source,
michael@0 235 UBool compat, int32_t options,
michael@0 236 UnicodeString& result,
michael@0 237 UErrorCode &status);
michael@0 238
michael@0 239 /**
michael@0 240 * Static method to decompose a <code>UnicodeString</code>.
michael@0 241 * This is equivalent to normalize() with mode UNORM_NFD or UNORM_NFKD.
michael@0 242 * This is a wrapper for unorm_normalize(), using UnicodeString's.
michael@0 243 *
michael@0 244 * The <code>options</code> parameter specifies which optional
michael@0 245 * <code>Normalizer</code> features are to be enabled for this operation.
michael@0 246 *
michael@0 247 * @param source the string to be decomposed.
michael@0 248 * @param compat Perform compatibility decomposition.
michael@0 249 * If this argument is <code>FALSE</code>, only canonical
michael@0 250 * decomposition will be performed.
michael@0 251 * @param options the optional features to be enabled (0 for no options)
michael@0 252 * @param result The decomposed string (on output).
michael@0 253 * @param status The error code.
michael@0 254 * @stable ICU 2.0
michael@0 255 */
michael@0 256 static void U_EXPORT2 decompose(const UnicodeString& source,
michael@0 257 UBool compat, int32_t options,
michael@0 258 UnicodeString& result,
michael@0 259 UErrorCode &status);
michael@0 260
michael@0 261 /**
michael@0 262 * Performing quick check on a string, to quickly determine if the string is
michael@0 263 * in a particular normalization format.
michael@0 264 * This is a wrapper for unorm_quickCheck(), using a UnicodeString.
michael@0 265 *
michael@0 266 * Three types of result can be returned UNORM_YES, UNORM_NO or
michael@0 267 * UNORM_MAYBE. Result UNORM_YES indicates that the argument
michael@0 268 * string is in the desired normalized format, UNORM_NO determines that
michael@0 269 * argument string is not in the desired normalized format. A
michael@0 270 * UNORM_MAYBE result indicates that a more thorough check is required,
michael@0 271 * the user may have to put the string in its normalized form and compare the
michael@0 272 * results.
michael@0 273 * @param source string for determining if it is in a normalized format
michael@0 274 * @param mode normalization format
michael@0 275 * @param status A reference to a UErrorCode to receive any errors
michael@0 276 * @return UNORM_YES, UNORM_NO or UNORM_MAYBE
michael@0 277 *
michael@0 278 * @see isNormalized
michael@0 279 * @stable ICU 2.0
michael@0 280 */
michael@0 281 static inline UNormalizationCheckResult
michael@0 282 quickCheck(const UnicodeString &source, UNormalizationMode mode, UErrorCode &status);
michael@0 283
michael@0 284 /**
michael@0 285 * Performing quick check on a string; same as the other version of quickCheck
michael@0 286 * but takes an extra options parameter like most normalization functions.
michael@0 287 *
michael@0 288 * @param source string for determining if it is in a normalized format
michael@0 289 * @param mode normalization format
michael@0 290 * @param options the optional features to be enabled (0 for no options)
michael@0 291 * @param status A reference to a UErrorCode to receive any errors
michael@0 292 * @return UNORM_YES, UNORM_NO or UNORM_MAYBE
michael@0 293 *
michael@0 294 * @see isNormalized
michael@0 295 * @stable ICU 2.6
michael@0 296 */
michael@0 297 static UNormalizationCheckResult
michael@0 298 quickCheck(const UnicodeString &source, UNormalizationMode mode, int32_t options, UErrorCode &status);
michael@0 299
michael@0 300 /**
michael@0 301 * Test if a string is in a given normalization form.
michael@0 302 * This is semantically equivalent to source.equals(normalize(source, mode)) .
michael@0 303 *
michael@0 304 * Unlike unorm_quickCheck(), this function returns a definitive result,
michael@0 305 * never a "maybe".
michael@0 306 * For NFD, NFKD, and FCD, both functions work exactly the same.
michael@0 307 * For NFC and NFKC where quickCheck may return "maybe", this function will
michael@0 308 * perform further tests to arrive at a TRUE/FALSE result.
michael@0 309 *
michael@0 310 * @param src String that is to be tested if it is in a normalization format.
michael@0 311 * @param mode Which normalization form to test for.
michael@0 312 * @param errorCode ICU error code in/out parameter.
michael@0 313 * Must fulfill U_SUCCESS before the function call.
michael@0 314 * @return Boolean value indicating whether the source string is in the
michael@0 315 * "mode" normalization form.
michael@0 316 *
michael@0 317 * @see quickCheck
michael@0 318 * @stable ICU 2.2
michael@0 319 */
michael@0 320 static inline UBool
michael@0 321 isNormalized(const UnicodeString &src, UNormalizationMode mode, UErrorCode &errorCode);
michael@0 322
michael@0 323 /**
michael@0 324 * Test if a string is in a given normalization form; same as the other version of isNormalized
michael@0 325 * but takes an extra options parameter like most normalization functions.
michael@0 326 *
michael@0 327 * @param src String that is to be tested if it is in a normalization format.
michael@0 328 * @param mode Which normalization form to test for.
michael@0 329 * @param options the optional features to be enabled (0 for no options)
michael@0 330 * @param errorCode ICU error code in/out parameter.
michael@0 331 * Must fulfill U_SUCCESS before the function call.
michael@0 332 * @return Boolean value indicating whether the source string is in the
michael@0 333 * "mode" normalization form.
michael@0 334 *
michael@0 335 * @see quickCheck
michael@0 336 * @stable ICU 2.6
michael@0 337 */
michael@0 338 static UBool
michael@0 339 isNormalized(const UnicodeString &src, UNormalizationMode mode, int32_t options, UErrorCode &errorCode);
michael@0 340
michael@0 341 /**
michael@0 342 * Concatenate normalized strings, making sure that the result is normalized as well.
michael@0 343 *
michael@0 344 * If both the left and the right strings are in
michael@0 345 * the normalization form according to "mode/options",
michael@0 346 * then the result will be
michael@0 347 *
michael@0 348 * \code
michael@0 349 * dest=normalize(left+right, mode, options)
michael@0 350 * \endcode
michael@0 351 *
michael@0 352 * For details see unorm_concatenate in unorm.h.
michael@0 353 *
michael@0 354 * @param left Left source string.
michael@0 355 * @param right Right source string.
michael@0 356 * @param result The output string.
michael@0 357 * @param mode The normalization mode.
michael@0 358 * @param options A bit set of normalization options.
michael@0 359 * @param errorCode ICU error code in/out parameter.
michael@0 360 * Must fulfill U_SUCCESS before the function call.
michael@0 361 * @return result
michael@0 362 *
michael@0 363 * @see unorm_concatenate
michael@0 364 * @see normalize
michael@0 365 * @see unorm_next
michael@0 366 * @see unorm_previous
michael@0 367 *
michael@0 368 * @stable ICU 2.1
michael@0 369 */
michael@0 370 static UnicodeString &
michael@0 371 U_EXPORT2 concatenate(const UnicodeString &left, const UnicodeString &right,
michael@0 372 UnicodeString &result,
michael@0 373 UNormalizationMode mode, int32_t options,
michael@0 374 UErrorCode &errorCode);
michael@0 375
michael@0 376 /**
michael@0 377 * Compare two strings for canonical equivalence.
michael@0 378 * Further options include case-insensitive comparison and
michael@0 379 * code point order (as opposed to code unit order).
michael@0 380 *
michael@0 381 * Canonical equivalence between two strings is defined as their normalized
michael@0 382 * forms (NFD or NFC) being identical.
michael@0 383 * This function compares strings incrementally instead of normalizing
michael@0 384 * (and optionally case-folding) both strings entirely,
michael@0 385 * improving performance significantly.
michael@0 386 *
michael@0 387 * Bulk normalization is only necessary if the strings do not fulfill the FCD
michael@0 388 * conditions. Only in this case, and only if the strings are relatively long,
michael@0 389 * is memory allocated temporarily.
michael@0 390 * For FCD strings and short non-FCD strings there is no memory allocation.
michael@0 391 *
michael@0 392 * Semantically, this is equivalent to
michael@0 393 * strcmp[CodePointOrder](NFD(foldCase(s1)), NFD(foldCase(s2)))
michael@0 394 * where code point order and foldCase are all optional.
michael@0 395 *
michael@0 396 * UAX 21 2.5 Caseless Matching specifies that for a canonical caseless match
michael@0 397 * the case folding must be performed first, then the normalization.
michael@0 398 *
michael@0 399 * @param s1 First source string.
michael@0 400 * @param s2 Second source string.
michael@0 401 *
michael@0 402 * @param options A bit set of options:
michael@0 403 * - U_FOLD_CASE_DEFAULT or 0 is used for default options:
michael@0 404 * Case-sensitive comparison in code unit order, and the input strings
michael@0 405 * are quick-checked for FCD.
michael@0 406 *
michael@0 407 * - UNORM_INPUT_IS_FCD
michael@0 408 * Set if the caller knows that both s1 and s2 fulfill the FCD conditions.
michael@0 409 * If not set, the function will quickCheck for FCD
michael@0 410 * and normalize if necessary.
michael@0 411 *
michael@0 412 * - U_COMPARE_CODE_POINT_ORDER
michael@0 413 * Set to choose code point order instead of code unit order
michael@0 414 * (see u_strCompare for details).
michael@0 415 *
michael@0 416 * - U_COMPARE_IGNORE_CASE
michael@0 417 * Set to compare strings case-insensitively using case folding,
michael@0 418 * instead of case-sensitively.
michael@0 419 * If set, then the following case folding options are used.
michael@0 420 *
michael@0 421 * - Options as used with case-insensitive comparisons, currently:
michael@0 422 *
michael@0 423 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I
michael@0 424 * (see u_strCaseCompare for details)
michael@0 425 *
michael@0 426 * - regular normalization options shifted left by UNORM_COMPARE_NORM_OPTIONS_SHIFT
michael@0 427 *
michael@0 428 * @param errorCode ICU error code in/out parameter.
michael@0 429 * Must fulfill U_SUCCESS before the function call.
michael@0 430 * @return <0 or 0 or >0 as usual for string comparisons
michael@0 431 *
michael@0 432 * @see unorm_compare
michael@0 433 * @see normalize
michael@0 434 * @see UNORM_FCD
michael@0 435 * @see u_strCompare
michael@0 436 * @see u_strCaseCompare
michael@0 437 *
michael@0 438 * @stable ICU 2.2
michael@0 439 */
michael@0 440 static inline int32_t
michael@0 441 compare(const UnicodeString &s1, const UnicodeString &s2,
michael@0 442 uint32_t options,
michael@0 443 UErrorCode &errorCode);
michael@0 444
michael@0 445 //-------------------------------------------------------------------------
michael@0 446 // Iteration API
michael@0 447 //-------------------------------------------------------------------------
michael@0 448
michael@0 449 /**
michael@0 450 * Return the current character in the normalized text.
michael@0 451 * current() may need to normalize some text at getIndex().
michael@0 452 * The getIndex() is not changed.
michael@0 453 *
michael@0 454 * @return the current normalized code point
michael@0 455 * @stable ICU 2.0
michael@0 456 */
michael@0 457 UChar32 current(void);
michael@0 458
michael@0 459 /**
michael@0 460 * Return the first character in the normalized text.
michael@0 461 * This is equivalent to setIndexOnly(startIndex()) followed by next().
michael@0 462 * (Post-increment semantics.)
michael@0 463 *
michael@0 464 * @return the first normalized code point
michael@0 465 * @stable ICU 2.0
michael@0 466 */
michael@0 467 UChar32 first(void);
michael@0 468
michael@0 469 /**
michael@0 470 * Return the last character in the normalized text.
michael@0 471 * This is equivalent to setIndexOnly(endIndex()) followed by previous().
michael@0 472 * (Pre-decrement semantics.)
michael@0 473 *
michael@0 474 * @return the last normalized code point
michael@0 475 * @stable ICU 2.0
michael@0 476 */
michael@0 477 UChar32 last(void);
michael@0 478
michael@0 479 /**
michael@0 480 * Return the next character in the normalized text.
michael@0 481 * (Post-increment semantics.)
michael@0 482 * If the end of the text has already been reached, DONE is returned.
michael@0 483 * The DONE value could be confused with a U+FFFF non-character code point
michael@0 484 * in the text. If this is possible, you can test getIndex()<endIndex()
michael@0 485 * before calling next(), or (getIndex()<endIndex() || last()!=DONE)
michael@0 486 * after calling next(). (Calling last() will change the iterator state!)
michael@0 487 *
michael@0 488 * The C API unorm_next() is more efficient and does not have this ambiguity.
michael@0 489 *
michael@0 490 * @return the next normalized code point
michael@0 491 * @stable ICU 2.0
michael@0 492 */
michael@0 493 UChar32 next(void);
michael@0 494
michael@0 495 /**
michael@0 496 * Return the previous character in the normalized text and decrement.
michael@0 497 * (Pre-decrement semantics.)
michael@0 498 * If the beginning of the text has already been reached, DONE is returned.
michael@0 499 * The DONE value could be confused with a U+FFFF non-character code point
michael@0 500 * in the text. If this is possible, you can test
michael@0 501 * (getIndex()>startIndex() || first()!=DONE). (Calling first() will change
michael@0 502 * the iterator state!)
michael@0 503 *
michael@0 504 * The C API unorm_previous() is more efficient and does not have this ambiguity.
michael@0 505 *
michael@0 506 * @return the previous normalized code point
michael@0 507 * @stable ICU 2.0
michael@0 508 */
michael@0 509 UChar32 previous(void);
michael@0 510
michael@0 511 /**
michael@0 512 * Set the iteration position in the input text that is being normalized,
michael@0 513 * without any immediate normalization.
michael@0 514 * After setIndexOnly(), getIndex() will return the same index that is
michael@0 515 * specified here.
michael@0 516 *
michael@0 517 * @param index the desired index in the input text.
michael@0 518 * @stable ICU 2.0
michael@0 519 */
michael@0 520 void setIndexOnly(int32_t index);
michael@0 521
michael@0 522 /**
michael@0 523 * Reset the index to the beginning of the text.
michael@0 524 * This is equivalent to setIndexOnly(startIndex)).
michael@0 525 * @stable ICU 2.0
michael@0 526 */
michael@0 527 void reset(void);
michael@0 528
michael@0 529 /**
michael@0 530 * Retrieve the current iteration position in the input text that is
michael@0 531 * being normalized.
michael@0 532 *
michael@0 533 * A following call to next() will return a normalized code point from
michael@0 534 * the input text at or after this index.
michael@0 535 *
michael@0 536 * After a call to previous(), getIndex() will point at or before the
michael@0 537 * position in the input text where the normalized code point
michael@0 538 * was returned from with previous().
michael@0 539 *
michael@0 540 * @return the current index in the input text
michael@0 541 * @stable ICU 2.0
michael@0 542 */
michael@0 543 int32_t getIndex(void) const;
michael@0 544
michael@0 545 /**
michael@0 546 * Retrieve the index of the start of the input text. This is the begin index
michael@0 547 * of the <code>CharacterIterator</code> or the start (i.e. index 0) of the string
michael@0 548 * over which this <code>Normalizer</code> is iterating.
michael@0 549 *
michael@0 550 * @return the smallest index in the input text where the Normalizer operates
michael@0 551 * @stable ICU 2.0
michael@0 552 */
michael@0 553 int32_t startIndex(void) const;
michael@0 554
michael@0 555 /**
michael@0 556 * Retrieve the index of the end of the input text. This is the end index
michael@0 557 * of the <code>CharacterIterator</code> or the length of the string
michael@0 558 * over which this <code>Normalizer</code> is iterating.
michael@0 559 * This end index is exclusive, i.e., the Normalizer operates only on characters
michael@0 560 * before this index.
michael@0 561 *
michael@0 562 * @return the first index in the input text where the Normalizer does not operate
michael@0 563 * @stable ICU 2.0
michael@0 564 */
michael@0 565 int32_t endIndex(void) const;
michael@0 566
michael@0 567 /**
michael@0 568 * Returns TRUE when both iterators refer to the same character in the same
michael@0 569 * input text.
michael@0 570 *
michael@0 571 * @param that a Normalizer object to compare this one to
michael@0 572 * @return comparison result
michael@0 573 * @stable ICU 2.0
michael@0 574 */
michael@0 575 UBool operator==(const Normalizer& that) const;
michael@0 576
michael@0 577 /**
michael@0 578 * Returns FALSE when both iterators refer to the same character in the same
michael@0 579 * input text.
michael@0 580 *
michael@0 581 * @param that a Normalizer object to compare this one to
michael@0 582 * @return comparison result
michael@0 583 * @stable ICU 2.0
michael@0 584 */
michael@0 585 inline UBool operator!=(const Normalizer& that) const;
michael@0 586
michael@0 587 /**
michael@0 588 * Returns a pointer to a new Normalizer that is a clone of this one.
michael@0 589 * The caller is responsible for deleting the new clone.
michael@0 590 * @return a pointer to a new Normalizer
michael@0 591 * @stable ICU 2.0
michael@0 592 */
michael@0 593 Normalizer* clone(void) const;
michael@0 594
michael@0 595 /**
michael@0 596 * Generates a hash code for this iterator.
michael@0 597 *
michael@0 598 * @return the hash code
michael@0 599 * @stable ICU 2.0
michael@0 600 */
michael@0 601 int32_t hashCode(void) const;
michael@0 602
michael@0 603 //-------------------------------------------------------------------------
michael@0 604 // Property access methods
michael@0 605 //-------------------------------------------------------------------------
michael@0 606
michael@0 607 /**
michael@0 608 * Set the normalization mode for this object.
michael@0 609 * <p>
michael@0 610 * <b>Note:</b>If the normalization mode is changed while iterating
michael@0 611 * over a string, calls to {@link #next() } and {@link #previous() } may
michael@0 612 * return previously buffers characters in the old normalization mode
michael@0 613 * until the iteration is able to re-sync at the next base character.
michael@0 614 * It is safest to call {@link #setIndexOnly }, {@link #reset() },
michael@0 615 * {@link #setText }, {@link #first() },
michael@0 616 * {@link #last() }, etc. after calling <code>setMode</code>.
michael@0 617 * <p>
michael@0 618 * @param newMode the new mode for this <code>Normalizer</code>.
michael@0 619 * @see #getUMode
michael@0 620 * @stable ICU 2.0
michael@0 621 */
michael@0 622 void setMode(UNormalizationMode newMode);
michael@0 623
michael@0 624 /**
michael@0 625 * Return the normalization mode for this object.
michael@0 626 *
michael@0 627 * This is an unusual name because there used to be a getMode() that
michael@0 628 * returned a different type.
michael@0 629 *
michael@0 630 * @return the mode for this <code>Normalizer</code>
michael@0 631 * @see #setMode
michael@0 632 * @stable ICU 2.0
michael@0 633 */
michael@0 634 UNormalizationMode getUMode(void) const;
michael@0 635
michael@0 636 /**
michael@0 637 * Set options that affect this <code>Normalizer</code>'s operation.
michael@0 638 * Options do not change the basic composition or decomposition operation
michael@0 639 * that is being performed, but they control whether
michael@0 640 * certain optional portions of the operation are done.
michael@0 641 * Currently the only available option is obsolete.
michael@0 642 *
michael@0 643 * It is possible to specify multiple options that are all turned on or off.
michael@0 644 *
michael@0 645 * @param option the option(s) whose value is/are to be set.
michael@0 646 * @param value the new setting for the option. Use <code>TRUE</code> to
michael@0 647 * turn the option(s) on and <code>FALSE</code> to turn it/them off.
michael@0 648 *
michael@0 649 * @see #getOption
michael@0 650 * @stable ICU 2.0
michael@0 651 */
michael@0 652 void setOption(int32_t option,
michael@0 653 UBool value);
michael@0 654
michael@0 655 /**
michael@0 656 * Determine whether an option is turned on or off.
michael@0 657 * If multiple options are specified, then the result is TRUE if any
michael@0 658 * of them are set.
michael@0 659 * <p>
michael@0 660 * @param option the option(s) that are to be checked
michael@0 661 * @return TRUE if any of the option(s) are set
michael@0 662 * @see #setOption
michael@0 663 * @stable ICU 2.0
michael@0 664 */
michael@0 665 UBool getOption(int32_t option) const;
michael@0 666
michael@0 667 /**
michael@0 668 * Set the input text over which this <code>Normalizer</code> will iterate.
michael@0 669 * The iteration position is set to the beginning.
michael@0 670 *
michael@0 671 * @param newText a string that replaces the current input text
michael@0 672 * @param status a UErrorCode
michael@0 673 * @stable ICU 2.0
michael@0 674 */
michael@0 675 void setText(const UnicodeString& newText,
michael@0 676 UErrorCode &status);
michael@0 677
michael@0 678 /**
michael@0 679 * Set the input text over which this <code>Normalizer</code> will iterate.
michael@0 680 * The iteration position is set to the beginning.
michael@0 681 *
michael@0 682 * @param newText a CharacterIterator object that replaces the current input text
michael@0 683 * @param status a UErrorCode
michael@0 684 * @stable ICU 2.0
michael@0 685 */
michael@0 686 void setText(const CharacterIterator& newText,
michael@0 687 UErrorCode &status);
michael@0 688
michael@0 689 /**
michael@0 690 * Set the input text over which this <code>Normalizer</code> will iterate.
michael@0 691 * The iteration position is set to the beginning.
michael@0 692 *
michael@0 693 * @param newText a string that replaces the current input text
michael@0 694 * @param length the length of the string, or -1 if NUL-terminated
michael@0 695 * @param status a UErrorCode
michael@0 696 * @stable ICU 2.0
michael@0 697 */
michael@0 698 void setText(const UChar* newText,
michael@0 699 int32_t length,
michael@0 700 UErrorCode &status);
michael@0 701 /**
michael@0 702 * Copies the input text into the UnicodeString argument.
michael@0 703 *
michael@0 704 * @param result Receives a copy of the text under iteration.
michael@0 705 * @stable ICU 2.0
michael@0 706 */
michael@0 707 void getText(UnicodeString& result);
michael@0 708
michael@0 709 /**
michael@0 710 * ICU "poor man's RTTI", returns a UClassID for this class.
michael@0 711 * @returns a UClassID for this class.
michael@0 712 * @stable ICU 2.2
michael@0 713 */
michael@0 714 static UClassID U_EXPORT2 getStaticClassID();
michael@0 715
michael@0 716 /**
michael@0 717 * ICU "poor man's RTTI", returns a UClassID for the actual class.
michael@0 718 * @return a UClassID for the actual class.
michael@0 719 * @stable ICU 2.2
michael@0 720 */
michael@0 721 virtual UClassID getDynamicClassID() const;
michael@0 722
michael@0 723 private:
michael@0 724 //-------------------------------------------------------------------------
michael@0 725 // Private functions
michael@0 726 //-------------------------------------------------------------------------
michael@0 727
michael@0 728 Normalizer(); // default constructor not implemented
michael@0 729 Normalizer &operator=(const Normalizer &that); // assignment operator not implemented
michael@0 730
michael@0 731 // Private utility methods for iteration
michael@0 732 // For documentation, see the source code
michael@0 733 UBool nextNormalize();
michael@0 734 UBool previousNormalize();
michael@0 735
michael@0 736 void init();
michael@0 737 void clearBuffer(void);
michael@0 738
michael@0 739 //-------------------------------------------------------------------------
michael@0 740 // Private data
michael@0 741 //-------------------------------------------------------------------------
michael@0 742
michael@0 743 FilteredNormalizer2*fFilteredNorm2; // owned if not NULL
michael@0 744 const Normalizer2 *fNorm2; // not owned; may be equal to fFilteredNorm2
michael@0 745 UNormalizationMode fUMode;
michael@0 746 int32_t fOptions;
michael@0 747
michael@0 748 // The input text and our position in it
michael@0 749 CharacterIterator *text;
michael@0 750
michael@0 751 // The normalization buffer is the result of normalization
michael@0 752 // of the source in [currentIndex..nextIndex[ .
michael@0 753 int32_t currentIndex, nextIndex;
michael@0 754
michael@0 755 // A buffer for holding intermediate results
michael@0 756 UnicodeString buffer;
michael@0 757 int32_t bufferPos;
michael@0 758 };
michael@0 759
michael@0 760 //-------------------------------------------------------------------------
michael@0 761 // Inline implementations
michael@0 762 //-------------------------------------------------------------------------
michael@0 763
michael@0 764 inline UBool
michael@0 765 Normalizer::operator!= (const Normalizer& other) const
michael@0 766 { return ! operator==(other); }
michael@0 767
michael@0 768 inline UNormalizationCheckResult
michael@0 769 Normalizer::quickCheck(const UnicodeString& source,
michael@0 770 UNormalizationMode mode,
michael@0 771 UErrorCode &status) {
michael@0 772 return quickCheck(source, mode, 0, status);
michael@0 773 }
michael@0 774
michael@0 775 inline UBool
michael@0 776 Normalizer::isNormalized(const UnicodeString& source,
michael@0 777 UNormalizationMode mode,
michael@0 778 UErrorCode &status) {
michael@0 779 return isNormalized(source, mode, 0, status);
michael@0 780 }
michael@0 781
michael@0 782 inline int32_t
michael@0 783 Normalizer::compare(const UnicodeString &s1, const UnicodeString &s2,
michael@0 784 uint32_t options,
michael@0 785 UErrorCode &errorCode) {
michael@0 786 // all argument checking is done in unorm_compare
michael@0 787 return unorm_compare(s1.getBuffer(), s1.length(),
michael@0 788 s2.getBuffer(), s2.length(),
michael@0 789 options,
michael@0 790 &errorCode);
michael@0 791 }
michael@0 792
michael@0 793 U_NAMESPACE_END
michael@0 794
michael@0 795 #endif /* #if !UCONFIG_NO_NORMALIZATION */
michael@0 796
michael@0 797 #endif // NORMLZR_H

mercurial