Author: desruisseaux
Date: Sat Jun 11 21:16:39 2016
New Revision: 1747935

URL: http://svn.apache.org/viewvc?rev=1747935&view=rev
Log:
Adjustment in OpenOffice function names and documentation.
Add a TRANSFORM.ENVELOPPE(...) function.
Text <-> angle conversions as matrix functions for more efficient conversions of large amout of values.

Modified:
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/AnglePattern.java
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/CalcAddins.java
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/ReferencingFunctions.java
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/Transformer.java
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.idl
    sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.java
    sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/Referencing.xcu
    sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/org/apache/sis/openoffice/XReferencing.class
    sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/sis.rdb
    sis/branches/JDK8/application/sis-openoffice/src/test/java/org/apache/sis/openoffice/ReferencingFunctionsTest.java
    sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/CRSTest.java
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/Locales.java

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/AnglePattern.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/AnglePattern.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/AnglePattern.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/AnglePattern.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -58,6 +58,11 @@ final class AnglePattern {
     private byte type;
 
     /**
+     * If an error occurred during parsing, the first error.
+     */
+    ParseException warning;
+
+    /**
      * Converts the given argument to a pattern valid for {@link AngleFormat}.
      *
      * @param  patternOrVoid the optional pattern argument from the OpenOffice formula.
@@ -106,48 +111,67 @@ final class AnglePattern {
     }
 
     /**
-     * Parses the given angle.
+     * Parses the given angle. This function is typically invoked for parsing only one value.
+     * But it is nevertheless defined as a matrix function for more efficient conversions of
+     * a bulk of angles.
      *
      * @param text    the angle to parse.
      * @param locale  the expected locale of the text to parse.
      */
-    double parse(final String text, final Locale locale) throws ParseException {
-        AngleFormat format = getAngleFormat(locale);
-        Angle angle;
-        try {
-            synchronized (format) {
-                angle = format.parse(text);
-            }
-        } catch (ParseException exception) {
-            // Parse failed. Try to parse as an unlocalized string.
-            format = getAngleFormat(Locale.ROOT);
-            try {
-                synchronized (format) {
-                    angle = format.parse(text);
+    double[][] parse(final String[][] text, final Locale locale) {
+        final AngleFormat format = getAngleFormat(locale);
+        final double[][] value = new double[text.length][];
+        synchronized (format) {
+            for (int j=0; j<text.length; j++) {
+                final String[] input = text[j];
+                if (input != null) {                                            // Paranoiac check.
+                    final double[] result = new double[input.length];
+                    for (int i=0; i<input.length; i++) {
+                        try {
+                            result[i] = format.parse(input[i]).degrees();
+                        } catch (ParseException e) {
+                            result[i] = Double.NaN;
+                            if (warning == null) {
+                                warning = e;
+                            }
+                        }
+                    }
+                    value[j] = result;
                 }
-            } catch (ParseException ignore) {
-                throw exception;
             }
         }
-        return angle.degrees();
+        return value;
     }
 
     /**
-     * Formats the given angle.
+     * Formats the given angle. This function is typically invoked for formatting only one value.
+     * But it is nevertheless defined as a matrix function for more efficient conversions of a bulk of angles.
      *
      * @param value   the value to format.
      * @param locale  the target locale.
      */
-    String format(final double value, final Locale locale) {
+    String[][] format(final double[][] value, final Locale locale) {
         final AngleFormat format = getAngleFormat(locale);
-        final Angle angle;
-        switch (type) {
-            default:        angle = new Angle    (value); break;
-            case LATITUDE:  angle = new Latitude (value); break;
-            case LONGITUDE: angle = new Longitude(value); break;
-        }
+        final String[][] text = new String[value.length][];
         synchronized (format) {
-            return format.format(angle);
+            for (int j=0; j<value.length; j++) {
+                final double[] input = value[j];
+                if (input != null) {                                            // Paranoiac check.
+                    final String[] result = new String[input.length];
+                    for (int i=0; i<input.length; i++) {
+                        final double v = input[i];
+                        final Angle angle;
+                        switch (type) {
+                            default:        angle = new Angle    (v); break;
+                            case LATITUDE:  angle = new Latitude (v); break;
+                            case LONGITUDE: angle = new Longitude(v); break;
+                        }
+                        result[i] = format.format(angle);
+                    }
+                    text[j] = result;
+                }
+            }
         }
+        return text;
     }
 }

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/CalcAddins.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/CalcAddins.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/CalcAddins.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/CalcAddins.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -31,7 +31,6 @@ import com.sun.star.lib.uno.helper.WeakB
 import org.apache.sis.util.Classes;
 import org.apache.sis.util.Exceptions;
 import org.apache.sis.util.logging.Logging;
-import org.apache.sis.util.collection.BackingStoreException;
 
 
 /**
@@ -44,13 +43,6 @@ import org.apache.sis.util.collection.Ba
  */
 public abstract class CalcAddins extends WeakBase implements XServiceName, XServiceInfo, XLocalizable {
     /**
-     * {@code true} for throwing an exception in case of failure, or {@code false} for returning {@code NaN} instead.
-     * This apply only to numerical computations; formulas returning a text value will returns the exception message
-     * in case of failure.
-     */
-    static final boolean THROW_EXCEPTION = true;
-
-    /**
      * Indirectly provides access to the service manager.
      * For example {@code com.sun.star.sdb.DatabaseContext} holds databases registered with OpenOffice.
      */
@@ -216,9 +208,8 @@ public abstract class CalcAddins extends
      *
      * @param method     the method from which an exception occurred.
      * @param exception  the exception.
-     * @param rethrow    {@code true} for rethrowing the exception after the report.
      */
-    final void reportException(final String method, final Exception exception, final boolean rethrow) {
+    final void reportException(final String method, final Exception exception) {
         final Logger logger = getLogger();
         final LogRecord record = new LogRecord(Level.WARNING, getLocalizedMessage(exception));
         record.setLoggerName(logger.getName());
@@ -226,12 +217,6 @@ public abstract class CalcAddins extends
         record.setSourceMethodName(method);
         record.setThrown(exception);
         logger.log(record);
-        if (rethrow) {
-            if (exception instanceof RuntimeException) {
-                throw (RuntimeException) exception;
-            }
-            throw new BackingStoreException(exception);
-        }
     }
 
     /**

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/ReferencingFunctions.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/ReferencingFunctions.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/ReferencingFunctions.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/ReferencingFunctions.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -16,8 +16,6 @@
  */
 package org.apache.sis.openoffice;
 
-import java.text.ParseException;
-
 import org.opengis.metadata.Metadata;
 import org.opengis.util.FactoryException;
 import org.opengis.util.InternationalString;
@@ -39,6 +37,7 @@ import org.apache.sis.referencing.Identi
 import org.apache.sis.referencing.AbstractIdentifiedObject;
 import org.apache.sis.io.wkt.Transliterator;
 import org.apache.sis.util.Classes;
+import org.apache.sis.util.Locales;
 import org.apache.sis.util.collection.Cache;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.internal.util.PatchedUnitFormat;
@@ -271,14 +270,14 @@ public class ReferencingFunctions extend
                         area = Extents.getGeographicBoundingBox((Extent) domain);
                     }
                 } catch (Exception exception) {
-                    reportException("getGeographicArea", exception, THROW_EXCEPTION);
+                    reportException("getGeographicArea", exception);
                 }
             } finally {
                 handler.putAndUnlock(area);
             }
         }
         if (area == null) {
-            return getFailure(4,4);
+            return getFailure(2,2);
         }
         return new double[][] {
             new double[] {area.getNorthBoundLatitude(), area.getWestBoundLongitude()},
@@ -307,23 +306,23 @@ public class ReferencingFunctions extend
     /**
      * Returns the accuracy of a transformation between two coordinate reference systems.
      *
-     * @param  sourceCRS  the authority code for the source coordinate reference system.
-     * @param  targetCRS  the authority code for the target coordinate reference system.
-     * @param  points     the coordinates to transform (for computing area of interest).
+     * @param  sourceCRS       the authority code for the source coordinate reference system.
+     * @param  targetCRS       the authority code for the target coordinate reference system.
+     * @param  areaOfInterest  an optional bounding box of source coordinates to transform.
      * @throws IllegalArgumentException if {@code points} is not a {@code double[][]} value or void.
      * @return the operation accuracy.
      */
     @Override
-    public double getAccuracy(final String sourceCRS, final String targetCRS, final Object points)
+    public double getAccuracy(final String sourceCRS, final String targetCRS, final Object areaOfInterest)
             throws IllegalArgumentException
     {
         final double[][] coordinates;
-        if (AnyConverter.isVoid(points)) {
+        if (AnyConverter.isVoid(areaOfInterest)) {
             coordinates = null;
-        } else if (points instanceof double[][]) {
-            coordinates = (double[][]) points;
-        } else if (points instanceof Object[][]) {
-            final Object[][] values = (Object[][]) points;
+        } else if (areaOfInterest instanceof double[][]) {
+            coordinates = (double[][]) areaOfInterest;
+        } else if (areaOfInterest instanceof Object[][]) {
+            final Object[][] values = (Object[][]) areaOfInterest;
             coordinates = new double[values.length][];
             for (int j=0; j<values.length; j++) {
                 final Object[] row = values[j];
@@ -339,7 +338,7 @@ public class ReferencingFunctions extend
         try {
             return new Transformer(this, getCRS(sourceCRS), targetCRS, coordinates).getAccuracy();
         } catch (Exception exception) {
-            reportException("getAccuracy", exception, THROW_EXCEPTION);
+            reportException("getAccuracy", exception);
             return Double.NaN;
         }
     }
@@ -350,17 +349,46 @@ public class ReferencingFunctions extend
      * @param  sourceCRS  the authority code for the source coordinate reference system.
      * @param  targetCRS  the authority code for the target coordinate reference system.
      * @param  points     the coordinates to transform.
-     * @return The transformed coordinates.
+     * @return the transformed coordinates.
      */
     @Override
     public double[][] transformPoints(final String sourceCRS, final String targetCRS, final double[][] points) {
         if (points == null || points.length == 0) {
             return new double[][] {};
+        }
+        double[][] result;
+        Exception warning;
+        try {
+            final Transformer tr = new Transformer(this, getCRS(sourceCRS), targetCRS, points);
+            result  = tr.transform(points);
+            warning = tr.warning;
+        } catch (Exception exception) {
+            result  = getFailure(points.length, 2);
+            warning = exception;
+        }
+        if (warning != null) {
+            reportException("transformPoints", warning);
+        }
+        return result;
+    }
+
+    /**
+     * Transforms an envelope from the specified source CRS to the specified target CRS.
+     *
+     * @param  sourceCRS  the authority code for the source coordinate reference system.
+     * @param  targetCRS  the authority code for the target coordinate reference system.
+     * @param  envelope   points inside the envelope to transform.
+     * @return the transformed envelope.
+     */
+    @Override
+    public double[][] transformEnvelope(String sourceCRS, String targetCRS, double[][] envelope) {
+        if (envelope == null || envelope.length == 0) {
+            return new double[][] {};
         } else try {
-            return new Transformer(this, getCRS(sourceCRS), targetCRS, points).transform(points);
+            return new Transformer(this, getCRS(sourceCRS), targetCRS, envelope).transformEnvelope(envelope);
         } catch (Exception exception) {
-            reportException("transformPoints", exception, THROW_EXCEPTION);
-            return getFailure(points.length, 2);
+            reportException("transformEnvelope", exception);
+            return getFailure(envelope.length, 2);
         }
     }
 
@@ -370,17 +398,21 @@ public class ReferencingFunctions extend
      *
      * @param  text     the text to be converted to an angle.
      * @param  pattern  an optional text that describes the format (example: "D°MM.m'").
+     * @param  locale   the convention to use (e.g. decimal separator symbol).
      * @return the angle parsed as a number.
      * @throws IllegalArgumentException if {@code pattern} is not a string value or void.
      */
     @Override
-    public double parseAngle(final String text, final Object pattern) throws IllegalArgumentException {
-        try {
-            return new AnglePattern(pattern).parse(text, getJavaLocale());
-        } catch (ParseException exception) {
-            reportException("parseAngle", exception, THROW_EXCEPTION);
-            return Double.NaN;
+    public double[][] parseAngle(final String[][] text, final Object pattern, final Object locale)
+            throws IllegalArgumentException
+    {
+        final AnglePattern p = new AnglePattern(pattern);
+        final double[][] result = p.parse(text, AnyConverter.isVoid(locale)
+                ? getJavaLocale() : Locales.parse(AnyConverter.toString(locale)));
+        if (p.warning != null) {
+            reportException("parseAngle", p.warning);
         }
+        return result;
     }
 
     /**
@@ -394,11 +426,15 @@ public class ReferencingFunctions extend
      *
      * @param  value    the angle value (in decimal degrees) to be converted.
      * @param  pattern  an optional text that describes the format (example: "D°MM.m'").
+     * @param  locale   the convention to use (e.g. decimal separator symbol).
      * @return the angle formatted as a string.
      * @throws IllegalArgumentException if {@code pattern} is not a string value or void.
      */
     @Override
-    public String formatAngle(final double value, final Object pattern) throws IllegalArgumentException {
-        return new AnglePattern(pattern).format(value, getJavaLocale());
+    public String[][] formatAngle(final double[][] value, final Object pattern, final Object locale)
+            throws IllegalArgumentException
+    {
+        return new AnglePattern(pattern).format(value, AnyConverter.isVoid(locale)
+                ? getJavaLocale() : Locales.parse(AnyConverter.toString(locale)));
     }
 }

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/Transformer.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/Transformer.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/Transformer.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/Transformer.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -16,6 +16,7 @@
  */
 package org.apache.sis.openoffice;
 
+import java.util.Arrays;
 import org.opengis.util.FactoryException;
 import org.opengis.metadata.extent.GeographicBoundingBox;
 import org.opengis.referencing.crs.GeographicCRS;
@@ -23,6 +24,8 @@ import org.opengis.referencing.crs.Coord
 import org.opengis.referencing.operation.CoordinateOperation;
 import org.opengis.referencing.operation.MathTransform;
 import org.opengis.referencing.operation.TransformException;
+import org.apache.sis.geometry.Envelopes;
+import org.apache.sis.geometry.GeneralEnvelope;
 import org.apache.sis.geometry.GeneralDirectPosition;
 import org.apache.sis.referencing.CRS;
 import org.apache.sis.util.collection.Cache;
@@ -156,7 +159,7 @@ final class Transformer {
         final double[][] result = new double[points.length][];
         for (int j=0; j<points.length; j++) {
             final double[] coords = points[j];
-            if (coords != null) {
+            if (coords != null) {                                               // Paranoiac check.
                 for (int i=sourcePt.ordinates.length; --i>=0;) {
                     sourcePt.ordinates[i] = (i < coords.length) ? coords[i] : 0;
                 }
@@ -169,6 +172,9 @@ final class Transformer {
                      * we will report the failure for logging purpose, but only the first one since
                      * all subsequent failures are likely to be the same one.
                      */
+                    final double[] pad = new double[mt.getTargetDimensions()];
+                    Arrays.fill(pad, Double.NaN);
+                    result[j] = pad;
                     if (warning == null) {
                         warning = exception;
                     }
@@ -177,4 +183,28 @@ final class Transformer {
         }
         return result;
     }
+
+    /**
+     * Transforms the given envelope.
+     */
+    final double[][] transformEnvelope(final double[][] points) throws TransformException {
+        final double[] min = new double[operation.getMathTransform().getSourceDimensions()];
+        final double[] max = new double[min.length];
+        Arrays.fill(min, Double.POSITIVE_INFINITY);
+        Arrays.fill(max, Double.NEGATIVE_INFINITY);
+        for (final double[] p : points) {
+            if (p != null) {                                                    // Paranoiac check.
+                for (int i=Math.min(min.length, p.length); --i >= 0;) {
+                    final double v = p[i];
+                    if (v < min[i]) min[i] = v;
+                    if (v > max[i]) max[i] = v;
+                }
+            }
+        }
+        final GeneralEnvelope result = Envelopes.transform(operation, new GeneralEnvelope(min, max));
+        return new double[][] {
+            result.getLowerCorner().getCoordinate(),
+            result.getUpperCorner().getCoordinate()
+        };
+    }
 }

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.idl
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.idl?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.idl [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.idl [UTF-8] Sat Jun 11 21:16:39 2016
@@ -64,8 +64,8 @@ module org {
             [in] string sourceCRS,
             /// Authority code of the target coordinate reference system.
             [in] string targetCRS,
-            /// The source coordinates to transform.
-            [in] any points
+            /// An optional bounding box of source coordinates to transform.
+            [in] any areaOfInterest
           ) raises (com::sun::star::lang::IllegalArgumentException);
 
           /// Transforms a list of coordinates from source CRS to target CRS.
@@ -78,20 +78,34 @@ module org {
             [in] sequence< sequence< double > > points
           );
 
+          /// Transforms the envelope of given points from source CRS to target CRS.
+          sequence< sequence< double > > transformEnvelope(
+            /// Authority code of the source coordinate reference system.
+            [in] string sourceCRS,
+            /// Authority code of the target coordinate reference system.
+            [in] string targetCRS,
+            /// The source envelope to transform.
+            [in] sequence< sequence< double > > envelope
+          );
+
           /// Converts text in degrees-minutes-seconds to an angle in decimal degrees.
-          double parseAngle(
+          sequence< sequence< double > > parseAngle(
             /// The text to be converted to an angle.
-            [in] string text,
+            [in] sequence< sequence< string > > text,
             /// The text that describes the format (example: "D MM.m'").
-            [in] any pattern
+            [in] any pattern,
+            /// The locale (example: "en", "fr").
+            [in] any locale
           ) raises (com::sun::star::lang::IllegalArgumentException);
 
           /// Converts an angle to text according to a given format.
-          string formatAngle(
+          sequence< sequence< string > > formatAngle(
             /// The angle value (in decimal degrees) to be converted.
-            [in] double value,
+            [in] sequence< sequence< double > > value,
             /// The text that describes the format (example: "D MM.m'").
-            [in] any pattern
+            [in] any pattern,
+            /// The locale (example: "en", "fr").
+            [in] any locale
           ) raises (com::sun::star::lang::IllegalArgumentException);
         };
 

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/java/org/apache/sis/openoffice/XReferencing.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -71,13 +71,13 @@ public interface XReferencing extends XI
     /**
      * Returns the accuracy of a transformation between two coordinate reference systems.
      *
-     * @param  sourceCRS  the authority code for the source coordinate reference system.
-     * @param  targetCRS  the authority code for the target coordinate reference system.
-     * @param  points     the coordinates to transform (for computing area of interest).
+     * @param  sourceCRS       the authority code for the source coordinate reference system.
+     * @param  targetCRS       the authority code for the target coordinate reference system.
+     * @param  areaOfInterest  an optional bounding box of source coordinates to transform.
      * @return the operation accuracy.
      * @throws IllegalArgumentException if {@code points} is not a {@code double[][]} value or void.
      */
-    double getAccuracy(String sourceCRS, String targetCRS, Object points) throws IllegalArgumentException;
+    double getAccuracy(String sourceCRS, String targetCRS, Object areaOfInterest) throws IllegalArgumentException;
 
     /**
      * Transforms coordinates from the specified source CRS to the specified target CRS.
@@ -85,20 +85,31 @@ public interface XReferencing extends XI
      * @param  sourceCRS  the authority code for the source coordinate reference system.
      * @param  targetCRS  the authority code for the target coordinate reference system.
      * @param  points     the coordinates to transform.
-     * @return The transformed coordinates.
+     * @return the transformed coordinates.
      */
     double[][] transformPoints(String sourceCRS, String targetCRS, double[][] points);
 
     /**
+     * Transforms an envelope from the specified source CRS to the specified target CRS.
+     *
+     * @param  sourceCRS  the authority code for the source coordinate reference system.
+     * @param  targetCRS  the authority code for the target coordinate reference system.
+     * @param  envelope   points inside the envelope to transform.
+     * @return the transformed envelope.
+     */
+    double[][] transformEnvelope(String sourceCRS, String targetCRS, double[][] envelope);
+
+    /**
      * Converts text in degrees-minutes-seconds to an angle in decimal degrees.
      * See {@link org.apache.sis.measure.AngleFormat} for pattern description.
      *
-     * @param  text       the text to be converted to an angle.
-     * @param  pattern    an optional text that describes the format (example: "D°MM.m'").
+     * @param  text     the text to be converted to an angle.
+     * @param  pattern  an optional text that describes the format (example: "D°MM.m'").
+     * @param  locale   the convention to use (e.g. decimal separator symbol).
      * @return the angle parsed as a number.
      * @throws IllegalArgumentException if {@code pattern} is not a string value or void.
      */
-    double parseAngle(String text, Object pattern) throws IllegalArgumentException;
+    double[][] parseAngle(String[][] text, Object pattern, Object locale) throws IllegalArgumentException;
 
     /**
      * Converts an angle to text according to a given format. This method uses the pattern
@@ -109,10 +120,11 @@ public interface XReferencing extends XI
      *   <li>If the pattern ends with N or S, then the angle is formatted as a latitude.</li>
      * </ul>
      *
-     * @param  value      the angle value (in decimal degrees) to be converted.
-     * @param  pattern    an optional text that describes the format (example: "D°MM.m'").
+     * @param  value    the angle value (in decimal degrees) to be converted.
+     * @param  pattern  an optional text that describes the format (example: "D°MM.m'").
+     * @param  locale   the convention to use (e.g. decimal separator symbol).
      * @return the angle formatted as a string.
      * @throws IllegalArgumentException if {@code pattern} is not a string value or void.
      */
-    String formatAngle(double value, Object pattern) throws IllegalArgumentException;
+    String[][] formatAngle(double[][] value, Object pattern, Object locale) throws IllegalArgumentException;
 }

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/Referencing.xcu
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/Referencing.xcu?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/Referencing.xcu (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/Referencing.xcu Sat Jun 11 21:16:39 2016
@@ -28,11 +28,11 @@
         <node oor:name="getName" oor:op="replace">
           <prop oor:name="DisplayName">
             <value xml:lang="en">CRS.NAME</value>
-            <value xml:lang="fr">CRS.NOM</value>
+            <value xml:lang="fr">NOM.SRS</value>
           </prop>
           <prop oor:name="Description">
-            <value xml:lang="en">Returns the name of an object identified by the given code.</value>
-            <value xml:lang="fr">Retourne le nom d’un objet identifié par le code donné.</value>
+            <value xml:lang="en">Returns the name of an object identified by the given code. The object is usually, but not necessarily, a Coordinate Reference System (CRS).</value>
+            <value xml:lang="fr">Retourne le nom d’un objet identifié par le code donné. L’objet est habituellement, mais pas obligatoirement, un Système de Références Spatiales (SRS).</value>
           </prop>
           <prop oor:name="Category">
             <value>Add-In</value>
@@ -54,11 +54,11 @@
         <node oor:name="getAxis" oor:op="replace">
           <prop oor:name="DisplayName">
             <value xml:lang="en">CRS.AXIS</value>
-            <value xml:lang="fr">CRS.AXE</value>
+            <value xml:lang="fr">AXE.SRS</value>
           </prop>
           <prop oor:name="Description">
-            <value xml:lang="en">Returns the axis name for the specified dimension in a system identified by the given code.</value>
-            <value xml:lang="fr">Retourne le nom de l’axe à la dimension spécifiée dans un système identifié par le code donné.</value>
+            <value xml:lang="en">Returns the axis name for the specified dimension in a Coordinate Reference System (CRS) identified by the given code.</value>
+            <value xml:lang="fr">Retourne le nom de l’axe à la dimension spécifiée dans un Système de Références Spatiales (SRS) identifié par le code donné.</value>
           </prop>
           <prop oor:name="Category">
             <value>Add-In</value>
@@ -93,10 +93,8 @@
             <value xml:lang="fr">REGION.GEOGRAPHIQUE</value>
           </prop>
           <prop oor:name="Description">
-            <value xml:lang="en">Returns the domain as a geographic bounding box for an object identified by the given code.
-                                 The box is expressed by a 2×2 matrix with latitudes in the first column and longitudes in the second column.</value>
-            <value xml:lang="fr">Retourne sous forme de boîte englobante le domaine d’un objet identifié par le code donné.
-                                 La boîte est exprimée par une matrice 2×2 avec les latitudes dans la première colonne et les longitudes dans la seconde colonne.</value>
+            <value xml:lang="en">Returns the domain as a geographic bounding box for an object identified by the given code. The box is expressed by a 2×2 matrix with latitudes in the first column and longitudes in the second column.</value>
+            <value xml:lang="fr">Retourne sous forme de boîte englobante le domaine d’un objet identifié par le code donné. La boîte est exprimée par une matrice 2×2 avec les latitudes dans la première colonne et les longitudes dans la seconde colonne.</value>
           </prop>
           <prop oor:name="Category">
             <value>Add-In</value>
@@ -121,8 +119,8 @@
             <value xml:lang="fr">PRECISION.TRANSFORM</value>
           </prop>
           <prop oor:name="Description">
-            <value xml:lang="en">Returns the accuracy of a coordinate operation applied between two given reference systems.</value>
-            <value xml:lang="fr">Retourne la précision d’une opération sur les coordonnées effectuée entre les deux systèmes de référence donnés.</value>
+            <value xml:lang="en">Returns the accuracy of a coordinate operation applied between two given Coordinate Reference Systems (CRS). In some cases, accuracy depends also on the geographic area of the points to transform.</value>
+            <value xml:lang="fr">Retourne la précision d’une opération sur les coordonnées effectuée entre les deux Systèmes de Références Spatiales (SRS) donnés. Dans certains cas, la précision dépend aussi de la région géographique contenant les points à transformer.</value>
           </prop>
           <prop oor:name="Category">
             <value>Add-In</value>
@@ -135,7 +133,7 @@
               </prop>
               <prop oor:name="Description">
                 <value xml:lang="en">Identifier of the source coordinate reference system.</value>
-                <value xml:lang="fr">Identifiant du système de référence des coordonnées sources.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales des coordonnées sources.</value>
               </prop>
             </node>
             <node oor:name="targetCRS" oor:op="replace">
@@ -145,17 +143,17 @@
               </prop>
               <prop oor:name="Description">
                 <value xml:lang="en">Identifier of the target coordinate reference system.</value>
-                <value xml:lang="fr">Identifiant du système de référence des coordonnées destinations.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales des coordonnées destinations.</value>
               </prop>
             </node>
-            <node oor:name="points" oor:op="replace">
+            <node oor:name="areaOfInterest" oor:op="replace">
               <prop oor:name="DisplayName">
-                <value xml:lang="en">points</value>
-                <value xml:lang="fr">points</value>
+                <value xml:lang="en">area</value>
+                <value xml:lang="fr">région</value>
               </prop>
               <prop oor:name="Description">
-                <value xml:lang="en">Coordinates of points to transform (optional). This information may affect parameters of the selected coordinate transformation.</value>
-                <value xml:lang="fr">Coordonnées des points à transformer (optionnel). Cette information peut influer les paramètres de la transformation choisie.</value>
+                <value xml:lang="en">Bounding box of source points to transform. This is a matrix of at least two rows containing (in any order) the minimum and maximum values of all coordinates to transform.</value>
+                <value xml:lang="fr">Boîte englobante des points sources à transformer. C’est une matrice d’au moins deux lignes contenant (dans n’importe quel ordre) les valeurs minimales et maximales des coordonnées à transformer.</value>
               </prop>
             </node>
           </node>
@@ -167,8 +165,8 @@
             <value xml:lang="fr">TRANSFORM.POINTS</value>
           </prop>
           <prop oor:name="Description">
-            <value xml:lang="en">Transform coordinates from the given source CRS to the given target CRS.</value>
-            <value xml:lang="fr">Transforme des coordonnées à partir du CRS source donné vers le CRS destination donné.</value>
+            <value xml:lang="en">Transform coordinates from the given source Coordinate Reference System (CRS) to the given target CRS.</value>
+            <value xml:lang="fr">Transforme des coordonnées à partir du Système de Références Spatiales (SRS) source donné vers le SRS destination donné.</value>
           </prop>
           <prop oor:name="Category">
             <value>Add-In</value>
@@ -181,7 +179,7 @@
               </prop>
               <prop oor:name="Description">
                 <value xml:lang="en">Identifier of the source coordinate reference system.</value>
-                <value xml:lang="fr">Identifiant du système de référence des coordonnées sources.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales des coordonnées sources.</value>
               </prop>
             </node>
             <node oor:name="targetCRS" oor:op="replace">
@@ -191,7 +189,7 @@
               </prop>
               <prop oor:name="Description">
                 <value xml:lang="en">Identifier of the target coordinate reference system.</value>
-                <value xml:lang="fr">Identifiant du système de référence des coordonnées destinations.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales des coordonnées destinations.</value>
               </prop>
             </node>
             <node oor:name="points" oor:op="replace">
@@ -207,6 +205,52 @@
           </node>
         </node>
 
+        <node oor:name="transformEnvelope" oor:op="replace">
+          <prop oor:name="DisplayName">
+            <value xml:lang="en">TRANSFORM.ENVELOPE</value>
+            <value xml:lang="fr">TRANSFORM.ENVELOPPE</value>
+          </prop>
+          <prop oor:name="Description">
+            <value xml:lang="en">Transform the bounding box of given points from source Coordinate Reference System (CRS) to target CRS.</value>
+            <value xml:lang="fr">Transforme la boîte englobante des points donnés à partir du Système de Références Spatiales (SRS) source vers le SRS destination.</value>
+          </prop>
+          <prop oor:name="Category">
+            <value>Add-In</value>
+          </prop>
+          <node oor:name="Parameters">
+            <node oor:name="sourceCRS" oor:op="replace">
+              <prop oor:name="DisplayName">
+                <value xml:lang="en">source</value>
+                <value xml:lang="fr">source</value>
+              </prop>
+              <prop oor:name="Description">
+                <value xml:lang="en">Identifier of the source coordinate reference system.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales de l’enveloppe sources.</value>
+              </prop>
+            </node>
+            <node oor:name="targetCRS" oor:op="replace">
+              <prop oor:name="DisplayName">
+                <value xml:lang="en">target</value>
+                <value xml:lang="fr">destination</value>
+              </prop>
+              <prop oor:name="Description">
+                <value xml:lang="en">Identifier of the target coordinate reference system.</value>
+                <value xml:lang="fr">Identifiant du système de références spatiales de l’enveloppe destinations.</value>
+              </prop>
+            </node>
+            <node oor:name="envelope" oor:op="replace">
+              <prop oor:name="DisplayName">
+                <value xml:lang="en">envelope</value>
+                <value xml:lang="fr">enveloppe</value>
+              </prop>
+              <prop oor:name="Description">
+                <value xml:lang="en">Source envelope to transform. This is a matrix of at least two rows containing (in any order) the minimum and maximum values of the envelope to transform.</value>
+                <value xml:lang="fr">Boîte englobante des points sources à transformer. C’est une matrice d’au moins deux lignes contenant (dans n’importe quel ordre) les valeurs minimales et maximales de l’enveloppe à transformer.</value>
+              </prop>
+            </node>
+          </node>
+        </node>
+
         <node oor:name="parseAngle" oor:op="replace">
           <prop oor:name="DisplayName">
             <value xml:lang="en">VALUE.ANGLE</value>
@@ -236,8 +280,20 @@
                 <value xml:lang="fr">modèle</value>
               </prop>
               <prop oor:name="Description">
-                <value xml:lang="en">An optional text that gives the angle pattern (example: D°MM.m’).</value>
-                <value xml:lang="fr">Un texte optionnel donnant le modèle des angles (exemple: D°MM.m’).</value>
+                <value xml:lang="en">The angle format pattern (example: D°MM.m’). D is for degrees, M for minutes, S for seconds and . for the decimal separator. Upper-cases are for integer parts and lower-case are are the fractional part. Pattern can be optionally be suffixed by N or S for latitudes and by E or W for longitudes.
+                </value>
+                <value xml:lang="fr">Le modèle du format des angles (exemple: D°MM.m’). D est pour les degrés, M pour les minutes, S pour les secondes et . pour le séparateur décimal. Les majuscules sont pour la partie entière et les minuscules pour la partie fractionnaire de l'angle. Le modèle peut facultativement être suivit de N ou S pour les latitudes et E or W pour les longitudes.
+                </value>
+              </prop>
+            </node>
+            <node oor:name="locale" oor:op="replace">
+              <prop oor:name="DisplayName">
+                <value xml:lang="en">locale</value>
+                <value xml:lang="fr">langue</value>
+              </prop>
+              <prop oor:name="Description">
+                <value xml:lang="en">An optional language code for specifying the convention to use. For example “en” uses the dot as a decimal separator while “fr” uses coma. If unspecified, then conventions will be those of the default locale.</value>
+                <value xml:lang="fr">Un code de langue optionnel pour spécifier les conventions à utiliser. Par exemple « en » utilise le point comme séparateur décimal alors que « fr » utilise la virgule. Si non-spécifié, alors les conventions seront celles de la langue par défaut.</value>
               </prop>
             </node>
           </node>
@@ -272,8 +328,18 @@
                 <value xml:lang="fr">modèle</value>
               </prop>
               <prop oor:name="Description">
-                <value xml:lang="en">An optional text that gives the angle pattern (example: D°MM.m’).</value>
-                <value xml:lang="fr">Un texte optionnel donnant le modèle des angles (exemple: D°MM.m’).</value>
+                <value xml:lang="en">The angle format pattern (example: D°MM.m’). D is for degrees, M for minutes, S for seconds and . for the decimal separator. Upper-cases are for integer parts and lower-case are are the fractional part. Pattern can be optionally be suffixed by N or S for latitudes and by E or W for longitudes.</value>
+                <value xml:lang="fr">Le modèle du format des angles (exemple: D°MM.m’). D est pour les degrés, M pour les minutes, S pour les secondes et . pour le séparateur décimal. Les majuscules sont pour la partie entière et les minuscules pour la partie fractionnaire de l'angle. Le modèle peut facultativement être suivit de N ou S pour les latitudes et E or W pour les longitudes.</value>
+              </prop>
+            </node>
+            <node oor:name="locale" oor:op="replace">
+              <prop oor:name="DisplayName">
+                <value xml:lang="en">locale</value>
+                <value xml:lang="fr">langue</value>
+              </prop>
+              <prop oor:name="Description">
+                <value xml:lang="en">An optional language code for specifying the convention to use. For example “en” uses the dot as a decimal separator while “fr” uses coma. If unspecified, then conventions will be those of the default locale.</value>
+                <value xml:lang="fr">Un code de langue optionnel pour spécifier les conventions à utiliser. Par exemple « en » utilise le point comme séparateur décimal alors que « fr » utilise la virgule. Si non-spécifié, alors les conventions seront celles de la langue par défaut.</value>
               </prop>
             </node>
           </node>

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/org/apache/sis/openoffice/XReferencing.class
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/org/apache/sis/openoffice/XReferencing.class?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
Binary files - no diff available.

Modified: sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/sis.rdb
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/main/unopkg/sis.rdb?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
Binary files - no diff available.

Modified: sis/branches/JDK8/application/sis-openoffice/src/test/java/org/apache/sis/openoffice/ReferencingFunctionsTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/application/sis-openoffice/src/test/java/org/apache/sis/openoffice/ReferencingFunctionsTest.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/application/sis-openoffice/src/test/java/org/apache/sis/openoffice/ReferencingFunctionsTest.java [UTF-8] (original)
+++ sis/branches/JDK8/application/sis-openoffice/src/test/java/org/apache/sis/openoffice/ReferencingFunctionsTest.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -150,15 +150,34 @@ public final strictfp class ReferencingF
     }
 
     /**
+     * Tests {@link ReferencingFunctions#transformEnvelope(String, String, double[][])}.
+     */
+    @Test
+    public void testTransformEnvelope() {
+        final double[][] points = {
+            new double[] {30,  20,  4},
+            new double[] {34,  17, -3},
+            new double[] {27, -12, 12},
+            new double[] {32,  23, -1}
+        };
+        final double[][] result = {
+            new double[] {27, -12},
+            new double[] {34,  23}
+        };
+        TransformerTest.assertPointsEqual(result,
+                instance.transformEnvelope("EPSG:4979", "EPSG:4326", points), STRICT);
+    }
+
+    /**
      * Tests {@link ReferencingFunctions#parseAngle(String, Object)}.
      *
      * @throws IllegalArgumentException if the pattern used by the test is not a string or void.
      */
     @Test
     public void testParseAngle() throws IllegalArgumentException {
-        assertEquals(43.50, instance.parseAngle("43°30'", "D°MM.m'"), STRICT);
-        assertEquals(43.50, instance.parseAngle("4330",   "DMM"),     STRICT);
-        assertEquals(-3.25, instance.parseAngle("-3°15'", "D°MM.m'"), STRICT);
+        assertEquals(43.50, singleton(instance.parseAngle(new String[][] {{"43°30'"}}, "D°MM.m'", "en")), STRICT);
+        assertEquals(43.50, singleton(instance.parseAngle(new String[][] {{"4330"}},   "DMM",     "en")), STRICT);
+        assertEquals(-3.25, singleton(instance.parseAngle(new String[][] {{"-3°15'"}}, "D°MM.m'", "en")), STRICT);
     }
 
     /**
@@ -168,8 +187,26 @@ public final strictfp class ReferencingF
      */
     @Test
     public void testFormatAngle() throws IllegalArgumentException {
-        assertEquals("43°30.0'", instance.formatAngle(43.50, "D°MM.m'"));
-        assertEquals("4330",     instance.formatAngle(43.50, "DMM"));
-        assertEquals("-3°15.0'", instance.formatAngle(-3.25, "D°MM.m'"));
+        assertEquals("43°30.0'", singleton(instance.formatAngle(new double[][] {{43.50}}, "D°MM.m'", "en")));
+        assertEquals("4330",     singleton(instance.formatAngle(new double[][] {{43.50}}, "DMM",     "en")));
+        assertEquals("-3°15.0'", singleton(instance.formatAngle(new double[][] {{-3.25}}, "D°MM.m'", "en")));
+    }
+
+    /**
+     * Ensures that the given array contains exactly one element and returns that element.
+     */
+    private static double singleton(final double[][] value) {
+        assertEquals("array length", 1, value.length);
+        assertEquals("array length", 1, value[0].length);
+        return value[0][0];
+    }
+
+    /**
+     * Ensures that the given array contains exactly one element and returns that element.
+     */
+    private static String singleton(final String[][] value) {
+        assertEquals("array length", 1, value.length);
+        assertEquals("array length", 1, value[0].length);
+        return value[0][0];
     }
 }

Modified: sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/CRSTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/CRSTest.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/CRSTest.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/test/java/org/apache/sis/referencing/CRSTest.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -20,6 +20,7 @@ import org.opengis.referencing.crs.Coord
 import org.opengis.referencing.crs.GeodeticCRS;
 import org.opengis.referencing.crs.SingleCRS;
 import org.opengis.util.FactoryException;
+import org.opengis.util.NoSuchIdentifierException;
 import org.apache.sis.referencing.crs.DefaultCompoundCRS;
 import org.apache.sis.referencing.crs.DefaultGeographicCRS;
 import org.apache.sis.referencing.crs.HardCodedCRS;
@@ -40,7 +41,7 @@ import static org.apache.sis.test.Assert
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.4
- * @version 0.7
+ * @version 0.8
  * @module
  */
 @DependsOn({
@@ -106,6 +107,21 @@ public final strictfp class CRSTest exte
     }
 
     /**
+     * Test {@link CRS#forCode(String)} with values that should be invalid.
+     *
+     * @throws FactoryException if an error other than {@link NoSuchIdentifierException} happened.
+     */
+    @Test
+    public void testForInvalidCode() throws FactoryException {
+        try {
+            CRS.forCode("EPSG:4");
+            fail("Should not find EPSG:4");
+        } catch (NoSuchIdentifierException e) {
+            assertEquals("4", e.getIdentifierCode());
+        }
+    }
+
+    /**
      * Tests simple WKT parsing. It is not the purpose of this class to test extensively the WKT parser;
      * those tests are rather done by {@link org.apache.sis.io.wkt.GeodeticObjectParserTest}.
      * Here we merely test that {@link CRS#fromWKT(String)} is connected to the parser.

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/Locales.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/Locales.java?rev=1747935&r1=1747934&r2=1747935&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/Locales.java [UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/Locales.java [UTF-8] Sat Jun 11 21:16:39 2016
@@ -103,10 +103,10 @@ public final class Locales extends Stati
      */
     private static final short[] ISO3, ISO2;
     static {
-        final Short CONFLICT = 0; // Sentinal value for conflicts (paranoiac safety).
+        final Short CONFLICT = 0;                           // Sentinal value for conflicts (paranoiac safety).
         final Map<Short,Short> map = new TreeMap<>();
         for (final Locale locale : POOL.values()) {
-            short type = LANGUAGE; // 0 for language, or leftmost bit set for country.
+            short type = LANGUAGE;                          // 0 for language, or leftmost bit set for country.
             do { // Executed exactly twice: once for language, than once for country.
                 final short alpha2 = toNumber((type == LANGUAGE) ? locale.getLanguage() : locale.getCountry(), type);
                 if (alpha2 != 0) {
@@ -114,7 +114,7 @@ public final class Locales extends Stati
                     try {
                         alpha3 = toNumber((type == LANGUAGE) ? locale.getISO3Language() : locale.getISO3Country(), type);
                     } catch (MissingResourceException e) {
-                        continue; // No 3-letters code to map for this locale.
+                        continue;                           // No 3-letters code to map for this locale.
                     }
                     if (alpha3 != 0 && alpha3 != alpha2) {
                         final Short p = map.put(alpha3, alpha2);
@@ -127,7 +127,7 @@ public final class Locales extends Stati
                 }
             } while ((type ^= COUNTRY) != LANGUAGE);
         }
-        while (map.values().remove(CONFLICT)); // Remove all conflicts that we may have found.
+        while (map.values().remove(CONFLICT));              // Remove all conflicts that we may have found.
         ISO3 = new short[map.size()];
         ISO2 = new short[map.size()];
         int i = 0;
@@ -298,8 +298,8 @@ filter: for (final Locale locale : local
     }
 
     /**
-     * Converts a 3-letters ISO code to a 2-letters one. If the given code is not recognized,
-     * then this method returns {@code code} unmodified.
+     * Converts a 3-letters ISO code to a 2-letters one.
+     * If the given code is not recognized, then this method returns {@code code} unmodified.
      *
      * @param  code The 3-letters code.
      * @param  type Either {@link #LANGUAGE} or {@link #COUNTRY}.