Package com.globalmentor.io

Class Readers

java.lang.Object
com.globalmentor.io.Readers
public class Readers extends Object
Utility methods for working with Reader instances.
Author:
Garret Wilson

  • Constructor Summary

    Constructors
    Constructor
    Description
    Readers()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    read(Reader reader, char[] buffer)
    Fills a buffer with characters from a reader, starting at its beginning, blocking until the buffer is full or the end of the reader is reached.
    static int
    read(Reader reader, char[] buffer, int length)
    Fills a section of a buffer with characters from a reader, starting at its beginning, blocking until the buffer is full or the end of the reader is reached.
    static int
    read(Reader reader, char[] buffer, int offset, int length)
    Fills a section of a buffer with characters from a reader, blocking until the buffer is full or the end of the reader is reached.
    static String
    readString(Reader reader)
    Reads all characters remaining in the reader into a string.
    static String
    readString(Reader reader, int maxLength)
    Reads all characters remaining in the reader into a string up until the given maximum length.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Readers

      public Readers()

  • Method Details

    • read

      public static int read(Reader reader, char[] buffer) throws IOException
      Fills a buffer with characters from a reader, starting at its beginning, blocking until the buffer is full or the end of the reader is reached.
      API Note:
      This method functions identically to Reader.read(char[]) except that this method guarantees that the buffer will always be filled unless the end of the reader is reached or an error is encountered.
      Implementation Specification:
      This implementation delegates to read(Reader, char[], int).
      Implementation Note:
      Technically the Reader read API does not guarantee that an IndexOutOfBoundsException will be thrown, but many implementations do and the analogous InputStream methods explicitly indicate IndexOutOfBoundsException. Importantly this method will throw whatever exception the underlying Reader throws.
      Parameters:
      reader - The reader from which to read.
      buffer - The buffer to fill.
      Returns:
      The number of characters actually read; if less than the size of the buffer, the end of the reader has been reached.
      Throws:
      IndexOutOfBoundsException - If the length is negative or the length is greater than the size of the buffer.
      IOException - if there is an error reading from the reader.
      See Also:

    • read

      public static int read(Reader reader, char[] buffer, int length) throws IOException
      Fills a section of a buffer with characters from a reader, starting at its beginning, blocking until the buffer is full or the end of the reader is reached.
      API Note:
      This method functions identically to Reader.read(char[], int, int) with an offset of 0 except that this method guarantees that the requested number of characters will always be read unless the end of the reader is reached or an error is encountered.
      Implementation Specification:
      This implementation delegates to read(Reader, char[], int, int).
      Implementation Note:
      Technically the Reader read API does not guarantee that an IndexOutOfBoundsException will be thrown, but many implementations do and the analogous InputStream methods explicitly indicate IndexOutOfBoundsException. Importantly this method will throw whatever exception the underlying Reader throws.
      Parameters:
      reader - The reader from which to read.
      buffer - The buffer to fill.
      length - The maximum number of characters to read.
      Returns:
      The number of characters actually read; if less than the requested length, the end of the reader has been reached.
      Throws:
      IndexOutOfBoundsException - If the length is negative or the length is greater than the size of the buffer.
      IOException - if there is an error reading from the reader.
      See Also:

    • read

      public static int read(Reader reader, char[] buffer, int offset, int length) throws IOException
      Fills a section of a buffer with characters from a reader, blocking until the buffer is full or the end of the reader is reached.
      API Note:
      This method functions identically to Reader.read(char[], int, int) except that this method guarantees that the requested number of characters will always be read unless the end of the reader is reached or an error is encountered.
      Implementation Note:
      Technically the Reader read API does not guarantee that an IndexOutOfBoundsException will be thrown, but many implementations do and the analogous InputStream methods explicitly indicate IndexOutOfBoundsException. Importantly this method will throw whatever exception the underlying Reader throws.
      Parameters:
      reader - The reader from which to read.
      buffer - The buffer to fill.
      offset - The start offset in the buffer at which the data is written.
      length - The maximum number of characters to read.
      Returns:
      The number of characters actually read; if less than the requested length, the end of the reader has been reached.
      Throws:
      IndexOutOfBoundsException - If the offset is negative, the length is negative, or the length is greater than the remaining characters in the buffer starting at the given offset.
      IOException - if there is an error reading from the reader.
      See Also:

    • readString

      public static String readString(@Nonnull Reader reader) throws IOException
      Reads all characters remaining in the reader into a string. This method will block until some input is available, an I/O error occurs, or the end of the reader is reached.
      API Note:
      This method is analogous to {{java.nio.file.Files.readString(Path path)}}, introduced in Java 11.
      Implementation Specification:
      This implementation delegates to readString(Reader, int) with a maximum length of 2147483647.
      Parameters:
      reader - The reader from which to read content.
      Returns:
      A string containing all the remaining characters read from the reader.
      Throws:
      IOException - if an I/O error occurs.

    • readString

      public static String readString(@Nonnull Reader reader, @Nonnegative int maxLength) throws IOException
      Reads all characters remaining in the reader into a string up until the given maximum length. This method will block until some input is available, an I/O error occurs, or the end of the reader is reached.
      Parameters:
      reader - The reader from which to read content.
      maxLength - The maximum number of characters to read; may be 2147483647.
      Returns:
      A string containing all the remaining characters read from the reader but no longer that the given maximum length.
      Throws:
      IllegalArgumentException - if the given maximum length is negative.
      IOException - if an I/O error occurs.