Package org.apache.commons.lang3

## Class CharSet

- java.lang.Object
- - org.apache.commons.lang3.CharSet

All Implemented Interfaces:
  `java.io.Serializable`

    public class CharSet
    extends java.lang.Object
    implements java.io.Serializable

A set of characters.

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

#ThreadSafe#

Since:
  1.0
See Also:
  Serialized Form

### Field Summary

Fields
`static CharSet` `ASCII_ALPHA` A CharSet defining ASCII alphabetic characters "a-zA-Z".
`static CharSet` `ASCII_ALPHA_LOWER` A CharSet defining ASCII alphabetic characters "a-z".
`static CharSet` `ASCII_ALPHA_UPPER` A CharSet defining ASCII alphabetic characters "A-Z".
`static CharSet` `ASCII_NUMERIC` A CharSet defining ASCII alphabetic characters "0-9".
`protected static java.util.Map<java.lang.String,​CharSet>` `COMMON` A Map of the common cases used in the factory.
`static CharSet` `EMPTY` A CharSet defining no characters.

### Constructor Summary

Constructors
`protected` `CharSet​(java.lang.String... set)` Constructs a new CharSet using the set syntax.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`protected void` `add​(java.lang.String str)` Add a set definition string to the `CharSet`.
`boolean` `contains​(char ch)` Does the `CharSet` contain the specified character `ch`.
`boolean` `equals​(java.lang.Object obj)` Compares two `CharSet` objects, returning true if they represent exactly the same set of characters defined in the same way.
`static CharSet` `getInstance​(java.lang.String... setStrs)` Factory method to create a new CharSet using a special syntax.
`int` `hashCode()` Gets a hash code compatible with the equals method.
`java.lang.String` `toString()` Gets a string representation of the set.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### EMPTY

    public static final CharSet EMPTY

A CharSet defining no characters.

Since:
  2.0

#### ASCII_ALPHA

    public static final CharSet ASCII_ALPHA

A CharSet defining ASCII alphabetic characters "a-zA-Z".

Since:
  2.0

#### ASCII_ALPHA_LOWER

    public static final CharSet ASCII_ALPHA_LOWER

A CharSet defining ASCII alphabetic characters "a-z".

Since:
  2.0

#### ASCII_ALPHA_UPPER

    public static final CharSet ASCII_ALPHA_UPPER

A CharSet defining ASCII alphabetic characters "A-Z".

Since:
  2.0

#### ASCII_NUMERIC

    public static final CharSet ASCII_NUMERIC

A CharSet defining ASCII alphabetic characters "0-9".

Since:
  2.0

#### COMMON

    protected static final java.util.Map<java.lang.String,​CharSet> COMMON

A Map of the common cases used in the factory. Subclasses can add more common patterns if desired

Since:
  2.0

### Constructor Detail

#### CharSet

    protected CharSet​(java.lang.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` - if set is `null`

### Method Detail

#### getInstance

    public static CharSet getInstance​(java.lang.String... setStrs)

Factory method to create a new CharSet using a special syntax.

- `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

#### add

    protected void add​(java.lang.String str)

Add a set definition string to the `CharSet`.

Parameters:
  `str` - set definition string

#### contains

    public boolean contains​(char ch)

Does the `CharSet` contain the specified character `ch`.

Parameters:
  `ch` - the character to check for
Returns:
  `true` if the set contains the characters

#### equals

    public boolean equals​(java.lang.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.

Overrides:
  `equals` in class `java.lang.Object`
Parameters:
  `obj` - the object to compare to
Returns:
  true if equal
Since:
  2.0

#### hashCode

    public int hashCode()

Gets a hash code compatible with the equals method.

Overrides:
  `hashCode` in class `java.lang.Object`
Returns:
  a suitable hash code
Since:
  2.0

#### toString

    public java.lang.String toString()

Gets a string representation of the set.

Overrides:
  `toString` in class `java.lang.Object`
Returns:
  string representation of the set