codekingpro/portable-devtools
116k
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/utypes.h"
17
18#if U_SHOW_CPLUSPLUS_API
19
20#include "unicode/ucpmap.h"
21#include "unicode/unifilt.h"
22#include "unicode/unistr.h"
23#include "unicode/uset.h"
24
25/**
26 * \file
27 * \brief C++ API: Unicode Set
28 */
29
30U_NAMESPACE_BEGIN
31
32// Forward Declarations.
33class BMPSet;
34class ParsePosition;
35class RBBIRuleScanner;
36class SymbolTable;
37class UnicodeSetStringSpan;
38class UVector;
39class RuleCharacterIterator;
40
41/**
42 * A mutable set of Unicode characters and multicharacter strings. Objects of this class
43 * represent <em>character classes</em> used in regular expressions.
44 * A character specifies a subset of Unicode code points. Legal
45 * code points are U+0000 to U+10FFFF, inclusive.
46 *
47 * <p>The UnicodeSet class is not designed to be subclassed.
48 *
49 * <p><code>UnicodeSet</code> supports two APIs. The first is the
50 * <em>operand</em> API that allows the caller to modify the value of
51 * a <code>UnicodeSet</code> object. It conforms to Java 2's
52 * <code>java.util.Set</code> interface, although
53 * <code>UnicodeSet</code> does not actually implement that
54 * interface. All methods of <code>Set</code> are supported, with the
55 * modification that they take a character range or single character
56 * instead of an <code>Object</code>, and they take a
57 * <code>UnicodeSet</code> instead of a <code>Collection</code>. The
58 * operand API may be thought of in terms of boolean logic: a boolean
59 * OR is implemented by <code>add</code>, a boolean AND is implemented
60 * by <code>retain</code>, a boolean XOR is implemented by
61 * <code>complement</code> taking an argument, and a boolean NOT is
62 * implemented by <code>complement</code> with no argument. In terms
63 * of traditional set theory function names, <code>add</code> is a
64 * union, <code>retain</code> is an intersection, <code>remove</code>
65 * is an asymmetric difference, and <code>complement</code> with no
66 * argument is a set complement with respect to the superset range
67 * <code>MIN_VALUE-MAX_VALUE</code>
68 *
69 * <p>The second API is the
70 * <code>applyPattern()</code>/<code>toPattern()</code> API from the
71 * <code>java.text.Format</code>-derived classes. Unlike the
72 * methods that add characters, add categories, and control the logic
73 * of the set, the method <code>applyPattern()</code> sets all
74 * attributes of a <code>UnicodeSet</code> at once, based on a
75 * string pattern.
76 *
77 * <p><b>Pattern syntax</b></p>
78 *
79 * Patterns are accepted by the constructors and the
80 * <code>applyPattern()</code> methods and returned by the
81 * <code>toPattern()</code> method. These patterns follow a syntax
82 * similar to that employed by version 8 regular expression character
83 * classes. Here are some simple examples:
84 *
85 * \htmlonly<blockquote>\endhtmlonly
86 * <table>
87 * <tr align="top">
88 * <td nowrap valign="top" align="left"><code>[]</code></td>
89 * <td valign="top">No characters</td>
90 * </tr><tr align="top">
91 * <td nowrap valign="top" align="left"><code>[a]</code></td>
92 * <td valign="top">The character 'a'</td>
93 * </tr><tr align="top">
94 * <td nowrap valign="top" align="left"><code>[ae]</code></td>
95 * <td valign="top">The characters 'a' and 'e'</td>
96 * </tr>
97 * <tr>
98 * <td nowrap valign="top" align="left"><code>[a-e]</code></td>
99 * <td valign="top">The characters 'a' through 'e' inclusive, in Unicode code
100 * point order</td>
101 * </tr>
102 * <tr>
103 * <td nowrap valign="top" align="left"><code>[\\u4E01]</code></td>
104 * <td valign="top">The character U+4E01</td>
105 * </tr>
106 * <tr>
107 * <td nowrap valign="top" align="left"><code>[a{ab}{ac}]</code></td>
108 * <td valign="top">The character 'a' and the multicharacter strings "ab" and
109 * "ac"</td>
110 * </tr>
111 * <tr>
112 * <td nowrap valign="top" align="left"><code>[\\p{Lu}]</code></td>
113 * <td valign="top">All characters in the general category Uppercase Letter</td>
114 * </tr>
115 * </table>
116 * \htmlonly</blockquote>\endhtmlonly
117 *
118 * Any character may be preceded by a backslash in order to remove any special
119 * meaning. White space characters, as defined by UCharacter.isWhitespace(), are
120 * ignored, unless they are escaped.
121 *
122 * <p>Property patterns specify a set of characters having a certain
123 * property as defined by the Unicode standard. Both the POSIX-like
124 * "[:Lu:]" and the Perl-like syntax "\\p{Lu}" are recognized. For a
125 * complete list of supported property patterns, see the User's Guide
126 * for UnicodeSet at
127 * <a href="http://icu-project.org/userguide/unicodeSet.html">
128 * http://icu-project.org/userguide/unicodeSet.html</a>.
129 * Actual determination of property data is defined by the underlying
130 * Unicode database as implemented by UCharacter.
131 *
132 * <p>Patterns specify individual characters, ranges of characters, and
133 * Unicode property sets. When elements are concatenated, they
134 * specify their union. To complement a set, place a '^' immediately
135 * after the opening '['. Property patterns are inverted by modifying
136 * their delimiters; "[:^foo]" and "\\P{foo}". In any other location,
137 * '^' has no special meaning.
138 *
139 * <p>Ranges are indicated by placing two a '-' between two
140 * characters, as in "a-z". This specifies the range of all
141 * characters from the left to the right, in Unicode order. If the
142 * left character is greater than or equal to the
143 * right character it is a syntax error. If a '-' occurs as the first
144 * character after the opening '[' or '[^', or if it occurs as the
145 * last character before the closing ']', then it is taken as a
146 * literal. Thus "[a\-b]", "[-ab]", and "[ab-]" all indicate the same
147 * set of three characters, 'a', 'b', and '-'.
148 *
149 * <p>Sets may be intersected using the '&' operator or the asymmetric
150 * set difference may be taken using the '-' operator, for example,
151 * "[[:L:]&[\\u0000-\\u0FFF]]" indicates the set of all Unicode letters
152 * with values less than 4096. Operators ('&' and '|') have equal
153 * precedence and bind left-to-right. Thus
154 * "[[:L:]-[a-z]-[\\u0100-\\u01FF]]" is equivalent to
155 * "[[[:L:]-[a-z]]-[\\u0100-\\u01FF]]". This only really matters for
156 * difference; intersection is commutative.
157 *
158 * <table>
159 * <tr valign=top><td nowrap><code>[a]</code><td>The set containing 'a'
160 * <tr valign=top><td nowrap><code>[a-z]</code><td>The set containing 'a'
161 * through 'z' and all letters in between, in Unicode order
162 * <tr valign=top><td nowrap><code>[^a-z]</code><td>The set containing
163 * all characters but 'a' through 'z',
164 * that is, U+0000 through 'a'-1 and 'z'+1 through U+10FFFF
165 * <tr valign=top><td nowrap><code>[[<em>pat1</em>][<em>pat2</em>]]</code>
166 * <td>The union of sets specified by <em>pat1</em> and <em>pat2</em>
167 * <tr valign=top><td nowrap><code>[[<em>pat1</em>]&[<em>pat2</em>]]</code>
168 * <td>The intersection of sets specified by <em>pat1</em> and <em>pat2</em>
169 * <tr valign=top><td nowrap><code>[[<em>pat1</em>]-[<em>pat2</em>]]</code>
170 * <td>The asymmetric difference of sets specified by <em>pat1</em> and
171 * <em>pat2</em>
172 * <tr valign=top><td nowrap><code>[:Lu:] or \\p{Lu}</code>
173 * <td>The set of characters having the specified
174 * Unicode property; in
175 * this case, Unicode uppercase letters
176 * <tr valign=top><td nowrap><code>[:^Lu:] or \\P{Lu}</code>
177 * <td>The set of characters <em>not</em> having the given
178 * Unicode property
179 * </table>
180 *
181 * <p><b>Warning</b>: you cannot add an empty string ("") to a UnicodeSet.</p>
182 *
183 * <p><b>Formal syntax</b></p>
184 *
185 * \htmlonly<blockquote>\endhtmlonly
186 * <table>
187 * <tr align="top">
188 * <td nowrap valign="top" align="right"><code>pattern := </code></td>
189 * <td valign="top"><code>('[' '^'? item* ']') |
190 * property</code></td>
191 * </tr>
192 * <tr align="top">
193 * <td nowrap valign="top" align="right"><code>item := </code></td>
194 * <td valign="top"><code>char | (char '-' char) | pattern-expr<br>
195 * </code></td>
196 * </tr>
197 * <tr align="top">
198 * <td nowrap valign="top" align="right"><code>pattern-expr := </code></td>
199 * <td valign="top"><code>pattern | pattern-expr pattern |
200 * pattern-expr op pattern<br>
201 * </code></td>
202 * </tr>
203 * <tr align="top">
204 * <td nowrap valign="top" align="right"><code>op := </code></td>
205 * <td valign="top"><code>'&' | '-'<br>
206 * </code></td>
207 * </tr>
208 * <tr align="top">
209 * <td nowrap valign="top" align="right"><code>special := </code></td>
210 * <td valign="top"><code>'[' | ']' | '-'<br>
211 * </code></td>
212 * </tr>
213 * <tr align="top">
214 * <td nowrap valign="top" align="right"><code>char := </code></td>
215 * <td valign="top"><em>any character that is not</em><code> special<br>
216 * | ('\' </code><em>any character</em><code>)<br>
217 * | ('\\u' hex hex hex hex)<br>
218 * </code></td>
219 * </tr>
220 * <tr align="top">
221 * <td nowrap valign="top" align="right"><code>hex := </code></td>
222 * <td valign="top"><em>any character for which
223 * </em><code>Character.digit(c, 16)</code><em>
224 * returns a non-negative result</em></td>
225 * </tr>
226 * <tr>
227 * <td nowrap valign="top" align="right"><code>property := </code></td>
228 * <td valign="top"><em>a Unicode property set pattern</em></td>
229 * </tr>
230 * </table>
231 * <br>
232 * <table border="1">
233 * <tr>
234 * <td>Legend: <table>
235 * <tr>
236 * <td nowrap valign="top"><code>a := b</code></td>
237 * <td width="20" valign="top"> </td>
238 * <td valign="top"><code>a</code> may be replaced by <code>b</code> </td>
239 * </tr>
240 * <tr>
241 * <td nowrap valign="top"><code>a?</code></td>
242 * <td valign="top"></td>
243 * <td valign="top">zero or one instance of <code>a</code><br>
244 * </td>
245 * </tr>
246 * <tr>
247 * <td nowrap valign="top"><code>a*</code></td>
248 * <td valign="top"></td>
249 * <td valign="top">one or more instances of <code>a</code><br>
250 * </td>
251 * </tr>
252 * <tr>
253 * <td nowrap valign="top"><code>a | b</code></td>
254 * <td valign="top"></td>
255 * <td valign="top">either <code>a</code> or <code>b</code><br>
256 * </td>
257 * </tr>
258 * <tr>
259 * <td nowrap valign="top"><code>'a'</code></td>
260 * <td valign="top"></td>
261 * <td valign="top">the literal string between the quotes </td>
262 * </tr>
263 * </table>
264 * </td>
265 * </tr>
266 * </table>
267 * \htmlonly</blockquote>\endhtmlonly
268 *
269 * <p>Note:
270 * - Most UnicodeSet methods do not take a UErrorCode parameter because
271 * there are usually very few opportunities for failure other than a shortage
272 * of memory, error codes in low-level C++ string methods would be inconvenient,
273 * and the error code as the last parameter (ICU convention) would prevent
274 * the use of default parameter values.
275 * Instead, such methods set the UnicodeSet into a "bogus" state
276 * (see isBogus()) if an error occurs.
277 *
278 * @author Alan Liu
279 * @stable ICU 2.0
280 */
281class U_COMMON_API UnicodeSet U_FINAL : public UnicodeFilter {
282private:
283 /**
284 * Enough for sets with few ranges.
285 * For example, White_Space has 10 ranges, list length 21.
286 */
287 static constexpr int32_t INITIAL_CAPACITY = 25;
288 // fFlags constant
289 static constexpr uint8_t kIsBogus = 1; // This set is bogus (i.e. not valid)
290
291 UChar32* list = stackList; // MUST be terminated with HIGH
292 int32_t capacity = INITIAL_CAPACITY; // capacity of list
293 int32_t len = 1; // length of list used; 1 <= len <= capacity
294 uint8_t fFlags = 0; // Bit flag (see constants above)
295
296 BMPSet *bmpSet = nullptr; // The set is frozen iff either bmpSet or stringSpan is not NULL.
297 UChar32* buffer = nullptr; // internal buffer, may be NULL
298 int32_t bufferCapacity = 0; // capacity of buffer
299
300 /**
301 * The pattern representation of this set. This may not be the
302 * most economical pattern. It is the pattern supplied to
303 * applyPattern(), with variables substituted and whitespace
304 * removed. For sets constructed without applyPattern(), or
305 * modified using the non-pattern API, this string will be empty,
306 * indicating that toPattern() must generate a pattern
307 * representation from the inversion list.
308 */
309 char16_t *pat = nullptr;
310 int32_t patLen = 0;
311
312 UVector* strings = nullptr; // maintained in sorted order
313 UnicodeSetStringSpan *stringSpan = nullptr;
314
315 /**
316 * Initial list array.
317 * Avoids some heap allocations, and list is never nullptr.
318 * Increases the object size a bit.
319 */
320 UChar32 stackList[INITIAL_CAPACITY];
321
322public:
323 /**
324 * Determine if this object contains a valid set.
325 * A bogus set has no value. It is different from an empty set.
326 * It can be used to indicate that no set value is available.
327 *
328 * @return TRUE if the set is bogus/invalid, FALSE otherwise
329 * @see setToBogus()
330 * @stable ICU 4.0
331 */
332 inline UBool isBogus(void) const;
333
334 /**
335 * Make this UnicodeSet object invalid.
336 * The string will test TRUE with isBogus().
337 *
338 * A bogus set has no value. It is different from an empty set.
339 * It can be used to indicate that no set value is available.
340 *
341 * This utility function is used throughout the UnicodeSet
342 * implementation to indicate that a UnicodeSet operation failed,
343 * and may be used in other functions,
344 * especially but not exclusively when such functions do not
345 * take a UErrorCode for simplicity.
346 *
347 * @see isBogus()
348 * @stable ICU 4.0
349 */
350 void setToBogus();
351
352public:
353
354 enum {
355 /**
356 * Minimum value that can be stored in a UnicodeSet.
357 * @stable ICU 2.4
358 */
359 MIN_VALUE = 0,
360
361 /**
362 * Maximum value that can be stored in a UnicodeSet.
363 * @stable ICU 2.4
364 */
365 MAX_VALUE = 0x10ffff
366 };
367
368 //----------------------------------------------------------------
369 // Constructors &c
370 //----------------------------------------------------------------
371
372public:
373
374 /**
375 * Constructs an empty set.
376 * @stable ICU 2.0
377 */
378 UnicodeSet();
379
380 /**
381 * Constructs a set containing the given range. If <code>end <
382 * start</code> then an empty set is created.
383 *
384 * @param start first character, inclusive, of range
385 * @param end last character, inclusive, of range
386 * @stable ICU 2.4
387 */
388 UnicodeSet(UChar32 start, UChar32 end);
389
390#ifndef U_HIDE_INTERNAL_API
391 /**
392 * @internal
393 */
394 enum ESerialization {
395 kSerialized /* result of serialize() */
396 };
397
398 /**
399 * Constructs a set from the output of serialize().
400 *
401 * @param buffer the 16 bit array
402 * @param bufferLen the original length returned from serialize()
403 * @param serialization the value 'kSerialized'
404 * @param status error code
405 *
406 * @internal
407 */
408 UnicodeSet(const uint16_t buffer[], int32_t bufferLen,
409 ESerialization serialization, UErrorCode &status);
410#endif /* U_HIDE_INTERNAL_API */
411
412 /**
413 * Constructs a set from the given pattern. See the class
414 * description for the syntax of the pattern language.
415 * @param pattern a string specifying what characters are in the set
416 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern
417 * contains a syntax error.
418 * @stable ICU 2.0
419 */
420 UnicodeSet(const UnicodeString& pattern,
421 UErrorCode& status);
422
423#ifndef U_HIDE_INTERNAL_API
424 /**
425 * Constructs a set from the given pattern. See the class
426 * description for the syntax of the pattern language.
427 * @param pattern a string specifying what characters are in the set
428 * @param options bitmask for options to apply to the pattern.
429 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
430 * @param symbols a symbol table mapping variable names to values
431 * and stand-in characters to UnicodeSets; may be NULL
432 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern
433 * contains a syntax error.
434 * @internal
435 */
436 UnicodeSet(const UnicodeString& pattern,
437 uint32_t options,
438 const SymbolTable* symbols,
439 UErrorCode& status);
440#endif /* U_HIDE_INTERNAL_API */
441
442 /**
443 * Constructs a set from the given pattern. See the class description
444 * for the syntax of the pattern language.
445 * @param pattern a string specifying what characters are in the set
446 * @param pos on input, the position in pattern at which to start parsing.
447 * On output, the position after the last character parsed.
448 * @param options bitmask for options to apply to the pattern.
449 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
450 * @param symbols a symbol table mapping variable names to values
451 * and stand-in characters to UnicodeSets; may be NULL
452 * @param status input-output error code
453 * @stable ICU 2.8
454 */
455 UnicodeSet(const UnicodeString& pattern, ParsePosition& pos,
456 uint32_t options,
457 const SymbolTable* symbols,
458 UErrorCode& status);
459
460 /**
461 * Constructs a set that is identical to the given UnicodeSet.
462 * @stable ICU 2.0
463 */
464 UnicodeSet(const UnicodeSet& o);
465
466 /**
467 * Destructs the set.
468 * @stable ICU 2.0
469 */
470 virtual ~UnicodeSet();
471
472 /**
473 * Assigns this object to be a copy of another.
474 * A frozen set will not be modified.
475 * @stable ICU 2.0
476 */
477 UnicodeSet& operator=(const UnicodeSet& o);
478
479 /**
480 * Compares the specified object with this set for equality. Returns
481 * <tt>true</tt> if the two sets
482 * have the same size, and every member of the specified set is
483 * contained in this set (or equivalently, every member of this set is
484 * contained in the specified set).
485 *
486 * @param o set to be compared for equality with this set.
487 * @return <tt>true</tt> if the specified set is equal to this set.
488 * @stable ICU 2.0
489 */
490 virtual UBool operator==(const UnicodeSet& o) const;
491
492 /**
493 * Compares the specified object with this set for equality. Returns
494 * <tt>true</tt> if the specified set is not equal to this set.
495 * @stable ICU 2.0
496 */
497 inline UBool operator!=(const UnicodeSet& o) const;
498
499 /**
500 * Returns a copy of this object. All UnicodeFunctor objects have
501 * to support cloning in order to allow classes using
502 * UnicodeFunctors, such as Transliterator, to implement cloning.
503 * If this set is frozen, then the clone will be frozen as well.
504 * Use cloneAsThawed() for a mutable clone of a frozen set.
505 * @see cloneAsThawed
506 * @stable ICU 2.0
507 */
508 virtual UnicodeSet* clone() const;
509
510 /**
511 * Returns the hash code value for this set.
512 *
513 * @return the hash code value for this set.
514 * @see Object#hashCode()
515 * @stable ICU 2.0
516 */
517 virtual int32_t hashCode(void) const;
518
519 /**
520 * Get a UnicodeSet pointer from a USet
521 *
522 * @param uset a USet (the ICU plain C type for UnicodeSet)
523 * @return the corresponding UnicodeSet pointer.
524 *
525 * @stable ICU 4.2
526 */
527 inline static UnicodeSet *fromUSet(USet *uset);
528
529 /**
530 * Get a UnicodeSet pointer from a const USet
531 *
532 * @param uset a const USet (the ICU plain C type for UnicodeSet)
533 * @return the corresponding UnicodeSet pointer.
534 *
535 * @stable ICU 4.2
536 */
537 inline static const UnicodeSet *fromUSet(const USet *uset);
538
539 /**
540 * Produce a USet * pointer for this UnicodeSet.
541 * USet is the plain C type for UnicodeSet
542 *
543 * @return a USet pointer for this UnicodeSet
544 * @stable ICU 4.2
545 */
546 inline USet *toUSet();
547
548
549 /**
550 * Produce a const USet * pointer for this UnicodeSet.
551 * USet is the plain C type for UnicodeSet
552 *
553 * @return a const USet pointer for this UnicodeSet
554 * @stable ICU 4.2
555 */
556 inline const USet * toUSet() const;
557
558
559 //----------------------------------------------------------------
560 // Freezable API
561 //----------------------------------------------------------------
562
563 /**
564 * Determines whether the set has been frozen (made immutable) or not.
565 * See the ICU4J Freezable interface for details.
566 * @return TRUE/FALSE for whether the set has been frozen
567 * @see freeze
568 * @see cloneAsThawed
569 * @stable ICU 3.8
570 */
571 inline UBool isFrozen() const;
572
573 /**
574 * Freeze the set (make it immutable).
575 * Once frozen, it cannot be unfrozen and is therefore thread-safe
576 * until it is deleted.
577 * See the ICU4J Freezable interface for details.
578 * Freezing the set may also make some operations faster, for example
579 * contains() and span().
580 * A frozen set will not be modified. (It remains frozen.)
581 * @return this set.
582 * @see isFrozen
583 * @see cloneAsThawed
584 * @stable ICU 3.8
585 */
586 UnicodeSet *freeze();
587
588 /**
589 * Clone the set and make the clone mutable.
590 * See the ICU4J Freezable interface for details.
591 * @return the mutable clone
592 * @see freeze
593 * @see isFrozen
594 * @stable ICU 3.8
595 */
596 UnicodeSet *cloneAsThawed() const;
597
598 //----------------------------------------------------------------
599 // Public API
600 //----------------------------------------------------------------
601
602 /**
603 * Make this object represent the range `start - end`.
604 * If `end > start` then this object is set to an empty range.
605 * A frozen set will not be modified.
606 *
607 * @param start first character in the set, inclusive
608 * @param end last character in the set, inclusive
609 * @stable ICU 2.4
610 */
611 UnicodeSet& set(UChar32 start, UChar32 end);
612
613 /**
614 * Return true if the given position, in the given pattern, appears
615 * to be the start of a UnicodeSet pattern.
616 * @stable ICU 2.4
617 */
618 static UBool resemblesPattern(const UnicodeString& pattern,
619 int32_t pos);
620
621 /**
622 * Modifies this set to represent the set specified by the given
623 * pattern, ignoring Unicode Pattern_White_Space characters.
624 * See the class description for the syntax of the pattern language.
625 * A frozen set will not be modified.
626 * @param pattern a string specifying what characters are in the set
627 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern
628 * contains a syntax error.
629 * <em> Empties the set passed before applying the pattern.</em>
630 * @return a reference to this
631 * @stable ICU 2.0
632 */
633 UnicodeSet& applyPattern(const UnicodeString& pattern,
634 UErrorCode& status);
635
636#ifndef U_HIDE_INTERNAL_API
637 /**
638 * Modifies this set to represent the set specified by the given
639 * pattern, optionally ignoring Unicode Pattern_White_Space characters.
640 * See the class description for the syntax of the pattern language.
641 * A frozen set will not be modified.
642 * @param pattern a string specifying what characters are in the set
643 * @param options bitmask for options to apply to the pattern.
644 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
645 * @param symbols a symbol table mapping variable names to
646 * values and stand-ins to UnicodeSets; may be NULL
647 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern
648 * contains a syntax error.
649 *<em> Empties the set passed before applying the pattern.</em>
650 * @return a reference to this
651 * @internal
652 */
653 UnicodeSet& applyPattern(const UnicodeString& pattern,
654 uint32_t options,
655 const SymbolTable* symbols,
656 UErrorCode& status);
657#endif /* U_HIDE_INTERNAL_API */
658
659 /**
660 * Parses the given pattern, starting at the given position. The
661 * character at pattern.charAt(pos.getIndex()) must be '[', or the
662 * parse fails. Parsing continues until the corresponding closing
663 * ']'. If a syntax error is encountered between the opening and
664 * closing brace, the parse fails. Upon return from a successful
665 * parse, the ParsePosition is updated to point to the character
666 * following the closing ']', and a StringBuffer containing a
667 * pairs list for the parsed pattern is returned. This method calls
668 * itself recursively to parse embedded subpatterns.
669 *<em> Empties the set passed before applying the pattern.</em>
670 * A frozen set will not be modified.
671 *
672 * @param pattern the string containing the pattern to be parsed.
673 * The portion of the string from pos.getIndex(), which must be a
674 * '[', to the corresponding closing ']', is parsed.
675 * @param pos upon entry, the position at which to being parsing.
676 * The character at pattern.charAt(pos.getIndex()) must be a '['.
677 * Upon return from a successful parse, pos.getIndex() is either
678 * the character after the closing ']' of the parsed pattern, or
679 * pattern.length() if the closing ']' is the last character of
680 * the pattern string.
681 * @param options bitmask for options to apply to the pattern.
682 * Valid options are USET_IGNORE_SPACE and USET_CASE_INSENSITIVE.
683 * @param symbols a symbol table mapping variable names to
684 * values and stand-ins to UnicodeSets; may be NULL
685 * @param status returns <code>U_ILLEGAL_ARGUMENT_ERROR</code> if the pattern
686 * contains a syntax error.
687 * @return a reference to this
688 * @stable ICU 2.8
689 */
690 UnicodeSet& applyPattern(const UnicodeString& pattern,
691 ParsePosition& pos,
692 uint32_t options,
693 const SymbolTable* symbols,
694 UErrorCode& status);
695
696 /**
697 * Returns a string representation of this set. If the result of
698 * calling this function is passed to a UnicodeSet constructor, it
699 * will produce another set that is equal to this one.
700 * A frozen set will not be modified.
701 * @param result the string to receive the rules. Previous
702 * contents will be deleted.
703 * @param escapeUnprintable if TRUE then convert unprintable
704 * character to their hex escape representations, \\uxxxx or
705 * \\Uxxxxxxxx. Unprintable characters are those other than
706 * U+000A, U+0020..U+007E.
707 * @stable ICU 2.0
708 */
709 virtual UnicodeString& toPattern(UnicodeString& result,
710 UBool escapeUnprintable = FALSE) const;
711
712 /**
713 * Modifies this set to contain those code points which have the given value
714 * for the given binary or enumerated property, as returned by
715 * u_getIntPropertyValue. Prior contents of this set are lost.
716 * A frozen set will not be modified.
717 *
718 * @param prop a property in the range UCHAR_BIN_START..UCHAR_BIN_LIMIT-1
719 * or UCHAR_INT_START..UCHAR_INT_LIMIT-1
720 * or UCHAR_MASK_START..UCHAR_MASK_LIMIT-1.
721 *
722 * @param value a value in the range u_getIntPropertyMinValue(prop)..
723 * u_getIntPropertyMaxValue(prop), with one exception. If prop is
724 * UCHAR_GENERAL_CATEGORY_MASK, then value should not be a UCharCategory, but
725 * rather a mask value produced by U_GET_GC_MASK(). This allows grouped
726 * categories such as [:L:] to be represented.
727 *
728 * @param ec error code input/output parameter
729 *
730 * @return a reference to this set
731 *
732 * @stable ICU 2.4
733 */
734 UnicodeSet& applyIntPropertyValue(UProperty prop,
735 int32_t value,
736 UErrorCode& ec);
737
738 /**
739 * Modifies this set to contain those code points which have the
740 * given value for the given property. Prior contents of this
741 * set are lost.
742 * A frozen set will not be modified.
743 *
744 * @param prop a property alias, either short or long. The name is matched
745 * loosely. See PropertyAliases.txt for names and a description of loose
746 * matching. If the value string is empty, then this string is interpreted
747 * as either a General_Category value alias, a Script value alias, a binary
748 * property alias, or a special ID. Special IDs are matched loosely and
749 * correspond to the following sets:
750 *
751 * "ANY" = [\\u0000-\\U0010FFFF],
752 * "ASCII" = [\\u0000-\\u007F],
753 * "Assigned" = [:^Cn:].
754 *
755 * @param value a value alias, either short or long. The name is matched
756 * loosely. See PropertyValueAliases.txt for names and a description of
757 * loose matching. In addition to aliases listed, numeric values and
758 * canonical combining classes may be expressed numerically, e.g., ("nv",
759 * "0.5") or ("ccc", "220"). The value string may also be empty.
760 *
761 * @param ec error code input/output parameter
762 *
763 * @return a reference to this set
764 *
765 * @stable ICU 2.4
766 */
767 UnicodeSet& applyPropertyAlias(const UnicodeString& prop,
768 const UnicodeString& value,
769 UErrorCode& ec);
770
771 /**
772 * Returns the number of elements in this set (its cardinality).
773 * Note than the elements of a set may include both individual
774 * codepoints and strings.
775 *
776 * @return the number of elements in this set (its cardinality).
777 * @stable ICU 2.0
778 */
779 virtual int32_t size(void) const;
780
781 /**
782 * Returns <tt>true</tt> if this set contains no elements.
783 *
784 * @return <tt>true</tt> if this set contains no elements.
785 * @stable ICU 2.0
786 */
787 virtual UBool isEmpty(void) const;
788
789 /**
790 * Returns true if this set contains the given character.
791 * This function works faster with a frozen set.
792 * @param c character to be checked for containment
793 * @return true if the test condition is met
794 * @stable ICU 2.0
795 */
796 virtual UBool contains(UChar32 c) const;
797
798 /**
799 * Returns true if this set contains every character
800 * of the given range.
801 * @param start first character, inclusive, of the range
802 * @param end last character, inclusive, of the range
803 * @return true if the test condition is met
804 * @stable ICU 2.0
805 */
806 virtual UBool contains(UChar32 start, UChar32 end) const;
807
808 /**
809 * Returns <tt>true</tt> if this set contains the given
810 * multicharacter string.
811 * @param s string to be checked for containment
812 * @return <tt>true</tt> if this set contains the specified string
813 * @stable ICU 2.4
814 */
815 UBool contains(const UnicodeString& s) const;
816
817 /**
818 * Returns true if this set contains all the characters and strings
819 * of the given set.
820 * @param c set to be checked for containment
821 * @return true if the test condition is met
822 * @stable ICU 2.4
823 */
824 virtual UBool containsAll(const UnicodeSet& c) const;
825
826 /**
827 * Returns true if this set contains all the characters
828 * of the given string.
829 * @param s string containing characters to be checked for containment
830 * @return true if the test condition is met
831 * @stable ICU 2.4
832 */
833 UBool containsAll(const UnicodeString& s) const;
834
835 /**
836 * Returns true if this set contains none of the characters
837 * of the given range.
838 * @param start first character, inclusive, of the range
839 * @param end last character, inclusive, of the range
840 * @return true if the test condition is met
841 * @stable ICU 2.4
842 */
843 UBool containsNone(UChar32 start, UChar32 end) const;
844
845 /**
846 * Returns true if this set contains none of the characters and strings
847 * of the given set.
848 * @param c set to be checked for containment
849 * @return true if the test condition is met
850 * @stable ICU 2.4
851 */
852 UBool containsNone(const UnicodeSet& c) const;
853
854 /**
855 * Returns true if this set contains none of the characters
856 * of the given string.
857 * @param s string containing characters to be checked for containment
858 * @return true if the test condition is met
859 * @stable ICU 2.4
860 */
861 UBool containsNone(const UnicodeString& s) const;
862
863 /**
864 * Returns true if this set contains one or more of the characters
865 * in the given range.
866 * @param start first character, inclusive, of the range
867 * @param end last character, inclusive, of the range
868 * @return true if the condition is met
869 * @stable ICU 2.4
870 */
871 inline UBool containsSome(UChar32 start, UChar32 end) const;
872
873 /**
874 * Returns true if this set contains one or more of the characters
875 * and strings of the given set.
876 * @param s The set to be checked for containment
877 * @return true if the condition is met
878 * @stable ICU 2.4
879 */
880 inline UBool containsSome(const UnicodeSet& s) const;
881
882 /**
883 * Returns true if this set contains one or more of the characters
884 * of the given string.
885 * @param s string containing characters to be checked for containment
886 * @return true if the condition is met
887 * @stable ICU 2.4
888 */
889 inline UBool containsSome(const UnicodeString& s) const;
890
891 /**
892 * Returns the length of the initial substring of the input string which
893 * consists only of characters and strings that are contained in this set
894 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE),
895 * or only of characters and strings that are not contained
896 * in this set (USET_SPAN_NOT_CONTAINED).
897 * See USetSpanCondition for details.
898 * Similar to the strspn() C library function.
899 * Unpaired surrogates are treated according to contains() of their surrogate code points.
900 * This function works faster with a frozen set and with a non-negative string length argument.
901 * @param s start of the string
902 * @param length of the string; can be -1 for NUL-terminated
903 * @param spanCondition specifies the containment condition
904 * @return the length of the initial substring according to the spanCondition;
905 * 0 if the start of the string does not fit the spanCondition
906 * @stable ICU 3.8
907 * @see USetSpanCondition
908 */
909 int32_t span(const char16_t *s, int32_t length, USetSpanCondition spanCondition) const;
910
911 /**
912 * Returns the end of the substring of the input string according to the USetSpanCondition.
913 * Same as <code>start+span(s.getBuffer()+start, s.length()-start, spanCondition)</code>
914 * after pinning start to 0<=start<=s.length().
915 * @param s the string
916 * @param start the start index in the string for the span operation
917 * @param spanCondition specifies the containment condition
918 * @return the exclusive end of the substring according to the spanCondition;
919 * the substring s.tempSubStringBetween(start, end) fulfills the spanCondition
920 * @stable ICU 4.4
921 * @see USetSpanCondition
922 */
923 inline int32_t span(const UnicodeString &s, int32_t start, USetSpanCondition spanCondition) const;
924
925 /**
926 * Returns the start of the trailing substring of the input string which
927 * consists only of characters and strings that are contained in this set
928 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE),
929 * or only of characters and strings that are not contained
930 * in this set (USET_SPAN_NOT_CONTAINED).
931 * See USetSpanCondition for details.
932 * Unpaired surrogates are treated according to contains() of their surrogate code points.
933 * This function works faster with a frozen set and with a non-negative string length argument.
934 * @param s start of the string
935 * @param length of the string; can be -1 for NUL-terminated
936 * @param spanCondition specifies the containment condition
937 * @return the start of the trailing substring according to the spanCondition;
938 * the string length if the end of the string does not fit the spanCondition
939 * @stable ICU 3.8
940 * @see USetSpanCondition
941 */
942 int32_t spanBack(const char16_t *s, int32_t length, USetSpanCondition spanCondition) const;
943
944 /**
945 * Returns the start of the substring of the input string according to the USetSpanCondition.
946 * Same as <code>spanBack(s.getBuffer(), limit, spanCondition)</code>
947 * after pinning limit to 0<=end<=s.length().
948 * @param s the string
949 * @param limit the exclusive-end index in the string for the span operation
950 * (use s.length() or INT32_MAX for spanning back from the end of the string)
951 * @param spanCondition specifies the containment condition
952 * @return the start of the substring according to the spanCondition;
953 * the substring s.tempSubStringBetween(start, limit) fulfills the spanCondition
954 * @stable ICU 4.4
955 * @see USetSpanCondition
956 */
957 inline int32_t spanBack(const UnicodeString &s, int32_t limit, USetSpanCondition spanCondition) const;
958
959 /**
960 * Returns the length of the initial substring of the input string which
961 * consists only of characters and strings that are contained in this set
962 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE),
963 * or only of characters and strings that are not contained
964 * in this set (USET_SPAN_NOT_CONTAINED).
965 * See USetSpanCondition for details.
966 * Similar to the strspn() C library function.
967 * Malformed byte sequences are treated according to contains(0xfffd).
968 * This function works faster with a frozen set and with a non-negative string length argument.
969 * @param s start of the string (UTF-8)
970 * @param length of the string; can be -1 for NUL-terminated
971 * @param spanCondition specifies the containment condition
972 * @return the length of the initial substring according to the spanCondition;
973 * 0 if the start of the string does not fit the spanCondition
974 * @stable ICU 3.8
975 * @see USetSpanCondition
976 */
977 int32_t spanUTF8(const char *s, int32_t length, USetSpanCondition spanCondition) const;
978
979 /**
980 * Returns the start of the trailing substring of the input string which
981 * consists only of characters and strings that are contained in this set
982 * (USET_SPAN_CONTAINED, USET_SPAN_SIMPLE),
983 * or only of characters and strings that are not contained
984 * in this set (USET_SPAN_NOT_CONTAINED).
985 * See USetSpanCondition for details.
986 * Malformed byte sequences are treated according to contains(0xfffd).
987 * This function works faster with a frozen set and with a non-negative string length argument.
988 * @param s start of the string (UTF-8)
989 * @param length of the string; can be -1 for NUL-terminated
990 * @param spanCondition specifies the containment condition
991 * @return the start of the trailing substring according to the spanCondition;
992 * the string length if the end of the string does not fit the spanCondition
993 * @stable ICU 3.8
994 * @see USetSpanCondition
995 */
996 int32_t spanBackUTF8(const char *s, int32_t length, USetSpanCondition spanCondition) const;
997
998 /**
999 * Implement UnicodeMatcher::matches()
1000 * @stable ICU 2.4
1001 */
1002 virtual UMatchDegree matches(const Replaceable& text,
1003 int32_t& offset,
1004 int32_t limit,
1005 UBool incremental);
1006
1007private:
1008 /**
1009 * Returns the longest match for s in text at the given position.
1010 * If limit > start then match forward from start+1 to limit
1011 * matching all characters except s.charAt(0). If limit < start,
1012 * go backward starting from start-1 matching all characters
1013 * except s.charAt(s.length()-1). This method assumes that the
1014 * first character, text.charAt(start), matches s, so it does not
1015 * check it.
1016 * @param text the text to match
1017 * @param start the first character to match. In the forward
1018 * direction, text.charAt(start) is matched against s.charAt(0).
1019 * In the reverse direction, it is matched against
1020 * s.charAt(s.length()-1).
1021 * @param limit the limit offset for matching, either last+1 in
1022 * the forward direction, or last-1 in the reverse direction,
1023 * where last is the index of the last character to match.
1024 * @param s
1025 * @return If part of s matches up to the limit, return |limit -
1026 * start|. If all of s matches before reaching the limit, return
1027 * s.length(). If there is a mismatch between s and text, return
1028 * 0
1029 */
1030 static int32_t matchRest(const Replaceable& text,
1031 int32_t start, int32_t limit,
1032 const UnicodeString& s);
1033
1034 /**
1035 * Returns the smallest value i such that c < list[i]. Caller
1036 * must ensure that c is a legal value or this method will enter
1037 * an infinite loop. This method performs a binary search.
1038 * @param c a character in the range MIN_VALUE..MAX_VALUE
1039 * inclusive
1040 * @return the smallest integer i in the range 0..len-1,
1041 * inclusive, such that c < list[i]
1042 */
1043 int32_t findCodePoint(UChar32 c) const;
1044
1045public:
1046
1047 /**
1048 * Implementation of UnicodeMatcher API. Union the set of all
1049 * characters that may be matched by this object into the given
1050 * set.
1051 * @param toUnionTo the set into which to union the source characters
1052 * @stable ICU 2.4
1053 */
1054 virtual void addMatchSetTo(UnicodeSet& toUnionTo) const;
1055
1056 /**
1057 * Returns the index of the given character within this set, where
1058 * the set is ordered by ascending code point. If the character
1059 * is not in this set, return -1. The inverse of this method is
1060 * <code>charAt()</code>.
1061 * @return an index from 0..size()-1, or -1
1062 * @stable ICU 2.4
1063 */
1064 int32_t indexOf(UChar32 c) const;
1065
1066 /**
1067 * Returns the character at the given index within this set, where
1068 * the set is ordered by ascending code point. If the index is
1069 * out of range, return (UChar32)-1. The inverse of this method is
1070 * <code>indexOf()</code>.
1071 * @param index an index from 0..size()-1
1072 * @return the character at the given index, or (UChar32)-1.
1073 * @stable ICU 2.4
1074 */
1075 UChar32 charAt(int32_t index) const;
1076
1077 /**
1078 * Adds the specified range to this set if it is not already
1079 * present. If this set already contains the specified range,
1080 * the call leaves this set unchanged. If <code>end > start</code>
1081 * then an empty range is added, leaving the set unchanged.
1082 * This is equivalent to a boolean logic OR, or a set UNION.
1083 * A frozen set will not be modified.
1084 *
1085 * @param start first character, inclusive, of range to be added
1086 * to this set.
1087 * @param end last character, inclusive, of range to be added
1088 * to this set.
1089 * @stable ICU 2.0
1090 */
1091 virtual UnicodeSet& add(UChar32 start, UChar32 end);
1092
1093 /**
1094 * Adds the specified character to this set if it is not already
1095 * present. If this set already contains the specified character,
1096 * the call leaves this set unchanged.
1097 * A frozen set will not be modified.
1098 * @stable ICU 2.0
1099 */
1100 UnicodeSet& add(UChar32 c);
1101
1102 /**
1103 * Adds the specified multicharacter to this set if it is not already
1104 * present. If this set already contains the multicharacter,
1105 * the call leaves this set unchanged.
1106 * Thus "ch" => {"ch"}
1107 * <br><b>Warning: you cannot add an empty string ("") to a UnicodeSet.</b>
1108 * A frozen set will not be modified.
1109 * @param s the source string
1110 * @return this object, for chaining
1111 * @stable ICU 2.4
1112 */
1113 UnicodeSet& add(const UnicodeString& s);
1114
1115 private:
1116 /**
1117 * @return a code point IF the string consists of a single one.
1118 * otherwise returns -1.
1119 * @param s string to test
1120 */
1121 static int32_t getSingleCP(const UnicodeString& s);
1122
1123 void _add(const UnicodeString& s);
1124
1125 public:
1126 /**
1127 * Adds each of the characters in this string to the set. Thus "ch" => {"c", "h"}
1128 * If this set already any particular character, it has no effect on that character.
1129 * A frozen set will not be modified.
1130 * @param s the source string
1131 * @return this object, for chaining
1132 * @stable ICU 2.4
1133 */
1134 UnicodeSet& addAll(const UnicodeString& s);
1135
1136 /**
1137 * Retains EACH of the characters in this string. Note: "ch" == {"c", "h"}
1138 * If this set already any particular character, it has no effect on that character.
1139 * A frozen set will not be modified.
1140 * @param s the source string
1141 * @return this object, for chaining
1142 * @stable ICU 2.4
1143 */
1144 UnicodeSet& retainAll(const UnicodeString& s);
1145
1146 /**
1147 * Complement EACH of the characters in this string. Note: "ch" == {"c", "h"}
1148 * If this set already any particular character, it has no effect on that character.
1149 * A frozen set will not be modified.
1150 * @param s the source string
1151 * @return this object, for chaining
1152 * @stable ICU 2.4
1153 */
1154 UnicodeSet& complementAll(const UnicodeString& s);
1155
1156 /**
1157 * Remove EACH of the characters in this string. Note: "ch" == {"c", "h"}
1158 * If this set already any particular character, it has no effect on that character.
1159 * A frozen set will not be modified.
1160 * @param s the source string
1161 * @return this object, for chaining
1162 * @stable ICU 2.4
1163 */
1164 UnicodeSet& removeAll(const UnicodeString& s);
1165
1166 /**
1167 * Makes a set from a multicharacter string. Thus "ch" => {"ch"}
1168 * <br><b>Warning: you cannot add an empty string ("") to a UnicodeSet.</b>
1169 * @param s the source string
1170 * @return a newly created set containing the given string.
1171 * The caller owns the return object and is responsible for deleting it.
1172 * @stable ICU 2.4
1173 */
1174 static UnicodeSet* U_EXPORT2 createFrom(const UnicodeString& s);
1175
1176
1177 /**
1178 * Makes a set from each of the characters in the string. Thus "ch" => {"c", "h"}
1179 * @param s the source string
1180 * @return a newly created set containing the given characters
1181 * The caller owns the return object and is responsible for deleting it.
1182 * @stable ICU 2.4
1183 */
1184 static UnicodeSet* U_EXPORT2 createFromAll(const UnicodeString& s);
1185
1186 /**
1187 * Retain only the elements in this set that are contained in the
1188 * specified range. If <code>end > start</code> then an empty range is
1189 * retained, leaving the set empty. This is equivalent to
1190 * a boolean logic AND, or a set INTERSECTION.
1191 * A frozen set will not be modified.
1192 *
1193 * @param start first character, inclusive, of range to be retained
1194 * to this set.
1195 * @param end last character, inclusive, of range to be retained
1196 * to this set.
1197 * @stable ICU 2.0
1198 */
1199 virtual UnicodeSet& retain(UChar32 start, UChar32 end);
1200