- All Implemented Interfaces:
Serializable,Cloneable,UnitFormat,Localized
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
If a character sequence given to theparse(CharSequence) method is of the form "EPSG:####",
"urn:ogc:def:uom:EPSG::####" or "http://www.opengis.net/def/uom/EPSG/0/####" (ignoring case
and whitespaces around path separators), then "####" is parsed as an integer and forwarded to the
Units.valueOfEPSG(int) method.
Note on netCDF unit symbols
In netCDF files, values of "unit" attribute are concatenations of an angular unit with an axis direction, as in"degrees_east" or "degrees_north". This class ignores those suffixes and unconditionally
returns Units.DEGREE for all axis directions.
Multi-threading
UnitFormat is generally not thread-safe. If units need to be parsed or formatted in different threads,
each thread should have its own UnitFormat instance.- Since:
- 0.8
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumIdentify whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.Nested classes/interfaces inherited from class Format
Format.Field -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionclone()Returns a clone of this unit format.format(Object unit, StringBuffer toAppendTo, FieldPosition pos) Formats the specified unit in the given buffer.Formats the given unit.format(Unit<?> unit, Appendable toAppendTo) Formats the specified unit.Returns the locale used by thisUnitFormat.Returns whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.booleanReturns whether thisUnitFormatdepends on theLocalegiven at construction time for performing its tasks.voidAttaches a label to the specified unit.Unit<?> parse(CharSequence symbols) Parses the given text as an instance ofUnit.Unit<?> parse(CharSequence symbols, ParsePosition position) Parses a portion of the given text as an instance ofUnit.parseObject(String source) Parses text from a string to produce a unit.parseObject(String source, ParsePosition pos) Parses text from a string to produce a unit, or returnsnullif the parsing failed.voidsetLocale(Locale locale) Sets the locale that thisUnitFormatwill use for long names.voidsetStyle(UnitFormat.Style style) Sets whether unit formatting should use ASCII symbols, Unicode symbols or full localized names.Methods inherited from class Format
format, formatToCharacterIterator
-
Constructor Details
-
UnitFormat
Creates a new format for the given locale.- Parameters:
locale- the locale to use for parsing and formatting units.
-
-
Method Details
-
getLocale
Returns the locale used by thisUnitFormat.- Specified by:
getLocalein interfaceLocalized- Returns:
- the locale of this
UnitFormat.
-
setLocale
Sets the locale that thisUnitFormatwill use for long names. For example, a call tosetLocale(Locale.US)instructs this formatter to use the “meter” spelling instead of “metre”.- Parameters:
locale- the new locale for thisUnitFormat.- See Also:
-
isLocaleSensitive
public boolean isLocaleSensitive()Returns whether thisUnitFormatdepends on theLocalegiven at construction time for performing its tasks. This method returnstrueif formatting long names (e.g. “metre” or “meter”} andfalseif formatting only the unit symbol (e.g. “m”).- Specified by:
isLocaleSensitivein interfaceUnitFormat- Returns:
trueif formatting depends on the locale.
-
getStyle
Returns whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.- Returns:
- the style of units formatted by this
UnitFormatinstance.
-
setStyle
Sets whether unit formatting should use ASCII symbols, Unicode symbols or full localized names.- Parameters:
style- the desired style of units.
-
label
Attaches a label to the specified unit. A label can be a substitute to either the unit symbol or theunit 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. The set of legal characters may be expanded in future Apache SIS versions, but 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 cannot begin or end with digits, since such digits would be confused with unit power.
- Specified by:
labelin interfaceUnitFormat- Parameters:
unit- the unit being labeled.label- the new label for the given unit.- Throws:
IllegalArgumentException- if the given label is not a valid unit name.
- The following characters are reserved since they have special meaning in UCUM format, in URI
or in Apache SIS parser:
-
format
Formats the specified unit. This method performs the first of the following actions that can be done.- If a label has been specified for the given unit, then that label is appended unconditionally.
- Otherwise if the formatting style is
UnitFormat.Style.NAMEand theUnit.getName()method returns a non-null value, then that value is appended.Unitinstances implemented by Apache SIS are handled in a special way for localizing the name according the locale specified to this format. - Otherwise if the
Unit.getSymbol()method returns a non-null value, then that value is appended. - Otherwise a default symbol is created from the entries returned by
Unit.getBaseUnits().
- Specified by:
formatin interfaceUnitFormat- Parameters:
unit- the unit to format.toAppendTo- where to format the unit.- Returns:
- the given
toAppendToargument, for method calls chaining. - Throws:
IOException- if an error occurred while writing to the destination.
-
format
Formats the specified unit in the given buffer. This method delegates toformat(Unit, Appendable). -
format
Formats the given unit. This method delegates toformat(Unit, Appendable).- Specified by:
formatin interfaceUnitFormat- Parameters:
unit- the unit to format.- Returns:
- the formatted unit.
-
parse
Parses the given text as an instance ofUnit. 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²”.This method differs from
parse(CharSequence, ParsePosition)in the treatment of white spaces: that method with aParsePositionargument stops parsing at the first white space, while thisparse(…)method treats white spaces as multiplications. The reason for this difference is that white space is normally not a valid multiplication symbol; it could be followed by a text which is not part of the unit symbol. But in the case of thisparse(CharSequence)method, the wholeCharSequenceshall be a unit symbol. In such case, white spaces are less ambiguous.The default implementation delegates to
parse(symbols, new ParsePosition(0))and verifies that all non-white characters have been parsed. Units separated by spaces are multiplied; for example "kg m**-2" is parsed as kg/m².- Specified by:
parsein interfaceUnitFormat- Parameters:
symbols- the unit symbols or URI to parse.- Returns:
- the unit parsed from the specified symbols.
- Throws:
MeasurementParseException- if a problem occurred while parsing the given symbols.- See Also:
-
parse
Parses a portion of the given text as an instance ofUnit. Parsing begins at the index given byParsePosition.getIndex(). 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
parseObject(String, ParsePosition), this method never returnnull. If an error occurs at parsing time, an uncheckedMeasurementParseExceptionis thrown.- Specified by:
parsein interfaceUnitFormat- 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:
MeasurementParseException- if a problem occurred while parsing the given symbols.
-
parseObject
Parses text from a string to produce a unit. The default implementation delegates toparse(CharSequence)and wraps theMeasurementParseExceptioninto aParseExceptionfor compatibility withjava.textAPI.- Overrides:
parseObjectin classFormat- Parameters:
source- the text, part of which should be parsed.- Returns:
- a unit parsed from the string.
- Throws:
ParseException- if the given string cannot be fully parsed.
-
parseObject
Parses text from a string to produce a unit, or returnsnullif the parsing failed. The default implementation delegates toparse(CharSequence, ParsePosition)and catches theMeasurementParseException.- Specified by:
parseObjectin classFormat- 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
nullin case of error.
-
clone
-