From ffe4ebba87d78d4da242adb6e95d2976bd796d91 Mon Sep 17 00:00:00 2001 From: Michael Koch Date: Mon, 24 Mar 2003 08:27:28 +0000 Subject: DataInputStream.java (): Wrapped documentation line. 2003-03-24 Michael Koch * java/io/DataInputStream.java (): Wrapped documentation line. (): Fixed @return tag. * java/io/DataOutputStream.java (written): Moved to top of class. (all methods): Merged documentation from classpath. * java/io/File.java: Merged copyright year with classpath. * java/io/FileInputStream.java (all methods): Merged documentation from classpath. * java/io/LineNumberReader.java (getLineNumber): Fixed @return tag. * java/io/ObjectInputStream.java. Reformatted. * java/io/ObjectOutputStream.java: Reformatted, fixed some @see tags. * java/io/OutputStreamWriter.java: Deleted empty line. * java/io/Writer.java: Reformatted. From-SVN: r64780 --- libjava/java/io/DataOutputStream.java | 192 ++++++++++++++++++++++++++++++++-- 1 file changed, 184 insertions(+), 8 deletions(-) (limited to 'libjava/java/io/DataOutputStream.java') diff --git a/libjava/java/io/DataOutputStream.java b/libjava/java/io/DataOutputStream.java index 61a00f5..8fe9bbe 100644 --- a/libjava/java/io/DataOutputStream.java +++ b/libjava/java/io/DataOutputStream.java @@ -38,40 +38,90 @@ exception statement from your version. */ package java.io; -/** - * @author Tom Tromey - * @date September 24, 1998 - */ - /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 * "The Java Language Specification", ISBN 0-201-63451-1 * Status: Complete to version 1.1. */ +/** + * This class provides a mechanism for writing primitive Java datatypes + * to an OutputStream in a portable way. Data written to + * a stream using this class can be read back in using the + * DataInputStream class on any platform. + * + * @see DataInputStream + * + * @author Aaron M. Renn + * @author Tom Tromey + */ public class DataOutputStream extends FilterOutputStream implements DataOutput { + /** + * This is the total number of bytes that have been written to the + * stream by this object instance. + */ + protected int written; + + /** + * This method initializes an instance of DataOutputStream to + * write its data to the specified underlying OutputStream + * + * @param out The subordinate OutputStream to which this + * object will write + */ public DataOutputStream (OutputStream out) { super (out); written = 0; } + /** + * This method flushes any unwritten bytes to the underlying stream. + * + * @exception IOException If an error occurs. + */ public void flush () throws IOException { out.flush(); } + /** + * This method returns the total number of bytes that have been written to + * the underlying output stream so far. This is the value of the + * written instance variable + * + * @return The number of bytes written to the stream. + */ public final int size () { return written; } + /** + * This method writes the specified byte (passed as an int) + * to the underlying output stream. + * + * @param b The byte to write, passed as an int. + * + * @exception IOException If an error occurs. + */ public synchronized void write (int b) throws IOException { out.write(b); ++written; } + /** + * This method writes len bytes from the specified byte array + * buf starting at position offset into the + * buffer to the underlying output stream. + * + * @param buf The byte array to write from. + * @param offset The index into the byte array to start writing from. + * @param len The number of bytes to write. + * + * @exception IOException If an error occurs. + */ public synchronized void write (byte[] b, int off, int len) throws IOException, NullPointerException, IndexOutOfBoundsException { @@ -79,28 +129,72 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput written += 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 v) throws IOException { write (v ? 1 : 0); } + /** + * This method writes a Java byte value to the underlying + * output stream. + * + * @param b The byte to write to the stream, passed as + * the low eight bits of an int. + * + * @exception IOException If an error occurs + */ public final void writeByte (int v) throws IOException { write (v & 0xff); } + /** + * 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 { write ((byte) (0xff & (v >> 8))); write ((byte) (0xff & v)); } + /** + * This method writes a single char value to the stream, + * high byte first. + * + * @param c The char value to write, + * passed as an int. + * + * @exception IOException If an error occurs + */ public final void writeChar (int v) throws IOException { write ((byte) (0xff & (v >> 8))); write ((byte) (0xff & v)); } + /** + * This method writes a Java int to the stream, high bytes + * first. This method requires four bytes to encode the value. + * + * @param i The int value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeInt (int v) throws IOException { write ((byte) (0xff & (v >> 24))); @@ -109,6 +203,14 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput write ((byte) (0xff & v)); } + /** + * This method writes a Java long to the stream, high bytes + * first. This method requires eight bytes to encode the value. + * + * @param l The long value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeLong (long v) throws IOException { write ((byte) (0xff & (v >> 56))); @@ -121,16 +223,55 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput write ((byte) (0xff & 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 f The floating point number to write to the stream. + * + * @exception IOException If an error occurs + * + * @see writeInt + */ public final void writeFloat (float v) throws IOException { writeInt (Float.floatToIntBits(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 d The double precision floating point number to write to + * the stream. + * + * @exception IOException If an error occurs + * + * @see writeLong + */ public final void writeDouble (double v) throws IOException { writeLong (Double.doubleToLongBits(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 { int len = s.length(); @@ -138,6 +279,15 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput writeByte (s.charAt(i)); } + /** + * 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 { int len = s.length(); @@ -145,6 +295,33 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput writeChar (s.charAt(i)); } + /** + * This method writes a Java String to the stream in a modified + * UTF-8 format. First, two bytes are written to the stream indicating the + * number of bytes to follow. Note that this is the number of bytes in the + * encoded String not the String length. Next + * come the encoded characters. Each character in the String + * is encoded as either one, two or three bytes. For characters in the + * range of \u0001 to <\u007F>, one byte is used. The character + * value goes into bits 0-7 and bit eight is 0. For characters in the range + * of \u0080 to \u007FF, two bytes are used. Bits + * 6-10 of the character value are encoded bits 0-4 of the first byte, with + * the high bytes having a value of "110". Bits 0-5 of the character value + * are stored in bits 0-5 of the second byte, with the high bits set to + * "10". This type of encoding is also done for the null character + * \u0000. This eliminates any C style NUL character values + * in the output. All remaining characters are stored as three bytes. + * Bits 12-15 of the character value are stored in bits 0-3 of the first + * byte. The high bits of the first bytes are set to "1110". Bits 6-11 + * of the character value are stored in bits 0-5 of the second byte. The + * high bits of the second byte are set to "10". And bits 0-5 of the + * character value are stored in bits 0-5 of byte three, with the high bits + * of that byte set to "10". + * + * @param s The String to write to the output in UTF format + * + * @exception IOException If an error occurs + */ public final void writeUTF (String s) throws IOException { int len = s.length(); @@ -188,6 +365,5 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput } } - // Number of bytes written so far. - protected int written; -} +} // class DataOutputStream + -- cgit v1.1