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 `AngleFormat`.
  - Ordinate values in temporal units are formated as dates using `DateFormat`.
  - Other values are formatted as numbers using `NumberFormat` followed by the unit symbol formatted by `UnitFormat`.
  The format can be controlled by invoking the `applyPattern(Class, String)` public method, or by overriding the `CompoundFormat​.createFormat(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:
    `AngleFormat`, `UnitFormat`, `GeneralDirectPosition`, 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

    All Methods Instance Methods Concrete 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 `DirectPosition`.
    `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 `DirectPosition`.
    `void` | `setSeparator(String separator)` Sets the separator between each coordinate.

    - ### Methods inherited from class CompoundFormat

      `createFormat, format, getFormat, getLocale, getLocale, getTimeZone, parseObject, parseObject`

    - ### Methods inherited from class Format

      `format, formatToCharacterIterator`

    - ### Methods inherited from class Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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 `DirectPosition`.
      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 `DirectPosition`. 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 `valueType` 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:
        `valueType` - 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:
        `CompoundFormat​.getFormat(Class)`

    - #### applyPattern

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

      Sets the pattern for number, angle or date fields. The pattern syntax depends on the `valueType` argument:
      - If `valueType` is `Number​.class`, then the pattern syntax shall be as described in the `DecimalFormat` class. This pattern may be used for any ordinate to be formatted as plain number, for example in Cartesian coordinate system.
      - If `valueType` is `Angle​.class`, then the pattern syntax shall be as described in the `AngleFormat` class. This pattern may be used for any ordinate to be formatted as latitude or longitude, for example in ellipsoidal coordinate system.
      - If `valueType` is `Date​.class`, then the pattern syntax shall be as described in the `SimpleDateFormat` class. This pattern may be used for any ordinate to be formatted as date and time, for example in time coordinate system.
      Parameters:
        `valueType` - the base type of ordinate values to parse and format: `Number​.class`, `Angle​.class` or `Date​.class`.
        `pattern` - the pattern as specified in `DecimalFormat`, `AngleFormat` or `SimpleDateFormat` javadoc.
      Returns:
        `true` if the pattern has been applied, or `false` if `valueType` does not specify a known type or if the format associated to that type does not support patterns.
      Throws:
        `IllegalArgumentException` - 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:
        `getValueType` in class `CompoundFormat<DirectPosition>`
      Returns:
        `DirectPosition​.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 `CompoundFormat<DirectPosition>`
      Parameters:
        `position` - the coordinate to format.
        `toAppendTo` - 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 `CompoundFormat<DirectPosition>`
      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:
        `ParseException` - if an error occurred while parsing the coordinate.

    - #### clone

          public CoordinateFormat clone()

      Returns a clone of this format.
      Overrides:
        `clone` in class `CompoundFormat<DirectPosition>`
      Returns:
        a clone of this format.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.