Package com.google.common.io

Class CharStreams

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

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static CharSink asCharSink​(OutputSupplier<? extends java.lang.Appendable> supplier)
      Returns a view of the given Appendable supplier as a CharSink.
      static CharSource asCharSource​(InputSupplier<? extends java.lang.Readable> supplier)
      Returns a view of the given Readable supplier as a CharSource.
      static CharSource asCharSource​(java.lang.String string)
      Deprecated.
      Use CharSource.wrap(CharSequence) instead.
      static java.io.Writer asWriter​(java.lang.Appendable target)
      Returns a Writer that sends all output to the given Appendable target.
      static <R extends java.lang.Readable & java.io.Closeable,​W extends java.lang.Appendable & java.io.Closeable>
      long      		 copy​(InputSupplier<R> from, OutputSupplier<W> to)
      Opens Readable and Appendable objects from the given factories, copies all characters between the two, and closes them.
      static <R extends java.lang.Readable & java.io.Closeable>
      long      		 copy​(InputSupplier<R> from, java.lang.Appendable to)
      Opens a Readable object from the supplier, copies all characters to the Appendable object, and closes the input.
      static long copy​(java.lang.Readable from, java.lang.Appendable to)
      Copies all characters between the Readable and Appendable objects.
      static InputSupplier<java.io.Reader> join​(InputSupplier<? extends java.io.Reader>... suppliers)
      Varargs form of join(Iterable).
      static InputSupplier<java.io.Reader> join​(java.lang.Iterable<? extends InputSupplier<? extends java.io.Reader>> suppliers)
      Joins multiple Reader suppliers into a single supplier.
      static InputSupplier<java.io.InputStreamReader> newReaderSupplier​(InputSupplier<? extends java.io.InputStream> in, java.nio.charset.Charset charset)
      Returns a factory that will supply instances of InputStreamReader, using the given InputStream factory and character set.
      static InputSupplier<java.io.StringReader> newReaderSupplier​(java.lang.String value)
      Returns a factory that will supply instances of StringReader that read a string value.
      static OutputSupplier<java.io.OutputStreamWriter> newWriterSupplier​(OutputSupplier<? extends java.io.OutputStream> out, java.nio.charset.Charset charset)
      Returns a factory that will supply instances of OutputStreamWriter, using the given OutputStream factory and character set.
      static java.io.Writer nullWriter()
      Returns a Writer that simply discards written chars.
      static <R extends java.lang.Readable & java.io.Closeable>
      java.lang.String      		 readFirstLine​(InputSupplier<R> supplier)
      Reads the first line from a Readable & Closeable object supplied by a factory.
      static <R extends java.lang.Readable & java.io.Closeable>
      java.util.List<java.lang.String>      		 readLines​(InputSupplier<R> supplier)
      Reads all of the lines from a Readable & Closeable object supplied by a factory.
      static <R extends java.lang.Readable & java.io.Closeable,​T>
      T      		 readLines​(InputSupplier<R> supplier, LineProcessor<T> callback)
      Streams lines from a Readable and Closeable object supplied by a factory, stopping when our callback returns false, or we have read all of the lines.
      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 <R extends java.lang.Readable & java.io.Closeable>
      java.lang.String      		 toString​(InputSupplier<R> supplier)
      Returns the characters from a Readable & Closeable object supplied by a factory as a String.
      static java.lang.String toString​(java.lang.Readable r)
      Reads all characters from a Readable object into a String.
      static <W extends java.lang.Appendable & java.io.Closeable>
      void      		 write​(java.lang.CharSequence from, OutputSupplier<W> to)
      Writes a character sequence (such as a string) to an appendable object from the given supplier.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • newReaderSupplier

        public static InputSupplier<java.io.StringReader> newReaderSupplier​(java.lang.String value)
        Returns a factory that will supply instances of StringReader that read a string value.
        Parameters:
        value - the string to read
        Returns:
        the factory

      • asCharSource

        @Deprecated
public static CharSource asCharSource​(java.lang.String string)
        Deprecated.
        Use CharSource.wrap(CharSequence) instead. This method is scheduled to be removed in Guava 16.0.
        Returns a CharSource that reads the given string value.
        Since:
        14.0

      • newReaderSupplier

        public static InputSupplier<java.io.InputStreamReader> newReaderSupplier​(InputSupplier<? extends java.io.InputStream> in,
                                                                         java.nio.charset.Charset charset)
        Returns a factory that will supply instances of InputStreamReader, using the given InputStream factory and character set.
        Parameters:
        in - the factory that will be used to open input streams
        charset - the charset used to decode the input stream; see Charsets for helpful predefined constants
        Returns:
        the factory

      • newWriterSupplier

        public static OutputSupplier<java.io.OutputStreamWriter> newWriterSupplier​(OutputSupplier<? extends java.io.OutputStream> out,
                                                                           java.nio.charset.Charset charset)
        Returns a factory that will supply instances of OutputStreamWriter, using the given OutputStream factory and character set.
        Parameters:
        out - the factory that will be used to open output streams
        charset - the charset used to encode the output stream; see Charsets for helpful predefined constants
        Returns:
        the factory

      • write

        public static <W extends java.lang.Appendable & java.io.Closeable> void write​(java.lang.CharSequence from,
                                                                              OutputSupplier<W> to)
                                                                       throws java.io.IOException
        Writes a character sequence (such as a string) to an appendable object from the given supplier.
        Parameters:
        from - the character sequence to write
        to - the output supplier
        Throws:
        java.io.IOException - if an I/O error occurs

      • copy

        public static <R extends java.lang.Readable & java.io.Closeable,​W extends java.lang.Appendable & java.io.Closeable> long copy​(InputSupplier<R> from,
                                                                                                                                    OutputSupplier<W> to)
                                                                                                                             throws java.io.IOException
        Opens Readable and Appendable objects from the given factories, copies all characters between the two, and closes them.
        Parameters:
        from - the input factory
        to - the output factory
        Returns:
        the number of characters copied
        Throws:
        java.io.IOException - if an I/O error occurs

      • copy

        public static <R extends java.lang.Readable & java.io.Closeable> long copy​(InputSupplier<R> from,
                                                                           java.lang.Appendable to)
                                                                    throws java.io.IOException
        Opens a Readable object from the supplier, copies all characters to the Appendable object, and closes the input. Does not close or flush the output.
        Parameters:
        from - the input factory
        to - the object to write to
        Returns:
        the number of characters copied
        Throws:
        java.io.IOException - if an I/O error occurs

      • 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

      • 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

      • toString

        public static <R extends java.lang.Readable & java.io.Closeable> java.lang.String toString​(InputSupplier<R> supplier)
                                                                                    throws java.io.IOException
        Returns the characters from a Readable & Closeable object supplied by a factory as a String.
        Parameters:
        supplier - the factory to read from
        Returns:
        a string containing all the characters
        Throws:
        java.io.IOException - if an I/O error occurs

      • readFirstLine

        public static <R extends java.lang.Readable & java.io.Closeable> java.lang.String readFirstLine​(InputSupplier<R> supplier)
                                                                                         throws java.io.IOException
        Reads the first line from a Readable & Closeable object supplied by a factory. The line does not include line-termination characters, but does include other leading and trailing whitespace.
        Parameters:
        supplier - the factory to read from
        Returns:
        the first line, or null if the reader is empty
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLines

        public static <R extends java.lang.Readable & java.io.Closeable> java.util.List<java.lang.String> readLines​(InputSupplier<R> supplier)
                                                                                                     throws java.io.IOException
        Reads all of the lines from a Readable & Closeable object supplied by a factory. The lines do not include line-termination characters, but do include other leading and trailing whitespace.
        Parameters:
        supplier - the factory to read from
        Returns:
        a mutable List containing all the lines
        Throws:
        java.io.IOException - if an I/O error occurs

      • readLines

        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

      • readLines

        public static <R extends java.lang.Readable & java.io.Closeable,​T> T readLines​(InputSupplier<R> supplier,
                                                                                     LineProcessor<T> callback)
                                                                              throws java.io.IOException
        Streams lines from a Readable and Closeable object supplied by a factory, stopping when our callback returns false, or we have read all of the lines.
        Parameters:
        supplier - the factory to read from
        callback - the LineProcessor to use to handle the lines
        Returns:
        the output of processing the lines
        Throws:
        java.io.IOException - if an I/O error occurs

      • join

        public static InputSupplier<java.io.Reader> join​(java.lang.Iterable<? extends InputSupplier<? extends java.io.Reader>> suppliers)
        Joins multiple Reader suppliers into a single supplier. Reader returned from the supplier will contain the concatenated data from the readers of the underlying suppliers.

        Reading from the joined reader will throw a NullPointerException if any of the suppliers are null or return null.

        Only one underlying reader will be open at a time. Closing the joined reader will close the open underlying reader.

        Parameters:
        suppliers - the suppliers to concatenate
        Returns:
        a supplier that will return a reader containing the concatenated data

      • 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.
        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

      • asCharSource

        public static CharSource asCharSource​(InputSupplier<? extends java.lang.Readable> supplier)
        Returns a view of the given Readable supplier as a CharSource.

        This method is a temporary method provided for easing migration from suppliers to sources and sinks.

        Since:
        15.0

      • asCharSink

        public static CharSink asCharSink​(OutputSupplier<? extends java.lang.Appendable> supplier)
        Returns a view of the given Appendable supplier as a CharSink.

        This method is a temporary method provided for easing migration from suppliers to sources and sinks.

        Since:
        15.0