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
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package java.io;
039
040 import java.util.Locale;
041 import 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 */
064 public 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 }