1 // 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 *************************************************************************** 5 * Copyright (C) 1999-2016, International Business Machines Corporation 6 * and others. All Rights Reserved. 7 *************************************************************************** 8 * Date Name Description 9 * 10/20/99 alan Creation. 10 *************************************************************************** 11 */ 12 13 #ifndef UNICODESET_H 14 #define UNICODESET_H 15 16 #include "unicode/ucpmap.h" 17 #include "unicode/unifilt.h" 18 #include "unicode/unistr.h" 19 #include "unicode/uset.h" 20 21 /** 22 * \file 23 * \brief C++ API: Unicode Set 24 */ 25 26 U_NAMESPACE_BEGIN 27 28 // Forward Declarations. 29 class BMPSet; 30 class ParsePosition; 31 class RBBIRuleScanner; 32 class SymbolTable; 33 class UnicodeSetStringSpan; 34 class UVector; 35 class RuleCharacterIterator; 36 37 /** 38 * A mutable set of Unicode characters and multicharacter strings. Objects of this class 39 * represent <em>character classes</em> used in regular expressions. 40 * A character specifies a subset of Unicode code points. Legal 41 * code points are U+0000 to U+10FFFF, inclusive. 42 * 43 * <p>The UnicodeSet class is not designed to be subclassed. 44 * 45 * <p><code>UnicodeSet</code> supports two APIs. The first is the 46 * <em>operand</em> API that allows the caller to modify the value of 47 * a <code>UnicodeSet</code> object. It conforms to Java 2's 48 * <code>java.util.Set</code> interface, although 49 * <code>UnicodeSet</code> does not actually implement that 50 * interface. All methods of <code>Set</code> are supported, with the 51 * modification that they take a character range or single character 52 * instead of an <code>Object</code>, and they take a 53 * <code>UnicodeSet</code> instead of a <code>Collection</code>. The 54 * operand API may be thought of in terms of boolean logic: a boolean 55 * OR is implemented by <code>add</code>, a boolean AND is implemented 56 * by <code>retain</code>, a boolean XOR is implemented by 57 * <code>complement</code> taking an argument, and a boolean NOT is 58 * implemented by <code>complement</code> with no argument. In terms 59 * of traditional set theory function names, <code>add</code> is a 60 * union, <code>retain</code> is an intersection, <code>remove</code> 61 * is an asymmetric difference, and <code>complement</code> with no 62 * argument is a set complement with respect to the superset range 63 * <code>MIN_VALUE-MAX_VALUE</code> 64 * 65 * <p>The second API is the 66 * <code>applyPattern()</code>/<code>toPattern()</code> API from the 67 * <code>java.text.Format</code>-derived classes. Unlike the 68 * methods that add characters, add categories, and control the logic 69 * of the set, the method <code>applyPattern()</code> sets all 70 * attributes of a <code>UnicodeSet</code> at once, based on a 71 * string pattern. 72 * 73 * <p><b>Pattern syntax</b></p> 74 * 75 * Patterns are accepted by the constructors and the 76 * <code>applyPattern()</code> methods and returned by the 77 * <code>toPattern()</code> method. These patterns follow a syntax 78 * similar to that employed by version 8 regular expression character 79 * classes. Here are some simple examples: 80 * 81 * \htmlonly<blockquote>\endhtmlonly 82 * <table> 83 * <tr align="top"> 84 * <td nowrap valign="top" align="left"><code>[]</code></td> 85 * <td valign="top">No characters</td> 86 * </tr><tr align="top"> 87 * <td nowrap valign="top" align="left"><code>[a]</code></td> 88 * <td valign="top">The character 'a'</td> 89 * </tr><tr align="top"> 90 * <td nowrap valign="top" align="left"><code>[ae]</code></td> 91 * <td valign="top">The characters 'a' and 'e'</td> 92 * </tr> 93 * <tr> 94 * <td nowrap valign="top" align="left"><code>[a-e]</code></td> 95 * <td valign="top">The characters 'a' through 'e' inclusive, in Unicode code 96 * point order</td> 97 * </tr> 98 * <tr> 99 * <td nowrap valign="top" align="left"><code>[\\u4E01]</code></td> 100 * <td valign="top">The character U+4E01</td> 101 * </tr> 102 * <tr> 103 * <td nowrap valign="top" align="left"><code>[a{ab}{ac}]</code></td> 104 * <td valign="top">The character 'a' and the multicharacter strings "ab" and 105 * "ac"</td> 106 * </tr> 107 * <tr> 108 * <td nowrap valign="top" align="left"><code>[\\p{Lu}]</code></td> 109 * <td valign="top">All characters in the general category Uppercase Letter</td> 110 * </tr> 111 * </table> 112 * \htmlonly</blockquote>\endhtmlonly 113 * 114 * Any character may be preceded by a backslash in order to remove any special 115 * meaning. White space characters, as defined by UCharacter.isWhitespace(), are 116 * ignored, unless they are escaped. 117 * 118 * <p>Property patterns specify a set of characters having a certain 119 * property as defined by the Unicode standard. Both the POSIX-like 120 * "[:Lu:]" and the Perl-like syntax "\\p{Lu}" are recognized. For a 121 * complete list of supported property patterns, see the User's Guide 122 * for UnicodeSet at 123 * <a href="http://icu-project.org/userguide/unicodeSet.html"> 124 * http://icu-project.org/userguide/unicodeSet.html</a>. 125 * Actual determination of property data is defined by the underlying 126 * Unicode database as implemented by UCharacter. 127 * 128 * <p>Patterns specify individual characters, ranges of characters, and 129 * Unicode property sets. When elements are concatenated, they 130 * specify their union. To complement a set, place a '^' immediately 131 * after the opening '['. Property patterns are inverted by modifying 132 * their delimiters; "[:^foo]" and "\\P{foo}". In any other location, 133 * '^' has no special meaning. 134 * 135 * <p>Ranges are indicated by placing two a '-' between two 136 * characters, as in "a-z". This specifies the range of all 137 * characters from the left to the right, in Unicode order. If the 138 * left character is greater than or equal to the 139 * right character it is a syntax error. If a '-' occurs as the first 140 * character after the opening '[' or '[^', or if it occurs as the 141 * last character before the closing ']', then it is taken as a 142 * literal. Thus "[a\-b]", "[-ab]", and "[ab-]" all indicate the same 143 * set of three characters, 'a', 'b', and '-'. 144 * 145 * <p>Sets may be intersected using the '&' operator or the asymmetric 146 * set difference may be taken using the '-' operator, for example, 147 * "[[:L:]&[\\u0000-\\u0FFF]]" indicates the set of all Unicode letters 148 * with values less than 4096. Operators ('&' and '|') have equal 149 * precedence and bind left-to-right. Thus 150 * "[[:L:]-[a-z]-[\\u0100-\\u01FF]]" is equivalent to 151 * "[[[:L:]-[a-z]]-[\\u0100-\\u01FF]]". This only really matters for 152 * difference; intersection is commutative. 153 * 154 * <table> 155 * <tr valign=top><td nowrap><code>[a]</code><td>The set containing 'a' 156 * <tr valign=top><td nowrap><code>[a-z]</code><td>The set containing 'a' 157 * through 'z' and all letters in between, in Unicode order 158 * <tr valign=top><td nowrap><code>[^a-z]</code><td>The set containing 159 * all characters but 'a' through 'z', 160 * that is, U+0000 through 'a'-1 and 'z'+1 through U+10FFFF 161 * <tr valign=top><td nowrap><code>[[<em>pat1</em>][<em>pat2</em>]]</code> 162 * <td>The union of sets specified by <em>pat1</em> and <em>pat2</em> 163 * <tr valign=top><td nowrap><code>[[<em>pat1</em>]&[<em>pat2</em>]]</code> 164 * <td>The intersection of sets specified by <em>pat1</em> and <em>pat2</em> 165 * <tr valign=top><td nowrap><code>[[<em>pat1</em>]-[<em>pat2</em>]]</code> 166 * <td>The asymmetric difference of sets specified by <em>pat1</em> and 167 * <em>pat2</em> 168 * <tr valign=top><td nowrap><code>[:Lu:] or \\p{Lu}</code> 169 * <td>The set of characters having the specified 170 * Unicode property; in 171 * this case, Unicode uppercase letters 172 * <tr valign=top><td nowrap><code>[:^Lu:] or \\P{Lu}</code> 173 * <td>The set of characters <em>not</em> having the given 174 * Unicode property 175 * </table> 176 * 177 * <p><b>Warning</b>: you cannot add an empty string ("") to a UnicodeSet.</p> 178 * 179 * <p><b>Formal syntax</b></p> 180 * 181 * \htmlonly<blockquote>\endhtmlonly 182 * <table> 183 * <tr align="top"> 184 * <td nowrap valign="top" align="right"><code>pattern := </code></td> 185 * <td valign="top"><code>('[' '^'? item* ']') | 186 * property</code></td> 187 * </tr> 188 * <tr align="top"> 189 * <td nowrap valign="top" align="right"><code>item := </code></td> 190 * <td valign="top"><code>char | (char '-' char) | pattern-expr<br> 191 * </code></td> 192 * </tr> 193 * <tr align="top"> 194 * <td nowrap valign="top" align="right"><code>pattern-expr := </code></td> 195 * <td valign="top"><code>pattern | pattern-expr pattern | 196 * pattern-expr op pattern<br> 197 * </code></td> 198 * </tr> 199 * <tr align="top"> 200 * <td nowrap valign="top" align="right"><code>op := </code></td> 201 * <td valign="top"><code>'&' | '-'<br> 202 * </code></td> 203 * </tr> 204 * <tr align="top"> 205 * <td nowrap valign="top" align="right"><code>special := </code></td> 206 * <td valign="top"><code>'[' | ']' | '-'<br> 207 * </code></td> 208 * </tr> 209 * <tr align="top"> 210 * <td nowrap valign="top" align="right"><code>char := </code></td> 211 * <td valign="top"><em>any character that is not</em><code> special<br> 212 * | ('\' </code><em>any character</em><code>)<br> 213 * | ('\\u' hex hex hex hex)<br> 214 * </code></td> 215 * </tr> 216 * <tr align="top"> 217 * <td nowrap valign="top" align="right"><code>hex := </code></td> 218 * <td valign="top"><em>any character for which 219 * </em><code>Character.digit(c, 16)</code><em> 220 * returns a non-negative result</em></td> 221 * </tr> 222 * <tr> 223 * <td nowrap valign="top" align="right"><code>property := </code></td> 224 * <td valign="top"><em>a Unicode property set pattern</em></td> 225 * </tr> 226 * </table> 227 * <br> 228 * <table border="1"> 229 * <tr> 230 * <td>Legend: <table> 231 * <tr> 232 * <td nowrap valign="top"><code>a := b</code></td> 233 * <td width="20" valign="top"> </td> 234 * <td valign="top"><code>a</code> may be replaced by <code>b</code> </td> 235 * </tr> 236 * <tr> 237 * <td nowrap valign="top"><code>a?</code></td> 238 * <td valign="top"></td> 239 * <td valign="top">zero or one instance of <code>a</code><br> 240 * </td> 241 * </tr> 242 * <tr> 243 * <td nowrap valign="top"><code>a*</code></td> 244 * <td valign="top"></td> 245 * <td valign="top">one or more instances of <code>a</code><br> 246 * </td> 247 * </tr> 248 * <tr> 249 * <td nowrap valign="top"><code>a | b</code></td> 250 * <td valign="top"></td> 251 * <td valign="top">either <code>a</code> or <code>b</code><br> 252 * </td> 253 * </tr> 254 * <tr> 255 * <td nowrap valign="top"><code>'a'</code></td> 256 * <td valign="top"></td> 257 * <td valign="top">the literal string between the quotes </td> 258 * </tr> 259 * </table> 260 * </td> 261 * </tr> 262 * </table> 263 * \htmlonly</blockquote>\endhtmlonly 264 * 265 * <p>Note: 266 * - Most UnicodeSet methods do not take a UErrorCode parameter because 267 * there are usually very few opportunities for failure other than a shortage 268 * of memory, error codes in low-level C++ string methods would be inconvenient, 269 * and the error code as the last parameter (ICU convention) would prevent 270 * the use of default parameter values. 271 * Instead, such methods set the UnicodeSet into a "bogus" state 272 * (see isBogus()) if an error occurs. 273 * 274 * @author Alan Liu 275 * @stable ICU 2.0 276 */ 277 class U_COMMON_API UnicodeSet U_FINAL : public UnicodeFilter { 278 private: 279 /** 280 * Enough for sets with few ranges. 281 * For example, White_Space has 10 ranges, list length 21. 282 */ 283 static constexpr int32_t INITIAL_CAPACITY = 25; 284 // fFlags constant 285 static constexpr uint8_t kIsBogus = 1; // This set is bogus (i.e. not valid) 286 287 UChar32* list = stackList; // MUST be terminated with HIGH 288 int32_t capacity = INITIAL_CAPACITY; // capacity of list 289 int32_t len = 1; // length of list used; 1 <= len <= capacity 290 uint8_t fFlags = 0; // Bit flag (see constants above) 291 292 BMPSet *bmpSet = nullptr; // The set is frozen iff either bmpSet or stringSpan is not NULL. 293 UChar32* buffer = nullptr; // internal buffer, may be NULL 294 int32_t bufferCapacity = 0; // capacity of buffer 295 296 /** 297 * The pattern representation of this set. This may not be the 298 * most economical pattern. It is the pattern supplied to 299 * applyPattern(), with variables substituted and whitespace 300 * removed. For sets constructed without applyPattern(), or 301 * modified using the non-pattern API, this string will be empty, 302 * indicating that toPattern() must generate a pattern 303 * representation from the inversion list. 304 */ 305 char16_t *pat = nullptr; 306 int32_t patLen = 0; 307 308 UVector* strings = nullptr; // maintained in sorted order 309 UnicodeSetStringSpan *stringSpan = nullptr; 310 311 /** 312 * Initial list array. 313 * Avoids some heap allocations, and list is never nullptr. 314 * Increases the object size a bit. 315 */ 316 UChar32 stackList[INITIAL_CAPACITY]; 317 318 public: 319 /** 320 * Determine if this object contains a valid set. 321 * A bogus set has no value. It is different from an empty set. 322 * It can be used to indicate that no set value is available. 323 * 324 * @return TRUE if the set is bogus/invalid, FALSE otherwise 325 * @see setToBogus() 326 * @stable ICU 4.0 327 */ 328 inline UBool isBogus(void) const; 329 330 /** 331 * Make this UnicodeSet object invalid. 332 * The string will test TRUE with isBogus(). 333 * 334 * A bogus set has no value. It is different from an empty set. 335 * It can be used to indicate that no set value is available. 336 * 337 * This utility function is used throughout the UnicodeSet 338 * implementation to indicate that a UnicodeSet operation failed, 339 * and may be used in other functions, 340 * especially but not exclusively when such functions do not 341 * take a UErrorCode for simplicity. 342 * 343 * @see isBogus() 344 * @stable ICU 4.0 345 */ 346 void setToBogus(); 347 348 public: 349 350 enum { 351 /** 352 * Minimum value that can be stored in a UnicodeSet. 353 * @stable ICU 2.4 354 */ 355 MIN_VALUE = 0, 356 357 /** 358 * Maximum value that can be stored in a UnicodeSet. 359 * @stable ICU 2.4 360 */ 361 MAX_VALUE = 0x10ffff 362 }; 363 364 //---------------------------------------------------------------- 365 // Constructors &c 366 //---------------------------------------------------------------- 367 368 public: 369 370 /** 371 * Constructs an empty set. 372 * @stable ICU 2.0 373 */ 374 UnicodeSet(); 375 376 /** 377 * Constructs a set containing the given range. If <code>end < 378 * start</code> then an empty set is created. 379 * 380 * @param start first character, inclusive, of range 381 * @param end last character, inclusive, of range 382 * @stable ICU 2.4 383 */ 384 UnicodeSet(UChar32 start, UChar32 end); 385 386 #ifndef U_HIDE_INTERNAL_API 387 /** 388 * @internal 389 */ 390 enum ESerialization { 391 kSerialized /* result of serialize() */ 392 }; 393 394 /** 395 * Constructs a set from the output of serialize(). 396 * 397 * @param buffer the 16 bit array 398 * @param bufferLen the original length returned from serialize() 399 * @param serialization the value 'kSerialized' 400 * @param status error code 401 * 402 * @internal 403 */ 404 UnicodeSet(const uint16_t buffer[], int32_t bufferLen, 405 ESerialization serialization, UErrorCode &status); 406 #endif /* U_HIDE_INTERNAL_API */ 407 408 /** 409 * Constructs a set from the given pattern. See the class 410 * description for the syntax of the pattern language. 411 * @param pattern a string specifying what characters are in the set 412 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern 413 * contains a syntax error. 414 * @stable ICU 2.0 415 */ 416 UnicodeSet(const UnicodeString& pattern, 417 UErrorCode& status); 418 419 #ifndef U_HIDE_INTERNAL_API 420 /** 421 * Constructs a set from the given pattern. See the class 422 * description for the syntax of the pattern language. 423 * @param pattern a string specifying what characters are in the set 424 * @param options bitmask for options to apply to the pattern. 425 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE. 426 * @param symbols a symbol table mapping variable names to values 427 * and stand-in characters to UnicodeSets; may be NULL 428 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern 429 * contains a syntax error. 430 * @internal 431 */ 432 UnicodeSet(const UnicodeString& pattern, 433 uint32_t options, 434 const SymbolTable* symbols, 435 UErrorCode& status); 436 #endif /* U_HIDE_INTERNAL_API */ 437 438 /** 439 * Constructs a set from the given pattern. See the class description 440 * for the syntax of the pattern language. 441 * @param pattern a string specifying what characters are in the set 442 * @param pos on input, the position in pattern at which to start parsing. 443 * On output, the position after the last character parsed. 444 * @param options bitmask for options to apply to the pattern. 445 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE. 446 * @param symbols a symbol table mapping variable names to values 447 * and stand-in characters to UnicodeSets; may be NULL 448 * @param status input-output error code 449 * @stable ICU 2.8 450 */ 451 UnicodeSet(const UnicodeString& pattern, ParsePosition& pos, 452 uint32_t options, 453 const SymbolTable* symbols, 454 UErrorCode& status); 455 456 /** 457 * Constructs a set that is identical to the given UnicodeSet. 458 * @stable ICU 2.0 459 */ 460 UnicodeSet(const UnicodeSet& o); 461 462 /** 463 * Destructs the set. 464 * @stable ICU 2.0 465 */ 466 virtual ~UnicodeSet(); 467 468 /** 469 * Assigns this object to be a copy of another. 470 * A frozen set will not be modified. 471 * @stable ICU 2.0 472 */ 473 UnicodeSet& operator=(const UnicodeSet& o); 474 475 /** 476 * Compares the specified object with this set for equality. Returns 477 * <tt>true</tt> if the two sets 478 * have the same size, and every member of the specified set is 479 * contained in this set (or equivalently, every member of this set is 480 * contained in the specified set). 481 * 482 * @param o set to be compared for equality with this set. 483 * @return <tt>true</tt> if the specified set is equal to this set. 484 * @stable ICU 2.0 485 */ 486 virtual UBool operator==(const UnicodeSet& o) const; 487 488 /** 489 * Compares the specified object with this set for equality. Returns 490 * <tt>true</tt> if the specified set is not equal to this set. 491 * @stable ICU 2.0 492 */ 493 UBool operator!=(const UnicodeSet& o) const; 494 495 /** 496 * Returns a copy of this object. All UnicodeFunctor objects have 497 * to support cloning in order to allow classes using 498 * UnicodeFunctors, such as Transliterator, to implement cloning. 499 * If this set is frozen, then the clone will be frozen as well. 500 * Use cloneAsThawed() for a mutable clone of a frozen set. 501 * @see cloneAsThawed 502 * @stable ICU 2.0 503 */ 504 virtual UnicodeFunctor* clone() const; 505 506 /** 507 * Returns the hash code value for this set. 508 * 509 * @return the hash code value for this set. 510 * @see Object#hashCode() 511 * @stable ICU 2.0 512 */ 513 virtual int32_t hashCode(void) const; 514 515 /** 516 * Get a UnicodeSet pointer from a USet 517 * 518 * @param uset a USet (the ICU plain C type for UnicodeSet) 519 * @return the corresponding UnicodeSet pointer. 520 * 521 * @stable ICU 4.2 522 */ 523 inline static UnicodeSet *fromUSet(USet *uset); 524 525 /** 526 * Get a UnicodeSet pointer from a const USet 527 * 528 * @param uset a const USet (the ICU plain C type for UnicodeSet) 529 * @return the corresponding UnicodeSet pointer. 530 * 531 * @stable ICU 4.2 532 */ 533 inline static const UnicodeSet *fromUSet(const USet *uset); 534 535 /** 536 * Produce a USet * pointer for this UnicodeSet. 537 * USet is the plain C type for UnicodeSet 538 * 539 * @return a USet pointer for this UnicodeSet 540 * @stable ICU 4.2 541 */ 542 inline USet *toUSet(); 543 544 545 /** 546 * Produce a const USet * pointer for this UnicodeSet. 547 * USet is the plain C type for UnicodeSet 548 * 549 * @return a const USet pointer for this UnicodeSet 550 * @stable ICU 4.2 551 */ 552 inline const USet * toUSet() const; 553 554 555 //---------------------------------------------------------------- 556 // Freezable API 557 //---------------------------------------------------------------- 558 559 /** 560 * Determines whether the set has been frozen (made immutable) or not. 561 * See the ICU4J Freezable interface for details. 562 * @return TRUE/FALSE for whether the set has been frozen 563 * @see freeze 564 * @see cloneAsThawed 565 * @stable ICU 3.8 566 */ 567 inline UBool isFrozen() const; 568 569 /** 570 * Freeze the set (make it immutable). 571 * Once frozen, it cannot be unfrozen and is therefore thread-safe 572 * until it is deleted. 573 * See the ICU4J Freezable interface for details. 574 * Freezing the set may also make some operations faster, for example 575 * contains() and span(). 576 * A frozen set will not be modified. (It remains frozen.) 577 * @return this set. 578 * @see isFrozen 579 * @see cloneAsThawed 580 * @stable ICU 3.8 581 */ 582 UnicodeFunctor *freeze(); 583 584 /** 585 * Clone the set and make the clone mutable. 586 * See the ICU4J Freezable interface for details. 587 * @return the mutable clone 588 * @see freeze 589 * @see isFrozen 590 * @stable ICU 3.8 591 */ 592 UnicodeFunctor *cloneAsThawed() const; 593 594 //---------------------------------------------------------------- 595 // Public API 596 //---------------------------------------------------------------- 597 598 /** 599 * Make this object represent the range `start - end`. 600 * If `end > start` then this object is set to an empty range. 601 * A frozen set will not be modified. 602 * 603 * @param start first character in the set, inclusive 604 * @param end last character in the set, inclusive 605 * @stable ICU 2.4 606 */ 607 UnicodeSet& set(UChar32 start, UChar32 end); 608 609 /** 610 * Return true if the given position, in the given pattern, appears 611 * to be the start of a UnicodeSet pattern. 612 * @stable ICU 2.4 613 */ 614 static UBool resemblesPattern(const UnicodeString& pattern, 615 int32_t pos); 616 617 /** 618 * Modifies this set to represent the set specified by the given 619 * pattern, ignoring Unicode Pattern_White_Space characters. 620 * See the class description for the syntax of the pattern language. 621 * A frozen set will not be modified. 622 * @param pattern a string specifying what characters are in the set 623 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern 624 * contains a syntax error. 625 * <em> Empties the set passed before applying the pattern.</em> 626 * @return a reference to this 627 * @stable ICU 2.0 628 */ 629 UnicodeSet& applyPattern(const UnicodeString& pattern, 630 UErrorCode& status); 631 632 #ifndef U_HIDE_INTERNAL_API 633 /** 634 * Modifies this set to represent the set specified by the given 635 * pattern, optionally ignoring Unicode Pattern_White_Space characters. 636 * See the class description for the syntax of the pattern language. 637 * A frozen set will not be modified. 638 * @param pattern a string specifying what characters are in the set 639 * @param options bitmask for options to apply to the pattern. 640 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE. 641 * @param symbols a symbol table mapping variable names to 642 * values and stand-ins to UnicodeSets; may be NULL 643 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern 644 * contains a syntax error. 645 *<em> Empties the set passed before applying the pattern.</em> 646 * @return a reference to this 647 * @internal 648 */ 649 UnicodeSet& applyPattern(const UnicodeString& pattern, 650 uint32_t options, 651 const SymbolTable* symbols, 652 UErrorCode& status); 653 #endif /* U_HIDE_INTERNAL_API */ 654 655 /** 656 * Parses the given pattern, starting at the given position. The 657 * character at pattern.charAt(pos.getIndex()) must be '[', or the 658 * parse fails. Parsing continues until the corresponding closing 659 * ']'. If a syntax error is encountered between the opening and 660 * closing brace, the parse fails. Upon return from a successful 661 * parse, the ParsePosition is updated to point to the character 662 * following the closing ']', and a StringBuffer containing a 663 * pairs list for the parsed pattern is returned. This method calls 664 * itself recursively to parse embedded subpatterns. 665 *<em> Empties the set passed before applying the pattern.</em> 666 * A frozen set will not be modified. 667 * 668 * @param pattern the string containing the pattern to be parsed. 669 * The portion of the string from pos.getIndex(), which must be a 670 * '[', to the corresponding closing ']', is parsed. 671 * @param pos upon entry, the position at which to being parsing. 672 * The character at pattern.charAt(pos.getIndex()) must be a '['. 673 * Upon return from a successful parse, pos.getIndex() is either 674 * the character after the closing ']' of the parsed pattern, or 675 * pattern.length() if the closing ']' is the last character of 676 * the pattern string. 677 * @param options bitmask for options to apply to the pattern. 678 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE. 679 * @param symbols a symbol table mapping variable names to 680 * values and stand-ins to UnicodeSets; may be NULL 681 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern 682 * contains a syntax error. 683 * @return a reference to this 684 * @stable ICU 2.8 685 */ 686 UnicodeSet& applyPattern(const UnicodeString& pattern, 687 ParsePosition& pos, 688 uint32_t options, 689 const SymbolTable* symbols, 690 UErrorCode& status); 691 692 /** 693 * Returns a string representation of this set. If the result of 694 * calling this function is passed to a UnicodeSet constructor, it 695 * will produce another set that is equal to this one. 696 * A frozen set will not be modified. 697 * @param result the string to receive the rules. Previous 698 * contents will be deleted. 699 * @param escapeUnprintable if TRUE then convert unprintable 700 * character to their hex escape representations, \\uxxxx or 701 * \\Uxxxxxxxx. Unprintable characters are those other than 702 * U+000A, U+0020..U+007E. 703 * @stable ICU 2.0 704 */ 705 virtual UnicodeString& toPattern(UnicodeString& result, 706 UBool escapeUnprintable = FALSE) const; 707 708 /** 709 * Modifies this set to contain those code points which have the given value 710 * for the given binary or enumerated property, as returned by 711 * u_getIntPropertyValue. Prior contents of this set are lost. 712 * A frozen set will not be modified. 713 * 714 * @param prop a property in the range UCHAR_BIN_START..UCHAR_BIN_LIMIT-1 715 * or UCHAR_INT_START..UCHAR_INT_LIMIT-1 716 * or UCHAR_MASK_START..UCHAR_MASK_LIMIT-1. 717 * 718 * @param value a value in the range u_getIntPropertyMinValue(prop).. 719 * u_getIntPropertyMaxValue(prop), with one exception. If prop is 720 * UCHAR_GENERAL_CATEGORY_MASK, then value should not be a UCharCategory, but 721 * rather a mask value produced by U_GET_GC_MASK(). This allows grouped 722 * categories such as [:L:] to be represented. 723 * 724 * @param ec error code input/output parameter 725 * 726 * @return a reference to this set 727 * 728 * @stable ICU 2.4 729 */ 730 UnicodeSet& applyIntPropertyValue(UProperty prop, 731 int32_t value, 732 UErrorCode& ec); 733 734 /** 735 * Modifies this set to contain those code points which have the 736 * given value for the given property. Prior contents of this 737 * set are lost. 738 * A frozen set will not be modified. 739 * 740 * @param prop a property alias, either short or long. The name is matched 741 * loosely. See PropertyAliases.txt for names and a description of loose 742 * matching. If the value string is empty, then this string is interpreted 743 * as either a General_Category value alias, a Script value alias, a binary 744 * property alias, or a special ID. Special IDs are matched loosely and 745 * correspond to the following sets: 746 * 747 * "ANY" = [\\u0000-\\U0010FFFF], 748 * "ASCII" = [\\u0000-\\u007F], 749 * "Assigned" = [:^Cn:]. 750 * 751 * @param value a value alias, either short or long. The name is matched 752 * loosely. See PropertyValueAliases.txt for names and a description of 753 * loose matching. In addition to aliases listed, numeric values and 754 * canonical combining classes may be expressed numerically, e.g., ("nv", 755 * "0.5") or ("ccc", "220"). The value string may also be empty. 756 * 757 * @param ec error code input/output parameter 758 * 759 * @return a reference to this set 760 * 761 * @stable ICU 2.4 762 */ 763 UnicodeSet& applyPropertyAlias(const UnicodeString& prop, 764 const UnicodeString& value, 765 UErrorCode& ec); 766 767 /** 768 * Returns the number of elements in this set (its cardinality). 769 * Note than the elements of a set may include both individual 770 * codepoints and strings. 771 * 772 * @return the number of elements in this set (its cardinality). 773 * @stable ICU 2.0 774 */ 775 virtual int32_t size(void) const; 776 777 /** 778 * Returns <tt>true</tt> if this set contains no elements. 779 * 780 * @return <tt>true</tt> if this set contains no elements. 781 * @stable ICU 2.0 782 */ 783 virtual UBool isEmpty(void) const; 784 785 /** 786 * Returns true if this set contains the given character. 787 * This function works faster with a frozen set. 788 * @param c character to be checked for containment 789 * @return true if the test condition is met 790 * @stable ICU 2.0 791 */ 792 virtual UBool contains(UChar32 c) const; 793 794 /** 795 * Returns true if this set contains every character 796 * of the given range. 797 * @param start first character, inclusive, of the range 798 * @param end last character, inclusive, of the range 799 * @return true if the test condition is met 800 * @stable ICU 2.0 801 */ 802 virtual UBool contains(UChar32 start, UChar32 end) const; 803 804 /** 805 * Returns <tt>true</tt> if this set contains the given 806 * multicharacter string. 807 * @param s string to be checked for containment 808 * @return <tt>true</tt> if this set contains the specified string 809 * @stable ICU 2.4 810 */ 811 UBool contains(const UnicodeString& s) const; 812 813 /** 814 * Returns true if this set contains all the characters and strings 815 * of the given set. 816 * @param c set to be checked for containment 817 * @return true if the test condition is met 818 * @stable ICU 2.4 819 */ 820 virtual UBool containsAll(const UnicodeSet& c) const; 821 822 /** 823 * Returns true if this set contains all the characters 824 * of the given string. 825 * @param s string containing characters to be checked for containment 826 * @return true if the test condition is met 827 * @stable ICU 2.4 828 */ 829 UBool containsAll(const UnicodeString& s) const; 830 831 /** 832 * Returns true if this set contains none of the characters 833 * of the given range. 834 * @param start first character, inclusive, of the range 835 * @param end last character, inclusive, of the range 836 * @return true if the test condition is met 837 * @stable ICU 2.4 838 */ 839 UBool containsNone(UChar32 start, UChar32 end) const; 840 841 /** 842 * Returns true if this set contains none of the characters and strings 843 * of the given set. 844 * @param c set to be checked for containment 845 * @return true if the test condition is met 846 * @stable ICU 2.4 847 */ 848 UBool containsNone(const UnicodeSet& c) const; 849 850 /** 851 * Returns true if this set contains none of the characters 852 * of the given string. 853 * @param s string containing characters to be checked for containment 854 * @return true if the test condition is met 855 * @stable ICU 2.4 856 */ 857 UBool containsNone(const UnicodeString& s) const; 858 859 /** 860 * Returns true if this set contains one or more of the characters 861 * in the given range. 862 * @param start first character, inclusive, of the range 863 * @param end last character, inclusive, of the range 864 * @return true if the condition is met 865 * @stable ICU 2.4 866 */ 867 inline UBool containsSome(UChar32 start, UChar32 end) const; 868 869 /** 870 * Returns true if this set contains one or more of the characters 871 * and strings of the given set. 872 * @param s The set to be checked for containment 873 * @return true if the condition is met 874 * @stable ICU 2.4 875 */ 876 inline UBool containsSome(const UnicodeSet& s) const; 877 878 /** 879 * Returns true if this set contains one or more of the characters 880 * of the given string. 881 * @param s string containing characters to be checked for containment 882 * @return true if the condition is met 883 * @stable ICU 2.4 884 */ 885 inline UBool containsSome(const UnicodeString& s) const; 886 887 /** 888 * Returns the length of the initial substring of the input string which 889 * consists only of characters and strings that are contained in this set 890 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), 891 * or only of characters and strings that are not contained 892 * in this set (USET_SPAN_NOT_CONTAINED). 893 * See USetSpanCondition for details. 894 * Similar to the strspn() C library function. 895 * Unpaired surrogates are treated according to contains() of their surrogate code points. 896 * This function works faster with a frozen set and with a non-negative string length argument. 897 * @param s start of the string 898 * @param length of the string; can be -1 for NUL-terminated 899 * @param spanCondition specifies the containment condition 900 * @return the length of the initial substring according to the spanCondition; 901 * 0 if the start of the string does not fit the spanCondition 902 * @stable ICU 3.8 903 * @see USetSpanCondition 904 */ 905 int32_t span(const char16_t *s, int32_t length, USetSpanCondition spanCondition) const; 906 907 /** 908 * Returns the end of the substring of the input string according to the USetSpanCondition. 909 * Same as <code>start+span(s.getBuffer()+start, s.length()-start, spanCondition)</code> 910 * after pinning start to 0<=start<=s.length(). 911 * @param s the string 912 * @param start the start index in the string for the span operation 913 * @param spanCondition specifies the containment condition 914 * @return the exclusive end of the substring according to the spanCondition; 915 * the substring s.tempSubStringBetween(start, end) fulfills the spanCondition 916 * @stable ICU 4.4 917 * @see USetSpanCondition 918 */ 919 inline int32_t span(const UnicodeString &s, int32_t start, USetSpanCondition spanCondition) const; 920 921 /** 922 * Returns the start of the trailing substring of the input string which 923 * consists only of characters and strings that are contained in this set 924 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), 925 * or only of characters and strings that are not contained 926 * in this set (USET_SPAN_NOT_CONTAINED). 927 * See USetSpanCondition for details. 928 * Unpaired surrogates are treated according to contains() of their surrogate code points. 929 * This function works faster with a frozen set and with a non-negative string length argument. 930 * @param s start of the string 931 * @param length of the string; can be -1 for NUL-terminated 932 * @param spanCondition specifies the containment condition 933 * @return the start of the trailing substring according to the spanCondition; 934 * the string length if the end of the string does not fit the spanCondition 935 * @stable ICU 3.8 936 * @see USetSpanCondition 937 */ 938 int32_t spanBack(const char16_t *s, int32_t length, USetSpanCondition spanCondition) const; 939 940 /** 941 * Returns the start of the substring of the input string according to the USetSpanCondition. 942 * Same as <code>spanBack(s.getBuffer(), limit, spanCondition)</code> 943 * after pinning limit to 0<=end<=s.length(). 944 * @param s the string 945 * @param limit the exclusive-end index in the string for the span operation 946 * (use s.length() or INT32_MAX for spanning back from the end of the string) 947 * @param spanCondition specifies the containment condition 948 * @return the start of the substring according to the spanCondition; 949 * the substring s.tempSubStringBetween(start, limit) fulfills the spanCondition 950 * @stable ICU 4.4 951 * @see USetSpanCondition 952 */ 953 inline int32_t spanBack(const UnicodeString &s, int32_t limit, USetSpanCondition spanCondition) const; 954 955 /** 956 * Returns the length of the initial substring of the input string which 957 * consists only of characters and strings that are contained in this set 958 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE), 959 * or only of characters and strings that are not contained 960 * in this set (USET_SPAN_NOT_CONTAINED). 961 * See USetSpanCondition for details. 962 * Similar to the strspn() C library function. 963 * Malformed byte sequences are treated according to contains(0xfffd). 964 * This function works faster with a frozen set and with a non-negative string length argument. 965 * @param s start of the string (UTF-8) 966 * @param length of the string; can be -1 for NUL-terminated 967 * @param spanCondition specifies the containment condition 968 * @return the length of the initial substring according to the spanCondition; 969 * 0 if the start of the string does not fit the spanCondition 970 * @stable ICU 3.8 971 * @see USetSpanCondition 972 */ 973 int32_t spanUTF8(const char *s, int32_t length, USetSpanCondition spanCondition) const; 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 s start of the string (UTF-8) 985 * @param length of the string; can be -1 for NUL-terminated 986 * @param spanCondition specifies the containment condition 987 * @return the start of the trailing substring according to the spanCondition; 988 * the string length if the end of the string does not fit the spanCondition 989 * @stable ICU 3.8 990 * @see USetSpanCondition 991 */ 992 int32_t spanBackUTF8(const char *s, int32_t length, USetSpanCondition spanCondition) const; 993 994 /** 995 * Implement UnicodeMatcher::matches() 996 * @stable ICU 2.4 997 */ 998 virtual UMatchDegree matches(const Replaceable& text, 999 int32_t& offset, 1000 int32_t limit, 1001 UBool incremental); 1002 1003 private: 1004 /** 1005 * Returns the longest match for s in text at the given position. 1006 * If limit > start then match forward from start+1 to limit 1007 * matching all characters except s.charAt(0). If limit < start, 1008 * go backward starting from start-1 matching all characters 1009 * except s.charAt(s.length()-1). This method assumes that the 1010 * first character, text.charAt(start), matches s, so it does not 1011 * check it. 1012 * @param text the text to match 1013 * @param start the first character to match. In the forward 1014 * direction, text.charAt(start) is matched against s.charAt(0). 1015 * In the reverse direction, it is matched against 1016 * s.charAt(s.length()-1). 1017 * @param limit the limit offset for matching, either last+1 in 1018 * the forward direction, or last-1 in the reverse direction, 1019 * where last is the index of the last character to match. 1020 * @param s 1021 * @return If part of s matches up to the limit, return |limit - 1022 * start|. If all of s matches before reaching the limit, return 1023 * s.length(). If there is a mismatch between s and text, return 1024 * 0 1025 */ 1026 static int32_t matchRest(const Replaceable& text, 1027 int32_t start, int32_t limit, 1028 const UnicodeString& s); 1029 1030 /** 1031 * Returns the smallest value i such that c < list[i]. Caller 1032 * must ensure that c is a legal value or this method will enter 1033 * an infinite loop. This method performs a binary search. 1034 * @param c a character in the range MIN_VALUE..MAX_VALUE 1035 * inclusive 1036 * @return the smallest integer i in the range 0..len-1, 1037 * inclusive, such that c < list[i] 1038 */ 1039 int32_t findCodePoint(UChar32 c) const; 1040 1041 public: 1042 1043 /** 1044 * Implementation of UnicodeMatcher API. Union the set of all 1045 * characters that may be matched by this object into the given 1046 * set. 1047 * @param toUnionTo the set into which to union the source characters 1048 * @stable ICU 2.4 1049 */ 1050 virtual void addMatchSetTo(UnicodeSet& toUnionTo) const; 1051 1052 /** 1053 * Returns the index of the given character within this set, where 1054 * the set is ordered by ascending code point. If the character 1055 * is not in this set, return -1. The inverse of this method is 1056 * <code>charAt()</code>. 1057 * @return an index from 0..size()-1, or -1 1058 * @stable ICU 2.4 1059 */ 1060 int32_t indexOf(UChar32 c) const; 1061 1062 /** 1063 * Returns the character at the given index within this set, where 1064 * the set is ordered by ascending code point. If the index is 1065 * out of range, return (UChar32)-1. The inverse of this method is 1066 * <code>indexOf()</code>. 1067 * @param index an index from 0..size()-1 1068 * @return the character at the given index, or (UChar32)-1. 1069 * @stable ICU 2.4 1070 */ 1071 UChar32 charAt(int32_t index) const; 1072 1073 /** 1074 * Adds the specified range to this set if it is not already 1075 * present. If this set already contains the specified range, 1076 * the call leaves this set unchanged. If <code>end > start</code> 1077 * then an empty range is added, leaving the set unchanged. 1078 * This is equivalent to a boolean logic OR, or a set UNION. 1079 * A frozen set will not be modified. 1080 * 1081 * @param start first character, inclusive, of range to be added 1082 * to this set. 1083 * @param end last character, inclusive, of range to be added 1084 * to this set. 1085 * @stable ICU 2.0 1086 */ 1087 virtual UnicodeSet& add(UChar32 start, UChar32 end); 1088 1089 /** 1090 * Adds the specified character to this set if it is not already 1091 * present. If this set already contains the specified character, 1092 * the call leaves this set unchanged. 1093 * A frozen set will not be modified. 1094 * @stable ICU 2.0 1095 */ 1096 UnicodeSet& add(UChar32 c); 1097 1098 /** 1099 * Adds the specified multicharacter to this set if it is not already 1100 * present. If this set already contains the multicharacter, 1101 * the call leaves this set unchanged. 1102 * Thus "ch" => {"ch"} 1103 * <br><b>Warning: you cannot add an empty string ("") to a UnicodeSet.</b> 1104 * A frozen set will not be modified. 1105 * @param s the source string 1106 * @return this object, for chaining 1107 * @stable ICU 2.4 1108 */ 1109 UnicodeSet& add(const UnicodeString& s); 1110 1111 private: 1112 /** 1113 * @return a code point IF the string consists of a single one. 1114 * otherwise returns -1. 1115 * @param s string to test 1116 */ 1117 static int32_t getSingleCP(const UnicodeString& s); 1118 1119 void _add(const UnicodeString& s); 1120 1121 public: 1122 /** 1123 * Adds each of the characters in this string to the set. Thus "ch" => {"c", "h"} 1124 * If this set already any particular character, it has no effect on that character. 1125 * A frozen set will not be modified. 1126 * @param s the source string 1127 * @return this object, for chaining 1128 * @stable ICU 2.4 1129 */ 1130 UnicodeSet& addAll(const UnicodeString& s); 1131 1132 /** 1133 * Retains EACH of the characters in this string. Note: "ch" == {"c", "h"} 1134 * If this set already any particular character, it has no effect on that character. 1135 * A frozen set will not be modified. 1136 * @param s the source string 1137 * @return this object, for chaining 1138 * @stable ICU 2.4 1139 */ 1140 UnicodeSet& retainAll(const UnicodeString& s); 1141 1142 /** 1143 * Complement EACH of the characters in this string. Note: "ch" == {"c", "h"} 1144 * If this set already any particular character, it has no effect on that character. 1145 * A frozen set will not be modified. 1146 * @param s the source string 1147 * @return this object, for chaining 1148 * @stable ICU 2.4 1149 */ 1150 UnicodeSet& complementAll(const UnicodeString& s); 1151 1152 /** 1153 * Remove EACH of the characters in this string. Note: "ch" == {"c", "h"} 1154 * If this set already any particular character, it has no effect on that character. 1155 * A frozen set will not be modified. 1156 * @param s the source string 1157 * @return this object, for chaining 1158 * @stable ICU 2.4 1159 */ 1160 UnicodeSet& removeAll(const UnicodeString& s); 1161 1162 /** 1163 * Makes a set from a multicharacter string. Thus "ch" => {"ch"} 1164 * <br><b>Warning: you cannot add an empty string ("") to a UnicodeSet.</b> 1165 * @param s the source string 1166 * @return a newly created set containing the given string. 1167 * The caller owns the return object and is responsible for deleting it. 1168 * @stable ICU 2.4 1169 */ 1170 static UnicodeSet* U_EXPORT2 createFrom(const UnicodeString& s); 1171 1172 1173 /** 1174 * Makes a set from each of the characters in the string. Thus "ch" => {"c", "h"} 1175 * @param s the source string 1176 * @return a newly created set containing the given characters 1177 * The caller owns the return object and is responsible for deleting it. 1178 * @stable ICU 2.4 1179 */ 1180 static UnicodeSet* U_EXPORT2 createFromAll(const UnicodeString& s); 1181 1182 /** 1183 * Retain only the elements in this set that are contained in the 1184 * specified range. If <code>end > start</code> then an empty range is 1185 * retained, leaving the set empty. This is equivalent to 1186 * a boolean logic AND, or a set INTERSECTION. 1187 * A frozen set will not be modified. 1188 * 1189 * @param start first character, inclusive, of range to be retained 1190 * to this set. 1191 * @param end last character, inclusive, of range to be retained 1192 * to this set. 1193 * @stable ICU 2.0 1194 */ 1195 virtual UnicodeSet& retain(UChar32 start, UChar32 end); 1196 1197 1198 /** 1199 * Retain the specified character from this set if it is present. 1200 * A frozen set will not be modified. 1201 * @stable ICU 2.0 1202 */ 1203 UnicodeSet& retain(UChar32 c); 1204 1205 /** 1206 * Removes the specified range from this set if it is present. 1207 * The set will not contain the specified range once the call 1208 * returns. If <code>end > start</code> then an empty range is 1209 * removed, leaving the set unchanged. 1210 * A frozen set will not be modified. 1211 * 1212 * @param start first character, inclusive, of range to be removed 1213 * from this set. 1214 * @param end last character, inclusive, of range to be removed 1215 * from this set. 1216 * @stable ICU 2.0 1217 */ 1218 virtual UnicodeSet& remove(UChar32 start, UChar32 end); 1219 1220 /** 1221 * Removes the specified character from this set if it is present. 1222 * The set will not contain the specified range once the call 1223 * returns. 1224 * A frozen set will not be modified. 1225 * @stable ICU 2.0 1226 */ 1227 UnicodeSet& remove(UChar32 c); 1228 1229 /** 1230 * Removes the specified string from this set if it is present. 1231 * The set will not contain the specified character once the call 1232 * returns. 1233 * A frozen set will not be modified. 1234 * @param s the source string 1235 * @return this object, for chaining 1236 * @stable ICU 2.4 1237 */ 1238 UnicodeSet& remove(const UnicodeString& s); 1239 1240 /** 1241 * Inverts this set. This operation modifies this set so that 1242 * its value is its complement. This is equivalent to 1243 * <code>complement(MIN_VALUE, MAX_VALUE)</code>. 1244 * A frozen set will not be modified. 1245 * @stable ICU 2.0 1246 */ 1247 virtual UnicodeSet& complement(void); 1248 1249 /** 1250 * Complements the specified range in this set. Any character in 1251 * the range will be removed if it is in this set, or will be 1252 * added if it is not in this set. If <code>end > start</code> 1253 * then an empty range is complemented, leaving the set unchanged. 1254 * This is equivalent to a boolean logic XOR. 1255 * A frozen set will not be modified. 1256 * 1257 * @param start first character, inclusive, of range to be removed 1258 * from this set. 1259 * @param end last character, inclusive, of range to be removed 1260 * from this set. 1261 * @stable ICU 2.0 1262 */ 1263 virtual UnicodeSet& complement(UChar32 start, UChar32 end); 1264 1265 /** 1266 * Complements the specified character in this set. The character 1267 * will be removed if it is in this set, or will be added if it is 1268 * not in this set. 1269 * A frozen set will not be modified. 1270 * @stable ICU 2.0 1271 */ 1272 UnicodeSet& complement(UChar32 c); 1273 1274 /** 1275 * Complement the specified string in this set. 1276 * The set will not contain the specified string once the call 1277 * returns. 1278 * <br><b>Warning: you cannot add an empty string ("") to a UnicodeSet.</b> 1279 * A frozen set will not be modified. 1280 * @param s the string to complement 1281 * @return this object, for chaining 1282 * @stable ICU 2.4 1283 */ 1284 UnicodeSet& complement(const UnicodeString& s); 1285 1286 /** 1287 * Adds all of the elements in the specified set to this set if 1288 * they're not already present. This operation effectively 1289 * modifies this set so that its value is the <i>union</i> of the two 1290 * sets. The behavior of this operation is unspecified if the specified 1291 * collection is modified while the operation is in progress. 1292 * A frozen set will not be modified. 1293 * 1294 * @param c set whose elements are to be added to this set. 1295 * @see #add(UChar32, UChar32) 1296 * @stable ICU 2.0 1297 */ 1298 virtual UnicodeSet& addAll(const UnicodeSet& c); 1299 1300 /** 1301 * Retains only the elements in this set that are contained in the 1302 * specified set. In other words, removes from this set all of 1303 * its elements that are not contained in the specified set. This 1304 * operation effectively modifies this set so that its value is 1305 * the <i>intersection</i> of the two sets. 1306 * A frozen set will not be modified. 1307 * 1308 * @param c set that defines which elements this set will retain. 1309 * @stable ICU 2.0 1310 */ 1311 virtual UnicodeSet& retainAll(const UnicodeSet& c); 1312 1313 /** 1314 * Removes from this set all of its elements that are contained in the 1315 * specified set. This operation effectively modifies this 1316 * set so that its value is the <i>asymmetric set difference</i> of 1317 * the two sets. 1318 * A frozen set will not be modified. 1319 * 1320 * @param c set that defines which elements will be removed from 1321 * this set. 1322 * @stable ICU 2.0 1323 */ 1324 virtual UnicodeSet& removeAll(const UnicodeSet& c); 1325 1326 /** 1327 * Complements in this set all elements contained in the specified 1328 * set. Any character in the other set will be removed if it is 1329 * in this set, or will be added if it is not in this set. 1330 * A frozen set will not be modified. 1331 * 1332 * @param c set that defines which elements will be xor'ed from 1333 * this set. 1334 * @stable ICU 2.4 1335 */ 1336 virtual UnicodeSet& complementAll(const UnicodeSet& c); 1337 1338 /** 1339 * Removes all of the elements from this set. This set will be 1340 * empty after this call returns. 1341 * A frozen set will not be modified. 1342 * @stable ICU 2.0 1343 */ 1344 virtual UnicodeSet& clear(void); 1345 1346 /** 1347 * Close this set over the given attribute. For the attribute 1348 * USET_CASE, the result is to modify this set so that: 1349 * 1350 * 1. For each character or string 'a' in this set, all strings or 1351 * characters 'b' such that foldCase(a) == foldCase(b) are added 1352 * to this set. 1353 * 1354 * 2. For each string 'e' in the resulting set, if e != 1355 * foldCase(e), 'e' will be removed. 1356 * 1357 * Example: [aq\\u00DF{Bc}{bC}{Fi}] => [aAqQ\\u00DF\\uFB01{ss}{bc}{fi}] 1358 * 1359 * (Here foldCase(x) refers to the operation u_strFoldCase, and a 1360 * == b denotes that the contents are the same, not pointer 1361 * comparison.) 1362 * 1363 * A frozen set will not be modified. 1364 * 1365 * @param attribute bitmask for attributes to close over. 1366 * Currently only the USET_CASE bit is supported. Any undefined bits 1367 * are ignored. 1368 * @return a reference to this set. 1369 * @stable ICU 4.2 1370 */ 1371 UnicodeSet& closeOver(int32_t attribute); 1372 1373 /** 1374 * Remove all strings from this set. 1375 * 1376 * @return a reference to this set. 1377 * @stable ICU 4.2 1378 */ 1379 virtual UnicodeSet &removeAllStrings(); 1380 1381 /** 1382 * Iteration method that returns the number of ranges contained in 1383 * this set. 1384 * @see #getRangeStart 1385 * @see #getRangeEnd 1386 * @stable ICU 2.4 1387 */ 1388 virtual int32_t getRangeCount(void) const; 1389 1390 /** 1391 * Iteration method that returns the first character in the 1392 * specified range of this set. 1393 * @see #getRangeCount 1394 * @see #getRangeEnd 1395 * @stable ICU 2.4 1396 */ 1397 virtual UChar32 getRangeStart(int32_t index) const; 1398 1399 /** 1400 * Iteration method that returns the last character in the 1401 * specified range of this set. 1402 * @see #getRangeStart 1403 * @see #getRangeEnd 1404 * @stable ICU 2.4 1405 */ 1406 virtual UChar32 getRangeEnd(int32_t index) const; 1407 1408 /** 1409 * Serializes this set into an array of 16-bit integers. Serialization 1410 * (currently) only records the characters in the set; multicharacter 1411 * strings are ignored. 1412 * 1413 * The array has following format (each line is one 16-bit 1414 * integer): 1415 * 1416 * length = (n+2*m) | (m!=0?0x8000:0) 1417 * bmpLength = n; present if m!=0 1418 * bmp[0] 1419 * bmp[1] 1420 * ... 1421 * bmp[n-1] 1422 * supp-high[0] 1423 * supp-low[0] 1424 * supp-high[1] 1425 * supp-low[1] 1426 * ... 1427 * supp-high[m-1] 1428 * supp-low[m-1] 1429 * 1430 * The array starts with a header. After the header are n bmp 1431 * code points, then m supplementary code points. Either n or m 1432 * or both may be zero. n+2*m is always <= 0x7FFF. 1433 * 1434 * If there are no supplementary characters (if m==0) then the 1435 * header is one 16-bit integer, 'length', with value n. 1436 * 1437 * If there are supplementary characters (if m!=0) then the header 1438 * is two 16-bit integers. The first, 'length', has value 1439 * (n+2*m)|0x8000. The second, 'bmpLength', has value n. 1440 * 1441 * After the header the code points are stored in ascending order. 1442 * Supplementary code points are stored as most significant 16 1443 * bits followed by least significant 16 bits. 1444 * 1445 * @param dest pointer to buffer of destCapacity 16-bit integers. 1446 * May be NULL only if destCapacity is zero. 1447 * @param destCapacity size of dest, or zero. Must not be negative. 1448 * @param ec error code. Will be set to U_INDEX_OUTOFBOUNDS_ERROR 1449 * if n+2*m > 0x7FFF. Will be set to U_BUFFER_OVERFLOW_ERROR if 1450 * n+2*m+(m!=0?2:1) > destCapacity. 1451 * @return the total length of the serialized format, including 1452 * the header, that is, n+2*m+(m!=0?2:1), or 0 on error other 1453 * than U_BUFFER_OVERFLOW_ERROR. 1454 * @stable ICU 2.4 1455 */ 1456 int32_t serialize(uint16_t *dest, int32_t destCapacity, UErrorCode& ec) const; 1457 1458 /** 1459 * Reallocate this objects internal structures to take up the least 1460 * possible space, without changing this object's value. 1461 * A frozen set will not be modified. 1462 * @stable ICU 2.4 1463 */ 1464 virtual UnicodeSet& compact(); 1465 1466 /** 1467 * Return the class ID for this class. This is useful only for 1468 * comparing to a return value from getDynamicClassID(). For example: 1469 * <pre> 1470 * . Base* polymorphic_pointer = createPolymorphicObject(); 1471 * . if (polymorphic_pointer->getDynamicClassID() == 1472 * . Derived::getStaticClassID()) ... 1473 * </pre> 1474 * @return The class ID for all objects of this class. 1475 * @stable ICU 2.0 1476 */ 1477 static UClassID U_EXPORT2 getStaticClassID(void); 1478 1479 /** 1480 * Implement UnicodeFunctor API. 1481 * 1482 * @return The class ID for this object. All objects of a given 1483 * class have the same class ID. Objects of other classes have 1484 * different class IDs. 1485 * @stable ICU 2.4 1486 */ 1487 virtual UClassID getDynamicClassID(void) const; 1488 1489 private: 1490 1491 // Private API for the USet API 1492 1493 friend class USetAccess; 1494 1495 const UnicodeString* getString(int32_t index) const; 1496 1497 //---------------------------------------------------------------- 1498 // RuleBasedTransliterator support 1499 //---------------------------------------------------------------- 1500 1501 private: 1502 1503 /** 1504 * Returns <tt>true</tt> if this set contains any character whose low byte 1505 * is the given value. This is used by <tt>RuleBasedTransliterator</tt> for 1506 * indexing. 1507 */ 1508 virtual UBool matchesIndexValue(uint8_t v) const; 1509 1510 private: 1511 friend class RBBIRuleScanner; 1512 1513 //---------------------------------------------------------------- 1514 // Implementation: Clone as thawed (see ICU4J Freezable) 1515 //---------------------------------------------------------------- 1516 1517 UnicodeSet(const UnicodeSet& o, UBool /* asThawed */); 1518 UnicodeSet& copyFrom(const UnicodeSet& o, UBool asThawed); 1519 1520 //---------------------------------------------------------------- 1521 // Implementation: Pattern parsing 1522 //---------------------------------------------------------------- 1523 1524 void applyPatternIgnoreSpace(const UnicodeString& pattern, 1525 ParsePosition& pos, 1526 const SymbolTable* symbols, 1527 UErrorCode& status); 1528 1529 void applyPattern(RuleCharacterIterator& chars, 1530 const SymbolTable* symbols, 1531 UnicodeString& rebuiltPat, 1532 uint32_t options, 1533 UnicodeSet& (UnicodeSet::*caseClosure)(int32_t attribute), 1534 int32_t depth, 1535 UErrorCode& ec); 1536 1537 //---------------------------------------------------------------- 1538 // Implementation: Utility methods 1539 //---------------------------------------------------------------- 1540 1541 static int32_t nextCapacity(int32_t minCapacity); 1542 1543 bool ensureCapacity(int32_t newLen); 1544 1545 bool ensureBufferCapacity(int32_t newLen); 1546 1547 void swapBuffers(void); 1548 1549 UBool allocateStrings(UErrorCode &status); 1550 UBool hasStrings() const; 1551 int32_t stringsSize() const; 1552 UBool stringsContains(const UnicodeString &s) const; 1553 1554 UnicodeString& _toPattern(UnicodeString& result, 1555 UBool escapeUnprintable) const; 1556 1557 UnicodeString& _generatePattern(UnicodeString& result, 1558 UBool escapeUnprintable) const; 1559 1560 static void _appendToPat(UnicodeString& buf, const UnicodeString& s, UBool escapeUnprintable); 1561 1562 static void _appendToPat(UnicodeString& buf, UChar32 c, UBool escapeUnprintable); 1563 1564 //---------------------------------------------------------------- 1565 // Implementation: Fundamental operators 1566 //---------------------------------------------------------------- 1567 1568 void exclusiveOr(const UChar32* other, int32_t otherLen, int8_t polarity); 1569 1570 void add(const UChar32* other, int32_t otherLen, int8_t polarity); 1571 1572 void retain(const UChar32* other, int32_t otherLen, int8_t polarity); 1573 1574 /** 1575 * Return true if the given position, in the given pattern, appears 1576 * to be the start of a property set pattern [:foo:], \\p{foo}, or 1577 * \\P{foo}, or \\N{name}. 1578 */ 1579 static UBool resemblesPropertyPattern(const UnicodeString& pattern, 1580 int32_t pos); 1581 1582 static UBool resemblesPropertyPattern(RuleCharacterIterator& chars, 1583 int32_t iterOpts); 1584 1585 /** 1586 * Parse the given property pattern at the given parse position 1587 * and set this UnicodeSet to the result. 1588 * 1589 * The original design document is out of date, but still useful. 1590 * Ignore the property and value names: 1591 * http://source.icu-project.org/repos/icu/icuhtml/trunk/design/unicodeset_properties.html 1592 * 1593 * Recognized syntax: 1594 * 1595 * [:foo:] [:^foo:] - white space not allowed within "[:" or ":]" 1596 * \\p{foo} \\P{foo} - white space not allowed within "\\p" or "\\P" 1597 * \\N{name} - white space not allowed within "\\N" 1598 * 1599 * Other than the above restrictions, Unicode Pattern_White_Space characters are ignored. 1600 * Case is ignored except in "\\p" and "\\P" and "\\N". In 'name' leading 1601 * and trailing space is deleted, and internal runs of whitespace 1602 * are collapsed to a single space. 1603 * 1604 * We support binary properties, enumerated properties, and the 1605 * following non-enumerated properties: 1606 * 1607 * Numeric_Value 1608 * Name 1609 * Unicode_1_Name 1610 * 1611 * @param pattern the pattern string 1612 * @param ppos on entry, the position at which to begin parsing. 1613 * This should be one of the locations marked '^': 1614 * 1615 * [:blah:] \\p{blah} \\P{blah} \\N{name} 1616 * ^ % ^ % ^ % ^ % 1617 * 1618 * On return, the position after the last character parsed, that is, 1619 * the locations marked '%'. If the parse fails, ppos is returned 1620 * unchanged. 1621 * @param ec status 1622 * @return a reference to this. 1623 */ 1624 UnicodeSet& applyPropertyPattern(const UnicodeString& pattern, 1625 ParsePosition& ppos, 1626 UErrorCode &ec); 1627 1628 void applyPropertyPattern(RuleCharacterIterator& chars, 1629 UnicodeString& rebuiltPat, 1630 UErrorCode& ec); 1631 1632 static const UnicodeSet* getInclusions(int32_t src, UErrorCode &status); 1633 1634 /** 1635 * A filter that returns TRUE if the given code point should be 1636 * included in the UnicodeSet being constructed. 1637 */ 1638 typedef UBool (*Filter)(UChar32 codePoint, void* context); 1639 1640 /** 1641 * Given a filter, set this UnicodeSet to the code points 1642 * contained by that filter. The filter MUST be 1643 * property-conformant. That is, if it returns value v for one 1644 * code point, then it must return v for all affiliated code 1645 * points, as defined by the inclusions list. See 1646 * getInclusions(). 1647 * src is a UPropertySource value. 1648 */ 1649 void applyFilter(Filter filter, 1650 void* context, 1651 const UnicodeSet* inclusions, 1652 UErrorCode &status); 1653 1654 #ifndef U_HIDE_DRAFT_API // Skipped: ucpmap.h is draft only. 1655 void applyIntPropertyValue(const UCPMap *map, 1656 UCPMapValueFilter *filter, const void *context, 1657 UErrorCode &errorCode); 1658 #endif /* U_HIDE_DRAFT_API */ 1659 1660 /** 1661 * Set the new pattern to cache. 1662 */ 1663 void setPattern(const UnicodeString& newPat) { 1664 setPattern(newPat.getBuffer(), newPat.length()); 1665 } 1666 void setPattern(const char16_t *newPat, int32_t newPatLen); 1667 /** 1668 * Release existing cached pattern. 1669 */ 1670 void releasePattern(); 1671 1672 friend class UnicodeSetIterator; 1673 }; 1674 1675 1676 1677 inline UBool UnicodeSet::operator!=(const UnicodeSet& o) const { 1678 return !operator==(o); 1679 } 1680 1681 inline UBool UnicodeSet::isFrozen() const { 1682 return (UBool)(bmpSet!=NULL || stringSpan!=NULL); 1683 } 1684 1685 inline UBool UnicodeSet::containsSome(UChar32 start, UChar32 end) const { 1686 return !containsNone(start, end); 1687 } 1688 1689 inline UBool UnicodeSet::containsSome(const UnicodeSet& s) const { 1690 return !containsNone(s); 1691 } 1692 1693 inline UBool UnicodeSet::containsSome(const UnicodeString& s) const { 1694 return !containsNone(s); 1695 } 1696 1697 inline UBool UnicodeSet::isBogus() const { 1698 return (UBool)(fFlags & kIsBogus); 1699 } 1700 1701 inline UnicodeSet *UnicodeSet::fromUSet(USet *uset) { 1702 return reinterpret_cast<UnicodeSet *>(uset); 1703 } 1704 1705 inline const UnicodeSet *UnicodeSet::fromUSet(const USet *uset) { 1706 return reinterpret_cast<const UnicodeSet *>(uset); 1707 } 1708 1709 inline USet *UnicodeSet::toUSet() { 1710 return reinterpret_cast<USet *>(this); 1711 } 1712 1713 inline const USet *UnicodeSet::toUSet() const { 1714 return reinterpret_cast<const USet *>(this); 1715 } 1716 1717 inline int32_t UnicodeSet::span(const UnicodeString &s, int32_t start, USetSpanCondition spanCondition) const { 1718 int32_t sLength=s.length(); 1719 if(start<0) { 1720 start=0; 1721 } else if(start>sLength) { 1722 start=sLength; 1723 } 1724 return start+span(s.getBuffer()+start, sLength-start, spanCondition); 1725 } 1726 1727 inline int32_t UnicodeSet::spanBack(const UnicodeString &s, int32_t limit, USetSpanCondition spanCondition) const { 1728 int32_t sLength=s.length(); 1729 if(limit<0) { 1730 limit=0; 1731 } else if(limit>sLength) { 1732 limit=sLength; 1733 } 1734 return spanBack(s.getBuffer(), limit, spanCondition); 1735 } 1736 1737 U_NAMESPACE_END 1738 1739 #endif 1740
