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