From da557ab84661f8906af7f8b55a8a4e68f4176258 Mon Sep 17 00:00:00 2001 From: Michael Koch Date: Mon, 31 Mar 2003 10:15:48 +0000 Subject: 2003-03-31 Michael Koch * java/io/File.java (separator): Merged documentation from classpath. (separatorChar): Merged documentation from classpath. (pathSeparator): Merged documentation from classpath. (pathSeparatorChar): Merged documentation from classpath. (path): Merged documentation from classpath. (canRead): Merged documentation from classpath. (canWrite): Merged documentation from classpath. (createNewFile): Merged documentation from classpath. (delete): Merged documentation from classpath. (equals): Merged documentation from classpath. (exists): Merged documentation from classpath. (File): Renamed p to name to match classpath, merged documentation from classpath. (getAbsolutePath): Merged documentation from classpath. (getCanonicalPath): Merged documentation from classpath. (getCanonicalFile): Merged documentation from classpath. (getName): Merged documentation from classpath. (getParent): Merged documentation from classpath. (getParentFile): Merged documentation from classpath. (getPath): Merged documentation from classpath. (hashCode): Merged documentation from classpath. (isAbsolute): Merged documentation from classpath. (isDirectory): Merged documentation from classpath. (isFile): Merged documentation from classpath. (isHidden): Merged documentation from classpath. (lastModified): Merged documentation from classpath. (length): Merged documentation from classpath. (list): Merged documentation from classpath. (listFiles): Merged documentation from classpath. (toString): Merged documentation from classpath. (toURL): Merged documentation from classpath. (mkdir): Merged documentation from classpath. (mkdirs): Merged documentation from classpath. (createTempFile): Merged documentation from classpath. (setReadOnly): Merged documentation from classpath. (listRoots): Merged documentation from classpath. (compareTo): Merged documentation from classpath. (renameTo): Merged documentation from classpath. (setLastModified): Merged documentation from classpath. * java/io/PrintStream.java (auto_flush): Merged documentation from classpath. (PrintStream): Merged documentation from classpath. (checkError): Merged documentation from classpath. (setError): Merged documentation from classpath. (close): Merged documentation from classpath. (flush): Merged documentation from classpath. (print): Merged documentation from classpath. (println): Merged documentation from classpath. (write): Renamed count to len to match classpath, merged documentation from classpath. * java/io/RandomAccessFile.java (readShort): Merged documentation from classpath. (readUnsignedByte): Merged documentation from classpath. (readUnsignedShort): Merged documentation from classpath. (readUTF): Merged documentation from classpath. (seek): Reformatted, merged documentation from classpath. (skipBytes): Renamed some variables to match classpath, reformatted, merged documentation from classpath. (write): Merged documentation from classpath. (writeBoolean): Merged documentation from classpath. (writeByte): Merged documentation from classpath. (writeShort): Merged documentation from classpath. (writeChar): Merged documentation from classpath. (writeInt): Merged documentation from classpath. (writeLong): Merged documentation from classpath. (writeFloat): Merged documentation from classpath. (writeDouble): Merged documentation from classpath. (writeBytes): Merged documentation from classpath. (writeChars): Merged documentation from classpath. (writeUTF): Reformatted. (getChannel): Reformatted. From-SVN: r65081 --- libjava/java/io/RandomAccessFile.java | 313 ++++++++++++++++++++++++++++++++-- 1 file changed, 302 insertions(+), 11 deletions(-) (limited to 'libjava/java/io/RandomAccessFile.java') diff --git a/libjava/java/io/RandomAccessFile.java b/libjava/java/io/RandomAccessFile.java index afe54a6..990b2dc 100644 --- a/libjava/java/io/RandomAccessFile.java +++ b/libjava/java/io/RandomAccessFile.java @@ -525,100 +525,391 @@ public class RandomAccessFile implements DataOutput, DataInput return in.readLong(); } + /** + * This method reads a signed 16-bit value into a Java in from the stream. + * It operates by reading two bytes from the stream and converting them to + * a single 16-bit Java short The two bytes are stored most + * significant byte first (i.e., "big endian") regardless of the native + * host byte ordering. + *

+ * As an example, if byte1 and code{byte2 + * represent the first + * and second byte read from the stream respectively, they will be + * transformed to a short in the following manner: + *

+ * (short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF) + *

+ * The value returned is in the range of -32768 to 32767. + *

+ * This method can read a short written by an object + * implementing the + * writeShort() method in the DataOutput interface. + * + * @return The short value read + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final short readShort () throws IOException { return in.readShort(); } + /** + * This method reads 8 unsigned bits into a Java int value + * from the + * stream. The value returned is in the range of 0 to 255. + *

+ * This method can read an unsigned byte written by an object implementing + * the writeUnsignedByte() method in the + * DataOutput interface. + * + * @return The unsigned bytes value read as a Java int + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final int readUnsignedByte () throws IOException { return in.readUnsignedByte(); } + /** + * This method reads 16 unsigned bits into a Java int value from the stream. + * It operates by reading two bytes from the stream and converting them to + * a single Java int The two bytes are stored most + * significant byte first (i.e., "big endian") regardless of the native + * host byte ordering. + *

+ * As an example, if byte1 and byte2 + * represent the first + * and second byte read from the stream respectively, they will be + * transformed to an int in the following manner: + *

+ * (int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF)) + *

+ * The value returned is in the range of 0 to 65535. + *

+ * This method can read an unsigned short written by an object implementing + * the writeUnsignedShort() method in the + * DataOutput interface. + * + * @return The unsigned short value read as a Java int + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + */ public final int readUnsignedShort () throws IOException { return in.readUnsignedShort(); } + /** + * This method reads a String from an input stream that + * is encoded in + * a modified UTF-8 format. This format has a leading two byte sequence + * that contains the remaining number of bytes to read. This two byte + * sequence is read using the readUnsignedShort() method of this + * interface. + *

+ * After the number of remaining bytes have been determined, these bytes + * are read an transformed into char values. + * These char values + * are encoded in the stream using either a one, two, or three byte format. + * The particular format in use can be determined by examining the first + * byte read. + *

+ * If the first byte has a high order bit of 0 then + * that character consists on only one byte. This character value consists + * of seven bits that are at positions 0 through 6 of the byte. As an + * example, if byte1 is the byte read from the stream, it would + * be converted to a char like so: + *

+ * (char)byte1 + *

+ * If the first byte has 110 as its high order bits, then the + * character consists of two bytes. The bits that make up the character + * value are in positions 0 through 4 of the first byte and bit positions + * 0 through 5 of the second byte. (The second byte should have + * 10 as its high order bits). These values are in most significant + * byte first (i.e., "big endian") order. + *

+ * As an example, if byte1 and byte2 + * are the first two bytes + * read respectively, and the high order bits of them match the patterns + * which indicate a two byte character encoding, then they would be + * converted to a Java char like so: + *

+ * (char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F)) + *

+ * If the first byte has a 1110 as its high order bits, then the + * character consists of three bytes. The bits that make up the character + * value are in positions 0 through 3 of the first byte and bit positions + * 0 through 5 of the other two bytes. (The second and third bytes should + * have 10 as their high order bits). These values are in most + * significant byte first (i.e., "big endian") order. + *

+ * As an example, if byte1 byte2 + * and byte3 are the + * three bytes read, and the high order bits of them match the patterns + * which indicate a three byte character encoding, then they would be + * converted to a Java char like so: + *

+ * (char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) | + * (byte3 & 0x3F)) + *

+ * Note that all characters are encoded in the method that requires the + * fewest number of bytes with the exception of the character with the + * value of \u0000 which is encoded as two bytes. This is + * a modification of the UTF standard used to prevent C language style + * NUL values from appearing in the byte stream. + *

+ * This method can read data that was written by an object implementing the + * writeUTF() method in DataOutput + * + * @return The String read + * + * @exception EOFException If end of file is reached before reading the + * String + * @exception UTFDataFormatException If the data is not in UTF-8 format + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final String readUTF () throws IOException { return in.readUTF(); } + /** + * This method sets the current file position to the specified offset + * from the beginning of the file. Note that some operating systems will + * allow the file pointer to be set past the current end of the file. + * + * @param pos The offset from the beginning of the file at which to set + * the file pointer + * + * @exception IOException If an error occurs + */ public void seek (long pos) throws IOException { - fd.seek(pos, FileDescriptor.SET, false); + fd.seek (pos, FileDescriptor.SET, false); } - public int skipBytes (int count) throws IOException + /** + * This method attempts to skip and discard the specified number of bytes + * in the input stream. It may actually skip fewer bytes than requested. + * The actual number of bytes skipped is returned. This method will not + * skip any bytes if passed a negative number of bytes to skip. + * + * @param numBytes The requested number of bytes to skip. + * + * @return The number of bytes actually skipped. + * + * @exception IOException If an error occurs. + */ + public int skipBytes (int numBytes) throws IOException { - if (count <= 0) + if (numBytes < 0) + throw new IllegalArgumentException ("Can't skip negative bytes: " + + numBytes); + + if (numBytes == 0) return 0; - long startPos = fd.getFilePointer(); - long endPos = fd.seek(count, FileDescriptor.CUR, true); - return (int) (endPos - startPos); + + long curPos = fd.getFilePointer (); + long newPos = fd.seek (numBytes, FileDescriptor.CUR, true); + + return (int) (newPos - curPos); } + /** + * This method writes a single byte of data to the file. The file must + * be open for read-write in order for this operation to succeed. + * + * @param The byte of data to write, passed as an int. + * + * @exception IOException If an error occurs + */ public void write (int oneByte) throws IOException { out.write(oneByte); } + /** + * This method writes all the bytes in the specified array to the file. + * The file must be open read-write in order for this operation to succeed. + * + * @param buf The array of bytes to write to the file + */ public void write (byte[] buffer) throws IOException { out.write(buffer); } - public void write (byte[] buffer, int offset, int count) throws IOException + /** + * This method writes len bytes to the file from the specified + * array starting at index offset into the array. + * + * @param buf The array of bytes to write to the file + * @param offset The index into the array to start writing file + * @param len The number of bytes to write + * + * @exception IOException If an error occurs + */ + public void write (byte[] buffer, int offset, int len) throws IOException { - out.write(buffer, offset, count); + out.write (buffer, offset, len); } + /** + * This method writes a Java boolean to the underlying output + * stream. For a value of true, 1 is written to the stream. + * For a value of false, 0 is written. + * + * @param b The boolean value to write to the stream + * + * @exception IOException If an error occurs + */ public final void writeBoolean (boolean val) throws IOException { out.writeBoolean(val); } + /** + * This method writes a Java byte value to the underlying + * output stream. + * + * @param b The byte to write to the stream, passed + * as an int. + * + * @exception IOException If an error occurs + */ public final void writeByte (int v) throws IOException { out.writeByte(v); } + /** + * This method writes a Java short to the stream, high byte + * first. This method requires two bytes to encode the value. + * + * @param s The short value to write to the stream, + * passed as an int. + * + * @exception IOException If an error occurs + */ public final void writeShort (int v) throws IOException { out.writeShort(v); } + /** + * This method writes a single char value to the stream, + * high byte first. + * + * @param v The char value to write, passed as + * an int. + * + * @exception IOException If an error occurs + */ public final void writeChar (int v) throws IOException { out.writeChar(v); } + /** + * This method writes a Java int to the stream, high bytes + * first. This method requires four bytes to encode the value. + * + * @param v The int value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeInt (int v) throws IOException { out.writeInt(v); } + /** + * This method writes a Java long to the stream, high bytes + * first. This method requires eight bytes to encode the value. + * + * @param v The long value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeLong (long v) throws IOException { out.writeLong(v); } + /** + * This method writes a Java float value to the stream. This + * value is written by first calling the method + * Float.floatToIntBits + * to retrieve an int representing the floating point number, + * then writing this int value to the stream exactly the same + * as the writeInt() method does. + * + * @param v The floating point number to write to the stream. + * + * @exception IOException If an error occurs + * + * @see #writeInt(int) + */ public final void writeFloat (float v) throws IOException { out.writeFloat(v); } + /** + * This method writes a Java double value to the stream. This + * value is written by first calling the method + * Double.doubleToLongBits + * to retrieve an long representing the floating point number, + * then writing this long value to the stream exactly the same + * as the writeLong() method does. + * + * @param v The double precision floating point number to write to the + * stream. + * + * @exception IOException If an error occurs + * + * @see #writeLong(long) + */ public final void writeDouble (double v) throws IOException { out.writeDouble(v); } + /** + * This method writes all the bytes in a String out to the + * stream. One byte is written for each character in the String. + * The high eight bits of each character are discarded. + * + * @param s The String to write to the stream + * + * @exception IOException If an error occurs + */ public final void writeBytes (String s) throws IOException { out.writeBytes(s); } - + + /** + * This method writes all the characters in a String to the + * stream. There will be two bytes for each character value. The high + * byte of the character will be written first. + * + * @param s The String to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeChars (String s) throws IOException { out.writeChars(s); @@ -653,7 +944,7 @@ public class RandomAccessFile implements DataOutput, DataInput * * @exception IOException If an error occurs */ - public final void writeUTF(String s) throws IOException + public final void writeUTF (String s) throws IOException { out.writeUTF(s); } @@ -664,7 +955,7 @@ public class RandomAccessFile implements DataOutput, DataInput * A file channel must be created by first creating an instance of * Input/Output/RandomAccessFile and invoking the getChannel() method on it. */ - public synchronized FileChannel getChannel() + public synchronized FileChannel getChannel () { if (ch == null) ch = new FileChannelImpl (fd, true, this); -- cgit v1.1