libjava/classpath/java/io/PrintWriter.java

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