Removed microdegrees from Point, added documentation

Author: rijnb

README.md

@@ -13,6 +13,9 @@ and to decode mapcodes back to latitude/longitude pairs.
 
 **An example of how to use this library can be found at: https://github.com/mapcode-foundation/mapcode-java-example**
 
+If you wish to use mapcodes in your own application landscape, consider using running an instance of the
+Mapcode REST API, which can be found on: **https://github.com/mapcode-foundation/mapcode-rest-service**
+
 # License
 
 Licensed under the Apache License, Version 2.0 (the "License");

pom.xml

@@ -45,7 +45,7 @@
             <name>Matthew Lowden</name>
             <organization>Mapcode</organization>
             <roles>
-                <role>Developer</role>
+                <role>Original Port</role>
             </roles>
         </developer>
     </developers>

src/main/java/com/mapcode/Alphabet.java

@@ -17,14 +17,12 @@
 package com.mapcode;
 
 import javax.annotation.Nonnull;
-import java.util.HashSet;
-import java.util.Set;
 
 import static com.mapcode.CheckArgs.checkNonnull;
 
 /**
  * This enum defines all alphabets supported for mapcodes. Mapcodes can be safely converted between
- * alphabets and fed to the mapcode decoder.
+ * alphabets and fed to the mapcode decoder in the regular ASCII Roman alphabet or any other.
  */
 public enum Alphabet {
     ROMAN(0),
@@ -42,6 +40,10 @@ public enum Alphabet {
     GURMUKHI(12),
     TIBETAN(13);
 
+    /**
+     * The numeric code is synonym for the alphanumeric code. It can be used in the decoder
+     * to define a territory as well.
+     */
     private final int code;
 
     private Alphabet(final int code) {
@@ -52,12 +54,17 @@ public int getCode() {
         return code;
     }
 
+    /**
+     * Get an alphabet from a numeric code.
+     *
+     * @param code Numeric code.
+     * @return Alphabet.
+     * @throws UnknownAlphabetException Thrown if code out of range.
+     */
     @Nonnull
     public static Alphabet fromCode(final int code) throws UnknownAlphabetException {
-        for (final Alphabet alphabet : values()) {
-            if (alphabet.code == code) {
-                return alphabet;
-            }
+        if ((code >= 0) && (code < Alphabet.values().length)) {
+            return Alphabet.values()[code];
         }
         throw new UnknownAlphabetException(code);
     }
@@ -89,20 +96,12 @@ public static Alphabet fromString(@Nonnull final String numericOrAlpha) throws U
      * Static checking of the static data structures.
      */
     static {
-        final String errorPrefix = "Initializing error: ";
-        final Set<Integer> alphabetCodeList = new HashSet<>();
-
+        int i = 0;
         for (final Alphabet alphabet : Alphabet.values()) {
-            final int alphabetCode = alphabet.getCode();
-            if ((alphabetCode < 0) || (alphabetCode >= Alphabet.values().length)) {
-                throw new ExceptionInInitializerError(errorPrefix + "alphabet code out of range: " + alphabetCode);
-
-            }
-            if (alphabetCodeList.contains(alphabetCode)) {
-                throw new ExceptionInInitializerError(errorPrefix + "non-unique alphabet code: " + alphabetCode);
+            if (Alphabet.values()[i].code != i) {
+                throw new ExceptionInInitializerError("Incorrect alphabet code: " + alphabet + ".code should be " + i);
             }
-            alphabetCodeList.add(alphabet.getCode());
+            ++i;
         }
-        assert alphabetCodeList.size() == Alphabet.values().length;
     }
 }

src/main/java/com/mapcode/CheckArgs.java

@@ -22,7 +22,7 @@
 import static com.mapcode.Mapcode.isValidMapcodeFormat;
 
 /**
- * Package private helper methods.
+ * Package private helper methods to check arguments for validity.
  */
 class CheckArgs {
 

src/main/java/com/mapcode/Decoder.java

@@ -165,8 +165,7 @@ static Point decode(@Nonnull final String argMapcode,
         LOG.trace("decode: result=({}, {})",
                 result.isDefined() ? result.getLatDeg() : Double.NaN,
                 result.isDefined() ? result.getLonDeg() : Double.NaN);
-        result = Point.restrictLatLon(result);
-        return result;
+        return result.wrap();
     }
 
     // ----------------------------------------------------------------------

src/main/java/com/mapcode/Encoder.java

@@ -64,21 +64,10 @@ private static List<Mapcode> encode(final double argLatDeg, final double argLonD
                 argLatDeg, argLonDeg, (territory == null) ? null : territory.name(), isRecursive, limitToOneResult,
                 allowWorld);
 
-        double latDeg = argLatDeg;
-        double lonDeg = argLonDeg;
+        double latDeg = Point.mapToLat(argLatDeg);
+        double lonDeg = Point.mapToLon(argLonDeg);
         Territory stateOverride = argStateOverride;
 
-        if (latDeg > 90) {
-            latDeg -= 180;
-        } else if (latDeg < -90) {
-            latDeg += 180;
-        }
-        if (lonDeg > 179.999999) {
-            lonDeg -= 360;
-        } else if (lonDeg < -180) {
-            lonDeg += 180;
-        }
-
         final Point pointToEncode = Point.fromDeg(latDeg, lonDeg);
         final List<SubArea> areas = SubArea.getAreasForPoint(pointToEncode);
         final List<Mapcode> results = new ArrayList<>();

src/main/java/com/mapcode/MapcodeCodec.java

@@ -25,7 +25,6 @@
 import java.util.regex.Matcher;
 
 import static com.mapcode.CheckArgs.checkNonnull;
-import static com.mapcode.CheckArgs.checkRange;
 
 /**
  * ----------------------------------------------------------------------------------------------
@@ -86,8 +85,8 @@ public static List<Mapcode> encode(@Nonnull final Point point) throws IllegalArg
      * that the first result is the shortest mapcode. If you want to use the shortest mapcode, use
      * {@link #encodeToShortest(double, double, Territory)}.
      *
-     * @param latDeg              Latitude, accepted range: -90..90.
-     * @param lonDeg              Longitude, accepted range: -180..180.
+     * @param latDeg              Latitude, accepted range: -90..90 (limited to this range if outside).
+     * @param lonDeg              Longitude, accepted range: -180..180 (wrapped to this range if outside).
      * @param restrictToTerritory Try to encode only within this territory, see {@link Territory}. May be null.
      * @return List of mapcode information records, see {@link Mapcode}. This list is empty if no
      * Mapcode can be generated for this territory matching the lat/lon.
@@ -96,9 +95,6 @@ public static List<Mapcode> encode(@Nonnull final Point point) throws IllegalArg
     @Nonnull
     public static List<Mapcode> encode(final double latDeg, final double lonDeg,
                                        @Nullable final Territory restrictToTerritory) throws IllegalArgumentException {
-        checkRange("latDeg", latDeg, Point.LAT_DEG_MIN, Point.LAT_DEG_MAX);
-        checkRange("lonDeg", lonDeg, Point.LON_DEG_MIN, Point.LON_DEG_MAX);
-
         // Call Mapcode encoder.
         final List<Mapcode> results = Encoder.encode(latDeg, lonDeg, restrictToTerritory, false, false, (restrictToTerritory == null));
         assert results != null;
@@ -149,9 +145,6 @@ public static Mapcode encodeToShortest(@Nonnull final Point point) throws Illega
     @Nonnull
     public static Mapcode encodeToShortest(final double latDeg, final double lonDeg,
                                            @Nullable final Territory restrictToTerritory) throws IllegalArgumentException, UnknownMapcodeException {
-        checkRange("latDeg", latDeg, Point.LAT_DEG_MIN, Point.LAT_DEG_MAX);
-        checkRange("lonDeg", lonDeg, Point.LON_DEG_MIN, Point.LON_DEG_MAX);
-
         // Call mapcode encoder.
         @Nonnull final List<Mapcode> results =
                 Encoder.encode(latDeg, lonDeg, restrictToTerritory, false, true, (restrictToTerritory == null));
@@ -181,8 +174,6 @@ public static Mapcode encodeToShortest(@Nonnull final Point point,
      */
     @Nonnull
     public static Mapcode encodeToInternational(final double latDeg, final double lonDeg) throws IllegalArgumentException {
-        checkRange("latDeg", latDeg, Point.LAT_DEG_MIN, Point.LAT_DEG_MAX);
-        checkRange("lonDeg", lonDeg, Point.LON_DEG_MIN, Point.LON_DEG_MAX);
 
         // Call mapcode encoder.
         @Nonnull final List<Mapcode> results = encode(latDeg, lonDeg, Territory.AAA);
@@ -280,8 +271,6 @@ public static Point decode(
             throw new UnknownMapcodeException("Unknown Mapcode: " + mapcodeClean +
                     ", territoryContext=" + defaultTerritoryContext);
         }
-        assert (Point.LAT_DEG_MIN <= point.getLatDeg()) && (point.getLatDeg() <= Point.LAT_DEG_MAX) : point.getLatDeg();
-        assert (Point.LON_DEG_MIN <= point.getLonDeg()) && (point.getLonDeg() <= Point.LON_DEG_MAX) : point.getLonDeg();
         return point;
     }
 }