2 *******************************************************************************
4 * Copyright (C) 2002-2006, International Business Machines
5 * Corporation and others. All Rights Reserved.
7 *******************************************************************************
10 * tab size: 8 (not used)
13 * created on: 2002mar07
14 * created by: Markus W. Scherer
16 * C version of UnicodeSet.
22 * \brief C API: Unicode Set
24 * <p>This is a C wrapper around the C++ UnicodeSet class.</p>
30 #include "unicode/utypes.h"
31 #include "unicode/uchar.h"
36 * A UnicodeSet. Use the uset_* API to manipulate. Create with
37 * uset_open*, and destroy with uset_close.
40 typedef struct USet USet
;
44 * Bitmask values to be passed to uset_openPatternOptions() or
45 * uset_applyPattern() taking an option parameter.
50 * Ignore white space within patterns unless quoted or escaped.
53 USET_IGNORE_SPACE
= 1,
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.
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.
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.
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.
81 USET_CASE_INSENSITIVE
= 2,
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.
91 USET_ADD_CASE_MAPPINGS
= 4,
94 * Enough for any single-code point set
97 USET_SERIALIZED_STATIC_ARRAY_CAPACITY
=8
101 * A serialized form of a Unicode set. Limited manipulations are
102 * possible directly on a serialized set. See below.
105 typedef struct USerializedSet
{
107 * The serialized Unicode Set.
110 const uint16_t *array
;
112 * The length of the array that contains BMP characters.
117 * The total length of the array.
122 * A small buffer for the array to reduce memory allocations.
125 uint16_t staticArray
[USET_SERIALIZED_STATIC_ARRAY_CAPACITY
];
128 /*********************************************************************
130 *********************************************************************/
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
141 U_STABLE USet
* U_EXPORT2
142 uset_open(UChar32 start
, UChar32 end
);
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
150 * @param ec the error code
153 U_STABLE USet
* U_EXPORT2
154 uset_openPattern(const UChar
* pattern
, int32_t patternLength
,
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
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
168 U_STABLE USet
* U_EXPORT2
169 uset_openPatternOptions(const UChar
* pattern
, int32_t patternLength
,
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
179 U_STABLE
void U_EXPORT2
180 uset_close(USet
* set
);
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
190 U_STABLE
void U_EXPORT2
192 UChar32 start
, UChar32 end
);
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.
214 U_STABLE
int32_t U_EXPORT2
215 uset_applyPattern(USet
*set
,
216 const UChar
*pattern
, int32_t patternLength
,
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.
225 * @param set the object to contain the code points defined by the property
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.
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.
237 * @param ec error code input/output parameter
241 U_STABLE
void U_EXPORT2
242 uset_applyIntPropertyValue(USet
* set
,
243 UProperty prop
, int32_t value
, UErrorCode
* ec
);
246 * Modifies the set to contain those code points which have the
247 * given value for the given property. Prior contents of this
250 * @param set the object to contain the code points defined by the given
251 * property and value alias
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:
260 * "ANY" = [\\u0000-\\U0010FFFF],
261 * "ASCII" = [\\u0000-\\u007F],
262 * "Assigned" = [:^Cn:].
264 * @param propLength the length of the prop, or -1 if NULL
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
273 * @param valueLength the length of the value, or -1 if NULL
275 * @param ec error code input/output parameter
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
,
286 * Return true if the given position, in the given pattern, appears
287 * to be the start of a UnicodeSet pattern.
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
294 U_STABLE UBool U_EXPORT2
295 uset_resemblesPattern(const UChar
*pattern
, int32_t patternLength
,
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.
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
313 U_STABLE
int32_t U_EXPORT2
314 uset_toPattern(const USet
* set
,
315 UChar
* result
, int32_t resultCapacity
,
316 UBool escapeUnprintable
,
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
326 U_STABLE
void U_EXPORT2
327 uset_add(USet
* set
, UChar32 c
);
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.
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.
340 U_STABLE
void U_EXPORT2
341 uset_addAll(USet
* set
, const USet
*additionalSet
);
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
351 U_STABLE
void U_EXPORT2
352 uset_addRange(USet
* set
, UChar32 start
, UChar32 end
);
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.
362 U_STABLE
void U_EXPORT2
363 uset_addString(USet
* set
, const UChar
* str
, int32_t strLen
);
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.
373 U_DRAFT
void U_EXPORT2
374 uset_addAllCodePoints(USet
* set
, const UChar
*str
, int32_t strLen
);
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
383 U_STABLE
void U_EXPORT2
384 uset_remove(USet
* set
, UChar32 c
);
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
394 U_STABLE
void U_EXPORT2
395 uset_removeRange(USet
* set
, UChar32 start
, UChar32 end
);
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.
405 U_STABLE
void U_EXPORT2
406 uset_removeString(USet
* set
, const UChar
* str
, int32_t strLen
);
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
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
418 U_STABLE
void U_EXPORT2
419 uset_removeAll(USet
* set
, const USet
* removeSet
);
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.
427 * @param set the object for which to retain only the specified range
428 * @param start first character, inclusive, of range to be retained
430 * @param end last character, inclusive, of range to be retained
434 U_STABLE
void U_EXPORT2
435 uset_retain(USet
* set
, UChar32 start
, UChar32 end
);
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.
444 * @param set the object on which to perform the retain
445 * @param retain set that defines which elements this set will retain
448 U_STABLE
void U_EXPORT2
449 uset_retainAll(USet
* set
, const USet
* retain
);
452 * Reallocate this objects internal structures to take up the least
453 * possible space, without changing this object's value.
455 * @param set the object on which to perfrom the compact
458 U_STABLE
void U_EXPORT2
459 uset_compact(USet
* set
);
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.
468 U_STABLE
void U_EXPORT2
469 uset_complement(USet
* set
);
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.
476 * @param set the set with which to complement
477 * @param complement set that defines which elements will be xor'ed
481 U_STABLE
void U_EXPORT2
482 uset_complementAll(USet
* set
, const USet
* complement
);
485 * Removes all of the elements from this set. This set will be
486 * empty after this call returns.
490 U_STABLE
void U_EXPORT2
491 uset_clear(USet
* set
);
494 * Returns TRUE if the given USet contains no characters and no
497 * @return true if set is empty
500 U_STABLE UBool U_EXPORT2
501 uset_isEmpty(const USet
* set
);
504 * Returns TRUE if the given USet contains the given character.
506 * @param c The codepoint to check for within the set
507 * @return true if set contains c
510 U_STABLE UBool U_EXPORT2
511 uset_contains(const USet
* set
, UChar32 c
);
514 * Returns TRUE if the given USet contains all characters c
515 * where start <= c && c <= end.
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
522 U_STABLE UBool U_EXPORT2
523 uset_containsRange(const USet
* set
, UChar32 start
, UChar32 end
);
526 * Returns TRUE if the given USet contains the given string.
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
533 U_STABLE UBool U_EXPORT2
534 uset_containsString(const USet
* set
, const UChar
* str
, int32_t strLen
);
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>.
542 * @param c the character to obtain the index for
543 * @return an index from 0..size()-1, or -1
546 U_STABLE
int32_t U_EXPORT2
547 uset_indexOf(const USet
* set
, UChar32 c
);
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>.
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.
559 U_STABLE UChar32 U_EXPORT2
560 uset_charAt(const USet
* set
, int32_t index
);
563 * Returns the number of characters and strings contained in the given
566 * @return a non-negative integer counting the characters and strings
570 U_STABLE
int32_t U_EXPORT2
571 uset_size(const USet
* set
);
574 * Returns the number of items in this set. An item is either a range
575 * of characters or a single multicharacter string.
577 * @return a non-negative integer counting the character ranges
578 * and/or strings contained in set
581 U_STABLE
int32_t U_EXPORT2
582 uset_getItemCount(const USet
* set
);
585 * Returns an item of this set. An item is either a range of
586 * characters or a single multicharacter string.
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,
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
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
,
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
616 U_STABLE UBool U_EXPORT2
617 uset_containsAll(const USet
* set1
, const USet
* set2
);
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
629 U_DRAFT UBool U_EXPORT2
630 uset_containsAllCodePoints(const USet
* set
, const UChar
*str
, int32_t strLen
);
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
640 U_STABLE UBool U_EXPORT2
641 uset_containsNone(const USet
* set1
, const USet
* set2
);
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
651 U_STABLE UBool U_EXPORT2
652 uset_containsSome(const USet
* set1
, const USet
* set2
);
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
662 U_STABLE UBool U_EXPORT2
663 uset_equals(const USet
* set1
, const USet
* set2
);
665 /*********************************************************************
667 *********************************************************************/
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.
675 * has following format (each line is one 16-bit integer):
677 * length = (n+2*m) | (m!=0?0x8000:0)
678 * bmpLength = n; present if m!=0
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.
695 * If there are no supplementary characters (if m==0) then the
696 * header is one 16-bit integer, 'length', with value n.
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.
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.
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.
718 U_STABLE
int32_t U_EXPORT2
719 uset_serialize(const USet
* set
, uint16_t* dest
, int32_t destCapacity
, UErrorCode
* pErrorCode
);
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
729 U_STABLE UBool U_EXPORT2
730 uset_getSerializedSet(USerializedSet
* fillSet
, const uint16_t* src
, int32_t srcLength
);
733 * Set the USerializedSet to contain the given character (and nothing
735 * @param fillSet pointer to result
736 * @param c The codepoint to set
739 U_STABLE
void U_EXPORT2
740 uset_setSerializedToOne(USerializedSet
* fillSet
, UChar32 c
);
743 * Returns TRUE if the given USerializedSet contains the given
745 * @param set the serialized set
746 * @param c The codepoint to check for within the set
747 * @return true if set contains c
750 U_STABLE UBool U_EXPORT2
751 uset_serializedContains(const USerializedSet
* set
, UChar32 c
);
754 * Returns the number of disjoint ranges of characters contained in
755 * the given serialized set. Ignores any strings contained in the
757 * @param set the serialized set
758 * @return a non-negative integer counting the character ranges
762 U_STABLE
int32_t U_EXPORT2
763 uset_getSerializedRangeCount(const USerializedSet
* set
);
766 * Returns a range of characters contained in the given serialized
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,
775 * @return true if rangeIndex is valid, otherwise false
778 U_STABLE UBool U_EXPORT2
779 uset_getSerializedRange(const USerializedSet
* set
, int32_t rangeIndex
,
780 UChar32
* pStart
, UChar32
* pEnd
);