Package com.norconex.commons.lang.unit

# Class DataUnitParser

java.lang.Object
com.norconex.commons.lang.unit.DataUnitParser

public final class DataUnitParser extends Object

Parse a textual representation of a data unit and converts it into a `BigDecimal` representing the quantity for a given unit (e.g., bytes).

If the string is made of digits only, it is assumed to be bytes and the value will remain the same.

The data unit can be written in its prefix form, or in full, whether using binary or decimal notations. (e.g., "kB", "kilobyte", "kilobytes").

Languages supported are English (default) and French (since 2.0.0). The following are acceptable symbols for each data units, for bytes and bits. The symbols are case-insensitive, and accent-insensitive.

## English decimal notation:

- kB,kilobyte,kilobytes, kbit,kilobit,kilobits
- MB,megabyte,megabytes, Mbit,megabit,megabits
- GB,gigabyte,gigabytes, Gbit,gigabit,gigabits
- TB,terabyte,terabytes, Tbit,terabit,terabits
- PB,petabyte,petabytes, Pbit,petabit,petabits
- EB,exabyte,exabytes, Ebit,exabit,exabits
- ZB,zettabyte,zettabytes, Zbit,zettabit,zettabits
- YB,yottabyte,yottabytes, Ybit,yottabit,yottabits

## English binary notation:

- KiB,kibibyte,kibibytes, kibit,kibibit,kibibits
- MiB,mebibyte,mebibytes, Mibit,mebibit,mebibits
- GiB,gibibyte,gibibytes, Gibit,gibibit,gibibits
- TiB,tebibyte,tebibytes, Tibit,tebibit,tebibits
- PiB,pebibyte,pebibytes, Pibit,pebibit,pebibits
- EiB,exbibyte,exbiytes, Eibit,exbibit,exbibits
- ZiB,zebibyte,zebibytes, Zibit,zebibit,zebibits
- YiB,yobibyte,yobibytes, Yibit,yobibit,yobibits

## French notations

French uses the same symbols. Accents aside, the names are also the same, except for replacing "byte" with "octet" (e.g., "gigabyte" becomes "gigaoctet").

French typically write the following prefixes with an "é": méga, mébi, téra, tébi péta, pébi. Both variations are supported (with or without accents).

Refer to `DataUnit` for extra information of what they values represent.

No distinction is made between plural and singular. Numeric values can be integers or decimals numbers (e.g., 2.5kB). A numeric value must be followed by a data unit. Other terms or characters are ignored.

## Examples:

All of the following will be parsed properly:

- 2 gigabytes, 530 megabytes, and 2 kilobytes
- 6GB10MB23kB
- 2.5MiB
- 10PiB9 gibibytes, 8 MB, and 5.5 kibibytes
- 2 mégaoctets et 3 kilooctet

This class is thread-safe and immutable.

Since:
  2.0.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static BigDecimal`
  `parse(String text)`
  Parses a text representation of a data measurement and returns the number of bytes it represents.
  `static BigDecimal`
  `parse(String text, DataUnit targetUnit)`
  Parses a text representation of a data measurement.
  `static BigDecimal`
  `parse(String text, DataUnit targetUnit, BigDecimal defaultValue)`
  Parses a text representation of a data measurement.
  `static BigDecimal`
  `parse(String text, BigDecimal defaultValue)`
  Parses a text representation of a data measurement.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### parse

    public static BigDecimal parse(String text)
    Parses a text representation of a data measurement and returns the number of bytes it represents. If the value cannot be parsed, a `DataUnitParserException` is thrown. Default value is zero byte.
    Parameters:
      `text` - the data measurement text to parse
    Returns:
      data measurement

  - ### parse

    public static BigDecimal parse(String text, BigDecimal defaultValue)
    Parses a text representation of a data measurement. If the value cannot be parsed, the default value is returned (no exception is thrown).
    Parameters:
      `text` - the data measurement text to parse
      `defaultValue` - default value
    Returns:
      data measurement

  - ### parse

    public static BigDecimal parse(String text, DataUnit targetUnit)
    Parses a text representation of a data measurement. If the value cannot be parsed, a `DataUnitParserException` is thrown. Default value is zero byte.
    Parameters:
      `text` - the data measurement text to parse
      `targetUnit` - desired target unit for the returned amount
    Returns:
      amount for unit

  - ### parse

    public static BigDecimal parse(String text, DataUnit targetUnit, BigDecimal defaultValue)
    Parses a text representation of a data measurement. If the value cannot be parsed, the default value is returned (no exception is thrown).
    Parameters:
      `text` - the data measurement text to parse
      `targetUnit` - desired target unit for the returned amount
      `defaultValue` - default value
    Returns:
      amount for unit