Package com.peterphi.std.types

Enum Class StorageUnit

java.lang.Object
java.lang.Enum<StorageUnit>
com.peterphi.std.types.StorageUnit
All Implemented Interfaces:
Serializable, Comparable<StorageUnit>, Constable
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 Details

    • 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 Details

    • 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:

  • Method Details

    • values

      public static StorageUnit[] 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 StorageUnit 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

    • 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)