Merge pull request #24 from mapcode-foundation/arabic

Added Arabic support

Author: rijnb

README.md

@@ -39,6 +39,95 @@ limitations under the License.
 Original C library created by Pieter Geelen. Work on Java version
 of the mapcode library by Rijn Buve. Initial port by Matthew Lowden.
 
+# Using the Mapcode Library
+
+For a description of what mapcodes are, please visit http://mapcode.com.
+
+This library exposes a `Mapcode` class, which represents a full mapcode, 
+consisting of a code and a territory. You can extract the code and territory
+with methods like `getCode()` and `getTerritory()`. Codes may be retrieved 
+in a multitude of scripts (or 'alphabets', as they are called in this
+library), such as Roman, Greek, Hindi and Arabic.
+
+`Mapcode` objects are returned by the `MapcodeCodec` with encodes coordinates
+to mapcodes and decodes mapcodes to coordinates (codec means coder/decoder).
+
+# Examples
+
+Here's an example to `decode()` mapcode within a given territory context.
+Note that the territory context (`NLD` is this case) is only used to
+disambiguate the code if needed. If the provided code is an international
+code, the context is simply ignored, because no disambiguation is needed.
+
+    final Territory territory = Territory.fromString("NLD");
+    final String mapcode = "49.4V";
+    try {
+        final Point p = MapcodeCodec.decode(mapcode, territory);
+        // p now points at the (lat, lon) for the mapcode.
+    } catch (final UnknownMapcodeException ignored) {
+        // The mapcode was not valid.
+    }
+  
+And to `encode()` a latitude and longitude into a mapcode you would write:
+
+    final List<Mapcode> results = MapcodeCodec.encode(lat, lon);
+
+As you see, the returned result is actually a list of mapcodes. That's 
+because many locations have multiple mapcodes. The last code in the list
+is always the longest code, the international code. This means this method
+always returns a result (as for every location on Earth, there is at least
+one mapcode).
+
+So, the last code is the international code, but notice that the first code 
+is not always the shortest, nor does it need  to have the "correct"
+territory associated to it.
+
+If you want to get the shortest code for a coordinate, you should should
+specify a territory and use `encodeToShortest` like this:
+
+    final Territory territory = Territory.NLD;
+    final Mapcode mapcode = encodeToShortest(lat, lon, territory);
+    
+This makes sure you get the shortest code for a coordinate which has
+territory `NLD` (or whatever you choose the territory to be).
+
+This method may fail, as the specified coordinate may not lie in the
+specified territory. In that case a `UnknownMapcodeException` is thrown.
+
+The `Mapcode` class offers some additional methods to, for example, get
+high-resolution mapcode strings.
+
+    // Retrieve an ultra-high precision mapcode.
+    final String highRez = mapcode.getCode(8);
+
+Or to get full mapcode strings (Unicode), in different scripts (or alphabets):
+
+    // Get a Roman version of the mapcode.
+    final String roman = mapcode.getCodeWithTerritory(Alphabet.ROMAN);
+
+    // Get an Arabic version of the mapcode.
+    final String arabic = mapcode.getCodeWithTerritory(Alphabet.ARABIC);
+
+Note that mapcodes from different scripts can be passed as strings back
+to the decoder and they will 'just work'.
+
+There's also a `Territory` class, which allows you get territory codes,
+given their ISO 3-character code, or their full names (or even some
+supported aliases).
+
+    final Territory territory = Territory.fromString("France");
+    // territory is now Territory.FRA.
+    
+Finally, there is a `Point` utility class, which represents coordinates
+with a latitude and longitude. The class offers some simple utility methods
+like `distanceInMeters` to calculate the distance between two points. Note 
+that this method is only accurate for pretty short distances, up to, say
+a couple of hundred kilometers.
+
+The `Point` class is usually easier to use than individual latitude and
+longitude paramters and class makes sure it always wraps latitudes to
+a range of `[-90, 90]` and longitude to `[-180, 180>`. 
+
 # Coding Formatting Style
 
 The code formatting style used is the default code formatting style from IntelliJ IDEA (version 14).

pom.xml

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

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

@@ -45,7 +45,8 @@ public enum Alphabet {
     ARMENIAN(10),
     BENGALI(11),
     GURMUKHI(12),
-    TIBETAN(13);
+    TIBETAN(13),
+    ARABIC(14);
 
     /**
      * The numeric code is synonym for the alphanumeric code. Used in the decoder.

src/main/java/com/mapcode/DataModel.java

@@ -170,11 +170,9 @@ public static DataModel getInstance() {
                         i += 4;
                     }
                 } finally {
-                    //noinspection ThrowFromFinallyBlock
                     outputStream.close();
                 }
             } finally {
-                //noinspection ThrowFromFinallyBlock
                 inputStream.close();
             }
         } catch (final IOException e) {