Merge pull request #14 from mapcode-foundation/dev

Release 1.50.3

Author: rijnb

pom.xml

@@ -8,7 +8,7 @@
     <artifactId>mapcode</artifactId>
 
     <packaging>jar</packaging>
-    <version>1.50.2</version>
+    <version>1.50.3-SNAPSHOT</version>
 
     <name>Mapcode Java Library</name>
     <description>

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

@@ -44,44 +44,44 @@ public enum Alphabet {
      * 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 final int number;
 
-    private Alphabet(final int code) {
-        this.code = code;
+    private Alphabet(final int number) {
+        this.number = number;
     }
 
-    public int getCode() {
-        return code;
+    public int getNumber() {
+        return number;
     }
 
     /**
      * Get an alphabet from a numeric code.
      *
-     * @param code Numeric code.
+     * @param number Numeric code.
      * @return Alphabet.
      * @throws UnknownAlphabetException Thrown if code out of range.
      */
     @Nonnull
-    public static Alphabet fromCode(final int code) throws UnknownAlphabetException {
-        if ((code >= 0) && (code < Alphabet.values().length)) {
-            return Alphabet.values()[code];
+    public static Alphabet fromNumber(final int number) throws UnknownAlphabetException {
+        if ((number >= 0) && (number < Alphabet.values().length)) {
+            return Alphabet.values()[number];
         }
-        throw new UnknownAlphabetException(code);
+        throw new UnknownAlphabetException(number);
     }
 
     /**
      * Return alphabet from a string, which can be a numeric or alpha code.
      *
-     * @param numericOrAlpha Alphabet. May be a numeric or alphanumeric code.
+     * @param numberOrString Alphabet. May be a numeric or alphanumeric code.
      * @return Alphabet.
      * @throws UnknownAlphabetException Thrown if incorrect numeric or alphanumeric code.
      */
     @Nonnull
-    public static Alphabet fromString(@Nonnull final String numericOrAlpha) throws UnknownAlphabetException {
-        checkNonnull("name", numericOrAlpha);
-        final String trimmed = numericOrAlpha.trim().toUpperCase();
+    public static Alphabet fromString(@Nonnull final String numberOrString) throws UnknownAlphabetException {
+        checkNonnull("numberOrString", numberOrString);
+        final String trimmed = numberOrString.trim().toUpperCase();
         try {
-            return fromCode(Integer.valueOf(numericOrAlpha));
+            return fromNumber(Integer.valueOf(numberOrString));
         } catch (final IllegalArgumentException ignored) {
             // Ignore. Re-try as alpha code.
         }
@@ -98,10 +98,10 @@ public static Alphabet fromString(@Nonnull final String numericOrAlpha) throws U
     static {
         int i = 0;
         for (final Alphabet alphabet : Alphabet.values()) {
-            if (Alphabet.values()[i].code != i) {
-                throw new ExceptionInInitializerError("Incorrect alphabet code: " + alphabet + ".code should be " + i);
+            if (Alphabet.values()[i].number != i) {
+                throw new ExceptionInInitializerError("Incorrect alphabet number: " + alphabet + ".number should be " + i);
             }
             ++i;
         }
     }
-}
+}

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

@@ -19,7 +19,7 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-import static com.mapcode.Mapcode.isValidMapcodeFormat;
+import static com.mapcode.Mapcode.getPrecisionFormat;
 
 /**
  * Package private helper methods to check arguments for validity.
@@ -48,9 +48,8 @@ static void checkNonnull(@Nonnull final String param, @Nullable final Object obj
     static void checkMapcodeCode(@Nonnull final String param, @Nullable final String code)
             throws IllegalArgumentException {
         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);
-        }
+
+        // Throws an exception if the format is incorrect.
+        getPrecisionFormat(code);
     }
 }

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

@@ -79,7 +79,7 @@ static Point decode(@Nonnull final String argMapcode,
             }
         }
 
-        final int ccode = territory.getCode();
+        final int ccode = territory.getNumber();
 
         final int from = DataAccess.dataFirstRecord(ccode);
         if (DataAccess.dataFlags(from) == 0) {

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

@@ -87,12 +87,12 @@ private static List<Mapcode> encode(final double argLatDeg, final double argLonD
                 continue;
             }
 
-            final int from = DataAccess.dataFirstRecord(currentEncodeTerritory.getCode());
+            final int from = DataAccess.dataFirstRecord(currentEncodeTerritory.getNumber());
             final Data mapcoderData = new Data(from);
             if (mapcoderData.getFlags() == 0) {
                 continue;
             }
-            final int upto = DataAccess.dataLastRecord(currentEncodeTerritory.getCode());
+            final int upto = DataAccess.dataLastRecord(currentEncodeTerritory.getNumber());
 
 
             final int i = subArea.getSubAreaID();

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

@@ -271,75 +271,80 @@ public Territory getTerritory() {
             Pattern.compile(REGEX_CODE_PRECISION + '$', Pattern.UNICODE_CHARACTER_CLASS);
 
     /**
-     * This enum describes the types of available mapcodes (as returned by {@link #getMapcodeFormatType(String)}.
+     * This enum describes the types of available mapcodes (as returned by {@link #getPrecisionFormat(String)}.
      */
-    public enum FormatType {
+    public enum PrecisionFormat {
         PRECISION_0,
         PRECISION_1,
-        PRECISION_2,
-        INVALID;
+        PRECISION_2;
 
-        public static FormatType fromPrecision(final int precision) {
-            switch (precision) {
+        public static PrecisionFormat fromNumber(final int number) {
+            switch (number) {
                 case 0:
                     return PRECISION_0;
                 case 1:
                     return PRECISION_1;
                 case 2:
                     return PRECISION_2;
                 default:
-                    return INVALID;
+                    throw new UnknownPrecisionFormatException("Precision must be in [0, 2], is: " + number, number);
             }
         }
     }
 
     /**
      * This method return the mapcode type, given a mapcode string. If the mapcode string has an invalid
-     * format, {@link FormatType#INVALID} is returned. If another value is returned,
-     * the precision of the mapcode is given.
+     * 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.
      *
      * @param mapcode Mapcode (optionally with a territory).
-     * @return Type of mapcode code format, or {@link FormatType#INVALID} if not valid.
-     * @throws IllegalArgumentException If mapcode has incorrect syntax.
+     * @return Type of mapcode code format.
+     * @throws UnknownPrecisionFormatException If precision format is incorrect.
      */
     @Nonnull
-    public static FormatType getMapcodeFormatType(@Nonnull final String mapcode) throws IllegalArgumentException {
+    public static PrecisionFormat getPrecisionFormat(@Nonnull final String mapcode) throws UnknownPrecisionFormatException {
 
         // First, decode to ASCII.
         final String decodedMapcode = convertStringToPlainAscii(mapcode).toUpperCase();
 
         // Syntax needs to be OK.
         if (!PATTERN_MAPCODE.matcher(decodedMapcode).matches()) {
-            return FormatType.INVALID;
+            throw new UnknownPrecisionFormatException(decodedMapcode + " is not a correctly formatted mapcode code; " +
+                    "the regular expression for the mapcode code syntax is: " + REGEX_MAPCODE);
         }
 
         // Precision part should be OK.
         final Matcher matcherPrecision = PATTERN_PRECISION.matcher(decodedMapcode);
         if (!matcherPrecision.find()) {
-            return FormatType.PRECISION_0;
+            return PrecisionFormat.PRECISION_0;
         }
         final int length = matcherPrecision.end() - matcherPrecision.start();
         assert (2 <= length) && (length <= 3);
         if (length == 2) {
-            return FormatType.PRECISION_1;
+            return PrecisionFormat.PRECISION_1;
         }
-        return FormatType.PRECISION_2;
+        return PrecisionFormat.PRECISION_2;
     }
 
     /**
      * This method provides a shortcut to checking if a mapcode string is formatted properly or not at all.
      *
-     * @param mapcode Mapcode (optionally with a territory_).
+     * @param mapcode Mapcode (optionally with a territory).
      * @return 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.
      */
-    public static boolean isValidMapcodeFormat(@Nonnull final String mapcode) throws IllegalArgumentException {
+    public static boolean isValidPrecisionFormat(@Nonnull final String mapcode) throws IllegalArgumentException {
         checkNonnull("mapcode", mapcode);
-        return getMapcodeFormatType(mapcode.toUpperCase()) != FormatType.INVALID;
+        try {
+            // Throws an exception if the format is incorrect.
+            getPrecisionFormat(mapcode.toUpperCase());
+            return true;
+        } catch (final UnknownPrecisionFormatException ignored) {
+            return false;
+        }
     }
 
     /**
@@ -362,9 +367,12 @@ public static boolean containsTerritory(@Nonnull final String mapcode) throws Il
 
     /**
      * 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 slightly
+     * 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.
+     *
      * @param precision Precision of mapcode.
      * @return Maximum offset in meters.
      */
@@ -397,7 +405,7 @@ static String convertStringToPlainAscii(@Nonnull final String string) {
      */
     @Nonnull
     static String convertStringToAlphabet(@Nonnull final String string, @Nullable final Alphabet alphabet) throws IllegalArgumentException {
-        return (alphabet != null) ? Decoder.encodeUTF16(string.toUpperCase(), alphabet.getCode()) : string.toUpperCase();
+        return (alphabet != null) ? Decoder.encodeUTF16(string.toUpperCase(), alphabet.getNumber()) : string.toUpperCase();
     }
 
     /**
@@ -431,124 +439,4 @@ public boolean equals(@Nullable final Object obj) {
                 codePrecision2.equals(that.codePrecision2) &&
                 (this.territory.equals(that.territory));
     }
-
-    /**
-     * ----------------------------------------------------------------------
-     * Deprecated methods.
-     * ----------------------------------------------------------------------
-     *
-     * Important: these methods will potentially be removed from the interface in later releases.
-     * It is advised to migrate to the newer variants.
-     */
-
-    /**
-     * Deprecated. Replaced with {@link #getCode}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcode() {
-        return getCode();
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode}.
-     *
-     * @param precision Deprecated.
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodePrecision(final int precision) {
-        return getCode(precision);
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode(int)}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodePrecision0() {
-        return codePrecision0;
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode(int)}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodePrecision1() {
-        return codePrecision1;
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode(int)}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodeMediumPrecision() {
-        return codePrecision1;
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode(int)}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodePrecision2() {
-        return codePrecision2;
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode(int)}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String getMapcodeHighPrecision() {
-        return codePrecision2;
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCode()}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String asLocal() {
-        return getCode();
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCodeWithTerritoryFullname()}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String asInternationalFullName() {
-        return getCodeWithTerritoryFullname();
-    }
-
-    /**
-     * Deprecated. Replaced with {@link #getCodeWithTerritory()}.
-     *
-     * @return Deprecated.
-     */
-    @Deprecated
-    @Nonnull
-    public String asInternationalISO() {
-        return getCodeWithTerritory();
-    }
 }