FYI: Patch: java.io.LineNumberReader

[Michael Koch <konqueror at gmx dot de>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi list,


I commited the attached patch to trunk to merge 
java.io.LineNumberReader mostly with classpath. Only little 
differences still existing.


Michael
- -- 
Homepage: http://www.worldforge.org/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)

iD8DBQE+etJWWSOgCCdjSDsRAv5HAJ4pv0E4k2Sx+bTFhiB1ikT5ygFV9ACggTsr
yfSYViLXArvaM8i6o2UdeK4=
=sNM0
-----END PGP SIGNATURE-----

Index: ChangeLog
===================================================================
RCS file: /cvs/gcc/gcc/libjava/ChangeLog,v
retrieving revision 1.1795
diff -u -r1.1795 ChangeLog
--- ChangeLog	20 Mar 2003 11:14:35 -0000	1.1795
+++ ChangeLog	21 Mar 2003 08:47:27 -0000
@@ -1,3 +1,15 @@
+2003-03-21  Michael Koch  <konqueror at gmx dot de>
+
+	* 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-20  Michael Koch  <konqueror at gmx dot de>
 
 	* gnu/java/nio/FileChannelImpl.java
Index: java/io/LineNumberReader.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/io/LineNumberReader.java,v
retrieving revision 1.5
diff -u -r1.5 LineNumberReader.java
--- java/io/LineNumberReader.java	20 Mar 2003 07:47:01 -0000	1.5
+++ java/io/LineNumberReader.java	21 Mar 2003 08:47:27 -0000
@@ -38,7 +38,22 @@
 package java.io;
 
 /**
+ * This class functions like a standard <code>Reader</code> 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.
+ * <p>
+ * 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 <bothner at cygnus dot com>
+ * @author Aaron M. Renn (arenn at urbanophile dot com)
  * @date April 22, 1998.  
  */
 /* Written using "Java Class Libraries", 2nd edition, plus online
@@ -52,27 +67,51 @@
  *
  * 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 <code>LineNumberReader</code> that reads from the
+    * specified subordinate <code>Reader</code>.  A default 8K char sized
+    * buffer will be used for reads.
+    *
+    * @param in The subordinate <code>Reader</code> to read from
+    */
   public LineNumberReader(Reader in)
   {
     super(in, 8192);
   }
 
+  /**
+    * This method initializes a new <code>LineNumberReader</code> to read
+    * from the specified subordinate <code>Reader</code> using the specified
+    * read buffer size.
+    *
+    * @param in The subordinate <code>Reader</code> 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 @@
     return count;
   }
 
+  /**
+    * This method marks a position in the input to which the stream can be
+    * "reset" char calling the <code>reset()</code> method.  The parameter
+    * <code>readlimit</code> is the number of chars that can be read from the
+    * stream after setting the mark before the mark becomes invalid.   For
+    * example, if <code>mark()</code> is called with a read limit of 10,
+    * then when
+    * 11 chars of data are read from the stream before the <code>reset()</code>
+    * method is called, then the mark is invalid and the stream object
+    * instance is not required to remember the mark.
+    * <p>
+    * In this class, this method will remember the current line number as well
+    * as the current position in the stream.  When the <code>reset()</code>
+    * 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 @@
       }
   }
 
+  /**
+    * This method resets a stream to the point where the <code>mark()</code>
+    * method
+    * was called.  Any chars that were read after the mark point was set will
+    * be re-read during subsequent reads.
+    * <p>
+    * In this class, this method will also restore the line number that was
+    * current when the <code>mark()</code> method was called.
+    *
+    * @exception IOException If an error occurs
+    */
   public void reset() throws IOException
   {
     synchronized (lock)
@@ -128,6 +200,24 @@
       }
   }
 
+  /**
+    * 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.
+    * <p>
+    * 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.
+    * <p>
+    * 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 @@
       }
   }
 
+  /**
+    * This method reads chars from a stream and stores them into a caller
+    * supplied buffer.  It starts storing data at index <code>offset</code> into    * the buffer and attemps to read <code>len</code> 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.
+    * <p>
+    * This method will block until some data can be read.
+    * <p>
+    * 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 @@
       }
   }
 
+  /**
+    * This method reads a line of text from the input stream and returns
+    * it as a <code>String</code>.  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 <code>String</code> or <code>null</code>
+    * 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 @@
     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 @@
     return count - to_do;
   }
 }
+