]> git.saurik.com Git - apple/javascriptcore.git/blame_incremental - icu/unicode/unorm2.h
JavaScriptCore-1218.tar.gz
[apple/javascriptcore.git] / icu / unicode / unorm2.h
... / ...
CommitLineData
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 * @stable 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 * @stable 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 * @stable 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 * @stable 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 * @stable 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 * @stable ICU 4.4
115 */
116struct UNormalizer2;
117typedef struct UNormalizer2 UNormalizer2; /**< C typedef for struct UNormalizer2. @stable 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 * @stable ICU 4.4
141 */
142U_STABLE 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 UNormalizer2 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 * @stable ICU 4.4
162 */
163U_STABLE 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 * @stable ICU 4.4
171 */
172U_STABLE 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 * @stable 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 * @stable ICU 4.4
209 */
210U_STABLE 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 * @stable ICU 4.4
232 */
233U_STABLE 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 * @stable ICU 4.4
255 */
256U_STABLE 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 * Gets the decomposition mapping of c. Equivalent to unorm2_normalize(string(c))
264 * on a UNORM2_DECOMPOSE UNormalizer2 instance, but much faster.
265 * This function is independent of the mode of the UNormalizer2.
266 * @param norm2 UNormalizer2 instance
267 * @param c code point
268 * @param decomposition String buffer which will be set to c's
269 * decomposition mapping, if there is one.
270 * @param capacity number of UChars that can be written to decomposition
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 the non-negative length of c's decomposition, if there is one; otherwise a negative value
276 * @draft ICU 4.6
277 */
278U_DRAFT int32_t U_EXPORT2
279unorm2_getDecomposition(const UNormalizer2 *norm2,
280 UChar32 c, UChar *decomposition, int32_t capacity,
281 UErrorCode *pErrorCode);
282
283/**
284 * Tests if the string is normalized.
285 * Internally, in cases where the quickCheck() method would return "maybe"
286 * (which is only possible for the two COMPOSE modes) this method
287 * resolves to "yes" or "no" to provide a definitive result,
288 * at the cost of doing more work in those cases.
289 * @param norm2 UNormalizer2 instance
290 * @param s input string
291 * @param length length of the string, or -1 if NUL-terminated
292 * @param pErrorCode Standard ICU error code. Its input value must
293 * pass the U_SUCCESS() test, or else the function returns
294 * immediately. Check for U_FAILURE() on output or use with
295 * function chaining. (See User Guide for details.)
296 * @return TRUE if s is normalized
297 * @stable ICU 4.4
298 */
299U_STABLE UBool U_EXPORT2
300unorm2_isNormalized(const UNormalizer2 *norm2,
301 const UChar *s, int32_t length,
302 UErrorCode *pErrorCode);
303
304/**
305 * Tests if the string is normalized.
306 * For the two COMPOSE modes, the result could be "maybe" in cases that
307 * would take a little more work to resolve definitively.
308 * Use spanQuickCheckYes() and normalizeSecondAndAppend() for a faster
309 * combination of quick check + normalization, to avoid
310 * re-checking the "yes" prefix.
311 * @param norm2 UNormalizer2 instance
312 * @param s input string
313 * @param length length of the string, or -1 if NUL-terminated
314 * @param pErrorCode Standard ICU error code. Its input value must
315 * pass the U_SUCCESS() test, or else the function returns
316 * immediately. Check for U_FAILURE() on output or use with
317 * function chaining. (See User Guide for details.)
318 * @return UNormalizationCheckResult
319 * @stable ICU 4.4
320 */
321U_STABLE UNormalizationCheckResult U_EXPORT2
322unorm2_quickCheck(const UNormalizer2 *norm2,
323 const UChar *s, int32_t length,
324 UErrorCode *pErrorCode);
325
326/**
327 * Returns the end of the normalized substring of the input string.
328 * In other words, with <code>end=spanQuickCheckYes(s, ec);</code>
329 * the substring <code>UnicodeString(s, 0, end)</code>
330 * will pass the quick check with a "yes" result.
331 *
332 * The returned end index is usually one or more characters before the
333 * "no" or "maybe" character: The end index is at a normalization boundary.
334 * (See the class documentation for more about normalization boundaries.)
335 *
336 * When the goal is a normalized string and most input strings are expected
337 * to be normalized already, then call this method,
338 * and if it returns a prefix shorter than the input string,
339 * copy that prefix and use normalizeSecondAndAppend() for the remainder.
340 * @param norm2 UNormalizer2 instance
341 * @param s input string
342 * @param length length of the string, or -1 if NUL-terminated
343 * @param pErrorCode Standard ICU error code. Its input value must
344 * pass the U_SUCCESS() test, or else the function returns
345 * immediately. Check for U_FAILURE() on output or use with
346 * function chaining. (See User Guide for details.)
347 * @return "yes" span end index
348 * @stable ICU 4.4
349 */
350U_STABLE int32_t U_EXPORT2
351unorm2_spanQuickCheckYes(const UNormalizer2 *norm2,
352 const UChar *s, int32_t length,
353 UErrorCode *pErrorCode);
354
355/**
356 * Tests if the character always has a normalization boundary before it,
357 * regardless of context.
358 * For details see the Normalizer2 base class documentation.
359 * @param norm2 UNormalizer2 instance
360 * @param c character to test
361 * @return TRUE if c has a normalization boundary before it
362 * @stable ICU 4.4
363 */
364U_STABLE UBool U_EXPORT2
365unorm2_hasBoundaryBefore(const UNormalizer2 *norm2, UChar32 c);
366
367/**
368 * Tests if the character always has a normalization boundary after it,
369 * regardless of context.
370 * For details see the Normalizer2 base class documentation.
371 * @param norm2 UNormalizer2 instance
372 * @param c character to test
373 * @return TRUE if c has a normalization boundary after it
374 * @stable ICU 4.4
375 */
376U_STABLE UBool U_EXPORT2
377unorm2_hasBoundaryAfter(const UNormalizer2 *norm2, UChar32 c);
378
379/**
380 * Tests if the character is normalization-inert.
381 * For details see the Normalizer2 base class documentation.
382 * @param norm2 UNormalizer2 instance
383 * @param c character to test
384 * @return TRUE if c is normalization-inert
385 * @stable ICU 4.4
386 */
387U_STABLE UBool U_EXPORT2
388unorm2_isInert(const UNormalizer2 *norm2, UChar32 c);
389
390#endif /* !UCONFIG_NO_NORMALIZATION */
391#endif /* __UNORM2_H__ */