javax.measure.unit
Class UnitFormat

java.lang.Object
  java.text.Format
      javax.measure.unit.UnitFormat

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public abstract class UnitFormat
extends java.text.Format

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").equals(SI.MILLI(SI.CELSIUS))
        Unit.valueOf("kW").equals(SI.KILO(SI.WATT))
        Unit.valueOf("ft").equals(SI.METER.multiply(0.3048))

Version:

1.2, February 9, 2006

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.text.Format

java.text.Format.Field

Constructor Summary

protected

UnitFormat() Base constructor.

Method Summary

abstract void	alias(Unit unit, java.lang.String alias) Attaches a system-wide alias to this unit.
java.lang.StringBuffer	format(java.lang.Object unit, java.lang.StringBuffer toAppendTo, java.text.FieldPosition pos) Formats an unit and appends the resulting text to a given string buffer (implements java.text.Format).
abstract java.lang.Appendable	format(Unit unit, java.lang.Appendable appendable) Formats the specified unit.
static UnitFormat	getAsciiInstance() Returns the ASCII unit format; this format uses characters range 0000-007F exclusively.
static UnitFormat	getHtmlInstance() Returns the HTML unit format.
static UnitFormat	getLocaleInstance() Returns the locale instance; this format interprets units differently based upon the current runtime locale (e.g.
static UnitFormat	getStandardInstance() Returns the standard unit format (format used by Unit.valueOf(CharSequence) and Unit.toString()).
abstract boolean	isValidIdentifier(java.lang.String name) Indicates if the specified name can be used as unit identifier.
abstract void	label(Unit unit, java.lang.String label) Attaches a system-wide label to the specified unit.
abstract Unit<? extends Quantity>	parse(java.lang.CharSequence csq, java.text.ParsePosition pos) Parses a sequence of character to produce an unit.
java.lang.Object	parseObject(java.lang.String source, java.text.ParsePosition pos) Parses the text from a string to produce an object (implements java.text.Format).

Methods inherited from class java.text.Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

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

Constructor Detail

UnitFormat

protected UnitFormat()

Base constructor.

Method Detail

getStandardInstance

public static UnitFormat getStandardInstance()

Returns the standard unit format (format used by Unit.valueOf(CharSequence) and Unit.toString()). This format is independant of any locale and uses UTF Latin-1 Supplement (range 0080-00FF) supported by the majority of fonts. For example: cm³·A²/kg

getLocaleInstance

public static UnitFormat getLocaleInstance()

Returns the locale instance; this format interprets units differently based upon the current runtime locale (e.g. "gal" (gallon) has not the same value in US and UK)

getAsciiInstance

public static UnitFormat getAsciiInstance()

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

getHtmlInstance

public static 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)

format

public abstract java.lang.Appendable format(Unit unit,
                                            java.lang.Appendable appendable)
                                     throws java.io.IOException

Formats the specified unit.

Parameters:

unit - the unit to format.

appendable - the appendable destination.

Throws:

java.io.IOException - if an error occurs.

parse

public abstract Unit<? extends Quantity> parse(java.lang.CharSequence csq,
                                               java.text.ParsePosition pos)

Parses a sequence of character to produce an 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:

java.lang.IllegalArgumentException - if the character sequence contains an illegal syntax.

label

public abstract void label(Unit unit,
                           java.lang.String label)

Attaches a system-wide label to the specified unit. For example:

     UnitFormat.getStandardInstance().label(DAY.multiply(365), "year");
     UnitFormat.getStandardInstance().label(METER.multiply(0.3048), "ft");
 

If the specified label is already associated to an unit the previous association is discarded or ignored.

Parameters:

unit - the unit being labelled.

label - the new label for this unit.

Throws:

java.lang.IllegalArgumentException - if the label is not a isValidIdentifier(String) valid identifier.

alias

public abstract void alias(Unit unit,
                           java.lang.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:

     UnitFormat.getLocaleInstance().alias(METER.multiply(0.3048), "foot");
     UnitFormat.getLocaleInstance().alias(METER.multiply(0.3048), "feet");
     UnitFormat.getLocaleInstance().alias(METER, "meter");
     UnitFormat.getLocaleInstance().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:

java.lang.IllegalArgumentException - if the label is not a isValidIdentifier(String) valid identifier.

isValidIdentifier

public abstract boolean isValidIdentifier(java.lang.String name)

Indicates if the specified name can be used as unit identifier. For the standard format (getStandardInstance()) identifiers with separators (e.g. blank spaces) are not valid.

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 java.lang.StringBuffer format(java.lang.Object unit,
                                           java.lang.StringBuffer toAppendTo,
                                           java.text.FieldPosition pos)

Formats an unit and appends the resulting text to a given string buffer (implements java.text.Format).

Specified by:

format in class 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 java.lang.Object parseObject(java.lang.String source,
                                          java.text.ParsePosition pos)

Parses the text from a string to produce an object (implements java.text.Format).

Specified by:

parseObject in class 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.