11# Mapcode Library for Java
22
3- Welcome to the Java library to handle mapcodes. The original C library was created by Pieter Geelen. Work
4- on the Java version of the Mapcode library was done by Rijn Buve, initial port by Matthew Lowden.
3+ Welcome to the Java library to handle mapcodes. The original C library was created by Pieter Geelen.
4+ The initial port to Java and considerable speed-ups were done by Matthew Lowden.
5+ Rijn Buve has further developed and maintained the Java version of the Mapcode library since.
56
67## Release Notes
78
89You can find the release notes for this library at: ** [ Release Notes] ( ./ReleaseNotes.html ) ** .
910
1011## Code Style Settings for IntelliJ IDEA
1112
12- The Java code uses the default IntelliJ IDEA code style settings for Java.
13+ The Java code uses the * default* [ JetBrains IntelliJ IDEA] ( https://www.jetbrains.com/idea )
14+ code style settings for Java, with one exception:
15+ code blocks are always surround by ` {...} ` and on separate lines.
1316
14- How To Build The Mapcode Library JAR File
17+ ### How To Build The Mapcode Library JAR File
1518
1619The sources for the Mapcode Library for Java contain everything to build the Mapcode JAR file as well
1720as a significant number of unit tests to verify the correctness of the implementation against the
@@ -22,15 +25,16 @@ with JDK 1.6, JDK 1.7 and JDK 1.8.
2225
2326To build the library:
2427
25- cd ** MAPCODE-HOME**
28+ cd < MAPCODE-HOME>
2629 mvn clean install
2730
28- This produces a JAR file in your local Maven repository at ` ~/.m2/repository/com/mapcode/mapcode/x.y / `
31+ This produces a JAR file in your local Maven repository at ` ~/.m2/repository/com/mapcode/mapcode/<version> / `
2932You can include this JAR in your project, or store it in your local Nexus repository, for example.
3033
31- If you creating a Maven project, you can see how to include the JAR in your project in the menu
34+ If you create a Maven project, you can see how to include the JAR in your project in the menu
3235item ` Dependency Information ` in the menu on this page.
3336
37+ The latest official version of the libray on Maven Central can be found [ ** here** ] ( http://search.maven.org/#search%7Cga%7C1%7Cmapcode ) .
3438
3539## How To Use This Library In Your Application
3640
@@ -62,9 +66,9 @@ original input.
6266
6367Example:
6468
65- final double lat = 52.376514;
66- final double lon = 4.908542;
67- final List**Mapcode** results = MapcodeCodec.encode(lat, lon);
69+ double lat = 52.376514;
70+ double lon = 4.908542;
71+ List**Mapcode** results = MapcodeCodec.encode(lat, lon);
6872 // Returns a non-empty list of results.
6973
7074This produces a non-empty list of resulting mapcodes. The shortest (potentially local) mapcodes is always
@@ -76,8 +80,8 @@ longitude) pair, where encoding is restricted to a specific territory.
7680
7781Example:
7882
79- final List**Mapcode** results = MapcodeCodec.encode(lat, lon, Territory.NLD);
80- // Returns an empty list of results if the location is not within the territory.
83+ List**Mapcode** results = MapcodeCodec.encode(lat, lon, Territory.NLD);
84+ // Returns an empty list of results if the location is not within territory NLD .
8185
8286This resticts encoding to a specific territory and produces a potentially empty list of results.
8387Again, if encoding succeeded, the first mapcode is the shortest one and the last mapcode in the list is the
@@ -86,26 +90,27 @@ globally unique international mapcode.
8690Both ` encode() ` methods are also offered as a ` encodeToShortest() ` method, which essentially
8791returns only the first result of the previous methods (if there are any results).
8892
89- final Mapcode result = MapcodeCodec.encodeToShortest(lat, lon);
90- // Always returns a mapcode.
93+ Mapcode result = MapcodeCodec.encodeToShortest(lat, lon);
94+ // Always returns a mapcode (or valid lat and lon values) .
9195
9296 try {
93- final Mapcode result = MapcodeCodec.encodeToShortest(lat, lon, Territory.NLD);
97+ Mapcode result = MapcodeCodec.encodeToShortest(lat, lon, Territory.NLD);
98+ // This may fail.
9499 }
95- catch (final UnknownMapcodeException e) {
100+ catch (UnknownMapcodeException e) {
96101 // If the location is not within the territory, this exception is thrown.
97102 }
98103
99104** ` Point decode(String mapcode) ` ** decodes a mapcode to a ` Point ` which contains a location. Example:
100105
101- final Point p = MapcodeCodec.decode("NLD 49.4V");
106+ Point p = MapcodeCodec.decode("NLD 49.4V");
102107
103108** ` Point decode(String mapcode, Territory territory) ` ** decodes a mapcode to a ` Point ` which contains a
104109location, where the mapcode must be located within a specific territory.
105110
106111Examples of usage:
107112
108- final Point p = MapcodeCodec.decode("49.4V", Territory.NLD);
113+ Point p = MapcodeCodec.decode("49.4V", Territory.NLD);
109114
110115
111116## Class ` Mapcode.java `
@@ -125,12 +130,16 @@ The default precision offered by `getCode()` is approximately 10m (maximum dista
125130longitude the mapcode decodes to). This corresponds to an area of 20m x 20m (400m2). These mapcodes include
126131no additional precision digits.
127132
128- The precision offered by ` getMapcodePrecision1( )` is approximately 2m.
133+ The precision offered by ` getCode(1 )` is approximately 2m.
129134This corresponds to an area of 4m x 4m (16m2). These mapcodes include 1 additional precision digit.
130135
131- The precision offered by ` getMapcodePrecision2( )` is approximately 0.40m. This corresponds to an area
136+ The precision offered by ` getCode(2 )` is approximately 0.40m. This corresponds to an area
132137of 0.80m x 0.80m (0.64m2). These mapcodes include 2 additional precision digits.
133138
139+ This goes up to ` getCode(8) ` , which provides nanometer accuracy. (Please note one of the main advantages
140+ of mapcodes over WGS84 coordinates is their simplicity and short size, so try to use as little precision
141+ as required for your application...)
142+
134143** ` Territory getTerritory() ` ** returns the territory information.
135144
136145** ` toString() ` ** and ** ` getCodeWithTerritory() ` ** return mapcodes string with territory information,
@@ -144,8 +153,9 @@ degrees.
144153
145154** ` Point fromDeg(double latitude, double longitude) ` ** returns a ` Point ` for a given (latitude, longitude)
146155pair. Note that latitudes are always between ** -90** and ** 90** , and longitudes are
147- always between ** -180** and ** 180** (non-inclusive). Values outside these range are correctly limited
148- (latitude) or wrapped (longitude) to these ranges.
156+ always between ** -180** and ** 180** (non-inclusive) whenreturned.
157+ However, values outside these range are correctly limited (latitude) or wrapped (longitude) to these ranges
158+ when supplied to the class.
149159
150160The methods ** ` double getLat() ` ** and ** ` getLon() ` ** return the latitude and longitude respectively, in degrees.
151161
0 commit comments