UnitFormat (JADE v6.1 API)

Overview

Package

Class

Tree

Deprecated

Index

Help

JADE v6.1

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.units
Class UnitFormat

java.lang.Object
  java.text.Format
      javax.units.UnitFormat

All Implemented Interfaces:: java.lang.Cloneable, java.io.Serializable

public abstract class UnitFormat
extends java.text.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)

Version:: 4.0, February 29, 2003
Author:: Jean-Marie Dautelle
See Also:: Serialized Form

Nested Class Summary

Nested classes inherited from class java.text.Format

java.text.Format.Field

Constructor Summary
`protected`	`UnitFormat()` Base constructor.

Method Summary
`static Unit`	`alias(Unit unit, java.lang.String alias)` Attaches a system-wide alias to the specified unit.
`abstract java.lang.StringBuffer`	`format(java.lang.Object obj, java.lang.StringBuffer toAppendTo, java.text.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 `context local` unit format (default `getStandardInstance()`).
`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, java.lang.String label)` Attaches a system-wide label to the specified unit.
`java.lang.String`	`labelFor(Unit unit)` Returns the label for the specified unit.
`java.lang.Object`	`parseObject(java.lang.String source, java.text.ParsePosition pos)` Parses text from a string to produce an object.
`Unit`	`parseUnit(java.lang.CharSequence source)` Parses text from a character sequence to produce a unit.
`static void`	`setInstance(UnitFormat format)` Sets the `context local` unit format.
`Unit`	`unitFor(java.lang.CharSequence label)` Returns the unit identified by the specified label.

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

label

public static Unit label(Unit unit,
                         java.lang.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:: java.lang.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,
                         java.lang.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 UnitFormat getInstance()

Returns the context local unit format (default getStandardInstance()).

Returns:: the unit format for the current thread.

setInstance

public static void setInstance(UnitFormat format)

Sets the context local unit format.

Parameters:: format - the new local/global format.

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>

(cm³·kg^-1·A²)

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 java.lang.StringBuffer format(java.lang.Object obj,
                                              java.lang.StringBuffer toAppendTo,
                                              java.text.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:: java.lang.NullPointerException - if toAppendTo is null; java.lang.IllegalArgumentException - if this format cannot format the given object (e.g. not a Unit instance).

parseObject

public final java.lang.Object parseObject(java.lang.String source,
                                          java.text.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(java.lang.CharSequence source)
               throws java.text.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<sup>-1</sup>·s<sup>-2</sup>

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

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:: java.text.ParseException - if a parsing error occurs.

labelFor

public java.lang.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(java.lang.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)