Add IOIterable.unwrap()

Author: garydgregory

src/main/java/org/apache/commons/io/function/IOIterable.java

@@ -37,8 +37,7 @@ public interface IOIterable<T> {
      * @see Iterable#iterator()
      */
     default void forEach(final IOConsumer<? super T> action) throws IOException {
-        Objects.requireNonNull(action);
-        iterator().forEachRemaining(action);
+        iterator().forEachRemaining(Objects.requireNonNull(action));
     }
 
     /**
@@ -59,4 +58,13 @@ default IOSpliterator<T> spliterator() {
         return IOSpliteratorAdapter.adapt(new UncheckedIOIterable<>(this).spliterator());
     }
 
+    /**
+     * Unwraps this instance and returns the underlying {@link Iterable}.
+     * <p>
+     * Implementations may not have anything to unwrap and that behavior is undefined for now.
+     * </p>
+     * @return the underlying Iterable.
+     */
+    Iterable<T> unwrap();
+
 }

src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java

@@ -584,4 +584,9 @@ public String toString(final int lineCount) throws IOException {
         return lines.isEmpty() ? EMPTY_STRING : String.join(System.lineSeparator(), lines) + System.lineSeparator();
     }
 
+    @Override
+    public Iterable<String> unwrap() {
+        return null;
+    }
+
 }

src/test/java/org/apache/commons/io/function/IOIterableTest.java

@@ -18,6 +18,7 @@
 package org.apache.commons.io.function;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.io.IOException;
@@ -44,6 +45,11 @@ public IOIterator<Path> iterator() {
             return IOIterator.adapt(list);
         }
 
+        @Override
+        public Iterable<Path> unwrap() {
+            return list;
+        }
+
     }
 
     private IOIterable<Path> iterable;
@@ -76,4 +82,10 @@ public void testSpliterator() throws IOException {
         iterable.spliterator().forEachRemaining(e -> ref.incrementAndGet());
         assertEquals(2, ref.get());
     }
+
+    @Test
+    public void testUnrwap() throws IOException {
+        assertSame(fixture.list, iterable.unwrap());
+        assertSame(fixture.unwrap(), iterable.unwrap());
+    }
 }