Coverage Summary for Class: LineReader (com.google.common.io)

1 /*
2  * Copyright (C) 2007 The Guava Authors
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5  * in compliance with the License. You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software distributed under the License
10  * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11  * or implied. See the License for the specific language governing permissions and limitations under
12  * the License.
13  */
14 
15 package com.google.common.io;
16 
17 import static com.google.common.base.Preconditions.checkNotNull;
18 import static com.google.common.io.CharStreams.createBuffer;
19 
20 import com.google.common.annotations.Beta;
21 import com.google.common.annotations.GwtIncompatible;
22 import com.google.errorprone.annotations.CanIgnoreReturnValue;
23 import java.io.IOException;
24 import java.io.Reader;
25 import java.nio.CharBuffer;
26 import java.util.ArrayDeque;
27 import java.util.Queue;
28 import javax.annotation.CheckForNull;
29 
30 /**
31  * A class for reading lines of text. Provides the same functionality as {@link
32  * java.io.BufferedReader#readLine()} but for all {@link Readable} objects, not just instances of
33  * {@link Reader}.
34  *
35  * @author Chris Nokleberg
36  * @since 1.0
37  */
38 @Beta
39 @GwtIncompatible
40 // TODO(b/147136275): After adding @CheckForNull below, add @ElementTypesAreNonnullByDefault.
41 public final class LineReader {
42   private final Readable readable;
43   @CheckForNull private final Reader reader;
44   private final CharBuffer cbuf = createBuffer();
45   private final char[] buf = cbuf.array();
46 
47   private final Queue<String> lines = new ArrayDeque<>();
48   private final LineBuffer lineBuf =
49       new LineBuffer() {
50         @Override
51         protected void handleLine(String line, String end) {
52           lines.add(line);
53         }
54       };
55 
56   /** Creates a new instance that will read lines from the given {@code Readable} object. */
57   public LineReader(Readable readable) {
58     this.readable = checkNotNull(readable);
59     this.reader = (readable instanceof Reader) ? (Reader) readable : null;
60   }
61 
62   /**
63    * Reads a line of text. A line is considered to be terminated by any one of a line feed ({@code
64    * '\n'}), a carriage return ({@code '\r'}), or a carriage return followed immediately by a
65    * linefeed ({@code "\r\n"}).
66    *
67    * @return a {@code String} containing the contents of the line, not including any
68    *     line-termination characters, or {@code null} if the end of the stream has been reached.
69    * @throws IOException if an I/O error occurs
70    */
71   @CanIgnoreReturnValue // to skip a line
72   @SuppressWarnings("nullness")
73   // TODO(b/147136275): After updating callers, add @CheckForNull, and remove @SuppressWarnings.
74   public String readLine() throws IOException {
75     while (lines.peek() == null) {
76       Java8Compatibility.clear(cbuf);
77       // The default implementation of Reader#read(CharBuffer) allocates a
78       // temporary char[], so we call Reader#read(char[], int, int) instead.
79       int read = (reader != null) ? reader.read(buf, 0, buf.length) : readable.read(cbuf);
80       if (read == -1) {
81         lineBuf.finish();
82         break;
83       }
84       lineBuf.add(buf, 0, read);
85     }
86     return lines.poll();
87   }
88 }