/[classpath]/classpath/java/io/DataOutput.java
ViewVC logotype

Diff of /classpath/java/io/DataOutput.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.10 by mkoch, Sun Mar 23 10:53:29 2003 UTC revision 1.11 by arenn, Sun Apr 6 20:43:57 2003 UTC
# Line 1  Line 1 
1  /* DataOutput.java -- Interface for writing data from a stream  /* DataOutput.java -- Interface for writing data from a stream
2     Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.     Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 45  package java.io; Line 45  package java.io;
45    
46  /**  /**
47   * This interface is implemented by classes that can wrte data to streams   * This interface is implemented by classes that can wrte data to streams
48   * from Java primitive types.   * from Java primitive types.  This data can subsequently be read back
49     * by classes implementing the <code>DataInput</code> interface.
50   *   *
51   * @author Aaron M. Renn (arenn@urbanophile.com)   * @author Aaron M. Renn (arenn@urbanophile.com)
52   * @author Tom Tromey <tromey@cygnus.com>   * @author Tom Tromey <tromey@cygnus.com>
53     *
54     * @see DataInput
55   */   */
56  public interface DataOutput  public interface DataOutput
57  {  {
   
58    /**    /**
59     * This method writes a Java boolean value to an output stream     * This method writes a Java boolean value to an output stream.  If
60       * <code>value</code> is <code>true</code>, a byte with the value of
61       * 1 will be written, otherwise a byte with the value of 0 will be
62       * written.
63       *
64       * The value written can be read using the <code>readBoolean</code>
65       * method in <code>DataInput</code>.
66     *     *
67     * @param value The boolean value to write     * @param value The boolean value to write
68     *     *
69     * @exception IOException If an error occurs     * @exception IOException If an error occurs
70       *
71       * @see DataInput#readBoolean
72     */     */
73    void writeBoolean(boolean value) throws IOException;    void writeBoolean(boolean value) throws IOException;
74    
75    /**    /**
76     * This method writes a Java byte value to an output stream     * This method writes a Java byte value to an output stream.  The
77       * byte to be written will be in the lowest 8 bits of the
78       * <code>int</code> value passed.
79       *
80       * The value written can be read using the <code>readByte</code> or
81       * <code>readUnsignedByte</code> methods in <code>DataInput</code>.
82     *     *
83     * @param value The int value to write     * @param value The int value to write
84     *     *
85     * @exception IOException If an error occurs     * @exception IOException If an error occurs
86       *
87       * @see DataInput#readByte
88       * @see DataInput#readUnsignedByte
89     */     */
90    void writeByte(int value) throws IOException;    void writeByte(int value) throws IOException;
91    
92    /**    /**
93     * This method writes a Java char value to an output stream     * This method writes a Java char value to an output stream.  The
94       * char to be written will be in the lowest 16 bits of the <code>int</code>
95       * value passed.  These bytes will be written "big endian".  That is,
96       * with the high byte written first in the following manner:
97       * <p>
98       * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
99       * byte1 = (byte)(value & 0x00FF);</code>
100       * <p>
101       *
102       * The value written can be read using the <code>readChar</code>
103       * method in <code>DataInput</code>.
104     *     *
105     * @param value The char value to write     * @param value The char value to write
106     *     *
107     * @exception IOException If an error occurs     * @exception IOException If an error occurs
108       *
109       * @see DataInput#readChar
110     */     */
111    void writeChar(int value) throws IOException;    void writeChar(int value) throws IOException;
112    
113    /**    /**
114     * This method writes a Java int value to an output stream as a 16 bit value     * This method writes a Java char value to an output stream.  The
115       * char to be written will be in the lowest 16 bits of the <code>int</code>
116       * value passed.  These bytes will be written "big endian".  That is,
117       * with the high byte written first in the following manner:
118       * <p>
119       * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
120       * byte1 = (byte)(value & 0x00FF);</code>
121       * <p>
122       *
123       * The value written can be read using the <code>readShort</code> and
124       * <code>readUnsignedShort</code> methods in <code>DataInput</code>.
125     *     *
126     * @param value The int value to write as a 16-bit value     * @param value The int value to write as a 16-bit value
127     *     *
128     * @exception IOException If an error occurs     * @exception IOException If an error occurs
129       *
130       * @see DataInput#readShort
131       * @see DataInput#readUnsignedShort
132     */     */
133    void writeShort(int value) throws IOException;    void writeShort(int value) throws IOException;
134    
135    /**    /**
136     * This method writes a Java int value to an output stream     * This method writes a Java int value to an output stream.  The 4 bytes
137       * of the passed value will be written "big endian".  That is, with
138       * the high byte written first in the following manner:
139       * <p>
140       * <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br>
141       * byte1 = (byte)((value & 0x00FF0000) >> 16);<br>
142       * byte2 = (byte)((value & 0x0000FF00) >> 8);<br>
143       * byte3 = (byte)(value & 0x000000FF);</code>
144       * <p>
145       *
146       * The value written can be read using the <code>readInt</code>
147       * method in <code>DataInput</code>.
148     *     *
149     * @param value The int value to write     * @param value The int value to write
150     *     *
151     * @exception IOException If an error occurs     * @exception IOException If an error occurs
152       *
153       * @see DataInput#readInt
154     */     */
155    void writeInt(int value) throws IOException;    void writeInt(int value) throws IOException;
156    
157    /**    /**
158     * This method writes a Java long value to an output stream     * This method writes a Java long value to an output stream.  The 8 bytes
159       * of the passed value will be written "big endian".  That is, with
160       * the high byte written first in the following manner:
161       * <p>
162       * <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br>
163       * byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br>
164       * byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br>
165       * byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br>
166       * byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br>
167       * byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br>
168       * byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br>
169       * byte7 = (byte)(value & 0x00000000000000FFL);</code>
170       * <p>
171       *
172       * The value written can be read using the <code>readLong</code>
173       * method in <code>DataInput</code>.
174     *     *
175     * @param value The long value to write     * @param value The long value to write
176     *     *
177     * @exception IOException If an error occurs     * @exception IOException If an error occurs
178       *
179       * @see DataInput#readLong
180     */     */
181    void writeLong(long value) throws IOException;    void writeLong(long value) throws IOException;
182    
183    /**    /**
184     * This method writes a Java float value to an output stream     * This method writes a Java <code>float</code> value to the stream.  This
185       * value is written by first calling the method
186       * <code>Float.floatToIntBits</code>
187       * to retrieve an <code>int</code> representing the floating point number,
188       * then writing this <code>int</code> value to the stream exactly the same
189       * as the <code>writeInt()</code> method does.
190       *
191       * The value written can be read using the <code>readFloat</code>
192       * method in <code>DataInput</code>.
193     *     *
194     * @param value The float value to write     * @param value The float value to write
195     *     *
196     * @exception IOException If an error occurs     * @exception IOException If an error occurs
197       *
198       * @see writeInt
199       * @see DataInput#readFloat
200       * @see Float#floatToIntBits
201     */     */
202    void writeFloat(float value) throws IOException;    void writeFloat(float value) throws IOException;
203    
204    /**    /**
205     * This method writes a Java double value to an output stream     * This method writes a Java <code>double</code> value to the stream.  This
206       * value is written by first calling the method
207       * <code>Double.doubleToLongBits</code>
208       * to retrieve an <code>long</code> representing the floating point number,
209       * then writing this <code>long</code> value to the stream exactly the same
210       * as the <code>writeLong()</code> method does.
211       *
212       * The value written can be read using the <code>readDouble</code>
213       * method in <code>DataInput</code>.
214     *     *
215     * @param value The double value to write     * @param value The double value to write
216     *     *
217     * @exception IOException If any other error occurs     * @exception IOException If any other error occurs
218       *
219       * @see writeLong
220       * @see DataInput#readDouble
221       * @see Double#doubleToLongBits
222     */     */
223    void writeDouble(double value) throws IOException;    void writeDouble(double value) throws IOException;
224    
225    /**    /**
226     * This method writes a String to an output stream as an array of bytes     * This method writes all the bytes in a <code>String</code> out to the
227       * stream.  One byte is written for each character in the
228       * <code>String</code>.
229       * The high eight bits of each character are discarded, thus this
230       * method is inappropriate for completely representing Unicode characters.
231     *     *
232     * @param value The String to write     * @param value The <code>String</code> to write
233     *     *
234     * @exception IOException If an error occurs     * @exception IOException If an error occurs
235     */     */
236    void writeBytes(String value) throws IOException;    void writeBytes(String value) throws IOException;
237    
238    /**    /**
239     * This method writes a String to an output stream as an array of char's     * This method writes all the bytes of a <code>String</code> to an
240       * output stream as an array of <code>char</code>'s. Each character
241       * is written using the method specified in the <code>writeChar</code>
242       * method.
243     *     *
244     * @param value The String to write     * @param value The String to write
245     *     *
246     * @exception IOException If an error occurs     * @exception IOException If an error occurs
247       *
248       * @see writeChar
249     */     */
250    void writeChars(String value) throws IOException;    void writeChars(String value) throws IOException;
251    
252    /**    /**
253     * This method writes a String to an output stream encoded in    * This method writes a Java <code>String</code> to the stream in a modified
254     * UTF-8 format.     * UTF-8 format.  First, two bytes are written to the stream indicating the
255       * number of bytes to follow.  This is written in the form of a Java
256       * <code>short</code> value in the same manner used by the
257       * <code>writeShort</code> method.  Note that this is the number of
258       * bytes in the
259       * encoded <code>String</code> not the <code>String</code> length.  Next
260       * come the encoded characters.  Each character in the <code>String</code>
261       * is encoded as either one, two or three bytes.  For characters in the
262       * range of <code>\u0001</code> to <code>\u007F</code>, one byte is used.  
263       * The character
264       * value goes into bits 0-7 and bit eight is 0.  For characters in the range
265       * of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used.  Bits
266       * 6-10 of the character value are encoded bits 0-4 of the first byte, with
267       * the high bytes having a value of "110".  Bits 0-5 of the character value
268       * are stored in bits 0-5 of the second byte, with the high bits set to
269       * "10".  This type of encoding is also done for the null character
270       * <code>\u0000</code>.  This eliminates any C style NUL character values
271       * in the output.  All remaining characters are stored as three bytes.
272       * Bits 12-15 of the character value are stored in bits 0-3 of the first
273       * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11
274       * of the character value are stored in bits 0-5 of the second byte.  The
275       * high bits of the second byte are set to "10".  And bits 0-5 of the
276       * character value are stored in bits 0-5 of byte three, with the high bits
277       * of that byte set to "10".
278     *     *
279     * @param value The String to write     * The value written can be read using the <code>readUTF</code>
280       * method in <code>DataInput</code>.
281       *
282       * @param value The <code>String</code> to write
283     *     *
284     * @exception IOException If an error occurs     * @exception IOException If an error occurs
285       *
286       * @see DataInput#readUTF
287     */     */
288    void writeUTF(String value) throws IOException;    void writeUTF(String value) throws IOException;
289    
290    /**    /**
291     * This method writes an 8-bit value (passed into the method as a Java     * This method writes an 8-bit value (passed into the method as a Java
292     * int) to an output stream.     * <code>int</code>) to an output stream.  The low 8 bits of the
293       * passed value are written.
294     *     *
295     * @param value The byte to write to the output stream     * @param value The <code>byte</code> to write to the output stream
296     *     *
297     * @exception IOException If an error occurs     * @exception IOException If an error occurs
298     */     */
# Line 176  public interface DataOutput Line 311  public interface DataOutput
311     * This method writes raw bytes from the passed array <code>buf</code>     * This method writes raw bytes from the passed array <code>buf</code>
312     * starting     * starting
313     * <code>offset</code> bytes into the buffer.  The number of bytes     * <code>offset</code> bytes into the buffer.  The number of bytes
314     * written will be * exactly <code>len</code>.     * written will be exactly <code>len</code>.
315     *     *
316     * @param buf The buffer from which to write the data     * @param buf The buffer from which to write the data
317     * @param offset The offset into the buffer to start writing data from     * @param offset The offset into the buffer to start writing data from

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26