# Class MilitaryGridReferenceSystem.Coder

Object
ReferencingByIdentifiers.Coder
Coder

Enclosing class:
  `MilitaryGridReferenceSystem`

public class MilitaryGridReferenceSystem.Coder extends ReferencingByIdentifiers.Coder
Conversions between direct positions and references in the Military Grid Reference System (MGRS). Each `Coder` instance can read references at arbitrary precision, but formats at the specified precision. The same `Coder` instance can be reused for reading or writing many MGRS references.

See the `MilitaryGridReferenceSystem` enclosing class for usage example.

## 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 coder initialized to the default precision and separator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AbstractLocation`
  `decode(CharSequence reference)`
  Decodes the given MGRS reference into a position and an envelope.
  `String`
  `encode(DirectPosition position)`
  Encodes the given position into a MGRS reference.
  `String`
  `encode(DirectPosition position, Quantity<?> precision)`
  Encodes the given position into a MGRS reference with the given precision.
  `Iterator<String>`
  `encode(Envelope areaOfInterest)`
  Returns an iterator over all MGRS references that intersect the given envelope.
  `Stream<String>`
  `encode(Envelope areaOfInterest, boolean parallel)`
  Returns a stream of all MGRS references that intersect the given envelope.
  `boolean`
  `getClipToValidArea()`
  Returns whether the decoded locations should be clipped to the valid area.
  `double`
  `getPrecision()`
  Returns the precision of the references formatted by this coder.
  `Quantity<Length>`
  `getPrecision(DirectPosition position)`
  Returns the precision of the references formatted by this coder.
  `final MilitaryGridReferenceSystem`
  `getReferenceSystem()`
  Returns the reference system for which MGRS references will be encoded or decoded.
  `String`
  `getSeparator()`
  Returns the separator to insert between each component of the MGRS identifier.
  `void`
  `setClipToValidArea(boolean clip)`
  Sets whether the decoded locations should be clipped to the valid area.
  `void`
  `setPrecision(double precision)`
  Sets the desired precision of the references formatted by this coder.
  `void`
  `setPrecision(Quantity<?> precision, DirectPosition position)`
  Sets the desired precision of the references formatted by this coder.
  `void`
  `setSeparator(String separator)`
  Sets the separator to insert between each component of the MGRS identifier.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### Coder

    protected Coder()
    Creates a new coder initialized to the default precision and separator.

- ## Method Details

  - ### getReferenceSystem

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

  - ### getPrecision

    public double getPrecision()
    Returns the precision of the references formatted by this coder. This method returns one of the following values:

    MGRS reference precisions
    Precision (m) | Reference example
    --- | ---
    1 | 4 Q FJ 12345 67890
    10 | 4 Q FJ 1234 6789
    100 | 4 Q FJ 123 678
    1000 | 4 Q FJ 12 67
    10 000 | 4 Q FJ 1 6
    100 000 | 4 Q FJ
    (approximated) 1 000 000 | 4 Q

    Values smaller than 1 (e.g. 0.01 for a centimetre precision) may also be returned if that value has been explicitly set, but sub-metric precision are usually not used with MGRS.
    Returns:
      precision of formatted references in metres.

  - ### setPrecision

    public void setPrecision(double precision)
    Sets the desired precision of the references formatted by this coder. This method rounds the given precision to one of the power of 10 documented in the `getPrecision()` method.
    Parameters:
      `precision` - the desired precision in metres.
    Throws:
      `ArithmeticException` - if the given precision is zero, negative, infinity or NaN.

  - ### getPrecision

    public Quantity<Length> getPrecision(DirectPosition position)
    Returns the precision of the references formatted by this coder. This method returns the same value as `getPrecision()` but as a quantity.
    Specified by:
      `getPrecision` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `position` - ignored (can be null).
    Returns:
      precision of formatted references in metres.
    Since:
      1.3

  - ### setPrecision

    public void setPrecision(Quantity<?> precision, DirectPosition position) throws IncommensurableException
    Sets the desired precision of the references formatted by this coder. If the given quantity uses angular units, it is converted to an approximate precision in metres at the latitude of given position. Then this method delegates to `setPrecision(double)`.
    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.
      `ArithmeticException` - if the precision is zero, negative, infinity or NaN.
    Since:
      1.3

  - ### getSeparator

    public String getSeparator()
    Returns the separator to insert between each component of the MGRS identifier. Components are zone number, latitude band, 100 000-metres square identifier and numerical values. By default the separator is an empty string, which produce references like "4QFJ12345678".
    Returns:
      the separator to insert between each component of the MGRS identifier, or an empty string if none.

  - ### setSeparator

    public void setSeparator(String separator)
    Sets the separator to insert between each component of the MGRS identifier. Components are zone number, latitude band, 100 000-metres square identifier and numerical values. By default the separator is an empty string, which produce references like "4QFJ12345678". If the separator is set to a space, then the references will be formatted like "4 Q FJ 1234 5678".

    Note that a MGRS reference is normally written as an entity without spaces, parentheses, dashes, or decimal points. Invoking this method with a non-empty separator produces non-conform MGRS, but is sometimes convenient for readability or for use in file systems (with the `'/'` separator).

    Parameters:
      `separator` - the separator to insert between each component of the MGRS identifier.

  - ### getClipToValidArea

    public boolean getClipToValidArea()
    Returns whether the decoded locations should be clipped to the valid area. The default value is `true`.
    Returns:
      `true` if decoded locations are clipped to the valid area.

  - ### setClipToValidArea

    public void setClipToValidArea(boolean clip)
    Sets whether the decoded locations should be clipped to the valid area. MGRS 100 km squares can actually be smaller than 100 km when the square overlaps two UTM zones or two latitude bands. We may have half of a square in a zone and the other half in the other zone. By default, the `decode(CharSequence)` method clips the square to the zone where it belongs. Invoking this method with the `false` value disables this behavior.
    Parameters:
      `clip` - whether the decoded locations should be clipped to the valid area.

  - ### encode

    public String encode(DirectPosition position) throws TransformException
    Encodes the given position into a MGRS reference. The given position must have a Coordinate Reference System (CRS) associated to it.
    Specified by:
      `encode` in class `ReferencingByIdentifiers​.Coder`
    Parameters:
      `position` - the coordinate to encode.
    Returns:
      MGRS encoding of the given position.
    Throws:
      `TransformException` - if an error occurred while transforming the given coordinate to a MGRS reference.

  - ### encode

    public String encode(DirectPosition position, Quantity<?> precision) throws IncommensurableException, TransformException
    Encodes the given position into a MGRS reference 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:
      MGRS encoding of the given position.
    Throws:
      `ArithmeticException` - if the precision is zero, negative, infinity or NaN.
      `IncommensurableException` - if the given precision does not use linear or angular units.
      `TransformException` - if an error occurred while transforming the given coordinate to a MGRS reference.
    Since:
      1.3

  - ### encode

    public Iterator<String> encode(Envelope areaOfInterest) throws TransformException
    Returns an iterator over all MGRS references that intersect the given envelope. The given envelope must have a Coordinate Reference System (CRS) associated to it. If the CRS is geographic, the envelope is allowed to span the anti-meridian. The MGRS references may be returned in any iteration order.

    #### Possible future evolution

    Current implementation does not clip the cells to UPS/UTM valid areas before to test for intersection with `areaOfInterest`. Consequently, the iterator may return slightly more cells than expected. A future version may filter the cells more accurately. If an application needs the same set of cells than what current the implementation returns, it can invoke `setClipToValidArea(false)` for preserving current behavior in future Apache SIS versions.
    Parameters:
      `areaOfInterest` - envelope of desired MGRS references.
    Returns:
      an iterator over MGRS references intersecting the given area of interest.
    Throws:
      `TransformException` - if an error occurred while transforming the area of interest.

  - ### encode

    public Stream<String> encode(Envelope areaOfInterest, boolean parallel) throws TransformException
    Returns a stream of all MGRS references that intersect the given envelope. The given envelope must have a Coordinate Reference System (CRS) associated to it. If the CRS is geographic, the envelope is allowed to span the anti-meridian. The MGRS references may be returned in any order.

    #### Possible future evolution

    Current implementation does not clip the cells to UPS/UTM valid areas before to test for intersection with `areaOfInterest`. Consequently, the iterator may return slightly more cells than expected. A future version may filter the cells more accurately. If an application needs the same set of cells than what current the implementation returns, it can invoke `setClipToValidArea(false)` for preserving current behavior in future Apache SIS versions.
    Parameters:
      `areaOfInterest` - envelope of desired MGRS references.
      `parallel` - `true` for a parallel stream, or `false` for a sequential stream.
    Returns:
      a stream of MGRS references intersecting the given area of interest.
    Throws:
      `TransformException` - if an error occurred while transforming the area of interest.

  - ### decode

    public AbstractLocation decode(CharSequence reference) throws TransformException
    Decodes the given MGRS reference into a position and an envelope. The Coordinate Reference System (CRS) associated to the returned position depends on the given reference.
    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:
      `reference` - MGRS string to decode.
    Returns:
      a new position with the longitude at coordinate 0 and latitude at coordinate 1.
    Throws:
      `TransformException` - if an error occurred while parsing the given string.