001/* PrintWriter.java -- prints primitive values and objects to a stream as text
002   Copyright (C) 1998, 1999, 2000, 2001, 2005  Free Software Foundation
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package java.io;
039
040import java.util.Locale;
041import java.util.Formatter;
042
043/* Written using "Java Class Libraries", 2nd edition, plus online
044 * API docs for JDK 1.2 beta from http://www.javasoft.com.
045 * Status:  Believed complete and correct.
046 * However, should use native methods for conversion.
047 */
048
049/**
050 * This class prints Java primitive values and objects to a stream as
051 * text.  None of the methods in this class throw an exception.  However,
052 * errors can be detected by calling the <code>checkError()</code> method.
053 * Additionally, this stream can be designated as "autoflush" when
054 * created so that any writes are automatically flushed to the underlying
055 * output sink whenever one of the <code>println</code> methods is
056 * called.  (Note that this differs from the <code>PrintStream</code>
057 * class which also auto-flushes when it encounters a newline character
058 * in the chars written).
059 *
060 * @author Per Bothner (bothner@cygnus.com)
061 * @author Aaron M. Renn (arenn@urbanophile.com)
062 * @date April 17, 1998.
063 */
064public class PrintWriter extends Writer
065{
066  /**
067   * <code>true</code> if auto-flush is enabled, <code>false</code> otherwise
068   */
069  private boolean autoflush;
070
071  /**
072   * This boolean indicates whether or not an error has ever occurred
073   * on this stream.
074   */
075  private boolean error;
076
077  /**
078   * Indicates whether or not the stream has been closed.
079   */
080  private boolean closed;
081
082  /**
083   * This is the underlying <code>Writer</code> we are sending output
084   * to
085   */
086  protected Writer out;
087
088  /**
089   * This method intializes a new <code>PrintWriter</code> object to write
090   * to the specified output sink.  The form of the constructor does not
091   * enable auto-flush functionality.
092   *
093   * @param wr The <code>Writer</code> to write to.
094   */
095  public PrintWriter(Writer wr)
096  {
097    super(wr.lock);
098    this.out = wr;
099  }
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}