StorageSize (stdlib 7.0.1 API)

java.lang.Object
- com.peterphi.std.types.StorageSize

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<StorageSize>
```
public final class StorageSize
extends java.lang.Object
implements java.lang.Comparable<StorageSize>, java.io.Serializable
```
Note: this class has a natural ordering that is inconsistent with equals.

Represents an amount of space in a given unit
Internally the amount of storage this object refers to is stored in bits. Any time getAmount() or getBytes() is called this value is converted to the necessary unit

Users are discouraged from using getAmount() unless a rounded value is acceptable (which it rarely is). In most circumstances users are recommended to use getDecimalAmount()

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static StorageSize ZERO

Fields
Modifier and Type	Field and Description
`static StorageSize`	`ZERO`

Constructor Summary

Constructors
Modifier	Constructor and Description
	`StorageSize(java.math.BigDecimal amount, StorageUnit unit)` Creates a new StorageSize where the value is an approximation of the provided value Since this is an approximation some information may be lost.
	`StorageSize(java.math.BigInteger amount, StorageUnit unit)` Creates a new StorageSize where the value is equal to the provided value If the unit is in BITS then any fractional bytes resulting from the conversion will be discarded (e.g.
	`StorageSize(long amount, StorageUnit unit)`
`protected`	`StorageSize(StorageUnit unit, java.math.BigInteger bits)` Internal constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`StorageSize`	`add(StorageSize that)` Adds two storage sizes together, using the smallest unit as the resulting StorageSize's unit
`int`	`compareTo(long amount, StorageUnit unit)` Performs a comparison based on the number of bits represented Since this class has a natural ordering that is inconsistent with equals, this method may return 0 where `equals` would not return `0` - since this compares based on bits but equals tests based on the unit+amount
`int`	`compareTo(StorageSize that)` Performs a comparison based on the number of bits represented Since this class has a natural ordering that is inconsistent with equals, this method may return 0 where `equals` would not return `0` - since this compares based on bits but equals tests based on the unit+amount
`StorageSize`	`convert(StorageUnit toUnit)` Convert this StorageSize to use the named unit
`boolean`	`equals(java.lang.Object o)` Determines whether the amount and unit represented by the other object is exactly equal to this object; N.B.
`java.math.BigInteger`	`getAmount()` Deprecated.
`java.math.BigInteger`	`getAmount(StorageUnit unit)` Converts the size of this StorageSize to another unit, rounding the result to an integer This method may result in the loss of information (due to rounding).
`java.math.BigInteger`	`getBits()` The number of bits represented by this object
`java.math.BigInteger`	`getBytes()` Return the number of bytes this StorageSize represents This method may result in information being lost (e.g.
`java.math.BigDecimal`	`getDecimalAmount()` Converts the size of this StorageSize to another unit, returning the result as a real number (using the BigDecimal type) Uses the default representation unit for this type The calculations may result in minimal loss of precision, however this is unavoidable.
`java.math.BigDecimal`	`getDecimalAmount(StorageUnit unit)` Converts the size of this StorageSize to another unit, returning the result as a real number (using the BigDecimal type) The calculations may result in minimal loss of precision, however this is unavoidable.
`StorageUnit`	`getUnit()` The unit which this Storage Size should be expressed by default
`int`	`hashCode()`
`boolean`	`isZero()` Determines whether this StorageSize represents zero (which is the same in any unit)
`StorageSize`	`multiply(java.math.BigInteger by)` Multiplies the storage size by a certain amount
`StorageSize`	`subtract(StorageSize that)` Subtracts a storage size from the current object, using the smallest unit as the resulting StorageSize's unit
`java.lang.String`	`toPlainString()` Return a String version of this size (e.g.
`java.lang.String`	`toPlainString(StorageUnit unit)` Return a String version of this size (e.g.
`java.lang.String`	`toShortString()` Return a short ISO String version of this size (e.g.
`java.lang.String`	`toShortString(StorageUnit unit)` Return a short ISO String version of this size using the provided unit (e.g.
`java.lang.String`	`toString()`

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

- Field Detail
  - ZERO
```
public static final StorageSize ZERO
```
- Constructor Detail
  - StorageSize
```
public StorageSize(java.math.BigInteger amount,
           StorageUnit unit)
```
    Creates a new StorageSize where the value is equal to the provided value
    If the unit is in BITS then any fractional bytes resulting from the conversion will be discarded (e.g. passing 9 bits will result in 1 byte)
    
    Parameters:
    amount - the amount component of the space this StorageSize should represent
    unit - the unit that amount is expressed in
  - StorageSize
```
public StorageSize(java.math.BigDecimal amount,
           StorageUnit unit)
```
    Creates a new StorageSize where the value is an approximation of the provided value
    Since this is an approximation some information may be lost. This method converts the amount to a number of bytes, then converts it to an integer using the toBigInteger() method of BigDecimal, so information loss should be minimised
    
    Parameters:
    amount - the amount component of the space this StorageSize should represent
    unit - the unit that amount is expressed in. If the unit is BITS then any fractional bits will be ignored (i.e. identical to calling the BigInteger constructor with amount.toBigInteger())
  - StorageSize
```
protected StorageSize(StorageUnit unit,
           java.math.BigInteger bits)
```
    Internal constructor. Should not be exposed to users
    
    Parameters:
    unit - the unit the user would like to see their StorageSize in by default
    bytes - the number of bytes this StorageSize represents
  - StorageSize
```
public StorageSize(long amount,
           StorageUnit unit)
```
- Method Detail
  - getBytes
```
public java.math.BigInteger getBytes()
```
    Return the number of bytes this StorageSize represents
    This method may result in information being lost (e.g. partial bits). Users are encouraged to use the getBits method if this loss is unacceptable
    
    Returns:
    the number of bytes represented by this object (determined by diving the number of bits by 8 and then rounding the result)
  - getBits
```
public java.math.BigInteger getBits()
```
    The number of bits represented by this object
    
    Returns:
    the number of bits represented by this object
  - getUnit
```
public StorageUnit getUnit()
```
    The unit which this Storage Size should be expressed by default
    
    Returns:
    the unit which this Storage Size should be expressed by default
  - getDecimalAmount
```
public java.math.BigDecimal getDecimalAmount()
```
    Converts the size of this StorageSize to another unit, returning the result as a real number (using the BigDecimal type)
    Uses the default representation unit for this type
    The calculations may result in minimal loss of precision, however this is unavoidable.
    
    Returns:
    a real number approximation (which will be more accurate than getAmount() which only deals with integers)
  - getDecimalAmount
```
public java.math.BigDecimal getDecimalAmount(StorageUnit unit)
```
    Converts the size of this StorageSize to another unit, returning the result as a real number (using the BigDecimal type)
    The calculations may result in minimal loss of precision, however this is unavoidable.
    
    Parameters:
    unit - the unit to use (instead of the default StorageSize unit)
    
    Returns:
    an approximation of the (which will be more accurate than getAmount(unit) which only deals with integers)
  - getAmount
```
@Deprecated
public java.math.BigInteger getAmount()
```
    Deprecated.
    
    Converts the size of this StorageSize to another unit, rounding the result to an integer
    Uses the default representation unit for this type
    This method may result in the loss of information (due to rounding). If precision is required then getDecimalAmount() should be used
    
    Returns:
    the size (as an integer) in the default unit for this StorageSize.
  - getAmount
```
public java.math.BigInteger getAmount(StorageUnit unit)
```
    Converts the size of this StorageSize to another unit, rounding the result to an integer
    This method may result in the loss of information (due to rounding). If precision is required then getDecimalAmount(unit) should be used
    
    Parameters:
    unit - the unit to use (instead of the default StorageSize unit)
    
    Returns:
    the size (as an integer) in the provided unit.
  - isZero
```
public boolean isZero()
```
    Determines whether this StorageSize represents zero (which is the same in any unit)
    
    Returns:
    true if the number of bits represented by this object is exactly Zero, otherwise false
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toPlainString
```
public java.lang.String toPlainString()
```
    Return a String version of this size (e.g. "4 Bytes") in its default unit
    
    Returns:
    a String version of this size (e.g. "4 Bytes") in its default unit
  - toPlainString
```
public java.lang.String toPlainString(StorageUnit unit)
```
    Return a String version of this size (e.g. "4 Bytes") in the provided unit
    
    Parameters:
    unit - the desired unit
    
    Returns:
    a String version of this size (e.g. "4 Bytes") in the provided unit
  - toShortString
```
public java.lang.String toShortString()
```
    Return a short ISO String version of this size (e.g. "4 B") in its default unit
    
    Returns:
    a short ISO String version of this size (e.g. "4 B") in its default unit
  - toShortString
```
public java.lang.String toShortString(StorageUnit unit)
```
    Return a short ISO String version of this size using the provided unit (e.g. "4 MiB")
    
    Parameters:
    unit - the unit to represent the amount in
    
    Returns:
    a short ISO String version of this size using the provided unit (e.g. "4 MiB")
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object o)
```
    Determines whether the amount and unit represented by the other object is exactly equal to this object;
    N.B. 1024 Megabytes != 1 Gigabyte for this method
    
    Overrides:
    
    equals in class java.lang.Object
    
    See Also:
    Object.equals(java.lang.Object)
  - convert
```
public StorageSize convert(StorageUnit toUnit)
```
    Convert this StorageSize to use the named unit
    
    Parameters:
    toUnit -
    
    Returns:
  - add
```
public StorageSize add(StorageSize that)
```
    Adds two storage sizes together, using the smallest unit as the resulting StorageSize's unit
    
    Parameters:
    that -
    
    Returns:
  - multiply
```
public StorageSize multiply(java.math.BigInteger by)
```
    Multiplies the storage size by a certain amount
    
    Parameters:
    that -
    
    Returns:
  - subtract
```
public StorageSize subtract(StorageSize that)
```
    Subtracts a storage size from the current object, using the smallest unit as the resulting StorageSize's unit
    
    Parameters:
    storage -
    
    Returns:
  - compareTo
```
public int compareTo(StorageSize that)
```
    Performs a comparison based on the number of bits represented
    Since this class has a natural ordering that is inconsistent with equals, this method may return 0 where equals would not return 0 - since this compares based on bits but equals tests based on the unit+amount
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<StorageSize>
    
    Parameters:
    that - some other storage amount
    See Also:
    Comparable.compareTo(java.lang.Object)
  - compareTo
```
public int compareTo(long amount,
            StorageUnit unit)
```
    Performs a comparison based on the number of bits represented
    Since this class has a natural ordering that is inconsistent with equals, this method may return 0 where equals would not return 0 - since this compares based on bits but equals tests based on the unit+amount
    
    Parameters:
    amount - the number of units for this amount
    unit - the unit that amount should be expressed in
    See Also:
    Comparable.compareTo(java.lang.Object)

Class StorageSize

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

Constructor Detail

StorageSize

StorageSize

StorageSize

StorageSize

Method Detail

getBytes

getBits

getUnit

getDecimalAmount

getDecimalAmount

getAmount

getAmount

isZero

toString

toPlainString

toPlainString

toShortString

toShortString

hashCode

equals

convert

add

multiply

subtract

compareTo

compareTo