A mutable set of Unicode characters and multicharacter strings. Objects of this class represent character classes used in regular expressions. A character specifies a subset of Unicode code points. Legal code points are U+0000 to U+10FFFF, inclusive.

The UnicodeSet class is not designed to be subclassed.

UnicodeSet supports two APIs. The first is the operand API that allows the caller to modify the value of a UnicodeSet object. It conforms to Java 2's java.util.Set interface, although UnicodeSet does not actually implement that interface. All methods of Set are supported, with the modification that they take a character range or single character instead of an Object, and they take a UnicodeSet instead of a Collection. The operand API may be thought of in terms of boolean logic: a boolean OR is implemented by add, a boolean AND is implemented by retain, a boolean XOR is implemented by complement taking an argument, and a boolean NOT is implemented by complement with no argument. In terms of traditional set theory function names, add is a union, retain is an intersection, remove is an asymmetric difference, and complement with no argument is a set complement with respect to the superset range MIN_VALUE-MAX_VALUE

The second API is the applyPattern()/toPattern() API from the java.text.Format-derived classes. Unlike the methods that add characters, add categories, and control the logic of the set, the method applyPattern() sets all attributes of a UnicodeSet at once, based on a string pattern.

Pattern syntax

Patterns are accepted by the constructors and the applyPattern() methods and returned by the toPattern() method. These patterns follow a syntax similar to that employed by version 8 regular expression character classes. Here are some simple examples:

[]	No characters
[a]	The character 'a'
[ae]	The characters 'a' and 'e'
[a-e]	The characters 'a' through 'e' inclusive, in Unicode code point order
[\\u4E01]	The character U+4E01
[a{ab}{ac}]	The character 'a' and the multicharacter strings "ab" and "ac"
[\p{Lu}]	All characters in the general category Uppercase Letter

Any character may be preceded by a backslash in order to remove any special meaning. White space characters, as defined by the Unicode Pattern_White_Space property, are ignored, unless they are escaped.

Property patterns specify a set of characters having a certain property as defined by the Unicode standard. Both the POSIX-like "[:Lu:]" and the Perl-like syntax "\p{Lu}" are recognized. For a complete list of supported property patterns, see the User's Guide for UnicodeSet at https://unicode-org.github.io/icu/userguide/strings/unicodeset. Actual determination of property data is defined by the underlying Unicode database as implemented by UCharacter.

Patterns specify individual characters, ranges of characters, and Unicode property sets. When elements are concatenated, they specify their union. To complement a set, place a '^' immediately after the opening '['. Property patterns are inverted by modifying their delimiters; "[:^foo]" and "\P{foo}". In any other location, '^' has no special meaning.

Since ICU 70, "[^...]", "[:^foo]", "\P{foo}", and "[:binaryProperty=No:]" perform a "code point complement" (all code points minus the original set), removing all multicharacter strings, equivalent to .complement().removeAllStrings() . The complement() API function continues to perform a symmetric difference with all code points and thus retains all multicharacter strings.

Ranges are indicated by placing two a '-' between two characters, as in "a-z". This specifies the range of all characters from the left to the right, in Unicode order. If the left character is greater than or equal to the right character it is a syntax error. If a '-' occurs as the first character after the opening '[' or '[^', or if it occurs as the last character before the closing ']', then it is taken as a literal. Thus "[a\\-b]", "[-ab]", and "[ab-]" all indicate the same set of three characters, 'a', 'b', and '-'.

Sets may be intersected using the '&' operator or the asymmetric set difference may be taken using the '-' operator, for example, "[[:L:]&[\\u0000-\\u0FFF]]" indicates the set of all Unicode letters with values less than 4096. Operators ('&' and '|') have equal precedence and bind left-to-right. Thus "[[:L:]-[a-z]-[\\u0100-\\u01FF]]" is equivalent to "[[[:L:]-[a-z]]-[\\u0100-\\u01FF]]". This only really matters for difference; intersection is commutative.

[a]	The set containing 'a'
[a-z]	The set containing 'a' through 'z' and all letters in between, in Unicode order
[^a-z]	The set containing all characters but 'a' through 'z', that is, U+0000 through 'a'-1 and 'z'+1 through U+10FFFF
[[pat1][pat2]]	The union of sets specified by pat1 and pat2
[[pat1]&[pat2]]	The intersection of sets specified by pat1 and pat2
[[pat1]-[pat2]]	The asymmetric difference of sets specified by pat1 and pat2
[:Lu:] or \p{Lu}	The set of characters having the specified Unicode property; in this case, Unicode uppercase letters
[:^Lu:] or \P{Lu}	The set of characters not having the given Unicode property

Formal syntax

pattern :=	('[' '^'? item* ']') | property
item :=	char | (char '-' char) | pattern-expr
pattern-expr :=	pattern | pattern-expr pattern | pattern-expr op pattern
op :=	'&' | '-'
special :=	'[' | ']' | '-'
char :=	any character that is not special | ('\\' any character) | ('\u' hex hex hex hex)
hex :=	'0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' |     'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
property :=	a Unicode property set pattern

Legend: a := b   a may be replaced by b a? zero or one instance of a a* one or more instances of a a | b either a or b 'a' the literal string between the quotes

To iterate over contents of UnicodeSet, the following are available:

• ranges() to iterate through the ranges
• strings() to iterate through the strings
• iterator() to iterate through the entire contents in a single loop. That method is, however, not particularly efficient, since it "boxes" each code point into a String.

All of the above can be used in for loops. The UnicodeSetIterator can also be used, but not in for loops.

To replace, count elements, or delete spans, see UnicodeSetSpanner.