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

  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 Details

  - ### 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 Details

  - ### 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.