[COLLECTIONS-670] Add

org.apache.commons.collections4.IteratorUtils.first(Iterator).

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

@@ -1412,6 +1412,23 @@ public class IteratorUtils {
         throw new IndexOutOfBoundsException("Entry does not exist: " + i);
     }
 
+    /**
+     * Returns the <code>first</code> value in {@link Iterator}, throwing
+     * <code>IndexOutOfBoundsException</code> if there is no such element.
+     * <p>
+     * The Iterator is advanced to <code>index</code> (or to the end, if
+     * <code>index</code> exceeds the number of entries) as a side effect of this method.
+     *
+     * @param <E> the type of object in the {@link Iterator}
+     * @param iterator  the iterator to get a value from
+     * @return the first object
+     * @throws IndexOutOfBoundsException if the request is invalid
+     * @since 4.2
+     */
+    public static <E> E first(final Iterator<E> iterator) {
+        return get(iterator, 0);
+    }
+
     /**
      * Returns the number of elements contained in the given iterator.
      * <p>

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

@@ -1005,7 +1005,7 @@ public class IteratorUtilsTest {
 
     // -----------------------------------------------------------------------
     @Test
-    public void forEach() {
+    public void testForEach() {
         final List<Integer> listA = new ArrayList<>();
         listA.add(1);
 
@@ -1033,7 +1033,7 @@ public class IteratorUtilsTest {
     }
 
     @Test
-    public void forEachButLast() {
+    public void testForEachButLast() {
         final List<Integer> listA = new ArrayList<>();
         listA.add(1);
 
@@ -1065,7 +1065,7 @@ public class IteratorUtilsTest {
     }
 
     @Test
-    public void find() {
+    public void testFind() {
         Predicate<Number> testPredicate = equalPredicate((Number) 4);
         Integer test = IteratorUtils.find(iterableA.iterator(), testPredicate);
         assertTrue(test.equals(4));
@@ -1082,7 +1082,7 @@ public class IteratorUtilsTest {
     }
 
     @Test
-    public void indexOf() {
+    public void testIndexOf() {
         Predicate<Number> testPredicate = equalPredicate((Number) 4);
         int index = IteratorUtils.indexOf(iterableA.iterator(), testPredicate);
         assertEquals(6, index);
@@ -1099,7 +1099,7 @@ public class IteratorUtilsTest {
     }
 
     @Test
-    public void getFromIterator() throws Exception {
+    public void testGetAtIndexFromIterator() throws Exception {
         // Iterator, entry exists
         Iterator<Integer> iterator = iterableA.iterator();
         assertEquals(1, (int) IteratorUtils.get(iterator, 0));
@@ -1116,6 +1116,13 @@ public class IteratorUtilsTest {
         assertTrue(!iterator.hasNext());
     }
 
+    @Test
+    public void testFirstFromIterator() throws Exception {
+        // Iterator, entry exists
+        Iterator<Integer> iterator = iterableA.iterator();
+        assertEquals(1, (int) IteratorUtils.first(iterator));
+    }
+
     @Test
     public void testGetIterator() {
     	final Object[] objArray = {"a", "b", "c"};