Deprecated forgotten precision methods; improved unit tests

rijnb · rijnb · commit 01ac04265669 · 2015-05-09T11:10:35.000+02:00
diff --git a/src/main/java/com/mapcode/Mapcode.java b/src/main/java/com/mapcode/Mapcode.java
@@ -82,14 +82,13 @@ public String getMapcode() {
      * 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 0: area is approx 20 x 20 meters; max. distance from original location less than 10 meters.
      *
-     * 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 1: area is approx 4 x 4 meters; max. distance from original location less than 2 meters.
      *
-     * 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.
+     * Precision 2: area is approx 0.8 x 0.8 meters; max. distance from original location less than 0.4 meters.
+     *
+     * The accuracy is slightly better than the figures above, but these figures are safe assumptions.
      *
      * @return Mapcode string.
      */
@@ -113,59 +112,35 @@ public String getMapcodePrecision(final int precision) {
         }
     }
 
-    /**
-     * Alias for {@link #getMapcode}.
-     *
-     * @return Mapcode string.
-     */
+    // Deprecated alias for getMapcodePrecision().
     @Deprecated
     @Nonnull
     public String getMapcodePrecision0() {
         return mapcodePrecision0;
     }
 
-    /**
-     * 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.
-     *
-     * 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).
-     *
-     * @return Medium precision mapcode string.
-     */
+    // Deprecated alias for getMapcodePrecision().
+    @Deprecated
     @Nonnull
     public String getMapcodePrecision1() {
         return mapcodePrecision1;
     }
 
-    /**
-     * Deprecated alias for {@link #getMapcodePrecision1}.
-     */
+    // Deprecated alias for getMapcodePrecision().
     @Deprecated
     @Nonnull
     public String getMapcodeMediumPrecision() {
         return mapcodePrecision1;
     }
 
-    /**
-     * 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.
-     *
-     * 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).
-     *
-     * @return High precision mapcode string.
-     */
+    // Deprecated alias for getMapcodePrecision().
+    @Deprecated
     @Nonnull
     public String getMapcodePrecision2() {
         return mapcodePrecision2;
     }
 
-    // Deprecated alias for {@see #getMapcodePrecision2}.
+    // Deprecated alias for getMapcodePrecision().
     @Deprecated
     @Nonnull
     public String getMapcodeHighPrecision() {
diff --git a/src/main/java/com/mapcode/MapcodeCodec.java b/src/main/java/com/mapcode/MapcodeCodec.java
@@ -47,11 +47,12 @@ private MapcodeCodec() {
      *
      * The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.
      *
-     * 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.
+     * The list is ordered in such a way that the last result is the international code. However, you cannot assume
+     * that the first result is the shortest mapcode. If you want to use the shortest mapcode, use
+     * {@link #encodeToShortest(double, double)}.
      *
-     * The international code can be obtained from the list by using: "results.get(results.size() - 1)".
+     * The international code can be obtained from the list by using: "results.get(results.size() - 1)", or
+     * you can use {@link #encodeToInternational(double, double)}, which is faster.
      *
      * @param latDeg Latitude, accepted range: -90..90.
      * @param lonDeg Longitude, accepted range: -180..180.
@@ -78,8 +79,9 @@ public static List<Mapcode> encode(
      *
      * The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.
      *
-     * The list is ordered in such a way that the first result contains the shortest mapcode (which is usually a
-     * local mapcode).
+     * The list is ordered in such a way that the last result is the international code. However, you cannot assume
+     * 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.
@@ -106,8 +108,8 @@ public static List<Mapcode> encode(
     }
 
     /**
-     * Encode a lat/lon pair to its shortest mapcode without territory information. For a valid lat/lon pair, this will
-     * always yield a mapcode.
+     * Encode a lat/lon pair to its shortest mapcode without specifying territory information. For a valid lat/lon pair,
+     * this will always yield a mapcode.
      *
      * @param latDeg Latitude, accepted range: -90..90.
      * @param lonDeg Longitude, accepted range: -180..180.
diff --git a/src/test/java/com/mapcode/EncodeDecodeTest.java b/src/test/java/com/mapcode/EncodeDecodeTest.java
@@ -31,73 +31,103 @@
 @SuppressWarnings({"JUnitTestMethodWithNoAssertions", "OverlyBroadThrowsClause", "ProhibitedExceptionDeclared"})
 public class EncodeDecodeTest {
     private static final Logger LOG = LoggerFactory.getLogger(EncodeDecodeTest.class);
-
-    private static final int NUMBER_OF_POINTS = 1000;
-    private static final int LOG_LINE_EVERY = 500;
-    private static final double ALLOWED_DISTANCE_DELTA_METERS = 10.0;
-    public static final Gson GSON =
+    private static final Gson GSON =
             new GsonBuilder().serializeSpecialFloatingPointValues().create();
 
+    private static final int NUMBER_OF_POINTS = 5000;
+    private static final int LOG_LINE_EVERY = 100;
+
+    private static final double PRECISION_0_METERS = 10.0;
+    private static final double PRECISION_1_METERS = 2.0;
+    private static final double PRECISION_2_METERS = 0.4;
+
     @Test
     public void encodeDecodeTestFixedSeed() throws Exception {
         LOG.info("encodeDecodeTestFixedSeed");
-        doEncodeDecode(12345678);
+        doEncodeDecode(123212321);
     }
 
     @Test
     public void encodeDecodeTestRandomSeed() throws Exception {
         LOG.info("encodeDecodeTestRandomSeed");
-        doEncodeDecode(System.currentTimeMillis());
+        final long seed = System.currentTimeMillis();
+        LOG.info("encodeDecodeTestRandomSeed: seed={}", seed);
+        doEncodeDecode(seed);
     }
 
     private static void doEncodeDecode(final long seed) throws UnknownMapcodeException {
         final Random randomGenerator = new Random(seed);
+        double maxDistancePrecision0Meters = 0.0;
+        double maxDistancePrecision1Meters = 0.0;
+        double maxDistancePrecision2Meters = 0.0;
         for (int i = 0; i < NUMBER_OF_POINTS; i++) {
             boolean showLogLine = ((i % LOG_LINE_EVERY) == 0);
 
+            // Encode location.
+            final Point encode = Point.fromUniformlyDistributedRandomPoints(randomGenerator);
+            final double latDeg = encode.getLatDeg();
+            final double lonDeg = encode.getLonDeg();
+
+            // Check local and international codes.
+            final Mapcode resultInternational = MapcodeCodec.encodeToInternational(latDeg, lonDeg);
+
+            // Check encodeToShortest and encodeToInternational.
+            final List<Mapcode> resultsAll = MapcodeCodec.encode(latDeg, lonDeg);
+            assertTrue(!resultsAll.isEmpty());
+            assertEquals("encodeToInternational failed, result=" + resultsAll,
+                    resultsAll.get(resultsAll.size() - 1), resultInternational);
+
             // Every point must have a Mapcode.
             boolean found = false;
-            final Point encode = Point.fromUniformlyDistributedRandomPoints(randomGenerator);
 
             // Walk through the list in reverse order to get International first.
             for (final Territory territory : Territory.values()) {
-
-                // Encode location.
-                final double latDeg = encode.getLatDeg();
-                final double lonDeg = encode.getLonDeg();
-
-                final List<Mapcode> results = MapcodeCodec.encode(latDeg, lonDeg, territory);
-                for (final Mapcode result : results) {
+                final List<Mapcode> resultsLimited = MapcodeCodec.encode(latDeg, lonDeg, territory);
+                for (final Mapcode result : resultsLimited) {
                     found = true;
                     if (showLogLine) {
                         LOG.info("encodeDecodeTest: #{}/{}, encode={}, {} {} --> results={}",
-                                i, NUMBER_OF_POINTS, latDeg, lonDeg, territory, GSON.toJson(results));
+                                i, NUMBER_OF_POINTS, latDeg, lonDeg, territory, GSON.toJson(resultsLimited));
                     }
 
-                    // Decode location, up to '/'.
-                    final String mapcode = result.getMapcode();
-
                     // Check if the territory matches.
+                    final String mapcodePrecision0 = result.getMapcodePrecision(0);
+                    final String mapcodePrecision1 = result.getMapcodePrecision(1);
+                    final String mapcodePrecision2 = result.getMapcodePrecision(2);
                     assertEquals(territory, result.getTerritory());
 
-                    final Point decodeLocation = MapcodeCodec.decode(mapcode, territory);
-                    final double distanceMeters = Point.distanceInMeters(encode, decodeLocation);
+                    // Check max distance.
+                    final Point decodeLocationPrecision0 = MapcodeCodec.decode(mapcodePrecision0, territory);
+                    final Point decodeLocationPrecision1 = MapcodeCodec.decode(mapcodePrecision1, territory);
+                    final Point decodeLocationPrecision2 = MapcodeCodec.decode(mapcodePrecision2, territory);
+                    final double distancePrecision0Meters = Point.distanceInMeters(encode, decodeLocationPrecision0);
+                    final double distancePrecision1Meters = Point.distanceInMeters(encode, decodeLocationPrecision1);
+                    final double distancePrecision2Meters = Point.distanceInMeters(encode, decodeLocationPrecision2);
+
+                    maxDistancePrecision0Meters = Math.max(maxDistancePrecision0Meters, distancePrecision0Meters);
+                    maxDistancePrecision1Meters = Math.max(maxDistancePrecision1Meters, distancePrecision1Meters);
+                    maxDistancePrecision2Meters = Math.max(maxDistancePrecision2Meters, distancePrecision2Meters);
+
+                    assertTrue("distancePrecision0Meters=" + distancePrecision0Meters + " >= " + PRECISION_0_METERS,
+                            distancePrecision0Meters < PRECISION_0_METERS);
+                    assertTrue("distancePrecision1Meters=" + distancePrecision1Meters + " >= " + PRECISION_1_METERS,
+                            distancePrecision1Meters < PRECISION_1_METERS);
+                    assertTrue("distancePrecision2Meters=" + distancePrecision2Meters + " >= " + PRECISION_2_METERS,
+                            distancePrecision2Meters < PRECISION_2_METERS);
 
                     if (showLogLine) {
                         LOG.info("encodeDecodeTest: #{}/{}, result={}, mapcode={}, territory={} --> " +
                                         "lat={}, lon={}; delta={}", i, NUMBER_OF_POINTS,
-                                result, mapcode, territory.getFullName(), decodeLocation.getLatDeg(),
-                                decodeLocation.getLonDeg(), distanceMeters);
+                                result, mapcodePrecision0, territory.getFullName(), decodeLocationPrecision0.getLatDeg(),
+                                decodeLocationPrecision0.getLonDeg(), distancePrecision0Meters);
                         LOG.info("");
                     }
-
-                    // Check if the distance is not too great.
-                    assertTrue("distanceMeters=" + distanceMeters + " >= " + ALLOWED_DISTANCE_DELTA_METERS,
-                            distanceMeters < ALLOWED_DISTANCE_DELTA_METERS);
                     showLogLine = false;
                 }
             }
             assertTrue(found);
         }
+        LOG.info("encodeDecodeTest: maximum distances, precision 0, 1, 2: {}, {}, {} meters, ",
+                maxDistancePrecision0Meters, maxDistancePrecision1Meters, maxDistancePrecision2Meters);
     }
 }
diff --git a/src/test/java/com/mapcode/ReferenceFileTest.java b/src/test/java/com/mapcode/ReferenceFileTest.java
@@ -33,7 +33,7 @@
 @SuppressWarnings({"ProhibitedExceptionDeclared", "OverlyBroadThrowsClause"})
 public class ReferenceFileTest {
     private static final Logger LOG = LoggerFactory.getLogger(ReferenceFileTest.class);
-    public static final Gson GSON = new GsonBuilder().serializeSpecialFloatingPointValues().create();
+    private static final Gson GSON = new GsonBuilder().serializeSpecialFloatingPointValues().create();
 
     private static final String RANDOM_REFERENCE_FILE_1 = "/random_1k.txt";
     private static final String RANDOM_REFERENCE_FILE_2 = "/random_10k.txt";
@@ -142,6 +142,33 @@ private static void checkFile(@Nonnull final String baseFileName) throws Excepti
                 }
 
                 // Check the number of mapcodes.
+                if (results.isEmpty()) {
+                    LOG.error("checkFile: encode fails, no results found for reference={}", reference);
+                    ++error;
+                }
+
+                /**
+                 * Check encodeToShortest.
+                 */
+                final Mapcode resultShortest = MapcodeCodec.encodeToShortest(reference.point.getLatDeg(), reference.point.getLonDeg());
+                final Mapcode expectedShortest = results.get(0);
+                if (!resultShortest.asLocal().equals(expectedShortest.asLocal())) {
+                    LOG.error("checkFile: encodeToShortest fails, expected={}, got={} for reference",
+                            expectedShortest, resultShortest, reference);
+                    ++error;
+                }
+
+                /**
+                 * Check encodeToInternational.
+                 */
+                final Mapcode resultInternational = MapcodeCodec.encodeToInternational(reference.point.getLatDeg(), reference.point.getLonDeg());
+                final Mapcode expectedInternational = results.get(results.size() - 1);
+                if (!resultInternational.equals(expectedInternational)) {
+                    LOG.error("checkFile: encodeToInternational fails, expected={}, got={} for reference",
+                            expectedInternational, resultInternational, reference);
+                    ++error;
+                }
+
 
                 // Check the size and order of the results with a single assertion.
                 //
diff --git a/src/test/java/com/mapcode/TerritoryTest.java b/src/test/java/com/mapcode/TerritoryTest.java
@@ -37,8 +37,8 @@ public void emptyTerritoryCodeTest() throws Exception {
     public void checkDash() throws Exception {
         LOG.info("checkDash");
         assertEquals(Territory.IN_MN, Territory.fromString("IND-MN"));
-        assertEquals(Territory.US_MN, Territory.fromString("USA-MN"));
         assertEquals(Territory.IN_MN, Territory.fromString("IND_MN"));
+        assertEquals(Territory.US_MN, Territory.fromString("USA-MN"));
         assertEquals(Territory.US_MN, Territory.fromString("USA_MN"));
     }
 

Original file line number	Diff line number	Diff line change
`@@ -47,11 +47,12 @@ private MapcodeCodec() {`
`47`	`47`	`*`
`48`	`48`	`* The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.`
`49`	`49`	`*`
`50`		`- * The list is ordered in such a way that the first result contains the shortest mapcode (which is usually a`
`51`		`- * local mapcode). The last result contains the "International" or world-wide mapcode, which is always`
`52`		`- * unambiguous, even when used without a territory specification.`
	`50`	`+ * The list is ordered in such a way that the last result is the international code. However, you cannot assume`
	`51`	`+ * that the first result is the shortest mapcode. If you want to use the shortest mapcode, use`
	`52`	`+ * {@link #encodeToShortest(double, double)}.`
`53`	`53`	`*`
`54`		`- * The international code can be obtained from the list by using: "results.get(results.size() - 1)".`
	`54`	`+ * The international code can be obtained from the list by using: "results.get(results.size() - 1)", or`
	`55`	`+ * you can use {@link #encodeToInternational(double, double)}, which is faster.`
`55`	`56`	`*`
`56`	`57`	`* @param latDeg Latitude, accepted range: -90..90.`
`57`	`58`	`* @param lonDeg Longitude, accepted range: -180..180.`
`@@ -78,8 +79,9 @@ public static List<Mapcode> encode(`
`78`	`79`	`*`
`79`	`80`	`* The returned result list will always contain at least 1 mapcode, because every lat/lon pair can be encoded.`
`80`	`81`	`*`
`81`		`- * The list is ordered in such a way that the first result contains the shortest mapcode (which is usually a`
`82`		`- * local mapcode).`
	`82`	`+ * The list is ordered in such a way that the last result is the international code. However, you cannot assume`
	`83`	`+ * that the first result is the shortest mapcode. If you want to use the shortest mapcode, use`
	`84`	`+ * {@link #encodeToShortest(double, double, Territory)}.`
`83`	`85`	`*`
`84`	`86`	`* @param latDeg Latitude, accepted range: -90..90.`
`85`	`87`	`* @param lonDeg Longitude, accepted range: -180..180.`
`@@ -106,8 +108,8 @@ public static List<Mapcode> encode(`
`106`	`108`	`}`
`107`	`109`
`108`	`110`	`/**`
`109`		`- * Encode a lat/lon pair to its shortest mapcode without territory information. For a valid lat/lon pair, this will`
`110`		`- * always yield a mapcode.`
	`111`	`+ * Encode a lat/lon pair to its shortest mapcode without specifying territory information. For a valid lat/lon pair,`
	`112`	`+ * this will always yield a mapcode.`
`111`	`113`	`*`
`112`	`114`	`* @param latDeg Latitude, accepted range: -90..90.`
`113`	`115`	`* @param lonDeg Longitude, accepted range: -180..180.`
Original file line number	Diff line number	Diff line change
`@@ -37,8 +37,8 @@ public void emptyTerritoryCodeTest() throws Exception {`
`37`	`37`	`public void checkDash() throws Exception {`
`38`	`38`	`LOG.info("checkDash");`
`39`	`39`	`assertEquals(Territory.IN_MN, Territory.fromString("IND-MN"));`
`40`		`- assertEquals(Territory.US_MN, Territory.fromString("USA-MN"));`
`41`	`40`	`assertEquals(Territory.IN_MN, Territory.fromString("IND_MN"));`
	`41`	`+ assertEquals(Territory.US_MN, Territory.fromString("USA-MN"));`
`42`	`42`	`assertEquals(Territory.US_MN, Territory.fromString("USA_MN"));`
`43`	`43`	`}`
`44`	`44`