javax.units
Class UnitFormat

Object
  Format
      UnitFormat

All Implemented Interfaces:

Cloneable, Serializable

public abstract class UnitFormat

extends Format

This is the abstract base class for all unit formats.

This class provides the interface for formatting and parsing units.

For all SI units, the 20 SI prefixes used to form decimal multiples and sub-multiples of SI units are recognized. NonSI units are directly recognized. For example:

        Unit.valueOf("m°C") == SI.MILLI(SI.CELSIUS)
        Unit.valueOf("kW")  == SI.KILO(SI.WATT)
        Unit.valueOf("ft")  == SI.METER.multiply(0.3048)

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class Format

Format.Field

Constructor Summary

UnitFormat()

Method Summary

static Unit	alias(Unit unit, String alias) Attaches a system-wide alias to the specified unit.
abstract StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats a unit and appends the resulting text to a given string buffer.
static UnitFormat	getAsciiInstance() Returns the ASCII unit format.
static UnitFormat	getHtmlInstance() Returns the HTML unit format.
static UnitFormat	getInstance() Returns the default unit format for the current default locale.
static UnitFormat	getStandardInstance() Returns the standard unit format.
static boolean	isUnitIdentifierPart(char ch) Determines if the specified character may be part of a unit identifier.
static Unit	label(Unit unit, String label) Attaches a system-wide label to the specified unit.
String	labelFor(Unit unit) Returns the label for the specified unit.
Object	parseObject(String source, ParsePosition pos) Parses text from a string to produce an object.
Unit	parseUnit(CharSequence source) Parses text from a character sequence to produce a unit.
Unit	unitFor(CharSequence label) Returns the unit identified by the specified label.

Methods inherited from class Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class Object

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

Constructor Detail

UnitFormat

public UnitFormat()

Method Detail

label

public static Unit label(Unit unit,
                         String label)

Attaches a system-wide label to the specified unit. This method overrides the previous unit's label (e.g. label from unit database) as units may only have one label (but multiple aliases). For example:

     UnitFormat.label(DAY.multiply(365), "year");
     Unit FOOT = UnitFormat.label(METER.multiply(0.3048), "ft");
 

Parameters:

unit - the unit being associated to the specified label.

label - the new label for the specified unit or null to detache the previous label (if any).

Returns:

the specified unit.

Throws:

IllegalArgumentException - if the specified label is a known symbol or if the specified label is already attached to a different unit (must be detached first).

See Also:

labelFor(javax.units.Unit), alias(javax.units.Unit, java.lang.String)

alias

public static Unit alias(Unit unit,
                         String alias)

Attaches a system-wide alias to the specified 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:

     UnitFormat.alias(METER.multiply(0.3048), "foot");
     UnitFormat.alias(METER.multiply(0.3048), "feet");
     UnitFormat.alias(METER, "meter");
     UnitFormat.alias(METER, "metre");
 

Parameters:

unit - the unit being aliased.

alias - the alias being attached to the specified unit.

Returns:

the specified unit.

See Also:

unitFor(java.lang.CharSequence)

getInstance

public static final UnitFormat getInstance()

Returns the default unit format for the current default locale. For example: centimétre cube par kilogramme fois Ampére carré (French locale).

Returns:

the unit format for the current locale.

getStandardInstance

public static final UnitFormat getStandardInstance()

Returns the standard unit format. This format is not locale sensitive (international) and uses UTF Latin-1 Supplement (range 0080-00FF) supported by the majority of fonts. For example: cm³·A²/kg

Returns:

the standard unit format (format used by Unit.toString()).

getAsciiInstance

public static final UnitFormat getAsciiInstance()

Returns the ASCII unit format. This format uses characters range 0000-007F exclusively. For example: cm^3 kg^-1 A^2

Returns:

the ASCII unit format.

getHtmlInstance

public static final UnitFormat getHtmlInstance()

Returns the HTML unit format. This format makes use of HTML tags to represent product units. For example: cm<sup>3</sup>&#183;kg<sup>-1 </sup>&#183;A<sup>2</sup> (cm3·kg-1·A2)

Returns:

the HTML unit format.

isUnitIdentifierPart

public static boolean isUnitIdentifierPart(char ch)

Determines if the specified character may be part of a unit identifier. Any letter or symbol which cannot be mistaken for a separator is allowed.

Parameters:

ch - the character to be tested.

Returns:

true if the character may be part of a unit identifier; false otherwise.

format

public abstract StringBuffer format(Object obj,
                                    StringBuffer toAppendTo,
                                    FieldPosition pos)

Formats a unit and appends the resulting text to a given string buffer.

Parameters:

obj - the unit to format.

toAppendTo - where the text is to be appended

pos - a FieldPosition identifying a field in the formatted text (not used).

Returns:

the string buffer passed in as toAppendTo, with formatted text appended.

Throws:

NullPointerException - if toAppendTo is null

IllegalArgumentException - if this format cannot format the given object (e.g. not a Unit instance).

parseObject

public final Object parseObject(String source,
                                ParsePosition pos)

Parses text from a string to produce an object.

Parameters:

source - a String, part of which should be parsed.

pos - a ParsePosition object with index and error index information.

Returns:

an Object parsed from the string. In case of error, returns null.

See Also:

parseUnit(java.lang.CharSequence)

parseUnit

public Unit parseUnit(CharSequence source)
               throws ParseException

Parses text from a character sequence to produce a unit.

The expected form of the character sequence is: {<name>{<power>{<root>}}}

For examples:

• kg-2/3
• rad·s-²
• m*s**-2 (for Fortran users)
• [K+273.15] (equivalent to °C)
• K^+1:2 cd^-2
• mol^-1·s^-2

HTML tags are ignored (e.g. ^...).

Escape sequences are considered as separators (e.g. ·).

"/" (if not placed between two numbers) indicates ALL the following unit exponents will be multiplied by -1; multiple instances of "/" in a line will result in successive implicit multiplications by -1 of all the exponents that follow (e.g. "s/s/s" is equivalent to "s").

Parameters:

source - the characters sequence to be parsed.

Returns:

a Unit parsed from the string.

Throws:

ParseException - if a parsing error occurs.

labelFor

public String labelFor(Unit unit)

Returns the label for the specified unit. The default behavior of this method (which may be overridden) is first to search the label database.

Parameters:

unit - the unit to format.

Returns:

the database label, the unit's symbol, some other representation of the specified unit (e.g. [K+273.15], [m*0.01]) or null for units with custom converters or ProductUnit with no label.

See Also:

unitFor(java.lang.CharSequence)

unitFor

public Unit unitFor(CharSequence label)

Returns the unit identified by the specified label. The default behavior of this method (which may be overridden) is first to search the label database, then the alias database and finally the symbols collection.

Parameters:

label - the label, alias, or symbol identifying the unit.

Returns:

the unit identified by the specified label or null if the identification fails.

See Also:

labelFor(javax.units.Unit)