org.apache.sis.geometry

Class CoordinateFormat

Object

Format

CompoundFormat<DirectPosition>

CoordinateFormat

All Implemented Interfaces:

Serializable, Cloneable, Localized

public class CoordinateFormat
extends CompoundFormat<DirectPosition>

Formats spatiotemporal coordinates using number, angle and date formats inferred from the coordinate system. The format for each ordinate is inferred from the coordinate system units using the following rules:

• Ordinate values in angular units are formated as angles using Angle­Format.
• Ordinate values in temporal units are formated as dates using Date­Format.
• Other values are formatted as numbers using Number­Format followed by the unit symbol formatted by Unit­Format.

The format can be controlled by invoking the apply­Pattern(Class, String) public method, or by overriding the Compound­Format.create­Format(Class) protected method.

This format does not transform the given coordinates in a unique CRS. If the coordinates need to be formatted in a specific CRS, then the caller should transform the position before to format it.

Since:

0.8

See Also:

Angle­Format, Unit­Format, General­Direct­Position, Serialized Form

Defined in the sis-referencing module

Nested Class Summary

Nested classes/interfaces inherited from class Format

Format.Field

Constructor Summary

Constructors

Constructor and Description
CoordinateFormat() Constructs a new coordinate format with default locale and timezone.
CoordinateFormat(Locale locale, TimeZone timezone) Constructs a new coordinate format for the specified locale and timezone.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	applyPattern(Class<?> valueType, String pattern) Sets the pattern for number, angle or date fields.
CoordinateFormat	clone() Returns a clone of this format.
String	format(DirectPosition position) Formats the given coordinate.
void	format(DirectPosition position, Appendable toAppendTo) Formats the given coordinate and appends the resulting text to the given stream or buffer.
CoordinateReferenceSystem	getDefaultCRS() Returns the coordinate reference system to use if no CRS is explicitely associated to a given Direct­Position.
String	getPattern(Class<?> valueType) Returns the pattern for number, angle or date fields.
String	getSeparator() Returns the separator between each coordinate (number, angle or date).
Class<DirectPosition>	getValueType() Returns the base type of values parsed and formatted by this Format instance.
DirectPosition	parse(CharSequence text, ParsePosition pos) Parses a coordinate from the given character sequence.
void	setDefaultCRS(CoordinateReferenceSystem crs) Sets the coordinate reference system to use if no CRS is explicitely associated to a given Direct­Position.
void	setSeparator(String separator) Sets the separator between each coordinate.

Methods inherited from class CompoundFormat

create­Format, format, get­Format, get­Locale, get­Locale, get­Time­Zone, parse­Object, parse­Object

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

CoordinateFormat

public CoordinateFormat()

Constructs a new coordinate format with default locale and timezone.

CoordinateFormat

public CoordinateFormat(Locale locale,
                TimeZone timezone)

Constructs a new coordinate format for the specified locale and timezone.

Parameters:

locale - the locale for the new Format, or null for Locale.ROOT.

timezone - the timezone, or null for UTC.

Method Detail

getSeparator

public String getSeparator()

Returns the separator between each coordinate (number, angle or date). The default value is a single space.

Returns:

the current coordinate separator.

setSeparator

public void setSeparator(String separator)

Sets the separator between each coordinate. The default value is a single space.

Parameters:

separator - the new coordinate separator.

getDefaultCRS

public CoordinateReferenceSystem getDefaultCRS()

Returns the coordinate reference system to use if no CRS is explicitely associated to a given Direct­Position.

Returns:

the default coordinate reference system, or null if none.

setDefaultCRS

public void setDefaultCRS(CoordinateReferenceSystem crs)

Sets the coordinate reference system to use if no CRS is explicitely associated to a given Direct­Position. This CRS is only a default; positions given in another CRS are not automatically transformed to that CRS before formatting.

Parameters:

crs - the default coordinate reference system, or null if none.

getPattern

public String getPattern(Class<?> valueType)

Returns the pattern for number, angle or date fields. The given value­Type should be Number.class, Angle.class, Date.class or a sub-type of the above. This method may return null if the underlying format can not provide a pattern.

Pattern availability for type of value

Value type	Base format class	Format with pattern
Number	NumberFormat	DecimalFormat
Angle	AngleFormat	AngleFormat
Date	DateFormat	SimpleDateFormat

Parameters:

value­Type - the base type of ordinate values to parse and format: Number.class, Angle.class or Date.class.

Returns:

the pattern for fields of the given type, or null if not applicable.

See Also:

Compound­Format.get­Format(Class)

applyPattern

public boolean applyPattern(Class<?> valueType,
                   String pattern)

Sets the pattern for number, angle or date fields. The pattern syntax depends on the value­Type argument:

• If value­Type is Number.class, then the pattern syntax shall be as described in the Decimal­Format class. This pattern may be used for any ordinate to be formatted as plain number, for example in Cartesian coordinate system.
• If value­Type is Angle.class, then the pattern syntax shall be as described in the Angle­Format class. This pattern may be used for any ordinate to be formatted as latitude or longitude, for example in ellipsoidal coordinate system.
• If value­Type is Date.class, then the pattern syntax shall be as described in the Simple­Date­Format class. This pattern may be used for any ordinate to be formatted as date and time, for example in time coordinate system.

Parameters:

value­Type - the base type of ordinate values to parse and format: Number.class, Angle.class or Date.class.

pattern - the pattern as specified in Decimal­Format, Angle­Format or Simple­Date­Format javadoc.

Returns:

true if the pattern has been applied, or false if value­Type does not specify a known type or if the format associated to that type does not support patterns.

Throws:

Illegal­Argument­Exception - if the given pattern is invalid.

getValueType

public final Class<DirectPosition> getValueType()

Returns the base type of values parsed and formatted by this Format instance.

Specified by:

get­Value­Type in class Compound­Format<Direct­Position>

Returns:

Direct­Position.class.

format

public String format(DirectPosition position)

Formats the given coordinate.

Parameters:

position - the coordinate to format.

Returns:

the formatted position.

format

public void format(DirectPosition position,
          Appendable toAppendTo)
            throws IOException

Formats the given coordinate and appends the resulting text to the given stream or buffer.

Specified by:

format in class Compound­Format<Direct­Position>

Parameters:

position - the coordinate to format.

to­Append­To - where the text is to be appended.

Throws:

IOException - if an error occurred while writing to the given appendable.

parse

public DirectPosition parse(CharSequence text,
                   ParsePosition pos)
                     throws ParseException

Parses a coordinate from the given character sequence. This method presumes that the coordinate reference system is the default CRS. The parsing begins at the index given by the pos argument. If parsing succeeds, then the pos index is updated to the index after the last ordinate value and the parsed coordinate is returned. Otherwise (if parsing fails), the pos index is left unchanged, the pos error index is set to the index of the first unparsable character and an exception is thrown with a similar error index.

Specified by:

parse in class Compound­Format<Direct­Position>

Parameters:

text - the character sequence for the coordinate to parse.

pos - the index where to start the parsing.

Returns:

the parsed coordinate (never null).

Throws:

Parse­Exception - if an error occurred while parsing the coordinate.

clone

public CoordinateFormat clone()

Returns a clone of this format.

Overrides:

clone in class Compound­Format<Direct­Position>

Returns:

a clone of this format.