Java : Reader with Examples

final var path = Path.of("R:", "java-work", "aaa.txt");
System.out.println(path); // R:\java-work\aaa.txt

Files.writeString(path, "abcXYZ");

try (final Reader reader = Files.newBufferedReader(path)) {
    System.out.printf("%c%n", reader.read()); // a
    System.out.printf("%c%n", reader.read()); // b
    System.out.printf("%c%n", reader.read()); // c

    final var cbuf = new char[3];

    System.out.println(reader.read(cbuf)); // 3
    System.out.println(Arrays.toString(cbuf)); // [X, Y, Z]
}

protected Object lock

The object used to synchronize operations on this stream.

I think it's rare to create a subclass of Reader. Therefore, the code example is omitted.

Reader ()

Creates a new character-stream reader whose critical sections will synchronize on the reader itself.

I think it's rare to create a subclass of Reader. Therefore, the code example is omitted.

Reader (Object lock)

Creates a new character-stream reader whose critical sections will synchronize on the given object.

I think it's rare to create a subclass of Reader. Therefore, the code example is omitted.

abstract void close ()

Closes the stream and releases any system resources associated with it.

final var path = Path.of("R:", "java-work", "aaa.txt");
System.out.println(path); // R:\java-work\aaa.txt

Files.writeString(path, "abcd");

try (final Reader reader = Files.newBufferedReader(path)) {
    final var cbuf = new char[4];

    System.out.println(reader.read(cbuf)); // 4
    System.out.println(Arrays.toString(cbuf)); // [a, b, c, d]
}

// An example without a try-with-resources statement.
final var path = Path.of("R:", "java-work", "aaa.txt");
System.out.println(path); // R:\java-work\aaa.txt

Files.writeString(path, "abcd");

final Reader reader = Files.newBufferedReader(path);
try {
    final var cbuf = new char[4];

    System.out.println(reader.read(cbuf)); // 4
    System.out.println(Arrays.toString(cbuf)); // [a, b, c, d]
} finally {
    reader.close();
}

void mark (int readAheadLimit)

Marks the present position in the stream.

try (final Reader reader = new BufferedReader(new StringReader("abcde"))) {
    System.out.printf("%c%n", reader.read()); // a
    System.out.printf("%c%n", reader.read()); // b
    System.out.printf("%c%n", reader.read()); // c

    reader.mark(3);

    System.out.printf("%c%n", reader.read()); // d
    System.out.printf("%c%n", reader.read()); // e
    System.out.println(reader.read()); // -1

    reader.reset();

    System.out.printf("%c%n", reader.read()); // d
    System.out.printf("%c%n", reader.read()); // e
    System.out.println(reader.read()); // -1

    reader.reset();
    reader.mark(2);

    System.out.printf("%c%n", reader.read()); // d
    System.out.printf("%c%n", reader.read()); // e
    System.out.println(reader.read()); // -1

    try {
        reader.reset();
    } catch (IOException e) {
        System.out.println("IOException! : " + e.getMessage());
    }

    // Result
    // ↓
    //IOException! : Mark invalid
}

boolean markSupported ()

Tells whether this stream supports the mark() operation.

final var path = Path.of("R:", "java-work", "aaa.txt");
System.out.println(path); // R:\java-work\aaa.txt

Files.writeString(path, "abcd");

try (final Reader reader = Files.newBufferedReader(path)) {
    System.out.println(reader.markSupported()); // true
}

try (final Reader reader = new StringReader("abcd")) {
    System.out.println(reader.markSupported()); // true
}

final var url = new URL("https://example.com/");

try (final Reader reader = new InputStreamReader(url.openStream())) {
    System.out.println(reader.markSupported()); // false
}

static Reader nullReader ()

Returns a new Reader that reads no characters.

final var reader = Reader.nullReader();

System.out.println(reader.read()); // -1
System.out.println(reader.ready()); // false

reader.close();

//reader.read(); // IOException: Stream closed

int read ()

Reads a single character.

try (final Reader reader = new StringReader("abc")) {
    System.out.printf("%c%n", reader.read()); // a
    System.out.printf("%c%n", reader.read()); // b
    System.out.printf("%c%n", reader.read()); // c
    System.out.println(reader.read()); // -1
}

int read (char[] cbuf)

Reads characters into an array.

try (final Reader reader = new StringReader("abcde")) {
    final var cbuf1 = new char[3];

    System.out.println(reader.read(cbuf1)); // 3
    System.out.println(Arrays.toString(cbuf1)); // [a, b, c]

    final var cbuf2 = new char[5];

    System.out.println(reader.read(cbuf2)); // 2
    System.out.println(Arrays.toString(cbuf2)); // [d, e,  ,  ,  ]

    final var cbuf3 = new char[2];

    System.out.println(reader.read(cbuf3)); // -1
    System.out.println(Arrays.toString(cbuf3)); // [ ,  ]
}

abstract int read (char[] cbuf, int off, int len)

Reads characters into a portion of an array.

try (final Reader reader = new StringReader("abcdefg")) {
    final var cbuf = new char[5];

    System.out.println(reader.read(cbuf, 0, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [a,  ,  ,  ,  ]

    System.out.println(reader.read(cbuf, 0, 2)); // 2
    System.out.println(Arrays.toString(cbuf)); // [b, c,  ,  ,  ]

    System.out.println(reader.read(cbuf, 0, 3)); // 3
    System.out.println(Arrays.toString(cbuf)); // [d, e, f,  ,  ]

    System.out.println(reader.read(cbuf, 0, 4)); // 1
    System.out.println(Arrays.toString(cbuf)); // [g, e, f,  ,  ]

    System.out.println(reader.read(cbuf, 0, 5)); // -1
    System.out.println(Arrays.toString(cbuf)); // [g, e, f,  ,  ]
}

try (final Reader reader = new StringReader("abcde")) {
    final var cbuf = new char[5];

    System.out.println(reader.read(cbuf, 4, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [ ,  ,  ,  , a]

    System.out.println(reader.read(cbuf, 3, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [ ,  ,  , b, a]

    System.out.println(reader.read(cbuf, 2, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [ ,  , c, b, a]

    System.out.println(reader.read(cbuf, 1, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [ , d, c, b, a]

    System.out.println(reader.read(cbuf, 0, 1)); // 1
    System.out.println(Arrays.toString(cbuf)); // [e, d, c, b, a]
}

try (final Reader reader = new StringReader("abcdefg")) {
    final var cbuf = new char[3];

    System.out.println(reader.read(cbuf, 0, 3)); // 3
    System.out.println(Arrays.toString(cbuf)); // [a, b, c]

    //reader.read(cbuf, 0, 4); // IndexOutOfBoundsException
    //reader.read(cbuf, 3, 1); // IndexOutOfBoundsException
}

int read (CharBuffer target)

Attempts to read characters into the specified character buffer.

try (final Reader reader = new StringReader("abc")) {
    final var target = CharBuffer.allocate(5);

    System.out.println(reader.read(target)); // 3
    System.out.println(Arrays.toString(target.array())); // [a, b, c,  ,  ]
}

boolean ready ()

Tells whether this stream is ready to be read.

final var path = Path.of("R:", "java-work", "aaa.txt");
System.out.println(path); // R:\java-work\aaa.txt

Files.writeString(path, "abc");

try (final Reader reader = Files.newBufferedReader(path)) {
    System.out.println(reader.ready()); // true
    System.out.printf("%c%n", reader.read()); // a

    System.out.println(reader.ready()); // true
    System.out.printf("%c%n", reader.read()); // b

    System.out.println(reader.ready()); // true
    System.out.printf("%c%n", reader.read()); // c

    System.out.println(reader.ready()); // false
    System.out.println(reader.read()); // -1
}

void reset ()

Resets the stream.

Please see mark(int readAheadLimit).

long skip (long n)

Skips characters.

try (final Reader reader = new StringReader("abcdefghij")) {
    System.out.printf("%c%n", reader.read()); // a

    System.out.println(reader.skip(1)); // 1
    System.out.printf("%c%n", reader.read()); // c

    System.out.println(reader.skip(2)); // 2
    System.out.printf("%c%n", reader.read()); // f

    System.out.println(reader.skip(3)); // 3
    System.out.printf("%c%n", reader.read()); // j

    System.out.println(reader.skip(1)); // 0
    System.out.println(reader.read()); // -1
}

try (final Reader reader = new StringReader("abcde")) {
    System.out.printf("%c%n", reader.read()); // a

    System.out.println(reader.skip(10)); // 4
    System.out.println(reader.read()); // -1
}

long transferTo (Writer out)

Reads all characters from this reader and writes the characters to the given writer in the order that they are read.

try (final Reader reader = new StringReader("abcde")) {
    try (final var writer = new StringWriter()) {
        System.out.println(reader.transferTo(writer)); // 5
        System.out.println(writer); // abcde
    }
}