libjava/java/io/PrintWriter.java

   1 /* PrintWriter.java -- prints primitive values and objects to a stream as text
   2    Copyright (C) 1998, 1999, 2000, 2001  Free Software Foundation
   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 package java.io;
  39
  40 /**
  41   * This class prints Java primitive values and objects to a stream as
  42   * text.  None of the methods in this class throw an exception.  However,
  43   * errors can be detected by calling the <code>checkError()</code> method.
  44   * Additionally, this stream can be designated as "autoflush" when
  45   * created so that any writes are automatically flushed to the underlying
  46   * output sink whenever one of the <code>println</code> methods is
  47   * called.  (Note that this differs from the <code>PrintStream</code>
  48   * class which also auto-flushes when it encounters a newline character
  49   * in the chars written).
  50   *
  51   * @version 0.0
  52   *
  53   * @author Per Bothner <bothner@cygnus.com>
  54   * @author Aaron M. Renn (arenn@urbanophile.com)
  55   * @date April 17, 1998.
  56   */
  57 /* Written using "Java Class Libraries", 2nd edition, plus online
  58  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  59  * Status:  Believed complete and correct.
  60  * However, should use native methods for conversion.
  61  */
  62
  63 public class PrintWriter extends Writer
  64 {
  65   /**
  66    * <code>true</code> if auto-flush is enabled, <code>false</code> otherwise
  67    */
  68   private boolean autoflush;
  69
  70   /**
  71    * This boolean indicates whether or not an error has ever occurred
  72    * on this stream.
  73    */
  74   private boolean error;
  75
  76   /**
  77    * This is the underlying <code>Writer</code> we are sending output
  78    * to
  79    */
  80   protected Writer out;
  81
  82   /**
  83    * This method intializes a new <code>PrintWriter</code> object to write
  84    * to the specified output sink.  The form of the constructor does not
  85    * enable auto-flush functionality.
  86    *
  87    * @param wr The <code>Writer</code> to write to.
  88    */
  89   public PrintWriter(Writer wr)
  90   {
  91     super(wr);
  92     this.out = wr;
  93   }
  94
  95   /**
  96    * This method intializes a new <code>PrintWriter</code> object to write
  97    * to the specified output sink.  This constructor also allows "auto-flush"
  98    * functionality to be specified where the stream will be flushed after
  99    * every line is terminated or newline character is written.
 100    *
 101    * @param wr The <code>Writer</code> to write to.
 102    * @param autoflush <code>true</code> to flush the stream after every line, <code>false</code> otherwise
 103    */
 104   public PrintWriter(Writer wr, boolean autoflush)
 105   {
 106     super(wr);
 107     this.out = wr;
 108     this.autoflush = autoflush;
 109   }
 110
 111   /**
 112    * This method initializes a new <code>PrintWriter</code> object to write
 113    * to the specified <code>OutputStream</code>.  Characters will be converted
 114    * to chars using the system default encoding.  Auto-flush functionality
 115    * will not be enabled.
 116    *
 117    * @param out The <code>OutputStream</code> to write to
 118    */
 119   public PrintWriter(OutputStream out)
 120   {
 121     super();
 122     this.out = new OutputStreamWriter(out);
 123     this.lock = this.out;
 124   }
 125
 126   /**
 127    * This method initializes a new <code>PrintWriter</code> object to write
 128    * to the specified <code>OutputStream</code>.  Characters will be converted
 129    * to chars using the system default encoding.  This form of the
 130    * constructor allows auto-flush functionality to be enabled if desired
 131    *
 132    * @param out The <code>OutputStream</code> to write to
 133    * @param autoflush <code>true</code> to flush the stream after every <code>println</code> call, <code>false</code> otherwise.
 134    */
 135   public PrintWriter(OutputStream out, boolean autoflush)
 136   {
 137     this(out);
 138     this.autoflush = autoflush;
 139   }
 140
 141   /**
 142    * This method can be called by subclasses to indicate that an error
 143    * has occurred and should be reported by <code>checkError</code>.
 144    */
 145   protected void setError()
 146   {
 147     error = true;
 148   }
 149
 150   /**
 151    * This method checks to see if an error has occurred on this stream.  Note
 152    * that once an error has occurred, this method will continue to report
 153    * <code>true</code> forever for this stream.  Before checking for an
 154    * error condition, this method flushes the stream.
 155    *
 156    * @return <code>true</code> if an error has occurred, <code>false</code> otherwise
 157    */
 158   public boolean checkError()
 159   {
 160     flush();
 161     return error;
 162   }
 163
 164   /**
 165    * This method flushes any buffered chars to the underlying stream and
 166    * then flushes that stream as well.
 167    */
 168   public void flush()
 169   {
 170     try
 171       {
 172         out.flush();
 173       }
 174     catch (IOException ex)
 175       {
 176         error = true;
 177       }
 178   }
 179
 180   /**
 181    * This method closes this stream and all underlying streams.
 182    */
 183   public void close()
 184   {
 185     try
 186       {
 187         out.close();
 188       }
 189     catch (IOException ex)
 190       {
 191         error = true;
 192       }
 193   }
 194
 195   /**
 196    * This method prints a <code>String</code> to the stream.  The actual
 197    * value printed depends on the system default encoding.
 198    *
 199    * @param str The <code>String</code> to print.
 200    */
 201   public void print(String str)
 202   {
 203     write(str == null ? "null" : str);
 204   }
 205
 206   /**
 207    * This method prints a char to the stream.  The actual value printed is
 208    * determined by the character encoding in use.
 209    *
 210    * @param ch The <code>char</code> value to be printed
 211    */
 212   public void print(char ch)
 213   {
 214     write((int) ch);
 215   }
 216
 217   /**
 218    * This method prints an array of characters to the stream.  The actual
 219    * value printed depends on the system default encoding.
 220    *
 221    * @param charArray The array of characters to print.
 222    */
 223   public void print(char[] charArray)
 224   {
 225     write(charArray, 0, charArray.length);
 226   }
 227
 228   /**
 229    * This methods prints a boolean value to the stream.  <code>true</code>
 230    * values are printed as "true" and <code>false</code> values are printed
 231    * as "false".
 232    *
 233    * @param bool The <code>boolean</code> value to print
 234    */
 235   public void print(boolean bool)
 236   {
 237     // We purposely call write() and not print() here.  This preserves
 238     // compatibility with JDK 1.2.
 239     write (bool ? "true" : "false");
 240   }
 241
 242   /**
 243    * This method prints an integer to the stream.  The value printed is
 244    * determined using the <code>String.valueOf()</code> method.
 245    *
 246    * @param inum The <code>int</code> value to be printed
 247    */
 248   public void print(int inum)
 249   {
 250     // We purposely call write() and not print() here.  This preserves
 251     // compatibility with JDK 1.2.
 252     write(Integer.toString(inum));
 253   }
 254
 255   /**
 256    * This method prints a long to the stream.  The value printed is
 257    * determined using the <code>String.valueOf()</code> method.
 258    *
 259    * @param lnum The <code>long</code> value to be printed
 260    */
 261   public void print(long lnum)
 262   {
 263     // We purposely call write() and not print() here.  This preserves
 264     // compatibility with JDK 1.2.
 265     write(Long.toString(lnum));
 266   }
 267
 268   /**
 269    * This method prints a float to the stream.  The value printed is
 270    * determined using the <code>String.valueOf()</code> method.
 271    *
 272    * @param fnum The <code>float</code> value to be printed
 273    */
 274   public void print(float fnum)
 275   {
 276     // We purposely call write() and not print() here.  This preserves
 277     // compatibility with JDK 1.2.
 278     write(Float.toString(fnum));
 279   }
 280
 281   /**
 282    * This method prints a double to the stream.  The value printed is
 283    * determined using the <code>String.valueOf()</code> method.
 284    *
 285    * @param dnum The <code>double</code> value to be printed
 286    */
 287   public void print(double dnum)
 288   {
 289     // We purposely call write() and not print() here.  This preserves
 290     // compatibility with JDK 1.2.
 291     write(Double.toString(dnum));
 292   }
 293
 294   /**
 295    * This method prints an <code>Object</code> to the stream.  The actual
 296    * value printed is determined by calling the <code>String.valueOf()</code>
 297    * method.
 298    *
 299    * @param obj The <code>Object</code> to print.
 300    */
 301   public void print(Object obj)
 302   {
 303     // We purposely call write() and not print() here.  This preserves
 304     // compatibility with JDK 1.2.
 305     write(obj == null ? "null" : obj.toString());
 306   }
 307
 308   /**
 309    * This is the system dependent line separator
 310    */
 311   private static final char[] line_separator
 312   = System.getProperty("line.separator").toCharArray();
 313
 314   /**
 315    * This method prints a line separator sequence to the stream.  The value
 316    * printed is determined by the system property <xmp>line.separator</xmp>
 317    * and is not necessarily the Unix '\n' newline character.
 318    */
 319   public void println()
 320   {
 321     synchronized (lock)
 322       {
 323         try
 324           {
 325             write(line_separator, 0, line_separator.length);
 326             if (autoflush)
 327               out.flush();
 328           }
 329         catch (IOException ex)
 330           {
 331             error = true;
 332           }
 333       }
 334   }
 335
 336   /**
 337    * This methods prints a boolean value to the stream.  <code>true</code>
 338    * values are printed as "true" and <code>false</code> values are printed
 339    * as "false".
 340    *
 341    * This method prints a line termination sequence after printing the value.
 342    *
 343    * @param bool The <code>boolean</code> value to print
 344    */
 345   public void println(boolean bool)
 346   {
 347     synchronized (lock)
 348       {
 349         print(bool);
 350         println();
 351       }
 352   }
 353
 354   /**
 355    * This method prints an integer to the stream.  The value printed is
 356    * determined using the <code>String.valueOf()</code> method.
 357    *
 358    * This method prints a line termination sequence after printing the value.
 359    *
 360    * @param inum The <code>int</code> value to be printed
 361    */
 362   public void println(int inum)
 363   {
 364     synchronized (lock)
 365       {
 366         print(inum);
 367         println();
 368       }
 369   }
 370
 371   /**
 372    * This method prints a long to the stream.  The value printed is
 373    * determined using the <code>String.valueOf()</code> method.
 374    *
 375    * This method prints a line termination sequence after printing the value.
 376    *
 377    * @param lnum The <code>long</code> value to be printed
 378    */
 379   public void println(long lnum)
 380   {
 381     synchronized (lock)
 382       {
 383         print(lnum);
 384         println();
 385       }
 386   }
 387
 388   /**
 389    * This method prints a float to the stream.  The value printed is
 390    * determined using the <code>String.valueOf()</code> method.
 391    *
 392    * This method prints a line termination sequence after printing the value.
 393    *
 394    * @param fnum The <code>float</code> value to be printed
 395    */
 396   public void println(float fnum)
 397   {
 398     synchronized (lock)
 399       {
 400         print(fnum);
 401         println();
 402       }
 403   }
 404
 405   /**
 406    * This method prints a double to the stream.  The value printed is
 407    * determined using the <code>String.valueOf()</code> method.
 408    *
 409    * This method prints a line termination sequence after printing the value.
 410    *
 411    * @param dnum The <code>double</code> value to be printed
 412    */
 413   public void println(double dnum)
 414   {
 415     synchronized (lock)
 416       {
 417         print(dnum);
 418         println();
 419       }
 420   }
 421
 422   /**
 423    * This method prints an <code>Object</code> to the stream.  The actual
 424    * value printed is determined by calling the <code>String.valueOf()</code>
 425    * method.
 426    *
 427    * This method prints a line termination sequence after printing the value.
 428    *
 429    * @param obj The <code>Object</code> to print.
 430    */
 431   public void println(Object obj)
 432   {
 433     synchronized (lock)
 434       {
 435         print(obj);
 436         println();
 437       }
 438   }
 439
 440   /**
 441    * This method prints a <code>String</code> to the stream.  The actual
 442    * value printed depends on the system default encoding.
 443    *
 444    * This method prints a line termination sequence after printing the value.
 445    *
 446    * @param str The <code>String</code> to print.
 447    */
 448   public void println(String str)
 449   {
 450     synchronized (lock)
 451       {
 452         print(str);
 453         println();
 454       }
 455   }
 456
 457   /**
 458    * This method prints a char to the stream.  The actual value printed is
 459    * determined by the character encoding in use.
 460    *
 461    * This method prints a line termination sequence after printing the value.
 462    *
 463    * @param ch The <code>char</code> value to be printed
 464    */
 465   public void println(char ch)
 466   {
 467     synchronized (lock)
 468       {
 469         print(ch);
 470         println();
 471       }
 472   }
 473
 474   /**
 475    * This method prints an array of characters to the stream.  The actual
 476    * value printed depends on the system default encoding.
 477    *
 478    * This method prints a line termination sequence after printing the value.
 479    *
 480    * @param charArray The array of characters to print.
 481    */
 482   public void println(char[] charArray)
 483   {
 484     synchronized (lock)
 485       {
 486         print(charArray);
 487         println();
 488       }
 489   }
 490
 491   /**
 492    * This method writes a single char to the stream.
 493    *
 494    * @param ch The char to be written, passed as a int
 495    */
 496   public void write(int ch)
 497   {
 498     try
 499       {
 500         out.write(ch);
 501       }
 502     catch (IOException ex)
 503       {
 504         error = true;
 505       }
 506   }
 507
 508   /**
 509    * This method writes <code>count</code> chars from the specified array
 510    * starting at index <code>offset</code> into the array.
 511    *
 512    * @param charArray The array of chars to write
 513    * @param offset The index into the array to start writing from
 514    * @param count The number of chars to write
 515   */
 516   public void write(char[] charArray, int offset, int count)
 517   {
 518     try
 519       {
 520         out.write(charArray, offset, count);
 521       }
 522     catch (IOException ex)
 523       {
 524         error = true;
 525       }
 526   }
 527
 528   /**
 529    * This method writes <code>count</code> chars from the specified
 530    * <code>String</code> to the output starting at character position
 531    * <code>offset</code> into the <code>String</code>
 532    *
 533    * @param str The <code>String</code> to write chars from
 534    * @param offset The offset into the <code>String</code> to start writing from
 535    * @param count The number of chars to write.
 536    */
 537   public void write(String str, int offset, int count)
 538   {
 539     try
 540       {
 541         out.write(str, offset, count);
 542       }
 543     catch (IOException ex)
 544       {
 545         error = true;
 546       }
 547   }
 548
 549   /**
 550    * This method write all the chars in the specified array to the output.
 551    *
 552    * @param charArray The array of characters to write
 553    */
 554   public void write(char[] charArray)
 555   {
 556     write(charArray, 0, charArray.length);
 557   }
 558
 559   /**
 560    * This method writes the contents of the specified <code>String</code>
 561    * to the underlying stream.
 562    *
 563    * @param str The <code>String</code> to write
 564    */
 565   public void write(String str)
 566   {
 567     write(str, 0, str.length());
 568   }
 569 }