JScience v4.3

javax.measure.unit
Class UnitFormat

java.lang.Object
  extended by java.text.Format
      extended by javax.measure.unit.UnitFormat
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
UnitFormat.DefaultFormat

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.3, August 29, 2006
Author:
Jean-Marie Dautelle, Eric Russell
See Also:
Serialized Form

Nested Class Summary
protected static class UnitFormat.ASCIIFormat
          This class represents the ASCIIFormat format.
protected static class UnitFormat.DefaultFormat
          This class represents the standard format.
 
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 getInstance()
          Returns the unit format for the default locale (format used by Unit.valueOf(CharSequence) and Unit.toString()).
static UnitFormat getInstance(java.util.Locale inLocale)
          Returns the unit format for the specified locale.
static UnitFormat getUCUMInstance()
          Returns the UCUM international unit format; this format uses characters range 0000-007F exclusively and is not locale-sensitive.
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.
 Unit<?> parseObject(java.lang.String source, java.text.ParsePosition pos)
          Parses the text from a string to produce an object (implements java.text.Format).
abstract  Unit<? extends Quantity> parseProductUnit(java.lang.CharSequence csq, java.text.ParsePosition pos)
          Parses a sequence of character to produce a unit or a rational product of unit.
abstract  Unit<? extends Quantity> parseSingleUnit(java.lang.CharSequence csq, java.text.ParsePosition pos)
          Parses a sequence of character to produce a single unit.
 
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

getInstance

public static UnitFormat getInstance()
Returns the unit format for the default locale (format used by Unit.valueOf(CharSequence) and Unit.toString()).

Returns:
the default unit format (locale sensitive).

getInstance

public static UnitFormat getInstance(java.util.Locale inLocale)
Returns the unit format for the specified locale.

Returns:
the unit format for the specified locale.

getUCUMInstance

public static UnitFormat getUCUMInstance()
Returns the UCUM international unit format; this format uses characters range 0000-007F exclusively and is not locale-sensitive. For example: kg.m/s2

Returns:
the UCUM international format.

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.

parseProductUnit

public abstract Unit<? extends Quantity> parseProductUnit(java.lang.CharSequence csq,
                                                          java.text.ParsePosition pos)
                                                   throws java.text.ParseException
Parses a sequence of character to produce a unit or a rational product of 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.
java.text.ParseException

parseSingleUnit

public abstract Unit<? extends Quantity> parseSingleUnit(java.lang.CharSequence csq,
                                                         java.text.ParsePosition pos)
                                                  throws java.text.ParseException
Parses a sequence of character to produce a single 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 does not contain a valid unit identifier.
java.text.ParseException

label

public abstract void label(Unit<?> unit,
                           java.lang.String label)
Attaches a system-wide label to the specified unit. For example:
     UnitFormat.getInstance().label(DAY.multiply(365), "year");
     UnitFormat.getInstance().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.

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 Unit<?> 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.

JScience v4.3

Copyright © 2006 JScience.