# Class GeohashReferenceSystem.Coder

Object
ReferencingByIdentifiers.Coder
Coder

Enclosing class:
  `GeohashReferenceSystem`

public class GeohashReferenceSystem.Coder extends ReferencingByIdentifiers.Coder
Conversions between direct positions and geohashes. Each `Coder` instance can read codes at arbitrary precision, but formats at the specified precision. The same `Coder` instance can be reused for reading or writing many geohashes.

## Immutability and thread safety

This class is not thread-safe. A new instance must be created for each thread, or synchronization must be applied by the caller.

Since:
  0.8

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Coder()`
  Creates a new geohash coder/decoder initialized to the default precision.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AbstractLocation`
  `decode(CharSequence geohash)`
  Decodes the given geohash into a latitude and a longitude.
  `String`
  `encode(double φ, double λ)`
  Encodes the given latitude and longitude into a geohash.
  `String`
  `encode(DirectPosition position)`
  Encodes the given position into a geohash.
  `String`
  `encode(DirectPosition position, Quantity<?> precision)`
  Encodes the given position into a geohash with the given precision.
  `int`
  `getHashLength()`
  Returns the length of geohashes strings to be encoded by the `encode(DirectPosition)` method.
  `Quantity<Length>`
  `getPrecision(DirectPosition position)`
  Returns an approximate precision of the geohashes formatted by this coder.
  `final GeohashReferenceSystem`
  `getReferenceSystem()`
  Returns the reference system for which GeoHash identifiers will be encoded or decoded.
  `void`
  `setHashLength(int length)`
  Sets the length of geohashes strings to be encoded by the `encode(DirectPosition)` method.
  `void`
  `setPrecision(Quantity<?> precision, DirectPosition position)`
  Sets the desired precision of the identifiers formatted by this coder.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Coder

    protected Coder()
    Creates a new geohash coder/decoder initialized to the default precision.

- ## Method Details

  - ### getReferenceSystem

    public final GeohashReferenceSystem getReferenceSystem()
    Returns the reference system for which GeoHash identifiers will be encoded or decoded.
    Specified by:
      `getReferenceSystem` in class `ReferencingByIdentifiers​.Coder`
    Returns:
      the enclosing reference system.
    Since:
      1.3

  - ### getHashLength

    public int getHashLength()
    Returns the length of geohashes strings to be encoded by the `encode(DirectPosition)` method. The default value for `GeohashReferenceSystem​.Format​.BASE32` is 12.
    Returns:
      the length of geohashes strings.

  - ### setHashLength

    public void setHashLength(int length)
    Sets the length of geohashes strings to be encoded by the `encode(DirectPosition)` method.
    Parameters:
      `length` - the new length of geohashes strings.

  - ### getPrecision

    public Quantity<Length> getPrecision(DirectPosition position)
    Returns an approximate precision of the geohashes formatted by this coder. Values are in units of ellipsoid axis length (typically metres). If the location is unspecified, then this method returns a value for the "worst case" scenario, which is at equator. The actual precision is sometimes (but not always) better for coordinates closer to a pole.
    Specified by:
      `getPrecision` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `position` - where to evaluate the precision, or `null` for equator.
    Returns:
      approximate precision of formatted geohashes.
    Since:
      1.3

  - ### setPrecision

    public void setPrecision(Quantity<?> precision, DirectPosition position) throws IncommensurableException
    Sets the desired precision of the identifiers formatted by this coder. The given value is converted to a string length.
    Specified by:
      `setPrecision` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `precision` - the desired precision in a linear or angular unit.
      `position` - location where the specified precision is desired, or `null` for the equator.
    Throws:
      `IncommensurableException` - if the given precision does not use linear or angular units.
    Since:
      1.3

  - ### encode

    public String encode(double φ, double λ) throws TransformException
    Encodes the given latitude and longitude into a geohash. This method does not take in account the axis order and units of the coordinate reference system (CRS) given to the `GeohashReferenceSystem` constructor. For geohashing of coordinates in different CRS, use `encode(DirectPosition)` instead.
    Parameters:
      `φ` - latitude to encode, as decimal degrees in the [-90 … 90]° range.
      `λ` - longitude to encode, as decimal degrees in the [-180 … 180]° range.
    Returns:
      geohash encoding of the given longitude and latitude.
    Throws:
      `TransformException` - if an error occurred while formatting the given coordinate.

  - ### encode

    public String encode(DirectPosition position) throws TransformException
    Encodes the given position into a geohash. The default implementation transforms the given position to the coordinate reference system expected by the enclosing `GeohashReferenceSystem`, then delegates to `encode(double, double)`.
    Specified by:
      `encode` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `position` - the coordinate to encode.
    Returns:
      geohash encoding of the given position.
    Throws:
      `TransformException` - if an error occurred while transforming the given coordinate to a geohash reference.

  - ### encode

    public String encode(DirectPosition position, Quantity<?> precision) throws IncommensurableException, TransformException
    Encodes the given position into a geohash with the given precision. This is equivalent to invoking `setPrecision(Quantity, DirectPosition)` before `encode(DirectPosition)`, except that it is potentially more efficient.
    Overrides:
      `encode` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `position` - the coordinate to encode.
      `precision` - the desired precision in a linear or angular unit.
    Returns:
      geohash encoding of the given position.
    Throws:
      `IncommensurableException` - if the given precision does not use linear or angular units.
      `TransformException` - if an error occurred while transforming the given coordinate to a geohash reference.
    Since:
      1.3

  - ### decode

    public AbstractLocation decode(CharSequence geohash) throws TransformException
    Decodes the given geohash into a latitude and a longitude. The axis order depends on the coordinate reference system of the enclosing `GeohashReferenceSystem`.
    Upcoming API change — generalization
    in a future SIS version, the type of returned element may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
    Specified by:
      `decode` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `geohash` - geohash string to decode.
    Returns:
      a new geographic coordinate for the given geohash.
    Throws:
      `TransformException` - if an error occurred while parsing the given string.