1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.io;
27
28
29 import java.util.Iterator;
30 import java.util.NoSuchElementException;
31 import java.util.Spliterator;
32 import java.util.Spliterators;
33 import java.util.stream.Stream;
34 import java.util.stream.StreamSupport;
35
36 /**
37 * Reads text from a character-input stream, buffering characters so as to
38 * provide for the efficient reading of characters, arrays, and lines.
39 *
40 * <p> The buffer size may be specified, or the default size may be used. The
41 * default is large enough for most purposes.
42 *
43 * <p> In general, each read request made of a Reader causes a corresponding
44 * read request to be made of the underlying character or byte stream. It is
45 * therefore advisable to wrap a BufferedReader around any Reader whose read()
46 * operations may be costly, such as FileReaders and InputStreamReaders. For
47 * example,
48 *
49 * <pre>
50 * BufferedReader in
51 * = new BufferedReader(new FileReader("foo.in"));
52 * </pre>
53 *
54 * will buffer the input from the specified file. Without buffering, each
55 * invocation of read() or readLine() could cause bytes to be read from the
56 * file, converted into characters, and then returned, which can be very
57 * inefficient.
58 *
59 * <p> Programs that use DataInputStreams for textual input can be localized by
60 * replacing each DataInputStream with an appropriate BufferedReader.
61 *
62 * @see FileReader
63 * @see InputStreamReader
64 * @see java.nio.file.Files#newBufferedReader
65 *
66 * @author Mark Reinhold
67 * @since 1.1
68 */
69
70 public class BufferedReader extends Reader {
71
72 private Reader in;
73
74 private char cb[];
75 private int nChars, nextChar;
76
77 private static final int INVALIDATED = -2;
78 private static final int UNMARKED = -1;
79 private int markedChar = UNMARKED;
80 private int readAheadLimit = 0; /* Valid only when markedChar > 0 */
81
82 /** If the next character is a line feed, skip it */
83 private boolean skipLF = false;
84
85 /** The skipLF flag when the mark was set */
86 private boolean markedSkipLF = false;
87
88 private static int defaultCharBufferSize = 8192;
89 private static int defaultExpectedLineLength = 80;
90
91 /**
92 * Creates a buffering character-input stream that uses an input buffer of
93 * the specified size.
94 *
95 * @param in A Reader
96 * @param sz Input-buffer size
97 *
98 * @exception IllegalArgumentException If {@code sz <= 0}
99 */
100 public BufferedReader(Reader in, int sz) {
101 super(in);
102 if (sz <= 0)
103 throw new IllegalArgumentException("Buffer size <= 0");
104 this.in = in;
105 cb = new char[sz];
106 nextChar = nChars = 0;
107 }
108
109 /**
110 * Creates a buffering character-input stream that uses a default-sized
111 * input buffer.
112 *
113 * @param in A Reader
114 */
115 public BufferedReader(Reader in) {
116 this(in, defaultCharBufferSize);
117 }
118
119 /** Checks to make sure that the stream has not been closed */
120 private void ensureOpen() throws IOException {
121 if (in == null)
122 throw new IOException("Stream closed");
123 }
124
125 /**
126 * Fills the input buffer, taking the mark into account if it is valid.
127 */
128 private void fill() throws IOException {
129 int dst;
130 if (markedChar <= UNMARKED) {
131 /* No mark */
132 dst = 0;
133 } else {
134 /* Marked */
135 int delta = nextChar - markedChar;
136 if (delta >= readAheadLimit) {
137 /* Gone past read-ahead limit: Invalidate mark */
138 markedChar = INVALIDATED;
139 readAheadLimit = 0;
140 dst = 0;
141 } else {
142 if (readAheadLimit <= cb.length) {
143 /* Shuffle in the current buffer */
144 System.arraycopy(cb, markedChar, cb, 0, delta);
145 markedChar = 0;
146 dst = delta;
147 } else {
148 /* Reallocate buffer to accommodate read-ahead limit */
149 char ncb[] = new char[readAheadLimit];
150 System.arraycopy(cb, markedChar, ncb, 0, delta);
151 cb = ncb;
152 markedChar = 0;
153 dst = delta;
154 }
155 nextChar = nChars = delta;
156 }
157 }
158
159 int n;
160 do {
161 n = in.read(cb, dst, cb.length - dst);
162 } while (n == 0);
163 if (n > 0) {
164 nChars = dst + n;
165 nextChar = dst;
166 }
167 }
168
169 /**
170 * Reads a single character.
171 *
172 * @return The character read, as an integer in the range
173 * 0 to 65535 (<tt>0x00-0xffff</tt>), or -1 if the
174 * end of the stream has been reached
175 * @exception IOException If an I/O error occurs
176 */
177 public int read() throws IOException {
178 synchronized (lock) {
179 ensureOpen();
180 for (;;) {
181 if (nextChar >= nChars) {
182 fill();
183 if (nextChar >= nChars)
184 return -1;
185 }
186 if (skipLF) {
187 skipLF = false;
188 if (cb[nextChar] == '\n') {
189 nextChar++;
190 continue;
191 }
192 }
193 return cb[nextChar++];
194 }
195 }
196 }
197
198 /**
199 * Reads characters into a portion of an array, reading from the underlying
200 * stream if necessary.
201 */
202 private int read1(char[] cbuf, int off, int len) throws IOException {
203 if (nextChar >= nChars) {
204 /* If the requested length is at least as large as the buffer, and
205 if there is no mark/reset activity, and if line feeds are not
206 being skipped, do not bother to copy the characters into the
207 local buffer. In this way buffered streams will cascade
208 harmlessly. */
209 if (len >= cb.length && markedChar <= UNMARKED && !skipLF) {
210 return in.read(cbuf, off, len);
211 }
212 fill();
213 }
214 if (nextChar >= nChars) return -1;
215 if (skipLF) {
216 skipLF = false;
217 if (cb[nextChar] == '\n') {
218 nextChar++;
219 if (nextChar >= nChars)
220 fill();
221 if (nextChar >= nChars)
222 return -1;
223 }
224 }
225 int n = Math.min(len, nChars - nextChar);
226 System.arraycopy(cb, nextChar, cbuf, off, n);
227 nextChar += n;
228 return n;
229 }
230
231 /**
232 * Reads characters into a portion of an array.
233 *
234 * <p> This method implements the general contract of the corresponding
235 * <code>{@link Reader#read(char[], int, int) read}</code> method of the
236 * <code>{@link Reader}</code> class. As an additional convenience, it
237 * attempts to read as many characters as possible by repeatedly invoking
238 * the <code>read</code> method of the underlying stream. This iterated
239 * <code>read</code> continues until one of the following conditions becomes
240 * true: <ul>
241 *
242 * <li> The specified number of characters have been read,
243 *
244 * <li> The <code>read</code> method of the underlying stream returns
245 * <code>-1</code>, indicating end-of-file, or
246 *
247 * <li> The <code>ready</code> method of the underlying stream
248 * returns <code>false</code>, indicating that further input requests
249 * would block.
250 *
251 * </ul> If the first <code>read</code> on the underlying stream returns
252 * <code>-1</code> to indicate end-of-file then this method returns
253 * <code>-1</code>. Otherwise this method returns the number of characters
254 * actually read.
255 *
256 * <p> Subclasses of this class are encouraged, but not required, to
257 * attempt to read as many characters as possible in the same fashion.
258 *
259 * <p> Ordinarily this method takes characters from this stream's character
260 * buffer, filling it from the underlying stream as necessary. If,
261 * however, the buffer is empty, the mark is not valid, and the requested
262 * length is at least as large as the buffer, then this method will read
263 * characters directly from the underlying stream into the given array.
264 * Thus redundant <code>BufferedReader</code>s will not copy data
265 * unnecessarily.
266 *
267 * @param cbuf Destination buffer
268 * @param off Offset at which to start storing characters
269 * @param len Maximum number of characters to read
270 *
271 * @return The number of characters read, or -1 if the end of the
272 * stream has been reached
273 *
274 * @exception IOException If an I/O error occurs
275 * @exception IndexOutOfBoundsException {@inheritDoc}
276 */
277 public int read(char cbuf[], int off, int len) throws IOException {
278 synchronized (lock) {
279 ensureOpen();
280 if ((off < 0) || (off > cbuf.length) || (len < 0) ||
281 ((off + len) > cbuf.length) || ((off + len) < 0)) {
282 throw new IndexOutOfBoundsException();
283 } else if (len == 0) {
284 return 0;
285 }
286
287 int n = read1(cbuf, off, len);
288 if (n <= 0) return n;
289 while ((n < len) && in.ready()) {
290 int n1 = read1(cbuf, off + n, len - n);
291 if (n1 <= 0) break;
292 n += n1;
293 }
294 return n;
295 }
296 }
297
298 /**
299 * Reads a line of text. A line is considered to be terminated by any one
300 * of a line feed ('\n'), a carriage return ('\r'), or a carriage return
301 * followed immediately by a linefeed.
302 *
303 * @param ignoreLF If true, the next '\n' will be skipped
304 *
305 * @return A String containing the contents of the line, not including
306 * any line-termination characters, or null if the end of the
307 * stream has been reached
308 *
309 * @see java.io.LineNumberReader#readLine()
310 *
311 * @exception IOException If an I/O error occurs
312 */
313 String readLine(boolean ignoreLF) throws IOException {
314 StringBuffer s = null;
315 int startChar;
316
317 synchronized (lock) {
318 ensureOpen();
319 boolean omitLF = ignoreLF || skipLF;
320
321 bufferLoop:
322 for (;;) {
323
324 if (nextChar >= nChars)
325 fill();
326 if (nextChar >= nChars) { /* EOF */
327 if (s != null && s.length() > 0)
328 return s.toString();
329 else
330 return null;
331 }
332 boolean eol = false;
333 char c = 0;
334 int i;
335
336 /* Skip a leftover '\n', if necessary */
337 if (omitLF && (cb[nextChar] == '\n'))
338 nextChar++;
339 skipLF = false;
340 omitLF = false;
341
342 charLoop:
343 for (i = nextChar; i < nChars; i++) {
344 c = cb[i];
345 if ((c == '\n') || (c == '\r')) {
346 eol = true;
347 break charLoop;
348 }
349 }
350
351 startChar = nextChar;
352 nextChar = i;
353
354 if (eol) {
355 String str;
356 if (s == null) {
357 str = new String(cb, startChar, i - startChar);
358 } else {
359 s.append(cb, startChar, i - startChar);
360 str = s.toString();
361 }
362 nextChar++;
363 if (c == '\r') {
364 skipLF = true;
365 }
366 return str;
367 }
368
369 if (s == null)
370 s = new StringBuffer(defaultExpectedLineLength);
371 s.append(cb, startChar, i - startChar);
372 }
373 }
374 }
375
376 /**
377 * Reads a line of text. A line is considered to be terminated by any one
378 * of a line feed ('\n'), a carriage return ('\r'), or a carriage return
379 * followed immediately by a linefeed.
380 *
381 * @return A String containing the contents of the line, not including
382 * any line-termination characters, or null if the end of the
383 * stream has been reached
384 *
385 * @exception IOException If an I/O error occurs
386 *
387 * @see java.nio.file.Files#readAllLines
388 */
389 public String readLine() throws IOException {
390 return readLine(false);
391 }
392
393 /**
394 * Skips characters.
395 *
396 * @param n The number of characters to skip
397 *
398 * @return The number of characters actually skipped
399 *
400 * @exception IllegalArgumentException If <code>n</code> is negative.
401 * @exception IOException If an I/O error occurs
402 */
403 public long skip(long n) throws IOException {
404 if (n < 0L) {
405 throw new IllegalArgumentException("skip value is negative");
406 }
407 synchronized (lock) {
408 ensureOpen();
409 long r = n;
410 while (r > 0) {
411 if (nextChar >= nChars)
412 fill();
413 if (nextChar >= nChars) /* EOF */
414 break;
415 if (skipLF) {
416 skipLF = false;
417 if (cb[nextChar] == '\n') {
418 nextChar++;
419 }
420 }
421 long d = nChars - nextChar;
422 if (r <= d) {
423 nextChar += r;
424 r = 0;
425 break;
426 }
427 else {
428 r -= d;
429 nextChar = nChars;
430 }
431 }
432 return n - r;
433 }
434 }
435
436 /**
437 * Tells whether this stream is ready to be read. A buffered character
438 * stream is ready if the buffer is not empty, or if the underlying
439 * character stream is ready.
440 *
441 * @exception IOException If an I/O error occurs
442 */
443 public boolean ready() throws IOException {
444 synchronized (lock) {
445 ensureOpen();
446
447 /*
448 * If newline needs to be skipped and the next char to be read
449 * is a newline character, then just skip it right away.
450 */
451 if (skipLF) {
452 /* Note that in.ready() will return true if and only if the next
453 * read on the stream will not block.
454 */
455 if (nextChar >= nChars && in.ready()) {
456 fill();
457 }
458 if (nextChar < nChars) {
459 if (cb[nextChar] == '\n')
460 nextChar++;
461 skipLF = false;
462 }
463 }
464 return (nextChar < nChars) || in.ready();
465 }
466 }
467
468 /**
469 * Tells whether this stream supports the mark() operation, which it does.
470 */
471 public boolean markSupported() {
472 return true;
473 }
474
475 /**
476 * Marks the present position in the stream. Subsequent calls to reset()
477 * will attempt to reposition the stream to this point.
478 *
479 * @param readAheadLimit Limit on the number of characters that may be
480 * read while still preserving the mark. An attempt
481 * to reset the stream after reading characters
482 * up to this limit or beyond may fail.
483 * A limit value larger than the size of the input
484 * buffer will cause a new buffer to be allocated
485 * whose size is no smaller than limit.
486 * Therefore large values should be used with care.
487 *
488 * @exception IllegalArgumentException If {@code readAheadLimit < 0}
489 * @exception IOException If an I/O error occurs
490 */
491 public void mark(int readAheadLimit) throws IOException {
492 if (readAheadLimit < 0) {
493 throw new IllegalArgumentException("Read-ahead limit < 0");
494 }
495 synchronized (lock) {
496 ensureOpen();
497 this.readAheadLimit = readAheadLimit;
498 markedChar = nextChar;
499 markedSkipLF = skipLF;
500 }
501 }
502
503 /**
504 * Resets the stream to the most recent mark.
505 *
506 * @exception IOException If the stream has never been marked,
507 * or if the mark has been invalidated
508 */
509 public void reset() throws IOException {
510 synchronized (lock) {
511 ensureOpen();
512 if (markedChar < 0)
513 throw new IOException((markedChar == INVALIDATED)
514 ? "Mark invalid"
515 : "Stream not marked");
516 nextChar = markedChar;
517 skipLF = markedSkipLF;
518 }
519 }
520
521 public void close() throws IOException {
522 synchronized (lock) {
523 if (in == null)
524 return;
525 try {
526 in.close();
527 } finally {
528 in = null;
529 cb = null;
530 }
531 }
532 }
533
534 /**
535 * Returns a {@code Stream}, the elements of which are lines read from
536 * this {@code BufferedReader}. The {@link Stream} is lazily populated,
537 * i.e., read only occurs during the
538 * <a href="../util/stream/package-summary.html#StreamOps">terminal
539 * stream operation</a>.
540 *
541 * <p> The reader must not be operated on during the execution of the
542 * terminal stream operation. Otherwise, the result of the terminal stream
543 * operation is undefined.
544 *
545 * <p> After execution of the terminal stream operation there are no
546 * guarantees that the reader will be at a specific position from which to
547 * read the next character or line.
548 *
549 * <p> If an {@link IOException} is thrown when accessing the underlying
550 * {@code BufferedReader}, it is wrapped in an {@link
551 * UncheckedIOException} which will be thrown from the {@code Stream}
552 * method that caused the read to take place. This method will return a
553 * Stream if invoked on a BufferedReader that is closed. Any operation on
554 * that stream that requires reading from the BufferedReader after it is
555 * closed, will cause an UncheckedIOException to be thrown.
556 *
557 * @return a {@code Stream<String>} providing the lines of text
558 * described by this {@code BufferedReader}
559 *
560 * @since 1.8
561 */
562 public Stream<String> lines() {
563 Iterator<String> iter = new Iterator<String>() {
564 String nextLine = null;
565
566 @Override
567 public boolean hasNext() {
568 if (nextLine != null) {
569 return true;
570 } else {
571 try {
572 nextLine = readLine();
573 return (nextLine != null);
574 } catch (IOException e) {
575 throw new UncheckedIOException(e);
576 }
577 }
578 }
579
580 @Override
581 public String next() {
582 if (nextLine != null || hasNext()) {
583 String line = nextLine;
584 nextLine = null;
585 return line;
586 } else {
587 throw new NoSuchElementException();
588 }
589 }
590 };
591 return StreamSupport.stream(Spliterators.spliteratorUnknownSize(
592 iter, Spliterator.ORDERED | Spliterator.NONNULL), false);
593 }
594 }