1 /*
2 * Copyright (c) 2003, 2004, 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.lang;
27
28 import java.io.IOException;
29
30 /**
31 * An object to which {@code char} sequences and values can be appended. The
32 * {@code Appendable} interface must be implemented by any class whose
33 * instances are intended to receive formatted output from a {@link
34 * java.util.Formatter}.
35 *
36 * <p> The characters to be appended should be valid Unicode characters as
37 * described in <a href="Character.html#unicode">Unicode Character
38 * Representation</a>. Note that supplementary characters may be composed of
39 * multiple 16-bit {@code char} values.
40 *
41 * <p> Appendables are not necessarily safe for multithreaded access. Thread
42 * safety is the responsibility of classes that extend and implement this
43 * interface.
44 *
45 * <p> Since this interface may be implemented by existing classes
46 * with different styles of error handling there is no guarantee that
47 * errors will be propagated to the invoker.
48 *
49 * @since 1.5
50 */
51 public interface Appendable {
52
53 /**
54 * Appends the specified character sequence to this {@code Appendable}.
55 *
56 * <p> Depending on which class implements the character sequence
57 * {@code csq}, the entire sequence may not be appended. For
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.
60 *
61 * @param csq
62 * The character sequence to append. If {@code csq} is
63 * {@code null}, then the four characters {@code "null"} are
64 * appended to this Appendable.
65 *
66 * @return A reference to this {@code Appendable}
67 *
68 * @throws IOException
69 * If an I/O error occurs
70 */
71 Appendable append(CharSequence csq) throws IOException;
72
73 /**
74 * Appends a subsequence of the specified character sequence to this
75 * {@code Appendable}.
76 *
77 * <p> An invocation of this method of the form {@code out.append(csq, start, end)}
78 * when {@code csq} is not {@code null}, behaves in
79 * exactly the same way as the invocation
80 *
81 * <pre>
82 * out.append(csq.subSequence(start, end)) </pre>
83 *
84 * @param csq
85 * The character sequence from which a subsequence will be
86 * appended. If {@code csq} is {@code null}, then characters
87 * will be appended as if {@code csq} contained the four
88 * characters {@code "null"}.
89 *
90 * @param start
91 * The index of the first character in the subsequence
92 *
93 * @param end
94 * The index of the character following the last character in the
95 * subsequence
96 *
97 * @return A reference to this {@code Appendable}
98 *
99 * @throws IndexOutOfBoundsException
100 * If {@code start} or {@code end} are negative, {@code start}
101 * is greater than {@code end}, or {@code end} is greater than
102 * {@code csq.length()}
103 *
104 * @throws IOException
105 * If an I/O error occurs
106 */
107 Appendable append(CharSequence csq, int start, int end) throws IOException;
108
109 /**
110 * Appends the specified character to this {@code Appendable}.
111 *
112 * @param c
113 * The character to append
114 *
115 * @return A reference to this {@code Appendable}
116 *
117 * @throws IOException
118 * If an I/O error occurs
119 */
120 Appendable append(char c) throws IOException;
121
122 /**
123 * Appends {@code n} copies of the specified character to this
124 * {@code Appendable}.
125 *
126 * @param c
127 * The character to append
128 * @param n
129 * The number of copies
130 *
131 * @return A reference to this {@code Appendable}
132 *
133 * @throws IOException
134 * If an I/O error occurs
135 * @throws IllegalArgumentException
136 * If {@code n} is negative
137 */
138 default Appendable appendN(char c, int n) throws IOException {
139 if (n < 0) {
140 throw new IllegalArgumentException("Negative number of"
141 + " copies: " + n);
142 }
143 StringBuilder sb = new StringBuilder(n);
144 return append(sb.appendN(c, n));
145 }
146 }