1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.io;
27
28 import java.util.Formatter;
29 import java.util.Locale;
30
31
32 /**
33 * A <code>PrintStream</code> adds functionality to another output stream,
34 * namely the ability to print representations of various data values
35 * conveniently. Two other features are provided as well. Unlike other output
36 * streams, a <code>PrintStream</code> never throws an
37 * <code>IOException</code>; instead, exceptional situations merely set an
38 * internal flag that can be tested via the <code>checkError</code> method.
39 * Optionally, a <code>PrintStream</code> can be created so as to flush
40 * automatically; this means that the <code>flush</code> method is
41 * automatically invoked after a byte array is written, one of the
42 * <code>println</code> methods is invoked, or a newline character or byte
43 * (<code>'\n'</code>) is written.
44 *
45 * <p> All characters printed by a <code>PrintStream</code> are converted into
46 * bytes using the platform's default character encoding. The <code>{@link
47 * PrintWriter}</code> class should be used in situations that require writing
48 * characters rather than bytes.
49 *
50 * @author Frank Yellin
51 * @author Mark Reinhold
52 * @since JDK1.0
53 */
54
55 public class PrintStream extends FilterOutputStream
56 implements Appendable, Closeable
57 {
58
59 private boolean autoFlush = false;
60 private boolean trouble = false;
61 private Formatter formatter;
62
63 /**
64 * Track both the text- and character-output streams, so that their buffers
65 * can be flushed without flushing the entire stream.
66 */
67 private BufferedWriter textOut;
68 private OutputStreamWriter charOut;
69
70 /**
71 * Creates a new print stream. This stream will not flush automatically.
72 *
73 * @param out The output stream to which values and objects will be
74 * printed
75 *
76 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
77 */
78 public PrintStream(OutputStream out) {
79 this(out, false);
80 }
81
82 /* Initialization is factored into a private constructor (note the swapped
83 * parameters so that this one isn't confused with the public one) and a
84 * separate init method so that the following two public constructors can
85 * share code. We use a separate init method so that the constructor that
86 * takes an encoding will throw an NPE for a null stream before it throws
87 * an UnsupportedEncodingException for an unsupported encoding.
88 */
89
90 private PrintStream(boolean autoFlush, OutputStream out)
91 {
92 super(out);
93 if (out == null)
94 throw new NullPointerException("Null output stream");
95 this.autoFlush = autoFlush;
96 }
97
98 private void init(OutputStreamWriter osw) {
99 this.charOut = osw;
100 this.textOut = new BufferedWriter(osw);
101 }
102
103 /**
104 * Creates a new print stream.
105 *
106 * @param out The output stream to which values and objects will be
107 * printed
108 * @param autoFlush A boolean; if true, the output buffer will be flushed
109 * whenever a byte array is written, one of the
110 * <code>println</code> methods is invoked, or a newline
111 * character or byte (<code>'\n'</code>) is written
112 *
113 * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
114 */
115 public PrintStream(OutputStream out, boolean autoFlush) {
116 this(autoFlush, out);
117 init(new OutputStreamWriter(this));
118 }
119
120 /**
121 * Creates a new print stream.
122 *
123 * @param out The output stream to which values and objects will be
124 * printed
125 * @param autoFlush A boolean; if true, the output buffer will be flushed
126 * whenever a byte array is written, one of the
127 * <code>println</code> methods is invoked, or a newline
128 * character or byte (<code>'\n'</code>) is written
129 * @param encoding The name of a supported
130 * <a href="../lang/package-summary.html#charenc">
131 * character encoding</a>
132 *
133 * @throws UnsupportedEncodingException
134 * If the named encoding is not supported
135 *
136 * @since 1.4
137 */
138 public PrintStream(OutputStream out, boolean autoFlush, String encoding)
139 throws UnsupportedEncodingException
140 {
141 this(autoFlush, out);
142 init(new OutputStreamWriter(this, encoding));
143 }
144
145 /**
146 * Creates a new print stream, without automatic line flushing, with the
147 * specified file name. This convenience constructor creates
148 * the necessary intermediate {@link java.io.OutputStreamWriter
149 * OutputStreamWriter}, which will encode characters using the
150 * {@linkplain java.nio.charset.Charset#defaultCharset() default charset}
151 * for this instance of the Java virtual machine.
152 *
153 * @param fileName
154 * The name of the file to use as the destination of this print
155 * stream. If the file exists, then it will be truncated to
156 * zero size; otherwise, a new file will be created. The output
157 * will be written to the file and is buffered.
158 *
159 * @throws FileNotFoundException
160 * If the given file object does not denote an existing, writable
161 * regular file and a new regular file of that name cannot be
162 * created, or if some other error occurs while opening or
163 * creating the file
164 *
165 * @throws SecurityException
166 * If a security manager is present and {@link
167 * SecurityManager#checkWrite checkWrite(fileName)} denies write
168 * access to the file
169 *
170 * @since 1.5
171 */
172 public PrintStream(String fileName) throws FileNotFoundException {
173 this(false, new FileOutputStream(fileName));
174 init(new OutputStreamWriter(this));
175 }
176
177 /**
178 * Creates a new print stream, without automatic line flushing, with the
179 * specified file name and charset. This convenience constructor creates
180 * the necessary intermediate {@link java.io.OutputStreamWriter
181 * OutputStreamWriter}, which will encode characters using the provided
182 * charset.
183 *
184 * @param fileName
185 * The name of the file to use as the destination of this print
186 * stream. If the file exists, then it will be truncated to
187 * zero size; otherwise, a new file will be created. The output
188 * will be written to the file and is buffered.
189 *
190 * @param csn
191 * The name of a supported {@linkplain java.nio.charset.Charset
192 * charset}
193 *
194 * @throws FileNotFoundException
195 * If the given file object does not denote an existing, writable
196 * regular file and a new regular file of that name cannot be
197 * created, or if some other error occurs while opening or
198 * creating the file
199 *
200 * @throws SecurityException
201 * If a security manager is present and {@link
202 * SecurityManager#checkWrite checkWrite(fileName)} denies write
203 * access to the file
204 *
205 * @throws UnsupportedEncodingException
206 * If the named charset is not supported
207 *
208 * @since 1.5
209 */
210 public PrintStream(String fileName, String csn)
211 throws FileNotFoundException, UnsupportedEncodingException
212 {
213 this(false, new FileOutputStream(fileName));
214 init(new OutputStreamWriter(this, csn));
215 }
216
217 /**
218 * Creates a new print stream, without automatic line flushing, with the
219 * specified file. This convenience constructor creates the necessary
220 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
221 * which will encode characters using the {@linkplain
222 * java.nio.charset.Charset#defaultCharset() default charset} for this
223 * instance of the Java virtual machine.
224 *
225 * @param file
226 * The file to use as the destination of this print stream. If the
227 * file exists, then it will be truncated to zero size; otherwise,
228 * a new file will be created. The output will be written to the
229 * file and is buffered.
230 *
231 * @throws FileNotFoundException
232 * If the given file object does not denote an existing, writable
233 * regular file and a new regular file of that name cannot be
234 * created, or if some other error occurs while opening or
235 * creating the file
236 *
237 * @throws SecurityException
238 * If a security manager is present and {@link
239 * SecurityManager#checkWrite checkWrite(file.getPath())}
240 * denies write access to the file
241 *
242 * @since 1.5
243 */
244 public PrintStream(File file) throws FileNotFoundException {
245 this(false, new FileOutputStream(file));
246 init(new OutputStreamWriter(this));
247 }
248
249 /**
250 * Creates a new print stream, without automatic line flushing, with the
251 * specified file and charset. This convenience constructor creates
252 * the necessary intermediate {@link java.io.OutputStreamWriter
253 * OutputStreamWriter}, which will encode characters using the provided
254 * charset.
255 *
256 * @param file
257 * The file to use as the destination of this print stream. If the
258 * file exists, then it will be truncated to zero size; otherwise,
259 * a new file will be created. The output will be written to the
260 * file and is buffered.
261 *
262 * @param csn
263 * The name of a supported {@linkplain java.nio.charset.Charset
264 * charset}
265 *
266 * @throws FileNotFoundException
267 * If the given file object does not denote an existing, writable
268 * regular file and a new regular file of that name cannot be
269 * created, or if some other error occurs while opening or
270 * creating the file
271 *
272 * @throws SecurityException
273 * If a security manager is presentand {@link
274 * SecurityManager#checkWrite checkWrite(file.getPath())}
275 * denies write access to the file
276 *
277 * @throws UnsupportedEncodingException
278 * If the named charset is not supported
279 *
280 * @since 1.5
281 */
282 public PrintStream(File file, String csn)
283 throws FileNotFoundException, UnsupportedEncodingException
284 {
285 this(false, new FileOutputStream(file));
286 init(new OutputStreamWriter(this, csn));
287 }
288
289 /** Check to make sure that the stream has not been closed */
290 private void ensureOpen() throws IOException {
291 if (out == null)
292 throw new IOException("Stream closed");
293 }
294
295 /**
296 * Flushes the stream. This is done by writing any buffered output bytes to
297 * the underlying output stream and then flushing that stream.
298 *
299 * @see java.io.OutputStream#flush()
300 */
301 public void flush() {
302 synchronized (this) {
303 try {
304 ensureOpen();
305 out.flush();
306 }
307 catch (IOException x) {
308 trouble = true;
309 }
310 }
311 }
312
313 private boolean closing = false; /* To avoid recursive closing */
314
315 /**
316 * Closes the stream. This is done by flushing the stream and then closing
317 * the underlying output stream.
318 *
319 * @see java.io.OutputStream#close()
320 */
321 public void close() {
322 synchronized (this) {
323 if (! closing) {
324 closing = true;
325 try {
326 textOut.close();
327 out.close();
328 }
329 catch (IOException x) {
330 trouble = true;
331 }
332 textOut = null;
333 charOut = null;
334 out = null;
335 }
336 }
337 }
338
339 /**
340 * Flushes the stream and checks its error state. The internal error state
341 * is set to <code>true</code> when the underlying output stream throws an
342 * <code>IOException</code> other than <code>InterruptedIOException</code>,
343 * and when the <code>setError</code> method is invoked. If an operation
344 * on the underlying output stream throws an
345 * <code>InterruptedIOException</code>, then the <code>PrintStream</code>
346 * converts the exception back into an interrupt by doing:
347 * <pre>
348 * Thread.currentThread().interrupt();
349 * </pre>
350 * or the equivalent.
351 *
352 * @return <code>true</code> if and only if this stream has encountered an
353 * <code>IOException</code> other than
354 * <code>InterruptedIOException</code>, or the
355 * <code>setError</code> method has been invoked
356 */
357 public boolean checkError() {
358 if (out != null)
359 flush();
360 if (out instanceof java.io.PrintStream) {
361 PrintStream ps = (PrintStream) out;
362 return ps.checkError();
363 }
364 return trouble;
365 }
366
367 /**
368 * Sets the error state of the stream to <code>true</code>.
369 *
370 * <p> This method will cause subsequent invocations of {@link
371 * #checkError()} to return <tt>true</tt> until {@link
372 * #clearError()} is invoked.
373 *
374 * @since JDK1.1
375 */
376 protected void setError() {
377 trouble = true;
378 }
379
380 /**
381 * Clears the internal error state of this stream.
382 *
383 * <p> This method will cause subsequent invocations of {@link
384 * #checkError()} to return <tt>false</tt> until another write
385 * operation fails and invokes {@link #setError()}.
386 *
387 * @since 1.6
388 */
389 protected void clearError() {
390 trouble = false;
391 }
392
393 /*
394 * Exception-catching, synchronized output operations,
395 * which also implement the write() methods of OutputStream
396 */
397
398 /**
399 * Writes the specified byte to this stream. If the byte is a newline and
400 * automatic flushing is enabled then the <code>flush</code> method will be
401 * invoked.
402 *
403 * <p> Note that the byte is written as given; to write a character that
404 * will be translated according to the platform's default character
405 * encoding, use the <code>print(char)</code> or <code>println(char)</code>
406 * methods.
407 *
408 * @param b The byte to be written
409 * @see #print(char)
410 * @see #println(char)
411 */
412 public void write(int b) {
413 try {
414 synchronized (this) {
415 ensureOpen();
416 out.write(b);
417 if ((b == '\n') && autoFlush)
418 out.flush();
419 }
420 }
421 catch (InterruptedIOException x) {
422 Thread.currentThread().interrupt();
423 }
424 catch (IOException x) {
425 trouble = true;
426 }
427 }
428
429 /**
430 * Writes <code>len</code> bytes from the specified byte array starting at
431 * offset <code>off</code> to this stream. If automatic flushing is
432 * enabled then the <code>flush</code> method will be invoked.
433 *
434 * <p> Note that the bytes will be written as given; to write characters
435 * that will be translated according to the platform's default character
436 * encoding, use the <code>print(char)</code> or <code>println(char)</code>
437 * methods.
438 *
439 * @param buf A byte array
440 * @param off Offset from which to start taking bytes
441 * @param len Number of bytes to write
442 */
443 public void write(byte buf[], int off, int len) {
444 try {
445 synchronized (this) {
446 ensureOpen();
447 out.write(buf, off, len);
448 if (autoFlush)
449 out.flush();
450 }
451 }
452 catch (InterruptedIOException x) {
453 Thread.currentThread().interrupt();
454 }
455 catch (IOException x) {
456 trouble = true;
457 }
458 }
459
460 /*
461 * The following private methods on the text- and character-output streams
462 * always flush the stream buffers, so that writes to the underlying byte
463 * stream occur as promptly as with the original PrintStream.
464 */
465
466 private void write(char buf[]) {
467 try {
468 synchronized (this) {
469 ensureOpen();
470 textOut.write(buf);
471 textOut.flushBuffer();
472 charOut.flushBuffer();
473 if (autoFlush) {
474 for (int i = 0; i < buf.length; i++)
475 if (buf[i] == '\n')
476 out.flush();
477 }
478 }
479 }
480 catch (InterruptedIOException x) {
481 Thread.currentThread().interrupt();
482 }
483 catch (IOException x) {
484 trouble = true;
485 }
486 }
487
488 private void write(String s) {
489 try {
490 synchronized (this) {
491 ensureOpen();
492 textOut.write(s);
493 textOut.flushBuffer();
494 charOut.flushBuffer();
495 if (autoFlush && (s.indexOf('\n') >= 0))
496 out.flush();
497 }
498 }
499 catch (InterruptedIOException x) {
500 Thread.currentThread().interrupt();
501 }
502 catch (IOException x) {
503 trouble = true;
504 }
505 }
506
507 private void newLine() {
508 try {
509 synchronized (this) {
510 ensureOpen();
511 textOut.newLine();
512 textOut.flushBuffer();
513 charOut.flushBuffer();
514 if (autoFlush)
515 out.flush();
516 }
517 }
518 catch (InterruptedIOException x) {
519 Thread.currentThread().interrupt();
520 }
521 catch (IOException x) {
522 trouble = true;
523 }
524 }
525
526 /* Methods that do not terminate lines */
527
528 /**
529 * Prints a boolean value. The string produced by <code>{@link
530 * java.lang.String#valueOf(boolean)}</code> is translated into bytes
531 * according to the platform's default character encoding, and these bytes
532 * are written in exactly the manner of the
533 * <code>{@link #write(int)}</code> method.
534 *
535 * @param b The <code>boolean</code> to be printed
536 */
537 public void print(boolean b) {
538 write(b ? "true" : "false");
539 }
540
541 /**
542 * Prints a character. The character is translated into one or more bytes
543 * according to the platform's default character encoding, and these bytes
544 * are written in exactly the manner of the
545 * <code>{@link #write(int)}</code> method.
546 *
547 * @param c The <code>char</code> to be printed
548 */
549 public void print(char c) {
550 write(String.valueOf(c));
551 }
552
553 /**
554 * Prints an integer. The string produced by <code>{@link
555 * java.lang.String#valueOf(int)}</code> is translated into bytes
556 * according to the platform's default character encoding, and these bytes
557 * are written in exactly the manner of the
558 * <code>{@link #write(int)}</code> method.
559 *
560 * @param i The <code>int</code> to be printed
561 * @see java.lang.Integer#toString(int)
562 */
563 public void print(int i) {
564 write(String.valueOf(i));
565 }
566
567 /**
568 * Prints a long integer. The string produced by <code>{@link
569 * java.lang.String#valueOf(long)}</code> is translated into bytes
570 * according to the platform's default character encoding, and these bytes
571 * are written in exactly the manner of the
572 * <code>{@link #write(int)}</code> method.
573 *
574 * @param l The <code>long</code> to be printed
575 * @see java.lang.Long#toString(long)
576 */
577 public void print(long l) {
578 write(String.valueOf(l));
579 }
580
581 /**
582 * Prints a floating-point number. The string produced by <code>{@link
583 * java.lang.String#valueOf(float)}</code> is translated into bytes
584 * according to the platform's default character encoding, and these bytes
585 * are written in exactly the manner of the
586 * <code>{@link #write(int)}</code> method.
587 *
588 * @param f The <code>float</code> to be printed
589 * @see java.lang.Float#toString(float)
590 */
591 public void print(float f) {
592 write(String.valueOf(f));
593 }
594
595 /**
596 * Prints a double-precision floating-point number. The string produced by
597 * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
598 * bytes according to the platform's default character encoding, and these
599 * bytes are written in exactly the manner of the <code>{@link
600 * #write(int)}</code> method.
601 *
602 * @param d The <code>double</code> to be printed
603 * @see java.lang.Double#toString(double)
604 */
605 public void print(double d) {
606 write(String.valueOf(d));
607 }
608
609 /**
610 * Prints an array of characters. The characters are converted into bytes
611 * according to the platform's default character encoding, and these bytes
612 * are written in exactly the manner of the
613 * <code>{@link #write(int)}</code> method.
614 *
615 * @param s The array of chars to be printed
616 *
617 * @throws NullPointerException If <code>s</code> is <code>null</code>
618 */
619 public void print(char s[]) {
620 write(s);
621 }
622
623 /**
624 * Prints a string. If the argument is <code>null</code> then the string
625 * <code>"null"</code> is printed. Otherwise, the string's characters are
626 * converted into bytes according to the platform's default character
627 * encoding, and these bytes are written in exactly the manner of the
628 * <code>{@link #write(int)}</code> method.
629 *
630 * @param s The <code>String</code> to be printed
631 */
632 public void print(String s) {
633 if (s == null) {
634 s = "null";
635 }
636 write(s);
637 }
638
639 /**
640 * Prints an object. The string produced by the <code>{@link
641 * java.lang.String#valueOf(Object)}</code> method is translated into bytes
642 * according to the platform's default character encoding, and these bytes
643 * are written in exactly the manner of the
644 * <code>{@link #write(int)}</code> method.
645 *
646 * @param obj The <code>Object</code> to be printed
647 * @see java.lang.Object#toString()
648 */
649 public void print(Object obj) {
650 write(String.valueOf(obj));
651 }
652
653
654 /* Methods that do terminate lines */
655
656 /**
657 * Terminates the current line by writing the line separator string. The
658 * line separator string is defined by the system property
659 * <code>line.separator</code>, and is not necessarily a single newline
660 * character (<code>'\n'</code>).
661 */
662 public void println() {
663 newLine();
664 }
665
666 /**
667 * Prints a boolean and then terminate the line. This method behaves as
668 * though it invokes <code>{@link #print(boolean)}</code> and then
669 * <code>{@link #println()}</code>.
670 *
671 * @param x The <code>boolean</code> to be printed
672 */
673 public void println(boolean x) {
674 synchronized (this) {
675 print(x);
676 newLine();
677 }
678 }
679
680 /**
681 * Prints a character and then terminate the line. This method behaves as
682 * though it invokes <code>{@link #print(char)}</code> and then
683 * <code>{@link #println()}</code>.
684 *
685 * @param x The <code>char</code> to be printed.
686 */
687 public void println(char x) {
688 synchronized (this) {
689 print(x);
690 newLine();
691 }
692 }
693
694 /**
695 * Prints an integer and then terminate the line. This method behaves as
696 * though it invokes <code>{@link #print(int)}</code> and then
697 * <code>{@link #println()}</code>.
698 *
699 * @param x The <code>int</code> to be printed.
700 */
701 public void println(int x) {
702 synchronized (this) {
703 print(x);
704 newLine();
705 }
706 }
707
708 /**
709 * Prints a long and then terminate the line. This method behaves as
710 * though it invokes <code>{@link #print(long)}</code> and then
711 * <code>{@link #println()}</code>.
712 *
713 * @param x a The <code>long</code> to be printed.
714 */
715 public void println(long x) {
716 synchronized (this) {
717 print(x);
718 newLine();
719 }
720 }
721
722 /**
723 * Prints a float and then terminate the line. This method behaves as
724 * though it invokes <code>{@link #print(float)}</code> and then
725 * <code>{@link #println()}</code>.
726 *
727 * @param x The <code>float</code> to be printed.
728 */
729 public void println(float x) {
730 synchronized (this) {
731 print(x);
732 newLine();
733 }
734 }
735
736 /**
737 * Prints a double and then terminate the line. This method behaves as
738 * though it invokes <code>{@link #print(double)}</code> and then
739 * <code>{@link #println()}</code>.
740 *
741 * @param x The <code>double</code> to be printed.
742 */
743 public void println(double x) {
744 synchronized (this) {
745 print(x);
746 newLine();
747 }
748 }
749
750 /**
751 * Prints an array of characters and then terminate the line. This method
752 * behaves as though it invokes <code>{@link #print(char[])}</code> and
753 * then <code>{@link #println()}</code>.
754 *
755 * @param x an array of chars to print.
756 */
757 public void println(char x[]) {
758 synchronized (this) {
759 print(x);
760 newLine();
761 }
762 }
763
764 /**
765 * Prints a String and then terminate the line. This method behaves as
766 * though it invokes <code>{@link #print(String)}</code> and then
767 * <code>{@link #println()}</code>.
768 *
769 * @param x The <code>String</code> to be printed.
770 */
771 public void println(String x) {
772 synchronized (this) {
773 print(x);
774 newLine();
775 }
776 }
777
778 /**
779 * Prints an Object and then terminate the line. This method calls
780 * at first String.valueOf(x) to get the printed object's string value,
781 * then behaves as
782 * though it invokes <code>{@link #print(String)}</code> and then
783 * <code>{@link #println()}</code>.
784 *
785 * @param x The <code>Object</code> to be printed.
786 */
787 public void println(Object x) {
788 String s = String.valueOf(x);
789 synchronized (this) {
790 print(s);
791 newLine();
792 }
793 }
794
795
796 /**
797 * A convenience method to write a formatted string to this output stream
798 * using the specified format string and arguments.
799 *
800 * <p> An invocation of this method of the form <tt>out.printf(format,
801 * args)</tt> behaves in exactly the same way as the invocation
802 *
803 * <pre>
804 * out.format(format, args) </pre>
805 *
806 * @param format
807 * A format string as described in <a
808 * href="../util/Formatter.html#syntax">Format string syntax</a>
809 *
810 * @param args
811 * Arguments referenced by the format specifiers in the format
812 * string. If there are more arguments than format specifiers, the
813 * extra arguments are ignored. The number of arguments is
814 * variable and may be zero. The maximum number of arguments is
815 * limited by the maximum dimension of a Java array as defined by
816 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
817 * Virtual Machine Specification</a>. The behaviour on a
818 * <tt>null</tt> argument depends on the <a
819 * href="../util/Formatter.html#syntax">conversion</a>.
820 *
821 * @throws IllegalFormatException
822 * If a format string contains an illegal syntax, a format
823 * specifier that is incompatible with the given arguments,
824 * insufficient arguments given the format string, or other
825 * illegal conditions. For specification of all possible
826 * formatting errors, see the <a
827 * href="../util/Formatter.html#detail">Details</a> section of the
828 * formatter class specification.
829 *
830 * @throws NullPointerException
831 * If the <tt>format</tt> is <tt>null</tt>
832 *
833 * @return This output stream
834 *
835 * @since 1.5
836 */
837 public PrintStream printf(String format, Object ... args) {
838 return format(format, args);
839 }
840
841 /**
842 * A convenience method to write a formatted string to this output stream
843 * using the specified format string and arguments.
844 *
845 * <p> An invocation of this method of the form <tt>out.printf(l, format,
846 * args)</tt> behaves in exactly the same way as the invocation
847 *
848 * <pre>
849 * out.format(l, format, args) </pre>
850 *
851 * @param l
852 * The {@linkplain java.util.Locale locale} to apply during
853 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
854 * is applied.
855 *
856 * @param format
857 * A format string as described in <a
858 * href="../util/Formatter.html#syntax">Format string syntax</a>
859 *
860 * @param args
861 * Arguments referenced by the format specifiers in the format
862 * string. If there are more arguments than format specifiers, the
863 * extra arguments are ignored. The number of arguments is
864 * variable and may be zero. The maximum number of arguments is
865 * limited by the maximum dimension of a Java array as defined by
866 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
867 * Virtual Machine Specification</a>. The behaviour on a
868 * <tt>null</tt> argument depends on the <a
869 * href="../util/Formatter.html#syntax">conversion</a>.
870 *
871 * @throws IllegalFormatException
872 * If a format string contains an illegal syntax, a format
873 * specifier that is incompatible with the given arguments,
874 * insufficient arguments given the format string, or other
875 * illegal conditions. For specification of all possible
876 * formatting errors, see the <a
877 * href="../util/Formatter.html#detail">Details</a> section of the
878 * formatter class specification.
879 *
880 * @throws NullPointerException
881 * If the <tt>format</tt> is <tt>null</tt>
882 *
883 * @return This output stream
884 *
885 * @since 1.5
886 */
887 public PrintStream printf(Locale l, String format, Object ... args) {
888 return format(l, format, args);
889 }
890
891 /**
892 * Writes a formatted string to this output stream using the specified
893 * format string and arguments.
894 *
895 * <p> The locale always used is the one returned by {@link
896 * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
897 * previous invocations of other formatting methods on this object.
898 *
899 * @param format
900 * A format string as described in <a
901 * href="../util/Formatter.html#syntax">Format string syntax</a>
902 *
903 * @param args
904 * Arguments referenced by the format specifiers in the format
905 * string. If there are more arguments than format specifiers, the
906 * extra arguments are ignored. The number of arguments is
907 * variable and may be zero. The maximum number of arguments is
908 * limited by the maximum dimension of a Java array as defined by
909 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
910 * Virtual Machine Specification</a>. The behaviour on a
911 * <tt>null</tt> argument depends on the <a
912 * href="../util/Formatter.html#syntax">conversion</a>.
913 *
914 * @throws IllegalFormatException
915 * If a format string contains an illegal syntax, a format
916 * specifier that is incompatible with the given arguments,
917 * insufficient arguments given the format string, or other
918 * illegal conditions. For specification of all possible
919 * formatting errors, see the <a
920 * href="../util/Formatter.html#detail">Details</a> section of the
921 * formatter class specification.
922 *
923 * @throws NullPointerException
924 * If the <tt>format</tt> is <tt>null</tt>
925 *
926 * @return This output stream
927 *
928 * @since 1.5
929 */
930 public PrintStream format(String format, Object ... args) {
931 try {
932 synchronized (this) {
933 ensureOpen();
934 if ((formatter == null)
935 || (formatter.locale() != Locale.getDefault()))
936 formatter = new Formatter((Appendable) this);
937 formatter.format(Locale.getDefault(), format, args);
938 }
939 } catch (InterruptedIOException x) {
940 Thread.currentThread().interrupt();
941 } catch (IOException x) {
942 trouble = true;
943 }
944 return this;
945 }
946
947 /**
948 * Writes a formatted string to this output stream using the specified
949 * format string and arguments.
950 *
951 * @param l
952 * The {@linkplain java.util.Locale locale} to apply during
953 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
954 * is applied.
955 *
956 * @param format
957 * A format string as described in <a
958 * href="../util/Formatter.html#syntax">Format string syntax</a>
959 *
960 * @param args
961 * Arguments referenced by the format specifiers in the format
962 * string. If there are more arguments than format specifiers, the
963 * extra arguments are ignored. The number of arguments is
964 * variable and may be zero. The maximum number of arguments is
965 * limited by the maximum dimension of a Java array as defined by
966 * the <a href="http://java.sun.com/docs/books/vmspec/">Java
967 * Virtual Machine Specification</a>. The behaviour on a
968 * <tt>null</tt> argument depends on the <a
969 * href="../util/Formatter.html#syntax">conversion</a>.
970 *
971 * @throws IllegalFormatException
972 * If a format string contains an illegal syntax, a format
973 * specifier that is incompatible with the given arguments,
974 * insufficient arguments given the format string, or other
975 * illegal conditions. For specification of all possible
976 * formatting errors, see the <a
977 * href="../util/Formatter.html#detail">Details</a> section of the
978 * formatter class specification.
979 *
980 * @throws NullPointerException
981 * If the <tt>format</tt> is <tt>null</tt>
982 *
983 * @return This output stream
984 *
985 * @since 1.5
986 */
987 public PrintStream format(Locale l, String format, Object ... args) {
988 try {
989 synchronized (this) {
990 ensureOpen();
991 if ((formatter == null)
992 || (formatter.locale() != l))
993 formatter = new Formatter(this, l);
994 formatter.format(l, format, args);
995 }
996 } catch (InterruptedIOException x) {
997 Thread.currentThread().interrupt();
998 } catch (IOException x) {
999 trouble = true;
1000 }
1001 return this;
1002 }
1003
1004 /**
1005 * Appends the specified character sequence to this output stream.
1006 *
1007 * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
1008 * behaves in exactly the same way as the invocation
1009 *
1010 * <pre>
1011 * out.print(csq.toString()) </pre>
1012 *
1013 * <p> Depending on the specification of <tt>toString</tt> for the
1014 * character sequence <tt>csq</tt>, the entire sequence may not be
1015 * appended. For instance, invoking then <tt>toString</tt> method of a
1016 * character buffer will return a subsequence whose content depends upon
1017 * the buffer's position and limit.
1018 *
1019 * @param csq
1020 * The character sequence to append. If <tt>csq</tt> is
1021 * <tt>null</tt>, then the four characters <tt>"null"</tt> are
1022 * appended to this output stream.
1023 *
1024 * @return This output stream
1025 *
1026 * @since 1.5
1027 */
1028 public PrintStream append(CharSequence csq) {
1029 if (csq == null)
1030 print("null");
1031 else
1032 print(csq.toString());
1033 return this;
1034 }
1035
1036 /**
1037 * Appends a subsequence of the specified character sequence to this output
1038 * stream.
1039 *
1040 * <p> An invocation of this method of the form <tt>out.append(csq, start,
1041 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
1042 * exactly the same way as the invocation
1043 *
1044 * <pre>
1045 * out.print(csq.subSequence(start, end).toString()) </pre>
1046 *
1047 * @param csq
1048 * The character sequence from which a subsequence will be
1049 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
1050 * will be appended as if <tt>csq</tt> contained the four
1051 * characters <tt>"null"</tt>.
1052 *
1053 * @param start
1054 * The index of the first character in the subsequence
1055 *
1056 * @param end
1057 * The index of the character following the last character in the
1058 * subsequence
1059 *
1060 * @return This output stream
1061 *
1062 * @throws IndexOutOfBoundsException
1063 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1064 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1065 * <tt>csq.length()</tt>
1066 *
1067 * @since 1.5
1068 */
1069 public PrintStream append(CharSequence csq, int start, int end) {
1070 CharSequence cs = (csq == null ? "null" : csq);
1071 write(cs.subSequence(start, end).toString());
1072 return this;
1073 }
1074
1075 /**
1076 * Appends the specified character to this output stream.
1077 *
1078 * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1079 * behaves in exactly the same way as the invocation
1080 *
1081 * <pre>
1082 * out.print(c) </pre>
1083 *
1084 * @param c
1085 * The 16-bit character to append
1086 *
1087 * @return This output stream
1088 *
1089 * @since 1.5
1090 */
1091 public PrintStream append(char c) {
1092 print(c);
1093 return this;
1094 }
1095
1096 }
Save This Page