Package 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 coordinate is inferred from the coordinate system units using the following rules:
  - Coordinate values in angular units are formatted as angles using `AngleFormat`.
  - Coordinate values in temporal units are formatted 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 | 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 | 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 explicitly 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 explicitly associated to a given `DirectPosition`.
    `void` | `setPrecision​(double resolution, Unit<?> unit)` | Adjusts the number of fraction digits to show in coordinates for achieving the given precision.
    `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 explicitly 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 explicitly 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.

    - #### setPrecision

          public void setPrecision​(double resolution,
                                   Unit<?> unit)

      Adjusts the number of fraction digits to show in coordinates for achieving the given precision. The `NumberFormat` and `AngleFormat` are configured for coordinates expressed in the default coordinate reference system defined at the moment this method is invoked. The number of fraction digits is not updated if a different CRS is specified after this method call or if the coordinates to format are associated to a different CRS.

      The given resolution will be converted to the units used by coordinate system axes. For example if a 10 metres resolution is specified but the default CRS axes use kilometres, then this method converts the resolution to 0.01 kilometre and uses that value for inferring that coordinates should be formatted with 2 fraction digits. If the resolution is specified in an angular units such as degrees, this method uses the ellipsoid authalic radius for computing an equivalent resolution in linear units. For example if the ellipsoid of default CRS is WGS84, then this method considers a resolution of 1 second of angle as equivalent to a resolution of about 31 meters. Conversions work also in the opposite direction (from linear to angular units) and are also used for choosing which angle fields (degrees, minutes or seconds) to show.

      Parameters:
        `resolution` - the desired resolution.
        `unit` - unit of the desired resolution.
      Since:
        1.0
      See Also:
        `NumberFormat​.setMaximumFractionDigits(int)`, `AngleFormat​.setPrecision(double, boolean)`

    - #### 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 coordinate 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 coordinate 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 coordinate 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 coordinate to be formatted as date and time, for example in time coordinate system.
      Parameters:
        `valueType` - the base type of coordinate 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 coordinate 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.