org.apache.sis.measure

Class UnitFormat

Object

Format

UnitFormat

All Implemented Interfaces:

Serializable, Cloneable, UnitFormat, Localized

public class UnitFormat
extends Format
implements UnitFormat, Localized

Parses and formats units of measurement as SI symbols, URI in OGC namespace or other symbols. This class combines in a single class the API from java.text and the API from javax.measure.format. In addition to the symbols of the Système international (SI), this class is also capable to handle some symbols found in Well Known Text (WKT) definitions or in XML files.

Parsing authority codes

As a special case, if a character sequence given to the parse(Char­Sequence) method is of the "EPSG:####" or "urn:ogc:def:uom:EPSG::####" form (ignoring case and whitespaces), then "####" is parsed as an integer and forwarded to the Units.value­Of­EPSG(int) method.

NetCDF unit symbols

The attributes in netCDF files often merge the axis direction with the angular unit, as in "degrees_east", "degrees_north" or "Degrees North". This class ignores those suffixes and unconditionally returns Units.DEGREE for all axis directions. In particular, the units for "degrees_west" and "degrees_east" do not have opposite sign. It is caller responsibility to handle the direction of axes associated to netCDF units.

Multi-threading

Unit­Format is generally not thread-safe. However if there is no call to any setter method or to label(Unit, String) after construction, then the parse(Char­Sequence) and format(Unit) methods can be invoked concurrently in different threads.

Since:

0.8

See Also:

Units.value­Of(String), Serialized Form

Defined in the sis-utility module

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UnitFormat.Style Identify whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.

Nested classes/interfaces inherited from class Format

Format.Field

Constructor Summary

Constructors

Constructor and Description
UnitFormat(Locale locale) Creates a new format for the given locale.

Method Summary

Modifier and Type	Method and Description
UnitFormat	clone() Returns a clone of this unit format.
StringBuffer	format(Object unit, StringBuffer toAppendTo, FieldPosition pos) Formats the specified unit in the given buffer.
String	format(Unit<?> unit) Formats the given unit.
Appendable	format(Unit<?> unit, Appendable toAppendTo) Formats the specified unit.
Locale	getLocale() Returns the locale used by this Unit­Format.
UnitFormat.Style	getStyle() Returns whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.
boolean	isLocaleSensitive() Returns whether this Unit­Format depends on the Locale given at construction time for performing its tasks.
void	label(Unit<?> unit, String label) Attaches a label to the specified unit.
Unit<?>	parse(CharSequence symbols) Parses the given text as an instance of Unit.
Unit<?>	parse(CharSequence symbols, ParsePosition position) Parses a portion of the given text as an instance of Unit.
Object	parseObject(String source) Parses text from a string to produce a unit.
Object	parseObject(String source, ParsePosition pos) Parses text from a string to produce a unit, or returns null if the parsing failed.
void	setLocale(Locale locale) Sets the locale that this Unit­Format will use for long names.
void	setStyle(UnitFormat.Style style) Sets whether unit formatting should use ASCII symbols, Unicode symbols or full localized names.

Methods inherited from class Format

format, format­To­Character­Iterator

Methods inherited from class Object

equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

UnitFormat

public UnitFormat(Locale locale)

Creates a new format for the given locale.

Parameters:

locale - the locale to use for parsing and formatting units.

Method Detail

getLocale

public Locale getLocale()

Returns the locale used by this Unit­Format.

Specified by:

get­Locale in interface Localized

Returns:

the locale of this Unit­Format.

setLocale

public void setLocale(Locale locale)

Sets the locale that this Unit­Format will use for long names. For example a call to set­Locale(Locale.US) instructs this formatter to use the “meter” spelling instead of “metre”.

Parameters:

locale - the new locale for this Unit­Format.

See Also:

Unit­Services.get­Unit­Format(String)

isLocaleSensitive

public boolean isLocaleSensitive()

Returns whether this Unit­Format depends on the Locale given at construction time for performing its tasks. This method returns true if formatting long names (e.g. “metre” or “meter”} and false if formatting only the unit symbol (e.g. “m”).

Specified by:

is­Locale­Sensitive in interface Unit­Format

Returns:

true if formatting depends on the locale.

getStyle

public UnitFormat.Style getStyle()

Returns whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.

Returns:

the style of units formatted by this Unit­Format instance.

setStyle

public void setStyle(UnitFormat.Style style)

Sets whether unit formatting should use ASCII symbols, Unicode symbols or full localized names.

Parameters:

style - the desired style of units.

label

public void label(Unit<?> unit,
                  String label)

Attaches a label to the specified unit. A label can be a substitute to either the unit symbol or the unit name, depending on the format style. If the specified label is already associated to another unit, then the previous association is discarded.

Restriction on character set

Current implementation accepts only letters, subscripts, spaces (including non-breaking spaces but not CR/LF characters), the degree sign (°) and a few other characters like underscore, but the set of legal characters may be expanded in future Apache SIS versions. However the following restrictions are likely to remain:

• The following characters are reserved since they have special meaning in UCUM format, in URI or in Apache SIS parser:

  " # ( ) * + - . / : = ? [ ] { } ^ ⋅ ∕

• The symbol can not begin or end with digits, since such digits would be confused with unit power.

Specified by:

label in interface Unit­Format

Parameters:

unit - the unit being labeled.

label - the new label for the given unit.

Throws:

Illegal­Argument­Exception - if the given label is not a valid unit name.

format

public Appendable format(Unit<?> unit,
                         Appendable toAppendTo)
                  throws IOException

Formats the specified unit. This method performs the first of the following actions that can be done.

1. If a label has been specified for the given unit, then that label is appended unconditionally.
2. Otherwise if the formatting style is Unit­Format.Style.NAME and the Unit.get­Name() method returns a non-null value, then that value is appended. Unit instances implemented by Apache SIS are handled in a special way for localizing the name according the locale specified to this format.
3. Otherwise if the Unit.get­Symbol() method returns a non-null value, then that value is appended.
4. Otherwise a default symbol is created from the entries returned by Unit.get­Base­Units().

Specified by:

format in interface Unit­Format

Parameters:

unit - the unit to format.

to­Append­To - where to format the unit.

Returns:

the given to­Append­To argument, for method calls chaining.

Throws:

IOException - if an error occurred while writing to the destination.

format

public StringBuffer format(Object unit,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats the specified unit in the given buffer. This method delegates to format(Unit, Appendable).

Specified by:

format in class Format

Parameters:

unit - the unit to format.

to­Append­To - where to format the unit.

pos - where to store the position of a formatted field.

Returns:

the given to­Append­To argument, for method calls chaining.

format

public String format(Unit<?> unit)

Formats the given unit. This method delegates to format(Unit, Appendable).

Specified by:

format in interface Unit­Format

Parameters:

unit - the unit to format.

Returns:

the formatted unit.

parse

public Unit<?> parse(CharSequence symbols)
              throws ParserException

Parses the given text as an instance of Unit. If the parse completes without reading the entire length of the text, an exception is thrown.

The parsing is lenient: symbols can be products or quotients of units like “m∕s”, words like “meters per second”, or authority codes like "urn:ogc:def:uom:EPSG::1026". The product operator can be either '.' (ASCII) or '⋅' (Unicode) character. Exponent after symbol can be decimal digits as in “m2” or a superscript as in “m²”.

The default implementation delegates to parse(symbols, new Parse­Position(0)) and verifies that all non-white characters have been parsed.

Specified by:

parse in interface Unit­Format

Parameters:

symbols - the unit symbols or URI to parse.

Returns:

the unit parsed from the specified symbols.

Throws:

Parser­Exception - if a problem occurred while parsing the given symbols.

See Also:

Units.value­Of(String)

parse

public Unit<?> parse(CharSequence symbols,
                     ParsePosition position)
              throws ParserException

Parses a portion of the given text as an instance of Unit. Parsing begins at the index given by Parse­Position.get­Index(). After parsing, the above-cited index is updated to the first unparsed character.

The parsing is lenient: symbols can be products or quotients of units like “m∕s”, words like “meters per second”, or authority codes like "urn:ogc:def:uom:EPSG::1026". The product operator can be either '.' (ASCII) or '⋅' (Unicode) character. Exponent after symbol can be decimal digits as in “m2” or a superscript as in “m²”.

Note that contrarily to parse­Object(String, Parse­Position), this method never return null. If an error occurs at parsing time, an unchecked Parser­Exception is thrown.

Parameters:

symbols - the unit symbols to parse.

position - on input, index of the first character to parse. On output, index after the last parsed character.

Returns:

the unit parsed from the specified symbols.

Throws:

Parser­Exception - if a problem occurred while parsing the given symbols.

parseObject

public Object parseObject(String source)
                   throws ParseException

Parses text from a string to produce a unit. The default implementation delegates to parse(Char­Sequence) and wraps the Parser­Exception into a Parse­Exception for compatibility with java.text API.

Overrides:

parse­Object in class Format

Parameters:

source - the text, part of which should be parsed.

Returns:

a unit parsed from the string.

Throws:

Parse­Exception - if the given string can not be fully parsed.

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Parses text from a string to produce a unit, or returns null if the parsing failed. The default implementation delegates to parse(Char­Sequence, Parse­Position) and catches the Parser­Exception.

Specified by:

parse­Object in class Format

Parameters:

source - the text, part of which should be parsed.

pos - index and error index information as described above.

Returns:

a unit parsed from the string, or null in case of error.

clone

public UnitFormat clone()

Returns a clone of this unit format. The new unit format will be initialized to the same locale and labels than this format.

Overrides:

clone in class Format

Returns:

a clone of this unit format.