Java Units API
Build 2004-02-06

javax.units
Class UnitFormat

Object
  extended byFormat
      extended byUnitFormat
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:

HTML tags are ignored (e.g. <sup>...</sup>).

Escape sequences are considered as separators (e.g. &#183;).

"/" (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)

Java Units API
Build 2004-02-06

Symbols, terms and definitions
JSR-108 project