[COLLECTIONS-671] Add

org.apache.commons.collections4.IterableUtils.first(Iterable).

src/changes/changes.xml

@@ -81,6 +81,9 @@
     <action issue="COLLECTIONS-670" dev="ggregory" type="add" due-to="Gary Gregory">
       Add org.apache.commons.collections4.IteratorUtils.first(Iterator).
     </action>
+    <action issue="COLLECTIONS-671" dev="ggregory" type="add" due-to="Gary Gregory">
+      Add org.apache.commons.collections4.IterableUtils.first(Iterable).
+    </action>
   </release>
   <release version="4.1" date="2015-11-28" description="This is a security and minor release.">
     <action issue="COLLECTIONS-508" dev="tn" type="add">

src/main/java/org/apache/commons/collections4/IterableUtils.java

@@ -774,6 +774,22 @@ public class IterableUtils {
         return IteratorUtils.get(emptyIteratorIfNull(iterable), index);
     }
 
+    /**
+     * Returns the <code>first</code> value in the <code>iterable</code>'s {@link Iterator}, throwing
+     * <code>IndexOutOfBoundsException</code> if there is no such element.
+     * <p>
+     * If the {@link Iterable} is a {@link List}, then it will use {@link List#get(int)}.
+     *
+     * @param <T> the type of object in the {@link Iterable}.
+     * @param iterable  the {@link Iterable} to get a value from, may be null
+     * @return the first object
+     * @throws IndexOutOfBoundsException if the request  is invalid
+     * @since 4.2
+     */
+    public static <T> T first(final Iterable<T> iterable) {
+        return get(iterable, 0);
+    }
+
     /**
      * Returns the number of elements contained in the given iterator.
      * <p>

src/test/java/org/apache/commons/collections4/IterableUtilsTest.java

@@ -393,17 +393,37 @@ public class IterableUtilsTest {
         assertTrue(IterableUtils.matchesAll(emptyIterable, lessThanFour));
     }
 
-    @Test(expected = IndexOutOfBoundsException.class)
     public void getFromIterable() throws Exception {
         // Collection, entry exists
         final Bag<String> bag = new HashBag<>();
         bag.add("element", 1);
         assertEquals("element", IterableUtils.get(bag, 0));
+    }
 
+    @Test(expected = IndexOutOfBoundsException.class)
+    public void getFromIterableIndexOutOfBoundsException() throws Exception {
+        // Collection, entry exists
+        final Bag<String> bag = new HashBag<>();
+        bag.add("element", 1);
         // Collection, non-existent entry
         IterableUtils.get(bag, 1);
     }
 
+    public void firstFromIterable() throws Exception {
+        // Collection, entry exists
+        final Bag<String> bag = new HashBag<>();
+        bag.add("element", 1);
+        assertEquals("element", IterableUtils.first(bag));
+    }
+
+    @Test(expected = IndexOutOfBoundsException.class)
+    public void firstFromIterableIndexOutOfBoundsException() throws Exception {
+        // Collection, entry exists
+        final Bag<String> bag = new HashBag<>();
+        // Collection, non-existent entry
+        IterableUtils.first(bag);
+    }
+
     @SuppressWarnings("unchecked")
     @Test
     public void partition() {