Fixed code style, Java 8 and deprecated number of redundant toString variants of Mapcode

Author: rijnb

src/main/java/com/mapcode/Common.java

@@ -20,7 +20,7 @@
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the Mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class contains common data structures and methods used by the Mapcode implementation.
  */
 class Common {

src/main/java/com/mapcode/Data.java

@@ -23,7 +23,7 @@
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the Mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class the data class for Mapcode codex items.
  */
 class Data {

src/main/java/com/mapcode/DataAccess.java

@@ -24,7 +24,7 @@
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the Mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class contains the module that reads the Mapcode areas into memory and processes them.
  */
 class DataAccess {

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

@@ -24,12 +24,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
-import static com.mapcode.Common.countCityCoordinatesForCountry;
-import static com.mapcode.Common.getFirstNamelessRecord;
-import static com.mapcode.Common.nc;
-import static com.mapcode.Common.xDivider;
-import static com.mapcode.Common.xSide;
-import static com.mapcode.Common.ySide;
+import static com.mapcode.Common.*;
 
 class Encoder {
     private static final Logger LOG = LoggerFactory.getLogger(Encoder.class);

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

@@ -24,9 +24,9 @@
 /**
  * This class defines a single mapcode encoding result, including the mapcode itself and the
  * territory definition.
- *
+ * <p/>
  * Note that the constructor will throw an {@link IllegalArgumentException} if the syntax of the mapcode
- * is not correct. It does not throw an {@link UnknownMapcodeException}, because the mapcode
+ * is not correct. It does not throw an {@link com.mapcode.UnknownMapcodeException}, because the mapcode
  * is not checked for validity, other than its syntax.
  */
 public final class Mapcode {
@@ -63,7 +63,7 @@ public Mapcode(
     /**
      * Get the Mapcode string (without territory information) with standard precision.
      * The returned mapcode does not include the '-' separator and additional digits.
-     *
+     * <p/>
      * The returned precision is approximately 5 meters. The precision is defined as the maximum distance to the
      * (latitude, longitude) pair that encoded to this mapcode, which means the mapcode defines an area of
      * approximately 10 x 10 meters (100 m2).
@@ -75,6 +75,24 @@ public String getMapcode() {
         return mapcodePrecision0;
     }
 
+    /**
+     * Get the Mapcode string (without territory information) with a specified precision.
+     * The returned mapcode includes a '-' separator and additional digits for precisions 1 and 2.
+     *
+     * The precision defines the size of a geographical area a single mapcode covers. This means It also defines
+     * the maximum distance to the location, a (latitude, longitude) pair, that encoded to this mapcode.
+     *
+     * Precision 0 uses an area of approx 10 x 10 meters, which means the original location and the location
+     * as obtained by decoding the encoded mapcode are no further than 5 meters apart.
+     *
+     * Precision 1 uses an area of approx 10 x 10 meters, which means the original location and the location
+     * as obtained by decoding the encoded mapcode are no further than 5 meters apart.
+     *
+     * Precision 2 uses an area of approx 10 x 10 meters, which means the original location and the location
+     * as obtained by decoding the encoded mapcode are no further than 5 meters apart.
+     *
+     * @return Mapcode string.
+     */
     /**
      * Alias for {@link #getMapcode}.
      *
@@ -100,6 +118,7 @@ public String getMapcodePrecision(final int precision) {
      *
      * @return Mapcode string.
      */
+    @Deprecated
     @Nonnull
     public String getMapcodePrecision0() {
         return mapcodePrecision0;
@@ -109,7 +128,7 @@ public String getMapcodePrecision0() {
      * Get the medium-precision mapcode string (without territory information).
      * The returned mapcode includes the '-' separator and 1 additional digit, if available.
      * If a medium precision code is not available, the regular mapcode is returned.
-     *
+     * <p/>
      * The returned precision is approximately 1 meter. The precision is defined as the maximum distance to the
      * (latitude, longitude) pair that encoded to this mapcode, which means the mapcode defines an area of
      * approximately 2 x 2 meters (4 m2).
@@ -134,7 +153,7 @@ public String getMapcodeMediumPrecision() {
      * Get the high-precision mapcode string (without territory information).
      * The returned mapcode includes the '-' separator and 2 additional digit2, if available.
      * If a high precision code is not available, the regular mapcode is returned.
-     *
+     * <p/>
      * The returned precision is approximately 16 centimeters. The precision is defined as the maximum distance to the
      * (latitude, longitude) pair that encoded to this mapcode, which means the mapcode defines an area of
      * approximately 32 x 32 centimeters (0.1 m2).
@@ -203,7 +222,7 @@ public enum MapcodeFormatType {
      * 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.
-     *
+     * <p/>
      * 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.
      *
@@ -258,7 +277,7 @@ public static String convertToAscii(@Nonnull final String mapcode) {
 
     /**
      * Return the local mapcode string, potentially ambiguous.
-     *
+     * <p/>
      * Example:
      * 49.4V
      *
@@ -273,13 +292,19 @@ public String asLocal() {
      * Return the full international mapcode, including the full name of the territory and the Mapcode itself.
      * The format of the code is:
      * full-territory-name mapcode
-     *
+     * <p/>
      * Example:
      * Netherlands 49.4V           (regular code)
      * Netherlands 49.4V-K2        (high precision code)
      *
+     * @param precision Precision specifier. Range: [0, 2].
      * @return Full international mapcode.
      */
+    @Nonnull
+    public String asInternationalFullName(final int precision) {
+        return territory.getFullName() + ' ' + getMapcodePrecision(precision);
+    }
+
     @Nonnull
     public String asInternationalFullName() {
         return territory.getFullName() + ' ' + mapcodePrecision0;
@@ -290,18 +315,25 @@ public String asInternationalFullName() {
      * International codes use a territory code "AAA".
      * The format of the code is:
      * short-territory-name mapcode
-     *
+     * <p/>
      * Example:
      * NLD 49.4V                   (regular code)
      * NLD 49.4V-K2                (high-precision code)
      *
+     * @param precision Precision specifier. Range: [0, 2].
      * @return Short-hand international mapcode.
      */
+    @Nonnull
+    public String asInternationalISO(final int precision) {
+        return territory.toString() + ' ' + getMapcodePrecision(precision);
+    }
+
     @Nonnull
     public String asInternationalISO() {
         return territory.toString() + ' ' + mapcodePrecision0;
     }
 
+
     @Nonnull
     @Override
     public String toString() {
@@ -310,7 +342,7 @@ public String toString() {
 
     @Override
     public int hashCode() {
-        return Arrays.deepHashCode(new Object[]{mapcodePrecision0, territory});
+        return Arrays.deepHashCode(new Object[]{mapcodePrecision0, mapcodePrecision1, mapcodePrecision2, territory});
     }
 
     @Override
@@ -322,6 +354,9 @@ public boolean equals(final Object obj) {
             return false;
         }
         final Mapcode that = (Mapcode) obj;
-        return mapcodePrecision0.equals(that.mapcodePrecision0) && (this.territory.equals(that.territory));
+        return mapcodePrecision0.equals(that.mapcodePrecision0) &&
+                mapcodePrecision1.equals(that.mapcodePrecision1) &&
+                mapcodePrecision2.equals(that.mapcodePrecision2) &&
+                (this.territory.equals(that.territory));
     }
 }

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

@@ -26,7 +26,7 @@
  * ----------------------------------------------------------------------------------------------
  * Mapcode public interface.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class is the external Java interface for encoding and decoding mapcodes.
  */
 public final class MapcodeCodec {
@@ -44,13 +44,13 @@ private MapcodeCodec() {
     /**
      * Encode a lat/lon pair to a mapcode with territory information. This produces a non-empty list of mapcode,
      * with at the very least 1 mapcodes for the lat/lon, which is the "International" mapcode.
-     *
+     * <p/>
      * The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.
-     *
+     * <p/>
      * The list is ordered in such a way that the first result contains the shortest mapcode (which is usually a
      * local mapcode). The last result contains the "International" or world-wide mapcode, which is always
      * unambiguous, even when used without a territory specification.
-     *
+     * <p/>
      * The international code can be obtained from the list by using: "results.get(results.size() - 1)".
      *
      * @param latDeg Latitude, accepted range: -90..90.
@@ -75,9 +75,9 @@ public static List<Mapcode> encode(
     /**
      * Encode a lat/lon pair to a mapcode with territory information, for a specific territory. This produces a
      * potentially empty list of mapcodes (empty if the lat/lon does not fall within the territory for mapcodes).
-     *
+     * <p/>
      * The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.
-     *
+     * <p/>
      * The list is ordered in such a way that the first result contains the shortest mapcode (which is usually a
      * local mapcode).
      *
@@ -191,7 +191,7 @@ public static Mapcode encodeToInternational(
     /**
      * Decode a mapcode to a Point. The decoding process may fail for local mapcodes,
      * because no territory context is supplied (world-wide).
-     *
+     * <p/>
      * The accepted format is:
      * {mapcode}
      * {territory-code} {mapcode}
@@ -231,7 +231,7 @@ public static Point decode(
 
     /**
      * Decode a mapcode to a Point. A reference territory is supplied for disambiguation (only used if applicable).
-     *
+     * <p/>
      * The accepted format is:
      * {mapcode}        (note that a territory code is not allowed here)
      *

src/main/java/com/mapcode/ParentTerritory.java

@@ -22,7 +22,7 @@
  * ----------------------------------------------------------------------------------------------
  * Mapcode public interface.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class defines "parent territories" for territories that have multiple territory codes.
  */
 public enum ParentTerritory {

src/main/java/com/mapcode/Point.java

@@ -17,6 +17,7 @@
 package com.mapcode;
 
 import javax.annotation.Nonnull;
+import java.util.Arrays;
 import java.util.Random;
 
 import static com.mapcode.CheckArgs.checkNonnull;
@@ -25,7 +26,7 @@
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class defines a class for lat/lon points.
  */
 public class Point {
@@ -119,12 +120,6 @@ public double getLonDeg() {
         return lonDeg;
     }
 
-    @Override
-    @Nonnull
-    public String toString() {
-        return "(" + latDeg + ", " + lonDeg + ')';
-    }
-
     public static int degToMicroDeg(final double deg) {
         //noinspection NumericCastThatLosesPrecision
         return (int) Math.round(deg * MICRODEG_TO_DEG_FACTOR);
@@ -292,4 +287,31 @@ void setUndefined() {
     boolean isDefined() {
         return defined;
     }
+
+    @Nonnull
+    @Override
+    public String toString() {
+        return defined ? ("(" + latDeg + ", " + lonDeg + ')') : "undefined";
+    }
+
+    @SuppressWarnings("NonFinalFieldReferencedInHashCode")
+    @Override
+    public int hashCode() {
+        return Arrays.hashCode(new Object[]{latDeg, lonDeg, defined});
+    }
+
+    @SuppressWarnings("NonFinalFieldReferenceInEquals")
+    @Override
+    public boolean equals(final Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (!(obj instanceof Point)) {
+            return false;
+        }
+        final Point that = (Point) obj;
+        return (Double.compare(this.latDeg, that.latDeg) == 0) &&
+                (Double.compare(this.lonDeg, that.lonDeg) == 0) &&
+                (this.defined == that.defined);
+    }
 }

src/main/java/com/mapcode/Range.java

@@ -24,7 +24,7 @@
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the Mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class contains a class for dealing with ranges of comparable items.
  */
 class Range<T extends Comparable<T>> {

src/main/java/com/mapcode/SubArea.java

@@ -21,18 +21,14 @@
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
+import java.util.*;
 import java.util.Map.Entry;
-import java.util.SortedMap;
-import java.util.TreeMap;
 
 /**
  * ----------------------------------------------------------------------------------------------
  * Package private implementation class. For internal use within the mapcode implementation only.
  * ----------------------------------------------------------------------------------------------
- *
+ * <p/>
  * This class contains a class that defines an area for local mapcodes.
  */
 class SubArea {