1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4*******************************************************************************
5*
6* Copyright (C) 2009-2015, International Business Machines
7* Corporation and others. All Rights Reserved.
8*
9*******************************************************************************
10* file name: unorm2.h
11* encoding: UTF-8
12* tab size: 8 (not used)
13* indentation:4
14*
15* created on: 2009dec15
16* created by: Markus W. Scherer
17*/
18
19#ifndef __UNORM2_H__
20#define __UNORM2_H__
21
22/**
23 * \file
24 * \brief C API: New API for Unicode Normalization.
25 *
26 * Unicode normalization functionality for standard Unicode normalization or
27 * for using custom mapping tables.
28 * All instances of UNormalizer2 are unmodifiable/immutable.
29 * Instances returned by unorm2_getInstance() are singletons that must not be deleted by the caller.
30 * For more details see the Normalizer2 C++ class.
31 */
32
33#include "unicode/utypes.h"
34#include "unicode/stringoptions.h"
35#include "unicode/uset.h"
36
37#if U_SHOW_CPLUSPLUS_API
38#include "unicode/localpointer.h"
39#endif // U_SHOW_CPLUSPLUS_API
40
41/**
42 * Constants for normalization modes.
43 * For details about standard Unicode normalization forms
44 * and about the algorithms which are also used with custom mapping tables
45 * see http://www.unicode.org/unicode/reports/tr15/
46 * @stable ICU 4.4
47 */
48typedef enum {
49 /**
50 * Decomposition followed by composition.
51 * Same as standard NFC when using an "nfc" instance.
52 * Same as standard NFKC when using an "nfkc" instance.
53 * For details about standard Unicode normalization forms
54 * see http://www.unicode.org/unicode/reports/tr15/
55 * @stable ICU 4.4
56 */
57 UNORM2_COMPOSE,
58 /**
59 * Map, and reorder canonically.
60 * Same as standard NFD when using an "nfc" instance.
61 * Same as standard NFKD when using an "nfkc" instance.
62 * For details about standard Unicode normalization forms
63 * see http://www.unicode.org/unicode/reports/tr15/
64 * @stable ICU 4.4
65 */
66 UNORM2_DECOMPOSE,
67 /**
68 * "Fast C or D" form.
69 * If a string is in this form, then further decomposition <i>without reordering</i>
70 * would yield the same form as DECOMPOSE.
71 * Text in "Fast C or D" form can be processed efficiently with data tables
72 * that are "canonically closed", that is, that provide equivalent data for
73 * equivalent text, without having to be fully normalized.
74 * Not a standard Unicode normalization form.
75 * Not a unique form: Different FCD strings can be canonically equivalent.
76 * For details see http://www.unicode.org/notes/tn5/#FCD
77 * @stable ICU 4.4
78 */
79 UNORM2_FCD,
80 /**
81 * Compose only contiguously.
82 * Also known as "FCC" or "Fast C Contiguous".
83 * The result will often but not always be in NFC.
84 * The result will conform to FCD which is useful for processing.
85 * Not a standard Unicode normalization form.
86 * For details see http://www.unicode.org/notes/tn5/#FCC
87 * @stable ICU 4.4
88 */
89 UNORM2_COMPOSE_CONTIGUOUS
90} UNormalization2Mode;
91
92/**
93 * Result values for normalization quick check functions.
94 * For details see http://www.unicode.org/reports/tr15/#Detecting_Normalization_Forms
95 * @stable ICU 2.0
96 */
97typedef enum UNormalizationCheckResult {
98 /**
99 * The input string is not in the normalization form.
100 * @stable ICU 2.0
101 */
102 UNORM_NO,
103 /**
104 * The input string is in the normalization form.
105 * @stable ICU 2.0
106 */
107 UNORM_YES,
108 /**
109 * The input string may or may not be in the normalization form.
110 * This value is only returned for composition forms like NFC and FCC,
111 * when a backward-combining character is found for which the surrounding text
112 * would have to be analyzed further.
113 * @stable ICU 2.0
114 */
115 UNORM_MAYBE
116} UNormalizationCheckResult;
117
118/**
119 * Opaque C service object type for the new normalization API.
120 * @stable ICU 4.4
121 */
122struct UNormalizer2;
123typedef struct UNormalizer2 UNormalizer2; /**< C typedef for struct UNormalizer2. @stable ICU 4.4 */
124
125#if !UCONFIG_NO_NORMALIZATION
126
127/**
128 * Returns a UNormalizer2 instance for Unicode NFC normalization.
129 * Same as unorm2_getInstance(NULL, "nfc", UNORM2_COMPOSE, pErrorCode).
130 * Returns an unmodifiable singleton instance. Do not delete it.
131 * @param pErrorCode Standard ICU error code. Its input value must
132 * pass the U_SUCCESS() test, or else the function returns
133 * immediately. Check for U_FAILURE() on output or use with
134 * function chaining. (See User Guide for details.)
135 * @return the requested Normalizer2, if successful
136 * @stable ICU 49
137 */
138U_CAPI const UNormalizer2 * U_EXPORT2
139unorm2_getNFCInstance(UErrorCode *pErrorCode);
140
141/**
142 * Returns a UNormalizer2 instance for Unicode NFD normalization.
143 * Same as unorm2_getInstance(NULL, "nfc", UNORM2_DECOMPOSE, pErrorCode).
144 * Returns an unmodifiable singleton instance. Do not delete it.
145 * @param pErrorCode Standard ICU error code. Its input value must
146 * pass the U_SUCCESS() test, or else the function returns
147 * immediately. Check for U_FAILURE() on output or use with
148 * function chaining. (See User Guide for details.)
149 * @return the requested Normalizer2, if successful
150 * @stable ICU 49
151 */
152U_CAPI const UNormalizer2 * U_EXPORT2
153unorm2_getNFDInstance(UErrorCode *pErrorCode);
154
155/**
156 * Returns a UNormalizer2 instance for Unicode NFKC normalization.
157 * Same as unorm2_getInstance(NULL, "nfkc", UNORM2_COMPOSE, pErrorCode).
158 * Returns an unmodifiable singleton instance. Do not delete it.
159 * @param pErrorCode Standard ICU error code. Its input value must
160 * pass the U_SUCCESS() test, or else the function returns
161 * immediately. Check for U_FAILURE() on output or use with
162 * function chaining. (See User Guide for details.)
163 * @return the requested Normalizer2, if successful
164 * @stable ICU 49
165 */
166U_CAPI const UNormalizer2 * U_EXPORT2
167unorm2_getNFKCInstance(UErrorCode *pErrorCode);
168
169/**
170 * Returns a UNormalizer2 instance for Unicode NFKD normalization.
171 * Same as unorm2_getInstance(NULL, "nfkc", UNORM2_DECOMPOSE, pErrorCode).
172 * Returns an unmodifiable singleton instance. Do not delete it.
173 * @param pErrorCode Standard ICU error code. Its input value must
174 * pass the U_SUCCESS() test, or else the function returns
175 * immediately. Check for U_FAILURE() on output or use with
176 * function chaining. (See User Guide for details.)
177 * @return the requested Normalizer2, if successful
178 * @stable ICU 49
179 */
180U_CAPI const UNormalizer2 * U_EXPORT2
181unorm2_getNFKDInstance(UErrorCode *pErrorCode);
182
183/**
184 * Returns a UNormalizer2 instance for Unicode toNFKC_Casefold() normalization
185 * which is equivalent to applying the NFKC_Casefold mappings and then NFC.
186 * See https://www.unicode.org/reports/tr44/#NFKC_Casefold
187 *
188 * Same as unorm2_getInstance(NULL, "nfkc_cf", UNORM2_COMPOSE, pErrorCode).
189 * Returns an unmodifiable singleton instance. Do not delete it.
190 * @param pErrorCode Standard ICU error code. Its input value must
191 * pass the U_SUCCESS() test, or else the function returns
192 * immediately. Check for U_FAILURE() on output or use with
193 * function chaining. (See User Guide for details.)
194 * @return the requested Normalizer2, if successful
195 * @stable ICU 49
196 */
197U_CAPI const UNormalizer2 * U_EXPORT2
198unorm2_getNFKCCasefoldInstance(UErrorCode *pErrorCode);
199
200#ifndef U_HIDE_DRAFT_API
201/**
202 * Returns a UNormalizer2 instance for a variant of Unicode toNFKC_Casefold() normalization
203 * which is equivalent to applying the NFKC_Simple_Casefold mappings and then NFC.
204 * See https://www.unicode.org/reports/tr44/#NFKC_Simple_Casefold
205 *
206 * Same as unorm2_getInstance(NULL, "nfkc_scf", UNORM2_COMPOSE, pErrorCode).
207 * Returns an unmodifiable singleton instance. Do not delete it.
208 * @param pErrorCode Standard ICU error code. Its input value must
209 * pass the U_SUCCESS() test, or else the function returns
210 * immediately. Check for U_FAILURE() on output or use with
211 * function chaining. (See User Guide for details.)
212 * @return the requested Normalizer2, if successful
213 * @draft ICU 74
214 */
215U_CAPI const UNormalizer2 * U_EXPORT2
216unorm2_getNFKCSimpleCasefoldInstance(UErrorCode *pErrorCode);
217#endif // U_HIDE_DRAFT_API
218
219/**
220 * Returns a UNormalizer2 instance which uses the specified data file
221 * (packageName/name similar to ucnv_openPackage() and ures_open()/ResourceBundle)
222 * and which composes or decomposes text according to the specified mode.
223 * Returns an unmodifiable singleton instance. Do not delete it.
224 *
225 * Use packageName=NULL for data files that are part of ICU's own data.
226 * Use name="nfc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFC/NFD.
227 * Use name="nfkc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFKC/NFKD.
228 * Use name="nfkc_cf" and UNORM2_COMPOSE for Unicode standard NFKC_CF=NFKC_Casefold.
229 *
230 * @param packageName NULL for ICU built-in data, otherwise application data package name
231 * @param name "nfc" or "nfkc" or "nfkc_cf" or "nfkc_scf" or name of custom data file
232 * @param mode normalization mode (compose or decompose etc.)
233 * @param pErrorCode Standard ICU error code. Its input value must
234 * pass the U_SUCCESS() test, or else the function returns
235 * immediately. Check for U_FAILURE() on output or use with
236 * function chaining. (See User Guide for details.)
237 * @return the requested UNormalizer2, if successful
238 * @stable ICU 4.4
239 */
240U_CAPI const UNormalizer2 * U_EXPORT2
241unorm2_getInstance(const char *packageName,
242 const char *name,
243 UNormalization2Mode mode,
244 UErrorCode *pErrorCode);
245
246/**
247 * Constructs a filtered normalizer wrapping any UNormalizer2 instance
248 * and a filter set.
249 * Both are aliased and must not be modified or deleted while this object
250 * is used.
251 * The filter set should be frozen; otherwise the performance will suffer greatly.
252 * @param norm2 wrapped UNormalizer2 instance
253 * @param filterSet USet which determines the characters to be normalized
254 * @param pErrorCode Standard ICU error code. Its input value must
255 * pass the U_SUCCESS() test, or else the function returns
256 * immediately. Check for U_FAILURE() on output or use with
257 * function chaining. (See User Guide for details.)
258 * @return the requested UNormalizer2, if successful
259 * @stable ICU 4.4
260 */
261U_CAPI UNormalizer2 * U_EXPORT2
262unorm2_openFiltered(const UNormalizer2 *norm2, const USet *filterSet, UErrorCode *pErrorCode);
263
264/**
265 * Closes a UNormalizer2 instance from unorm2_openFiltered().
266 * Do not close instances from unorm2_getInstance()!
267 * @param norm2 UNormalizer2 instance to be closed
268 * @stable ICU 4.4
269 */
270U_CAPI void U_EXPORT2
271unorm2_close(UNormalizer2 *norm2);
272
273#if U_SHOW_CPLUSPLUS_API
274
275U_NAMESPACE_BEGIN
276
277/**
278 * \class LocalUNormalizer2Pointer
279 * "Smart pointer" class, closes a UNormalizer2 via unorm2_close().
280 * For most methods see the LocalPointerBase base class.
281 *
282 * @see LocalPointerBase
283 * @see LocalPointer
284 * @stable ICU 4.4
285 */
286U_DEFINE_LOCAL_OPEN_POINTER(LocalUNormalizer2Pointer, UNormalizer2, unorm2_close);
287
288U_NAMESPACE_END
289
290#endif
291
292/**
293 * Writes the normalized form of the source string to the destination string
294 * (replacing its contents) and returns the length of the destination string.
295 * The source and destination strings must be different buffers.
296 * @param norm2 UNormalizer2 instance
297 * @param src source string
298 * @param length length of the source string, or -1 if NUL-terminated
299 * @param dest destination string; its contents is replaced with normalized src
300 * @param capacity number of UChars that can be written to dest
301 * @param pErrorCode Standard ICU error code. Its input value must
302 * pass the U_SUCCESS() test, or else the function returns
303 * immediately. Check for U_FAILURE() on output or use with
304 * function chaining. (See User Guide for details.)
305 * @return dest
306 * @stable ICU 4.4
307 */
308U_CAPI int32_t U_EXPORT2
309unorm2_normalize(const UNormalizer2 *norm2,
310 const UChar *src, int32_t length,
311 UChar *dest, int32_t capacity,
312 UErrorCode *pErrorCode);
313/**
314 * Appends the normalized form of the second string to the first string
315 * (merging them at the boundary) and returns the length of the first string.
316 * The result is normalized if the first string was normalized.
317 * The first and second strings must be different buffers.
318 * @param norm2 UNormalizer2 instance
319 * @param first string, should be normalized
320 * @param firstLength length of the first string, or -1 if NUL-terminated
321 * @param firstCapacity number of UChars that can be written to first
322 * @param second string, will be normalized
323 * @param secondLength length of the source string, or -1 if NUL-terminated
324 * @param pErrorCode Standard ICU error code. Its input value must
325 * pass the U_SUCCESS() test, or else the function returns
326 * immediately. Check for U_FAILURE() on output or use with
327 * function chaining. (See User Guide for details.)
328 * @return first
329 * @stable ICU 4.4
330 */
331U_CAPI int32_t U_EXPORT2
332unorm2_normalizeSecondAndAppend(const UNormalizer2 *norm2,
333 UChar *first, int32_t firstLength, int32_t firstCapacity,
334 const UChar *second, int32_t secondLength,
335 UErrorCode *pErrorCode);
336/**
337 * Appends the second string to the first string
338 * (merging them at the boundary) and returns the length of the first string.
339 * The result is normalized if both the strings were normalized.
340 * The first and second strings must be different buffers.
341 * @param norm2 UNormalizer2 instance
342 * @param first string, should be normalized
343 * @param firstLength length of the first string, or -1 if NUL-terminated
344 * @param firstCapacity number of UChars that can be written to first
345 * @param second string, should be normalized
346 * @param secondLength length of the source string, or -1 if NUL-terminated
347 * @param pErrorCode Standard ICU error code. Its input value must
348 * pass the U_SUCCESS() test, or else the function returns
349 * immediately. Check for U_FAILURE() on output or use with
350 * function chaining. (See User Guide for details.)
351 * @return first
352 * @stable ICU 4.4
353 */
354U_CAPI int32_t U_EXPORT2
355unorm2_append(const UNormalizer2 *norm2,
356 UChar *first, int32_t firstLength, int32_t firstCapacity,
357 const UChar *second, int32_t secondLength,
358 UErrorCode *pErrorCode);
359
360/**
361 * Gets the decomposition mapping of c.
362 * Roughly equivalent to normalizing the String form of c
363 * on a UNORM2_DECOMPOSE UNormalizer2 instance, but much faster, and except that this function
364 * returns a negative value and does not write a string
365 * if c does not have a decomposition mapping in this instance's data.
366 * This function is independent of the mode of the UNormalizer2.
367 * @param norm2 UNormalizer2 instance
368 * @param c code point
369 * @param decomposition String buffer which will be set to c's
370 * decomposition mapping, if there is one.
371 * @param capacity number of UChars that can be written to decomposition
372 * @param pErrorCode Standard ICU error code. Its input value must
373 * pass the U_SUCCESS() test, or else the function returns
374 * immediately. Check for U_FAILURE() on output or use with
375 * function chaining. (See User Guide for details.)
376 * @return the non-negative length of c's decomposition, if there is one; otherwise a negative value
377 * @stable ICU 4.6
378 */
379U_CAPI int32_t U_EXPORT2
380unorm2_getDecomposition(const UNormalizer2 *norm2,
381 UChar32 c, UChar *decomposition, int32_t capacity,
382 UErrorCode *pErrorCode);
383
384/**
385 * Gets the raw decomposition mapping of c.
386 *
387 * This is similar to the unorm2_getDecomposition() function but returns the
388 * raw decomposition mapping as specified in UnicodeData.txt or
389 * (for custom data) in the mapping files processed by the gennorm2 tool.
390 * By contrast, unorm2_getDecomposition() returns the processed,
391 * recursively-decomposed version of this mapping.
392 *
393 * When used on a standard NFKC Normalizer2 instance,
394 * unorm2_getRawDecomposition() returns the Unicode Decomposition_Mapping (dm) property.
395 *
396 * When used on a standard NFC Normalizer2 instance,
397 * it returns the Decomposition_Mapping only if the Decomposition_Type (dt) is Canonical (Can);
398 * in this case, the result contains either one or two code points (=1..4 UChars).
399 *
400 * This function is independent of the mode of the UNormalizer2.
401 * @param norm2 UNormalizer2 instance
402 * @param c code point
403 * @param decomposition String buffer which will be set to c's
404 * raw decomposition mapping, if there is one.
405 * @param capacity number of UChars that can be written to decomposition
406 * @param pErrorCode Standard ICU error code. Its input value must
407 * pass the U_SUCCESS() test, or else the function returns
408 * immediately. Check for U_FAILURE() on output or use with
409 * function chaining. (See User Guide for details.)
410 * @return the non-negative length of c's raw decomposition, if there is one; otherwise a negative value
411 * @stable ICU 49
412 */
413U_CAPI int32_t U_EXPORT2
414unorm2_getRawDecomposition(const UNormalizer2 *norm2,
415 UChar32 c, UChar *decomposition, int32_t capacity,
416 UErrorCode *pErrorCode);
417
418/**
419 * Performs pairwise composition of a & b and returns the composite if there is one.
420 *
421 * Returns a composite code point c only if c has a two-way mapping to a+b.
422 * In standard Unicode normalization, this means that
423 * c has a canonical decomposition to a+b
424 * and c does not have the Full_Composition_Exclusion property.
425 *
426 * This function is independent of the mode of the UNormalizer2.
427 * @param norm2 UNormalizer2 instance
428 * @param a A (normalization starter) code point.
429 * @param b Another code point.
430 * @return The non-negative composite code point if there is one; otherwise a negative value.
431 * @stable ICU 49
432 */
433U_CAPI UChar32 U_EXPORT2
434unorm2_composePair(const UNormalizer2 *norm2, UChar32 a, UChar32 b);
435
436/**
437 * Gets the combining class of c.
438 * The default implementation returns 0
439 * but all standard implementations return the Unicode Canonical_Combining_Class value.
440 * @param norm2 UNormalizer2 instance
441 * @param c code point
442 * @return c's combining class
443 * @stable ICU 49
444 */
445U_CAPI uint8_t U_EXPORT2
446unorm2_getCombiningClass(const UNormalizer2 *norm2, UChar32 c);
447
448/**
449 * Tests if the string is normalized.
450 * Internally, in cases where the quickCheck() method would return "maybe"
451 * (which is only possible for the two COMPOSE modes) this method
452 * resolves to "yes" or "no" to provide a definitive result,
453 * at the cost of doing more work in those cases.
454 * @param norm2 UNormalizer2 instance
455 * @param s input string
456 * @param length length of the string, or -1 if NUL-terminated
457 * @param pErrorCode Standard ICU error code. Its input value must
458 * pass the U_SUCCESS() test, or else the function returns
459 * immediately. Check for U_FAILURE() on output or use with
460 * function chaining. (See User Guide for details.)
461 * @return true if s is normalized
462 * @stable ICU 4.4
463 */
464U_CAPI UBool U_EXPORT2
465unorm2_isNormalized(const UNormalizer2 *norm2,
466 const UChar *s, int32_t length,
467 UErrorCode *pErrorCode);
468
469/**
470 * Tests if the string is normalized.
471 * For the two COMPOSE modes, the result could be "maybe" in cases that
472 * would take a little more work to resolve definitively.
473 * Use spanQuickCheckYes() and normalizeSecondAndAppend() for a faster
474 * combination of quick check + normalization, to avoid
475 * re-checking the "yes" prefix.
476 * @param norm2 UNormalizer2 instance
477 * @param s input string
478 * @param length length of the string, or -1 if NUL-terminated
479 * @param pErrorCode Standard ICU error code. Its input value must
480 * pass the U_SUCCESS() test, or else the function returns
481 * immediately. Check for U_FAILURE() on output or use with
482 * function chaining. (See User Guide for details.)
483 * @return UNormalizationCheckResult
484 * @stable ICU 4.4
485 */
486U_CAPI UNormalizationCheckResult U_EXPORT2
487unorm2_quickCheck(const UNormalizer2 *norm2,
488 const UChar *s, int32_t length,
489 UErrorCode *pErrorCode);
490
491/**
492 * Returns the end of the normalized substring of the input string.
493 * In other words, with <code>end=spanQuickCheckYes(s, ec);</code>
494 * the substring <code>UnicodeString(s, 0, end)</code>
495 * will pass the quick check with a "yes" result.
496 *
497 * The returned end index is usually one or more characters before the
498 * "no" or "maybe" character: The end index is at a normalization boundary.
499 * (See the class documentation for more about normalization boundaries.)
500 *
501 * When the goal is a normalized string and most input strings are expected
502 * to be normalized already, then call this method,
503 * and if it returns a prefix shorter than the input string,
504 * copy that prefix and use normalizeSecondAndAppend() for the remainder.
505 * @param norm2 UNormalizer2 instance
506 * @param s input string
507 * @param length length of the string, or -1 if NUL-terminated
508 * @param pErrorCode Standard ICU error code. Its input value must
509 * pass the U_SUCCESS() test, or else the function returns
510 * immediately. Check for U_FAILURE() on output or use with
511 * function chaining. (See User Guide for details.)
512 * @return "yes" span end index
513 * @stable ICU 4.4
514 */
515U_CAPI int32_t U_EXPORT2
516unorm2_spanQuickCheckYes(const UNormalizer2 *norm2,
517 const UChar *s, int32_t length,
518 UErrorCode *pErrorCode);
519
520/**
521 * Tests if the character always has a normalization boundary before it,
522 * regardless of context.
523 * For details see the Normalizer2 base class documentation.
524 * @param norm2 UNormalizer2 instance
525 * @param c character to test
526 * @return true if c has a normalization boundary before it
527 * @stable ICU 4.4
528 */
529U_CAPI UBool U_EXPORT2
530unorm2_hasBoundaryBefore(const UNormalizer2 *norm2, UChar32 c);
531
532/**
533 * Tests if the character always has a normalization boundary after it,
534 * regardless of context.
535 * For details see the Normalizer2 base class documentation.
536 * @param norm2 UNormalizer2 instance
537 * @param c character to test
538 * @return true if c has a normalization boundary after it
539 * @stable ICU 4.4
540 */
541U_CAPI UBool U_EXPORT2
542unorm2_hasBoundaryAfter(const UNormalizer2 *norm2, UChar32 c);
543
544/**
545 * Tests if the character is normalization-inert.
546 * For details see the Normalizer2 base class documentation.
547 * @param norm2 UNormalizer2 instance
548 * @param c character to test
549 * @return true if c is normalization-inert
550 * @stable ICU 4.4
551 */
552U_CAPI UBool U_EXPORT2
553unorm2_isInert(const UNormalizer2 *norm2, UChar32 c);
554
555/**
556 * Compares two strings for canonical equivalence.
557 * Further options include case-insensitive comparison and
558 * code point order (as opposed to code unit order).
559 *
560 * Canonical equivalence between two strings is defined as their normalized
561 * forms (NFD or NFC) being identical.
562 * This function compares strings incrementally instead of normalizing
563 * (and optionally case-folding) both strings entirely,
564 * improving performance significantly.
565 *
566 * Bulk normalization is only necessary if the strings do not fulfill the FCD
567 * conditions. Only in this case, and only if the strings are relatively long,
568 * is memory allocated temporarily.
569 * For FCD strings and short non-FCD strings there is no memory allocation.
570 *
571 * Semantically, this is equivalent to
572 * strcmp[CodePointOrder](NFD(foldCase(NFD(s1))), NFD(foldCase(NFD(s2))))
573 * where code point order and foldCase are all optional.
574 *
575 * UAX 21 2.5 Caseless Matching specifies that for a canonical caseless match
576 * the case folding must be performed first, then the normalization.
577 *
578 * @param s1 First source string.
579 * @param length1 Length of first source string, or -1 if NUL-terminated.
580 *
581 * @param s2 Second source string.
582 * @param length2 Length of second source string, or -1 if NUL-terminated.
583 *
584 * @param options A bit set of options:
585 * - U_FOLD_CASE_DEFAULT or 0 is used for default options:
586 * Case-sensitive comparison in code unit order, and the input strings
587 * are quick-checked for FCD.
588 *
589 * - UNORM_INPUT_IS_FCD
590 * Set if the caller knows that both s1 and s2 fulfill the FCD conditions.
591 * If not set, the function will quickCheck for FCD
592 * and normalize if necessary.
593 *
594 * - U_COMPARE_CODE_POINT_ORDER
595 * Set to choose code point order instead of code unit order
596 * (see u_strCompare for details).
597 *
598 * - U_COMPARE_IGNORE_CASE
599 * Set to compare strings case-insensitively using case folding,
600 * instead of case-sensitively.
601 * If set, then the following case folding options are used.
602 *
603 * - Options as used with case-insensitive comparisons, currently:
604 *
605 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I
606 * (see u_strCaseCompare for details)
607 *
608 * - regular normalization options shifted left by UNORM_COMPARE_NORM_OPTIONS_SHIFT
609 *
610 * @param pErrorCode ICU error code in/out parameter.
611 * Must fulfill U_SUCCESS before the function call.
612 * @return <0 or 0 or >0 as usual for string comparisons
613 *
614 * @see unorm_normalize
615 * @see UNORM_FCD
616 * @see u_strCompare
617 * @see u_strCaseCompare
618 *
619 * @stable ICU 2.2
620 */
621U_CAPI int32_t U_EXPORT2
622unorm_compare(const UChar *s1, int32_t length1,
623 const UChar *s2, int32_t length2,
624 uint32_t options,
625 UErrorCode *pErrorCode);
626
627#endif /* !UCONFIG_NO_NORMALIZATION */
628#endif /* __UNORM2_H__ */
629

source code of include/unicode/unorm2.h