Package org.apache.sis.referencing.gazetteer

## Class GeohashReferenceSystem.Coder

- Object
- - Coder

- Enclosing class:
    GeohashReferenceSystem

      public class GeohashReferenceSystem.Coder
      extends Object

  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

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

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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.
    `int` | `getHashLength()` | Returns the length of geohashes strings to be encoded by the `encode(DirectPosition)` method.
    `void` | `setHashLength​(int length)` | Sets the length of geohashes strings to be encoded by the `encode(DirectPosition)` method.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### Coder

          protected Coder()

      Creates a new geohash coder/decoder initialized to the default precision.

  - ### Method Detail

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

    - #### 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:
        `\u03c6` - latitude to encode, as decimal degrees in the [-90 … 90]° range.
        `\u03bb` - 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)`.
      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.

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