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 and Description
    `EnumUtils()` This constructor is public to permit tools that require a JavaBean instance to operate.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

    - #### EnumUtils

          public EnumUtils()

      This constructor is public to permit tools that require a JavaBean instance to operate.

  - ### Method Detail

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

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