libjava/java/io/DataOutputStream.java

   1 /* DataOutputStream.java -- Writes primitive Java datatypes to streams
   2    Copyright (C) 1998, 2001, 2003, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.io;
  40
  41 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  42  * "The Java Language Specification", ISBN 0-201-63451-1
  43  * Status:  Complete to version 1.1.
  44  */
  45
  46 /**
  47  * This class provides a mechanism for writing primitive Java datatypes
  48  * to an <code>OutputStream</code> in a portable way.  Data written to
  49  * a stream using this class can be read back in using the
  50  * <code>DataInputStream</code> class on any platform.
  51  *
  52  * @see DataInputStream
  53  *
  54  * @author Aaron M. Renn (arenn@urbanophile.com)
  55  * @author Tom Tromey (tromey@cygnus.com)
  56  */
  57 public class DataOutputStream extends FilterOutputStream implements DataOutput
  58 {
  59   /**
  60    * This is the total number of bytes that have been written to the
  61    * stream by this object instance.
  62    */
  63   protected int written;
  64
  65   /**
  66    * This method initializes an instance of <code>DataOutputStream</code> to
  67    * write its data to the specified underlying <code>OutputStream</code>
  68    *
  69    * @param out The subordinate <code>OutputStream</code> to which this
  70    * object will write
  71    */
  72   public DataOutputStream (OutputStream out)
  73   {
  74     super (out);
  75     written = 0;
  76   }
  77
  78   /**
  79    * This method flushes any unwritten bytes to the underlying stream.
  80    *
  81    * @exception IOException If an error occurs.
  82    */
  83   public void flush () throws IOException
  84   {
  85     out.flush();
  86   }
  87
  88   /**
  89    * This method returns the total number of bytes that have been written to
  90    * the underlying output stream so far.  This is the value of the
  91    * <code>written</code> instance variable
  92    *
  93    * @return The number of bytes written to the stream.
  94    */
  95   public final int size ()
  96   {
  97     return written;
  98   }
  99
 100   /**
 101    * This method writes the specified byte (passed as an <code>int</code>)
 102    * to the underlying output stream.
 103    *
 104    * @param value The <code>byte</code> to write, passed as an <code>int</code>.
 105    *
 106    * @exception IOException If an error occurs.
 107    */
 108   public synchronized void write (int value) throws IOException
 109   {
 110     out.write (value);
 111     ++written;
 112   }
 113
 114   /**
 115    * This method writes <code>len</code> bytes from the specified byte array
 116    * <code>buf</code> starting at position <code>offset</code> into the
 117    * buffer to the underlying output stream.
 118    *
 119    * @param buf The byte array to write from.
 120    * @param offset The index into the byte array to start writing from.
 121    * @param len The number of bytes to write.
 122    *
 123    * @exception IOException If an error occurs.
 124    */
 125   public synchronized void write (byte[] buf, int offset, int len)
 126      throws IOException
 127   {
 128     out.write(buf, offset, len);
 129     written += len;
 130   }
 131
 132   /**
 133    * This method writes a Java boolean value to an output stream.  If
 134    * <code>value</code> is <code>true</code>, a byte with the value of
 135    * 1 will be written, otherwise a byte with the value of 0 will be
 136    * written.
 137    *
 138    * The value written can be read using the <code>readBoolean</code>
 139    * method in <code>DataInput</code>.
 140    *
 141    * @param value The <code>boolean</code> value to write to the stream
 142    *
 143    * @exception IOException If an error occurs
 144    *
 145    * @see DataInput#readBoolean
 146    */
 147   public final void writeBoolean (boolean value) throws IOException
 148   {
 149     write (value ? 1 : 0);
 150   }
 151
 152   /**
 153    * This method writes a Java byte value to an output stream.  The
 154    * byte to be written will be in the lowest 8 bits of the
 155    * <code>int</code> value passed.
 156    *
 157    * The value written can be read using the <code>readByte</code> or
 158    * <code>readUnsignedByte</code> methods in <code>DataInput</code>.
 159    *
 160    * @param value The <code>byte</code> to write to the stream, passed as
 161    * the low eight bits of an <code>int</code>.
 162    *
 163    * @exception IOException If an error occurs
 164    *
 165    * @see DataInput#readByte
 166    * @see DataInput#readUnsignedByte
 167    */
 168   public final void writeByte (int value) throws IOException
 169   {
 170     write (value & 0xff);
 171   }
 172
 173   /**
 174    * This method writes a Java short value to an output stream.  The
 175    * char to be written will be in the lowest 16 bits of the <code>int</code>
 176    * value passed.  These bytes will be written "big endian".  That is,
 177    * with the high byte written first in the following manner:
 178    * <p>
 179    * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
 180    * byte1 = (byte)(value & 0x00FF);</code>
 181    * <p>
 182    *
 183    * The value written can be read using the <code>readShort</code> and
 184    * <code>readUnsignedShort</code> methods in <code>DataInput</code>.
 185    *
 186    * @param value The <code>short</code> value to write to the stream,
 187    * passed as an <code>int</code>.
 188    *
 189    * @exception IOException If an error occurs
 190    *
 191    * @see DataInput#readShort
 192    * @see DataInput#readUnsignedShort
 193    */
 194   public final synchronized void writeShort (int value) throws IOException
 195   {
 196     write ((byte) (0xff & (value >> 8)));
 197     write ((byte) (0xff & value));
 198   }
 199
 200   /**
 201    * This method writes a Java char value to an output stream.  The
 202    * char to be written will be in the lowest 16 bits of the <code>int</code>
 203    * value passed.  These bytes will be written "big endian".  That is,
 204    * with the high byte written first in the following manner:
 205    * <p>
 206    * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
 207    * byte1 = (byte)(value & 0x00FF);</code>
 208    * <p>
 209    *
 210    * The value written can be read using the <code>readChar</code>
 211    * method in <code>DataInput</code>.
 212    *
 213    * @param value The <code>char</code> value to write,
 214    * passed as an <code>int</code>.
 215    *
 216    * @exception IOException If an error occurs
 217    *
 218    * @see DataInput#readChar
 219    */
 220   public final synchronized void writeChar (int value) throws IOException
 221   {
 222     write ((byte) (0xff & (value >> 8)));
 223     write ((byte) (0xff & value));
 224   }
 225
 226   /**
 227    * This method writes a Java int value to an output stream.  The 4 bytes
 228    * of the passed value will be written "big endian".  That is, with
 229    * the high byte written first in the following manner:
 230    * <p>
 231    * <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br>
 232    * byte1 = (byte)((value & 0x00FF0000) >> 16);<br>
 233    * byte2 = (byte)((value & 0x0000FF00) >> 8);<br>
 234    * byte3 = (byte)(value & 0x000000FF);</code>
 235    * <p>
 236    *
 237    * The value written can be read using the <code>readInt</code>
 238    * method in <code>DataInput</code>.
 239    *
 240    * @param value The <code>int</code> value to write to the stream
 241    *
 242    * @exception IOException If an error occurs
 243    *
 244    * @see DataInput#readInt
 245    */
 246   public final synchronized void writeInt (int value) throws IOException
 247   {
 248     write ((byte) (0xff & (value >> 24)));
 249     write ((byte) (0xff & (value >> 16)));
 250     write ((byte) (0xff & (value >>  8)));
 251     write ((byte) (0xff & value));
 252   }
 253
 254   /**
 255    * This method writes a Java long value to an output stream.  The 8 bytes
 256    * of the passed value will be written "big endian".  That is, with
 257    * the high byte written first in the following manner:
 258    * <p>
 259    * <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br>
 260    * byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br>
 261    * byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br>
 262    * byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br>
 263    * byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br>
 264    * byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br>
 265    * byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br>
 266    * byte7 = (byte)(value & 0x00000000000000FFL);</code>
 267    * <p>
 268    *
 269    * The value written can be read using the <code>readLong</code>
 270    * method in <code>DataInput</code>.
 271    *
 272    * @param value The <code>long</code> value to write to the stream
 273    *
 274    * @exception IOException If an error occurs
 275    *
 276    * @see DataInput#readLong
 277    */
 278   public final synchronized void writeLong (long value) throws IOException
 279   {
 280     write ((byte) (0xff & (value >> 56)));
 281     write ((byte) (0xff & (value>> 48)));
 282     write ((byte) (0xff & (value>> 40)));
 283     write ((byte) (0xff & (value>> 32)));
 284     write ((byte) (0xff & (value>> 24)));
 285     write ((byte) (0xff & (value>> 16)));
 286     write ((byte) (0xff & (value>>  8)));
 287     write ((byte) (0xff & value));
 288   }
 289
 290   /**
 291    * This method writes a Java <code>float</code> value to the stream.  This
 292    * value is written by first calling the method
 293    * <code>Float.floatToIntBits</code>
 294    * to retrieve an <code>int</code> representing the floating point number,
 295    * then writing this <code>int</code> value to the stream exactly the same
 296    * as the <code>writeInt()</code> method does.
 297    *
 298    * The value written can be read using the <code>readFloat</code>
 299    * method in <code>DataInput</code>.
 300    *
 301    * @param value The <code>float</code> value to write to the stream
 302    *
 303    * @exception IOException If an error occurs
 304    *
 305    * @see writeInt
 306    * @see DataInput#readFloat
 307    * @see Float#floatToIntBits
 308    */
 309   public final void writeFloat (float value) throws IOException
 310   {
 311     writeInt (Float.floatToIntBits (value));
 312   }
 313
 314   /**
 315    * This method writes a Java <code>double</code> value to the stream.  This
 316    * value is written by first calling the method
 317    * <code>Double.doubleToLongBits</code>
 318    * to retrieve an <code>long</code> representing the floating point number,
 319    * then writing this <code>long</code> value to the stream exactly the same
 320    * as the <code>writeLong()</code> method does.
 321    *
 322    * The value written can be read using the <code>readDouble</code>
 323    * method in <code>DataInput</code>.
 324    *
 325    * @param value The <code>double</code> value to write to the stream
 326    *
 327    * @exception IOException If an error occurs
 328    *
 329    * @see writeLong
 330    * @see DataInput#readDouble
 331    * @see Double#doubleToLongBits
 332    */
 333   public final void writeDouble (double value) throws IOException
 334   {
 335     writeLong (Double.doubleToLongBits (value));
 336   }
 337
 338   /**
 339    * This method writes all the bytes in a <code>String</code> out to the
 340    * stream.  One byte is written for each character in the
 341    * <code>String</code>.
 342    * The high eight bits of each character are discarded, thus this
 343    * method is inappropriate for completely representing Unicode characters.
 344    *
 345    * @param value The <code>String</code> to write to the stream
 346    *
 347    * @exception IOException If an error occurs
 348    */
 349   public final void writeBytes (String value) throws IOException
 350   {
 351     int len = value.length();
 352     for (int i = 0; i < len; ++i)
 353       writeByte (value.charAt(i));
 354   }
 355
 356   /**
 357    * This method writes all the characters of a <code>String</code> to an
 358    * output stream as an array of <code>char</code>'s. Each character
 359    * is written using the method specified in the <code>writeChar</code>
 360    * method.
 361    *
 362    * @param value The <code>String</code> to write to the stream
 363    *
 364    * @exception IOException If an error occurs
 365    *
 366    * @see writeChar
 367    */
 368   public final void writeChars (String value) throws IOException
 369   {
 370     int len = value.length();
 371     for (int i = 0; i < len; ++i)
 372       writeChar (value.charAt(i));
 373   }
 374
 375   /**
 376    * This method writes a Java <code>String</code> to the stream in a modified
 377    * UTF-8 format.  First, two bytes are written to the stream indicating the
 378    * number of bytes to follow.  Note that this is the number of bytes in the
 379    * encoded <code>String</code> not the <code>String</code> length.  Next
 380    * come the encoded characters.  Each character in the <code>String</code>
 381    * is encoded as either one, two or three bytes.  For characters in the
 382    * range of <code>\u0001</code> to <\u007F>, one byte is used.  The character
 383    * value goes into bits 0-7 and bit eight is 0.  For characters in the range
 384    * of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used.  Bits
 385    * 6-10 of the character value are encoded bits 0-4 of the first byte, with
 386    * the high bytes having a value of "110".  Bits 0-5 of the character value
 387    * are stored in bits 0-5 of the second byte, with the high bits set to
 388    * "10".  This type of encoding is also done for the null character
 389    * <code>\u0000</code>.  This eliminates any C style NUL character values
 390    * in the output.  All remaining characters are stored as three bytes.
 391    * Bits 12-15 of the character value are stored in bits 0-3 of the first
 392    * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11
 393    * of the character value are stored in bits 0-5 of the second byte.  The
 394    * high bits of the second byte are set to "10".  And bits 0-5 of the
 395    * character value are stored in bits 0-5 of byte three, with the high bits
 396    * of that byte set to "10".
 397    *
 398    * The value written can be read using the <code>readUTF</code>
 399    * method in <code>DataInput</code>.
 400    *
 401    * @param value The <code>String</code> to write to the output in UTF format
 402    *
 403    * @exception IOException If an error occurs
 404    *
 405    * @see DataInput#readUTF
 406    */
 407   public final synchronized void writeUTF(String value) throws IOException
 408   {
 409     int len = value.length();
 410     int sum = 0;
 411
 412     for (int i = 0; i < len && sum <= 65535; ++i)
 413       {
 414         char c = value.charAt(i);
 415         if (c >= '\u0001' && c <= '\u007f')
 416           sum += 1;
 417         else if (c == '\u0000' || (c >= '\u0080' && c <= '\u07ff'))
 418           sum += 2;
 419         else
 420           sum += 3;
 421       }
 422
 423     if (sum > 65535)
 424       throw new UTFDataFormatException ();
 425
 426     writeShort (sum);
 427
 428     for (int i = 0; i < len; ++i)
 429       {
 430         char c = value.charAt(i);
 431         if (c >= '\u0001' && c <= '\u007f')
 432           write (c);
 433         else if (c == '\u0000' || (c >= '\u0080' && c <= '\u07ff'))
 434           {
 435             write (0xc0 | (0x1f & (c >> 6)));
 436             write (0x80 | (0x3f & c));
 437           }
 438         else
 439           {
 440             // JSL says the first byte should be or'd with 0xc0, but
 441             // that is a typo.  Unicode says 0xe0, and that is what is
 442             // consistent with DataInputStream.
 443             write (0xe0 | (0x0f & (c >> 12)));
 444             write (0x80 | (0x3f & (c >> 6)));
 445             write (0x80 | (0x3f & c));
 446           }
 447       }
 448   }
 449
 450 } // class DataOutputStream
 451