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