javax.measure.format

Interface UnitFormat

public interface UnitFormat

Formats instances of Unit to a String or an Appendable and parses a CharSequence to a Unit.

Synchronization

Instances of this class are not required to be thread-safe. It is recommended to of separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

Version:

0.7.3, Oct 10, 2015

Author:

Jean-Marie Dautelle, Werner Keil

See Also:

Unit

Method Summary

Methods

Modifier and Type	Method and Description
String	format(Unit<?> unit) Formats the specified Unit.
Appendable	format(Unit<?> unit, Appendable appendable) Formats the specified Unit.
boolean	isLocaleSensitive() Returns true if this UnitFormat depends on a Locale to perform its tasks.
void	label(Unit<?> unit, String label) Attaches a system-wide label to the specified unit.
Unit<?>	parse(CharSequence csq) Parses a portion of the specified CharSequence from the specified position to produce a unit.

Method Detail

format

Appendable format(Unit<?> unit,
                Appendable appendable)
                  throws IOException

Formats the specified Unit.

Parameters:

unit - the Unit to format, not null

appendable - the appendable destination.

Returns:

the appendable destination passed in with formatted text appended.

Throws:

IOException - if an error occurs while writing to the destination.

format

String format(Unit<?> unit)

Formats the specified Unit.

Parameters:

unit - the Unit to format, not null

Returns:

the string representation using the settings of this UnitFormat.

Throws:

IOException - if an error occurs while writing to the destination.

label

void label(Unit<?> unit,
         String label)

Attaches a system-wide label to the specified unit.

If the specified label is already associated to a unit the previous association can be discarded or ignored. 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 - the unit being labeled.

label - the new label for this unit.

Throws:

IllegalArgumentException - if the label is not a valid identifier. This may include characters not supported by a particular UnitFormat implementation (e.g. only ASCII characters for certain devices)

UnsupportedOperationException - if the label operation is not supported by this UnitFormat

isLocaleSensitive

boolean isLocaleSensitive()

Returns true if this UnitFormat depends on a Locale to perform its tasks.

In environments that do not support a Locale, e.g. Java ME, this usually returns false.

Returns:

Whether this format depends on the locale.

parse

Unit<?> parse(CharSequence csq)
              throws ParserException

Parses a portion of the specified CharSequence from the specified position to produce a unit. If there is no unit to parse the unitary unit (dimensionless) is returned.

Parameters:

csq - the CharSequence to parse.

Returns:

the unit parsed from the specified character sub-sequence.

Throws:

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