26 package java.lang; |
26 package java.lang; |
27 |
27 |
28 import java.io.IOException; |
28 import java.io.IOException; |
29 |
29 |
30 /** |
30 /** |
31 * An object to which <tt>char</tt> sequences and values can be appended. The |
31 * An object to which {@code char} sequences and values can be appended. The |
32 * <tt>Appendable</tt> interface must be implemented by any class whose |
32 * {@code Appendable} interface must be implemented by any class whose |
33 * instances are intended to receive formatted output from a {@link |
33 * instances are intended to receive formatted output from a {@link |
34 * java.util.Formatter}. |
34 * java.util.Formatter}. |
35 * |
35 * |
36 * <p> The characters to be appended should be valid Unicode characters as |
36 * <p> The characters to be appended should be valid Unicode characters as |
37 * described in <a href="Character.html#unicode">Unicode Character |
37 * described in <a href="Character.html#unicode">Unicode Character |
38 * Representation</a>. Note that supplementary characters may be composed of |
38 * Representation</a>. Note that supplementary characters may be composed of |
39 * multiple 16-bit <tt>char</tt> values. |
39 * multiple 16-bit {@code char} values. |
40 * |
40 * |
41 * <p> Appendables are not necessarily safe for multithreaded access. Thread |
41 * <p> Appendables are not necessarily safe for multithreaded access. Thread |
42 * safety is the responsibility of classes that extend and implement this |
42 * safety is the responsibility of classes that extend and implement this |
43 * interface. |
43 * interface. |
44 * |
44 * |
49 * @since 1.5 |
49 * @since 1.5 |
50 */ |
50 */ |
51 public interface Appendable { |
51 public interface Appendable { |
52 |
52 |
53 /** |
53 /** |
54 * Appends the specified character sequence to this <tt>Appendable</tt>. |
54 * Appends the specified character sequence to this {@code Appendable}. |
55 * |
55 * |
56 * <p> Depending on which class implements the character sequence |
56 * <p> Depending on which class implements the character sequence |
57 * <tt>csq</tt>, the entire sequence may not be appended. For |
57 * {@code csq}, the entire sequence may not be appended. For |
58 * instance, if <tt>csq</tt> is a {@link java.nio.CharBuffer} then |
58 * instance, if {@code csq} is a {@link java.nio.CharBuffer} then |
59 * the subsequence to append is defined by the buffer's position and limit. |
59 * the subsequence to append is defined by the buffer's position and limit. |
60 * |
60 * |
61 * @param csq |
61 * @param csq |
62 * The character sequence to append. If <tt>csq</tt> is |
62 * The character sequence to append. If {@code csq} is |
63 * <tt>null</tt>, then the four characters <tt>"null"</tt> are |
63 * {@code null}, then the four characters {@code "null"} are |
64 * appended to this Appendable. |
64 * appended to this Appendable. |
65 * |
65 * |
66 * @return A reference to this <tt>Appendable</tt> |
66 * @return A reference to this {@code Appendable} |
67 * |
67 * |
68 * @throws IOException |
68 * @throws IOException |
69 * If an I/O error occurs |
69 * If an I/O error occurs |
70 */ |
70 */ |
71 Appendable append(CharSequence csq) throws IOException; |
71 Appendable append(CharSequence csq) throws IOException; |
72 |
72 |
73 /** |
73 /** |
74 * Appends a subsequence of the specified character sequence to this |
74 * Appends a subsequence of the specified character sequence to this |
75 * <tt>Appendable</tt>. |
75 * {@code Appendable}. |
76 * |
76 * |
77 * <p> An invocation of this method of the form <tt>out.append(csq, start, |
77 * <p> An invocation of this method of the form {@code out.append(csq, start, end)} |
78 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in |
78 * when {@code csq} is not {@code null}, behaves in |
79 * exactly the same way as the invocation |
79 * exactly the same way as the invocation |
80 * |
80 * |
81 * <pre> |
81 * <pre> |
82 * out.append(csq.subSequence(start, end)) </pre> |
82 * out.append(csq.subSequence(start, end)) </pre> |
83 * |
83 * |
84 * @param csq |
84 * @param csq |
85 * The character sequence from which a subsequence will be |
85 * The character sequence from which a subsequence will be |
86 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters |
86 * appended. If {@code csq} is {@code null}, then characters |
87 * will be appended as if <tt>csq</tt> contained the four |
87 * will be appended as if {@code csq} contained the four |
88 * characters <tt>"null"</tt>. |
88 * characters {@code "null"}. |
89 * |
89 * |
90 * @param start |
90 * @param start |
91 * The index of the first character in the subsequence |
91 * The index of the first character in the subsequence |
92 * |
92 * |
93 * @param end |
93 * @param end |
94 * The index of the character following the last character in the |
94 * The index of the character following the last character in the |
95 * subsequence |
95 * subsequence |
96 * |
96 * |
97 * @return A reference to this <tt>Appendable</tt> |
97 * @return A reference to this {@code Appendable} |
98 * |
98 * |
99 * @throws IndexOutOfBoundsException |
99 * @throws IndexOutOfBoundsException |
100 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt> |
100 * If {@code start} or {@code end} are negative, {@code start} |
101 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than |
101 * is greater than {@code end}, or {@code end} is greater than |
102 * <tt>csq.length()</tt> |
102 * {@code csq.length()} |
103 * |
103 * |
104 * @throws IOException |
104 * @throws IOException |
105 * If an I/O error occurs |
105 * If an I/O error occurs |
106 */ |
106 */ |
107 Appendable append(CharSequence csq, int start, int end) throws IOException; |
107 Appendable append(CharSequence csq, int start, int end) throws IOException; |
108 |
108 |
109 /** |
109 /** |
110 * Appends the specified character to this <tt>Appendable</tt>. |
110 * Appends the specified character to this {@code Appendable}. |
111 * |
111 * |
112 * @param c |
112 * @param c |
113 * The character to append |
113 * The character to append |
114 * |
114 * |
115 * @return A reference to this <tt>Appendable</tt> |
115 * @return A reference to this {@code Appendable} |
116 * |
116 * |
117 * @throws IOException |
117 * @throws IOException |
118 * If an I/O error occurs |
118 * If an I/O error occurs |
119 */ |
119 */ |
120 Appendable append(char c) throws IOException; |
120 Appendable append(char c) throws IOException; |