Package com.google.common.io

Class CharStreams

  • @GwtIncompatible
public final class CharStreams
extends java.lang.Object
    Provides utility methods for working with character streams.

    All method parameters must be non-null unless documented otherwise.

    Some of the methods in this class take arguments with a generic type of Readable & Closeable. A Reader implements both of those interfaces. Similarly for Appendable & Closeable and Writer.

    Since:
    1.0

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  CharStreams.NullWriter  

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int DEFAULT_BUF_SIZE  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private CharStreams()  

    • 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.
      (package private) static long copyReaderToBuilder​(java.io.Reader from, java.lang.StringBuilder to)
      Copies all characters between the Reader and StringBuilder objects.
      (package private) static long copyReaderToWriter​(java.io.Reader from, java.io.Writer to)
      Copies all characters between the Reader and Writer objects.
      (package private) static java.nio.CharBuffer createBuffer()
      Creates a new CharBuffer for buffering reads or writes.
      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> 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.
      private static java.lang.StringBuilder toStringBuilder​(java.lang.Readable r)
      Reads all characters from a Readable object into a new StringBuilder instance.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • CharStreams

        private CharStreams()

    • Method Detail

      • createBuffer

        static java.nio.CharBuffer createBuffer()
        Creates a new CharBuffer for buffering reads or writes.

      • copy

        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

      • copyReaderToBuilder

        static long copyReaderToBuilder​(java.io.Reader from,
                                java.lang.StringBuilder to)
                         throws java.io.IOException
        Copies all characters between the Reader and StringBuilder objects. Does not close or flush the reader.

        This is identical to copy(Readable, Appendable) but optimized for these specific types. CharBuffer has poor performance when being written into or read out of so round tripping all the bytes through the buffer takes a long time. With these specialized types we can just use a char array.

        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

      • copyReaderToWriter

        static long copyReaderToWriter​(java.io.Reader from,
                               java.io.Writer to)
                        throws java.io.IOException
        Copies all characters between the Reader and Writer objects. Does not close or flush the reader or writer.

        This is identical to copy(Readable, Appendable) but optimized for these specific types. CharBuffer has poor performance when being written into or read out of so round tripping all the bytes through the buffer takes a long time. With these specialized types we can just use a char array.

        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.
        Parameters:
        r - the object to read from
        Returns:
        a string containing all the characters
        Throws:
        java.io.IOException - if an I/O error occurs

      • toStringBuilder

        private static java.lang.StringBuilder toStringBuilder​(java.lang.Readable r)
                                                throws java.io.IOException
        Reads all characters from a Readable object into a new StringBuilder instance. Does not close the Readable.
        Parameters:
        r - the object to read from
        Returns:
        a StringBuilder containing all the characters
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLines

        @Beta
public static <T> 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.
        Throws:
        java.io.IOException - if an I/O error occurs
        Since:
        14.0

      • exhaust

        @Beta
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

        @Beta
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

        @Beta
public static java.io.Writer nullWriter()
        Returns a Writer that simply discards written chars.
        Since:
        15.0

      • asWriter

        @Beta
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