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