String, StringBuffer and
* CharBuffer to give a uniform way to get chars at a certain
* index, the number of characters in the sequence and a subrange of the
* chars. Indexes start at 0 and the last index is length()-1.
*
* Even when classes implement this interface they are not always
* exchangeble because they might implement their compare, equals or hash
* function differently. This means that in general one should not use a
* CharSequence as keys in collections since two sequences
* with the same chars at the same indexes with the same length might not
* have the same hash code, be equal or be comparable since the are
* represented by different classes.
*
* @author Mark Wielaard (mark@klomp.org)
* @since 1.4
* @status updated to 1.4
*/
public interface CharSequence
{
/**
* Returns the character at the given index.
*
* @param i the index to retrieve from
* @return the character at that location
* @throws IndexOutOfBoundsException if i < 0 || i >= length() - 1
*/
char charAt(int i);
/**
* Returns the length of the sequence. This is the number of 16-bit
* characters in the sequence, which may differ from the length of the
* underlying encoding.
*
* @return the sequence length
*/
int length();
/**
* Returns a new CharSequence of the indicated range.
*
* @param begin the start index (inclusive)
* @param end the end index (exclusive)
* @return a subsequence of this
* @throws IndexOutOfBoundsException if begin > end || begin < 0 ||
* end > length()
*/
CharSequence subSequence(int begin, int end);
/**
* Returns the complete CharSequence as a String.
* Classes that implement this interface should return a String
* which contains only the characters in the sequence in the correct order.
*
* @return the character sequence as a String
*/
String toString();
}