Class UnitFormat
- 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:
Defined in the sis-utility module
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic enumIdentify whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.Nested classes/interfaces inherited from class FormatFormat.Field
- 
Constructor SummaryConstructors
- 
Method SummaryModifier 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 Formatformat, formatToCharacterIterator
- 
Constructor Details- 
UnitFormatCreates a new format for the given locale.- Parameters:
- locale- the locale to use for parsing and formatting units.
 
 
- 
- 
Method Details- 
getLocaleReturns the locale used by thisUnitFormat.- Specified by:
- getLocalein interface- Localized
- Returns:
- the locale of this UnitFormat.
 
- 
setLocaleSets 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 this- UnitFormat.
- See Also:
 
- 
isLocaleSensitivepublic 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 interface- UnitFormat
- Returns:
- trueif formatting depends on the locale.
 
- 
getStyleReturns whether unit formatting uses ASCII symbols, Unicode symbols or full localized names.- Returns:
- the style of units formatted by this UnitFormatinstance.
 
- 
setStyleSets whether unit formatting should use ASCII symbols, Unicode symbols or full localized names.- Parameters:
- style- the desired style of units.
 
- 
labelAttaches 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 setCurrent 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 interface- UnitFormat
- 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: 
- 
formatFormats 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 interface- UnitFormat
- 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.
 
- 
formatFormats the specified unit in the given buffer. This method delegates toformat(Unit, Appendable).
- 
formatFormats the given unit. This method delegates toformat(Unit, Appendable).- Specified by:
- formatin interface- UnitFormat
- Parameters:
- unit- the unit to format.
- Returns:
- the formatted unit.
 
- 
parseParses 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 interface- UnitFormat
- Parameters:
- symbols- the unit symbols or URI to parse.
- Returns:
- the unit parsed from the specified symbols.
- Throws:
- ParserException- if a problem occurred while parsing the given symbols.
- See Also:
 
- 
parseParses 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 uncheckedParserExceptionis 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:
- ParserException- if a problem occurred while parsing the given symbols.
 
- 
parseObjectParses text from a string to produce a unit. The default implementation delegates toparse(CharSequence)and wraps theParserExceptioninto aParseExceptionfor compatibility withjava.textAPI.- Overrides:
- parseObjectin class- Format
- 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.
 
- 
parseObjectParses text from a string to produce a unit, or returnsnullif the parsing failed. The default implementation delegates toparse(CharSequence, ParsePosition)and catches theParserException.- Specified by:
- parseObjectin 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 nullin case of error.
 
- 
clone
 
-