package java.lang;

import java.io.IOException;

import ej.annotation.Nullable;

/**
 * An object to which <code>char</code> sequences and values can be appended.
 *
 * <p>
 * The characters to be appended should be valid Unicode characters. Note that supplementary
 * characters may be composed of multiple 16-bit <code>char</code> values.
 *
 * <p>
 * Appendables are not necessarily safe for multithreaded access. Thread safety is the
 * responsibility of classes that extend and implement this interface.
 *
 * <p>
 * Since this interface may be implemented by existing classes with different styles of error
 * handling there is no guarantee that errors will be propagated to the invoker.
 */
public interface Appendable {

	/**
	 * Appends the specified character to this <code>Appendable</code>.
	 *
	 * @param c
	 *        The character to append
	 *
	 * @return A reference to this <code>Appendable</code>
	 *
	 * @throws IOException
	 *         If an I/O error occurs
	 */
	Appendable append(char c) throws IOException;

	/**
	 * Appends the specified character sequence to this <code>Appendable</code>.
	 *
	 * <p>
	 * Depending on which class implements the character sequence <code>csq</code>, the entire sequence may
	 * not be appended.
	 *
	 * @param csq
	 *        The character sequence to append. If <code>csq</code> is <code>null</code>, then the four
	 *        characters <code>"null"</code> are appended to this Appendable.
	 *
	 * @return A reference to this <code>Appendable</code>
	 *
	 * @throws IOException
	 *         If an I/O error occurs
	 */
	Appendable append(@Nullable CharSequence csq) throws IOException;

	/**
	 * Appends a subsequence of the specified character sequence to this <code>Appendable</code>.
	 *
	 * <p>
	 * An invocation of this method of the form <code>out.append(csq, start,
	 * end)</code> when <code>csq</code> is not <code>null</code>, behaves in exactly the same way as the
	 * invocation
	 *
	 * <pre>
	 * out.append(csq.subSequence(start, end))
	 * </pre>
	 *
	 * @param csq
	 *        The character sequence from which a subsequence will be appended. If <code>csq</code> is
	 *        <code>null</code>, then characters will be appended as if <code>csq</code> contained the four
	 *        characters <code>"null"</code>.
	 *
	 * @param start
	 *        The index of the first character in the subsequence
	 *
	 * @param end
	 *        The index of the character following the last character in the subsequence
	 *
	 * @return A reference to this <code>Appendable</code>
	 *
	 * @throws IndexOutOfBoundsException
	 *         If <code>start</code> or <code>end</code> are negative, <code>start</code> is greater than
	 *         <code>end</code>, or <code>end</code> is greater than <code>csq.length()</code>
	 *
	 * @throws IOException
	 *         If an I/O error occurs
	 */
	Appendable append(@Nullable CharSequence csq, int start, int end) throws IOException;
}