Add IOUtils.readLines(CharSequence)

Author: garydgregory

src/changes/changes.xml

@@ -59,6 +59,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add IORandomAccessFile.</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add RandomAccessFileMode.io(String).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileAlterationObserver.Builder() and deprecate most constructors.</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add IOUtils.readLines(CharSequence).</action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update"             due-to="Gary Gregory">Bump org.apache.commons:commons-parent from 74 to 77 #670, #676, #679.</action>
       <action dev="ggregory" type="update"             due-to="Gary Gregory">Bump commons.bytebuddy.version from 1.15.1 to 1.15.5 #672, #673, #685, #686.</action>

src/main/java/org/apache/commons/io/IOUtils.java

@@ -64,6 +64,7 @@
 import org.apache.commons.io.function.IOConsumer;
 import org.apache.commons.io.function.IOSupplier;
 import org.apache.commons.io.function.IOTriFunction;
+import org.apache.commons.io.input.CharSequenceReader;
 import org.apache.commons.io.input.QueueInputStream;
 import org.apache.commons.io.output.AppendableWriter;
 import org.apache.commons.io.output.ByteArrayOutputStream;
@@ -2243,6 +2244,20 @@ public static List<String> readLines(final Reader reader) throws UncheckedIOExce
         return toBufferedReader(reader).lines().collect(Collectors.toList());
     }
 
+    /**
+     * Gets the contents of a {@link CharSequence} as a list of Strings, one entry per line.
+     *
+     * @param csq the {@link CharSequence} to read, not null
+     * @return the list of Strings, never null
+     * @throws UncheckedIOException if an I/O error occurs
+     * @since 2.18.0
+     */
+    public static List<String> readLines(final CharSequence csq) throws UncheckedIOException {
+        try (CharSequenceReader reader = new CharSequenceReader(csq)) {
+            return readLines(reader);
+        }
+    }
+
     /**
      * Gets the contents of a resource as a byte array.
      * <p>

src/test/java/org/apache/commons/io/IOUtilsTest.java

@@ -1015,6 +1015,36 @@ public void testReadFully_Reader_Offset() throws Exception {
         IOUtils.closeQuietly(reader);
     }
 
+    @Test
+    public void testReadLines_CharSequence() throws IOException {
+        final File file = TestUtils.newFile(temporaryFolder, "lines.txt");
+        CharSequence csq = null;
+        try {
+            final String[] data = {"hello", "/u1234", "", "this is", "some text"};
+            TestUtils.createLineBasedFile(file, data);
+            csq = new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8);
+            final List<String> lines = IOUtils.readLines(csq);
+            assertEquals(Arrays.asList(data), lines);
+        } finally {
+            TestUtils.deleteFile(file);
+        }
+    }
+
+    @Test
+    public void testReadLines_CharSequenceAsStringBuilder() throws IOException {
+        final File file = TestUtils.newFile(temporaryFolder, "lines.txt");
+        StringBuilder csq = null;
+        try {
+            final String[] data = {"hello", "/u1234", "", "this is", "some text"};
+            TestUtils.createLineBasedFile(file, data);
+            csq = new StringBuilder(new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8));
+            final List<String> lines = IOUtils.readLines(csq);
+            assertEquals(Arrays.asList(data), lines);
+        } finally {
+            TestUtils.deleteFile(file);
+        }
+    }
+
     @Test
     public void testReadLines_InputStream() throws Exception {
         final File file = TestUtils.newFile(temporaryFolder, "lines.txt");
@@ -1058,7 +1088,6 @@ public void testReadLines_Reader() throws Exception {
         try {
             final String[] data = {"hello", "/u1234", "", "this is", "some text"};
             TestUtils.createLineBasedFile(file, data);
-
             in = new InputStreamReader(Files.newInputStream(file.toPath()));
             final List<String> lines = IOUtils.readLines(in);
             assertEquals(Arrays.asList(data), lines);