EnumUtils
Date: 2017-02-08

org.apache.commons.lang3

## Class EnumUtils

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

-     public class EnumUtils
      extends java.lang.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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <E extends java.lang.Enum<E>> long` | `generateBitVector(java.lang.Class<E> enumClass, E... values)` Creates a long bit vector representation of the given array of Enum values.
    `static <E extends java.lang.Enum<E>> long` | `generateBitVector(java.lang.Class<E> enumClass, java.lang.Iterable<? extends E> values)` Creates a long bit vector representation of the given subset of an Enum.
    `static <E extends java.lang.Enum<E>> long[]` | `generateBitVectors(java.lang.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 java.lang.Enum<E>> long[]` | `generateBitVectors(java.lang.Class<E> enumClass, java.lang.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 java.lang.Enum<E>> E` | `getEnum(java.lang.Class<E> enumClass, java.lang.String enumName)` Gets the enum for the class, returning `null` if not found.
    `static <E extends java.lang.Enum<E>> java.util.List<E>` | `getEnumList(java.lang.Class<E> enumClass)` Gets the `List` of enums.
    `static <E extends java.lang.Enum<E>> java.util.Map<java.lang.String,E>` | `getEnumMap(java.lang.Class<E> enumClass)` Gets the `Map` of enums by name.
    `static <E extends java.lang.Enum<E>> boolean` | `isValidEnum(java.lang.Class<E> enumClass, java.lang.String enumName)` Checks if the specified name is a valid enum for the class.
    `static <E extends java.lang.Enum<E>> java.util.EnumSet<E>` | `processBitVector(java.lang.Class<E> enumClass, long value)` Convert a long value created by `generateBitVector(java.lang.Class<E>, java.lang.Iterable<? extends E>)` into the set of enum values that it represents.
    `static <E extends java.lang.Enum<E>> java.util.EnumSet<E>` | `processBitVectors(java.lang.Class<E> enumClass, long... values)` Convert a `long[]` created by `generateBitVectors(java.lang.Class<E>, java.lang.Iterable<? extends 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

    - #### getEnumMap

          public static <E extends java.lang.Enum<E>> java.util.Map<java.lang.String,E> getEnumMap(java.lang.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

    - #### getEnumList

          public static <E extends java.lang.Enum<E>> java.util.List<E> getEnumList(java.lang.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

    - #### isValidEnum

          public static <E extends java.lang.Enum<E>> boolean isValidEnum(java.lang.Class<E> enumClass,
                                                          java.lang.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 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

    - #### getEnum

          public static <E extends java.lang.Enum<E>> E getEnum(java.lang.Class<E> enumClass,
                                                java.lang.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

    - #### generateBitVector

          public static <E extends java.lang.Enum<E>> long generateBitVector(java.lang.Class<E> enumClass,
                                                             java.lang.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:
        `java.lang.NullPointerException` - if `enumClass` or `values` is `null`
        `java.lang.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

          public static <E extends java.lang.Enum<E>> long[] generateBitVectors(java.lang.Class<E> enumClass,
                                                                java.lang.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 least significant digits rightmost.
      Throws:
        `java.lang.NullPointerException` - if `enumClass` or `values` is `null`
        `java.lang.IllegalArgumentException` - if `enumClass` is not an enum class, or if any `values` `null`
      Since:
        3.2

    - #### generateBitVector

          public static <E extends java.lang.Enum<E>> long generateBitVector(java.lang.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:
        `java.lang.NullPointerException` - if `enumClass` or `values` is `null`
        `java.lang.IllegalArgumentException` - if `enumClass` is not an enum class or has more than 64 values
      Since:
        3.0.1
      See Also:
        `generateBitVectors(Class, Iterable)`

    - #### generateBitVectors

          public static <E extends java.lang.Enum<E>> long[] generateBitVectors(java.lang.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 least significant digits rightmost.
      Throws:
        `java.lang.NullPointerException` - if `enumClass` or `values` is `null`
        `java.lang.IllegalArgumentException` - if `enumClass` is not an enum class, or if any `values` `null`
      Since:
        3.2

    - #### processBitVector

          public static <E extends java.lang.Enum<E>> java.util.EnumSet<E> processBitVector(java.lang.Class<E> enumClass,
                                                                            long value)

      Convert a long value created by `generateBitVector(java.lang.Class<E>, java.lang.Iterable<? extends 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:
        `java.lang.NullPointerException` - if `enumClass` is `null`
        `java.lang.IllegalArgumentException` - if `enumClass` is not an enum class or has more than 64 values
      Since:
        3.0.1

    - #### processBitVectors

          public static <E extends java.lang.Enum<E>> java.util.EnumSet<E> processBitVectors(java.lang.Class<E> enumClass,
                                                                             long... values)

      Convert a `long[]` created by `generateBitVectors(java.lang.Class<E>, java.lang.Iterable<? extends 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, least significant digits rightmost, not `null`
      Returns:
        a set of enum values
      Throws:
        `java.lang.NullPointerException` - if `enumClass` is `null`
        `java.lang.IllegalArgumentException` - if `enumClass` is not an enum class
      Since:
        3.2