SimpleUnitFormat (Units of Measurement Reference Implementation 2.2 API)

java.lang.Object
- tech.units.indriya.format.AbstractUnitFormat
- - tech.units.indriya.format.SimpleUnitFormat

```
public abstract class SimpleUnitFormat
extends AbstractUnitFormat
```
This class implements the UnitFormat interface for formatting and parsing units.

For all SI units, the 24 SI prefixes used to form decimal multiples and sub-multiples are recognized. As well as the 8 binary prefixes.
Units are directly recognized. For example:
UnitFormat format = SimpleUnitFormat.getInstance(); format.parse("m°C").equals(MetricPrefix.MILLI(Units.CELSIUS)); format.parse("kW").equals(MetricPrefix.KILO(Units.WATT)); format.parse("ft").equals(Units.METRE.multiply(0.3048))

Since:

1.0

Version:

2.10, June 6, 2023

Author:

Jean-Marie Dautelle, Werner Keil, Eric Russell, Andi Huber

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static class SimpleUnitFormat.Flavor
Flavor of this format

Nested Classes
Modifier and Type	Class	Description
`static class`	`SimpleUnitFormat.Flavor`	Flavor of this format

Constructor Summary

Constructors
Modifier Constructor Description

protected SimpleUnitFormat()
Base constructor.

Constructors
Modifier	Constructor	Description
`protected`	`SimpleUnitFormat()`	Base constructor.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`abstract void`	`alias(javax.measure.Unit<?> unit, String alias)`	Attaches a system-wide alias to this unit.
`StringBuffer`	`format(Object unit, StringBuffer toAppendTo, FieldPosition pos)`	Formats an unit and appends the resulting text to a given string buffer (implements `java.text.Format`).
`abstract Appendable`	`format(javax.measure.Unit<?> unit, Appendable appendable)`	Formats the specified unit.
`static SimpleUnitFormat`	`getInstance()`	Returns the globally shared unit format instance (used by `AbstractUnit.parse()` and `AbstractUnit.toString()`).
`static SimpleUnitFormat`	`getInstance(SimpleUnitFormat.Flavor flavor)`	Returns the `SimpleUnitFormat` in the desired `SimpleUnitFormat.Flavor`
`static SimpleUnitFormat`	`getNewInstance()`	Similar to `getInstance()`, but returns a new, non-shared unit format instance, instead of a shared singleton instance.
`static SimpleUnitFormat`	`getNewInstance(SimpleUnitFormat.Flavor flavor)`	Similar to `getInstance(Flavor)`, but returns a new `SimpleUnitFormat` instance in the desired `SimpleUnitFormat.Flavor`, instead of a shared singleton instance.
`protected abstract boolean`	`isValidIdentifier(String name)`	Indicates if the specified name can be used as unit identifier.
`abstract void`	`label(javax.measure.Unit<?> unit, String label)`	Attaches a system-wide label to the specified unit.
`javax.measure.Unit<?>`	`parseObject(String source, ParsePosition pos)`	Parses the text from a string to produce an object (implements `java.text.Format`).
`abstract javax.measure.Unit<? extends javax.measure.Quantity>`	`parseProductUnit(CharSequence csq, ParsePosition pos)`	Parses a sequence of character to produce a unit or a rational product of unit.
`abstract javax.measure.Unit<? extends javax.measure.Quantity>`	`parseSingleUnit(CharSequence csq, ParsePosition pos)`	Parses a sequence of character to produce a single unit.
`abstract void`	`removeAlias(javax.measure.Unit<?> unit, String alias)`	Removes the given system-wide alias (added by `alias(Unit, String)`) for this unit and keeps the label (added by `label(Unit, String)`)
`abstract void`	`removeAliases(javax.measure.Unit<?> unit)`	Removes all system-wide aliases (added by `alias(Unit, String)`) for this unit and keeps the label (added by `label(Unit, String)`)
`abstract void`	`removeLabel(javax.measure.Unit<?> unit)`	Removes the system-wide label (added by `label(Unit, String)`) and all system-wide aliases (added by `alias(Unit, String)`) for this unit.

Methods inherited from class tech.units.indriya.format.AbstractUnitFormat
format, parse, parse

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

Methods inherited from interface javax.measure.format.UnitFormat
isLocaleSensitive, parse

- Constructor Detail
  - SimpleUnitFormat
```
protected SimpleUnitFormat()
```
    Base constructor.
- Method Detail
  - getInstance
```
public static SimpleUnitFormat getInstance()
```
    Returns the globally shared unit format instance (used by AbstractUnit.parse() and AbstractUnit.toString()).
    
    Returns:
    
    the default unit format.
  - getInstance
```
public static SimpleUnitFormat getInstance(SimpleUnitFormat.Flavor flavor)
```
    Returns the SimpleUnitFormat in the desired SimpleUnitFormat.Flavor
    
    Returns:
    
    the instance for the given SimpleUnitFormat.Flavor.
  - getNewInstance
```
public static SimpleUnitFormat getNewInstance()
```
    Similar to getInstance(), but returns a new, non-shared unit format instance, instead of a shared singleton instance.
    
    Returns:
    
    a new instance of the default unit format.
    
    Since:
    
    2.7
    
    See Also:
    
    getInstance()
  - getNewInstance
```
public static SimpleUnitFormat getNewInstance(SimpleUnitFormat.Flavor flavor)
```
    Similar to getInstance(Flavor), but returns a new SimpleUnitFormat instance in the desired SimpleUnitFormat.Flavor, instead of a shared singleton instance.
    
    Returns:
    
    a new instance for the given SimpleUnitFormat.Flavor.
    
    Since:
    
    2.7
    
    See Also:
    
    getInstance(Flavor)
  - format
```
public abstract Appendable format(javax.measure.Unit<?> unit,
                                  Appendable appendable)
                           throws IOException
```
    Formats the specified unit.
    
    Specified by:
    
    format in class AbstractUnitFormat
    
    Parameters:
    
    unit - the unit to format.
    
    appendable - the appendable destination.
    
    Returns:
    
    The appendable destination passed in as appendable, with formatted text appended.
    
    Throws:
    
    IOException - if an error occurs.
  - parseProductUnit
```
public abstract javax.measure.Unit<? extends javax.measure.Quantity> parseProductUnit(CharSequence csq,
                                                                                      ParsePosition pos)
                                                                               throws javax.measure.format.MeasurementParseException
```
    Parses a sequence of character to produce a unit or a rational product of unit.
    
    Parameters:
    
    csq - the CharSequence to parse.
    
    pos - an object holding the parsing index and error position.
    
    Returns:
    
    an Unit parsed from the character sequence.
    
    Throws:
    
    IllegalArgumentException - if the character sequence contains an illegal syntax.
    
    javax.measure.format.MeasurementParseException
  - parseSingleUnit
```
public abstract javax.measure.Unit<? extends javax.measure.Quantity> parseSingleUnit(CharSequence csq,
                                                                                     ParsePosition pos)
                                                                              throws javax.measure.format.MeasurementParseException
```
    Parses a sequence of character to produce a single unit.
    
    Parameters:
    
    csq - the CharSequence to parse.
    
    pos - an object holding the parsing index and error position.
    
    Returns:
    
    an Unit parsed from the character sequence.
    
    Throws:
    
    IllegalArgumentException - if the character sequence does not contain a valid unit identifier.
    
    javax.measure.format.MeasurementParseException
  - label
```
public abstract void label(javax.measure.Unit<?> unit,
                           String label)
```
    Attaches a system-wide label to the specified unit. For example: SimpleUnitFormat.getInstance().label(DAY.multiply(365), "year"); SimpleUnitFormat.getInstance().label(METER.multiply(0.3048), "ft"); If the specified label is already associated to an unit the previous association is discarded or ignored.
    If you set a different label without calling removeLabel(Unit)), removeAlias(Unit, String)), using the old label, or removeAliases(Unit)) on the given unit, the old label is overwritten for labeling/ purposes, but it remains like an alias (it still works for parsing).
    
    Overrides:
    
    label in class AbstractUnitFormat
    
    Parameters:
    
    unit - the unit being labeled.
    
    label - the new label for this unit.
    
    Throws:
    
    IllegalArgumentException - if the label is not a isValidIdentifier(String) valid identifier.
  removeLabel
  
  public abstract void removeLabel(javax.measure.Unit<?> unit)
  
  Removes the system-wide label (added by label(Unit, String)) and all system-wide aliases (added by alias(Unit, String)) for this unit.
  
  Parameters:
  
  unit - the unit for which label shall be removed.
  
  alias
  
  public abstract void alias(javax.measure.Unit<?> unit, String alias)
  
  Attaches a system-wide alias to this unit. Multiple aliases may be attached to the same unit. Aliases are used during parsing to recognize different variants of the same unit. For example: SimpleUnitFormat.getInstance().alias(METER.multiply(0.3048), "foot"); SimpleUnitFormat.getInstance().alias(METER.multiply(0.3048), "feet"); SimpleUnitFormat.getInstance().alias(METER, "meter"); SimpleUnitFormat.getInstance().alias(METER, "metre"); If the specified label is already associated to an unit the previous association is discarded or ignored.
  
  Parameters:
  
  unit - the unit being aliased.
  
  alias - the alias attached to this unit.
  
  Throws:
  
  IllegalArgumentException - if the label is not a isValidIdentifier(String) valid identifier.
  
  removeAlias
  
  public abstract void removeAlias(javax.measure.Unit<?> unit, String alias)
  
  Removes the given system-wide alias (added by alias(Unit, String)) for this unit and keeps the label (added by label(Unit, String))
  
  Parameters:
  
  unit - the unit for which alias shall be removed.
  
  alias - the alias to be removed.
  
  removeAliases
  
  public abstract void removeAliases(javax.measure.Unit<?> unit)
  
  Removes all system-wide aliases (added by alias(Unit, String)) for this unit and keeps the label (added by label(Unit, String))
  
  Parameters:
  
  unit - the unit for which aliases shall be removed.
  
  isValidIdentifier
  
  protected abstract boolean isValidIdentifier(String name)
  
  Indicates if the specified name can be used as unit identifier.
  
  Parameters:
  
  name - the identifier to be tested.
  
  Returns:
  
  true if the name specified can be used as label or alias for this format;false otherwise.
  
  format
  
  public final StringBuffer format(Object unit, StringBuffer toAppendTo, FieldPosition pos)
  
  Formats an unit and appends the resulting text to a given string buffer (implements java.text.Format).
  
  Parameters:
  
  unit - the unit to format.
  
  toAppendTo - where the text is to be appended
  
  pos - the field position (not used).
  
  Returns:
  
  toAppendTo
  
  parseObject
  
  public final javax.measure.Unit<?> parseObject(String source, ParsePosition pos) throws javax.measure.format.MeasurementParseException
  
  Parses the text from a string to produce an object (implements java.text.Format).
  
  Parameters:
  
  source - the string source, part of which should be parsed.
  
  pos - the cursor position.
  
  Returns:
  
  the corresponding unit or null if the string cannot be parsed.
  
  Throws:
  
  javax.measure.format.MeasurementParseException

Class SimpleUnitFormat

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class tech.units.indriya.format.AbstractUnitFormat

Methods inherited from class java.lang.Object

Methods inherited from interface javax.measure.format.UnitFormat

Constructor Detail

SimpleUnitFormat

Method Detail

getInstance

getInstance

getNewInstance

getNewInstance

format

parseProductUnit

parseSingleUnit

label

removeLabel

alias

removeAlias

removeAliases

isValidIdentifier

format

parseObject