Changed Java interface to reflect terminology around mapcode/code/territory

Author: rijnb

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

@@ -45,12 +45,12 @@ static void checkNonnull(@Nonnull final String param, @Nullable final Object obj
         }
     }
 
-    static void checkMapcode(@Nonnull final String param, @Nullable final String mapcode)
+    static void checkMapcodeCode(@Nonnull final String param, @Nullable final String code)
             throws IllegalArgumentException {
-        checkNonnull(param, mapcode);
-        if (!isValidMapcodeFormat(mapcode)) {
-            throw new IllegalArgumentException(mapcode + " is not a correctly formatted mapcode; " +
-                    "the regular expression for the mapcode syntax is: " + Mapcode.REGEX_MAPCODE_FORMAT);
+        checkNonnull(param, code);
+        if (!isValidMapcodeFormat(code)) {
+            throw new IllegalArgumentException(code + " is not a correctly formatted mapcode code; " +
+                    "the regular expression for the mapcode code syntax is: " + Mapcode.REGEX_MAPCODE);
         }
     }
 }

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

@@ -152,7 +152,7 @@ private static List<Mapcode> encode(final double argLatDeg, final double argLonD
                         results.add(newResult);
                     } else {
                         LOG.error("encode: Duplicate results found, newResult={}, results={} items",
-                                newResult.asInternationalISO(), results.size());
+                                newResult.getCodeWithTerritory(), results.size());
                     }
 
                     lastbasesubareaID = from;

src/main/java/com/mapcode/Mapcode.java

@@ -16,8 +16,12 @@
 
 package com.mapcode;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import javax.annotation.Nonnull;
 import java.util.List;
+import java.util.regex.Matcher;
 
 import static com.mapcode.CheckArgs.checkNonnull;
 import static com.mapcode.CheckArgs.checkRange;
@@ -30,6 +34,7 @@
  * This class is the external Java interface for encoding and decoding mapcodes.
  */
 public final class MapcodeCodec {
+    private static final Logger LOG = LoggerFactory.getLogger(MapcodeCodec.class);
 
     private MapcodeCodec() {
         // Prevent instantiation.
@@ -244,63 +249,68 @@ public static Mapcode encodeToInternational(@Nonnull final Point point) throws I
      * @throws IllegalArgumentException Thrown if arguments are null, or if the syntax of the mapcode is incorrect.
      */
     @Nonnull
-    public static Point decode(
-            @Nonnull final String mapcode) throws UnknownMapcodeException, IllegalArgumentException {
-        checkNonnull("mapcode", mapcode);
-        String mapcodeTrimmed = mapcode.trim().toUpperCase();
-        final int space = mapcodeTrimmed.indexOf(' ');
-        final Territory territory;
-        if ((space > 0) && (mapcodeTrimmed.length() > space)) {
-
-            // Get territory from mapcode.
-            final String territoryName = mapcodeTrimmed.substring(0, space).trim();
-            try {
-                territory = Territory.fromString(territoryName);
-            } catch (final UnknownTerritoryException ignored) {
-                throw new UnknownMapcodeException("Wrong territory code: " + territoryName);
-            }
-            mapcodeTrimmed = mapcode.substring(space + 1).trim();
-        } else {
-            territory = Territory.AAA;
-        }
-        if (!Mapcode.isValidMapcodeFormat(mapcodeTrimmed)) {
-            throw new IllegalArgumentException(mapcode + " is not a correctly formatted mapcode; " +
-                    "the regular expression for the mapcode syntax is: " + Mapcode.REGEX_MAPCODE_FORMAT);
-        }
-        return decode(mapcodeTrimmed, territory);
+    public static Point decode(@Nonnull final String mapcode) throws UnknownMapcodeException, IllegalArgumentException {
+        return decode(mapcode, Territory.AAA);
     }
 
     /**
      * Decode a mapcode to a Point. A reference territory is supplied for disambiguation (only used if applicable).
      *
      * The accepted format is:
-     * {mapcode}        (note that a territory code is not allowed here)
+     * {mapcode}
+     * {territory-code} {mapcode}
      *
-     * @param mapcode          Mapcode.
-     * @param territoryContext Territory for disambiguation purposes.
+     * Note that if a territory-code is supplied in the string, it takes preferences over the parameter.
+     *
+     * @param mapcode                 Mapcode.
+     * @param defaultTerritoryContext Default territory context for disambiguation purposes.
      * @return Point corresponding to mapcode. Latitude range: -90..90, longitude range: -180..180.
      * @throws UnknownMapcodeException  Thrown if the mapcode has the right syntax, but cannot be decoded into a point.
      * @throws IllegalArgumentException Thrown if arguments are null, or if the syntax of the mapcode is incorrect.
      */
     @Nonnull
     public static Point decode(
             @Nonnull final String mapcode,
-            @Nonnull final Territory territoryContext) throws UnknownMapcodeException, IllegalArgumentException {
+            @Nonnull final Territory defaultTerritoryContext) throws UnknownMapcodeException, IllegalArgumentException {
         checkNonnull("mapcode", mapcode);
-        checkNonnull("territoryContext", territoryContext);
-        final String mapcodeTrimmed = mapcode.trim().toUpperCase();
-        if (!Mapcode.isValidMapcodeFormat(mapcodeTrimmed)) {
-            throw new IllegalArgumentException(mapcode + " is not a correctly formatted mapcode; " +
-                    "the regular expression for the mapcode syntax is: " + Mapcode.REGEX_MAPCODE_FORMAT);
+        checkNonnull("territoryContext", defaultTerritoryContext);
+
+        // Clean up mapcode.
+        String mapcodeClean = mapcode.trim().toUpperCase();
+
+        // Determine territory from mapcode.
+        final Territory territory;
+        final Matcher matcherTerritory = Mapcode.PATTERN_TERRITORY.matcher(mapcodeClean);
+        if (!matcherTerritory.find()) {
+
+            // No territory code was supplied in the string, use specified territory context parameter.
+            territory = defaultTerritoryContext;
+        } else {
+
+            // Use the territory code from the string.
+            final String territoryName = mapcodeClean.substring(matcherTerritory.start(), matcherTerritory.end()).trim();
+            try {
+                territory = Territory.fromString(territoryName);
+            } catch (final UnknownTerritoryException ignored) {
+                throw new UnknownMapcodeException("Wrong territory code: " + territoryName);
+            }
+
+            // Cut off the territory part.
+            mapcodeClean = mapcode.substring(matcherTerritory.end()).trim();
+        }
+
+        if (!Mapcode.isValidMapcodeFormat(mapcodeClean)) {
+            throw new IllegalArgumentException(mapcodeClean + " is not a correctly formatted mapcode; " +
+                    "the regular expression for the mapcode syntax is: " + Mapcode.REGEX_MAPCODE);
         }
 
-        @Nonnull final Point point = Decoder.decode(mapcodeTrimmed, territoryContext);
+        @Nonnull final Point point = Decoder.decode(mapcodeClean, territory);
         assert point != null;
 
         // Points can only be undefined within the mapcode implementation. Throw an exception here if undefined.
         if (!point.isDefined()) {
-            throw new UnknownMapcodeException("Unknown Mapcode: " + mapcodeTrimmed +
-                    ", territoryContext=" + territoryContext);
+            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();

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

@@ -16,77 +16,67 @@
 
 package com.mapcode;
 
+import com.mapcode.Mapcode.FormatType;
 import org.junit.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import javax.annotation.Nonnull;
+
 import static org.junit.Assert.assertEquals;
 
 @SuppressWarnings({"OverlyBroadThrowsClause", "ProhibitedExceptionDeclared"})
 public class AlphabetTest {
     private static final Logger LOG = LoggerFactory.getLogger(AlphabetTest.class);
 
+    @SuppressWarnings("JUnitTestMethodWithNoAssertions")
     @Test
-    public void convertGreek1() throws Exception {
-        LOG.info("convertGreek1");
-        final String a1 = "\u0397\u03a0.\u03982";
-        LOG.info("type = {}", Mapcode.getMapcodeFormatType(a1));
-        final String x1 = Mapcode.convertToAscii(a1);
-        final Point p1 = MapcodeCodec.decode(x1, Territory.GRC);
-        final String y1 = MapcodeCodec.encodeToShortest(p1).getMapcode();
-        final String b1 = Mapcode.convertToAlphabet(y1, Alphabet.GREEK);
-        LOG.info("a1 = {}, b1 = {}, x1 = {}, y1 = {}, p1 = {}", a1, b1, x1, y1, p1);
-        assertEquals(a1, b1);
-        assertEquals(x1, y1);
+    public void testConvertToAlphabet() throws Exception {
+        LOG.info("testConvertToAlphabet");
+        convertCodeInAlphabet("\u0397\u03a0.\u03982", Territory.GRC, Alphabet.GREEK, 0);
+        convertCodeInAlphabet("\u0397\u03a0.\u03982-\u03a62", Territory.GRC, Alphabet.GREEK, 2);
+        convertCodeInAlphabet("GRC \u0397\u03a0.\u03982-\u03a62", Territory.GRC, Alphabet.GREEK, 2);
 
-        final String a2 = "\u0397\u03a0.\u03982-\u03a62";
-        LOG.info("type = {}", Mapcode.getMapcodeFormatType(a2));
-        final String x2 = Mapcode.convertToAscii(a2);
-        final Point p2 = MapcodeCodec.decode(x2, Territory.GRC);
-        final String y2 = MapcodeCodec.encodeToShortest(p2).getMapcodePrecision(2);
-        final String b2 = Mapcode.convertToAlphabet(y2, Alphabet.GREEK);
-        LOG.info("a2 = {}, b2 = {}, x2 = {}, y2 = {}, p2 = {}", a2, b2, x2, y2, p2);
-        assertEquals(a2, b2);
-        assertEquals(x2, y2);
+        convertCodeInAlphabet("XX.XX", Territory.NLD, Alphabet.GREEK, 0);
+        convertCodeInAlphabet("XX.XX-12", Territory.NLD, Alphabet.GREEK, 2);
 
-        final String a3 = "GRC \u0397\u03a0.\u03982-\u03a62";
-        LOG.info("type = {}", Mapcode.getMapcodeFormatType(a3));
-        final String x3 = Mapcode.convertToAscii(a3);
-        final Point p3 = MapcodeCodec.decode(x3);
-        final String y3 = MapcodeCodec.encodeToShortest(p3).getMapcodePrecision(2);
-        final String b3 = Mapcode.convertToAlphabet(y3, Alphabet.GREEK);
-        LOG.info("a3 = {}, b3 = {}, x3 = {}, y3 = {}, p3 = {}", a3, b3, x3, y3, p3);
-        assertEquals(a3, Territory.GRC.toString() + ' ' + b3);
-        assertEquals(x3, Territory.GRC.toString() + ' ' + y3);
-    }
+        convertCodeInAlphabet("NLD XX.XX", Territory.USA, Alphabet.GREEK, 0);
+        convertCodeInAlphabet("NLD XX.XX-12", Territory.USA, Alphabet.GREEK, 2);
 
-    @Test
-    public void convertGreek2() throws Exception {
-        LOG.info("convertGreek2");
-        final String a1 = "36128.92UW";
-        final Point p1 = MapcodeCodec.decode(a1);
-        final String y1 = MapcodeCodec.encodeToShortest(p1).getMapcodePrecision(0);
-        final String b1 = Mapcode.convertToAlphabet(y1, Alphabet.GREEK);
-        final String c1 = Mapcode.convertToAscii(b1);
-        final String d1 = Mapcode.convertToAlphabet(b1, Alphabet.ROMAN);
-        LOG.info("a1 = {}, b1 = {}, c1 = {}, d1 = {}, y1 = {}, p1 = {}", a1, b1, c1, d1, y1, p1);
-        assertEquals(a1, y1);
-        assertEquals(a1, c1);
-        assertEquals(a1, d1);
+        convertCodeInAlphabet("36128.92UW", Territory.GRC, Alphabet.GREEK, 0);
+        convertCodeInAlphabet("36228.92UW-TK", Territory.GRC, Alphabet.GREEK, 2);
     }
 
-    @Test
-    public void convertGreek3() throws Exception {
-        LOG.info("convertGreek3");
-        final String a2 = "36228.92UW-TK";
-        final Point p2 = MapcodeCodec.decode(a2);
-        final String y2 = MapcodeCodec.encodeToShortest(p2).getMapcodePrecision(2);
-        final String b2 = Mapcode.convertToAlphabet(y2, Alphabet.GREEK);
-        final String c2 = Mapcode.convertToAscii(b2);
-        final String d2 = Mapcode.convertToAlphabet(b2, Alphabet.ROMAN);
-        LOG.info("a2 = {}, b2 = {}, c2 = {}, d2 = {}, y2 = {}, p2 = {}", a2, b2, c2, d2, y2, p2);
-        assertEquals(a2, y2);
-        assertEquals(a2, c2);
-        assertEquals(a2, d2);
+    private static void convertCodeInAlphabet(
+            @Nonnull final String code,
+            @Nonnull final Territory territory, @Nonnull final Alphabet alphabet,
+            final int precision) throws Exception {
+
+        // Check type.
+        final FormatType formatType = FormatType.fromPrecision(precision);
+        final FormatType type = Mapcode.getMapcodeFormatType(code);
+        assertEquals("code = " + code + ", type = " + type, formatType, type);
+
+        // Check original code and converted to ASCII point at same location.
+        final String codeAscii = Mapcode.convertMapcodeToPlainAscii(code);
+        final Point pointCode = MapcodeCodec.decode(code, territory);
+        final Point pointAscii = MapcodeCodec.decode(codeAscii, territory);
+        assertEquals("code = " + code + ", pointCode = " + pointCode + ", pointAscii = " + pointAscii,
+                pointCode, pointAscii);
+
+        // Check if it re-encodes to the same mapcode codes.
+        final Mapcode mapcode = MapcodeCodec.encodeToShortest(pointCode);
+        final String codeRoman;
+        final String codeAlphabet;
+        if (Mapcode.containsTerritory(code)) {
+            codeRoman = mapcode.getCodeWithTerritory(precision);
+            codeAlphabet = mapcode.getCodeWithTerritory(precision, alphabet);
+        } else {
+            codeRoman = mapcode.getCode(precision);
+            codeAlphabet = mapcode.getCode(precision, alphabet);
+        }
+        LOG.info("code = {}, codeAlphabet = {}, codeAscii = {}, codeRoman = {}", code, codeAlphabet, codeAscii, codeRoman);
+        assertEquals(codeAscii, codeRoman);
+        assertEquals(code, codeAlphabet);
     }
 }

src/test/java/com/mapcode/AlphabetTest.java

@@ -162,10 +162,20 @@ public void mapCodeWithZeroGroitzsch() throws Exception {
                 point.getLonMicroDeg());
     }
 
-    @Test(expected = IllegalArgumentException.class)
-    public void invalidTerritory() throws Exception {
-        LOG.info("invalidTerritory");
-        MapcodeCodec.decode("NLD 49.4V", Territory.NLD);
+    @Test
+    public void validTerritory() throws Exception {
+        LOG.info("validTerritory");
+        final Point point1 = MapcodeCodec.decode("NLD 49.4V", Territory.NLD);
+        assertEquals("decode latitude", 52376514, point1.getLatMicroDeg());
+        assertEquals("decode longitude", 4908542, point1.getLonMicroDeg());
+
+        final Point point2 = MapcodeCodec.decode("NLD 49.4V", Territory.USA);
+        assertEquals("decode latitude", 52376514, point2.getLatMicroDeg());
+        assertEquals("decode longitude", 4908542, point2.getLonMicroDeg());
+
+        final Point point3 = MapcodeCodec.decode("NLD 49.4V");
+        assertEquals("decode latitude", 52376514, point3.getLatMicroDeg());
+        assertEquals("decode longitude", 4908542, point3.getLonMicroDeg());
     }
 
     @Test(expected = IllegalArgumentException.class)