CharSet

public class org.apache.commons.lang3.CharSet implements Serializable

A set of characters.

Instances are immutable, but instances of subclasses may not be.

#ThreadSafe#

Since:

1.0

Constructors

CharSet(String[])

Constructs a new CharSet using the set syntax.

protected CharSet(String... set)

Constructs a new CharSet using the set syntax. Each string is merged in with the set.

Parameters:

set – Strings to merge into the initial set.

Throws:

java.lang.NullPointerException – Thrown if set is null.

Fields and constants

ASCII_ALPHA	A CharSet defining ASCII alphabetic characters “a-zA-Z”.
ASCII_ALPHA_LOWER	A CharSet defining ASCII alphabetic characters “a-z”.
ASCII_ALPHA_UPPER	A CharSet defining ASCII alphabetic characters “A-Z”.
ASCII_NUMERIC	A CharSet defining ASCII alphabetic characters “0-9”.
COMMON	A Map of the common cases used in the factory.
EMPTY	A CharSet defining no characters.

public static final CharSet ASCII_ALPHA

A CharSet defining ASCII alphabetic characters “a-zA-Z”.

Since:

2.0

public static final CharSet ASCII_ALPHA_LOWER

A CharSet defining ASCII alphabetic characters “a-z”.

Since:

2.0

public static final CharSet ASCII_ALPHA_UPPER

A CharSet defining ASCII alphabetic characters “A-Z”.

Since:

2.0

public static final CharSet ASCII_NUMERIC

A CharSet defining ASCII alphabetic characters “0-9”.

Since:

2.0

protected static final Map<String, CharSet> COMMON

A Map of the common cases used in the factory.

Subclasses can add more common patterns if desired.

Since:

2.0

public static final CharSet EMPTY

A CharSet defining no characters.

Since:

2.0

Methods

add(String)	Add a set definition string to the CharSet.
contains(char)	Tests whether this CharSet contain the specified character ch.
equals(Object)	Compares two CharSet objects, returning true if they represent exactly the same set of characters defined in the same way.
getInstance(String[])	Gets a new CharSet using the syntax described below.
hashCode()	Gets a hash code compatible with the equals method.
toString()	Gets a string representation of the set.

protected void add(String str)

Add a set definition string to the CharSet.

Parameters:

str – set definition string

public boolean contains(char ch)

Tests whether this CharSet contain the specified character ch.

Examples using the negation character:

    CharSet.getInstance("^a-c").contains('a') = false
    CharSet.getInstance("^a-c").contains('d') = true
    CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is negated)
    CharSet.getInstance("^^a-c").contains('^') = false
    CharSet.getInstance("^a-cd-f").contains('d') = true
    CharSet.getInstance("a-c^").contains('^') = true
    CharSet.getInstance("^", "a-c").contains('^') = true

Parameters:

ch – The character to check.

Returns:

true if the set contains the characters.

@Override public boolean equals(Object obj)

Compares two CharSet objects, returning true if they represent exactly the same set of characters defined in the same way.

The two sets abc and a-c are not equal according to this method.

Parameters:

obj – The object to compare.

Returns:

true if equal.

Since:

2.0

public static CharSet getInstance(String... setStrs)

Gets a new CharSet using the syntax described below.

• null or empty string (“”) - set containing no characters

• Single character, such as “a” - set containing just that character

• Multi character, such as “a-e” - set containing characters from one character to the other

• Negated, such as “^a” or “^a-e” - set containing all characters except those defined

• Combinations, such as “abe-g” - set containing all the characters from the individual sets

The matching order is:

1. Negated multi character range, such as “^a-e”

2. Ordinary multi character range, such as “a-e”

3. Negated single character, such as “^a”

4. Ordinary single character, such as “a”

Matching works left to right. Once a match is found the search starts again from the next character.

If the same range is defined twice using the same syntax, only one range will be kept. Thus, “a-ca-c” creates only one range of “a-c”.

If the start and end of a range are in the wrong order, they are reversed. Thus “a-e” is the same as “e-a”. As a result, “a-ee-a” would create only one range, as the “a-e” and “e-a” are the same.

The set of characters represented is the union of the specified ranges.

There are two ways to add a literal negation character (^):

• As the last character in a string, e.g. CharSet.getInstance("a-z^")

• As a separate element, e.g. CharSet.getInstance("^", "a-z")

Examples using the negation character:

    CharSet.getInstance("^a-c").contains('a') = false
    CharSet.getInstance("^a-c").contains('d') = true
    CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is negated)
    CharSet.getInstance("^^a-c").contains('^') = false
    CharSet.getInstance("^a-cd-f").contains('d') = true
    CharSet.getInstance("a-c^").contains('^') = true
    CharSet.getInstance("^", "a-c").contains('^') = true

All CharSet objects returned by this method will be immutable.

Parameters:

setStrs – Strings to merge into the set, may be null.

Returns:

A CharSet instance.

Since:

2.4

@Override public int hashCode()

Gets a hash code compatible with the equals method.

Returns:

A suitable hash code.

Since:

2.0

@Override public String toString()

Gets a string representation of the set.

Returns:

string representation of the set.