Package org.apache.sis.referencing.gazetteer

## Class LocationFormat

- Object
- - Format
  - - CompoundFormat<T>
    - - TabularFormat<AbstractLocation>
      - - LocationFormat

- All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Localized`

      public class LocationFormat
      extends TabularFormat<AbstractLocation>

  Formats `Location` instances in a tabular format. This format assumes a monospaced font and an encoding supporting drawing box characters (e.g. UTF-8).
  Example: the location identified by "32TNL83" in the military grid reference system can be represented by the following string formatted using `Locale​.ENGLISH`:

  >     ┌─────────────────────────────────────────────────────────────┐
  >     │ Location type:               Grid zone designator           │
  >     │ Geographic identifier:       32TNL83                        │
  >     │ West bound:                    580,000 m    —     9°57′00″E │
  >     │ Representative value:          585,000 m    —    10°00′36″E │
  >     │ East bound:                    590,000 m    —    10°04′13″E │
  >     │ South bound:                 4,530,000 m    —    40°54′58″N │
  >     │ Representative value:        4,535,000 m    —    40°57′42″N │
  >     │ North bound:                 4,540,000 m    —    41°00′27″N │
  >     │ Coordinate reference system: WGS 84 / UTM zone 32N          │
  >     └─────────────────────────────────────────────────────────────┘

  Limitations:

  - The current implementation can only format features — parsing is not yet implemented.
  - `LocationFormat`, like most `java​.text​.Format` subclasses, is not thread-safe.
  Since:
    0.8
  See Also:
    Serialized Form

  Defined in the `sis-referencing-by-identifiers` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class Format

      `Format​.Field`

  - ### Field Summary

    - ### Fields inherited from class TabularFormat

      `beforeFill, columnSeparator, fillCharacter, lineSeparator, omitTrailingNulls`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `LocationFormat​(Locale locale, TimeZone timezone)` | Creates a new format for the given locale.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `LocationFormat` | `clone()` | Returns a clone of this format.
    `protected Format` | `createFormat​(Class<?> valueType)` | Creates the format to use for formatting a latitude, longitude or projected coordinate.
    `void` | `format​(AbstractLocation location, Appendable toAppendTo)` | Writes a textual representation of the given location in the given stream or buffer.
    `Class<AbstractLocation>` | `getValueType()` | Returns the type of values formatted by this `Format` instance.
    `AbstractLocation` | `parse​(CharSequence text, ParsePosition pos)` | Unsupported operation.

    - ### Methods inherited from class TabularFormat

      `getColumnSeparatorMatcher, getColumnSeparatorPattern, getLineSeparator, setColumnSeparatorPattern, setLineSeparator`

    - ### Methods inherited from class CompoundFormat

      `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

    - #### LocationFormat

          public LocationFormat​(Locale locale,
                                TimeZone timezone)

      Creates a new format for the given locale. The given locale can be `null` or `Locale​.ROOT` if this format shall format "unlocalized" strings.
      Parameters:
        `locale` - the locale for the new `Format`, or `null` for `Locale​.ROOT`.
        `timezone` - the timezone, or `null` for UTC.

  - ### Method Detail

    - #### getValueType

          public Class<AbstractLocation> getValueType()

      Returns the type of values formatted by this `Format` instance.
      Specified by:
        `getValueType` in class `CompoundFormat<AbstractLocation>`
      Returns:
        the type of values formatted by this `Format` instance.

    - #### format

          public void format​(AbstractLocation location,
                             Appendable toAppendTo)
                      throws IOException

      Writes a textual representation of the given location in the given stream or buffer.
      Upcoming API change — generalization
      in a future SIS version, the type of `location` parameter may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
      Specified by:
        `format` in class `CompoundFormat<AbstractLocation>`
      Parameters:
        `location` - the location to format.
        `toAppendTo` - where to format the location.
      Throws:
        `IOException` - if an error occurred while writing to the given appendable.

    - #### createFormat

          protected Format createFormat​(Class<?> valueType)

      Creates the format to use for formatting a latitude, longitude or projected coordinate. This method is invoked by `format(Location, Appendable)` when first needed.
      Overrides:
        `createFormat` in class `CompoundFormat<AbstractLocation>`
      Parameters:
        `valueType` - `Angle​.class`. `Number​.class` or `Unit​.class`.
      Returns:
        a new `AngleFormat`, `NumberFormat` or `UnitFormat` instance depending on the argument value.

    - #### parse

          public AbstractLocation parse​(CharSequence text,
                                        ParsePosition pos)
                                 throws ParseException

      Unsupported operation.
      Specified by:
        `parse` in class `CompoundFormat<AbstractLocation>`
      Parameters:
        `text` - the character sequence for the location to parse.
        `pos` - the position where to start the parsing.
      Returns:
        the parsed location, or `null` if the text is not recognized.
      Throws:
        `ParseException` - if an error occurred while parsing the location.

    - #### clone

          public LocationFormat clone()

      Returns a clone of this format.
      Overrides:
        `clone` in class `TabularFormat<AbstractLocation>`
      Returns:
        a clone of this format.