OSDN Git Service

d3f386dc08381bcf5b342687aa017f29c0c53dd9
[pf3gnuchains/gcc-fork.git] / libjava / java / io / PrintStream.java
1 /* PrintStream.java -- OutputStream for printing output
2    Copyright (C) 1998, 1999, 2001, 2003, 2004, 2005, 2006  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., 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
39 package java.io;
40
41 import java.util.Formatter;
42 import java.util.Locale;
43
44 import gnu.gcj.convert.UnicodeToBytes;
45
46 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
47  * "The Java Language Specification", ISBN 0-201-63451-1
48  * Status:  Believed complete and correct to 1.3
49  */
50
51 /**
52  * This class prints Java primitive values and object to a stream as
53  * text.  None of the methods in this class throw an exception.  However,
54  * errors can be detected by calling the <code>checkError()</code> method.
55  * Additionally, this stream can be designated as "autoflush" when 
56  * created so that any writes are automatically flushed to the underlying
57  * output sink when the current line is terminated.
58  * <p>
59  * This class converts char's into byte's using the system default encoding.
60  *
61  * @author Aaron M. Renn (arenn@urbanophile.com)
62  * @author Tom Tromey (tromey@cygnus.com)
63  */
64 public class PrintStream extends FilterOutputStream implements Appendable
65 {
66   /* Notice the implementation is quite similar to OutputStreamWriter.
67    * This leads to some minor duplication, because neither inherits
68    * from the other, and we want to maximize performance. */
69
70   // Line separator string.
71   private static final char[] line_separator
72     = System.getProperty("line.separator").toCharArray();
73   
74   UnicodeToBytes converter;
75
76   // Work buffer of characters for converter.
77   char[] work = new char[100];
78   // Work buffer of bytes where we temporarily keep converter output.
79   byte[] work_bytes = new byte[100];
80
81   /**
82    * This boolean indicates whether or not an error has ever occurred
83    * on this stream.
84    */
85   private boolean error_occurred = false;
86
87   /**
88    * This is <code>true</code> if auto-flush is enabled, 
89    * <code>false</code> otherwise
90    */
91   private boolean auto_flush;
92
93   /**
94    * This method intializes a new <code>PrintStream</code> object to write
95    * to the specified output sink.
96    *
97    * @param out The <code>OutputStream</code> to write to.
98    */
99   public PrintStream (OutputStream out)
100   {
101     this (out, false);
102   }
103
104   /**
105    * This method intializes a new <code>PrintStream</code> object to write
106    * to the specified output sink.  This constructor also allows "auto-flush"
107    * functionality to be specified where the stream will be flushed after
108    * every <code>print</code> or <code>println</code> call, when the 
109    * <code>write</code> methods with array arguments are called, or when a 
110    * single new-line character is written.
111    * <p>
112    *
113    * @param out The <code>OutputStream</code> to write to.
114    * @param auto_flush <code>true</code> to flush the stream after every 
115    * line, <code>false</code> otherwise
116    */
117   public PrintStream (OutputStream out, boolean auto_flush)
118   {
119     super (out);
120
121     converter = UnicodeToBytes.getDefaultEncoder();
122     this.auto_flush = auto_flush;
123   }
124
125   /**
126    * This method intializes a new <code>PrintStream</code> object to write
127    * to the specified output sink.  This constructor also allows "auto-flush"
128    * functionality to be specified where the stream will be flushed after
129    * every <code>print</code> or <code>println</code> call, when the 
130    * <code>write</code> methods with array arguments are called, or when a 
131    * single new-line character is written.
132    * <p>
133    *
134    * @param out The <code>OutputStream</code> to write to.
135    * @param auto_flush <code>true</code> to flush the stream after every 
136    * line, <code>false</code> otherwise
137    * @param encoding The name of the character encoding to use for this
138    * object.
139    */
140   public PrintStream (OutputStream out, boolean auto_flush, String encoding)
141     throws UnsupportedEncodingException
142   {
143     super (out);
144
145     converter = UnicodeToBytes.getEncoder (encoding);
146     this.auto_flush = auto_flush;
147   }
148
149   /**
150    * This method checks to see if an error has occurred on this stream.  Note
151    * that once an error has occurred, this method will continue to report
152    * <code>true</code> forever for this stream.  Before checking for an
153    * error condition, this method flushes the stream.
154    *
155    * @return <code>true</code> if an error has occurred, 
156    * <code>false</code> otherwise
157    */
158   public boolean checkError ()
159   {
160     flush ();
161     return error_occurred;
162   }
163
164   /**
165    * This method can be called by subclasses to indicate that an error
166    * has occurred and should be reported by <code>checkError</code>.
167    */
168   protected void setError ()
169   {
170     error_occurred = true;
171   }
172
173   /**
174    * This method closes this stream and all underlying streams.
175    */
176   public void close ()
177   {
178     try
179       {
180         converter.setFinished();
181         writeChars(new char[0], 0, 0);
182         flush();
183         out.close();
184       }
185     catch (InterruptedIOException iioe)
186       {
187         Thread.currentThread().interrupt();
188       }
189     catch (IOException e)
190       {
191         setError ();
192       }
193   }
194
195   /**
196    * This method flushes any buffered bytes to the underlying stream and
197    * then flushes that stream as well.
198    */
199   public void flush ()
200   {
201     try
202       {
203         out.flush();
204       }
205     catch (InterruptedIOException iioe)
206       {
207         Thread.currentThread().interrupt();
208       }
209     catch (IOException e)
210       {
211         setError ();
212       }
213   }
214
215   private synchronized void print (String str, boolean println)
216   {
217     try
218       {
219         writeChars(str, 0, str.length());
220         if (println)
221           writeChars(line_separator, 0, line_separator.length);
222         if (auto_flush)
223           flush();
224       }
225     catch (InterruptedIOException iioe)
226       {
227         Thread.currentThread().interrupt();
228       }
229     catch (IOException e)
230       {
231         setError ();
232       }
233   }
234
235   private synchronized void print (char[] chars, int pos, int len,
236                                    boolean println)
237   {
238     try
239       {
240         writeChars(chars, pos, len);
241         if (println)
242           writeChars(line_separator, 0, line_separator.length);
243         if (auto_flush)
244           flush();
245       }
246     catch (InterruptedIOException iioe)
247       {
248         Thread.currentThread().interrupt();
249       }
250     catch (IOException e)
251       {
252         setError ();
253       }
254   }
255
256   private void writeChars(char[] buf, int offset, int count)
257     throws IOException
258   {
259     do
260       {
261         converter.setOutput(work_bytes, 0);
262         int converted = converter.write(buf, offset, count);
263         offset += converted;
264         count -= converted;
265         out.write(work_bytes, 0, converter.count);
266       }
267     while (count > 0 || converter.havePendingBytes());
268   }
269
270   private void writeChars(String str, int offset, int count)
271     throws IOException
272   {
273     do
274       {
275         converter.setOutput(work_bytes, 0);
276         int converted = converter.write(str, offset, count, work);
277         offset += converted;
278         count -= converted;
279         out.write(work_bytes, 0, converter.count);
280       }
281     while (count > 0 || converter.havePendingBytes());
282   }
283
284   /**
285    * This methods prints a boolean value to the stream.  <code>true</code>
286    * values are printed as "true" and <code>false</code> values are printed
287    * as "false".
288    *
289    * @param bool The <code>boolean</code> value to print
290    */
291   public void print (boolean bool)
292   {
293     print(String.valueOf(bool), false);
294   }
295
296   /**
297    * This method prints an integer to the stream.  The value printed is
298    * determined using the <code>String.valueOf()</code> method.
299    *
300    * @param inum The <code>int</code> value to be printed
301    */
302   public void print (int inum)
303   {
304     print(String.valueOf(inum), false);
305   }
306
307   /**
308    * This method prints a long to the stream.  The value printed is
309    * determined using the <code>String.valueOf()</code> method.
310    *
311    * @param lnum The <code>long</code> value to be printed
312    */
313   public void print (long lnum)
314   {
315     print(String.valueOf(lnum), false);
316   }
317
318   /**
319    * This method prints a float to the stream.  The value printed is
320    * determined using the <code>String.valueOf()</code> method.
321    *
322    * @param fnum The <code>float</code> value to be printed
323    */
324   public void print (float fnum)
325   {
326     print(String.valueOf(fnum), false);
327   }
328
329   /**
330    * This method prints a double to the stream.  The value printed is
331    * determined using the <code>String.valueOf()</code> method.
332    *
333    * @param dnum The <code>double</code> value to be printed
334    */
335   public void print (double dnum)
336   {
337     print(String.valueOf(dnum), false);
338   }
339
340   /**
341    * This method prints an <code>Object</code> to the stream.  The actual
342    * value printed is determined by calling the <code>String.valueOf()</code>
343    * method.
344    *
345    * @param obj The <code>Object</code> to print.
346    */
347   public void print (Object obj)
348   {
349     print(obj == null ? "null" : obj.toString(), false);
350   }
351
352   /**
353    * This method prints a <code>String</code> to the stream.  The actual
354    * value printed depends on the system default encoding.
355    *
356    * @param str The <code>String</code> to print.
357    */
358   public void print (String str)
359   {
360     print(str == null ? "null" : str, false);
361   }
362
363   /**
364    * This method prints a char to the stream.  The actual value printed is
365    * determined by the character encoding in use.
366    *
367    * @param ch The <code>char</code> value to be printed
368    */
369   public synchronized void print (char ch)
370   {
371     work[0] = ch;
372     print(work, 0, 1, false);
373   }
374
375   /**
376    * This method prints an array of characters to the stream.  The actual
377    * value printed depends on the system default encoding.
378    *
379    * @param charArray The array of characters to print.
380    */
381   public void print (char[] charArray)
382   {
383     print(charArray, 0, charArray.length, false);
384   }
385
386   /**
387    * This method prints a line separator sequence to the stream.  The value
388    * printed is determined by the system property <xmp>line.separator</xmp>
389    * and is not necessarily the Unix '\n' newline character.
390    */
391   public void println ()
392   {
393     print(line_separator, 0, line_separator.length, false);
394   }
395
396   /**
397    * This methods prints a boolean value to the stream.  <code>true</code>
398    * values are printed as "true" and <code>false</code> values are printed
399    * as "false".
400    * <p>
401    * This method prints a line termination sequence after printing the value.
402    *
403    * @param bool The <code>boolean</code> value to print
404    */
405   public void println (boolean bool)
406   {
407     print(String.valueOf(bool), true);
408   }
409
410   /**
411    * This method prints an integer to the stream.  The value printed is
412    * determined using the <code>String.valueOf()</code> method.
413    * <p>
414    * This method prints a line termination sequence after printing the value.
415    *
416    * @param inum The <code>int</code> value to be printed
417    */
418   public void println (int inum)
419   {
420     print(String.valueOf(inum), true);
421   }
422
423   /**
424    * This method prints a long to the stream.  The value printed is
425    * determined using the <code>String.valueOf()</code> method.
426    * <p>
427    * This method prints a line termination sequence after printing the value.
428    *
429    * @param lnum The <code>long</code> value to be printed
430    */
431   public void println (long lnum)
432   {
433     print(String.valueOf(lnum), true);
434   }
435
436   /**
437    * This method prints a float to the stream.  The value printed is
438    * determined using the <code>String.valueOf()</code> method.
439    * <p>
440    * This method prints a line termination sequence after printing the value.
441    *
442    * @param fnum The <code>float</code> value to be printed
443    */
444   public void println (float fnum)
445   {
446     print(String.valueOf(fnum), true);
447   }
448
449   /**
450    * This method prints a double to the stream.  The value printed is
451    * determined using the <code>String.valueOf()</code> method.
452    * <p>
453    * This method prints a line termination sequence after printing the value.
454    *
455    * @param dnum The <code>double</code> value to be printed
456    */
457   public void println (double dnum)
458   {
459     print(String.valueOf(dnum), true);
460   }
461
462   /**
463    * This method prints an <code>Object</code> to the stream.  The actual
464    * value printed is determined by calling the <code>String.valueOf()</code>
465    * method.
466    * <p>
467    * This method prints a line termination sequence after printing the value.
468    *
469    * @param obj The <code>Object</code> to print.
470    */
471   public void println (Object obj)
472   {
473     print(obj == null ? "null" : obj.toString(), true);
474   }
475
476   /**
477    * This method prints a <code>String</code> to the stream.  The actual
478    * value printed depends on the system default encoding.
479    * <p>
480    * This method prints a line termination sequence after printing the value.
481    *
482    * @param str The <code>String</code> to print.
483    */
484   public void println (String str)
485   {
486     print (str == null ? "null" : str, true);
487   }
488
489   /**
490    * This method prints a char to the stream.  The actual value printed is
491    * determined by the character encoding in use.
492    * <p>
493    * This method prints a line termination sequence after printing the value.
494    *
495    * @param ch The <code>char</code> value to be printed
496    */
497   public synchronized void println (char ch)
498   {
499     work[0] = ch;
500     print(work, 0, 1, true);
501   }
502
503   /**
504    * This method prints an array of characters to the stream.  The actual
505    * value printed depends on the system default encoding.
506    * <p>
507    * This method prints a line termination sequence after printing the value.
508    *
509    * @param charArray The array of characters to print.
510    */
511   public void println (char[] charArray)
512   {
513     print(charArray, 0, charArray.length, true);
514   }
515
516   /**
517    * This method writes a byte of data to the stream.  If auto-flush is
518    * enabled, printing a newline character will cause the stream to be
519    * flushed after the character is written.
520    * 
521    * @param oneByte The byte to be written
522    */
523   public void write (int oneByte)
524   {
525     try
526       {
527         out.write (oneByte & 0xff);
528         
529         if (auto_flush && (oneByte == '\n'))
530           flush ();
531       }
532     catch (InterruptedIOException iioe)
533       {
534         Thread.currentThread ().interrupt ();
535       }
536     catch (IOException e)
537       {
538         setError ();
539       }
540   }
541
542   /**
543    * This method writes <code>len</code> bytes from the specified array
544    * starting at index <code>offset</code> into the array.
545    *
546    * @param buffer The array of bytes to write
547    * @param offset The index into the array to start writing from
548    * @param len The number of bytes to write
549    */
550   public void write (byte[] buffer, int offset, int len)
551   {
552     try
553       {
554         out.write (buffer, offset, len);
555         
556         if (auto_flush)
557           flush ();
558       }
559     catch (InterruptedIOException iioe)
560       {
561         Thread.currentThread ().interrupt ();
562       }
563     catch (IOException e)
564       {
565         setError ();
566       }
567   }
568
569   /** @since 1.5 */
570   public PrintStream append(char c)
571   {
572     print(c);
573     return this;
574   }
575
576   /** @since 1.5 */
577   public PrintStream append(CharSequence cs)
578   {
579     print(cs == null ? "null" : cs.toString());
580     return this;
581   }
582
583   /** @since 1.5 */
584   public PrintStream append(CharSequence cs, int start, int end)
585   {
586     print(cs == null ? "null" : cs.subSequence(start, end).toString());
587     return this;
588   }
589
590   /** @since 1.5 */
591   public PrintStream printf(String format, Object... args)
592   {
593     return format(format, args);
594   }
595
596   /** @since 1.5 */
597   public PrintStream printf(Locale locale, String format, Object... args)
598   {
599     return format(locale, format, args);
600   }
601
602   /** @since 1.5 */
603   public PrintStream format(String format, Object... args)
604   {
605     return format(Locale.getDefault(), format, args);
606   }
607
608   /** @since 1.5 */
609   public PrintStream format(Locale locale, String format, Object... args)
610   {
611     Formatter f = new Formatter(this, locale);
612     f.format(format, args);
613     return this;
614   }
615 } // class PrintStream
616