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
35struct 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 */
41typedef 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 */
49enum {
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 "ax",
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 */
156typedef 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 position
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 position
174     * it returned consists only of set elements (characters or strings) that are 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 or strings).
178     * (There must be a single, non-overlapping concatenation of characters or strings.)
179     * This is equivalent to a POSIX regular expression for (OR of each set element)*.
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 position
189     * it returned consists only of set elements (characters or strings) that are 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 (character 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 */
215typedef 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 */
249U_STABLE USet* U_EXPORT2
250uset_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 */
262U_STABLE USet* U_EXPORT2
263uset_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 */
274U_STABLE USet* U_EXPORT2
275uset_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 */
289U_STABLE USet* U_EXPORT2
290uset_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 */
300U_STABLE void U_EXPORT2
301uset_close(USet* set);
302
303#if U_SHOW_CPLUSPLUS_API
304
305U_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 */
316U_DEFINE_LOCAL_OPEN_POINTER(LocalUSetPointer, USet, uset_close);
317
318U_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 */
331U_STABLE USet * U_EXPORT2
332uset_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 */
343U_STABLE UBool U_EXPORT2
344uset_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 */
360U_STABLE void U_EXPORT2
361uset_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 */
373U_STABLE USet * U_EXPORT2
374uset_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 */
385U_STABLE void U_EXPORT2
386uset_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_INSENSITIVE.
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 return value
406 *                          is the index of the error in the source.
407 *
408 * @stable ICU 2.8
409 */
410U_STABLE int32_t U_EXPORT2
411uset_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 */
438U_STABLE void U_EXPORT2
439uset_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 */
477U_STABLE void U_EXPORT2
478uset_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 */
492U_STABLE UBool U_EXPORT2
493uset_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 */
511U_STABLE int32_t U_EXPORT2
512uset_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 */
525U_STABLE void U_EXPORT2
526uset_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 set.
538 * @stable ICU 2.6
539 */
540U_STABLE void U_EXPORT2
541uset_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 */
552U_STABLE void U_EXPORT2
553uset_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 */
564U_STABLE void U_EXPORT2
565uset_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 character.
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 */
576U_STABLE void U_EXPORT2
577uset_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 */
587U_STABLE void U_EXPORT2
588uset_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 */
599U_STABLE void U_EXPORT2
600uset_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 */
611U_STABLE void U_EXPORT2
612uset_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 */
625U_STABLE void U_EXPORT2
626uset_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 */
642U_STABLE void U_EXPORT2
643uset_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 */
657U_STABLE void U_EXPORT2
658uset_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 */
668U_STABLE void U_EXPORT2
669uset_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 */
679U_STABLE void U_EXPORT2
680uset_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 */
693U_STABLE void U_EXPORT2
694uset_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 */
703U_STABLE void U_EXPORT2
704uset_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 */
732U_STABLE void U_EXPORT2
733uset_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 */
741U_STABLE void U_EXPORT2
742uset_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 */
751U_STABLE UBool U_EXPORT2
752uset_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 */
762U_STABLE UBool U_EXPORT2
763uset_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 */
774U_STABLE UBool U_EXPORT2
775uset_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 */
785U_STABLE UBool U_EXPORT2
786uset_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 */
798U_STABLE int32_t U_EXPORT2
799uset_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 */
811U_STABLE UChar32 U_EXPORT2
812uset_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 */
822U_STABLE int32_t U_EXPORT2
823uset_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 */
833U_STABLE int32_t U_EXPORT2
834uset_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 */
854U_STABLE int32_t U_EXPORT2
855uset_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 */
868U_STABLE UBool U_EXPORT2
869uset_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 */
881U_STABLE UBool U_EXPORT2
882uset_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 */
892U_STABLE UBool U_EXPORT2
893uset_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 */
903U_STABLE UBool U_EXPORT2
904uset_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 code points.
915 * This function works faster with a frozen set and with a non-negative string length 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 */
925U_STABLE int32_t U_EXPORT2
926uset_span(const USet *set, const UChar *s, int32_t length, USetSpanCondition spanCondition);
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 code points.
936 * This function works faster with a frozen set and with a non-negative string length 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 spanCondition
943 * @stable ICU 3.8
944 * @see USetSpanCondition
945 */
946U_STABLE int32_t U_EXPORT2
947uset_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 length 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 */
968U_STABLE int32_t U_EXPORT2
969uset_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 length 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 spanCondition
986 * @stable ICU 3.8
987 * @see USetSpanCondition
988 */
989U_STABLE int32_t U_EXPORT2
990uset_spanBackUTF8(const USet *set, const char *s, int32_t length, USetSpanCondition 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 */
1000U_STABLE UBool U_EXPORT2
1001uset_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 */
1056U_STABLE int32_t U_EXPORT2
1057uset_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 */
1067U_STABLE UBool U_EXPORT2
1068uset_getSerializedSet(USerializedSet* fillSet, const uint16_t* src, int32_t srcLength);
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 */
1077U_STABLE void U_EXPORT2
1078uset_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 */
1088U_STABLE UBool U_EXPORT2
1089uset_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 */
1100U_STABLE int32_t U_EXPORT2
1101uset_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 */
1116U_STABLE UBool U_EXPORT2
1117uset_getSerializedRange(const USerializedSet* set, int32_t rangeIndex,
1118                        UChar32* pStart, UChar32* pEnd);
1119
1120#endif
1121