]> git.saurik.com Git - apple/icu.git/blob - icuSources/common/unicode/uset.h
ICU-8.11.2.tar.gz
[apple/icu.git] / icuSources / common / unicode / uset.h
1 /*
2 *******************************************************************************
3 *
4 * Copyright (C) 2002-2006, 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
33 #ifndef UCNV_H
34 struct USet;
35 /**
36 * A UnicodeSet. Use the uset_* API to manipulate. Create with
37 * uset_open*, and destroy with uset_close.
38 * @stable ICU 2.4
39 */
40 typedef struct USet USet;
41 #endif
42
43 /**
44 * Bitmask values to be passed to uset_openPatternOptions() or
45 * uset_applyPattern() taking an option parameter.
46 * @stable ICU 2.4
47 */
48 enum {
49 /**
50 * Ignore white space within patterns unless quoted or escaped.
51 * @stable ICU 2.4
52 */
53 USET_IGNORE_SPACE = 1,
54
55 /**
56 * Enable case insensitive matching. E.g., "[ab]" with this flag
57 * will match 'a', 'A', 'b', and 'B'. "[^ab]" with this flag will
58 * match all except 'a', 'A', 'b', and 'B'. This performs a full
59 * closure over case mappings, e.g. U+017F for s.
60 *
61 * The resulting set is a superset of the input for the code points but
62 * not for the strings.
63 * It performs a case mapping closure of the code points and adds
64 * full case folding strings for the code points, and reduces strings of
65 * the original set to their full case folding equivalents.
66 *
67 * This is designed for case-insensitive matches, for example
68 * in regular expressions. The full code point case closure allows checking of
69 * an input character directly against the closure set.
70 * Strings are matched by comparing the case-folded form from the closure
71 * set with an incremental case folding of the string in question.
72 *
73 * The closure set will also contain single code points if the original
74 * set contained case-equivalent strings (like U+00DF for "ss" or "Ss" etc.).
75 * This is not necessary (that is, redundant) for the above matching method
76 * but results in the same closure sets regardless of whether the original
77 * set contained the code point or a string.
78 *
79 * @stable ICU 2.4
80 */
81 USET_CASE_INSENSITIVE = 2,
82
83 /**
84 * Enable case insensitive matching. E.g., "[ab]" with this flag
85 * will match 'a', 'A', 'b', and 'B'. "[^ab]" with this flag will
86 * match all except 'a', 'A', 'b', and 'B'. This adds the lower-,
87 * title-, and uppercase mappings as well as the case folding
88 * of each existing element in the set.
89 * @stable ICU 3.2
90 */
91 USET_ADD_CASE_MAPPINGS = 4,
92
93 /**
94 * Enough for any single-code point set
95 * @internal
96 */
97 USET_SERIALIZED_STATIC_ARRAY_CAPACITY=8
98 };
99
100 /**
101 * A serialized form of a Unicode set. Limited manipulations are
102 * possible directly on a serialized set. See below.
103 * @stable ICU 2.4
104 */
105 typedef struct USerializedSet {
106 /**
107 * The serialized Unicode Set.
108 * @stable ICU 2.4
109 */
110 const uint16_t *array;
111 /**
112 * The length of the array that contains BMP characters.
113 * @stable ICU 2.4
114 */
115 int32_t bmpLength;
116 /**
117 * The total length of the array.
118 * @stable ICU 2.4
119 */
120 int32_t length;
121 /**
122 * A small buffer for the array to reduce memory allocations.
123 * @stable ICU 2.4
124 */
125 uint16_t staticArray[USET_SERIALIZED_STATIC_ARRAY_CAPACITY];
126 } USerializedSet;
127
128 /*********************************************************************
129 * USet API
130 *********************************************************************/
131
132 /**
133 * Creates a USet object that contains the range of characters
134 * start..end, inclusive.
135 * @param start first character of the range, inclusive
136 * @param end last character of the range, inclusive
137 * @return a newly created USet. The caller must call uset_close() on
138 * it when done.
139 * @stable ICU 2.4
140 */
141 U_STABLE USet* U_EXPORT2
142 uset_open(UChar32 start, UChar32 end);
143
144 /**
145 * Creates a set from the given pattern. See the UnicodeSet class
146 * description for the syntax of the pattern language.
147 * @param pattern a string specifying what characters are in the set
148 * @param patternLength the length of the pattern, or -1 if null
149 * terminated
150 * @param ec the error code
151 * @stable ICU 2.4
152 */
153 U_STABLE USet* U_EXPORT2
154 uset_openPattern(const UChar* pattern, int32_t patternLength,
155 UErrorCode* ec);
156
157 /**
158 * Creates a set from the given pattern. See the UnicodeSet class
159 * description for the syntax of the pattern language.
160 * @param pattern a string specifying what characters are in the set
161 * @param patternLength the length of the pattern, or -1 if null
162 * terminated
163 * @param options bitmask for options to apply to the pattern.
164 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
165 * @param ec the error code
166 * @stable ICU 2.4
167 */
168 U_STABLE USet* U_EXPORT2
169 uset_openPatternOptions(const UChar* pattern, int32_t patternLength,
170 uint32_t options,
171 UErrorCode* ec);
172
173 /**
174 * Disposes of the storage used by a USet object. This function should
175 * be called exactly once for objects returned by uset_open().
176 * @param set the object to dispose of
177 * @stable ICU 2.4
178 */
179 U_STABLE void U_EXPORT2
180 uset_close(USet* set);
181
182 /**
183 * Causes the USet object to represent the range <code>start - end</code>.
184 * If <code>start > end</code> then this USet is set to an empty range.
185 * @param set the object to set to the given range
186 * @param start first character in the set, inclusive
187 * @param end last character in the set, inclusive
188 * @stable ICU 3.2
189 */
190 U_STABLE void U_EXPORT2
191 uset_set(USet* set,
192 UChar32 start, UChar32 end);
193
194 /**
195 * Modifies the set to represent the set specified by the given
196 * pattern. See the UnicodeSet class description for the syntax of
197 * the pattern language. See also the User Guide chapter about UnicodeSet.
198 * <em>Empties the set passed before applying the pattern.</em>
199 * @param set The set to which the pattern is to be applied.
200 * @param pattern A pointer to UChar string specifying what characters are in the set.
201 * The character at pattern[0] must be a '['.
202 * @param patternLength The length of the UChar string. -1 if NUL terminated.
203 * @param options A bitmask for options to apply to the pattern.
204 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
205 * @param status Returns an error if the pattern cannot be parsed.
206 * @return Upon successful parse, the value is either
207 * the index of the character after the closing ']'
208 * of the parsed pattern.
209 * If the status code indicates failure, then the return value
210 * is the index of the error in the source.
211 *
212 * @stable ICU 2.8
213 */
214 U_STABLE int32_t U_EXPORT2
215 uset_applyPattern(USet *set,
216 const UChar *pattern, int32_t patternLength,
217 uint32_t options,
218 UErrorCode *status);
219
220 /**
221 * Modifies the set to contain those code points which have the given value
222 * for the given binary or enumerated property, as returned by
223 * u_getIntPropertyValue. Prior contents of this set are lost.
224 *
225 * @param set the object to contain the code points defined by the property
226 *
227 * @param prop a property in the range UCHAR_BIN_START..UCHAR_BIN_LIMIT-1
228 * or UCHAR_INT_START..UCHAR_INT_LIMIT-1
229 * or UCHAR_MASK_START..UCHAR_MASK_LIMIT-1.
230 *
231 * @param value a value in the range u_getIntPropertyMinValue(prop)..
232 * u_getIntPropertyMaxValue(prop), with one exception. If prop is
233 * UCHAR_GENERAL_CATEGORY_MASK, then value should not be a UCharCategory, but
234 * rather a mask value produced by U_GET_GC_MASK(). This allows grouped
235 * categories such as [:L:] to be represented.
236 *
237 * @param ec error code input/output parameter
238 *
239 * @stable ICU 3.2
240 */
241 U_STABLE void U_EXPORT2
242 uset_applyIntPropertyValue(USet* set,
243 UProperty prop, int32_t value, UErrorCode* ec);
244
245 /**
246 * Modifies the set to contain those code points which have the
247 * given value for the given property. Prior contents of this
248 * set are lost.
249 *
250 * @param set the object to contain the code points defined by the given
251 * property and value alias
252 *
253 * @param prop a string specifying a property alias, either short or long.
254 * The name is matched loosely. See PropertyAliases.txt for names and a
255 * description of loose matching. If the value string is empty, then this
256 * string is interpreted as either a General_Category value alias, a Script
257 * value alias, a binary property alias, or a special ID. Special IDs are
258 * matched loosely and correspond to the following sets:
259 *
260 * "ANY" = [\\u0000-\\U0010FFFF],
261 * "ASCII" = [\\u0000-\\u007F],
262 * "Assigned" = [:^Cn:].
263 *
264 * @param propLength the length of the prop, or -1 if NULL
265 *
266 * @param value a string specifying a value alias, either short or long.
267 * The name is matched loosely. See PropertyValueAliases.txt for names
268 * and a description of loose matching. In addition to aliases listed,
269 * numeric values and canonical combining classes may be expressed
270 * numerically, e.g., ("nv", "0.5") or ("ccc", "220"). The value string
271 * may also be empty.
272 *
273 * @param valueLength the length of the value, or -1 if NULL
274 *
275 * @param ec error code input/output parameter
276 *
277 * @stable ICU 3.2
278 */
279 U_STABLE void U_EXPORT2
280 uset_applyPropertyAlias(USet* set,
281 const UChar *prop, int32_t propLength,
282 const UChar *value, int32_t valueLength,
283 UErrorCode* ec);
284
285 /**
286 * Return true if the given position, in the given pattern, appears
287 * to be the start of a UnicodeSet pattern.
288 *
289 * @param pattern a string specifying the pattern
290 * @param patternLength the length of the pattern, or -1 if NULL
291 * @param pos the given position
292 * @stable ICU 3.2
293 */
294 U_STABLE UBool U_EXPORT2
295 uset_resemblesPattern(const UChar *pattern, int32_t patternLength,
296 int32_t pos);
297
298 /**
299 * Returns a string representation of this set. If the result of
300 * calling this function is passed to a uset_openPattern(), it
301 * will produce another set that is equal to this one.
302 * @param set the set
303 * @param result the string to receive the rules, may be NULL
304 * @param resultCapacity the capacity of result, may be 0 if result is NULL
305 * @param escapeUnprintable if TRUE then convert unprintable
306 * character to their hex escape representations, \\uxxxx or
307 * \\Uxxxxxxxx. Unprintable characters are those other than
308 * U+000A, U+0020..U+007E.
309 * @param ec error code.
310 * @return length of string, possibly larger than resultCapacity
311 * @stable ICU 2.4
312 */
313 U_STABLE int32_t U_EXPORT2
314 uset_toPattern(const USet* set,
315 UChar* result, int32_t resultCapacity,
316 UBool escapeUnprintable,
317 UErrorCode* ec);
318
319 /**
320 * Adds the given character to the given USet. After this call,
321 * uset_contains(set, c) will return TRUE.
322 * @param set the object to which to add the character
323 * @param c the character to add
324 * @stable ICU 2.4
325 */
326 U_STABLE void U_EXPORT2
327 uset_add(USet* set, UChar32 c);
328
329 /**
330 * Adds all of the elements in the specified set to this set if
331 * they're not already present. This operation effectively
332 * modifies this set so that its value is the <i>union</i> of the two
333 * sets. The behavior of this operation is unspecified if the specified
334 * collection is modified while the operation is in progress.
335 *
336 * @param set the object to which to add the set
337 * @param additionalSet the source set whose elements are to be added to this set.
338 * @stable ICU 2.6
339 */
340 U_STABLE void U_EXPORT2
341 uset_addAll(USet* set, const USet *additionalSet);
342
343 /**
344 * Adds the given range of characters to the given USet. After this call,
345 * uset_contains(set, start, end) will return TRUE.
346 * @param set the object to which to add the character
347 * @param start the first character of the range to add, inclusive
348 * @param end the last character of the range to add, inclusive
349 * @stable ICU 2.2
350 */
351 U_STABLE void U_EXPORT2
352 uset_addRange(USet* set, UChar32 start, UChar32 end);
353
354 /**
355 * Adds the given string to the given USet. After this call,
356 * uset_containsString(set, str, strLen) will return TRUE.
357 * @param set the object to which to add the character
358 * @param str the string to add
359 * @param strLen the length of the string or -1 if null terminated.
360 * @stable ICU 2.4
361 */
362 U_STABLE void U_EXPORT2
363 uset_addString(USet* set, const UChar* str, int32_t strLen);
364
365 /**
366 * Adds each of the characters in this string to the set. Thus "ch" => {"c", "h"}
367 * If this set already any particular character, it has no effect on that character.
368 * @param set the object to which to add the character
369 * @param str the source string
370 * @param strLen the length of the string or -1 if null terminated.
371 * @draft ICU 3.4
372 */
373 U_DRAFT void U_EXPORT2
374 uset_addAllCodePoints(USet* set, const UChar *str, int32_t strLen);
375
376 /**
377 * Removes the given character from the given USet. After this call,
378 * uset_contains(set, c) will return FALSE.
379 * @param set the object from which to remove the character
380 * @param c the character to remove
381 * @stable ICU 2.4
382 */
383 U_STABLE void U_EXPORT2
384 uset_remove(USet* set, UChar32 c);
385
386 /**
387 * Removes the given range of characters from the given USet. After this call,
388 * uset_contains(set, start, end) will return FALSE.
389 * @param set the object to which to add the character
390 * @param start the first character of the range to remove, inclusive
391 * @param end the last character of the range to remove, inclusive
392 * @stable ICU 2.2
393 */
394 U_STABLE void U_EXPORT2
395 uset_removeRange(USet* set, UChar32 start, UChar32 end);
396
397 /**
398 * Removes the given string to the given USet. After this call,
399 * uset_containsString(set, str, strLen) will return FALSE.
400 * @param set the object to which to add the character
401 * @param str the string to remove
402 * @param strLen the length of the string or -1 if null terminated.
403 * @stable ICU 2.4
404 */
405 U_STABLE void U_EXPORT2
406 uset_removeString(USet* set, const UChar* str, int32_t strLen);
407
408 /**
409 * Removes from this set all of its elements that are contained in the
410 * specified set. This operation effectively modifies this
411 * set so that its value is the <i>asymmetric set difference</i> of
412 * the two sets.
413 * @param set the object from which the elements are to be removed
414 * @param removeSet the object that defines which elements will be
415 * removed from this set
416 * @stable ICU 3.2
417 */
418 U_STABLE void U_EXPORT2
419 uset_removeAll(USet* set, const USet* removeSet);
420
421 /**
422 * Retain only the elements in this set that are contained in the
423 * specified range. If <code>start > end</code> then an empty range is
424 * retained, leaving the set empty. This is equivalent to
425 * a boolean logic AND, or a set INTERSECTION.
426 *
427 * @param set the object for which to retain only the specified range
428 * @param start first character, inclusive, of range to be retained
429 * to this set.
430 * @param end last character, inclusive, of range to be retained
431 * to this set.
432 * @stable ICU 3.2
433 */
434 U_STABLE void U_EXPORT2
435 uset_retain(USet* set, UChar32 start, UChar32 end);
436
437 /**
438 * Retains only the elements in this set that are contained in the
439 * specified set. In other words, removes from this set all of
440 * its elements that are not contained in the specified set. This
441 * operation effectively modifies this set so that its value is
442 * the <i>intersection</i> of the two sets.
443 *
444 * @param set the object on which to perform the retain
445 * @param retain set that defines which elements this set will retain
446 * @stable ICU 3.2
447 */
448 U_STABLE void U_EXPORT2
449 uset_retainAll(USet* set, const USet* retain);
450
451 /**
452 * Reallocate this objects internal structures to take up the least
453 * possible space, without changing this object's value.
454 *
455 * @param set the object on which to perfrom the compact
456 * @stable ICU 3.2
457 */
458 U_STABLE void U_EXPORT2
459 uset_compact(USet* set);
460
461 /**
462 * Inverts this set. This operation modifies this set so that
463 * its value is its complement. This operation does not affect
464 * the multicharacter strings, if any.
465 * @param set the set
466 * @stable ICU 2.4
467 */
468 U_STABLE void U_EXPORT2
469 uset_complement(USet* set);
470
471 /**
472 * Complements in this set all elements contained in the specified
473 * set. Any character in the other set will be removed if it is
474 * in this set, or will be added if it is not in this set.
475 *
476 * @param set the set with which to complement
477 * @param complement set that defines which elements will be xor'ed
478 * from this set.
479 * @stable ICU 3.2
480 */
481 U_STABLE void U_EXPORT2
482 uset_complementAll(USet* set, const USet* complement);
483
484 /**
485 * Removes all of the elements from this set. This set will be
486 * empty after this call returns.
487 * @param set the set
488 * @stable ICU 2.4
489 */
490 U_STABLE void U_EXPORT2
491 uset_clear(USet* set);
492
493 /**
494 * Returns TRUE if the given USet contains no characters and no
495 * strings.
496 * @param set the set
497 * @return true if set is empty
498 * @stable ICU 2.4
499 */
500 U_STABLE UBool U_EXPORT2
501 uset_isEmpty(const USet* set);
502
503 /**
504 * Returns TRUE if the given USet contains the given character.
505 * @param set the set
506 * @param c The codepoint to check for within the set
507 * @return true if set contains c
508 * @stable ICU 2.4
509 */
510 U_STABLE UBool U_EXPORT2
511 uset_contains(const USet* set, UChar32 c);
512
513 /**
514 * Returns TRUE if the given USet contains all characters c
515 * where start <= c && c <= end.
516 * @param set the set
517 * @param start the first character of the range to test, inclusive
518 * @param end the last character of the range to test, inclusive
519 * @return TRUE if set contains the range
520 * @stable ICU 2.2
521 */
522 U_STABLE UBool U_EXPORT2
523 uset_containsRange(const USet* set, UChar32 start, UChar32 end);
524
525 /**
526 * Returns TRUE if the given USet contains the given string.
527 * @param set the set
528 * @param str the string
529 * @param strLen the length of the string or -1 if null terminated.
530 * @return true if set contains str
531 * @stable ICU 2.4
532 */
533 U_STABLE UBool U_EXPORT2
534 uset_containsString(const USet* set, const UChar* str, int32_t strLen);
535
536 /**
537 * Returns the index of the given character within this set, where
538 * the set is ordered by ascending code point. If the character
539 * is not in this set, return -1. The inverse of this method is
540 * <code>charAt()</code>.
541 * @param set the set
542 * @param c the character to obtain the index for
543 * @return an index from 0..size()-1, or -1
544 * @stable ICU 3.2
545 */
546 U_STABLE int32_t U_EXPORT2
547 uset_indexOf(const USet* set, UChar32 c);
548
549 /**
550 * Returns the character at the given index within this set, where
551 * the set is ordered by ascending code point. If the index is
552 * out of range, return (UChar32)-1. The inverse of this method is
553 * <code>indexOf()</code>.
554 * @param set the set
555 * @param index an index from 0..size()-1 to obtain the char for
556 * @return the character at the given index, or (UChar32)-1.
557 * @stable ICU 3.2
558 */
559 U_STABLE UChar32 U_EXPORT2
560 uset_charAt(const USet* set, int32_t index);
561
562 /**
563 * Returns the number of characters and strings contained in the given
564 * USet.
565 * @param set the set
566 * @return a non-negative integer counting the characters and strings
567 * contained in set
568 * @stable ICU 2.4
569 */
570 U_STABLE int32_t U_EXPORT2
571 uset_size(const USet* set);
572
573 /**
574 * Returns the number of items in this set. An item is either a range
575 * of characters or a single multicharacter string.
576 * @param set the set
577 * @return a non-negative integer counting the character ranges
578 * and/or strings contained in set
579 * @stable ICU 2.4
580 */
581 U_STABLE int32_t U_EXPORT2
582 uset_getItemCount(const USet* set);
583
584 /**
585 * Returns an item of this set. An item is either a range of
586 * characters or a single multicharacter string.
587 * @param set the set
588 * @param itemIndex a non-negative integer in the range 0..
589 * uset_getItemCount(set)-1
590 * @param start pointer to variable to receive first character
591 * in range, inclusive
592 * @param end pointer to variable to receive last character in range,
593 * inclusive
594 * @param str buffer to receive the string, may be NULL
595 * @param strCapacity capacity of str, or 0 if str is NULL
596 * @param ec error code
597 * @return the length of the string (>= 2), or 0 if the item is a
598 * range, in which case it is the range *start..*end, or -1 if
599 * itemIndex is out of range
600 * @stable ICU 2.4
601 */
602 U_STABLE int32_t U_EXPORT2
603 uset_getItem(const USet* set, int32_t itemIndex,
604 UChar32* start, UChar32* end,
605 UChar* str, int32_t strCapacity,
606 UErrorCode* ec);
607
608 /**
609 * Returns true if set1 contains all the characters and strings
610 * of set2. It answers the question, 'Is set1 a superset of set2?'
611 * @param set1 set to be checked for containment
612 * @param set2 set to be checked for containment
613 * @return true if the test condition is met
614 * @stable ICU 3.2
615 */
616 U_STABLE UBool U_EXPORT2
617 uset_containsAll(const USet* set1, const USet* set2);
618
619 /**
620 * Returns true if this set contains all the characters
621 * of the given string. This is does not check containment of grapheme
622 * clusters, like uset_containsString.
623 * @param set set of characters to be checked for containment
624 * @param str string containing codepoints to be checked for containment
625 * @param strLen the length of the string or -1 if null terminated.
626 * @return true if the test condition is met
627 * @draft ICU 3.4
628 */
629 U_DRAFT UBool U_EXPORT2
630 uset_containsAllCodePoints(const USet* set, const UChar *str, int32_t strLen);
631
632 /**
633 * Returns true if set1 contains none of the characters and strings
634 * of set2. It answers the question, 'Is set1 a disjoint set of set2?'
635 * @param set1 set to be checked for containment
636 * @param set2 set to be checked for containment
637 * @return true if the test condition is met
638 * @stable ICU 3.2
639 */
640 U_STABLE UBool U_EXPORT2
641 uset_containsNone(const USet* set1, const USet* set2);
642
643 /**
644 * Returns true if set1 contains some of the characters and strings
645 * of set2. It answers the question, 'Does set1 and set2 have an intersection?'
646 * @param set1 set to be checked for containment
647 * @param set2 set to be checked for containment
648 * @return true if the test condition is met
649 * @stable ICU 3.2
650 */
651 U_STABLE UBool U_EXPORT2
652 uset_containsSome(const USet* set1, const USet* set2);
653
654 /**
655 * Returns true if set1 contains all of the characters and strings
656 * of set2, and vis versa. It answers the question, 'Is set1 equal to set2?'
657 * @param set1 set to be checked for containment
658 * @param set2 set to be checked for containment
659 * @return true if the test condition is met
660 * @stable ICU 3.2
661 */
662 U_STABLE UBool U_EXPORT2
663 uset_equals(const USet* set1, const USet* set2);
664
665 /*********************************************************************
666 * Serialized set API
667 *********************************************************************/
668
669 /**
670 * Serializes this set into an array of 16-bit integers. Serialization
671 * (currently) only records the characters in the set; multicharacter
672 * strings are ignored.
673 *
674 * The array
675 * has following format (each line is one 16-bit integer):
676 *
677 * length = (n+2*m) | (m!=0?0x8000:0)
678 * bmpLength = n; present if m!=0
679 * bmp[0]
680 * bmp[1]
681 * ...
682 * bmp[n-1]
683 * supp-high[0]
684 * supp-low[0]
685 * supp-high[1]
686 * supp-low[1]
687 * ...
688 * supp-high[m-1]
689 * supp-low[m-1]
690 *
691 * The array starts with a header. After the header are n bmp
692 * code points, then m supplementary code points. Either n or m
693 * or both may be zero. n+2*m is always <= 0x7FFF.
694 *
695 * If there are no supplementary characters (if m==0) then the
696 * header is one 16-bit integer, 'length', with value n.
697 *
698 * If there are supplementary characters (if m!=0) then the header
699 * is two 16-bit integers. The first, 'length', has value
700 * (n+2*m)|0x8000. The second, 'bmpLength', has value n.
701 *
702 * After the header the code points are stored in ascending order.
703 * Supplementary code points are stored as most significant 16
704 * bits followed by least significant 16 bits.
705 *
706 * @param set the set
707 * @param dest pointer to buffer of destCapacity 16-bit integers.
708 * May be NULL only if destCapacity is zero.
709 * @param destCapacity size of dest, or zero. Must not be negative.
710 * @param pErrorCode pointer to the error code. Will be set to
711 * U_INDEX_OUTOFBOUNDS_ERROR if n+2*m > 0x7FFF. Will be set to
712 * U_BUFFER_OVERFLOW_ERROR if n+2*m+(m!=0?2:1) > destCapacity.
713 * @return the total length of the serialized format, including
714 * the header, that is, n+2*m+(m!=0?2:1), or 0 on error other
715 * than U_BUFFER_OVERFLOW_ERROR.
716 * @stable ICU 2.4
717 */
718 U_STABLE int32_t U_EXPORT2
719 uset_serialize(const USet* set, uint16_t* dest, int32_t destCapacity, UErrorCode* pErrorCode);
720
721 /**
722 * Given a serialized array, fill in the given serialized set object.
723 * @param fillSet pointer to result
724 * @param src pointer to start of array
725 * @param srcLength length of array
726 * @return true if the given array is valid, otherwise false
727 * @stable ICU 2.4
728 */
729 U_STABLE UBool U_EXPORT2
730 uset_getSerializedSet(USerializedSet* fillSet, const uint16_t* src, int32_t srcLength);
731
732 /**
733 * Set the USerializedSet to contain the given character (and nothing
734 * else).
735 * @param fillSet pointer to result
736 * @param c The codepoint to set
737 * @stable ICU 2.4
738 */
739 U_STABLE void U_EXPORT2
740 uset_setSerializedToOne(USerializedSet* fillSet, UChar32 c);
741
742 /**
743 * Returns TRUE if the given USerializedSet contains the given
744 * character.
745 * @param set the serialized set
746 * @param c The codepoint to check for within the set
747 * @return true if set contains c
748 * @stable ICU 2.4
749 */
750 U_STABLE UBool U_EXPORT2
751 uset_serializedContains(const USerializedSet* set, UChar32 c);
752
753 /**
754 * Returns the number of disjoint ranges of characters contained in
755 * the given serialized set. Ignores any strings contained in the
756 * set.
757 * @param set the serialized set
758 * @return a non-negative integer counting the character ranges
759 * contained in set
760 * @stable ICU 2.4
761 */
762 U_STABLE int32_t U_EXPORT2
763 uset_getSerializedRangeCount(const USerializedSet* set);
764
765 /**
766 * Returns a range of characters contained in the given serialized
767 * set.
768 * @param set the serialized set
769 * @param rangeIndex a non-negative integer in the range 0..
770 * uset_getSerializedRangeCount(set)-1
771 * @param pStart pointer to variable to receive first character
772 * in range, inclusive
773 * @param pEnd pointer to variable to receive last character in range,
774 * inclusive
775 * @return true if rangeIndex is valid, otherwise false
776 * @stable ICU 2.4
777 */
778 U_STABLE UBool U_EXPORT2
779 uset_getSerializedRange(const USerializedSet* set, int32_t rangeIndex,
780 UChar32* pStart, UChar32* pEnd);
781
782 #endif