hunt.util.Appendable source code

1 module hunt.util.Appendable;
2 
3 
4 /**
5  * An object to which {@code char} sequences and values can be appended.  The
6  * {@code Appendable} interface must be implemented by any class whose
7  * instances are intended to receive formatted output from a formatter.
8  *
9  * <p> The characters to be appended should be valid Unicode characters as
10  * described in <a href="Character.html#unicode">Unicode Character
11  * Representation</a>.  Note that supplementary characters may be composed of
12  * multiple 16-bit {@code char} values.
13  *
14  * <p> Appendables are not necessarily safe for multithreaded access.  Thread
15  * safety is the responsibility of classes that extend and implement this
16  * interface.
17  *
18  * <p> Since this interface may be implemented by existing classes
19  * with different styles of error handling there is no guarantee that
20  * errors will be propagated to the invoker.
21  *
22  */
23 interface Appendable {
24 
25     /**
26      * Appends the specified character sequence to this {@code Appendable}.
27      *
28      * <p> Depending on which class implements the character sequence
29      * {@code csq}, the entire sequence may not be appended.  For
30      * instance, if {@code csq} is a {@link java.nio.CharBuffer} then
31      * the subsequence to append is defined by the buffer's position and limit.
32      *
33      * @param  csq
34      *         The character sequence to append.  If {@code csq} is
35      *         {@code null}, then the four characters {@code "null"} are
36      *         appended to this Appendable.
37      *
38      * @return  A reference to this {@code Appendable}
39      *
40      * @throws  IOException
41      *          If an I/O error occurs
42      */
43     Appendable append(const(char)[] csq);
44 
45     /**
46      * Appends a subsequence of the specified character sequence to this
47      * {@code Appendable}.
48      *
49      * <p> An invocation of this method of the form {@code out.append(csq, start, end)}
50      * when {@code csq} is not {@code null}, behaves in
51      * exactly the same way as the invocation
52      *
53      * <pre>
54      *     out.append(csq.subSequence(start, end)) </pre>
55      *
56      * @param  csq
57      *         The character sequence from which a subsequence will be
58      *         appended.  If {@code csq} is {@code null}, then characters
59      *         will be appended as if {@code csq} contained the four
60      *         characters {@code "null"}.
61      *
62      * @param  start
63      *         The index of the first character in the subsequence
64      *
65      * @param  end
66      *         The index of the character following the last character in the
67      *         subsequence
68      *
69      * @return  A reference to this {@code Appendable}
70      *
71      * @throws  IndexOutOfBoundsException
72      *          If {@code start} or {@code end} are negative, {@code start}
73      *          is greater than {@code end}, or {@code end} is greater than
74      *          {@code csq.length()}
75      *
76      * @throws  IOException
77      *          If an I/O error occurs
78      */
79     Appendable append(const(char)[], int start, int end);
80 
81     /**
82      * Appends the specified character to this {@code Appendable}.
83      *
84      * @param  c
85      *         The character to append
86      *
87      * @return  A reference to this {@code Appendable}
88      *
89      * @throws  IOException
90      *          If an I/O error occurs
91      */
92     Appendable append(char c);
93 }