com.luciad.text.gars

Defense SymbologyClass 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

GARS	Lon lat	Precision	Format string
403AA37	21.04166..., -89.95833..	KEYPAD	X3YQK
403AA3	21.125, -89.875	QUADRANT	X3YQ
403AA	21.25, -89.75	CELL	X3Y

Since:

2020.1

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TLcdGARSFormat.Precision The precision of the formatted GARS coordinate strings.

Nested classes/interfaces inherited from class java.text.Format

Format.Field

Constructor Summary

Constructors

Constructor and Description
TLcdGARSFormat() Creates a new TLcdGARSFormat that uses a default precision of TLcdGARSFormat.Precision.KEYPAD (5-minute by 5-minute grid) to format an ILcdPoint.
TLcdGARSFormat(String aFormat) Creates a new TLcdGARSFormat that uses the given format to format an ILcdPoint.
TLcdGARSFormat(TLcdGARSFormat.Precision aPrecision) Creates a new TLcdGARSFormat that uses the given precision to format an ILcdPoint.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object aO)
StringBuffer	format(Object aObject, StringBuffer aToAppendTo, FieldPosition aPosition) Formats an ILcdPoint and appends the resulting text to a given string buffer.
String	getPattern() Returns the GARS pattern used as described in TLcdGARSFormat(java.lang.String).
TLcdGARSFormat.Precision	getPrecision() Returns the precision when formatting points as GARS coordinate strings.
int	hashCode()
ILcdPoint	parse(String aString) Parses a given String and creates a new ILcdPoint with WGS84 longitude latitude coordinates.
ILcdPoint	parseObject(String aSource, ParsePosition aPosition) Parses text from a GARS coordinate string to produce an ILcdPoint with WGS84 longitude latitude coordinates.
void	setPrecision(TLcdGARSFormat.Precision aPrecision) Sets the precision when formatting points as GARS coordinate strings.
String	toString()

Methods inherited from class java.text.Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.luciad.util.ILcdFormatter

format

Constructor Detail

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

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

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 Detail

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:

ParsePosition

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