Package com.google.common.io

Class CharStreams

  • @GwtIncompatible
public final class CharStreams
extends java.lang.Object
    Provides utility methods for working with character streams.
    Since:
    1.0
    Author:
    Chris Nokleberg, Bin Zhu, Colin Decker

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.io.Writer asWriter​(java.lang.Appendable target)
      Returns a Writer that sends all output to the given Appendable target.
      static long copy​(java.lang.Readable from, java.lang.Appendable to)
      Copies all characters between the Readable and Appendable objects.
      static long exhaust​(java.lang.Readable readable)
      Reads and discards data from the given Readable until the end of the stream is reached.
      static java.io.Writer nullWriter()
      Returns a Writer that simply discards written chars.
      static java.util.List<java.lang.String> readLines​(java.lang.Readable r)
      Reads all of the lines from a Readable object.
      static <T extends @Nullable java.lang.Object>
      T      		 readLines​(java.lang.Readable readable, LineProcessor<T> processor)
      Streams lines from a Readable object, stopping when the processor returns false or all lines have been read and returning the result produced by the processor.
      static void skipFully​(java.io.Reader reader, long n)
      Discards n characters of data from the reader.
      static java.lang.String toString​(java.lang.Readable r)
      Reads all characters from a Readable object into a String.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • copy

        @CanIgnoreReturnValue
public static long copy​(java.lang.Readable from,
                        java.lang.Appendable to)
                 throws java.io.IOException
        Copies all characters between the Readable and Appendable objects. Does not close or flush either object.
        Parameters:
        from - the object to read from
        to - the object to write to
        Returns:
        the number of characters copied
        Throws:
        java.io.IOException - if an I/O error occurs

      • toString

        public static java.lang.String toString​(java.lang.Readable r)
                                 throws java.io.IOException
        Reads all characters from a Readable object into a String. Does not close the Readable.

        Java 25+ users: If the input is a Reader, prefer Reader#readAllAsString().

        Parameters:
        r - the object to read from
        Returns:
        a string containing all the characters
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLines

        public static java.util.List<java.lang.String> readLines​(java.lang.Readable r)
                                                  throws java.io.IOException
        Reads all of the lines from a Readable object. The lines do not include line-termination characters, but do include other leading and trailing whitespace.

        Does not close the Readable. If reading files or resources you should use the Files.readLines(java.io.File, java.nio.charset.Charset) and Resources.readLines(java.net.URL, java.nio.charset.Charset, com.google.common.io.LineProcessor<T>) methods.

        This method prioritizes convenience over performance: It reads the entire input into memory immediately. To instead read and process lines individually, use an alternative like BufferedReader.lines().

        Java 25+ users: If the input is a Reader, you may prefer Reader#readAllLines(). The two may have different performance characteristics for different Reader classes and Java versions, but both methods read the entire input into memory immediately, so we discourage use of both when memory usage is a concern.

        Parameters:
        r - the object to read from
        Returns:
        a mutable List containing all the lines
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLines

        @CanIgnoreReturnValue
public static <T extends @Nullable java.lang.Object> T readLines​(java.lang.Readable readable,
                                                                 LineProcessor<T> processor)
                                                          throws java.io.IOException
        Streams lines from a Readable object, stopping when the processor returns false or all lines have been read and returning the result produced by the processor. Does not close readable. Note that this method may not fully consume the contents of readable if the processor stops processing early.

        Users who can use Stream: If your input is a Reader, consider wrapping it with a BufferedReader and operating on the Stream of lines returned by BufferedReader.lines().

        Throws:
        java.io.IOException - if an I/O error occurs
        Since:
        14.0

      • exhaust

        @CanIgnoreReturnValue
public static long exhaust​(java.lang.Readable readable)
                    throws java.io.IOException
        Reads and discards data from the given Readable until the end of the stream is reached. Returns the total number of chars read. Does not close the stream.
        Throws:
        java.io.IOException
        Since:
        20.0

      • skipFully

        public static void skipFully​(java.io.Reader reader,
                             long n)
                      throws java.io.IOException
        Discards n characters of data from the reader. This method will block until the full amount has been skipped. Does not close the reader.
        Parameters:
        reader - the reader to read from
        n - the number of characters to skip
        Throws:
        java.io.EOFException - if this stream reaches the end before skipping all the characters
        java.io.IOException - if an I/O error occurs

      • nullWriter

        public static java.io.Writer nullWriter()
        Returns a Writer that simply discards written chars.

        Java 11+ users: use Writer.nullWriter() instead. Note that the CharStreams method returns a singleton writer whose close method has no effect, while the Writer.nullWriter() method returns a new instance whose methods throw after the instance is closed.

        Since:
        15.0

      • asWriter

        public static java.io.Writer asWriter​(java.lang.Appendable target)
        Returns a Writer that sends all output to the given Appendable target. Closing the writer will close the target if it is Closeable, and flushing the writer will flush the target if it is Flushable.
        Parameters:
        target - the object to which output will be sent
        Returns:
        a new Writer object, unless target is a Writer, in which case the target is returned