EnumUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3, class: EnumUtils

Package org.apache.commons.lang3

# Class EnumUtils

java.lang.Object
org.apache.commons.lang3.EnumUtils

public class EnumUtils extends Object
Utility library to provide helper methods for Java enums.

#ThreadSafe#

Since:
  3.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EnumUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E extends Enum<E>>
  long`
  `generateBitVector(Class<E> enumClass, E... values)`
  Creates a long bit vector representation of the given array of Enum values.
  `static <E extends Enum<E>>
  long`
  `generateBitVector(Class<E> enumClass, Iterable<? extends E> values)`
  Creates a long bit vector representation of the given subset of an Enum.
  `static <E extends Enum<E>>
  long[]`
  `generateBitVectors(Class<E> enumClass, E... values)`
  Creates a bit vector representation of the given subset of an Enum using as many `long`s as needed.
  `static <E extends Enum<E>>
  long[]`
  `generateBitVectors(Class<E> enumClass, Iterable<? extends E> values)`
  Creates a bit vector representation of the given subset of an Enum using as many `long`s as needed.
  `static <E extends Enum<E>>
  E`
  `getEnum(Class<E> enumClass, String enumName)`
  Gets the enum for the class, returning `null` if not found.
  `static <E extends Enum<E>>
  E`
  `getEnum(Class<E> enumClass, String enumName, E defaultEnum)`
  Gets the enum for the class, returning `defaultEnum` if not found.
  `static <E extends Enum<E>>
  E`
  `getEnumIgnoreCase(Class<E> enumClass, String enumName)`
  Gets the enum for the class, returning `null` if not found.
  `static <E extends Enum<E>>
  E`
  `getEnumIgnoreCase(Class<E> enumClass, String enumName, E defaultEnum)`
  Gets the enum for the class, returning `defaultEnum` if not found.
  `static <E extends Enum<E>>
  List<E>`
  `getEnumList(Class<E> enumClass)`
  Gets the `List` of enums.
  `static <E extends Enum<E>>
  Map<String,E>`
  `getEnumMap(Class<E> enumClass)`
  Gets the `Map` of enums by name.
  `static <E extends Enum<E>, K>
  Map<K,E>`
  `getEnumMap(Class<E> enumClass, Function<E,K> keyFunction)`
  Gets the `Map` of enums by name.
  `static <E extends Enum<E>>
  E`
  `getEnumSystemProperty(Class<E> enumClass, String propName, E defaultEnum)`
  Gets the enum for the class in a system property, returning `defaultEnum` if not found.
  `static <E extends Enum<E>>
  E`
  `getFirstEnumIgnoreCase(Class<E> enumClass, String enumName, Function<E,String> stringFunction, E defaultEnum)`
  Gets the enum for the class, returning `defaultEnum` if not found.
  `static <E extends Enum<E>>
  boolean`
  `isValidEnum(Class<E> enumClass, String enumName)`
  Checks if the specified name is a valid enum for the class.
  `static <E extends Enum<E>>
  boolean`
  `isValidEnumIgnoreCase(Class<E> enumClass, String enumName)`
  Checks if the specified name is a valid enum for the class.
  `static <E extends Enum<E>>
  EnumSet<E>`
  `processBitVector(Class<E> enumClass, long value)`
  Convert a long value created by `generateBitVector(java.lang.Class<E>, E...)` into the set of enum values that it represents.
  `static <E extends Enum<E>>
  EnumSet<E>`
  `processBitVectors(Class<E> enumClass, long... values)`
  Convert a `long[]` created by `generateBitVectors(java.lang.Class<E>, E...)` into the set of enum values that it represents.

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

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

- ## Constructor Details

  - ### EnumUtils

    @Deprecated public EnumUtils()
    Deprecated.
    TODO Make private in 4.0.
    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### generateBitVector

    @SafeVarargs public static <E extends Enum<E>> long generateBitVector(Class<E> enumClass, E... values)
    Creates a long bit vector representation of the given array of Enum values.

    This generates a value that is usable by `processBitVector(java.lang.Class<E>, long)`.

    Do not use this method if you have more than 64 values in your Enum, as this would create a value greater than a long can hold.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `values` - the values we want to convert, not `null`
    Returns:
      a long whose value provides a binary representation of the given set of enum values.
    Throws:
      `NullPointerException` - if `enumClass` or `values` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class or has more than 64 values
    Since:
      3.0.1
    See Also:
      - `generateBitVectors(Class, Iterable)`

  - ### generateBitVector

    public static <E extends Enum<E>> long generateBitVector(Class<E> enumClass, Iterable<? extends E> values)
    Creates a long bit vector representation of the given subset of an Enum.

    This generates a value that is usable by `processBitVector(java.lang.Class<E>, long)`.

    Do not use this method if you have more than 64 values in your Enum, as this would create a value greater than a long can hold.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `values` - the values we want to convert, not `null`, neither containing `null`
    Returns:
      a long whose value provides a binary representation of the given set of enum values.
    Throws:
      `NullPointerException` - if `enumClass` or `values` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class or has more than 64 values, or if any `values` `null`
    Since:
      3.0.1
    See Also:
      - `generateBitVectors(Class, Iterable)`

  - ### generateBitVectors

    @SafeVarargs public static <E extends Enum<E>> long[] generateBitVectors(Class<E> enumClass, E... values)
    Creates a bit vector representation of the given subset of an Enum using as many `long`s as needed.

    This generates a value that is usable by `processBitVectors(java.lang.Class<E>, long...)`.

    Use this method if you have more than 64 values in your Enum.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `values` - the values we want to convert, not `null`, neither containing `null`
    Returns:
      a long[] whose values provide a binary representation of the given set of enum values with the least significant digits rightmost.
    Throws:
      `NullPointerException` - if `enumClass` or `values` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class, or if any `values` `null`
    Since:
      3.2

  - ### generateBitVectors

    public static <E extends Enum<E>> long[] generateBitVectors(Class<E> enumClass, Iterable<? extends E> values)
    Creates a bit vector representation of the given subset of an Enum using as many `long`s as needed.

    This generates a value that is usable by `processBitVectors(java.lang.Class<E>, long...)`.

    Use this method if you have more than 64 values in your Enum.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `values` - the values we want to convert, not `null`, neither containing `null`
    Returns:
      a long[] whose values provide a binary representation of the given set of enum values with the least significant digits rightmost.
    Throws:
      `NullPointerException` - if `enumClass` or `values` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class, or if any `values` `null`
    Since:
      3.2

  - ### getEnum

    public static <E extends Enum<E>> E getEnum(Class<E> enumClass, String enumName)
    Gets the enum for the class, returning `null` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns null
    Returns:
      the enum, null if not found

  - ### getEnum

    public static <E extends Enum<E>> E getEnum(Class<E> enumClass, String enumName, E defaultEnum)
    Gets the enum for the class, returning `defaultEnum` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns default enum
      `defaultEnum` - the default enum
    Returns:
      the enum, default enum if not found
    Since:
      3.10

  - ### getEnumIgnoreCase

    public static <E extends Enum<E>> E getEnumIgnoreCase(Class<E> enumClass, String enumName)
    Gets the enum for the class, returning `null` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name and performs case insensitive matching of the name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns null
    Returns:
      the enum, null if not found
    Since:
      3.8

  - ### getEnumIgnoreCase

    public static <E extends Enum<E>> E getEnumIgnoreCase(Class<E> enumClass, String enumName, E defaultEnum)
    Gets the enum for the class, returning `defaultEnum` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name and performs case insensitive matching of the name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns default enum
      `defaultEnum` - the default enum
    Returns:
      the enum, default enum if not found
    Since:
      3.10

  - ### getEnumList

    public static <E extends Enum<E>> List<E> getEnumList(Class<E> enumClass)
    Gets the `List` of enums.

    This method is useful when you need a list of enums rather than an array.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
    Returns:
      the modifiable list of enums, never null

  - ### getEnumMap

    public static <E extends Enum<E>> Map<String,E> getEnumMap(Class<E> enumClass)
    Gets the `Map` of enums by name.

    This method is useful when you need a map of enums by name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
    Returns:
      the modifiable map of enum names to enums, never null

  - ### getEnumMap

    public static <E extends Enum<E>, K> Map<K,E> getEnumMap(Class<E> enumClass, Function<E,K> keyFunction)
    Gets the `Map` of enums by name.

    This method is useful when you need a map of enums by name.

    Type Parameters:
      `E` - the type of enumeration
      `K` - the type of the map key
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `keyFunction` - the function to query for the key, not null
    Returns:
      the modifiable map of enums, never null
    Since:
      3.13.0

  - ### getEnumSystemProperty

    public static <E extends Enum<E>> E getEnumSystemProperty(Class<E> enumClass, String propName, E defaultEnum)
    Gets the enum for the class in a system property, returning `defaultEnum` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `propName` - the system property key for the enum name, null returns default enum
      `defaultEnum` - the default enum
    Returns:
      the enum, default enum if not found
    Since:
      3.13.0

  - ### getFirstEnumIgnoreCase

    public static <E extends Enum<E>> E getFirstEnumIgnoreCase(Class<E> enumClass, String enumName, Function<E,String> stringFunction, E defaultEnum)
    Gets the enum for the class, returning `defaultEnum` if not found.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it does not throw an exception for an invalid enum name and performs case insensitive matching of the name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns default enum
      `stringFunction` - the function that gets the string for an enum for comparison to `enumName`.
      `defaultEnum` - the default enum
    Returns:
      the enum, default enum if not found
    Since:
      3.13.0

  - ### isValidEnum

    public static <E extends Enum<E>> boolean isValidEnum(Class<E> enumClass, String enumName)
    Checks if the specified name is a valid enum for the class.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it checks if the name is a valid enum without needing to catch the exception.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns false
    Returns:
      true if the enum name is valid, otherwise false

  - ### isValidEnumIgnoreCase

    public static <E extends Enum<E>> boolean isValidEnumIgnoreCase(Class<E> enumClass, String enumName)
    Checks if the specified name is a valid enum for the class.

    This method differs from `Enum.valueOf(java.lang.Class<T>, java.lang.String)` in that it checks if the name is a valid enum without needing to catch the exception and performs case insensitive matching of the name.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum to query, not null
      `enumName` - the enum name, null returns false
    Returns:
      true if the enum name is valid, otherwise false
    Since:
      3.8

  - ### processBitVector

    public static <E extends Enum<E>> EnumSet<E> processBitVector(Class<E> enumClass, long value)
    Convert a long value created by `generateBitVector(java.lang.Class<E>, E...)` into the set of enum values that it represents.

    If you store this value, beware any changes to the enum that would affect ordinal values.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `value` - the long value representation of a set of enum values
    Returns:
      a set of enum values
    Throws:
      `NullPointerException` - if `enumClass` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class or has more than 64 values
    Since:
      3.0.1

  - ### processBitVectors

    public static <E extends Enum<E>> EnumSet<E> processBitVectors(Class<E> enumClass, long... values)
    Convert a `long[]` created by `generateBitVectors(java.lang.Class<E>, E...)` into the set of enum values that it represents.

    If you store this value, beware any changes to the enum that would affect ordinal values.

    Type Parameters:
      `E` - the type of the enumeration
    Parameters:
      `enumClass` - the class of the enum we are working with, not `null`
      `values` - the long[] bearing the representation of a set of enum values, the least significant digits rightmost, not `null`
    Returns:
      a set of enum values
    Throws:
      `NullPointerException` - if `enumClass` is `null`
      `IllegalArgumentException` - if `enumClass` is not an enum class
    Since:
      3.2