2 * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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.
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).
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.
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
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;
36 * Prints formatted representations of objects to a text-output stream. This
37 * class implements all of the <tt>print</tt> 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.
41 * <p> Unlike the {@link PrintStream} class, if automatic flushing is enabled
42 * it will be done only when one of the <tt>println</tt>, <tt>printf</tt>, or
43 * <tt>format</tt> 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.
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()}.
51 * @author Frank Yellin
52 * @author Mark Reinhold
56 public class PrintWriter extends Writer {
59 * The underlying character-output stream of this
60 * <code>PrintWriter</code>.
66 private final boolean autoFlush;
67 private boolean trouble = false;
68 private Formatter formatter;
69 private PrintStream psOut = null;
72 * Line separator string. This is the value of the line.separator
73 * property at the moment that the stream was created.
75 private final String lineSeparator;
78 * Returns a charset object for the given charset name.
79 * @throws NullPointerException is csn is null
80 * @throws UnsupportedEncodingException if the charset is not supported
82 private static Charset toCharset(String csn)
83 throws UnsupportedEncodingException
85 Objects.requireNonNull(csn, "charsetName");
87 return Charset.forName(csn);
88 } catch (IllegalCharsetNameException|UnsupportedCharsetException unused) {
89 // UnsupportedEncodingException should be thrown
90 throw new UnsupportedEncodingException(csn);
95 * Creates a new PrintWriter, without automatic line flushing.
97 * @param out A character-output stream
99 public PrintWriter (Writer out) {
104 * Creates a new PrintWriter.
106 * @param out A character-output stream
107 * @param autoFlush A boolean; if true, the <tt>println</tt>,
108 * <tt>printf</tt>, or <tt>format</tt> methods will
109 * flush the output buffer
111 public PrintWriter(Writer out,
115 this.autoFlush = autoFlush;
116 lineSeparator = java.security.AccessController.doPrivileged(
117 new sun.security.action.GetPropertyAction("line.separator"));
121 * Creates a new PrintWriter, without automatic line flushing, from an
122 * existing OutputStream. This convenience constructor creates the
123 * necessary intermediate OutputStreamWriter, which will convert characters
124 * into bytes using the default character encoding.
126 * @param out An output stream
128 * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
130 public PrintWriter(OutputStream out) {
135 * Creates a new PrintWriter from an existing OutputStream. This
136 * convenience constructor creates the necessary intermediate
137 * OutputStreamWriter, which will convert characters into bytes using the
138 * default character encoding.
140 * @param out An output stream
141 * @param autoFlush A boolean; if true, the <tt>println</tt>,
142 * <tt>printf</tt>, or <tt>format</tt> methods will
143 * flush the output buffer
145 * @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
147 public PrintWriter(OutputStream out, boolean autoFlush) {
148 this(new BufferedWriter(new OutputStreamWriter(out)), autoFlush);
150 // save print stream for error propagation
151 if (out instanceof java.io.PrintStream) {
152 psOut = (PrintStream) out;
157 * Creates a new PrintWriter, without automatic line flushing, with the
158 * specified file name. This convenience constructor creates the necessary
159 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
160 * which will encode characters using the {@linkplain
161 * java.nio.charset.Charset#defaultCharset() default charset} for this
162 * instance of the Java virtual machine.
165 * The name of the file to use as the destination of this writer.
166 * If the file exists then it will be truncated to zero size;
167 * otherwise, a new file will be created. The output will be
168 * written to the file and is buffered.
170 * @throws FileNotFoundException
171 * If the given string does not denote an existing, writable
172 * regular file and a new regular file of that name cannot be
173 * created, or if some other error occurs while opening or
176 * @throws SecurityException
177 * If a security manager is present and {@link
178 * SecurityManager#checkWrite checkWrite(fileName)} denies write
183 public PrintWriter(String fileName) throws FileNotFoundException {
184 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(fileName))),
188 /* Private constructor */
189 private PrintWriter(Charset charset, File file)
190 throws FileNotFoundException
192 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), charset)),
197 * Creates a new PrintWriter, without automatic line flushing, with the
198 * specified file name and charset. This convenience constructor creates
199 * the necessary intermediate {@link java.io.OutputStreamWriter
200 * OutputStreamWriter}, which will encode characters using the provided
204 * The name of the file to use as the destination of this writer.
205 * If the file exists then it will be truncated to zero size;
206 * otherwise, a new file will be created. The output will be
207 * written to the file and is buffered.
210 * The name of a supported {@linkplain java.nio.charset.Charset
213 * @throws FileNotFoundException
214 * If the given string does not denote an existing, writable
215 * regular file and a new regular file of that name cannot be
216 * created, or if some other error occurs while opening or
219 * @throws SecurityException
220 * If a security manager is present and {@link
221 * SecurityManager#checkWrite checkWrite(fileName)} denies write
224 * @throws UnsupportedEncodingException
225 * If the named charset is not supported
229 public PrintWriter(String fileName, String csn)
230 throws FileNotFoundException, UnsupportedEncodingException
232 this(toCharset(csn), new File(fileName));
236 * Creates a new PrintWriter, without automatic line flushing, with the
237 * specified file. This convenience constructor creates the necessary
238 * intermediate {@link java.io.OutputStreamWriter OutputStreamWriter},
239 * which will encode characters using the {@linkplain
240 * java.nio.charset.Charset#defaultCharset() default charset} for this
241 * instance of the Java virtual machine.
244 * The file to use as the destination of this writer. If the file
245 * exists then it will be truncated to zero size; otherwise, a new
246 * file will be created. The output will be written to the file
249 * @throws FileNotFoundException
250 * If the given file object does not denote an existing, writable
251 * regular file and a new regular file of that name cannot be
252 * created, or if some other error occurs while opening or
255 * @throws SecurityException
256 * If a security manager is present and {@link
257 * SecurityManager#checkWrite checkWrite(file.getPath())}
258 * denies write access to the file
262 public PrintWriter(File file) throws FileNotFoundException {
263 this(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file))),
268 * Creates a new PrintWriter, without automatic line flushing, with the
269 * specified file and charset. This convenience constructor creates the
270 * necessary intermediate {@link java.io.OutputStreamWriter
271 * OutputStreamWriter}, which will encode characters using the provided
275 * The file to use as the destination of this writer. If the file
276 * exists then it will be truncated to zero size; otherwise, a new
277 * file will be created. The output will be written to the file
281 * The name of a supported {@linkplain java.nio.charset.Charset
284 * @throws FileNotFoundException
285 * If the given file object does not denote an existing, writable
286 * regular file and a new regular file of that name cannot be
287 * created, or if some other error occurs while opening or
290 * @throws SecurityException
291 * If a security manager is present and {@link
292 * SecurityManager#checkWrite checkWrite(file.getPath())}
293 * denies write access to the file
295 * @throws UnsupportedEncodingException
296 * If the named charset is not supported
300 public PrintWriter(File file, String csn)
301 throws FileNotFoundException, UnsupportedEncodingException
303 this(toCharset(csn), file);
306 /** Checks to make sure that the stream has not been closed */
307 private void ensureOpen() throws IOException {
309 throw new IOException("Stream closed");
313 * Flushes the stream.
316 public void flush() {
318 synchronized (lock) {
323 catch (IOException x) {
329 * Closes the stream and releases any system resources associated
330 * with it. Closing a previously closed stream has no effect.
334 public void close() {
336 synchronized (lock) {
343 catch (IOException x) {
349 * Flushes the stream if it's not closed and checks its error state.
351 * @return <code>true</code> if the print stream has encountered an error,
352 * either on the underlying output stream or during a format
355 public boolean checkError() {
359 if (out instanceof java.io.PrintWriter) {
360 PrintWriter pw = (PrintWriter) out;
361 return pw.checkError();
362 } else if (psOut != null) {
363 return psOut.checkError();
369 * Indicates that an error has occurred.
371 * <p> This method will cause subsequent invocations of {@link
372 * #checkError()} to return <tt>true</tt> until {@link
373 * #clearError()} is invoked.
375 protected void setError() {
380 * Clears the error state of this stream.
382 * <p> This method will cause subsequent invocations of {@link
383 * #checkError()} to return <tt>false</tt> until another write
384 * operation fails and invokes {@link #setError()}.
388 protected void clearError() {
393 * Exception-catching, synchronized output operations,
394 * which also implement the write() methods of Writer
398 * Writes a single character.
399 * @param c int specifying a character to be written.
401 public void write(int c) {
403 synchronized (lock) {
408 catch (InterruptedIOException x) {
409 Thread.currentThread().interrupt();
411 catch (IOException x) {
417 * Writes A Portion of an array of characters.
418 * @param buf Array of characters
419 * @param off Offset from which to start writing characters
420 * @param len Number of characters to write
422 public void write(char buf[], int off, int len) {
424 synchronized (lock) {
426 out.write(buf, off, len);
429 catch (InterruptedIOException x) {
430 Thread.currentThread().interrupt();
432 catch (IOException x) {
438 * Writes an array of characters. This method cannot be inherited from the
439 * Writer class because it must suppress I/O exceptions.
440 * @param buf Array of characters to be written
442 public void write(char buf[]) {
443 write(buf, 0, buf.length);
447 * Writes a portion of a string.
449 * @param off Offset from which to start writing characters
450 * @param len Number of characters to write
452 public void write(String s, int off, int len) {
454 synchronized (lock) {
456 out.write(s, off, len);
459 catch (InterruptedIOException x) {
460 Thread.currentThread().interrupt();
462 catch (IOException x) {
468 * Writes a string. This method cannot be inherited from the Writer class
469 * because it must suppress I/O exceptions.
470 * @param s String to be written
472 public void write(String s) {
473 write(s, 0, s.length());
476 private void newLine() {
478 synchronized (lock) {
480 out.write(lineSeparator);
485 catch (InterruptedIOException x) {
486 Thread.currentThread().interrupt();
488 catch (IOException x) {
493 /* Methods that do not terminate lines */
496 * Prints a boolean value. The string produced by <code>{@link
497 * java.lang.String#valueOf(boolean)}</code> is translated into bytes
498 * according to the platform's default character encoding, and these bytes
499 * are written in exactly the manner of the <code>{@link
500 * #write(int)}</code> method.
502 * @param b The <code>boolean</code> to be printed
504 public void print(boolean b) {
505 write(b ? "true" : "false");
509 * Prints a character. The character is translated into one or more bytes
510 * according to the platform's default character encoding, and these bytes
511 * are written in exactly the manner of the <code>{@link
512 * #write(int)}</code> method.
514 * @param c The <code>char</code> to be printed
516 public void print(char c) {
521 * Prints an integer. The string produced by <code>{@link
522 * java.lang.String#valueOf(int)}</code> is translated into bytes according
523 * to the platform's default character encoding, and these bytes are
524 * written in exactly the manner of the <code>{@link #write(int)}</code>
527 * @param i The <code>int</code> to be printed
528 * @see java.lang.Integer#toString(int)
530 public void print(int i) {
531 write(String.valueOf(i));
535 * Prints a long integer. The string produced by <code>{@link
536 * java.lang.String#valueOf(long)}</code> is translated into bytes
537 * according to the platform's default character encoding, and these bytes
538 * are written in exactly the manner of the <code>{@link #write(int)}</code>
541 * @param l The <code>long</code> to be printed
542 * @see java.lang.Long#toString(long)
544 public void print(long l) {
545 write(String.valueOf(l));
549 * Prints a floating-point number. The string produced by <code>{@link
550 * java.lang.String#valueOf(float)}</code> is translated into bytes
551 * according to the platform's default character encoding, and these bytes
552 * are written in exactly the manner of the <code>{@link #write(int)}</code>
555 * @param f The <code>float</code> to be printed
556 * @see java.lang.Float#toString(float)
558 public void print(float f) {
559 write(String.valueOf(f));
563 * Prints a double-precision floating-point number. The string produced by
564 * <code>{@link java.lang.String#valueOf(double)}</code> is translated into
565 * bytes according to the platform's default character encoding, and these
566 * bytes are written in exactly the manner of the <code>{@link
567 * #write(int)}</code> method.
569 * @param d The <code>double</code> to be printed
570 * @see java.lang.Double#toString(double)
572 public void print(double d) {
573 write(String.valueOf(d));
577 * Prints an array of characters. The characters are converted into bytes
578 * according to the platform's default character encoding, and these bytes
579 * are written in exactly the manner of the <code>{@link #write(int)}</code>
582 * @param s The array of chars to be printed
584 * @throws NullPointerException If <code>s</code> is <code>null</code>
586 public void print(char s[]) {
591 * Prints a string. If the argument is <code>null</code> then the string
592 * <code>"null"</code> is printed. Otherwise, the string's characters are
593 * converted into bytes according to the platform's default character
594 * encoding, and these bytes are written in exactly the manner of the
595 * <code>{@link #write(int)}</code> method.
597 * @param s The <code>String</code> to be printed
599 public void print(String s) {
607 * Prints an object. The string produced by the <code>{@link
608 * java.lang.String#valueOf(Object)}</code> method is translated into bytes
609 * according to the platform's default character encoding, and these bytes
610 * are written in exactly the manner of the <code>{@link #write(int)}</code>
613 * @param obj The <code>Object</code> to be printed
614 * @see java.lang.Object#toString()
616 public void print(Object obj) {
617 write(String.valueOf(obj));
620 /* Methods that do terminate lines */
623 * Terminates the current line by writing the line separator string. The
624 * line separator string is defined by the system property
625 * <code>line.separator</code>, and is not necessarily a single newline
626 * character (<code>'\n'</code>).
628 public void println() {
633 * Prints a boolean value and then terminates the line. This method behaves
634 * as though it invokes <code>{@link #print(boolean)}</code> and then
635 * <code>{@link #println()}</code>.
637 * @param x the <code>boolean</code> value to be printed
639 public void println(boolean x) {
640 synchronized (lock) {
647 * Prints a character and then terminates the line. This method behaves as
648 * though it invokes <code>{@link #print(char)}</code> and then <code>{@link
649 * #println()}</code>.
651 * @param x the <code>char</code> value to be printed
653 public void println(char x) {
654 synchronized (lock) {
661 * Prints an integer and then terminates the line. This method behaves as
662 * though it invokes <code>{@link #print(int)}</code> and then <code>{@link
663 * #println()}</code>.
665 * @param x the <code>int</code> value to be printed
667 public void println(int x) {
668 synchronized (lock) {
675 * Prints a long integer and then terminates the line. This method behaves
676 * as though it invokes <code>{@link #print(long)}</code> and then
677 * <code>{@link #println()}</code>.
679 * @param x the <code>long</code> value to be printed
681 public void println(long x) {
682 synchronized (lock) {
689 * Prints a floating-point number and then terminates the line. This method
690 * behaves as though it invokes <code>{@link #print(float)}</code> and then
691 * <code>{@link #println()}</code>.
693 * @param x the <code>float</code> value to be printed
695 public void println(float x) {
696 synchronized (lock) {
703 * Prints a double-precision floating-point number and then terminates the
704 * line. This method behaves as though it invokes <code>{@link
705 * #print(double)}</code> and then <code>{@link #println()}</code>.
707 * @param x the <code>double</code> value to be printed
709 public void println(double x) {
710 synchronized (lock) {
717 * Prints an array of characters and then terminates the line. This method
718 * behaves as though it invokes <code>{@link #print(char[])}</code> and then
719 * <code>{@link #println()}</code>.
721 * @param x the array of <code>char</code> values to be printed
723 public void println(char x[]) {
724 synchronized (lock) {
731 * Prints a String and then terminates the line. This method behaves as
732 * though it invokes <code>{@link #print(String)}</code> and then
733 * <code>{@link #println()}</code>.
735 * @param x the <code>String</code> value to be printed
737 public void println(String x) {
738 synchronized (lock) {
745 * Prints an Object and then terminates the line. This method calls
746 * at first String.valueOf(x) to get the printed object's string value,
748 * though it invokes <code>{@link #print(String)}</code> and then
749 * <code>{@link #println()}</code>.
751 * @param x The <code>Object</code> to be printed.
753 public void println(Object x) {
754 String s = String.valueOf(x);
755 synchronized (lock) {
762 * A convenience method to write a formatted string to this writer using
763 * the specified format string and arguments. If automatic flushing is
764 * enabled, calls to this method will flush the output buffer.
766 * <p> An invocation of this method of the form <tt>out.printf(format,
767 * args)</tt> behaves in exactly the same way as the invocation
770 * out.format(format, args) </pre>
773 * A format string as described in <a
774 * href="../util/Formatter.html#syntax">Format string syntax</a>.
777 * Arguments referenced by the format specifiers in the format
778 * string. If there are more arguments than format specifiers, the
779 * extra arguments are ignored. The number of arguments is
780 * variable and may be zero. The maximum number of arguments is
781 * limited by the maximum dimension of a Java array as defined by
782 * <cite>The Java™ Virtual Machine Specification</cite>.
784 * <tt>null</tt> argument depends on the <a
785 * href="../util/Formatter.html#syntax">conversion</a>.
787 * @throws IllegalFormatException
788 * If a format string contains an illegal syntax, a format
789 * specifier that is incompatible with the given arguments,
790 * insufficient arguments given the format string, or other
791 * illegal conditions. For specification of all possible
792 * formatting errors, see the <a
793 * href="../util/Formatter.html#detail">Details</a> section of the
794 * formatter class specification.
796 * @throws NullPointerException
797 * If the <tt>format</tt> is <tt>null</tt>
799 * @return This writer
803 public PrintWriter printf(String format, Object ... args) {
804 return format(format, args);
808 * A convenience method to write a formatted string to this writer using
809 * the specified format string and arguments. If automatic flushing is
810 * enabled, calls to this method will flush the output buffer.
812 * <p> An invocation of this method of the form <tt>out.printf(l, format,
813 * args)</tt> behaves in exactly the same way as the invocation
816 * out.format(l, format, args) </pre>
819 * The {@linkplain java.util.Locale locale} to apply during
820 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
824 * A format string as described in <a
825 * href="../util/Formatter.html#syntax">Format string syntax</a>.
828 * Arguments referenced by the format specifiers in the format
829 * string. If there are more arguments than format specifiers, the
830 * extra arguments are ignored. The number of arguments is
831 * variable and may be zero. The maximum number of arguments is
832 * limited by the maximum dimension of a Java array as defined by
833 * <cite>The Java™ Virtual Machine Specification</cite>.
835 * <tt>null</tt> argument depends on the <a
836 * href="../util/Formatter.html#syntax">conversion</a>.
838 * @throws IllegalFormatException
839 * If a format string contains an illegal syntax, a format
840 * specifier that is incompatible with the given arguments,
841 * insufficient arguments given the format string, or other
842 * illegal conditions. For specification of all possible
843 * formatting errors, see the <a
844 * href="../util/Formatter.html#detail">Details</a> section of the
845 * formatter class specification.
847 * @throws NullPointerException
848 * If the <tt>format</tt> is <tt>null</tt>
850 * @return This writer
854 public PrintWriter printf(Locale l, String format, Object ... args) {
855 return format(l, format, args);
859 * Writes a formatted string to this writer using the specified format
860 * string and arguments. If automatic flushing is enabled, calls to this
861 * method will flush the output buffer.
863 * <p> The locale always used is the one returned by {@link
864 * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
865 * previous invocations of other formatting methods on this object.
868 * A format string as described in <a
869 * href="../util/Formatter.html#syntax">Format string syntax</a>.
872 * Arguments referenced by the format specifiers in the format
873 * string. If there are more arguments than format specifiers, the
874 * extra arguments are ignored. The number of arguments is
875 * variable and may be zero. The maximum number of arguments is
876 * limited by the maximum dimension of a Java array as defined by
877 * <cite>The Java™ Virtual Machine Specification</cite>.
879 * <tt>null</tt> argument depends on the <a
880 * href="../util/Formatter.html#syntax">conversion</a>.
882 * @throws IllegalFormatException
883 * If a format string contains an illegal syntax, a format
884 * specifier that is incompatible with the given arguments,
885 * insufficient arguments given the format string, or other
886 * illegal conditions. For specification of all possible
887 * formatting errors, see the <a
888 * href="../util/Formatter.html#detail">Details</a> section of the
889 * Formatter class specification.
891 * @throws NullPointerException
892 * If the <tt>format</tt> is <tt>null</tt>
894 * @return This writer
898 public PrintWriter format(String format, Object ... args) {
900 synchronized (lock) {
902 if ((formatter == null)
903 || (formatter.locale() != Locale.getDefault()))
904 formatter = new Formatter(this);
905 formatter.format(Locale.getDefault(), format, args);
909 } catch (InterruptedIOException x) {
910 Thread.currentThread().interrupt();
911 } catch (IOException x) {
918 * Writes a formatted string to this writer using the specified format
919 * string and arguments. If automatic flushing is enabled, calls to this
920 * method will flush the output buffer.
923 * The {@linkplain java.util.Locale locale} to apply during
924 * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
928 * A format string as described in <a
929 * href="../util/Formatter.html#syntax">Format string syntax</a>.
932 * Arguments referenced by the format specifiers in the format
933 * string. If there are more arguments than format specifiers, the
934 * extra arguments are ignored. The number of arguments is
935 * variable and may be zero. The maximum number of arguments is
936 * limited by the maximum dimension of a Java array as defined by
937 * <cite>The Java™ Virtual Machine Specification</cite>.
939 * <tt>null</tt> argument depends on the <a
940 * href="../util/Formatter.html#syntax">conversion</a>.
942 * @throws IllegalFormatException
943 * If a format string contains an illegal syntax, a format
944 * specifier that is incompatible with the given arguments,
945 * insufficient arguments given the format string, or other
946 * illegal conditions. For specification of all possible
947 * formatting errors, see the <a
948 * href="../util/Formatter.html#detail">Details</a> section of the
949 * formatter class specification.
951 * @throws NullPointerException
952 * If the <tt>format</tt> is <tt>null</tt>
954 * @return This writer
958 public PrintWriter format(Locale l, String format, Object ... args) {
960 synchronized (lock) {
962 if ((formatter == null) || (formatter.locale() != l))
963 formatter = new Formatter(this, l);
964 formatter.format(l, format, args);
968 } catch (InterruptedIOException x) {
969 Thread.currentThread().interrupt();
970 } catch (IOException x) {
977 * Appends the specified character sequence to this writer.
979 * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
980 * behaves in exactly the same way as the invocation
983 * out.write(csq.toString()) </pre>
985 * <p> Depending on the specification of <tt>toString</tt> for the
986 * character sequence <tt>csq</tt>, the entire sequence may not be
987 * appended. For instance, invoking the <tt>toString</tt> method of a
988 * character buffer will return a subsequence whose content depends upon
989 * the buffer's position and limit.
992 * The character sequence to append. If <tt>csq</tt> is
993 * <tt>null</tt>, then the four characters <tt>"null"</tt> are
994 * appended to this writer.
996 * @return This writer
1000 public PrintWriter append(CharSequence csq) {
1004 write(csq.toString());
1009 * Appends a subsequence of the specified character sequence to this writer.
1011 * <p> An invocation of this method of the form <tt>out.append(csq, start,
1012 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
1013 * exactly the same way as the invocation
1016 * out.write(csq.subSequence(start, end).toString()) </pre>
1019 * The character sequence from which a subsequence will be
1020 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
1021 * will be appended as if <tt>csq</tt> contained the four
1022 * characters <tt>"null"</tt>.
1025 * The index of the first character in the subsequence
1028 * The index of the character following the last character in the
1031 * @return This writer
1033 * @throws IndexOutOfBoundsException
1034 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1035 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1036 * <tt>csq.length()</tt>
1040 public PrintWriter append(CharSequence csq, int start, int end) {
1041 CharSequence cs = (csq == null ? "null" : csq);
1042 write(cs.subSequence(start, end).toString());
1047 * Appends the specified character to this writer.
1049 * <p> An invocation of this method of the form <tt>out.append(c)</tt>
1050 * behaves in exactly the same way as the invocation
1053 * out.write(c) </pre>
1056 * The 16-bit character to append
1058 * @return This writer
1062 public PrintWriter append(char c) {