StorageUnit (stdlib 8.7.1 API)

java.lang.Object
- java.lang.Enum<StorageUnit>
- - com.peterphi.std.types.StorageUnit

All Implemented Interfaces:

Serializable, Comparable<StorageUnit>
```
public enum StorageUnit
extends Enum<StorageUnit>
```
Represents Storage unit conversions in a similar fashion to how TimeUnit represents time unit conversions
This enumeration reflects the confused landscape of storage units: it contains computer science units (binary), storage industry units (decimal) and network industry units (decimal, bit-based)

KILOBYTE as used here is, in fact, according to the ISO a Kibibyte. If your code needs to present ISO units to users, call the getISOUnit() method (which returns the short-form ISO unit - eg. "KiB" for KILOBYTES, "KB" for DECIMAL_KILOBYTES and "Kb" for KILOBIT)

Enum Constant Summary

Enum Constants
Enum Constant and Description
`BITS` One bit (4 bits)
`BYTES` One byte (8 bits)
`DECIMAL_EXABYTES` One decimal Exabyte (ISO: EB).
`DECIMAL_GIGABYTES` One decimal gigabyte (ISO: GB).
`DECIMAL_KILOBYTES` One decimal kilobyte (ISO: KB).
`DECIMAL_MEGABYTES` One decimal megabyte (ISO: MB).
`DECIMAL_PETABYTES` One decimal Petabyte (ISO: PB).
`DECIMAL_TERABYTES` One decimal terabyte (ISO: TB).
`DECIMAL_YOTTABYTES` One decimal yottabyte (ISO YB).
`DECIMAL_ZETTABYTES` One decimal zettabyte (ISO ZB).
`EXABITS` One Exabit (ISO: Eb).
`EXABYTES` One Exabyte (ISO: EiB) The ISO long form name for this unit is Exbibibyte (which we avoid using as the enum name to avoid confusion)
`GIGABITS` One Gigabit (ISO: Gb).
`GIGABYTES` One Gigabyte (ISO: GiB) The ISO long form name for this unit is Gibibyte (which we avoid using as the enum name to avoid confusion)
`KILOBITS` One Kilobit (ISO: Kb).
`KILOBYTES` One Kilobyte (ISO: KiB).
`MEGABITS` One Megabit (ISO: Mb).
`MEGABYTES` One Megabyte (ISO: MiB) The ISO long form name for this unit is Mebibyte (which we avoid using as the enum name to avoid confusion)
`NIBBLES` One nibble (4 bits)
`PETABITS` One Petabit (ISO: Pb).
`PETABYTES` One Petabyte (ISO: PiB) The ISO long form name for this unit is Pebibyte (which we avoid using as the enum name to avoid confusion)
`TERABITS` One Terabit (ISO: Tb).
`TERABYTES` One Terabyte (ISO: TiB) The ISO long form name for this unit is Tebibyte (which we avoid using as the enum name to avoid confusion)
`YOTTABITS` One yottabit (ISO Yb).
`YOTTABYTES` One yottabyte (ISO YiB) The ISO long form name for this unit is Yobibyte (which we avoid using as the enum name to avoid confusion)
`ZETTABITS` One zettabit (ISO Zb).
`ZETTABYTES` One zettabyte (ISO ZiB) The ISO long form name for this unit is Zebibyte (which we avoid using as the enum name to avoid confusion)

Field Summary

Fields
Modifier and Type	Field and Description
`static StorageUnit[]`	`BINARY_QUANTIFIERS` The range of quantifiers for binary units (bytes to terabytes (ISO: B to TiB))
`static StorageUnit[]`	`COMPSCI_BINARY`
`static StorageUnit[]`	`DECIMAL_QUANTIFIERS` The range of quantifiers for ISO decimal units (bytes to terabytes (ISO: B to TB))
`static StorageUnit[]`	`NETWORK_DECIMAL`
`static int`	`ROUNDING_MODE` The rounding mode this class uses; this is, by default, `BigDecimal.ROUND_HALF_UP`
`static StorageUnit[]`	`STORAGE_DECIMAL`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BigDecimal`	`convert(BigDecimal amount, StorageUnit unit)`
`BigInteger`	`convert(BigInteger amount, StorageUnit unit)`
`long`	`convert(long amount, StorageUnit unit)`
`BigDecimal`	`fromBits(BigDecimal bits)`
`BigInteger`	`fromBits(BigInteger bits)`
`static StorageUnit`	`getAppropriateBinaryUnit(BigInteger amount, StorageUnit sourceUnit)` Attempts to locate the most appropriate binary unit (binary units are what everyone but the ISO and the storage industry mean by "KB", "MB", etc.
`static StorageUnit`	`getAppropriateDecimalUnit(BigInteger amount, StorageUnit sourceUnit)` Attempts to locate the most appropriate decimal unit (decimal units are what the ISO and the storage industry (but nobody else) mean by "KB", "MB", etc.
`static StorageUnit`	`getAppropriateUnit(BigInteger amount, StorageUnit sourceUnit, StorageUnit[] options)` Attempts to locate the most appropriate of the provided units to express the provided amount in for human use (balancing precision and sensible expression)
`String`	`getISOUnit()` Return the ISO unit for this storage unit. for MEGABYTE this will return MiB (to avoid further confusion)
`String`	`getPlural()` Get the plural version of this unit (e.g.
`String`	`getSingular()` Get the singular version of this unit (e.g.
`static StorageUnit`	`largest(StorageUnit unit, StorageUnit unit2)` Returns the the larger unit of `unit` and unit2
`static StorageUnit`	`parse(String original)` Parse the non-ISO abbreviation: MiB and MB both -> MEGABYTE (which is technically a "Mebibyte")
`static StorageUnit`	`parseISO(String toParse)` Parse the ISO abbreviation: (e.g.
`static StorageUnit`	`smallest(StorageUnit unit, StorageUnit unit2)` Returns the the most diminutive unit of `unit` and unit2
`BigDecimal`	`toBits(BigDecimal amount)`
`BigInteger`	`toBits(BigInteger amount)`
`BigDecimal`	`toBytes(BigDecimal amount)`
`BigInteger`	`toBytes(BigInteger amount)`
`long`	`toBytes(long amount)`
`String`	`toString(BigDecimal amount)`
`String`	`toString(BigDecimal amount, boolean shortType)`
`String`	`toString(BigInteger amount)`
`String`	`toString(BigInteger amount, boolean shortType)`
`String`	`toString(long amount)`
`String`	`toString(long amount, boolean shortType)`
`static StorageUnit`	`valueOf(String name)` Returns the enum constant of this type with the specified name.
`static StorageUnit[]`	`values()` Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Enum Constant Detail
  - BITS
```
public static final StorageUnit BITS
```
    One bit (4 bits)
  - NIBBLES
```
public static final StorageUnit NIBBLES
```
    One nibble (4 bits)
  - BYTES
```
public static final StorageUnit BYTES
```
    One byte (8 bits)
  - KILOBYTES
```
public static final StorageUnit KILOBYTES
```
    One Kilobyte (ISO: KiB). 1 Kilobyte = 1024 bytes (8192 bits).
    The ISO long form name for this unit is Kibibyte (which we avoid using as the enum name to avoid confusion)
  - MEGABYTES
```
public static final StorageUnit MEGABYTES
```
    One Megabyte (ISO: MiB)
    The ISO long form name for this unit is Mebibyte (which we avoid using as the enum name to avoid confusion)
  - GIGABYTES
```
public static final StorageUnit GIGABYTES
```
    One Gigabyte (ISO: GiB)
    The ISO long form name for this unit is Gibibyte (which we avoid using as the enum name to avoid confusion)
  - TERABYTES
```
public static final StorageUnit TERABYTES
```
    One Terabyte (ISO: TiB)
    The ISO long form name for this unit is Tebibyte (which we avoid using as the enum name to avoid confusion)
  - PETABYTES
```
public static final StorageUnit PETABYTES
```
    One Petabyte (ISO: PiB)
    The ISO long form name for this unit is Pebibyte (which we avoid using as the enum name to avoid confusion)
  - EXABYTES
```
public static final StorageUnit EXABYTES
```
    One Exabyte (ISO: EiB)
    The ISO long form name for this unit is Exbibibyte (which we avoid using as the enum name to avoid confusion)
  - ZETTABYTES
```
public static final StorageUnit ZETTABYTES
```
    One zettabyte (ISO ZiB)
    The ISO long form name for this unit is Zebibyte (which we avoid using as the enum name to avoid confusion)
  - YOTTABYTES
```
public static final StorageUnit YOTTABYTES
```
    One yottabyte (ISO YiB)
    The ISO long form name for this unit is Yobibyte (which we avoid using as the enum name to avoid confusion)
  - DECIMAL_KILOBYTES
```
public static final StorageUnit DECIMAL_KILOBYTES
```
    One decimal kilobyte (ISO: KB). As used by the storage industry. 1 decimal kilobyte = 1000 bytes (8000 bits)
  - DECIMAL_MEGABYTES
```
public static final StorageUnit DECIMAL_MEGABYTES
```
    One decimal megabyte (ISO: MB). As used by the storage industry
  - DECIMAL_GIGABYTES
```
public static final StorageUnit DECIMAL_GIGABYTES
```
    One decimal gigabyte (ISO: GB). As used by the storage industry
  - DECIMAL_TERABYTES
```
public static final StorageUnit DECIMAL_TERABYTES
```
    One decimal terabyte (ISO: TB). As used by the storage industry
  - DECIMAL_PETABYTES
```
public static final StorageUnit DECIMAL_PETABYTES
```
    One decimal Petabyte (ISO: PB). As used by the storage industry
  - DECIMAL_EXABYTES
```
public static final StorageUnit DECIMAL_EXABYTES
```
    One decimal Exabyte (ISO: EB). As used by the storage industry
  - DECIMAL_ZETTABYTES
```
public static final StorageUnit DECIMAL_ZETTABYTES
```
    One decimal zettabyte (ISO ZB). As used by the storage industry
  - DECIMAL_YOTTABYTES
```
public static final StorageUnit DECIMAL_YOTTABYTES
```
    One decimal yottabyte (ISO YB). As used by the storage industry
  - KILOBITS
```
public static final StorageUnit KILOBITS
```
    One Kilobit (ISO: Kb). As used by the network industry. 1 kilobit = 125 bytes (1000 bits).
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - MEGABITS
```
public static final StorageUnit MEGABITS
```
    One Megabit (ISO: Mb). As used by the network industry. 1 megabit = 125000 bytes (1,000,000 bits).
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - GIGABITS
```
public static final StorageUnit GIGABITS
```
    One Gigabit (ISO: Gb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - TERABITS
```
public static final StorageUnit TERABITS
```
    One Terabit (ISO: Tb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - PETABITS
```
public static final StorageUnit PETABITS
```
    One Petabit (ISO: Pb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - EXABITS
```
public static final StorageUnit EXABITS
```
    One Exabit (ISO: Eb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - ZETTABITS
```
public static final StorageUnit ZETTABITS
```
    One zettabit (ISO Zb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
  - YOTTABITS
```
public static final StorageUnit YOTTABITS
```
    One yottabit (ISO Yb). As used by the network industry.
    N.B. this is a different value to what Google means by kilobit in its calculator (where it interprets 1 kilobit as 128 bytes -- which is a kibibit)
- Field Detail
  - NETWORK_DECIMAL
```
public static final StorageUnit[] NETWORK_DECIMAL
```
  - STORAGE_DECIMAL
```
public static final StorageUnit[] STORAGE_DECIMAL
```
  - COMPSCI_BINARY
```
public static final StorageUnit[] COMPSCI_BINARY
```
  - DECIMAL_QUANTIFIERS
```
public static final StorageUnit[] DECIMAL_QUANTIFIERS
```
    The range of quantifiers for ISO decimal units (bytes to terabytes (ISO: B to TB))
  - BINARY_QUANTIFIERS
```
public static final StorageUnit[] BINARY_QUANTIFIERS
```
    The range of quantifiers for binary units (bytes to terabytes (ISO: B to TiB))
  - ROUNDING_MODE
```
public static final int ROUNDING_MODE
```
    The rounding mode this class uses; this is, by default, BigDecimal.ROUND_HALF_UP
    
    See Also:
    
    Constant Field Values
- Method Detail
  - values
```
public static StorageUnit[] values()
```
    Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
```
for (StorageUnit c : StorageUnit.values())
    System.out.println(c);
```
    Returns:
    
    an array containing the constants of this enum type, in the order they are declared
  - valueOf
```
public static StorageUnit valueOf(String name)
```
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name
    
    NullPointerException - if the argument is null
  - getISOUnit
```
public String getISOUnit()
```
    Return the ISO unit for this storage unit.
    for MEGABYTE this will return MiB (to avoid further confusion)
    
    Returns:
  - getPlural
```
public String getPlural()
```
    Get the plural version of this unit (e.g. "Bytes")
    
    Returns:
  - getSingular
```
public String getSingular()
```
    Get the singular version of this unit (e.g. "Byte")
    
    Returns:
  - convert
```
public long convert(long amount,
                    StorageUnit unit)
```
  - convert
```
public BigInteger convert(BigInteger amount,
                          StorageUnit unit)
```
  - convert
```
public BigDecimal convert(BigDecimal amount,
                          StorageUnit unit)
```
  - toBits
```
public BigInteger toBits(BigInteger amount)
```
  - toBits
```
public BigDecimal toBits(BigDecimal amount)
```
  - fromBits
```
public BigInteger fromBits(BigInteger bits)
```
  - fromBits
```
public BigDecimal fromBits(BigDecimal bits)
```
  - toBytes
```
public long toBytes(long amount)
```
  - toBytes
```
public BigDecimal toBytes(BigDecimal amount)
```
  - toBytes
```
public BigInteger toBytes(BigInteger amount)
```
  - toString
```
public String toString(long amount)
```
  - toString
```
public String toString(BigInteger amount)
```
  - toString
```
public String toString(BigDecimal amount)
```
  - toString
```
public String toString(long amount,
                       boolean shortType)
```
  - toString
```
public String toString(BigInteger amount,
                       boolean shortType)
```
  - toString
```
public String toString(BigDecimal amount,
                       boolean shortType)
```
  - getAppropriateBinaryUnit
```
public static StorageUnit getAppropriateBinaryUnit(BigInteger amount,
                                                   StorageUnit sourceUnit)
```
    Attempts to locate the most appropriate binary unit (binary units are what everyone but the ISO and the storage industry mean by "KB", "MB", etc. - and what the ISO refer to as "KiB", "MiB", etc.) to express the provided amount in for human use (balancing precision and sensible expression)
    
    Parameters:
    
    amount - the amount
    
    sourceUnit - the unit the amount is expressed in
    
    Returns:
    
    the unit which is considered best for expressing the provided amount to a human
  - getAppropriateDecimalUnit
```
public static StorageUnit getAppropriateDecimalUnit(BigInteger amount,
                                                    StorageUnit sourceUnit)
```
    Attempts to locate the most appropriate decimal unit (decimal units are what the ISO and the storage industry (but nobody else) mean by "KB", "MB", etc. (i.e. KB = 1000 bytes) to express the provided amount in for human use (balancing precision and sensible expression)
    
    Parameters:
    
    amount - the amount
    
    sourceUnit - the unit the amount is expressed in
    
    Returns:
    
    the unit which is considered best for expressing the provided amount to a human
  - getAppropriateUnit
```
public static StorageUnit getAppropriateUnit(BigInteger amount,
                                             StorageUnit sourceUnit,
                                             StorageUnit[] options)
```
    Attempts to locate the most appropriate of the provided units to express the provided amount in for human use (balancing precision and sensible expression)
    
    Parameters:
    
    amount - the amount
    
    sourceUnit - the unit the amount is expressed in
    
    options - the storage units which may be used
    
    Returns:
    
    the unit which is considered best for expressing the provided amount to a human
  - smallest
```
public static StorageUnit smallest(StorageUnit unit,
                                   StorageUnit unit2)
```
    Returns the the most diminutive unit of unit and unit2
    
    Parameters:
    
    unit - a unit (should not be null)
    
    unit2 - a unit (should not be null)
    
    Returns:
    
    the most diminutive unit of unit and unit2 (or null if both units were null)
    
    Throws:
    
    NullPointerException - if one unit is null
  - largest
```
public static StorageUnit largest(StorageUnit unit,
                                  StorageUnit unit2)
```
    Returns the the larger unit of unit and unit2
    
    Parameters:
    
    unit - a unit (should not be null)
    
    unit2 - a unit (should not be null)
    
    Returns:
    
    the larger unit of unit and unit2 (or null if both units were null)
    
    Throws:
    
    NullPointerException - if one unit is null
  - parseISO
```
public static StorageUnit parseISO(String toParse)
```
    Parse the ISO abbreviation: (e.g. MiB -> MEGABYTE (1024*1024 bytes))
    
    Parameters:
    
    unit -
    
    Returns:
  - parse
```
public static StorageUnit parse(String original)
```
    Parse the non-ISO abbreviation: MiB and MB both -> MEGABYTE (which is technically a "Mebibyte")
    
    Parameters:
    
    toParse -
    
    Returns:
    
    A StorageUnit representing the unit, assuming that both MiB and MB mean "binary megabyte" (StorageUnit.MEGABYTES)

Enum StorageUnit

Enum Constant Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Enum

Methods inherited from class java.lang.Object

Enum Constant Detail

BITS

NIBBLES

BYTES

KILOBYTES

MEGABYTES

GIGABYTES

TERABYTES

PETABYTES

EXABYTES

ZETTABYTES

YOTTABYTES

DECIMAL_KILOBYTES

DECIMAL_MEGABYTES

DECIMAL_GIGABYTES

DECIMAL_TERABYTES

DECIMAL_PETABYTES

DECIMAL_EXABYTES

DECIMAL_ZETTABYTES

DECIMAL_YOTTABYTES

KILOBITS

MEGABITS

GIGABITS

TERABITS

PETABITS

EXABITS

ZETTABITS

YOTTABITS

Field Detail

NETWORK_DECIMAL

STORAGE_DECIMAL

COMPSCI_BINARY

DECIMAL_QUANTIFIERS

BINARY_QUANTIFIERS

ROUNDING_MODE

Method Detail

values

valueOf

getISOUnit

getPlural

getSingular

convert

convert

convert

toBits

toBits

fromBits

fromBits

toBytes

toBytes

toBytes

toString

toString

toString

toString

toString

toString

getAppropriateBinaryUnit

getAppropriateDecimalUnit

getAppropriateUnit

smallest

largest

parseISO

parse