1/*
2*******************************************************************************
3*
4*   Copyright (C) 2009-2010, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*
7*******************************************************************************
8*   file name:  unorm2.h
9*   encoding:   US-ASCII
10*   tab size:   8 (not used)
11*   indentation:4
12*
13*   created on: 2009dec15
14*   created by: Markus W. Scherer
15*/
16
17#ifndef __UNORM2_H__
18#define __UNORM2_H__
19
20/**
21 * \file
22 * \brief C API: New API for Unicode Normalization.
23 *
24 * Unicode normalization functionality for standard Unicode normalization or
25 * for using custom mapping tables.
26 * All instances of UNormalizer2 are unmodifiable/immutable.
27 * Instances returned by unorm2_getInstance() are singletons that must not be deleted by the caller.
28 * For more details see the Normalizer2 C++ class.
29 */
30
31#include "unicode/utypes.h"
32#include "unicode/localpointer.h"
33#include "unicode/uset.h"
34
35/**
36 * Constants for normalization modes.
37 * For details about standard Unicode normalization forms
38 * and about the algorithms which are also used with custom mapping tables
39 * see http://www.unicode.org/unicode/reports/tr15/
40 * @draft ICU 4.4
41 */
42typedef enum {
43    /**
44     * Decomposition followed by composition.
45     * Same as standard NFC when using an "nfc" instance.
46     * Same as standard NFKC when using an "nfkc" instance.
47     * For details about standard Unicode normalization forms
48     * see http://www.unicode.org/unicode/reports/tr15/
49     * @draft ICU 4.4
50     */
51    UNORM2_COMPOSE,
52    /**
53     * Map, and reorder canonically.
54     * Same as standard NFD when using an "nfc" instance.
55     * Same as standard NFKD when using an "nfkc" instance.
56     * For details about standard Unicode normalization forms
57     * see http://www.unicode.org/unicode/reports/tr15/
58     * @draft ICU 4.4
59     */
60    UNORM2_DECOMPOSE,
61    /**
62     * "Fast C or D" form.
63     * If a string is in this form, then further decomposition <i>without reordering</i>
64     * would yield the same form as DECOMPOSE.
65     * Text in "Fast C or D" form can be processed efficiently with data tables
66     * that are "canonically closed", that is, that provide equivalent data for
67     * equivalent text, without having to be fully normalized.
68     * Not a standard Unicode normalization form.
69     * Not a unique form: Different FCD strings can be canonically equivalent.
70     * For details see http://www.unicode.org/notes/tn5/#FCD
71     * @draft ICU 4.4
72     */
73    UNORM2_FCD,
74    /**
75     * Compose only contiguously.
76     * Also known as "FCC" or "Fast C Contiguous".
77     * The result will often but not always be in NFC.
78     * The result will conform to FCD which is useful for processing.
79     * Not a standard Unicode normalization form.
80     * For details see http://www.unicode.org/notes/tn5/#FCC
81     * @draft ICU 4.4
82     */
83    UNORM2_COMPOSE_CONTIGUOUS
84} UNormalization2Mode;
85
86/**
87 * Result values for normalization quick check functions.
88 * For details see http://www.unicode.org/reports/tr15/#Detecting_Normalization_Forms
89 * @stable ICU 2.0
90 */
91typedef enum UNormalizationCheckResult {
92  /**
93   * The input string is not in the normalization form.
94   * @stable ICU 2.0
95   */
96  UNORM_NO,
97  /**
98   * The input string is in the normalization form.
99   * @stable ICU 2.0
100   */
101  UNORM_YES,
102  /**
103   * The input string may or may not be in the normalization form.
104   * This value is only returned for composition forms like NFC and FCC,
105   * when a backward-combining character is found for which the surrounding text
106   * would have to be analyzed further.
107   * @stable ICU 2.0
108   */
109  UNORM_MAYBE
110} UNormalizationCheckResult;
111
112/**
113 * Opaque C service object type for the new normalization API.
114 * @draft ICU 4.4
115 */
116struct UNormalizer2;
117typedef struct UNormalizer2 UNormalizer2;  /**< C typedef for struct UNormalizer2. @draft ICU 4.4 */
118
119#if !UCONFIG_NO_NORMALIZATION
120
121/**
122 * Returns a UNormalizer2 instance which uses the specified data file
123 * (packageName/name similar to ucnv_openPackage() and ures_open()/ResourceBundle)
124 * and which composes or decomposes text according to the specified mode.
125 * Returns an unmodifiable singleton instance. Do not delete it.
126 *
127 * Use packageName=NULL for data files that are part of ICU's own data.
128 * Use name="nfc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFC/NFD.
129 * Use name="nfkc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFKC/NFKD.
130 * Use name="nfkc_cf" and UNORM2_COMPOSE for Unicode standard NFKC_CF=NFKC_Casefold.
131 *
132 * @param packageName NULL for ICU built-in data, otherwise application data package name
133 * @param name "nfc" or "nfkc" or "nfkc_cf" or name of custom data file
134 * @param mode normalization mode (compose or decompose etc.)
135 * @param pErrorCode Standard ICU error code. Its input value must
136 *                  pass the U_SUCCESS() test, or else the function returns
137 *                  immediately. Check for U_FAILURE() on output or use with
138 *                  function chaining. (See User Guide for details.)
139 * @return the requested UNormalizer2, if successful
140 * @draft ICU 4.4
141 */
142U_DRAFT const UNormalizer2 * U_EXPORT2
143unorm2_getInstance(const char *packageName,
144                   const char *name,
145                   UNormalization2Mode mode,
146                   UErrorCode *pErrorCode);
147
148/**
149 * Constructs a filtered normalizer wrapping any UNormalizer2 instance
150 * and a filter set.
151 * Both are aliased and must not be modified or deleted while this object
152 * is used.
153 * The filter set should be frozen; otherwise the performance will suffer greatly.
154 * @param norm2 wrapped Normalizer2 instance
155 * @param filterSet USet which determines the characters to be normalized
156 * @param pErrorCode Standard ICU error code. Its input value must
157 *                   pass the U_SUCCESS() test, or else the function returns
158 *                   immediately. Check for U_FAILURE() on output or use with
159 *                   function chaining. (See User Guide for details.)
160 * @return the requested UNormalizer2, if successful
161 * @draft ICU 4.4
162 */
163U_DRAFT UNormalizer2 * U_EXPORT2
164unorm2_openFiltered(const UNormalizer2 *norm2, const USet *filterSet, UErrorCode *pErrorCode);
165
166/**
167 * Closes a UNormalizer2 instance from unorm2_openFiltered().
168 * Do not close instances from unorm2_getInstance()!
169 * @param norm2 UNormalizer2 instance to be closed
170 * @draft ICU 4.4
171 */
172U_DRAFT void U_EXPORT2
173unorm2_close(UNormalizer2 *norm2);
174
175#if U_SHOW_CPLUSPLUS_API
176
177U_NAMESPACE_BEGIN
178
179/**
180 * \class LocalUNormalizer2Pointer
181 * "Smart pointer" class, closes a UNormalizer2 via unorm2_close().
182 * For most methods see the LocalPointerBase base class.
183 *
184 * @see LocalPointerBase
185 * @see LocalPointer
186 * @draft ICU 4.4
187 */
188U_DEFINE_LOCAL_OPEN_POINTER(LocalUNormalizer2Pointer, UNormalizer2, unorm2_close);
189
190U_NAMESPACE_END
191
192#endif
193
194/**
195 * Writes the normalized form of the source string to the destination string
196 * (replacing its contents) and returns the length of the destination string.
197 * The source and destination strings must be different buffers.
198 * @param norm2 UNormalizer2 instance
199 * @param src source string
200 * @param length length of the source string, or -1 if NUL-terminated
201 * @param dest destination string; its contents is replaced with normalized src
202 * @param capacity number of UChars that can be written to dest
203 * @param pErrorCode Standard ICU error code. Its input value must
204 *                   pass the U_SUCCESS() test, or else the function returns
205 *                   immediately. Check for U_FAILURE() on output or use with
206 *                   function chaining. (See User Guide for details.)
207 * @return dest
208 * @draft ICU 4.4
209 */
210U_DRAFT int32_t U_EXPORT2
211unorm2_normalize(const UNormalizer2 *norm2,
212                 const UChar *src, int32_t length,
213                 UChar *dest, int32_t capacity,
214                 UErrorCode *pErrorCode);
215/**
216 * Appends the normalized form of the second string to the first string
217 * (merging them at the boundary) and returns the length of the first string.
218 * The result is normalized if the first string was normalized.
219 * The first and second strings must be different buffers.
220 * @param norm2 UNormalizer2 instance
221 * @param first string, should be normalized
222 * @param firstLength length of the first string, or -1 if NUL-terminated
223 * @param firstCapacity number of UChars that can be written to first
224 * @param second string, will be normalized
225 * @param secondLength length of the source string, or -1 if NUL-terminated
226 * @param pErrorCode Standard ICU error code. Its input value must
227 *                   pass the U_SUCCESS() test, or else the function returns
228 *                   immediately. Check for U_FAILURE() on output or use with
229 *                   function chaining. (See User Guide for details.)
230 * @return first
231 * @draft ICU 4.4
232 */
233U_DRAFT int32_t U_EXPORT2
234unorm2_normalizeSecondAndAppend(const UNormalizer2 *norm2,
235                                UChar *first, int32_t firstLength, int32_t firstCapacity,
236                                const UChar *second, int32_t secondLength,
237                                UErrorCode *pErrorCode);
238/**
239 * Appends the second string to the first string
240 * (merging them at the boundary) and returns the length of the first string.
241 * The result is normalized if both the strings were normalized.
242 * The first and second strings must be different buffers.
243 * @param norm2 UNormalizer2 instance
244 * @param first string, should be normalized
245 * @param firstLength length of the first string, or -1 if NUL-terminated
246 * @param firstCapacity number of UChars that can be written to first
247 * @param second string, should be normalized
248 * @param secondLength length of the source string, or -1 if NUL-terminated
249 * @param pErrorCode Standard ICU error code. Its input value must
250 *                   pass the U_SUCCESS() test, or else the function returns
251 *                   immediately. Check for U_FAILURE() on output or use with
252 *                   function chaining. (See User Guide for details.)
253 * @return first
254 * @draft ICU 4.4
255 */
256U_DRAFT int32_t U_EXPORT2
257unorm2_append(const UNormalizer2 *norm2,
258              UChar *first, int32_t firstLength, int32_t firstCapacity,
259              const UChar *second, int32_t secondLength,
260              UErrorCode *pErrorCode);
261
262/**
263 * Tests if the string is normalized.
264 * Internally, in cases where the quickCheck() method would return "maybe"
265 * (which is only possible for the two COMPOSE modes) this method
266 * resolves to "yes" or "no" to provide a definitive result,
267 * at the cost of doing more work in those cases.
268 * @param norm2 UNormalizer2 instance
269 * @param s input string
270 * @param length length of the string, or -1 if NUL-terminated
271 * @param pErrorCode Standard ICU error code. Its input value must
272 *                   pass the U_SUCCESS() test, or else the function returns
273 *                   immediately. Check for U_FAILURE() on output or use with
274 *                   function chaining. (See User Guide for details.)
275 * @return TRUE if s is normalized
276 * @draft ICU 4.4
277 */
278U_DRAFT UBool U_EXPORT2
279unorm2_isNormalized(const UNormalizer2 *norm2,
280                    const UChar *s, int32_t length,
281                    UErrorCode *pErrorCode);
282
283/**
284 * Tests if the string is normalized.
285 * For the two COMPOSE modes, the result could be "maybe" in cases that
286 * would take a little more work to resolve definitively.
287 * Use spanQuickCheckYes() and normalizeSecondAndAppend() for a faster
288 * combination of quick check + normalization, to avoid
289 * re-checking the "yes" prefix.
290 * @param norm2 UNormalizer2 instance
291 * @param s input string
292 * @param length length of the string, or -1 if NUL-terminated
293 * @param pErrorCode Standard ICU error code. Its input value must
294 *                   pass the U_SUCCESS() test, or else the function returns
295 *                   immediately. Check for U_FAILURE() on output or use with
296 *                   function chaining. (See User Guide for details.)
297 * @return UNormalizationCheckResult
298 * @draft ICU 4.4
299 */
300U_DRAFT UNormalizationCheckResult U_EXPORT2
301unorm2_quickCheck(const UNormalizer2 *norm2,
302                  const UChar *s, int32_t length,
303                  UErrorCode *pErrorCode);
304
305/**
306 * Returns the end of the normalized substring of the input string.
307 * In other words, with <code>end=spanQuickCheckYes(s, ec);</code>
308 * the substring <code>UnicodeString(s, 0, end)</code>
309 * will pass the quick check with a "yes" result.
310 *
311 * The returned end index is usually one or more characters before the
312 * "no" or "maybe" character: The end index is at a normalization boundary.
313 * (See the class documentation for more about normalization boundaries.)
314 *
315 * When the goal is a normalized string and most input strings are expected
316 * to be normalized already, then call this method,
317 * and if it returns a prefix shorter than the input string,
318 * copy that prefix and use normalizeSecondAndAppend() for the remainder.
319 * @param norm2 UNormalizer2 instance
320 * @param s input string
321 * @param length length of the string, or -1 if NUL-terminated
322 * @param pErrorCode Standard ICU error code. Its input value must
323 *                   pass the U_SUCCESS() test, or else the function returns
324 *                   immediately. Check for U_FAILURE() on output or use with
325 *                   function chaining. (See User Guide for details.)
326 * @return "yes" span end index
327 * @draft ICU 4.4
328 */
329U_DRAFT int32_t U_EXPORT2
330unorm2_spanQuickCheckYes(const UNormalizer2 *norm2,
331                         const UChar *s, int32_t length,
332                         UErrorCode *pErrorCode);
333
334/**
335 * Tests if the character always has a normalization boundary before it,
336 * regardless of context.
337 * For details see the Normalizer2 base class documentation.
338 * @param norm2 UNormalizer2 instance
339 * @param c character to test
340 * @return TRUE if c has a normalization boundary before it
341 * @draft ICU 4.4
342 */
343U_DRAFT UBool U_EXPORT2
344unorm2_hasBoundaryBefore(const UNormalizer2 *norm2, UChar32 c);
345
346/**
347 * Tests if the character always has a normalization boundary after it,
348 * regardless of context.
349 * For details see the Normalizer2 base class documentation.
350 * @param norm2 UNormalizer2 instance
351 * @param c character to test
352 * @return TRUE if c has a normalization boundary after it
353 * @draft ICU 4.4
354 */
355U_DRAFT UBool U_EXPORT2
356unorm2_hasBoundaryAfter(const UNormalizer2 *norm2, UChar32 c);
357
358/**
359 * Tests if the character is normalization-inert.
360 * For details see the Normalizer2 base class documentation.
361 * @param norm2 UNormalizer2 instance
362 * @param c character to test
363 * @return TRUE if c is normalization-inert
364 * @draft ICU 4.4
365 */
366U_DRAFT UBool U_EXPORT2
367unorm2_isInert(const UNormalizer2 *norm2, UChar32 c);
368
369#endif  /* !UCONFIG_NO_NORMALIZATION */
370#endif  /* __UNORM2_H__ */
371