← Back to branch summary

~ubuntu-branches/ubuntu/vivid/mozjs24/vivid

« back to all changes in this revision

Viewing changes to intl/icu/source/common/unicode/normlzr.h

  • Committer: Package Import Robot
  • Author(s): Tim Lunn
  • Date: 2014-02-11 21:55:34 UTC
  • Revision ID: package-import@ubuntu.com-20140211215534-m1zyq5aj59md3y07
Tags: upstream-24.2.0
Import upstream version 24.2.0

Show diffs side-by-side

added added

removed removed

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