Fixes issue with Clipperton Island CPT/CP

rijnb · rijnb · commit 18e784e961be · 2018-05-03T16:25:37.000+02:00
diff --git a/README.md b/README.md
@@ -296,15 +296,15 @@ Again, if encoding succeeded, the first mapcode is the shortest one and the last
 globally unique international mapcode.
 
 **`List<Mapcode> encodeRestrictToCountryISO2/ISO3(double latitude, double longitude, String countryISO2/ISO3)`** encodes a (latitude,
-longitude) pair, where encoding is restricted to a specific country, provided as an ISO 3166-2 or -3 country code. 
+longitude) pair, where encoding is restricted to a specific country, provided as an ISO 3166 2 or 3 characters country code. 
     
 Example:
 
     List<Mapcode> results = MapcodeCodec.encodeRestrictToCountryISO2(lat, lon, "BR");
-    // Returns a list of mapcodes retricted to Brazil (not: IN-BR).
+    // Returns a list of mapcodes retricted to Brazil, so their territories start with BR- or BRA.
 
     List<Mapcode> results = MapcodeCodec.encodeRestrictToCountryISO3(lat, lon, "MEX");
-    // Returns a list of mapcodes retricted to Mexico.
+    // Returns a list of mapcodes retricted to Mexico, so their therritories start with MX- or MEX.
 
 **Important notice:** The codes used in these methods asume the ISO conversion, 
 not the `fromString` conversion from `Territory`. For example, `Territory.fromString("BR")` 
@@ -397,7 +397,7 @@ smaller areas, so mapcodes can remain fairly short:
 Rather than using the 3-letter territory code for mapcodes in these territories, you'd probably want
 to use the `TT-XXX` form, where `XXX` defines the subterritory (state, province, etc.) 
 
-Two convenience methods are provided to create a territory code from an ISO 3166-2 or -3 code: 
+Two convenience methods are provided to create a territory code from an ISO 3166 2 or 3 character code: 
 `Territory.fromCountryISO2(String)` and `Territory.fromCountryISO3(String)`. 
 
 
@@ -484,7 +484,7 @@ These are the release notes for the Java library for mapcodes.
 
 * General cleanup after running stricter IntelliJ inspections profile.
 
-* Added convenience methods to restrict encoded mapcodes to specific ISO 3166-2 or 3 country codes.
+* Added convenience methods to restrict encoded mapcodes to specific ISO 3166 2 or 3 character country codes.
 
 ### 2.4.5
 
diff --git a/src/main/java/com/mapcode/MapcodeCodec.java b/src/main/java/com/mapcode/MapcodeCodec.java
@@ -114,14 +114,14 @@ public static List<Mapcode> encode(@Nonnull final Point point,
 
     /**
      * Encode a lat/lon pair to a list of mapcodes, like {@link #encode(double, double)}.
-     * The result list is limited to those mapcodes that belong to the provided ISO 3166-2 country code.
+     * The result list is limited to those mapcodes that belong to the provided ISO 3166 country code, 2 characters.
      * For example, if you wish to restrict the list to Mexican mapcodes, use "MX". This would
      * produce a result list of mapcodes with territories that start with "MX-" (note that a
      * mapcode that starts with "MEX" is not returned in that case.)
      *
      * @param latDeg      Latitude, accepted range: -90..90.
      * @param lonDeg      Longitude, accepted range: -180..180.
-     * @param countryISO2 ISO 3166-2 country code.
+     * @param countryISO2 ISO 3166 country code, 2 characters.
      * @return Possibly empty, ordered list of mapcode information records, see {@link Mapcode}.
      * @throws IllegalArgumentException Thrown if latitude or longitude are out of range, or if the ISO code is invalid.
      */
@@ -162,14 +162,14 @@ public static List<Mapcode> encodeRestrictToCountryISO2(@Nonnull final Point poi
 
     /**
      * Encode a lat/lon pair to a list of mapcodes, like {@link #encode(double, double)}.
-     * The result list is limited to those mapcodes that belong to the provided ISO 3166-3 country code.
+     * The result list is limited to those mapcodes that belong to the provided ISO 3166 country code, 3 characters.
      * For example, if you wish to restrict the list to Mexican mapcodes, use "MEX". This would
      * produce a result list of mapcodes with territories that start with "MEX" (note that
      * mapcode that starts with "MX-" are not returned in that case.)
      *
      * @param latDeg      Latitude, accepted range: -90..90.
      * @param lonDeg      Longitude, accepted range: -180..180.
-     * @param countryISO3 ISO 3166-3 country code.
+     * @param countryISO3 ISO 3166 country code, 3 characters.
      * @return Possibly empty, ordered list of mapcode information records, see {@link Mapcode}.
      * @throws IllegalArgumentException Thrown if latitude or longitude are out of range, or if the ISO code is invalid.
      */
@@ -178,8 +178,7 @@ public static List<Mapcode> encodeRestrictToCountryISO3(final double latDeg, fin
                                                             @Nonnull final String countryISO3)
             throws IllegalArgumentException {
         checkNonnull("countryISO3", countryISO3);
-        final Territory restrictToTerritory = Territory.fromCountryISO3(countryISO3);
-        return encode(latDeg, lonDeg, restrictToTerritory);
+        return encodeRestrictToCountryISO2(latDeg, lonDeg, Territory.getCountryISO2FromISO3(countryISO3));
     }
 
     @Nonnull
diff --git a/src/main/java/com/mapcode/Territory.java b/src/main/java/com/mapcode/Territory.java
@@ -655,10 +655,10 @@ public Alphabet[] getAlphabets() {
      */
     @Nonnull
     static Territory fromNumber(final int number) throws UnknownTerritoryException {
-        if ((number < 0) || (number >= codeList.size())) {
+        if ((number < 0) || (number >= CODE_LIST.size())) {
             throw new UnknownTerritoryException(number);
         }
-        return codeList.get(number);
+        return CODE_LIST.get(number);
     }
 
     /**
@@ -704,47 +704,66 @@ public static Territory fromString(@Nonnull final String alphaCode,
         return createFromString(alphaCode, parentTerritory);
     }
 
-    // Keep a mapping from ISO3 to ISO2 codes. This map is used to make sure valid ISO3 codes are being used.
-    private static final Map<String, String> MAP_ISO3_TO_ISO2;
+    /**
+     * Create a Territory object from a valid ISO2 country code.
+     *
+     * @param countryISO2 ISO 3166 country code, 2 characters.
+     * @return Territory object for the country.
+     * @throws IllegalArgumentException Thrown if the country code is not a valid ISO 3166 code, 2 characters.
+     */
+    @Nonnull
+    public static Territory fromCountryISO2(@Nonnull final String countryISO2) {
+        return fromString(getCountryISO3FromISO2(countryISO2));
+    }
 
-    static {
-        final String[] countries = Locale.getISOCountries();
-        MAP_ISO3_TO_ISO2 = new HashMap<String, String>(countries.length);
-        for (final String countryISO2 : countries) {
-            final String countryISO3 = new Locale("", countryISO2).getISO3Country();
-            MAP_ISO3_TO_ISO2.put(countryISO3.toUpperCase(), countryISO2.toUpperCase());
+    /**
+     * Return the ISO 3166 2 character country code for a ISO 3166 3 character code.
+     *
+     * @param countryISO3 ISO 3166 country code, 3 characters.
+     * @return ISO 3166 country code, 2 characters.
+     */
+    @Nonnull
+    public static String getCountryISO2FromISO3(@Nonnull final String countryISO3) {
+        final String countryISO2 = MAP_ISO3_TO_ISO2.get(countryISO3.toUpperCase());
+        if (countryISO2 == null) {
+            throw new IllegalArgumentException("Parameter " + countryISO3 + " must be a valid ISO 3166 country code, 3 characters");
         }
+        return countryISO2;
     }
 
     /**
-     * Create a Territory object from a valid ISO2 country code.
+     * Return the ISO 3166 3 character country code for a ISO 3166 2 character code.
      *
-     * @param countryISO2 ISO 3166-2 country code.
-     * @return Territory object for the country.
-     * @throws IllegalArgumentException Thrown if the country code is not a valid ISO 3166-2 code.
+     * @param countryISO2 ISO 3166 country code, 2 characters.
+     * @return ISO 3166 country code, characters.
      */
     @Nonnull
-    public static Territory fromCountryISO2(@Nonnull final String countryISO2) {
+    public static String getCountryISO3FromISO2(@Nonnull final String countryISO2) {
+        // Clipperton Island not recognized by Java - treat separately.
+        if ("CP".equalsIgnoreCase(countryISO2)) {
+            return "CPT";
+        }
+
+        // Otherwise, use Java locales.
         final Locale locale = new Locale("", countryISO2);
         try {
-            final String countryISO3 = locale.getISO3Country().toUpperCase();
-            return fromString(countryISO3);
+            return locale.getISO3Country().toUpperCase();
         } catch (final MissingResourceException ignored) {
-            throw new IllegalArgumentException("Parameter " + countryISO2 + " must be a valid ISO 3166-2 country code");
+            throw new IllegalArgumentException("Parameter " + countryISO2 + " must be a valid ISO 3166 country code, 2 characters");
         }
     }
 
     /**
-     * Create a Territory object from a valid ISO 3166-3 country code.
+     * Create a Territory object from a valid ISO 3166 country code, 3 characters.
      *
-     * @param countryISO3 ISO 3166-3 country code.
+     * @param countryISO3 ISO 3166 country code, 3 characters.
      * @return Territory object for the country.
-     * @throws IllegalArgumentException Thrown if the country code is not a valid ISO 3166-3 code.
+     * @throws IllegalArgumentException Thrown if the country code is not a valid ISO 3166 code, 3 characters.
      */
     @Nonnull
     public static Territory fromCountryISO3(@Nonnull final String countryISO3) {
         if (!MAP_ISO3_TO_ISO2.containsKey(countryISO3.toUpperCase())) {
-            throw new IllegalArgumentException("Parameter " + countryISO3 + " must be a valid ISO 3166-3 country code");
+            throw new IllegalArgumentException("Parameter " + countryISO3 + " must be a valid ISO 3166 country code, 3 characters");
         }
         return fromString(countryISO3);
     }
@@ -798,7 +817,7 @@ public String toAlphaCode(@Nonnull final AlphaCodeFormat format, @Nullable final
             if (index != -1) {
                 assert name().length() > (index + 1);
                 final String shortName = name().substring(index + 1);
-                if ((format == AlphaCodeFormat.MINIMAL) || (nameMap.get(shortName).size() == 1)) {
+                if ((format == AlphaCodeFormat.MINIMAL) || (NAME_MAP.get(shortName).size() == 1)) {
                     result = shortName;
                 }
             }
@@ -833,7 +852,7 @@ public boolean isSubdivision() {
      * @return True if this territory contains other territory subdivisions.
      */
     public boolean hasSubdivisions() {
-        return parentList.contains(this);
+        return PARENT_LIST.contains(this);
     }
 
     /**
@@ -880,21 +899,36 @@ public boolean hasSubdivisions() {
         this.fullNameAliases = (fullNameAliases == null) ? new String[]{} : fullNameAliases;
     }
 
+    // Keep a mapping from ISO3 to ISO2 codes. This map is used to make sure valid ISO3 codes are being used.
     @Nonnull
-    private static final List<Territory> codeList;
+    private static final Map<String, String> MAP_ISO3_TO_ISO2;
     @Nonnull
-    private static final Map<String, List<Territory>> nameMap;
+    private static final List<Territory> CODE_LIST;
     @Nonnull
-    private static final List<Territory> parentList;
+    private static final Map<String, List<Territory>> NAME_MAP;
+    @Nonnull
+    private static final List<Territory> PARENT_LIST;
+
+    static {
+        final String[] countries = Locale.getISOCountries();
+        MAP_ISO3_TO_ISO2 = new HashMap<String, String>(countries.length);
+        for (final String countryISO2 : countries) {
+            final String countryISO3 = new Locale("", countryISO2).getISO3Country();
+            MAP_ISO3_TO_ISO2.put(countryISO3.toUpperCase(), countryISO2.toUpperCase());
+        }
+
+        // Add Clipperton Island (not recognized by Java).
+        MAP_ISO3_TO_ISO2.put("CPT", "CP");
+    }
 
     /**
      * Static checking of the static data structures.
      */
     static {
         final String errorPrefix = "Initializing error: ";
-        codeList = new ArrayList<Territory>();
-        nameMap = new HashMap<String, List<Territory>>();
-        parentList = new ArrayList<Territory>();
+        CODE_LIST = new ArrayList<Territory>();
+        NAME_MAP = new HashMap<String, List<Territory>>();
+        PARENT_LIST = new ArrayList<Territory>();
         int min = Integer.MAX_VALUE;
         int max = Integer.MIN_VALUE;
         final Set<Integer> territoryNumbers = new HashSet<Integer>();
@@ -915,13 +949,13 @@ public boolean hasSubdivisions() {
             }
             territoryNumbers.add(territory.getNumber());
 
-            final int initialCodeListSize = codeList.size();
+            final int initialCodeListSize = CODE_LIST.size();
             for (int i = initialCodeListSize; i <= territory.number; i++) {
-                codeList.add(null);
+                CODE_LIST.add(null);
             }
-            codeList.set(territory.number, territory);
-            if ((territory.parentTerritory != null) && !parentList.contains(territory.parentTerritory)) {
-                parentList.add(territory.parentTerritory);
+            CODE_LIST.set(territory.number, territory);
+            if ((territory.parentTerritory != null) && !PARENT_LIST.contains(territory.parentTerritory)) {
+                PARENT_LIST.add(territory.parentTerritory);
             }
 
             // Check if territory name is unique.
@@ -985,7 +1019,7 @@ private static Territory createFromString(@Nonnull final String alphaCode,
                 alphaCode.trim().replace('_', '-')).toUpperCase();
 
         // Try as alpha code.
-        final List<Territory> territories = nameMap.get(trimmed);
+        final List<Territory> territories = NAME_MAP.get(trimmed);
         if (territories != null) {
             if (parentTerritory == null) {
                 return territories.get(0);
@@ -1065,8 +1099,8 @@ private static void addNameWithSeperatorVariants(@Nonnull final String name, @No
     }
 
     private static void addName(@Nonnull final String name, @Nonnull final Territory territory) {
-        if (nameMap.containsKey(name)) {
-            final List<Territory> territories = nameMap.get(name);
+        if (NAME_MAP.containsKey(name)) {
+            final List<Territory> territories = NAME_MAP.get(name);
 
             // Add child territories in the order the parents are declared.
             // This results in consistent decoding of ambiguous territory names.
@@ -1098,7 +1132,7 @@ private static void addName(@Nonnull final String name, @Nonnull final Territory
         } else {
             final ArrayList<Territory> arrayList = new ArrayList<Territory>();
             arrayList.add(territory);
-            nameMap.put(name, arrayList);
+            NAME_MAP.put(name, arrayList);
         }
     }
 }
diff --git a/src/test/java/com/mapcode/EncoderTest.java b/src/test/java/com/mapcode/EncoderTest.java
@@ -22,8 +22,7 @@
 
 import java.util.List;
 
-import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.*;
 
 @SuppressWarnings({"OverlyBroadThrowsClause", "ProhibitedExceptionDeclared", "ValueOfIncrementOrDecrementUsed", "MagicNumber"})
 public class EncoderTest {
@@ -274,51 +273,56 @@ public void testEncodeCiudadJuarez() {
     }
 
     @Test
-    public void testEncodeRestrictToCountryISO2CountryWithSubdivision() {
-        LOG.info("testEncodeRestrictToCountryISO2CountryWithSubdivision");
+    public void testEncodeRestrictToCountryISOCountryWithSubdivision() {
+        LOG.info("testEncodeRestrictToCountryISOCountryWithSubdivision");
         final List<Mapcode> mapcodesMX = MapcodeCodec.encodeRestrictToCountryISO2(CIUDAD_JUAREZ, "MX");
+        final List<Mapcode> mapcodesMEX = MapcodeCodec.encodeRestrictToCountryISO3(CIUDAD_JUAREZ, "MEX");
         assertEquals(7, mapcodesMX.size());
+        assertEquals(7, mapcodesMEX.size());
         assertEquals("MX-CHH 5S.0G", mapcodesMX.get(0).toString());
+        assertEquals("MX-CHH 5S.0G", mapcodesMEX.get(0).toString());
 
         final List<Mapcode> mapcodesUS = MapcodeCodec.encodeRestrictToCountryISO2(CIUDAD_JUAREZ, "us");
+        final List<Mapcode> mapcodesUSA = MapcodeCodec.encodeRestrictToCountryISO3(CIUDAD_JUAREZ, "usa");
         assertEquals(5, mapcodesUS.size());
+        assertEquals(5, mapcodesUSA.size());
         assertEquals("US-NM T1DZ.338", mapcodesUS.get(0).toString());
+        assertEquals("US-NM T1DZ.338", mapcodesUSA.get(0).toString());
     }
 
     @Test
-    public void testEncodeRestrictToCountryISO2CountryWithoutSubdivision() {
+    public void testEncodeRestrictToCountryISOCountryWithoutSubdivision() {
         LOG.info("testEncodeRestrictToCountryISO2CountryWithoutSubdivision");
         final List<Mapcode> mapcodesNL = MapcodeCodec.encodeRestrictToCountryISO2(VAALS, "NL");
+        final List<Mapcode> mapcodesNLD = MapcodeCodec.encodeRestrictToCountryISO3(VAALS, "NLD");
         assertEquals(2, mapcodesNL.size());
+        assertEquals(2, mapcodesNLD.size());
         assertEquals("NLD ZNV.W78", mapcodesNL.get(0).toString());
+        assertEquals("NLD ZNV.W78", mapcodesNLD.get(0).toString());
 
         final List<Mapcode> mapcodesBE = MapcodeCodec.encodeRestrictToCountryISO2(VAALS, "be");
+        final List<Mapcode> mapcodesBEL = MapcodeCodec.encodeRestrictToCountryISO3(VAALS, "bel");
         assertEquals(2, mapcodesBE.size());
+        assertEquals(2, mapcodesBEL.size());
         assertEquals("BEL DRQ.PNK", mapcodesBE.get(0).toString());
+        assertEquals("BEL DRQ.PNK", mapcodesBEL.get(0).toString());
     }
 
     @Test
-    public void testEncodeRestrictToCountryISO3WithSubdivision() {
-        LOG.info("testEncodeRestrictToCountryISO3WithSubdivision");
-        final Point ciudadJuarez = Point.fromDeg(31.7, -106.5);
-        final List<Mapcode> mapcodesMEX = MapcodeCodec.encodeRestrictToCountryISO3(CIUDAD_JUAREZ, "MEX");
-        assertEquals(2, mapcodesMEX.size());
-        assertEquals("MEX 4CMT.DLX", mapcodesMEX.get(0).toString());
-
-        final List<Mapcode> mapcodesUSA = MapcodeCodec.encodeRestrictToCountryISO3(CIUDAD_JUAREZ, "usa");
-        assertEquals(1, mapcodesUSA.size());
-        assertEquals("USA NG4F.K745", mapcodesUSA.get(0).toString());
-    }
-
-    @Test
-    public void testEncodeRestrictToCountryISO3CountryWithoutSubdivision() {
-        LOG.info("testEncodeRestrictToCountryISO3CountryWithoutSubdivision");
-        final List<Mapcode> mapcodesNLD = MapcodeCodec.encodeRestrictToCountryISO3(VAALS, "NLD");
-        assertEquals(2, mapcodesNLD.size());
-        assertEquals("NLD ZNV.W78", mapcodesNLD.get(0).toString());
-
-        final List<Mapcode> mapcodesBEL = MapcodeCodec.encodeRestrictToCountryISO3(VAALS, "bel");
-        assertEquals(2, mapcodesBEL.size());
-        assertEquals("BEL DRQ.PNK", mapcodesBEL.get(0).toString());
+    public void testEncodeRestrictToCountryISOForAll() {
+        LOG.info("testEncodeRestrictToCountryISOForAll");
+        for (final Territory territory : Territory.values()) {
+            if (!"AAA".equals(territory.toString())) {
+                final String countryISO3;
+                if (territory.getParentTerritory() == null) {
+                    countryISO3 = territory.toString();
+                } else {
+                    countryISO3 = territory.getParentTerritory().toString();
+                }
+                final String countryISO2 = Territory.getCountryISO2FromISO3(countryISO3);
+                assertNotNull(MapcodeCodec.encodeRestrictToCountryISO2(CIUDAD_JUAREZ, countryISO2));
+                assertNotNull(MapcodeCodec.encodeRestrictToCountryISO3(CIUDAD_JUAREZ, countryISO3));
+            }
+        }
     }
 }
diff --git a/src/test/java/com/mapcode/TerritoryTest.java b/src/test/java/com/mapcode/TerritoryTest.java
