Package com.luciad.text.gars

Class TLcdGARSFormat

java.lang.Object
java.text.Format
com.luciad.text.gars.TLcdGARSFormat
All Implemented Interfaces:
ILcdFormatter, ILcdParser, Serializable, Cloneable
public class TLcdGARSFormat extends Format implements ILcdFormatter, ILcdParser
This class offers methods to format coordinates into Global Area Reference System (GARS) notation. This class also offers methods to parse a GARS coordinate string into a WGS84 longitude latitude ILcdPoint.

The formatting and parsing of GARS coordinate strings can be customized using a TLcdGARSFormat.Precision or a GARS format string. An example of a GARS coordinate string is 182QW37. This string consists of

  • 182: A number identifying the easting component of a 30 minutes square, starting at -180 degrees longitude.
  • QW: Letters identifying the northing component of a 30 minutes square, starting at -90 degrees latitude.
  • 3: One digit identifying a 15 minute square within this 30 minutes square.
  • 7: One digit identifying a 5 minute square within this 15 minutes square.

Examples

Formatting with precision

    ILcdPoint point = new TLcdLonLatPoint(21.036681004382054, -89.98288423774106);
    TLcdGARSFormat formatInstance = new TLcdGARSFormat(TLcdGARSFormat.Precision.KEYPAD);
    String format = formatInstance.format(point);

Formatting with format string

    ILcdPoint point = new TLcdLonLatPoint(21.036681004382054, -89.98288423774106);
    TLcdGARSFormat formatInstance = new TLcdGARSFormat("X3YQK");
    String format = formatInstance.format(point);

Parsing with precision

    TLcdGARSFormat format = new TLcdGARSFormat(TLcdGARSFormat.Precision.KEYPAD);
    ILcdPoint point = format.parse("403AA37");

Parsing with format string

    TLcdGARSFormat format = new TLcdGARSFormat("X3_Y_Q_K");
    ILcdPoint point = format.parse("403_AA_3_7");

Patterns

GARSLon latPrecisionFormat string
403AA3721.04166..., -89.95833..KEYPADX3YQK
403AA321.125, -89.875QUADRANTX3YQ
403AA21.25, -89.75CELLX3Y
Since:
2020.1
See Also:

  • Constructor Details

    • TLcdGARSFormat

      public TLcdGARSFormat()
      Creates a new TLcdGARSFormat that uses a default precision of TLcdGARSFormat.Precision.KEYPAD (5-minute by 5-minute grid) to format an ILcdPoint. Default constructor for TLcdGARSFormat.
      See Also:

    • TLcdGARSFormat

      public TLcdGARSFormat(TLcdGARSFormat.Precision aPrecision)
      Creates a new TLcdGARSFormat that uses the given precision to format an ILcdPoint.
      Parameters:
      aPrecision - a Precision as an argument, never null
      Throws:
      NullPointerException - if aPrecision is null.
      See Also:

    • TLcdGARSFormat

      public TLcdGARSFormat(String aFormat)
      Creates a new TLcdGARSFormat that uses the given format to format an ILcdPoint.

      The format should be expressed in EBNF notation (expressions enclosed in [] brackets are optional, expressions enclosed in {} brackets may be omitted or repeated): 

       <pattern>                       ::= <cellX> {<separator>} <cellY> [{<separator>} <quadrant>] [{<separator>} <keypad>]
 <cellX>                         ::= "X" | "X", <cellMinimumCharacterLength>
 <cellY>                         ::= "Y" | "Y", <cellMinimumCharacterLength>
 <quadrant>                      ::= "Q"
 <keypad>                        ::= "K"
 <cellMinimumCharacterLength>    ::= "2" | "3"
 <separator>                     ::= { ? any character ? }
      When the minimum character length is higher than the amount of actual characters, it will be padded with default characters. For X it will be padded with "0" (zero), for Y it will be padded with " " (space). When the minimum character length is lower than or equal to the amount of characters, the minimum character length has no effect. For example:
      • "340X15" has format "XYQK"
      • "182_ QW_7_2" has format "X3_Y3_K_Q"

      Parameters:
      aFormat - a format string, never null
      Throws:
      NullPointerException - if aFormat is null.
      Since:
      2021.1

  • Method Details

    • getPattern

      public String getPattern()
      Returns the GARS pattern used as described in TLcdGARSFormat(java.lang.String).
      Returns:
      the current GARS pattern in EBNF format
      Since:
      2021.1

    • getPrecision

      public TLcdGARSFormat.Precision getPrecision()
      Returns the precision when formatting points as GARS coordinate strings.

      For example, a precision value of TLcdGARSFormat.Precision.KEYPAD will output GARS coordinate strings representing a grid of 5-minute by 5-minute area on the map.

      Returns:
      the precision when formatting points as GARS coordinate strings

    • setPrecision

      public void setPrecision(TLcdGARSFormat.Precision aPrecision)
      Sets the precision when formatting points as GARS coordinate strings.

      For example, a precision value of TLcdGARSFormat.Precision.KEYPAD will output GARS coordinate strings representing a grid of 5-minute by 5-minute area on the map.

      Parameters:
      aPrecision - Precision for the GARS grid coordinate format, never null

    • format

      public StringBuffer format(Object aObject, StringBuffer aToAppendTo, FieldPosition aPosition)
      Formats an ILcdPoint and appends the resulting text to a given string buffer. If the aPosition argument identifies a field used by the format, its indices are set to the beginning and end of the first such field encountered.
      Specified by:
      format in class Format
      Parameters:
      aObject - The object to format. This should be an ILcdPoint.
      aToAppendTo - where the text is to be appended
      aPosition - A FieldPosition identifying a field in the formatted text
      Returns:
      the string buffer passed in as aToAppendTo, with formatted GARS Coordinate String appended
      Throws:
      NullPointerException - if aObject or aToAppendTo is null
      IllegalArgumentException - if the Format cannot format the given object

    • parse

      public ILcdPoint parse(String aString) throws IllegalArgumentException
      Parses a given String and creates a new ILcdPoint with WGS84 longitude latitude coordinates.
      Specified by:
      parse in interface ILcdParser
      Parameters:
      aString - the String representing a GARS coordinate to be parsed.
      Returns:
      an ILcdPoint
      Throws:
      IllegalArgumentException - if the String can't be parsed.

    • parseObject

      public ILcdPoint parseObject(String aSource, ParsePosition aPosition)
      Parses text from a GARS coordinate string to produce an ILcdPoint with WGS84 longitude latitude coordinates.

      The method attempts to parse a string representing a GARS coordinate, starting at the index given by aPosition. Parsing does not necessarily use all characters up to the end of the string. If parsing succeeds, the index of aPosition is updated to the index after the last character used, and the parsed object is returned. The updated aPosition can be used to indicate the starting point for the next call to this method. If an error occurs, the index of aPosition is not changed. The error index of aPosition is set to the index of the character where the error occurred, and null is returned.

      Specified by:
      parseObject in class Format
      Parameters:
      aSource - A String representing a GARS coordinate, part of which should be parsed.
      aPosition - A ParsePosition object with index and error index information as described above.
      Returns:
      an ILcdPoint parsed from the string. In case of error, returns null.
      Throws:
      NullPointerException - if aSource or aPosition is null.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object aO)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object