Package com.norconex.commons.lang.unit

# Enum Class DataUnit

java.lang.Object
java.lang.Enum<DataUnit>
com.norconex.commons.lang.unit.DataUnit

All Implemented Interfaces:
  `Serializable`, `Comparable<DataUnit>`, `Constable`

public enum DataUnit extends Enum<DataUnit>

A `DataUnit` offers representation and conversion of various quantity of bytes/bits. Release 2.0.0 introduces exa, zetta, and yotta units.

## Decimal vs binary notations

As of 2.0.0, this class aligns with the international standard system of units by treating decimal and binary notations distinctively. Each are represented as:

Data unit notations
Decimal | Binary
--- | ---
k | kilo | 103 | Ki | kibi | 210
M | mega | 106 | Mi | mebi | 220
G | giga | 109 | Gi | gibi | 230
T | tera | 1012 | Ti | tebi | 240
P | peta | 1015 | Pi | pebi | 250
E | exa | 1018 | Ei | exbi | 260
Z | zetta | 1021 | Zi | zebi | 270
Y | yotta | 1024 | Yi | yobi | 280

## Bytes vs bits

As of 2.0.0, this class supports bits in addition to bytes. They are represented as:

Bytes and bits notations
B | bytes (8-bit)
bit | bits

## Usage examples

       // how many kibibyte in a gibiabyte amount (binary notation).
       long kibibyte = DataUnit.GIB.to(3, KIB).longValue(); // results = 3072

       // how many megabyte in a kilobyte amount (decimal notation)
       float megabyte = DataUnit.KB.to(2500, MB).floatValue(); // results = 2.5

Since:
  1.4.0
See Also:
  - `DataUnitFormatter`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Enum

  `Enum.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `B`
  A single byte (8 bits).
  `BIT`
  A single bit.
  `EB`
  `EBIT`
  `EIB`
  `EIBIT`
  `GB`
  `GBIT`
  `GIB`
  `GIBIT`
  `KB`
  `KBIT`
  `KIB`
  `KIBIT`
  `MB`
  `MBIT`
  `MIB`
  `MIBIT`
  `PB`
  `PBIT`
  `PIB`
  `PIBIT`
  `TB`
  `TBIT`
  `TIB`
  `TIBIT`
  `YB`
  `YBIT`
  `YIB`
  `YIBIT`
  `ZB`
  `ZBIT`
  `ZIB`
  `ZIBIT`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final List<DataUnit>`
  `BINARY_BIT_UNITS`
  `static final List<DataUnit>`
  `BINARY_BYTE_UNITS`
  `static final List<DataUnit>`
  `DECIMAL_BIT_UNITS`
  `static final List<DataUnit>`
  `DECIMAL_BYTE_UNITS`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BigInteger`
  `bits()`
  `BigInteger`
  `bytes()`
  `BigDecimal`
  `from(double sourceAmount, DataUnit sourceUnit)`
  Converts an amount of a specific unit to this unit.
  `static DataUnit`
  `from(String dataUnit)`
  Gets the unit value representing the given text.
  `BigDecimal`
  `from(BigDecimal sourceAmount, DataUnit sourceUnit)`
  Converts an amount of a specific unit to this unit.
  `BigDecimal`
  `fromBits(double amount)`
  `BigDecimal`
  `fromBits(BigDecimal amount)`
  `BigDecimal`
  `fromBytes(double amount)`
  `BigDecimal`
  `fromBytes(BigDecimal amount)`
  `int`
  `getGroupIndex()`
  `String`
  `getName()`
  `String`
  `getPrefix()`
  `String`
  `getSymbol()`
  `boolean`
  `isBinary()`
  `boolean`
  `isBitUnit()`
  `boolean`
  `isByteUnit()`
  `boolean`
  `isDecimal()`
  `BigDecimal`
  `to(double sourceAmount, DataUnit targetUnit)`
  `BigDecimal`
  `to(BigDecimal sourceAmount, DataUnit targetUnit)`
  `BigDecimal`
  `toBits(double amount)`
  `BigDecimal`
  `toBits(BigDecimal amount)`
  `BigDecimal`
  `toBytes(double amount)`
  `BigDecimal`
  `toBytes(BigDecimal amount)`
  `String`
  `toString()`
  `static DataUnit`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static DataUnit[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

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

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf`

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

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### BIT

    public static final DataUnit BIT
    A single bit.

  - ### B

    public static final DataUnit B
    A single byte (8 bits).

  - ### KBIT

    public static final DataUnit KBIT

  - ### MBIT

    public static final DataUnit MBIT

  - ### GBIT

    public static final DataUnit GBIT

  - ### TBIT

    public static final DataUnit TBIT

  - ### PBIT

    public static final DataUnit PBIT

  - ### EBIT

    public static final DataUnit EBIT

  - ### ZBIT

    public static final DataUnit ZBIT

  - ### YBIT

    public static final DataUnit YBIT

  - ### KB

    public static final DataUnit KB

  - ### MB

    public static final DataUnit MB

  - ### GB

    public static final DataUnit GB

  - ### TB

    public static final DataUnit TB

  - ### PB

    public static final DataUnit PB

  - ### EB

    public static final DataUnit EB

  - ### ZB

    public static final DataUnit ZB

  - ### YB

    public static final DataUnit YB

  - ### KIBIT

    public static final DataUnit KIBIT

  - ### MIBIT

    public static final DataUnit MIBIT

  - ### GIBIT

    public static final DataUnit GIBIT

  - ### TIBIT

    public static final DataUnit TIBIT

  - ### PIBIT

    public static final DataUnit PIBIT

  - ### EIBIT

    public static final DataUnit EIBIT

  - ### ZIBIT

    public static final DataUnit ZIBIT

  - ### YIBIT

    public static final DataUnit YIBIT

  - ### KIB

    public static final DataUnit KIB

  - ### MIB

    public static final DataUnit MIB

  - ### GIB

    public static final DataUnit GIB

  - ### TIB

    public static final DataUnit TIB

  - ### PIB

    public static final DataUnit PIB

  - ### EIB

    public static final DataUnit EIB

  - ### ZIB

    public static final DataUnit ZIB

  - ### YIB

    public static final DataUnit YIB

- ## Field Details

  - ### DECIMAL_BIT_UNITS

    public static final List<DataUnit> DECIMAL_BIT_UNITS

  - ### DECIMAL_BYTE_UNITS

    public static final List<DataUnit> DECIMAL_BYTE_UNITS

  - ### BINARY_BIT_UNITS

    public static final List<DataUnit> BINARY_BIT_UNITS

  - ### BINARY_BYTE_UNITS

    public static final List<DataUnit> BINARY_BYTE_UNITS

- ## Method Details

  - ### values

    public static DataUnit[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static DataUnit valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### getSymbol

    public String getSymbol()

  - ### getPrefix

    public String getPrefix()

  - ### getName

    public String getName()

  - ### getGroupIndex

    public int getGroupIndex()

  - ### isBitUnit

    public boolean isBitUnit()

  - ### isByteUnit

    public boolean isByteUnit()

  - ### isBinary

    public boolean isBinary()

  - ### isDecimal

    public boolean isDecimal()

  - ### bits

    public BigInteger bits()

  - ### bytes

    public BigInteger bytes()

  - ### toBits

    public BigDecimal toBits(double amount)

  - ### toBits

    public BigDecimal toBits(BigDecimal amount)

  - ### toBytes

    public BigDecimal toBytes(double amount)

  - ### toBytes

    public BigDecimal toBytes(BigDecimal amount)

  - ### fromBits

    public BigDecimal fromBits(double amount)

  - ### fromBits

    public BigDecimal fromBits(BigDecimal amount)

  - ### fromBytes

    public BigDecimal fromBytes(double amount)

  - ### fromBytes

    public BigDecimal fromBytes(BigDecimal amount)

  - ### to

    public BigDecimal to(double sourceAmount, DataUnit targetUnit)

  - ### to

    public BigDecimal to(BigDecimal sourceAmount, DataUnit targetUnit)

  - ### from

    public BigDecimal from(double sourceAmount, DataUnit sourceUnit)
    Converts an amount of a specific unit to this unit.
    Parameters:
      `sourceAmount` - source amount to convert
      `sourceUnit` - source unit to convert
    Returns:
      converted value

  - ### from

    public BigDecimal from(BigDecimal sourceAmount, DataUnit sourceUnit)
    Converts an amount of a specific unit to this unit.
    Parameters:
      `sourceAmount` - source amount to convert
      `sourceUnit` - source unit to convert
    Returns:
      converted value

  - ### from

    public static DataUnit from(String dataUnit)
    Gets the unit value representing the given text. Both symbols or full names are supported (English or French, case-insensitive, ignoring accents).
    Parameters:
      `dataUnit` - the textual representation of the unit.
    Returns:
      DataUnit instance or `null` if no match.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Enum<DataUnit>`