com.mapcode

Class Mapcode

java.lang.Object

com.mapcode.Mapcode

public final class Mapcode
extends Object

This class defines a single mapcode encoding result, including the alphanumeric code and the territory definition. On terminology, mapcode territory and mapcode code: In written form. a mapcode is defined as an alphanumeric code, optionally preceded by a territory code. For example: "NLD 49.4V" is a mapcode, but "49.4V" is a mapcode as well, The latter is called a "local" mapcode, because it is not internationally unambiguous unless preceded by a territory code. For "NLD 49.4V" the "NLD"-part is called "the territory" and the "49.4V"-part is called "the code" (which are both part of "the mapcode"). This distinction between "territory" and "code" in a mapcode is why the interface of this class has been changed from version 1.50.0 to reflect this terminology. On alphabets: Mapcode codes can be represented in different alphabets. Note that an alphabet is something else than a locale or a language. The supported alphabets for mapcodes are listed in Alphabet. Mapcode objects provide methods to obtain the mapcode code in a specific alphabet. By default, the Alphabet.ROMAN is used.

Field Summary

Fields

Modifier and Type	Field and Description
static String	REGEX_MAPCODE This patterns/regular expressions is used for checking mapcode format strings.

Constructor Summary

Constructors

Constructor and Description
Mapcode(String code, Territory territory) Create a mapcode object.

Method Summary

Modifier and Type	Method and Description
static boolean	containsTerritory(String mapcode) Returns whether the mapcode contains territory information or not.
boolean	equals(Object obj)
String	getCode()
String	getCode(Alphabet alphabet) Get the Mapcode string (without territory information) with standard precision.
String	getCode(int precision)
String	getCode(int precision, Alphabet alphabet) Get the mapcode code (without territory information) with a specified precision.
String	getCodeWithTerritory()
String	getCodeWithTerritory(Alphabet alphabet)
String	getCodeWithTerritory(int precision)
String	getCodeWithTerritory(int precision, Alphabet alphabet) Return the international mapcode as a shorter version using the ISO territory codes where possible.
String	getCodeWithTerritoryFullname()
String	getCodeWithTerritoryFullname(Alphabet alphabet)
String	getCodeWithTerritoryFullname(int precision)
String	getCodeWithTerritoryFullname(int precision, Alphabet alphabet) Return the full international mapcode, including the full name of the territory and the mapcode code itself.
static int	getPrecisionFormat(String mapcode) This method return the mapcode type, given a mapcode string.
static double	getSafeMaxOffsetInMeters(int precision) Get a safe maximum for the distance between a decoded mapcode and its original location used for encoding the mapcode.
Territory	getTerritory() Get the territory information.
int	hashCode()
static boolean	isValidMapcodeFormat(String mapcode) This method provides a shortcut to checking if a mapcode string is formatted properly or not at all.
String	toString() This method is defined as returning the mapcode code including its territory, with normal precision (precision 0).

Methods inherited from class java.lang.Object

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

Field Detail

REGEX_MAPCODE

@Nonnull
public static final String REGEX_MAPCODE

This patterns/regular expressions is used for checking mapcode format strings. They've been made public to allow others to use the correct regular expressions as well.

See Also:

Constant Field Values

Constructor Detail

Mapcode

public Mapcode(@Nonnull
               String code,
               @Nonnull
               Territory territory)
        throws IllegalArgumentException

Create a mapcode object. Normally, mapcodes are created be encoding a lat/lon pair using MapcodeCodec.encode(double, double) rather than creating them yourself. Note that it is possible to create invalid mapcodes this way, which are syntactically correct. Note that the constructor will throw an IllegalArgumentException if the syntax of the mapcode is not correct. The mapcode is not checked for validity, other than its syntax.

Parameters:

code - Code of mapcode.

territory - Territory.

Throws:

IllegalArgumentException - Thrown if syntax not valid or if the mapcode string contains territory information.

Method Detail

getCode

@Nonnull
public String getCode(@Nullable
                               Alphabet alphabet)

Get the Mapcode string (without territory information) with standard precision. The returned mapcode does not include the '-' separator and additional digits. A mapcode defines an area of approximately 10 x 10 meters (100 m2) and will decode to the center of that area. On average, the original coordinate will be 3.6 meters from this center: the average inaccuracy of a mapcode.

Parameters:

alphabet - Alphabet.

Returns:

Mapcode string.

getCode

@Nonnull
public String getCode()

getCode

@Nonnull
public String getCode(int precision,
                               @Nullable
                               Alphabet alphabet)

Get the mapcode code (without territory information) with a specified precision. The returned mapcode includes a '-' separator and additional digits for precisions 1 to 8. The precision defines the size of a geographical area a single mapcode covers. This means It also defines the maximum distance to the location, a (latitude, longitude) pair, that encoded to this mapcode. Precision 0: area is approx 10 x 10 meters (100 m2); max. distance from original location less than 7.5 meters. Precision 1: area is approx 3.33 m2; max. distance from original location less than 1.5 meters. Precision 1: area is approx 0.11 m2; max. distance from original location less than 0.4 meters. etc. (each level reduces the area by a factor of 30) The accuracy is slightly better than the figures above, but these figures are safe assumptions.

Parameters:

precision - Precision. Range: 0..8.

alphabet - Alphabet.

Returns:

Mapcode code.

Throws:

IllegalArgumentException - Thrown if precision is out of range (must be in [0, 8]).

getCode

@Nonnull
public String getCode(int precision)
                        throws IllegalArgumentException

Throws:

IllegalArgumentException

getCodeWithTerritoryFullname

@Nonnull
public String getCodeWithTerritoryFullname(int precision,
                                                    @Nullable
                                                    Alphabet alphabet)
                                             throws IllegalArgumentException

Return the full international mapcode, including the full name of the territory and the mapcode code itself. The format of the string is: full-territory-name cde Example: Netherlands 49.4V (regular code) Netherlands 49.4V-K2 (high precision code)

Parameters:

precision - Precision specifier. Range: [0, 8].

alphabet - Alphabet.

Returns:

Full international mapcode.

Throws:

IllegalArgumentException - Thrown if precision is out of range (must be in [0, 8]).

getCodeWithTerritoryFullname

@Nonnull
public String getCodeWithTerritoryFullname(int precision)
                                             throws IllegalArgumentException

Throws:

IllegalArgumentException

getCodeWithTerritoryFullname

@Nonnull
public String getCodeWithTerritoryFullname(@Nullable
                                                    Alphabet alphabet)

getCodeWithTerritoryFullname

@Nonnull
public String getCodeWithTerritoryFullname()

getCodeWithTerritory

@Nonnull
public String getCodeWithTerritory(int precision,
                                            @Nullable
                                            Alphabet alphabet)
                                     throws IllegalArgumentException

Return the international mapcode as a shorter version using the ISO territory codes where possible. International codes use a territory code "AAA". The format of the code is: short-territory-name mapcode Example: NLD 49.4V (regular code) NLD 49.4V-K2 (high-precision code)

Parameters:

precision - Precision specifier. Range: [0, 8].

alphabet - Alphabet.

Returns:

Short-hand international mapcode.

Throws:

IllegalArgumentException - Thrown if precision is out of range (must be in [0, 8]).

getCodeWithTerritory

@Nonnull
public String getCodeWithTerritory(int precision)
                                     throws IllegalArgumentException

Throws:

IllegalArgumentException

getCodeWithTerritory

@Nonnull
public String getCodeWithTerritory(@Nonnull
                                            Alphabet alphabet)

getCodeWithTerritory

@Nonnull
public String getCodeWithTerritory()

getTerritory

@Nonnull
public Territory getTerritory()

Get the territory information.

Returns:

Territory information.

getPrecisionFormat

public static int getPrecisionFormat(@Nonnull
                                     String mapcode)
                              throws UnknownPrecisionFormatException

This method return the mapcode type, given a mapcode string. If the mapcode string has an invalid format, an exception is thrown. Note that this method only checks the syntactic validity of the mapcode, the string format. It does not check if the mapcode is really a valid mapcode representing a position on Earth.

Parameters:

mapcode - Mapcode (optionally with a territory).

Returns:

Type of mapcode code format.

Throws:

UnknownPrecisionFormatException - If precision format is incorrect.

isValidMapcodeFormat

public static boolean isValidMapcodeFormat(@Nonnull
                                           String mapcode)
                                    throws IllegalArgumentException

This method provides a shortcut to checking if a mapcode string is formatted properly or not at all.

Parameters:

mapcode - Mapcode (optionally with a territory).

Returns:

True if the mapcode format, the syntax, is correct. This does not mean the mapcode code is actually a valid mapcode representing a location on Earth.

Throws:

IllegalArgumentException - If mapcode is null.

containsTerritory

public static boolean containsTerritory(@Nonnull
                                        String mapcode)
                                 throws IllegalArgumentException

Returns whether the mapcode contains territory information or not.

Parameters:

mapcode - Mapcode string, optionally with territory information.

Returns:

True if mapcode contains territory information.

Throws:

IllegalArgumentException - If mapcode has incorrect syntax.

getSafeMaxOffsetInMeters

public static double getSafeMaxOffsetInMeters(int precision)

Get a safe maximum for the distance between a decoded mapcode and its original location used for encoding the mapcode. The actual accuracy (resolution) of mapcodes is better than this, but these are safe values to use under normal circumstances. Do not make any other assumptions on these numbers than that mapcodes are never more off by this distance.

Parameters:

precision - Precision of mapcode.

Returns:

Maximum offset in meters.

toString

@Nonnull
public String toString()

This method is defined as returning the mapcode code including its territory, with normal precision (precision 0).

Overrides:

toString in class Object

Returns:

Mapcode, including territory and code. Plain ASCII, non-Unicode.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(@Nullable
                      Object obj)

Overrides:

equals in class Object