Module io.helidon.common
Package io.helidon.common

Interface Size

public interface Size
A definition of size in bytes.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Size.Unit
    Units that can be used.
    static enum 
    Size.UnitKind
    Kind of units, used for printing out the correct unit.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Size
    ZERO
    Empty size - zero bytes.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Size
    create(long size)
    Create a new size with explicit number of bytes.
    static Size
    create(long amount, Size.Unit unit)
    Create a new size from amount and unit.
    static Size
    create(BigDecimal amount, Size.Unit unit)
    Create a new size from amount and unit.
    static Size
    parse(String sizeString)
    Crete a new size from the size string.
    BigDecimal
    to(Size.Unit unit)
    Amount of units in this size.
    long
    toBytes()
    Number of bytes this size represents.
    String
    toString(Size.UnitKind unitKind)
    Get the highest possible unit of the size with integer amount.
    String
    toString(Size.Unit unit, Size.UnitKind unitKind)
    Get the amount in the provided unit as a decimal number if needed.

  • Field Details

    • ZERO

      static final Size ZERO
      Empty size - zero bytes.

  • Method Details

    • create

      static Size create(long size)
      Create a new size with explicit number of bytes.
      Parameters:
      size - number of bytes
      Returns:
      a new size instance

    • create

      static Size create(long amount, Size.Unit unit)
      Create a new size from amount and unit.
      Parameters:
      amount - amount in the provided unit
      unit - unit
      Returns:
      size representing the amount

    • create

      static Size create(BigDecimal amount, Size.Unit unit)
      Create a new size from amount and unit.
      Parameters:
      amount - amount that can be decimal
      unit - unit
      Returns:
      size representing the amount
      Throws:
      IllegalArgumentException - in case the amount cannot be converted to whole bytes (i.e. it has a fraction of byte)

    • parse

      static Size parse(String sizeString)
      Crete a new size from the size string. The string may contain a unit. If a unit is not present, the size string is considered to be number of bytes.

      We understand units from kilo (meaning 1000 or 1024, see table below), to exa bytes. Each higher unit is either 1000 times or 1024 times bigger than the one below, depending on the approach used.

      Measuring approaches and their string representations:

      • KB, KiB - kibi, kilobinary, stands for 1024 bytes
      • kB, kb - kilobyte, stands for 1000 bytes
      • MB, MiB - mebi, megabinary, stands for 1024*1024 bytes
      • mB, mb - megabyte, stands for 1000*1000 bytes
      • From here the same concept is applied with Giga, Tera, Peta, and Exa bytes
      Parameters:
      sizeString - the string definition, such as 76 MB, or 976 mB, can also be a decimal number - we use BigDecimal to parse the numeric section of the size; if there is a unit defined, it must be separated by a single space from the numeric section
      Returns:
      parsed size that can provide exact number of bytes

    • to

      BigDecimal to(Size.Unit unit)
      Amount of units in this size.
      Parameters:
      unit - to get the size of
      Returns:
      size in the provided unit as a big decimal
      Throws:
      ArithmeticException - in case this size cannot be converted to the specified unit without losing information
      See Also:

    • toBytes

      long toBytes()
      Number of bytes this size represents.
      Returns:
      number of bytes
      Throws:
      ArithmeticException - in case the amount is higher than Long.MAX_VALUE, or would contain fractions of byte

    • toString

      String toString(Size.UnitKind unitKind)
      Get the highest possible unit of the size with integer amount.
      Parameters:
      unitKind - kind of unit to print (kB, kb, KB, or KiB)
      Returns:
      amount integer with a unit, such as 270 kB, if the amount is 2000 kB, this method would return 2 mB instead for Size.UnitKind.DECIMAL_UPPER_CASE

    • toString

      String toString(Size.Unit unit, Size.UnitKind unitKind)
      Get the amount in the provided unit as a decimal number if needed. If the amount cannot be correctly expressed in the provided unit, an exception is thrown.
      Parameters:
      unit - unit to use, such as Size.Unit.MIB
      unitKind - kind of unit for the output, must match the provided unit, such as Size.UnitKind.BINARY_BI to print MiB
      Returns:
      amount decimal with a unit, such as 270.426 MiB
      Throws:
      IllegalArgumentException - in case the unitKind does not match the unit