001: /*
002: * @(#)CharSequence.java 1.9 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.lang;
028:
029: /**
030: * A <tt>CharSequence</tt> is a readable sequence of characters. This
031: * interface provides uniform, read-only access to many different kinds of
032: * character sequences.
033: *
034: * <p> This interface does not refine the general contracts of the {@link
035: * java.lang.Object#equals(java.lang.Object) equals} and {@link
036: * java.lang.Object#hashCode() hashCode} methods. The result of comparing two
037: * objects that implement <tt>CharSequence</tt> is therefore, in general,
038: * undefined. Each object may be implemented by a different class, and there
039: * is no guarantee that each class will be capable of testing its instances
040: * for equality with those of the other. It is therefore inappropriate to use
041: * arbitrary <tt>CharSequence</tt> instances as elements in a set or as keys in
042: * a map. </p>
043: *
044: * @author Mike McCloskey
045: * @version 1.9 06/10/10
046: * @since 1.4
047: * @spec JSR-51
048: */
049:
050: public interface CharSequence {
051:
052: /**
053: * Returns the length of this character sequence. The length is the number
054: * of 16-bit Unicode characters in the sequence. </p>
055: *
056: * @return the number of characters in this sequence
057: */
058: int length();
059:
060: /**
061: * Returns the character at the specified index. An index ranges from zero
062: * to <tt>length() - 1</tt>. The first character of the sequence is at
063: * index zero, the next at index one, and so on, as for array
064: * indexing. </p>
065: *
066: * @param index the index of the character to be returned
067: *
068: * @return the specified character
069: *
070: * @throws IndexOutOfBoundsException
071: * if the <tt>index</tt> argument is negative or not less than
072: * <tt>length()</tt>
073: */
074: char charAt(int index);
075:
076: /**
077: * Returns a new character sequence that is a subsequence of this sequence.
078: * The subsequence starts with the character at the specified index and
079: * ends with the character at index <tt>end - 1</tt>. The length of the
080: * returned sequence is <tt>end - start</tt>, so if <tt>start == end</tt>
081: * then an empty sequence is returned. </p>
082: *
083: * @param start the start index, inclusive
084: * @param end the end index, exclusive
085: *
086: * @return the specified subsequence
087: *
088: * @throws IndexOutOfBoundsException
089: * if <tt>start</tt> or <tt>end</tt> are negative,
090: * if <tt>end</tt> is greater than <tt>length()</tt>,
091: * or if <tt>start</tt> is greater than <tt>end</tt>
092: */
093: CharSequence subSequence(int start, int end);
094:
095: /**
096: * Returns a string containing the characters in this sequence in the same
097: * order as this sequence. The length of the string will be the length of
098: * this sequence. </p>
099: *
100: * @return a string consisting of exactly this sequence of characters
101: */
102: public String toString();
103:
104: }
|