sun.text.normalizer
Class UnicodeSet

java.lang.Object
  sun.text.normalizer.UnicodeSet

All Implemented Interfaces:

UnicodeMatcher

public class UnicodeSet
extends Object
implements UnicodeMatcher

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 UCharacterProperty.isRuleWhiteSpace(), 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 http://oss.software.ibm.com/icu/userguide/unicodeSet.html. 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.

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

Warning: you cannot add an empty string ("") to a UnicodeSet.

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 :=	any character for which Character.digit(c, 16) returns a non-negative result
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

Field Summary

static int	IGNORE_SPACE Bitmask for constructor and applyPattern() indicating that white space should be ignored.
static int	MAX_VALUE Maximum value that can be stored in a UnicodeSet.
static int	MIN_VALUE Minimum value that can be stored in a UnicodeSet.

Fields inherited from interface sun.text.normalizer.UnicodeMatcher

ETHER

Constructor Summary

UnicodeSet()
Constructs an empty set.

UnicodeSet(int start, int end)
Constructs a set containing the given range.

UnicodeSet(String pattern)
Constructs a set from the given pattern.

Method Summary

StringBuffer	_generatePattern(StringBuffer result, boolean escapeUnprintable) Generate and append a string representation of this set to result.
UnicodeSet	add(int c) Adds the specified character to this set if it is not already present.
UnicodeSet	add(int start, int end) Adds the specified range to this set if it is not already present.
UnicodeSet	add(String s) Adds the specified multicharacter to this set if it is not already present.
UnicodeSet	addAll(UnicodeSet c) Adds all of the elements in the specified set to this set if they're not already present.
UnicodeSet	applyPattern(String pattern) Modifies this set to represent the set specified by the given pattern.
UnicodeSet	applyPropertyAlias(String propertyAlias, String valueAlias, SymbolTable symbols) Deprecated. This is a draft API and might change in a future release of ICU.
UnicodeSet	clear() Removes all of the elements from this set.
UnicodeSet	complement() This is equivalent to complement(MIN_VALUE, MAX_VALUE).
UnicodeSet	complement(int start, int end) Complements the specified range in this set.
boolean	contains(int c) Returns true if this set contains the given character.
int	getRangeCount() Iteration method that returns the number of ranges contained in this set.
int	getRangeEnd(int index) Iteration method that returns the last character in the specified range of this set.
int	getRangeStart(int index) Iteration method that returns the first character in the specified range of this set.
UnicodeSet	removeAll(UnicodeSet c) Removes from this set all of its elements that are contained in the specified set.
UnicodeSet	retainAll(UnicodeSet c) Retains only the elements in this set that are contained in the specified set.
UnicodeSet	set(UnicodeSet other) Make this object represent the same set as other.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_VALUE

public static final int MIN_VALUE

Minimum value that can be stored in a UnicodeSet.

See Also:

Constant Field Values

MAX_VALUE

public static final int MAX_VALUE

Maximum value that can be stored in a UnicodeSet.

See Also:

Constant Field Values

IGNORE_SPACE

public static final int IGNORE_SPACE

Bitmask for constructor and applyPattern() indicating that white space should be ignored. If set, ignore characters for which UCharacterProperty.isRuleWhiteSpace() returns true, unless they are quoted or escaped. This may be ORed together with other selectors.

See Also:

Constant Field Values

Constructor Detail

UnicodeSet

public UnicodeSet()

Constructs an empty set.

UnicodeSet

public UnicodeSet(int start,
                  int end)

Constructs a set containing the given range. If end > start then an empty set is created.

Parameters:

start - first character, inclusive, of range

end - last character, inclusive, of range

UnicodeSet

public UnicodeSet(String pattern)

Constructs a set from the given pattern. See the class description for the syntax of the pattern language. Whitespace is ignored.

Parameters:

pattern - a string specifying what characters are in the set

Throws:

IllegalArgumentException - if the pattern contains a syntax error.

Method Detail

set

public UnicodeSet set(UnicodeSet other)

Make this object represent the same set as other.

Parameters:

other - a UnicodeSet whose value will be copied to this object

applyPattern

public final UnicodeSet applyPattern(String pattern)

Modifies this set to represent the set specified by the given pattern. See the class description for the syntax of the pattern language. Whitespace is ignored.

Parameters:

pattern - a string specifying what characters are in the set

Throws:

IllegalArgumentException - if the pattern contains a syntax error.

_generatePattern

public StringBuffer _generatePattern(StringBuffer result,
                                     boolean escapeUnprintable)

Generate and append a string representation of this set to result. This does not use this.pat, the cleaned up copy of the string passed to applyPattern().

add

public UnicodeSet add(int start,
                      int end)

Adds the specified range to this set if it is not already present. If this set already contains the specified range, the call leaves this set unchanged. If end > start then an empty range is added, leaving the set unchanged.

Parameters:

start - first character, inclusive, of range to be added to this set.

end - last character, inclusive, of range to be added to this set.

add

public final UnicodeSet add(int c)

Adds the specified character to this set if it is not already present. If this set already contains the specified character, the call leaves this set unchanged.

add

public final UnicodeSet add(String s)

Adds the specified multicharacter to this set if it is not already present. If this set already contains the multicharacter, the call leaves this set unchanged. Thus "ch" => {"ch"}
Warning: you cannot add an empty string ("") to a UnicodeSet.

Parameters:

s - the source string

Returns:

this object, for chaining

complement

public UnicodeSet complement(int start,
                             int end)

Complements the specified range in this set. Any character in the range will be removed if it is in this set, or will be added if it is not in this set. If end > start then an empty range is complemented, leaving the set unchanged.

Parameters:

start - first character, inclusive, of range to be removed from this set.

end - last character, inclusive, of range to be removed from this set.

complement

public UnicodeSet complement()

This is equivalent to complement(MIN_VALUE, MAX_VALUE).

contains

public boolean contains(int c)

Returns true if this set contains the given character.

Parameters:

c - character to be checked for containment

Returns:

true if the test condition is met

addAll

public UnicodeSet addAll(UnicodeSet c)

Adds all of the elements in the specified set to this set if they're not already present. This operation effectively modifies this set so that its value is the union of the two sets. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress.

Parameters:

c - set whose elements are to be added to this set.

retainAll

public UnicodeSet retainAll(UnicodeSet c)

Retains only the elements in this set that are contained in the specified set. In other words, removes from this set all of its elements that are not contained in the specified set. This operation effectively modifies this set so that its value is the intersection of the two sets.

Parameters:

c - set that defines which elements this set will retain.

removeAll

public UnicodeSet removeAll(UnicodeSet c)

Removes from this set all of its elements that are contained in the specified set. This operation effectively modifies this set so that its value is the asymmetric set difference of the two sets.

Parameters:

c - set that defines which elements will be removed from this set.

clear

public UnicodeSet clear()

Removes all of the elements from this set. This set will be empty after this call returns.

getRangeCount

public int getRangeCount()

Iteration method that returns the number of ranges contained in this set.

See Also:

getRangeStart(int), getRangeEnd(int)

getRangeStart

public int getRangeStart(int index)

Iteration method that returns the first character in the specified range of this set.

Throws:

ArrayIndexOutOfBoundsException - if index is outside the range 0..getRangeCount()-1

See Also:

getRangeCount(), getRangeEnd(int)

getRangeEnd

public int getRangeEnd(int index)

Iteration method that returns the last character in the specified range of this set.

Throws:

ArrayIndexOutOfBoundsException - if index is outside the range 0..getRangeCount()-1

See Also:

getRangeStart(int), getRangeEnd(int)

applyPropertyAlias

public UnicodeSet applyPropertyAlias(String propertyAlias,
                                     String valueAlias,
                                     SymbolTable symbols)

Deprecated. This is a draft API and might change in a future release of ICU.

Modifies this set to contain those code points which have the given value for the given property. Prior contents of this set are lost.

Parameters:

propertyAlias -

valueAlias -

symbols - if not null, then symbols are first called to see if a property is available. If true, then everything else is skipped.

Returns:

this set