Top Description Fields Constructors Methods
tech.units.indriya.format

public Class EBNFUnitFormat

extends AbstractUnitFormat
Class Inheritance
Imports
javax.measure.Quantity, .Unit, javax.measure.format.MeasurementParseException, tech.units.indriya.AbstractUnit, tech.units.indriya.internal.format.UnitFormatParser, tech.units.indriya.unit.AnnotatedUnit, java.io.IOException, .StringReader, java.text.ParsePosition, java.util.Locale, .ResourceBundle

This class represents the local neutral format.

Here is the grammar for Units in Extended Backus-Naur Form (EBNF)

Note that the grammar has been left-factored to be suitable for use by a top-down parser generator such as JavaCC

Lexical Entities:
<sign> := "+" | "-"
<digit> := "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<superscript_digit> := "⁰" | "¹" | "²" | "³" | "⁴" | "⁵" | "⁶" | "⁷" | "⁸" | "⁹"
<integer> := (<digit>)+
<number> := (<sign>)? (<digit>)* (".")? (<digit>)+ (("e" | "E") (<sign>)? (<digit>)+)?
<exponent> := ( "^" ( <sign> )? <integer> )
| ( "^(" (<sign>)? <integer> ( "/" (<sign>)? <integer> )? ")" )
| ( <superscript_digit> )+
<initial_char> := ? Any Unicode character excluding the following: ASCII control & whitespace (\u0000 - \u0020), decimal digits '0'-'9', '(' (\u0028), ')' (\u0029), '*' (\u002A), '+' (\u002B), '-' (\u002D), '.' (\u002E), '/' (\u005C), ':' (\u003A), '^' (\u005E), '²' (\u00B2), '³' (\u00B3), '·' (\u00B7), '¹' (\u00B9), '⁰' (\u2070), '⁴' (\u2074), '⁵' (\u2075), '⁶' (\u2076), '⁷' (\u2077), '⁸' (\u2078), '⁹' (\u2079) ?
<unit_identifier> := <initial_char> ( <initial_char> | <digit> )*
Non-Terminals:
<unit_expr> := <mix_expr>
<mix_expr> := <add_expr> ( ":" <add_expr> )*
<add_expr> := ( <number> <sign> )? <mul_expr> ( <sign> <number> )?
<mul_expr> := <exponent_expr> ( ( ( "*" | "·" ) <exponent_expr> ) | ( "/" <exponent_expr> ) )*
<exponent_expr> := ( <atomic_expr> ( <exponent> )? )
| (<integer> "^" <atomic_expr>)
| ( ( "log" ( <integer> )? ) | "ln" ) "(" <add_expr> ")" )
<atomic_expr> := <number>
| <unit_identifier>
| ( "(" <add_expr> ")" )
Authors
Eric Russell, Werner Keil
Since
1.0
Version
2.2, October 12, 2024

Field Summary

Modifier and TypeField and Description
private static final String
BUNDLE_NAME

Name of the resource bundle

private static final EBNFUnitFormat
DEFAULT_INSTANCE

Default locale instance.

private final transient SymbolMap
symbolMap

The symbol map used by this instance to map between Units and Strings, etc...

Constructor Summary

AccessConstructor and Description
pack-priv
EBNFUnitFormat()

Base constructor.

private
EBNFUnitFormat(SymbolMap
the symbol mapping.
symbols)

Private constructor.

Method Summary

Modifier and TypeMethod and Description
public void
alias(Unit<?>
the unit being aliased.
unit, String
the alias attached to this unit.
alias)

Attaches a system-wide alias to this unit.

public Appendable
format(Unit<?>
the unit to format.
unit, Appendable
the appendable destination.
appendable)

Implements abstract tech.units.indriya.format.AbstractUnitFormat.format.

Implements javax.measure.format.UnitFormat.format.

Formats the specified unit.

public static EBNFUnitFormat
getInstance()

Returns the instance for the current default locale (non-ascii characters are allowed)

public static EBNFUnitFormat
getInstance(SymbolMap symbols)

Returns a new instance for the given symbol map.

public static EBNFUnitFormat

Returns:

a new instance of the default unit format.
getNewInstance()

Similar to getInstance(), but returns a new, non-shared unit format instance, instead of a shared singleton instance.

protected SymbolMap

Returns:

SymbolMap the current symbol map
getSymbols()

Get the symbol map used by this instance to map between Units and Strings, etc...

public void
label(Unit<?>
the unit being labeled.
unit, String
the new label for this unit.
label)

Overrides tech.units.indriya.format.AbstractUnitFormat.label.

Implements javax.measure.format.UnitFormat.label.

Attaches a system-wide label to the specified Unit.

public Unit<? extends Quantity<?>>
parse(CharSequence
the CharSequence to parse.
csq, ParsePosition
the cursor holding the current parsing index.
cursor)

Implements abstract tech.units.indriya.format.AbstractUnitFormat.parse.

Implements javax.measure.format.UnitFormat.parse.

Parses a portion of the specified CharSequence from the specified position to produce a unit.

protected Unit<?>
parse(CharSequence
the CharSequence to parse.
csq, int
the current parsing index.
index)

Implements abstract tech.units.indriya.format.AbstractUnitFormat.parse.

Parses a portion of the specified CharSequence from the specified position to produce a unit.

public Unit<?>
parse(CharSequence
the CharSequence to parse.
csq)

Implements javax.measure.format.UnitFormat.parse.

Parses the text into an instance of Unit.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from tech.units.indriya.format.AbstractUnitFormat:
format

Field Detail

BUNDLE_NAMEback to summary
private static final String BUNDLE_NAME

Name of the resource bundle

DEFAULT_INSTANCEback to summary
private static final EBNFUnitFormat DEFAULT_INSTANCE

Default locale instance. If the default locale is changed after the class is initialized, this instance will no longer be used.

symbolMapback to summary
private final transient SymbolMap symbolMap

The symbol map used by this instance to map between Units and Strings, etc...

Constructor Detail

EBNFUnitFormatback to summary
pack-priv EBNFUnitFormat()

Base constructor.

EBNFUnitFormatback to summary
private EBNFUnitFormat(SymbolMap symbols)

Private constructor.

Parameters
symbols:SymbolMap

the symbol mapping.

Method Detail

aliasback to summary
public void alias(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: EBNFUnitFormat.getInstance().alias(METRE.multiply(0.3048), "foot"); EBNFUnitFormat.getInstance().alias(METRE.multiply(0.3048), "feet"); EBNFUnitFormat.getInstance().alias(METRE, "meter"); If the specified alias is already associated to a unit or applied as a label, the association is replaced by the new one.

Parameters
unit:Unit<?>

the unit being aliased.

alias:String

the alias attached to this unit.

formatback to summary
public Appendable format(Unit<?> unit, Appendable appendable) throws IOException

Implements abstract tech.units.indriya.format.AbstractUnitFormat.format.

Implements javax.measure.format.UnitFormat.format.

Doc from tech.units.indriya.format.AbstractUnitFormat.format.

Formats the specified unit.

Parameters
unit:Unit<?>

the unit to format.

appendable:Appendable

the appendable destination.

Returns:Appendable

The appendable destination passed in as appendable, with formatted text appended.

Exceptions
IOException:
if an error occurs.
getInstanceback to summary
public static EBNFUnitFormat getInstance()

Returns the instance for the current default locale (non-ascii characters are allowed)

getInstanceback to summary
public static EBNFUnitFormat getInstance(SymbolMap symbols)

Returns a new instance for the given symbol map.

getNewInstanceback to summary
public static EBNFUnitFormat getNewInstance()

Similar to getInstance(), but returns a new, non-shared unit format instance, instead of a shared singleton instance.

Returns:EBNFUnitFormat

a new instance of the default unit format.

Since
2.0
See Also
getInstance()
getSymbolsback to summary
protected SymbolMap getSymbols()

Get the symbol map used by this instance to map between Units and Strings, etc...

Returns:SymbolMap

SymbolMap the current symbol map

labelback to summary
public void label(Unit<?> unit, String label)

Overrides tech.units.indriya.format.AbstractUnitFormat.label.

Implements javax.measure.format.UnitFormat.label.

Doc from javax.measure.format.UnitFormat.label.

Attaches a system-wide label to the specified Unit.

This method overrides the previous unit's label (e.g. label from unit database or unit system) as units may only have one label. Depending on the UnitFormat implementation, this call may be ignored if the particular unit already has a label.

If a UnitFormat implementation is explicitly immutable, similar to e.g. the result of Collections.unmodifiableList(), then an UnsupportedOperationException may be thrown upon this call.

Since UnitFormat implementations often apply the Singleton pattern, system-wide means, the label applies to every instance of UnitFormatA implementing UnitFormat in this case, but not every instance of UnitFormatB or UnitFormatC both also implementing UnitFormat. If a UnitFormat #isLocaleSensitive() it is up to the implementation, whether the label is ignored, applied in a local-neutral manner (in addition to its local-sensitive information) or locale-specific.

Parameters
unit:Unit<?>

the unit being labeled.

label:String

the new label for this unit.

Annotations
@Override
parseback to summary
public Unit<? extends Quantity<?>> parse(CharSequence csq, ParsePosition cursor) throws MeasurementParseException

Implements abstract tech.units.indriya.format.AbstractUnitFormat.parse.

Implements javax.measure.format.UnitFormat.parse.

Doc from tech.units.indriya.format.AbstractUnitFormat.parse.

Parses a portion of the specified CharSequence from the specified position to produce a unit. If there is no unit to parse AbstractUnit#ONE is returned.

Parameters
csq:CharSequence

the CharSequence to parse.

cursor:ParsePosition

the cursor holding the current parsing index.

Returns:Unit<? extends Quantity<?>>

the unit parsed from the specified character sub-sequence.

Annotations
@Override
Exceptions
MeasurementParseException:

Doc from javax.measure.format.UnitFormat.parse.

if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).

parseback to summary
protected Unit<?> parse(CharSequence csq, int index) throws IllegalArgumentException

Implements abstract tech.units.indriya.format.AbstractUnitFormat.parse.

Doc from tech.units.indriya.format.AbstractUnitFormat.parse.

Parses a portion of the specified CharSequence from the specified position to produce a unit. If there is no unit to parse AbstractUnit#ONE is returned.

Parameters
csq:CharSequence

the CharSequence to parse.

index:int

the current parsing index.

Returns:Unit<?>

the unit parsed from the specified character sub-sequence.

Annotations
@Override
Exceptions
IllegalArgumentException:
if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
parseback to summary
public Unit<?> parse(CharSequence csq) throws MeasurementParseException

Implements javax.measure.format.UnitFormat.parse.

Doc from javax.measure.format.UnitFormat.parse.

Parses the text into an instance of Unit.

The parse must complete normally and parse the entire text. If the parse completes without reading the entire length of the text, an exception is thrown. If any other problem occurs during parsing, an exception is thrown.

Parameters
csq:CharSequence

the CharSequence to parse.

Returns:Unit<?>

the unit parsed from the specified character sequence.

Annotations
@Override
Exceptions
MeasurementParseException:
if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override