org.springframework.util.unit

## Class DataSize

- java.lang.Object
- - org.springframework.util.unit.DataSize

- All Implemented Interfaces:
    Serializable, Comparable<DataSize>

      public final class DataSize
      extends Object
      implements Comparable<DataSize>, Serializable

  A data size, such as '12MB'.

  This class models data size in terms of bytes and is immutable and thread-safe.

  The terms and units used in this class are based on binary prefixes indicating multiplication by powers of 2. Consult the following table and the Javadoc for `DataUnit` for details.

  Term | Data Size | Size in Bytes
  --- | --- | ---
  byte | 1B | 1
  kilobyte | 1KB | 1,024
  megabyte | 1MB | 1,048,576
  gigabyte | 1GB | 1,073,741,824
  terabyte | 1TB | 1,099,511,627,776

  Since:
    5.1
  Author:
    Stephane Nicoll, Sam Brannen
  See Also:
    `DataUnit`, Serialized Form

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(DataSize other)`
    `boolean` | `equals(Object other)`
    `int` | `hashCode()`
    `boolean` | `isNegative()` Checks if this size is negative, excluding zero.
    `static DataSize` | `of(long amount, DataUnit unit)` Obtain a `DataSize` representing an amount in the specified `DataUnit`.
    `static DataSize` | `ofBytes(long bytes)` Obtain a `DataSize` representing the specified number of bytes.
    `static DataSize` | `ofGigabytes(long gigabytes)` Obtain a `DataSize` representing the specified number of gigabytes.
    `static DataSize` | `ofKilobytes(long kilobytes)` Obtain a `DataSize` representing the specified number of kilobytes.
    `static DataSize` | `ofMegabytes(long megabytes)` Obtain a `DataSize` representing the specified number of megabytes.
    `static DataSize` | `ofTerabytes(long terabytes)` Obtain a `DataSize` representing the specified number of terabytes.
    `static DataSize` | `parse(CharSequence text)` Obtain a `DataSize` from a text string such as `12MB` using `DataUnit.BYTES` if no unit is specified.
    `static DataSize` | `parse(CharSequence text, DataUnit defaultUnit)` Obtain a `DataSize` from a text string such as `12MB` using the specified default `DataUnit` if no unit is specified.
    `long` | `toBytes()` Return the number of bytes in this instance.
    `long` | `toGigabytes()` Return the number of gigabytes in this instance.
    `long` | `toKilobytes()` Return the number of kilobytes in this instance.
    `long` | `toMegabytes()` Return the number of megabytes in this instance.
    `String` | `toString()`
    `long` | `toTerabytes()` Return the number of terabytes in this instance.

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### ofBytes

          public static DataSize ofBytes(long bytes)

      Obtain a `DataSize` representing the specified number of bytes.
      Parameters:
        `bytes` - the number of bytes, positive or negative
      Returns:
        a `DataSize`

    - #### ofKilobytes

          public static DataSize ofKilobytes(long kilobytes)

      Obtain a `DataSize` representing the specified number of kilobytes.
      Parameters:
        `kilobytes` - the number of kilobytes, positive or negative
      Returns:
        a `DataSize`

    - #### ofMegabytes

          public static DataSize ofMegabytes(long megabytes)

      Obtain a `DataSize` representing the specified number of megabytes.
      Parameters:
        `megabytes` - the number of megabytes, positive or negative
      Returns:
        a `DataSize`

    - #### ofGigabytes

          public static DataSize ofGigabytes(long gigabytes)

      Obtain a `DataSize` representing the specified number of gigabytes.
      Parameters:
        `gigabytes` - the number of gigabytes, positive or negative
      Returns:
        a `DataSize`

    - #### ofTerabytes

          public static DataSize ofTerabytes(long terabytes)

      Obtain a `DataSize` representing the specified number of terabytes.
      Parameters:
        `terabytes` - the number of terabytes, positive or negative
      Returns:
        a `DataSize`

    - #### of

          public static DataSize of(long amount,
                                    DataUnit unit)

      Obtain a `DataSize` representing an amount in the specified `DataUnit`.
      Parameters:
        `amount` - the amount of the size, measured in terms of the unit, positive or negative
      Returns:
        a corresponding `DataSize`

    - #### parse

          public static DataSize parse(CharSequence text)

      Obtain a `DataSize` from a text string such as `12MB` using `DataUnit.BYTES` if no unit is specified.

      Examples:

           "12KB" -- parses as "12 kilobytes"
           "5MB"  -- parses as "5 megabytes"
           "20"   -- parses as "20 bytes"

      Parameters:
        `text` - the text to parse
      Returns:
        the parsed `DataSize`
      See Also:
        `parse(CharSequence, DataUnit)`

    - #### parse

          public static DataSize parse(CharSequence text,
                                       @Nullable
                                       DataUnit defaultUnit)

      Obtain a `DataSize` from a text string such as `12MB` using the specified default `DataUnit` if no unit is specified.

      The string starts with a number followed optionally by a unit matching one of the supported suffixes.

      Examples:

           "12KB" -- parses as "12 kilobytes"
           "5MB"  -- parses as "5 megabytes"
           "20"   -- parses as "20 kilobytes" (where the  defaultUnit is DataUnit.KILOBYTES)

      Parameters:
        `text` - the text to parse
      Returns:
        the parsed `DataSize`

    - #### isNegative

          public boolean isNegative()

      Checks if this size is negative, excluding zero.
      Returns:
        true if this size has a size less than zero bytes

    - #### toBytes

          public long toBytes()

      Return the number of bytes in this instance.
      Returns:
        the number of bytes

    - #### toKilobytes

          public long toKilobytes()

      Return the number of kilobytes in this instance.
      Returns:
        the number of kilobytes

    - #### toMegabytes

          public long toMegabytes()

      Return the number of megabytes in this instance.
      Returns:
        the number of megabytes

    - #### toGigabytes

          public long toGigabytes()

      Return the number of gigabytes in this instance.
      Returns:
        the number of gigabytes

    - #### toTerabytes

          public long toTerabytes()

      Return the number of terabytes in this instance.
      Returns:
        the number of terabytes

    - #### compareTo

          public int compareTo(DataSize other)

      Specified by:
        `compareTo` in interface `Comparable<DataSize>`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals(@Nullable
                                Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`