Source for java.lang.CharSequence

   1: /* CharSequence.java -- Anything that has an indexed sequence of chars
   2:    Copyright (C) 2001, 2002 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.lang;
  40: 
  41: /**
  42:  * General functions on a sequence of chars. This interface is implemented
  43:  * by <code>String</code>, <code>StringBuffer</code> and
  44:  * <code>CharBuffer</code> to give a uniform way to get chars at a certain
  45:  * index, the number of characters in the sequence and a subrange of the
  46:  * chars. Indexes start at 0 and the last index is <code>length()-1</code>.
  47:  *
  48:  * <p>Even when classes implement this interface they are not always
  49:  * exchangeble because they might implement their compare, equals or hash
  50:  * function differently. This means that in general one should not use a
  51:  * <code>CharSequence</code> as keys in collections since two sequences
  52:  * with the same chars at the same indexes with the same length might not
  53:  * have the same hash code, be equal or be comparable since the are
  54:  * represented by different classes.
  55:  *
  56:  * @author Mark Wielaard (mark@klomp.org)
  57:  * @since 1.4
  58:  * @status updated to 1.4
  59:  */
  60: public interface CharSequence
  61: {
  62:   /**
  63:    * Returns the character at the given index.
  64:    *
  65:    * @param i the index to retrieve from
  66:    * @return the character at that location
  67:    * @throws IndexOutOfBoundsException if i &lt; 0 || i &gt;= length() - 1
  68:    */
  69:   char charAt(int i);
  70: 
  71:   /**
  72:    * Returns the length of the sequence. This is the number of 16-bit
  73:    * characters in the sequence, which may differ from the length of the
  74:    * underlying encoding.
  75:    *
  76:    * @return the sequence length
  77:    */
  78:   int length();
  79: 
  80:   /**
  81:    * Returns a new <code>CharSequence</code> of the indicated range.
  82:    *
  83:    * @param begin the start index (inclusive)
  84:    * @param end the end index (exclusive)
  85:    * @return a subsequence of this
  86:    * @throws IndexOutOfBoundsException if begin &gt; end || begin &lt; 0 ||
  87:    *         end &gt; length()
  88:    */
  89:   CharSequence subSequence(int begin, int end);
  90: 
  91:   /**
  92:    * Returns the complete <code>CharSequence</code> as a <code>String</code>.
  93:    * Classes that implement this interface should return a <code>String</code>
  94:    * which contains only the characters in the sequence in the correct order.
  95:    *
  96:    * @return the character sequence as a String
  97:    */
  98:   String toString();
  99: }