OLD | NEW |
| (Empty) |
1 /* | |
2 ******************************************************************************* | |
3 * | |
4 * Copyright (C) 2002-2010, International Business Machines | |
5 * Corporation and others. All Rights Reserved. | |
6 * | |
7 ******************************************************************************* | |
8 * file name: uset.h | |
9 * encoding: US-ASCII | |
10 * tab size: 8 (not used) | |
11 * indentation:4 | |
12 * | |
13 * created on: 2002mar07 | |
14 * created by: Markus W. Scherer | |
15 * | |
16 * C version of UnicodeSet. | |
17 */ | |
18 | |
19 | |
20 /** | |
21 * \file | |
22 * \brief C API: Unicode Set | |
23 * | |
24 * <p>This is a C wrapper around the C++ UnicodeSet class.</p> | |
25 */ | |
26 | |
27 #ifndef __USET_H__ | |
28 #define __USET_H__ | |
29 | |
30 #include "unicode/utypes.h" | |
31 #include "unicode/uchar.h" | |
32 #include "unicode/localpointer.h" | |
33 | |
34 #ifndef UCNV_H | |
35 struct USet; | |
36 /** | |
37 * A UnicodeSet. Use the uset_* API to manipulate. Create with | |
38 * uset_open*, and destroy with uset_close. | |
39 * @stable ICU 2.4 | |
40 */ | |
41 typedef struct USet USet; | |
42 #endif | |
43 | |
44 /** | |
45 * Bitmask values to be passed to uset_openPatternOptions() or | |
46 * uset_applyPattern() taking an option parameter. | |
47 * @stable ICU 2.4 | |
48 */ | |
49 enum { | |
50 /** | |
51 * Ignore white space within patterns unless quoted or escaped. | |
52 * @stable ICU 2.4 | |
53 */ | |
54 USET_IGNORE_SPACE = 1, | |
55 | |
56 /** | |
57 * Enable case insensitive matching. E.g., "[ab]" with this flag | |
58 * will match 'a', 'A', 'b', and 'B'. "[^ab]" with this flag will | |
59 * match all except 'a', 'A', 'b', and 'B'. This performs a full | |
60 * closure over case mappings, e.g. U+017F for s. | |
61 * | |
62 * The resulting set is a superset of the input for the code points but | |
63 * not for the strings. | |
64 * It performs a case mapping closure of the code points and adds | |
65 * full case folding strings for the code points, and reduces strings of | |
66 * the original set to their full case folding equivalents. | |
67 * | |
68 * This is designed for case-insensitive matches, for example | |
69 * in regular expressions. The full code point case closure allows checking
of | |
70 * an input character directly against the closure set. | |
71 * Strings are matched by comparing the case-folded form from the closure | |
72 * set with an incremental case folding of the string in question. | |
73 * | |
74 * The closure set will also contain single code points if the original | |
75 * set contained case-equivalent strings (like U+00DF for "ss" or "Ss" etc.)
. | |
76 * This is not necessary (that is, redundant) for the above matching method | |
77 * but results in the same closure sets regardless of whether the original | |
78 * set contained the code point or a string. | |
79 * | |
80 * @stable ICU 2.4 | |
81 */ | |
82 USET_CASE_INSENSITIVE = 2, | |
83 | |
84 /** | |
85 * Enable case insensitive matching. E.g., "[ab]" with this flag | |
86 * will match 'a', 'A', 'b', and 'B'. "[^ab]" with this flag will | |
87 * match all except 'a', 'A', 'b', and 'B'. This adds the lower-, | |
88 * title-, and uppercase mappings as well as the case folding | |
89 * of each existing element in the set. | |
90 * @stable ICU 3.2 | |
91 */ | |
92 USET_ADD_CASE_MAPPINGS = 4, | |
93 | |
94 /** | |
95 * Enough for any single-code point set | |
96 * @internal | |
97 */ | |
98 USET_SERIALIZED_STATIC_ARRAY_CAPACITY=8 | |
99 }; | |
100 | |
101 /** | |
102 * Argument values for whether span() and similar functions continue while | |
103 * the current character is contained vs. not contained in the set. | |
104 * | |
105 * The functionality is straightforward for sets with only single code points, | |
106 * without strings (which is the common case): | |
107 * - USET_SPAN_CONTAINED and USET_SPAN_SIMPLE | |
108 * work the same. | |
109 * - span() and spanBack() partition any string the same way when | |
110 * alternating between span(USET_SPAN_NOT_CONTAINED) and | |
111 * span(either "contained" condition). | |
112 * - Using a complemented (inverted) set and the opposite span conditions | |
113 * yields the same results. | |
114 * | |
115 * When a set contains multi-code point strings, then these statements may not | |
116 * be true, depending on the strings in the set (for example, whether they | |
117 * overlap with each other) and the string that is processed. | |
118 * For a set with strings: | |
119 * - The complement of the set contains the opposite set of code points, | |
120 * but the same set of strings. | |
121 * Therefore, complementing both the set and the span conditions | |
122 * may yield different results. | |
123 * - When starting spans at different positions in a string | |
124 * (span(s, ...) vs. span(s+1, ...)) the ends of the spans may be different | |
125 * because a set string may start before the later position. | |
126 * - span(USET_SPAN_SIMPLE) may be shorter than | |
127 * span(USET_SPAN_CONTAINED) because it will not recursively try | |
128 * all possible paths. | |
129 * For example, with a set which contains the three strings "xy", "xya" and "a
x", | |
130 * span("xyax", USET_SPAN_CONTAINED) will return 4 but | |
131 * span("xyax", USET_SPAN_SIMPLE) will return 3. | |
132 * span(USET_SPAN_SIMPLE) will never be longer than | |
133 * span(USET_SPAN_CONTAINED). | |
134 * - With either "contained" condition, span() and spanBack() may partition | |
135 * a string in different ways. | |
136 * For example, with a set which contains the two strings "ab" and "ba", | |
137 * and when processing the string "aba", | |
138 * span() will yield contained/not-contained boundaries of { 0, 2, 3 } | |
139 * while spanBack() will yield boundaries of { 0, 1, 3 }. | |
140 * | |
141 * Note: If it is important to get the same boundaries whether iterating forward | |
142 * or backward through a string, then either only span() should be used and | |
143 * the boundaries cached for backward operation, or an ICU BreakIterator | |
144 * could be used. | |
145 * | |
146 * Note: Unpaired surrogates are treated like surrogate code points. | |
147 * Similarly, set strings match only on code point boundaries, | |
148 * never in the middle of a surrogate pair. | |
149 * Illegal UTF-8 sequences are treated like U+FFFD. | |
150 * When processing UTF-8 strings, malformed set strings | |
151 * (strings with unpaired surrogates which cannot be converted to UTF-8) | |
152 * are ignored. | |
153 * | |
154 * @stable ICU 3.8 | |
155 */ | |
156 typedef enum USetSpanCondition { | |
157 /** | |
158 * Continue a span() while there is no set element at the current position. | |
159 * Stops before the first set element (character or string). | |
160 * (For code points only, this is like while contains(current)==FALSE). | |
161 * | |
162 * When span() returns, the substring between where it started and the posit
ion | |
163 * it returned consists only of characters that are not in the set, | |
164 * and none of its strings overlap with the span. | |
165 * | |
166 * @stable ICU 3.8 | |
167 */ | |
168 USET_SPAN_NOT_CONTAINED = 0, | |
169 /** | |
170 * Continue a span() while there is a set element at the current position. | |
171 * (For characters only, this is like while contains(current)==TRUE). | |
172 * | |
173 * When span() returns, the substring between where it started and the posit
ion | |
174 * it returned consists only of set elements (characters or strings) that ar
e in the set. | |
175 * | |
176 * If a set contains strings, then the span will be the longest substring | |
177 * matching any of the possible concatenations of set elements (characters o
r strings). | |
178 * (There must be a single, non-overlapping concatenation of characters or s
trings.) | |
179 * This is equivalent to a POSIX regular expression for (OR of each set elem
ent)*. | |
180 * | |
181 * @stable ICU 3.8 | |
182 */ | |
183 USET_SPAN_CONTAINED = 1, | |
184 /** | |
185 * Continue a span() while there is a set element at the current position. | |
186 * (For characters only, this is like while contains(current)==TRUE). | |
187 * | |
188 * When span() returns, the substring between where it started and the posit
ion | |
189 * it returned consists only of set elements (characters or strings) that ar
e in the set. | |
190 * | |
191 * If a set only contains single characters, then this is the same | |
192 * as USET_SPAN_CONTAINED. | |
193 * | |
194 * If a set contains strings, then the span will be the longest substring | |
195 * with a match at each position with the longest single set element (charac
ter or string). | |
196 * | |
197 * Use this span condition together with other longest-match algorithms, | |
198 * such as ICU converters (ucnv_getUnicodeSet()). | |
199 * | |
200 * @stable ICU 3.8 | |
201 */ | |
202 USET_SPAN_SIMPLE = 2, | |
203 /** | |
204 * One more than the last span condition. | |
205 * @stable ICU 3.8 | |
206 */ | |
207 USET_SPAN_CONDITION_COUNT | |
208 } USetSpanCondition; | |
209 | |
210 /** | |
211 * A serialized form of a Unicode set. Limited manipulations are | |
212 * possible directly on a serialized set. See below. | |
213 * @stable ICU 2.4 | |
214 */ | |
215 typedef struct USerializedSet { | |
216 /** | |
217 * The serialized Unicode Set. | |
218 * @stable ICU 2.4 | |
219 */ | |
220 const uint16_t *array; | |
221 /** | |
222 * The length of the array that contains BMP characters. | |
223 * @stable ICU 2.4 | |
224 */ | |
225 int32_t bmpLength; | |
226 /** | |
227 * The total length of the array. | |
228 * @stable ICU 2.4 | |
229 */ | |
230 int32_t length; | |
231 /** | |
232 * A small buffer for the array to reduce memory allocations. | |
233 * @stable ICU 2.4 | |
234 */ | |
235 uint16_t staticArray[USET_SERIALIZED_STATIC_ARRAY_CAPACITY]; | |
236 } USerializedSet; | |
237 | |
238 /********************************************************************* | |
239 * USet API | |
240 *********************************************************************/ | |
241 | |
242 /** | |
243 * Create an empty USet object. | |
244 * Equivalent to uset_open(1, 0). | |
245 * @return a newly created USet. The caller must call uset_close() on | |
246 * it when done. | |
247 * @stable ICU 4.2 | |
248 */ | |
249 U_STABLE USet* U_EXPORT2 | |
250 uset_openEmpty(); | |
251 | |
252 /** | |
253 * Creates a USet object that contains the range of characters | |
254 * start..end, inclusive. If <code>start > end</code> | |
255 * then an empty set is created (same as using uset_openEmpty()). | |
256 * @param start first character of the range, inclusive | |
257 * @param end last character of the range, inclusive | |
258 * @return a newly created USet. The caller must call uset_close() on | |
259 * it when done. | |
260 * @stable ICU 2.4 | |
261 */ | |
262 U_STABLE USet* U_EXPORT2 | |
263 uset_open(UChar32 start, UChar32 end); | |
264 | |
265 /** | |
266 * Creates a set from the given pattern. See the UnicodeSet class | |
267 * description for the syntax of the pattern language. | |
268 * @param pattern a string specifying what characters are in the set | |
269 * @param patternLength the length of the pattern, or -1 if null | |
270 * terminated | |
271 * @param ec the error code | |
272 * @stable ICU 2.4 | |
273 */ | |
274 U_STABLE USet* U_EXPORT2 | |
275 uset_openPattern(const UChar* pattern, int32_t patternLength, | |
276 UErrorCode* ec); | |
277 | |
278 /** | |
279 * Creates a set from the given pattern. See the UnicodeSet class | |
280 * description for the syntax of the pattern language. | |
281 * @param pattern a string specifying what characters are in the set | |
282 * @param patternLength the length of the pattern, or -1 if null | |
283 * terminated | |
284 * @param options bitmask for options to apply to the pattern. | |
285 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE. | |
286 * @param ec the error code | |
287 * @stable ICU 2.4 | |
288 */ | |
289 U_STABLE USet* U_EXPORT2 | |
290 uset_openPatternOptions(const UChar* pattern, int32_t patternLength, | |
291 uint32_t options, | |
292 UErrorCode* ec); | |
293 | |
294 /** | |
295 * Disposes of the storage used by a USet object. This function should | |
296 * be called exactly once for objects returned by uset_open(). | |
297 * @param set the object to dispose of | |
298 * @stable ICU 2.4 | |
299 */ | |
300 U_STABLE void U_EXPORT2 | |
301 uset_close(USet* set); | |
302 | |
303 #if U_SHOW_CPLUSPLUS_API | |
304 | |
305 U_NAMESPACE_BEGIN | |
306 | |
307 /** | |
308 * \class LocalUSetPointer | |
309 * "Smart pointer" class, closes a USet via uset_close(). | |
310 * For most methods see the LocalPointerBase base class. | |
311 * | |
312 * @see LocalPointerBase | |
313 * @see LocalPointer | |
314 * @stable ICU 4.4 | |
315 */ | |
316 U_DEFINE_LOCAL_OPEN_POINTER(LocalUSetPointer, USet, uset_close); | |
317 | |
318 U_NAMESPACE_END | |
319 | |
320 #endif | |
321 | |
322 /** | |
323 * Returns a copy of this object. | |
324 * If this set is frozen, then the clone will be frozen as well. | |
325 * Use uset_cloneAsThawed() for a mutable clone of a frozen set. | |
326 * @param set the original set | |
327 * @return the newly allocated copy of the set | |
328 * @see uset_cloneAsThawed | |
329 * @stable ICU 3.8 | |
330 */ | |
331 U_STABLE USet * U_EXPORT2 | |
332 uset_clone(const USet *set); | |
333 | |
334 /** | |
335 * Determines whether the set has been frozen (made immutable) or not. | |
336 * See the ICU4J Freezable interface for details. | |
337 * @param set the set | |
338 * @return TRUE/FALSE for whether the set has been frozen | |
339 * @see uset_freeze | |
340 * @see uset_cloneAsThawed | |
341 * @stable ICU 3.8 | |
342 */ | |
343 U_STABLE UBool U_EXPORT2 | |
344 uset_isFrozen(const USet *set); | |
345 | |
346 /** | |
347 * Freeze the set (make it immutable). | |
348 * Once frozen, it cannot be unfrozen and is therefore thread-safe | |
349 * until it is deleted. | |
350 * See the ICU4J Freezable interface for details. | |
351 * Freezing the set may also make some operations faster, for example | |
352 * uset_contains() and uset_span(). | |
353 * A frozen set will not be modified. (It remains frozen.) | |
354 * @param set the set | |
355 * @return the same set, now frozen | |
356 * @see uset_isFrozen | |
357 * @see uset_cloneAsThawed | |
358 * @stable ICU 3.8 | |
359 */ | |
360 U_STABLE void U_EXPORT2 | |
361 uset_freeze(USet *set); | |
362 | |
363 /** | |
364 * Clone the set and make the clone mutable. | |
365 * See the ICU4J Freezable interface for details. | |
366 * @param set the set | |
367 * @return the mutable clone | |
368 * @see uset_freeze | |
369 * @see uset_isFrozen | |
370 * @see uset_clone | |
371 * @stable ICU 3.8 | |
372 */ | |
373 U_STABLE USet * U_EXPORT2 | |
374 uset_cloneAsThawed(const USet *set); | |
375 | |
376 /** | |
377 * Causes the USet object to represent the range <code>start - end</code>. | |
378 * If <code>start > end</code> then this USet is set to an empty range. | |
379 * A frozen set will not be modified. | |
380 * @param set the object to set to the given range | |
381 * @param start first character in the set, inclusive | |
382 * @param end last character in the set, inclusive | |
383 * @stable ICU 3.2 | |
384 */ | |
385 U_STABLE void U_EXPORT2 | |
386 uset_set(USet* set, | |
387 UChar32 start, UChar32 end); | |
388 | |
389 /** | |
390 * Modifies the set to represent the set specified by the given | |
391 * pattern. See the UnicodeSet class description for the syntax of | |
392 * the pattern language. See also the User Guide chapter about UnicodeSet. | |
393 * <em>Empties the set passed before applying the pattern.</em> | |
394 * A frozen set will not be modified. | |
395 * @param set The set to which the pattern is to be applied. | |
396 * @param pattern A pointer to UChar string specifying what characters
are in the set. | |
397 * The character at pattern[0] must be a '['. | |
398 * @param patternLength The length of the UChar string. -1 if NUL terminated
. | |
399 * @param options A bitmask for options to apply to the pattern. | |
400 * Valid options are USET_IGNORE_SPACE and USET_CASE_IN
SENSITIVE. | |
401 * @param status Returns an error if the pattern cannot be parsed. | |
402 * @return Upon successful parse, the value is either | |
403 * the index of the character after the closing ']' | |
404 * of the parsed pattern. | |
405 * If the status code indicates failure, then the retur
n value | |
406 * is the index of the error in the source. | |
407 * | |
408 * @stable ICU 2.8 | |
409 */ | |
410 U_STABLE int32_t U_EXPORT2 | |
411 uset_applyPattern(USet *set, | |
412 const UChar *pattern, int32_t patternLength, | |
413 uint32_t options, | |
414 UErrorCode *status); | |
415 | |
416 /** | |
417 * Modifies the set to contain those code points which have the given value | |
418 * for the given binary or enumerated property, as returned by | |
419 * u_getIntPropertyValue. Prior contents of this set are lost. | |
420 * A frozen set will not be modified. | |
421 * | |
422 * @param set the object to contain the code points defined by the property | |
423 * | |
424 * @param prop a property in the range UCHAR_BIN_START..UCHAR_BIN_LIMIT-1 | |
425 * or UCHAR_INT_START..UCHAR_INT_LIMIT-1 | |
426 * or UCHAR_MASK_START..UCHAR_MASK_LIMIT-1. | |
427 * | |
428 * @param value a value in the range u_getIntPropertyMinValue(prop).. | |
429 * u_getIntPropertyMaxValue(prop), with one exception. If prop is | |
430 * UCHAR_GENERAL_CATEGORY_MASK, then value should not be a UCharCategory, but | |
431 * rather a mask value produced by U_GET_GC_MASK(). This allows grouped | |
432 * categories such as [:L:] to be represented. | |
433 * | |
434 * @param ec error code input/output parameter | |
435 * | |
436 * @stable ICU 3.2 | |
437 */ | |
438 U_STABLE void U_EXPORT2 | |
439 uset_applyIntPropertyValue(USet* set, | |
440 UProperty prop, int32_t value, UErrorCode* ec); | |
441 | |
442 /** | |
443 * Modifies the set to contain those code points which have the | |
444 * given value for the given property. Prior contents of this | |
445 * set are lost. | |
446 * A frozen set will not be modified. | |
447 * | |
448 * @param set the object to contain the code points defined by the given | |
449 * property and value alias | |
450 * | |
451 * @param prop a string specifying a property alias, either short or long. | |
452 * The name is matched loosely. See PropertyAliases.txt for names and a | |
453 * description of loose matching. If the value string is empty, then this | |
454 * string is interpreted as either a General_Category value alias, a Script | |
455 * value alias, a binary property alias, or a special ID. Special IDs are | |
456 * matched loosely and correspond to the following sets: | |
457 * | |
458 * "ANY" = [\\u0000-\\U0010FFFF], | |
459 * "ASCII" = [\\u0000-\\u007F], | |
460 * "Assigned" = [:^Cn:]. | |
461 * | |
462 * @param propLength the length of the prop, or -1 if NULL | |
463 * | |
464 * @param value a string specifying a value alias, either short or long. | |
465 * The name is matched loosely. See PropertyValueAliases.txt for names | |
466 * and a description of loose matching. In addition to aliases listed, | |
467 * numeric values and canonical combining classes may be expressed | |
468 * numerically, e.g., ("nv", "0.5") or ("ccc", "220"). The value string | |
469 * may also be empty. | |
470 * | |
471 * @param valueLength the length of the value, or -1 if NULL | |
472 * | |
473 * @param ec error code input/output parameter | |
474 * | |
475 * @stable ICU 3.2 | |
476 */ | |
477 U_STABLE void U_EXPORT2 | |
478 uset_applyPropertyAlias(USet* set, | |
479 const UChar *prop, int32_t propLength, | |
480 const UChar *value, int32_t valueLength, | |
481 UErrorCode* ec); | |
482 | |
483 /** | |
484 * Return true if the given position, in the given pattern, appears | |
485 * to be the start of a UnicodeSet pattern. | |
486 * | |
487 * @param pattern a string specifying the pattern | |
488 * @param patternLength the length of the pattern, or -1 if NULL | |
489 * @param pos the given position | |
490 * @stable ICU 3.2 | |
491 */ | |
492 U_STABLE UBool U_EXPORT2 | |
493 uset_resemblesPattern(const UChar *pattern, int32_t patternLength, | |
494 int32_t pos); | |
495 | |
496 /** | |
497 * Returns a string representation of this set. If the result of | |
498 * calling this function is passed to a uset_openPattern(), it | |
499 * will produce another set that is equal to this one. | |
500 * @param set the set | |
501 * @param result the string to receive the rules, may be NULL | |
502 * @param resultCapacity the capacity of result, may be 0 if result is NULL | |
503 * @param escapeUnprintable if TRUE then convert unprintable | |
504 * character to their hex escape representations, \\uxxxx or | |
505 * \\Uxxxxxxxx. Unprintable characters are those other than | |
506 * U+000A, U+0020..U+007E. | |
507 * @param ec error code. | |
508 * @return length of string, possibly larger than resultCapacity | |
509 * @stable ICU 2.4 | |
510 */ | |
511 U_STABLE int32_t U_EXPORT2 | |
512 uset_toPattern(const USet* set, | |
513 UChar* result, int32_t resultCapacity, | |
514 UBool escapeUnprintable, | |
515 UErrorCode* ec); | |
516 | |
517 /** | |
518 * Adds the given character to the given USet. After this call, | |
519 * uset_contains(set, c) will return TRUE. | |
520 * A frozen set will not be modified. | |
521 * @param set the object to which to add the character | |
522 * @param c the character to add | |
523 * @stable ICU 2.4 | |
524 */ | |
525 U_STABLE void U_EXPORT2 | |
526 uset_add(USet* set, UChar32 c); | |
527 | |
528 /** | |
529 * Adds all of the elements in the specified set to this set if | |
530 * they're not already present. This operation effectively | |
531 * modifies this set so that its value is the <i>union</i> of the two | |
532 * sets. The behavior of this operation is unspecified if the specified | |
533 * collection is modified while the operation is in progress. | |
534 * A frozen set will not be modified. | |
535 * | |
536 * @param set the object to which to add the set | |
537 * @param additionalSet the source set whose elements are to be added to this se
t. | |
538 * @stable ICU 2.6 | |
539 */ | |
540 U_STABLE void U_EXPORT2 | |
541 uset_addAll(USet* set, const USet *additionalSet); | |
542 | |
543 /** | |
544 * Adds the given range of characters to the given USet. After this call, | |
545 * uset_contains(set, start, end) will return TRUE. | |
546 * A frozen set will not be modified. | |
547 * @param set the object to which to add the character | |
548 * @param start the first character of the range to add, inclusive | |
549 * @param end the last character of the range to add, inclusive | |
550 * @stable ICU 2.2 | |
551 */ | |
552 U_STABLE void U_EXPORT2 | |
553 uset_addRange(USet* set, UChar32 start, UChar32 end); | |
554 | |
555 /** | |
556 * Adds the given string to the given USet. After this call, | |
557 * uset_containsString(set, str, strLen) will return TRUE. | |
558 * A frozen set will not be modified. | |
559 * @param set the object to which to add the character | |
560 * @param str the string to add | |
561 * @param strLen the length of the string or -1 if null terminated. | |
562 * @stable ICU 2.4 | |
563 */ | |
564 U_STABLE void U_EXPORT2 | |
565 uset_addString(USet* set, const UChar* str, int32_t strLen); | |
566 | |
567 /** | |
568 * Adds each of the characters in this string to the set. Thus "ch" => {"c", "h"
} | |
569 * If this set already any particular character, it has no effect on that charac
ter. | |
570 * A frozen set will not be modified. | |
571 * @param set the object to which to add the character | |
572 * @param str the source string | |
573 * @param strLen the length of the string or -1 if null terminated. | |
574 * @stable ICU 3.4 | |
575 */ | |
576 U_STABLE void U_EXPORT2 | |
577 uset_addAllCodePoints(USet* set, const UChar *str, int32_t strLen); | |
578 | |
579 /** | |
580 * Removes the given character from the given USet. After this call, | |
581 * uset_contains(set, c) will return FALSE. | |
582 * A frozen set will not be modified. | |
583 * @param set the object from which to remove the character | |
584 * @param c the character to remove | |
585 * @stable ICU 2.4 | |
586 */ | |
587 U_STABLE void U_EXPORT2 | |
588 uset_remove(USet* set, UChar32 c); | |
589 | |
590 /** | |
591 * Removes the given range of characters from the given USet. After this call, | |
592 * uset_contains(set, start, end) will return FALSE. | |
593 * A frozen set will not be modified. | |
594 * @param set the object to which to add the character | |
595 * @param start the first character of the range to remove, inclusive | |
596 * @param end the last character of the range to remove, inclusive | |
597 * @stable ICU 2.2 | |
598 */ | |
599 U_STABLE void U_EXPORT2 | |
600 uset_removeRange(USet* set, UChar32 start, UChar32 end); | |
601 | |
602 /** | |
603 * Removes the given string to the given USet. After this call, | |
604 * uset_containsString(set, str, strLen) will return FALSE. | |
605 * A frozen set will not be modified. | |
606 * @param set the object to which to add the character | |
607 * @param str the string to remove | |
608 * @param strLen the length of the string or -1 if null terminated. | |
609 * @stable ICU 2.4 | |
610 */ | |
611 U_STABLE void U_EXPORT2 | |
612 uset_removeString(USet* set, const UChar* str, int32_t strLen); | |
613 | |
614 /** | |
615 * Removes from this set all of its elements that are contained in the | |
616 * specified set. This operation effectively modifies this | |
617 * set so that its value is the <i>asymmetric set difference</i> of | |
618 * the two sets. | |
619 * A frozen set will not be modified. | |
620 * @param set the object from which the elements are to be removed | |
621 * @param removeSet the object that defines which elements will be | |
622 * removed from this set | |
623 * @stable ICU 3.2 | |
624 */ | |
625 U_STABLE void U_EXPORT2 | |
626 uset_removeAll(USet* set, const USet* removeSet); | |
627 | |
628 /** | |
629 * Retain only the elements in this set that are contained in the | |
630 * specified range. If <code>start > end</code> then an empty range is | |
631 * retained, leaving the set empty. This is equivalent to | |
632 * a boolean logic AND, or a set INTERSECTION. | |
633 * A frozen set will not be modified. | |
634 * | |
635 * @param set the object for which to retain only the specified range | |
636 * @param start first character, inclusive, of range to be retained | |
637 * to this set. | |
638 * @param end last character, inclusive, of range to be retained | |
639 * to this set. | |
640 * @stable ICU 3.2 | |
641 */ | |
642 U_STABLE void U_EXPORT2 | |
643 uset_retain(USet* set, UChar32 start, UChar32 end); | |
644 | |
645 /** | |
646 * Retains only the elements in this set that are contained in the | |
647 * specified set. In other words, removes from this set all of | |
648 * its elements that are not contained in the specified set. This | |
649 * operation effectively modifies this set so that its value is | |
650 * the <i>intersection</i> of the two sets. | |
651 * A frozen set will not be modified. | |
652 * | |
653 * @param set the object on which to perform the retain | |
654 * @param retain set that defines which elements this set will retain | |
655 * @stable ICU 3.2 | |
656 */ | |
657 U_STABLE void U_EXPORT2 | |
658 uset_retainAll(USet* set, const USet* retain); | |
659 | |
660 /** | |
661 * Reallocate this objects internal structures to take up the least | |
662 * possible space, without changing this object's value. | |
663 * A frozen set will not be modified. | |
664 * | |
665 * @param set the object on which to perfrom the compact | |
666 * @stable ICU 3.2 | |
667 */ | |
668 U_STABLE void U_EXPORT2 | |
669 uset_compact(USet* set); | |
670 | |
671 /** | |
672 * Inverts this set. This operation modifies this set so that | |
673 * its value is its complement. This operation does not affect | |
674 * the multicharacter strings, if any. | |
675 * A frozen set will not be modified. | |
676 * @param set the set | |
677 * @stable ICU 2.4 | |
678 */ | |
679 U_STABLE void U_EXPORT2 | |
680 uset_complement(USet* set); | |
681 | |
682 /** | |
683 * Complements in this set all elements contained in the specified | |
684 * set. Any character in the other set will be removed if it is | |
685 * in this set, or will be added if it is not in this set. | |
686 * A frozen set will not be modified. | |
687 * | |
688 * @param set the set with which to complement | |
689 * @param complement set that defines which elements will be xor'ed | |
690 * from this set. | |
691 * @stable ICU 3.2 | |
692 */ | |
693 U_STABLE void U_EXPORT2 | |
694 uset_complementAll(USet* set, const USet* complement); | |
695 | |
696 /** | |
697 * Removes all of the elements from this set. This set will be | |
698 * empty after this call returns. | |
699 * A frozen set will not be modified. | |
700 * @param set the set | |
701 * @stable ICU 2.4 | |
702 */ | |
703 U_STABLE void U_EXPORT2 | |
704 uset_clear(USet* set); | |
705 | |
706 /** | |
707 * Close this set over the given attribute. For the attribute | |
708 * USET_CASE, the result is to modify this set so that: | |
709 * | |
710 * 1. For each character or string 'a' in this set, all strings or | |
711 * characters 'b' such that foldCase(a) == foldCase(b) are added | |
712 * to this set. | |
713 * | |
714 * 2. For each string 'e' in the resulting set, if e != | |
715 * foldCase(e), 'e' will be removed. | |
716 * | |
717 * Example: [aq\\u00DF{Bc}{bC}{Fi}] => [aAqQ\\u00DF\\uFB01{ss}{bc}{fi}] | |
718 * | |
719 * (Here foldCase(x) refers to the operation u_strFoldCase, and a | |
720 * == b denotes that the contents are the same, not pointer | |
721 * comparison.) | |
722 * | |
723 * A frozen set will not be modified. | |
724 * | |
725 * @param set the set | |
726 * | |
727 * @param attributes bitmask for attributes to close over. | |
728 * Currently only the USET_CASE bit is supported. Any undefined bits | |
729 * are ignored. | |
730 * @stable ICU 4.2 | |
731 */ | |
732 U_STABLE void U_EXPORT2 | |
733 uset_closeOver(USet* set, int32_t attributes); | |
734 | |
735 /** | |
736 * Remove all strings from this set. | |
737 * | |
738 * @param set the set | |
739 * @stable ICU 4.2 | |
740 */ | |
741 U_STABLE void U_EXPORT2 | |
742 uset_removeAllStrings(USet* set); | |
743 | |
744 /** | |
745 * Returns TRUE if the given USet contains no characters and no | |
746 * strings. | |
747 * @param set the set | |
748 * @return true if set is empty | |
749 * @stable ICU 2.4 | |
750 */ | |
751 U_STABLE UBool U_EXPORT2 | |
752 uset_isEmpty(const USet* set); | |
753 | |
754 /** | |
755 * Returns TRUE if the given USet contains the given character. | |
756 * This function works faster with a frozen set. | |
757 * @param set the set | |
758 * @param c The codepoint to check for within the set | |
759 * @return true if set contains c | |
760 * @stable ICU 2.4 | |
761 */ | |
762 U_STABLE UBool U_EXPORT2 | |
763 uset_contains(const USet* set, UChar32 c); | |
764 | |
765 /** | |
766 * Returns TRUE if the given USet contains all characters c | |
767 * where start <= c && c <= end. | |
768 * @param set the set | |
769 * @param start the first character of the range to test, inclusive | |
770 * @param end the last character of the range to test, inclusive | |
771 * @return TRUE if set contains the range | |
772 * @stable ICU 2.2 | |
773 */ | |
774 U_STABLE UBool U_EXPORT2 | |
775 uset_containsRange(const USet* set, UChar32 start, UChar32 end); | |
776 | |
777 /** | |
778 * Returns TRUE if the given USet contains the given string. | |
779 * @param set the set | |
780 * @param str the string | |
781 * @param strLen the length of the string or -1 if null terminated. | |
782 * @return true if set contains str | |
783 * @stable ICU 2.4 | |
784 */ | |
785 U_STABLE UBool U_EXPORT2 | |
786 uset_containsString(const USet* set, const UChar* str, int32_t strLen); | |
787 | |
788 /** | |
789 * Returns the index of the given character within this set, where | |
790 * the set is ordered by ascending code point. If the character | |
791 * is not in this set, return -1. The inverse of this method is | |
792 * <code>charAt()</code>. | |
793 * @param set the set | |
794 * @param c the character to obtain the index for | |
795 * @return an index from 0..size()-1, or -1 | |
796 * @stable ICU 3.2 | |
797 */ | |
798 U_STABLE int32_t U_EXPORT2 | |
799 uset_indexOf(const USet* set, UChar32 c); | |
800 | |
801 /** | |
802 * Returns the character at the given index within this set, where | |
803 * the set is ordered by ascending code point. If the index is | |
804 * out of range, return (UChar32)-1. The inverse of this method is | |
805 * <code>indexOf()</code>. | |
806 * @param set the set | |
807 * @param charIndex an index from 0..size()-1 to obtain the char for | |
808 * @return the character at the given index, or (UChar32)-1. | |
809 * @stable ICU 3.2 | |
810 */ | |
811 U_STABLE UChar32 U_EXPORT2 | |
812 uset_charAt(const USet* set, int32_t charIndex); | |
813 | |
814 /** | |
815 * Returns the number of characters and strings contained in the given | |
816 * USet. | |
817 * @param set the set | |
818 * @return a non-negative integer counting the characters and strings | |
819 * contained in set | |
820 * @stable ICU 2.4 | |
821 */ | |
822 U_STABLE int32_t U_EXPORT2 | |
823 uset_size(const USet* set); | |
824 | |
825 /** | |
826 * Returns the number of items in this set. An item is either a range | |
827 * of characters or a single multicharacter string. | |
828 * @param set the set | |
829 * @return a non-negative integer counting the character ranges | |
830 * and/or strings contained in set | |
831 * @stable ICU 2.4 | |
832 */ | |
833 U_STABLE int32_t U_EXPORT2 | |
834 uset_getItemCount(const USet* set); | |
835 | |
836 /** | |
837 * Returns an item of this set. An item is either a range of | |
838 * characters or a single multicharacter string. | |
839 * @param set the set | |
840 * @param itemIndex a non-negative integer in the range 0.. | |
841 * uset_getItemCount(set)-1 | |
842 * @param start pointer to variable to receive first character | |
843 * in range, inclusive | |
844 * @param end pointer to variable to receive last character in range, | |
845 * inclusive | |
846 * @param str buffer to receive the string, may be NULL | |
847 * @param strCapacity capacity of str, or 0 if str is NULL | |
848 * @param ec error code | |
849 * @return the length of the string (>= 2), or 0 if the item is a | |
850 * range, in which case it is the range *start..*end, or -1 if | |
851 * itemIndex is out of range | |
852 * @stable ICU 2.4 | |
853 */ | |
854 U_STABLE int32_t U_EXPORT2 | |
855 uset_getItem(const USet* set, int32_t itemIndex, | |
856 UChar32* start, UChar32* end, | |
857 UChar* str, int32_t strCapacity, | |
858 UErrorCode* ec); | |
859 | |
860 /** | |
861 * Returns true if set1 contains all the characters and strings | |
862 * of set2. It answers the question, 'Is set1 a superset of set2?' | |
863 * @param set1 set to be checked for containment | |
864 * @param set2 set to be checked for containment | |
865 * @return true if the test condition is met | |
866 * @stable ICU 3.2 | |
867 */ | |
868 U_STABLE UBool U_EXPORT2 | |
869 uset_containsAll(const USet* set1, const USet* set2); | |
870 | |
871 /** | |
872 * Returns true if this set contains all the characters | |
873 * of the given string. This is does not check containment of grapheme | |
874 * clusters, like uset_containsString. | |
875 * @param set set of characters to be checked for containment | |
876 * @param str string containing codepoints to be checked for containment | |
877 * @param strLen the length of the string or -1 if null terminated. | |
878 * @return true if the test condition is met | |
879 * @stable ICU 3.4 | |
880 */ | |
881 U_STABLE UBool U_EXPORT2 | |
882 uset_containsAllCodePoints(const USet* set, const UChar *str, int32_t strLen); | |
883 | |
884 /** | |
885 * Returns true if set1 contains none of the characters and strings | |
886 * of set2. It answers the question, 'Is set1 a disjoint set of set2?' | |
887 * @param set1 set to be checked for containment | |
888 * @param set2 set to be checked for containment | |
889 * @return true if the test condition is met | |
890 * @stable ICU 3.2 | |
891 */ | |
892 U_STABLE UBool U_EXPORT2 | |
893 uset_containsNone(const USet* set1, const USet* set2); | |
894 | |
895 /** | |
896 * Returns true if set1 contains some of the characters and strings | |
897 * of set2. It answers the question, 'Does set1 and set2 have an intersection?' | |
898 * @param set1 set to be checked for containment | |
899 * @param set2 set to be checked for containment | |
900 * @return true if the test condition is met | |
901 * @stable ICU 3.2 | |
902 */ | |
903 U_STABLE UBool U_EXPORT2 | |
904 uset_containsSome(const USet* set1, const USet* set2); | |
905 | |
906 /** | |
907 * Returns the length of the initial substring of the input string which | |
908 * consists only of characters and strings that are contained in this set | |
909 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), | |
910 * or only of characters and strings that are not contained | |
911 * in this set (USET_SPAN_NOT_CONTAINED). | |
912 * See USetSpanCondition for details. | |
913 * Similar to the strspn() C library function. | |
914 * Unpaired surrogates are treated according to contains() of their surrogate co
de points. | |
915 * This function works faster with a frozen set and with a non-negative string l
ength argument. | |
916 * @param set the set | |
917 * @param s start of the string | |
918 * @param length of the string; can be -1 for NUL-terminated | |
919 * @param spanCondition specifies the containment condition | |
920 * @return the length of the initial substring according to the spanCondition; | |
921 * 0 if the start of the string does not fit the spanCondition | |
922 * @stable ICU 3.8 | |
923 * @see USetSpanCondition | |
924 */ | |
925 U_STABLE int32_t U_EXPORT2 | |
926 uset_span(const USet *set, const UChar *s, int32_t length, USetSpanCondition spa
nCondition); | |
927 | |
928 /** | |
929 * Returns the start of the trailing substring of the input string which | |
930 * consists only of characters and strings that are contained in this set | |
931 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), | |
932 * or only of characters and strings that are not contained | |
933 * in this set (USET_SPAN_NOT_CONTAINED). | |
934 * See USetSpanCondition for details. | |
935 * Unpaired surrogates are treated according to contains() of their surrogate co
de points. | |
936 * This function works faster with a frozen set and with a non-negative string l
ength argument. | |
937 * @param set the set | |
938 * @param s start of the string | |
939 * @param length of the string; can be -1 for NUL-terminated | |
940 * @param spanCondition specifies the containment condition | |
941 * @return the start of the trailing substring according to the spanCondition; | |
942 * the string length if the end of the string does not fit the spanCondi
tion | |
943 * @stable ICU 3.8 | |
944 * @see USetSpanCondition | |
945 */ | |
946 U_STABLE int32_t U_EXPORT2 | |
947 uset_spanBack(const USet *set, const UChar *s, int32_t length, USetSpanCondition
spanCondition); | |
948 | |
949 /** | |
950 * Returns the length of the initial substring of the input string which | |
951 * consists only of characters and strings that are contained in this set | |
952 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), | |
953 * or only of characters and strings that are not contained | |
954 * in this set (USET_SPAN_NOT_CONTAINED). | |
955 * See USetSpanCondition for details. | |
956 * Similar to the strspn() C library function. | |
957 * Malformed byte sequences are treated according to contains(0xfffd). | |
958 * This function works faster with a frozen set and with a non-negative string l
ength argument. | |
959 * @param set the set | |
960 * @param s start of the string (UTF-8) | |
961 * @param length of the string; can be -1 for NUL-terminated | |
962 * @param spanCondition specifies the containment condition | |
963 * @return the length of the initial substring according to the spanCondition; | |
964 * 0 if the start of the string does not fit the spanCondition | |
965 * @stable ICU 3.8 | |
966 * @see USetSpanCondition | |
967 */ | |
968 U_STABLE int32_t U_EXPORT2 | |
969 uset_spanUTF8(const USet *set, const char *s, int32_t length, USetSpanCondition
spanCondition); | |
970 | |
971 /** | |
972 * Returns the start of the trailing substring of the input string which | |
973 * consists only of characters and strings that are contained in this set | |
974 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), | |
975 * or only of characters and strings that are not contained | |
976 * in this set (USET_SPAN_NOT_CONTAINED). | |
977 * See USetSpanCondition for details. | |
978 * Malformed byte sequences are treated according to contains(0xfffd). | |
979 * This function works faster with a frozen set and with a non-negative string l
ength argument. | |
980 * @param set the set | |
981 * @param s start of the string (UTF-8) | |
982 * @param length of the string; can be -1 for NUL-terminated | |
983 * @param spanCondition specifies the containment condition | |
984 * @return the start of the trailing substring according to the spanCondition; | |
985 * the string length if the end of the string does not fit the spanCondi
tion | |
986 * @stable ICU 3.8 | |
987 * @see USetSpanCondition | |
988 */ | |
989 U_STABLE int32_t U_EXPORT2 | |
990 uset_spanBackUTF8(const USet *set, const char *s, int32_t length, USetSpanCondit
ion spanCondition); | |
991 | |
992 /** | |
993 * Returns true if set1 contains all of the characters and strings | |
994 * of set2, and vis versa. It answers the question, 'Is set1 equal to set2?' | |
995 * @param set1 set to be checked for containment | |
996 * @param set2 set to be checked for containment | |
997 * @return true if the test condition is met | |
998 * @stable ICU 3.2 | |
999 */ | |
1000 U_STABLE UBool U_EXPORT2 | |
1001 uset_equals(const USet* set1, const USet* set2); | |
1002 | |
1003 /********************************************************************* | |
1004 * Serialized set API | |
1005 *********************************************************************/ | |
1006 | |
1007 /** | |
1008 * Serializes this set into an array of 16-bit integers. Serialization | |
1009 * (currently) only records the characters in the set; multicharacter | |
1010 * strings are ignored. | |
1011 * | |
1012 * The array | |
1013 * has following format (each line is one 16-bit integer): | |
1014 * | |
1015 * length = (n+2*m) | (m!=0?0x8000:0) | |
1016 * bmpLength = n; present if m!=0 | |
1017 * bmp[0] | |
1018 * bmp[1] | |
1019 * ... | |
1020 * bmp[n-1] | |
1021 * supp-high[0] | |
1022 * supp-low[0] | |
1023 * supp-high[1] | |
1024 * supp-low[1] | |
1025 * ... | |
1026 * supp-high[m-1] | |
1027 * supp-low[m-1] | |
1028 * | |
1029 * The array starts with a header. After the header are n bmp | |
1030 * code points, then m supplementary code points. Either n or m | |
1031 * or both may be zero. n+2*m is always <= 0x7FFF. | |
1032 * | |
1033 * If there are no supplementary characters (if m==0) then the | |
1034 * header is one 16-bit integer, 'length', with value n. | |
1035 * | |
1036 * If there are supplementary characters (if m!=0) then the header | |
1037 * is two 16-bit integers. The first, 'length', has value | |
1038 * (n+2*m)|0x8000. The second, 'bmpLength', has value n. | |
1039 * | |
1040 * After the header the code points are stored in ascending order. | |
1041 * Supplementary code points are stored as most significant 16 | |
1042 * bits followed by least significant 16 bits. | |
1043 * | |
1044 * @param set the set | |
1045 * @param dest pointer to buffer of destCapacity 16-bit integers. | |
1046 * May be NULL only if destCapacity is zero. | |
1047 * @param destCapacity size of dest, or zero. Must not be negative. | |
1048 * @param pErrorCode pointer to the error code. Will be set to | |
1049 * U_INDEX_OUTOFBOUNDS_ERROR if n+2*m > 0x7FFF. Will be set to | |
1050 * U_BUFFER_OVERFLOW_ERROR if n+2*m+(m!=0?2:1) > destCapacity. | |
1051 * @return the total length of the serialized format, including | |
1052 * the header, that is, n+2*m+(m!=0?2:1), or 0 on error other | |
1053 * than U_BUFFER_OVERFLOW_ERROR. | |
1054 * @stable ICU 2.4 | |
1055 */ | |
1056 U_STABLE int32_t U_EXPORT2 | |
1057 uset_serialize(const USet* set, uint16_t* dest, int32_t destCapacity, UErrorCode
* pErrorCode); | |
1058 | |
1059 /** | |
1060 * Given a serialized array, fill in the given serialized set object. | |
1061 * @param fillSet pointer to result | |
1062 * @param src pointer to start of array | |
1063 * @param srcLength length of array | |
1064 * @return true if the given array is valid, otherwise false | |
1065 * @stable ICU 2.4 | |
1066 */ | |
1067 U_STABLE UBool U_EXPORT2 | |
1068 uset_getSerializedSet(USerializedSet* fillSet, const uint16_t* src, int32_t srcL
ength); | |
1069 | |
1070 /** | |
1071 * Set the USerializedSet to contain the given character (and nothing | |
1072 * else). | |
1073 * @param fillSet pointer to result | |
1074 * @param c The codepoint to set | |
1075 * @stable ICU 2.4 | |
1076 */ | |
1077 U_STABLE void U_EXPORT2 | |
1078 uset_setSerializedToOne(USerializedSet* fillSet, UChar32 c); | |
1079 | |
1080 /** | |
1081 * Returns TRUE if the given USerializedSet contains the given | |
1082 * character. | |
1083 * @param set the serialized set | |
1084 * @param c The codepoint to check for within the set | |
1085 * @return true if set contains c | |
1086 * @stable ICU 2.4 | |
1087 */ | |
1088 U_STABLE UBool U_EXPORT2 | |
1089 uset_serializedContains(const USerializedSet* set, UChar32 c); | |
1090 | |
1091 /** | |
1092 * Returns the number of disjoint ranges of characters contained in | |
1093 * the given serialized set. Ignores any strings contained in the | |
1094 * set. | |
1095 * @param set the serialized set | |
1096 * @return a non-negative integer counting the character ranges | |
1097 * contained in set | |
1098 * @stable ICU 2.4 | |
1099 */ | |
1100 U_STABLE int32_t U_EXPORT2 | |
1101 uset_getSerializedRangeCount(const USerializedSet* set); | |
1102 | |
1103 /** | |
1104 * Returns a range of characters contained in the given serialized | |
1105 * set. | |
1106 * @param set the serialized set | |
1107 * @param rangeIndex a non-negative integer in the range 0.. | |
1108 * uset_getSerializedRangeCount(set)-1 | |
1109 * @param pStart pointer to variable to receive first character | |
1110 * in range, inclusive | |
1111 * @param pEnd pointer to variable to receive last character in range, | |
1112 * inclusive | |
1113 * @return true if rangeIndex is valid, otherwise false | |
1114 * @stable ICU 2.4 | |
1115 */ | |
1116 U_STABLE UBool U_EXPORT2 | |
1117 uset_getSerializedRange(const USerializedSet* set, int32_t rangeIndex, | |
1118 UChar32* pStart, UChar32* pEnd); | |
1119 | |
1120 #endif | |
OLD | NEW |