From: Michael Koch Date: Fri, 21 Mar 2003 08:48:27 +0000 (+0000) Subject: 2003-03-21 Michael Koch X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=ae429eabd866b9984f29b0305a903e5cb548909f;p=gcc.git 2003-03-21 Michael Koch * java/io/LineNumberReader.java (LineNumberReader): Merged documentation with classpath. (getLineNumber): Likewise. (setLineNumber): Likewise. (mark): Likewise. (reset): Likewise. (read): Likewise. (readLine): Likewise. (skip): Likewise. From-SVN: r64654 --- diff --git a/libjava/ChangeLog b/libjava/ChangeLog index ca424919580..0cfabb50853 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,15 @@ +2003-03-21 Michael Koch + + * java/io/LineNumberReader.java + (LineNumberReader): Merged documentation with classpath. + (getLineNumber): Likewise. + (setLineNumber): Likewise. + (mark): Likewise. + (reset): Likewise. + (read): Likewise. + (readLine): Likewise. + (skip): Likewise. + 2003-03-21 Michael Koch * java/rmi/RMISecurityManager.java diff --git a/libjava/java/io/LineNumberReader.java b/libjava/java/io/LineNumberReader.java index 4225c480ca2..8ef670d372f 100644 --- a/libjava/java/io/LineNumberReader.java +++ b/libjava/java/io/LineNumberReader.java @@ -38,7 +38,22 @@ exception statement from your version. */ package java.io; /** + * This class functions like a standard Reader except that it + * counts line numbers, and canonicalizes newline characters. As data + * is read, whenever the char sequences "\r", "\n", or "\r\n" are encountered, + * the running line count is incremeted by one. Additionally, the whatever + * line termination sequence was encountered will be converted to a "\n" + * char. Note that this class numbers lines from 0. When the first + * line terminator is encountered, the line number is incremented to 1, and + * so on. Also note that actual "\r" and "\n" characters are looked for. + * The system dependent line separator sequence is ignored. + *

+ * This class counts only line termination characters. If the last line + * read from the stream does not end in a line termination sequence, it + * will not be counted as a line. + * * @author Per Bothner + * @author Aaron M. Renn (arenn@urbanophile.com) * @date April 22, 1998. */ /* Written using "Java Class Libraries", 2nd edition, plus online @@ -52,27 +67,51 @@ package java.io; * * This implementation is also minimal in the number of fields it uses. */ - public class LineNumberReader extends BufferedReader { /** The current line number. */ int lineNumber; + /** + * Create a new LineNumberReader that reads from the + * specified subordinate Reader. A default 8K char sized + * buffer will be used for reads. + * + * @param in The subordinate Reader to read from + */ public LineNumberReader(Reader in) { super(in, 8192); } + /** + * This method initializes a new LineNumberReader to read + * from the specified subordinate Reader using the specified + * read buffer size. + * + * @param in The subordinate Reader to read from + * @param size The buffer size to use for reading + */ public LineNumberReader(Reader in, int size) { super(in, size); } + /** + * This method returns the current line number + * + * @returns The current line number + */ public int getLineNumber() { return lineNumber; } + /** + * This method sets the current line number to the specified value. + * + * @param line_number The new line number + */ public void setLineNumber(int lineNumber) { this.lineNumber = lineNumber; @@ -92,6 +131,28 @@ public class LineNumberReader extends BufferedReader return count; } + /** + * This method marks a position in the input to which the stream can be + * "reset" char calling the reset() method. The parameter + * readlimit is the number of chars that can be read from the + * stream after setting the mark before the mark becomes invalid. For + * example, if mark() is called with a read limit of 10, + * then when + * 11 chars of data are read from the stream before the reset() + * method is called, then the mark is invalid and the stream object + * instance is not required to remember the mark. + *

+ * In this class, this method will remember the current line number as well + * as the current position in the stream. When the reset() + * method + * is called, the line number will be restored to the saved line number in + * addition to the stream position. + * + * @param readlimit The number of chars that can be read before the + * mark becomes invalid + * + * @exception IOException If an error occurs + */ public void mark(int readLimit) throws IOException { synchronized (lock) @@ -114,6 +175,17 @@ public class LineNumberReader extends BufferedReader } } + /** + * This method resets a stream to the point where the mark() + * method + * was called. Any chars that were read after the mark point was set will + * be re-read during subsequent reads. + *

+ * In this class, this method will also restore the line number that was + * current when the mark() method was called. + * + * @exception IOException If an error occurs + */ public void reset() throws IOException { synchronized (lock) @@ -128,6 +200,24 @@ public class LineNumberReader extends BufferedReader } } + /** + * This method reads an unsigned char from the input stream and returns it + * as an int in the range of 0-65535. This method will return -1 if the + * end of the stream has been reached. + *

+ * Note that if a line termination sequence is encountered (ie, "\r", + * "\n", or "\r\n") then that line termination sequence is converted to + * a single "\n" value which is returned from this method. This means + * that it is possible this method reads two chars from the subordinate + * stream instead of just one. + *

+ * Note that this method will block until a char of data is available + * to be read. + * + * @return The char read or -1 if end of stream + * + * @exception IOException If an error occurs + */ public int read() throws IOException { synchronized (lock) @@ -154,6 +244,28 @@ public class LineNumberReader extends BufferedReader } } + /** + * This method reads chars from a stream and stores them into a caller + * supplied buffer. It starts storing data at index offset into * the buffer and attemps to read len chars. This method can + * return before reading the number of chars requested. The actual number + * of chars read is returned as an int. A -1 is returned to indicated the + * end of the stream. + *

+ * This method will block until some data can be read. + *

+ * Note that if a line termination sequence is encountered (ie, "\r", + * "\n", or "\r\n") then that line termination sequence is converted to + * a single "\n" value which is stored in the buffer. Only a single + * char is counted towards the number of chars read in this case. + * + * @param buf The array into which the chars read should be stored + * @param offset The offset into the array to start storing chars + * @param len The requested number of chars to read + * + * @return The actual number of chars read, or -1 if end of stream + * + * @exception IOException If an error occurs. + */ public int read(char[] buf, int offset, int count) throws IOException { if (count <= 0) @@ -213,6 +325,17 @@ public class LineNumberReader extends BufferedReader } } + /** + * This method reads a line of text from the input stream and returns + * it as a String. A line is considered to be terminated + * by a "\r", "\n", or "\r\n" sequence, not by the system dependent line + * separator. + * + * @return The line read as a String or null + * if end of stream. + * + * @exception IOException If an error occurs + */ public String readLine() throws IOException { // BufferedReader.readLine already does this. Shouldn't need to keep @@ -239,6 +362,18 @@ public class LineNumberReader extends BufferedReader return str; } + /** + * This method skips over characters in the stream. This method will + * skip the specified number of characters if possible, but is not required + * to skip them all. The actual number of characters skipped is returned. + * This method returns 0 if the specified number of chars is less than 1. + * + * @param count The specified number of chars to skip. + * + * @return The actual number of chars skipped. + * + * @exception IOException If an error occurs + */ public long skip(long count) throws IOException { if (count <= 0) @@ -272,3 +407,4 @@ public class LineNumberReader extends BufferedReader return count - to_do; } } +