org.apache.commons.lang3

## Class CharSet

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

- All Implemented Interfaces:
    Serializable

      public class CharSet
      extends Object
      implements 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
    Modifier and Type | Field and Description
    --- | ---
    `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 Map<String,CharSet>` | `COMMON` A Map of the common cases used in the factory.
    `static CharSet` | `EMPTY` A CharSet defining no characters.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CharSet(String... set)` Constructs a new CharSet using the set syntax.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `add(String str)` Add a set definition string to the `CharSet`.
    `boolean` | `contains(char ch)` Does the `CharSet` contain the specified character `ch`.
    `boolean` | `equals(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(String... setStrs)` Factory method to create a new CharSet using a special syntax.
    `int` | `hashCode()` Gets a hash code compatible with the equals method.
    `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 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

  - ### Constructor Detail

    - #### CharSet

          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:
        `NullPointerException` - if set is `null`

  - ### Method Detail

    - #### getInstance

          public static CharSet getInstance(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(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(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 `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 `Object`
      Returns:
        a suitable hash code
      Since:
        2.0

    - #### toString

          public String toString()

      Gets a string representation of the set.
      Overrides:
        `toString` in class `Object`
      Returns:
        string representation of the set

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.