Added checks for mapcode syntax checking

rijnb · rijnb · commit 2dfd255437b9 · 2014-10-09T12:02:17.000+02:00
diff --git a/src/main/java/com/mapcode/Mapcode.java b/src/main/java/com/mapcode/Mapcode.java
@@ -18,6 +18,8 @@
 
 import javax.annotation.Nonnull;
 import java.util.Arrays;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 /**
  * This class defines a single mapcode encoding result, including the mapcode itself and the
@@ -31,7 +33,14 @@ public final class Mapcode {
 
     public Mapcode(
         @Nonnull final String mapcode,
-        @Nonnull final Territory territory) {
+        @Nonnull final Territory territory) throws IllegalArgumentException {
+
+        // Check mapcode format.
+        if (!isValidMapcodeFormat(mapcode)) {
+            throw new IllegalArgumentException(mapcode + " is not a correctly formatted mapcode; " +
+                "the regular expression for the mapcode syntax is: " + REGEX_MAPCODE_FORMAT);
+        }
+
         this.mapcodePrecision2 = mapcode;
         if (mapcode.contains("-")) {
             this.mapcodePrecision0 = mapcode.substring(0, mapcode.length() - 3);
@@ -129,9 +138,65 @@ public Territory getTerritory() {
         return territory;
     }
 
-    @Override
-    public int hashCode() {
-        return Arrays.deepHashCode(new Object[]{mapcodePrecision0, territory});
+    /**
+     * This enum describes the types of mapcodes available.
+     */
+    public enum MapcodeFormatType {
+        MAPCODE_TYPE_INVALID,
+        MAPCODE_TYPE_PRECISION_0,
+        MAPCODE_TYPE_PRECISION_1,
+        MAPCODE_TYPE_PRECISION_2,
+    }
+
+    /**
+     * These patterns and regular expressions are used for checking mapcode format strings.
+     * They've been made pulkic to allow others to use the correct regular expressions as well.
+     */
+    @Nonnull public static final String REGEX_MAPCODE_FORMAT    =
+        "^[a-zA-Z0-9]{2,5}?[.][a-zA-Z0-9]{2,5}?([-][a-zA-Z0-9]{1,2}?)?$";
+    @Nonnull public static final String REGEX_MAPCODE_PRECISION = "[-][a-zA-Z0-9]{1,2}?$";
+
+    @Nonnull public static final Pattern PATTERN_MAPCODE_FORMAT    = Pattern.compile(REGEX_MAPCODE_FORMAT);
+    @Nonnull public static final Pattern PATTERN_MAPCODE_PRECISION = Pattern.compile(REGEX_MAPCODE_PRECISION);
+
+    /**
+     * This method return the mapcode type, given a mapcode string. If the mapcode string has an invalid
+     * format, {@link MapcodeFormatType#MAPCODE_TYPE_INVALID} is returned. If another value is returned,
+     * the precision of the mapcode is given.
+     *
+     * 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.
+     *
+     * @param mapcode Mapcode string.
+     * @return Type of mapcode format, or {@link MapcodeFormatType#MAPCODE_TYPE_INVALID} if not valid.
+     */
+    @Nonnull
+    public static MapcodeFormatType getMapcodeFormatType(@Nonnull final String mapcode) {
+        final Matcher matcherMapcodeFormat = PATTERN_MAPCODE_FORMAT.matcher(mapcode);
+        if (!matcherMapcodeFormat.matches()) {
+            return MapcodeFormatType.MAPCODE_TYPE_INVALID;
+        }
+        final Matcher matcherMapcodePrecision = PATTERN_MAPCODE_PRECISION.matcher(mapcode);
+        if (!matcherMapcodePrecision.find()) {
+            return MapcodeFormatType.MAPCODE_TYPE_PRECISION_0;
+        }
+        final int length = matcherMapcodePrecision.group().length();
+        assert (2 <= length) && (length <= 3);
+        if (length == 2) {
+            return MapcodeFormatType.MAPCODE_TYPE_PRECISION_1;
+        }
+        return MapcodeFormatType.MAPCODE_TYPE_PRECISION_2;
+    }
+
+    /**
+     * This method provides a shortcut to checking if a mapcode string is formatted properly or not at all.
+     *
+     * @param mapcode Mapcode string.
+     * @return True if the mapcode format, the syntax, is correct. This does not mean the mapcode is actually a valid
+     * mapcode representing a location on Earth.
+     */
+    public static boolean isValidMapcodeFormat(@Nonnull final String mapcode) {
+        return getMapcodeFormatType(mapcode) != MapcodeFormatType.MAPCODE_TYPE_INVALID;
     }
 
     /**
@@ -186,6 +251,11 @@ public String toString() {
         return asInternationalISO();
     }
 
+    @Override
+    public int hashCode() {
+        return Arrays.deepHashCode(new Object[]{mapcodePrecision0, territory});
+    }
+
     @Override
     public boolean equals(final Object obj) {
         if (this == obj) {
diff --git a/src/site/apt/ReleaseNotes.apt.vm b/src/site/apt/ReleaseNotes.apt.vm
@@ -9,6 +9,15 @@ Release Notes (Version ${project.version})
     In any case, never depend on them for your own non-<<<SNAPSHOT>>> releases.
 #end
 
+* 1.40.2
+
+    * Added <<<getMapcodeFormatType>>> and <<<isValidMapcodeFormat>>> to check validity of mapcode strings. Added
+    unit tests for these methods as well.
+
+    * Constructor of <<<Mapcode>>> now checks for validity of mapcode string.
+
+    []
+
 * 1.40.1
 
     * Deprecated names <<<getMapcodeHighPrecision>>> and <<<getMapcodeMediumPrecision>>>.
diff --git a/src/test/java/com/mapcode/MapcodeTest.java b/src/test/java/com/mapcode/MapcodeTest.java
@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2014 Stichting Mapcode Foundation (http://www.mapcode.com)
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mapcode;
+
+import org.junit.Test;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class MapcodeTest {
+    private static final Logger LOG = LoggerFactory.getLogger(MapcodeTest.class);
+
+    @Test
+    public void checkValidMapcodeFormats() {
+        LOG.info("checkValidMapcodeFormats");
+
+        assertTrue(Mapcode.isValidMapcodeFormat("A1.B1"));
+        assertTrue(Mapcode.isValidMapcodeFormat("a1.B1"));
+        assertTrue(Mapcode.isValidMapcodeFormat("00.01"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAA.01"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAA.BBB"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAAA.BBB"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAAA.BBBB"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAAAA.BBBB"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AAAAA.BBBBB"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AA.AA-0"));
+        assertTrue(Mapcode.isValidMapcodeFormat("AA.AA-01"));
+    }
+
+    @Test
+    public void checkInvalidMapcodeFormats() {
+        LOG.info("checkInvalidMapcodeFormats");
+
+        assertFalse(Mapcode.isValidMapcodeFormat("A"));
+        assertFalse(Mapcode.isValidMapcodeFormat("AB"));
+        assertFalse(Mapcode.isValidMapcodeFormat("AB."));
+        assertFalse(Mapcode.isValidMapcodeFormat(".A"));
+        assertFalse(Mapcode.isValidMapcodeFormat(".AB"));
+        assertFalse(Mapcode.isValidMapcodeFormat("A.B"));
+        assertFalse(Mapcode.isValidMapcodeFormat("a.B"));
+        assertFalse(Mapcode.isValidMapcodeFormat("0.1"));
+        assertFalse(Mapcode.isValidMapcodeFormat("0.1"));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.1"));
+        assertFalse(Mapcode.isValidMapcodeFormat("0.01"));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.01."));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.01.0"));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.01.00"));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.01-"));
+        assertFalse(Mapcode.isValidMapcodeFormat("00.01-"));
+        assertFalse(Mapcode.isValidMapcodeFormat("AAAAAA.BBBBB"));
+        assertFalse(Mapcode.isValidMapcodeFormat("AAAAA.BBBBBB"));
+        assertFalse(Mapcode.isValidMapcodeFormat("AA.AA-012"));
+    }
+
+    @Test
+    public void checkMapcodeFormatType() {
+        LOG.info("checkMapcodeFormatType");
+
+        assertEquals(Mapcode.MapcodeFormatType.MAPCODE_TYPE_INVALID, Mapcode.getMapcodeFormatType("ABC"));
+        assertEquals(Mapcode.MapcodeFormatType.MAPCODE_TYPE_PRECISION_0, Mapcode.getMapcodeFormatType("AA.BB"));
+        assertEquals(Mapcode.MapcodeFormatType.MAPCODE_TYPE_PRECISION_1, Mapcode.getMapcodeFormatType("AA.BB-1"));
+        assertEquals(Mapcode.MapcodeFormatType.MAPCODE_TYPE_PRECISION_2, Mapcode.getMapcodeFormatType("AA.BB-12"));
+    }
+}
