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