Module org.apache.sis.util
Package org.apache.sis.measure

# Class QuantityFormat

Object
Format
QuantityFormat

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `QuantityFormat`

public class QuantityFormat extends Format implements QuantityFormat
Parses and formats numbers with units of measurement.

Since:
  1.1
See Also:
  - `NumberFormat`
  - `UnitFormat`
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Format

  `Format​.Field`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final NumberFormat`
  `numberFormat`
  The format for parsing and formatting the number part.
  `static final char`
  `SEPARATOR`
  The default separator used between numerical value and its unit of measurement.
  `protected final UnitFormat`
  `unitFormat`
  The format for parsing and formatting the unit of measurement part.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `QuantityFormat(NumberFormat numberFormat, UnitFormat unitFormat)`
  Creates a new instance using the given number and unit formats.
  `QuantityFormat(Locale locale)`
  Creates a new instance for the given locale.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `QuantityFormat`
  `clone()`
  Returns a clone of this format.
  `StringBuffer`
  `format(Object quantity, StringBuffer toAppendTo, FieldPosition pos)`
  Formats the specified quantity in the given buffer.
  `String`
  `format(Quantity<?> quantity)`
  Formats the specified quantity.
  `Appendable`
  `format(Quantity<?> quantity, Appendable toAppendTo)`
  Formats the specified quantity in the given destination.
  `boolean`
  `isLocaleSensitive()`
  Returns whether this format depends on a `Locale` to perform its tasks.
  `Quantity<?>`
  `parse(CharSequence source)`
  Parses the specified text to produce a `Quantity`.
  `Quantity<?>`
  `parse(CharSequence source, ParsePosition pos)`
  Parses a portion of the specified `CharSequence` from the specified position to produce a `Quantity`.
  `Object`
  `parseObject(String source, ParsePosition pos)`
  Parses text from a string to produce a quantity, or returns `null` if the parsing failed.

  ### Methods inherited from class Format

  `format, formatToCharacterIterator, parseObject`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### SEPARATOR

    public static final char SEPARATOR
    The default separator used between numerical value and its unit of measurement. Current value is narrow no-break space (U+202F).
    See Also:
      - Constant Field Values

  - ### numberFormat

    protected final NumberFormat numberFormat
    The format for parsing and formatting the number part.

  - ### unitFormat

    protected final UnitFormat unitFormat
    The format for parsing and formatting the unit of measurement part.

- ## Constructor Details

  - ### QuantityFormat

    public QuantityFormat(Locale locale)
    Creates a new instance for the given locale.
    Parameters:
      `locale` - the locale for the quantity format.

  - ### QuantityFormat

    public QuantityFormat(NumberFormat numberFormat, UnitFormat unitFormat)
    Creates a new instance using the given number and unit formats.
    Parameters:
      `numberFormat` - the format for parsing and formatting the number part.
      `unitFormat` - the format for parsing and formatting the unit of measurement part.

- ## Method Details

  - ### isLocaleSensitive

    public boolean isLocaleSensitive()
    Returns whether this format depends on a `Locale` to perform its tasks. This is `true` in this `QuantityFormat` implementation.
    Specified by:
      `isLocaleSensitive` in interface `QuantityFormat`
    Returns:
      whether this format depends on the locale, which is true in this implementation.
    Since:
      1.4

  - ### format

    public String format(Quantity<?> quantity)
    Formats the specified quantity. The default implementation delegates to `format(Object, StringBuffer, FieldPosition)`.
    Specified by:
      `format` in interface `QuantityFormat`
    Parameters:
      `quantity` - the quantity to format.
    Returns:
      the string representation of the given quantity.
    Since:
      1.4

  - ### format

    public Appendable format(Quantity<?> quantity, Appendable toAppendTo) throws IOException
    Formats the specified quantity in the given destination. The default implementation delegates to `format(Object, StringBuffer, FieldPosition)`.
    Specified by:
      `format` in interface `QuantityFormat`
    Parameters:
      `quantity` - the quantity to format.
      `toAppendTo` - where to format the quantity.
    Returns:
      the given `toAppendTo` argument, for method calls chaining.
    Throws:
      `IOException` - if an I/O exception occurred.
    Since:
      1.4

  - ### format

    public StringBuffer format(Object quantity, StringBuffer toAppendTo, FieldPosition pos)
    Formats the specified quantity in the given buffer. The given object shall be a `Quantity` instance.
    Specified by:
      `format` in class `Format`
    Parameters:
      `quantity` - the quantity to format.
      `toAppendTo` - where to format the quantity.
      `pos` - where to store the position of a formatted field, or `null` if none.
    Returns:
      the given `toAppendTo` argument, for method calls chaining.

  - ### parse

    public Quantity<?> parse(CharSequence source) throws MeasurementParseException
    Parses the specified text to produce a `Quantity`.
    Specified by:
      `parse` in interface `QuantityFormat`
    Parameters:
      `source` - the text to parse.
    Returns:
      the quantity parsed from the specified text.
    Throws:
      `MeasurementParseException` - if the given text cannot be parsed.
    Since:
      1.4

  - ### parse

    public Quantity<?> parse(CharSequence source, ParsePosition pos) throws MeasurementParseException
    Parses a portion of the specified `CharSequence` from the specified position to produce a `Quantity`. If parsing succeeds, then the index of the `pos` argument is updated to the index after the last character used.
    Specified by:
      `parse` in interface `QuantityFormat`
    Parameters:
      `source` - the text, part of which should be parsed.
      `pos` - index and error index information.
    Returns:
      the quantity parsed from the specified character sub-sequence.
    Throws:
      `MeasurementParseException` - if the given text cannot be parsed.
    Since:
      1.4

  - ### parseObject

    public Object parseObject(String source, ParsePosition pos)
    Parses text from a string to produce a quantity, or returns `null` if the parsing failed.
    Specified by:
      `parseObject` in class `Format`
    Parameters:
      `source` - the text, part of which should be parsed.
      `pos` - index and error index information.
    Returns:
      a quantity parsed from the string, or `null` in case of error.

  - ### clone

    public QuantityFormat clone()
    Returns a clone of this format.
    Overrides:
      `clone` in class `Format`
    Returns:
      a clone of this format.