Add documentation for CollectionUtils#arrayAsList

(This is a cherrypick of http://ag/576739)

Also, modify the IllegalArgumentException to capture the
values passed for start, end, and array.length to make
debugging easier in the unlikely event that it is thrown.
Add corresponding tests for the exceptions.

Tested:
tapas LatinImeGoogle LatinImeGoogleTests userdebug
make -j30 && \
adb install -r \
out/target/product/generic/data/app/LatinImeGoogleTests/LatinImeGoogleTests.apk && \
adb install -r \
out/target/product/generic/system/app/LatinImeGoogle/LatinImeGoogle.apk && \
adb shell am instrument -w -e class \
com.android.inputmethod.latin.utils.CollectionUtilsTests \
com.google.android.inputmethod.latin.tests/android.support.test.runner.AndroidJUnitRunner

Change-Id: I0c579ca4f4f2a9b2575aa6f8fa75e3ee4a21cf8a

java/src/com/android/inputmethod/latin/utils/CollectionUtils.java

@@ -22,16 +22,27 @@ import java.util.Collection;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+/**
+ * Utility methods for working with collections.
+ */
 public final class CollectionUtils {
     private CollectionUtils() {
         // This utility class is not publicly instantiable.
     }
 
+    /**
+     * Converts a sub-range of the given array to an ArrayList of the appropriate type.
+     * @param array Array to be converted.
+     * @param start First index inclusive to be converted.
+     * @param end Last index exclusive to be converted.
+     * @throws IllegalArgumentException if start or end are out of range or start > end.
+     */
     @Nonnull
     public static <E> ArrayList<E> arrayAsList(@Nonnull final E[] array, final int start,
             final int end) {
         if (start < 0 || start > end || end > array.length) {
-            throw new IllegalArgumentException();
+            throw new IllegalArgumentException("Invalid start: " + start + " end: " + end
+                    + " with array.length: " + array.length);
         }
 
         final ArrayList<E> list = new ArrayList<>(end - start);

tests/src/com/android/inputmethod/latin/utils/CollectionUtilsTests.java

@@ -28,15 +28,46 @@ import java.util.Collections;
  */
 @SmallTest
 public class CollectionUtilsTests extends AndroidTestCase {
+    /**
+     * Tests that {@link CollectionUtils#arrayAsList(Object[],int,int)} fails as expected
+     * with some invalid inputs.
+     */
+    public void testArrayAsListFailure() {
+        final String[] array = { "0", "1" };
+        // Negative start
+        try {
+            CollectionUtils.arrayAsList(array, -1, 1);
+            fail("Failed to catch start < 0");
+        } catch (final IllegalArgumentException e) {
+            assertEquals("Invalid start: -1 end: 1 with array.length: 2", e.getMessage());
+        }
+        // start > end
+        try {
+            CollectionUtils.arrayAsList(array, 1, -1);
+            fail("Failed to catch start > end");
+        } catch (final IllegalArgumentException e) {
+            assertEquals("Invalid start: 1 end: -1 with array.length: 2", e.getMessage());
+        }
+        // end > array.length
+        try {
+            CollectionUtils.arrayAsList(array, 1, 3);
+            fail("Failed to catch end > array.length");
+        } catch (final IllegalArgumentException e) {
+            assertEquals("Invalid start: 1 end: 3 with array.length: 2", e.getMessage());
+        }
+    }
+
     /**
      * Tests that {@link CollectionUtils#arrayAsList(Object[],int,int)} gives the expected
      * results for a few valid inputs.
      */
     public void testArrayAsList() {
-        final String[] array = { "0", "1", "2", "3", "4" };
         final ArrayList<String> empty = new ArrayList<>();
+        assertEquals(empty, CollectionUtils.arrayAsList(new String[] { }, 0, 0));
+        final String[] array = { "0", "1", "2", "3", "4" };
         assertEquals(empty, CollectionUtils.arrayAsList(array, 0, 0));
         assertEquals(empty, CollectionUtils.arrayAsList(array, 1, 1));
+        assertEquals(empty, CollectionUtils.arrayAsList(array, array.length, array.length));
         final ArrayList<String> expected123 = new ArrayList<>(Arrays.asList("1", "2", "3"));
         assertEquals(expected123, CollectionUtils.arrayAsList(array, 1, 4));
     }