libjava/java/lang/String.java

   1 /* String.java -- immutable character sequences; the object of string literals
   2    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39
  40 package java.lang;
  41
  42 import java.io.Serializable;
  43 import java.io.UnsupportedEncodingException;
  44 import java.lang.Comparable;
  45 import java.util.Comparator;
  46 import java.util.Locale;
  47 import java.util.regex.Pattern;
  48 import java.util.regex.PatternSyntaxException;
  49
  50 /**
  51  * Strings represent an immutable set of characters.  All String literals
  52  * are instances of this class, and two string literals with the same contents
  53  * refer to the same String object.
  54  *
  55  * <p>This class also includes a number of methods for manipulating the
  56  * contents of strings (of course, creating a new object if there are any
  57  * changes, as String is immutable). Case mapping relies on Unicode 3.0.0
  58  * standards, where some character sequences have a different number of
  59  * characters in the uppercase version than the lower case.
  60  *
  61  * <p>Strings are special, in that they are the only object with an overloaded
  62  * operator. When you use '+' with at least one String argument, both
  63  * arguments have String conversion performed on them, and another String (not
  64  * guaranteed to be unique) results.
  65  *
  66  * <p>String is special-cased when doing data serialization - rather than
  67  * listing the fields of this class, a String object is converted to a string
  68  * literal in the object stream.
  69  *
  70  * @author Paul N. Fisher
  71  * @author Eric Blake (ebb9@email.byu.edu)
  72  * @author Per Bothner (bothner@cygnus.com)
  73  * @since 1.0
  74  * @status updated to 1.4
  75  */
  76 public final class String implements Serializable, Comparable, CharSequence
  77 {
  78   // WARNING: String is a CORE class in the bootstrap cycle. See the comments
  79   // in vm/reference/java/lang/Runtime for implications of this fact.
  80
  81   /**
  82    * This is probably not necessary because this class is special cased already
  83    * but it will avoid showing up as a discrepancy when comparing SUIDs.
  84    */
  85   private static final long serialVersionUID = -6849794470754667710L;
  86
  87   /**
  88    * This is the object that holds the characters that make up the
  89    * String.  It might be a char[], or it could be String.  It could
  90    * even be `this'.  The actual characters can't be located using
  91    * pure Java code.
  92    * @see #boffset
  93    */
  94   private Object data;
  95
  96   /**
  97    * This is a <emph>byte</emph> offset of the actual characters from
  98    * the start of the character-holding object.  Don't use this field
  99    * in Java code.
 100    */
 101   private int boffset;
 102
 103   /**
 104    * Holds the number of characters in value.  Package visible for use
 105    * by trusted code.
 106    */
 107   int count;
 108
 109   /**
 110    * Caches the result of hashCode().  If this value is zero, the hashcode
 111    * is considered uncached (even if 0 is the correct hash value).
 112    */
 113   private int cachedHashCode;
 114
 115   /**
 116    * An implementation for {@link CASE_INSENSITIVE_ORDER}.
 117    * This must be {@link Serializable}. The class name is dictated by
 118    * compatibility with Sun's JDK.
 119    */
 120   private static final class CaseInsensitiveComparator
 121     implements Comparator, Serializable
 122   {
 123     /**
 124      * Compatible with JDK 1.2.
 125      */
 126     private static final long serialVersionUID = 8575799808933029326L;
 127
 128     /**
 129      * The default private constructor generates unnecessary overhead.
 130      */
 131     CaseInsensitiveComparator() {}
 132
 133     /**
 134      * Compares to Strings, using
 135      * <code>String.compareToIgnoreCase(String)</code>.
 136      *
 137      * @param o1 the first string
 138      * @param o2 the second string
 139      * @return &lt; 0, 0, or &gt; 0 depending on the case-insensitive
 140      *         comparison of the two strings.
 141      * @throws NullPointerException if either argument is null
 142      * @throws ClassCastException if either argument is not a String
 143      * @see #compareToIgnoreCase(String)
 144      */
 145     public int compare(Object o1, Object o2)
 146     {
 147       return ((String) o1).compareToIgnoreCase((String) o2);
 148     }
 149   } // class CaseInsensitiveComparator
 150
 151   /**
 152    * A Comparator that uses <code>String.compareToIgnoreCase(String)</code>.
 153    * This comparator is {@link Serializable}. Note that it ignores Locale,
 154    * for that, you want a Collator.
 155    *
 156    * @see Collator#compare(String, String)
 157    * @since 1.2
 158    */
 159   public static final Comparator CASE_INSENSITIVE_ORDER
 160     = new CaseInsensitiveComparator();
 161
 162   /**
 163    * Creates an empty String (length 0). Unless you really need a new object,
 164    * consider using <code>""</code> instead.
 165    */
 166   public String()
 167   {
 168     data = "".data;
 169     boffset = 0;
 170     count = 0;
 171   }
 172
 173   /**
 174    * Copies the contents of a String to a new String. Since Strings are
 175    * immutable, only a shallow copy is performed.
 176    *
 177    * @param str String to copy
 178    * @throws NullPointerException if value is null
 179    */
 180   public String(String str)
 181   {
 182     data = str.data;
 183     boffset = str.boffset;
 184     count = str.count;
 185     cachedHashCode = str.cachedHashCode;
 186   }
 187
 188   /**
 189    * Creates a new String using the character sequence of the char array.
 190    * Subsequent changes to data do not affect the String.
 191    *
 192    * @param data char array to copy
 193    * @throws NullPointerException if data is null
 194    */
 195   public String(char[] data)
 196   {
 197     init(data, 0, data.length, false);
 198   }
 199
 200   /**
 201    * Creates a new String using the character sequence of a subarray of
 202    * characters. The string starts at offset, and copies count chars.
 203    * Subsequent changes to data do not affect the String.
 204    *
 205    * @param data char array to copy
 206    * @param offset position (base 0) to start copying out of data
 207    * @param count the number of characters from data to copy
 208    * @throws NullPointerException if data is null
 209    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
 210    *         || offset + count &gt; data.length)
 211    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 212    */
 213   public String(char[] data, int offset, int count)
 214   {
 215     init(data, offset, count, false);
 216   }
 217
 218   /**
 219    * Creates a new String using an 8-bit array of integer values, starting at
 220    * an offset, and copying up to the count. Each character c, using
 221    * corresponding byte b, is created in the new String as if by performing:
 222    *
 223    * <pre>
 224    * c = (char) (((hibyte &amp; 0xff) &lt;&lt; 8) | (b &amp; 0xff))
 225    * </pre>
 226    *
 227    * @param ascii array of integer values
 228    * @param hibyte top byte of each Unicode character
 229    * @param offset position (base 0) to start copying out of ascii
 230    * @param count the number of characters from ascii to copy
 231    * @throws NullPointerException if ascii is null
 232    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
 233    *         || offset + count &gt; ascii.length)
 234    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 235    * @see #String(byte[])
 236    * @see #String(byte[], String)
 237    * @see #String(byte[], int, int)
 238    * @see #String(byte[], int, int, String)
 239    * @deprecated use {@link #String(byte[], int, int, String)} to perform
 240    *             correct encoding
 241    */
 242   public String(byte[] ascii, int hibyte, int offset, int count)
 243   {
 244     init(ascii, hibyte, offset, count);
 245   }
 246
 247   /**
 248    * Creates a new String using an 8-bit array of integer values. Each
 249    * character c, using corresponding byte b, is created in the new String
 250    * as if by performing:
 251    *
 252    * <pre>
 253    * c = (char) (((hibyte &amp; 0xff) &lt;&lt; 8) | (b &amp; 0xff))
 254    * </pre>
 255    *
 256    * @param ascii array of integer values
 257    * @param hibyte top byte of each Unicode character
 258    * @throws NullPointerException if ascii is null
 259    * @see #String(byte[])
 260    * @see #String(byte[], String)
 261    * @see #String(byte[], int, int)
 262    * @see #String(byte[], int, int, String)
 263    * @see #String(byte[], int, int, int)
 264    * @deprecated use {@link #String(byte[], String)} to perform
 265    *             correct encoding
 266    */
 267   public String(byte[] ascii, int hibyte)
 268   {
 269     init(ascii, hibyte, 0, ascii.length);
 270   }
 271
 272   /**
 273    * Creates a new String using the portion of the byte array starting at the
 274    * offset and ending at offset + count. Uses the specified encoding type
 275    * to decode the byte array, so the resulting string may be longer or
 276    * shorter than the byte array. For more decoding control, use
 277    * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
 278    * see {@link java.nio.charset.Charset}. The behavior is not specified if
 279    * the decoder encounters invalid characters; this implementation throws
 280    * an Error.
 281    *
 282    * @param data byte array to copy
 283    * @param offset the offset to start at
 284    * @param count the number of characters in the array to use
 285    * @param encoding the name of the encoding to use
 286    * @throws NullPointerException if data or encoding is null
 287    * @throws IndexOutOfBoundsException if offset or count is incorrect
 288    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 289    * @throws UnsupportedEncodingException if encoding is not found
 290    * @throws Error if the decoding fails
 291    * @since 1.1
 292    */
 293   public String(byte[] data, int offset, int count, String encoding)
 294     throws UnsupportedEncodingException
 295   {
 296     init (data, offset, count, encoding);
 297   }
 298
 299   /**
 300    * Creates a new String using the byte array. Uses the specified encoding
 301    * type to decode the byte array, so the resulting string may be longer or
 302    * shorter than the byte array. For more decoding control, use
 303    * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
 304    * see {@link java.nio.charset.Charset}. The behavior is not specified if
 305    * the decoder encounters invalid characters; this implementation throws
 306    * an Error.
 307    *
 308    * @param data byte array to copy
 309    * @param encoding the name of the encoding to use
 310    * @throws NullPointerException if data or encoding is null
 311    * @throws UnsupportedEncodingException if encoding is not found
 312    * @throws Error if the decoding fails
 313    * @see #String(byte[], int, int, String)
 314    * @since 1.1
 315    */
 316   public String(byte[] data, String encoding)
 317     throws UnsupportedEncodingException
 318   {
 319     this(data, 0, data.length, encoding);
 320   }
 321
 322   /**
 323    * Creates a new String using the portion of the byte array starting at the
 324    * offset and ending at offset + count. Uses the encoding of the platform's
 325    * default charset, so the resulting string may be longer or shorter than
 326    * the byte array. For more decoding control, use
 327    * {@link java.nio.charset.CharsetDecoder}.  The behavior is not specified
 328    * if the decoder encounters invalid characters; this implementation throws
 329    * an Error.
 330    *
 331    * @param data byte array to copy
 332    * @param offset the offset to start at
 333    * @param count the number of characters in the array to use
 334    * @throws NullPointerException if data is null
 335    * @throws IndexOutOfBoundsException if offset or count is incorrect
 336    * @throws Error if the decoding fails
 337    * @see #String(byte[], int, int, String)
 338    * @since 1.1
 339    */
 340   public String(byte[] data, int offset, int count)
 341   {
 342     try
 343       {
 344         init (data, offset, count,
 345               System.getProperty("file.encoding", "8859_1"));
 346       }
 347     catch (UnsupportedEncodingException x1)
 348       {
 349         // Maybe the default encoding is bad.
 350         try
 351           {
 352             init (data, offset, count, "8859_1");
 353           }
 354         catch (UnsupportedEncodingException x2)
 355           {
 356             // We know this can't happen.
 357           }
 358       }
 359   }
 360
 361   /**
 362    * Creates a new String using the byte array. Uses the encoding of the
 363    * platform's default charset, so the resulting string may be longer or
 364    * shorter than the byte array. For more decoding control, use
 365    * {@link java.nio.charset.CharsetDecoder}.  The behavior is not specified
 366    * if the decoder encounters invalid characters; this implementation throws
 367    * an Error.
 368    *
 369    * @param data byte array to copy
 370    * @throws NullPointerException if data is null
 371    * @throws Error if the decoding fails
 372    * @see #String(byte[], int, int)
 373    * @see #String(byte[], int, int, String)
 374    * @since 1.1
 375    */
 376   public String(byte[] data)
 377   {
 378     this(data, 0, data.length);
 379   }
 380
 381   /**
 382    * Creates a new String using the character sequence represented by
 383    * the StringBuffer. Subsequent changes to buf do not affect the String.
 384    *
 385    * @param buffer StringBuffer to copy
 386    * @throws NullPointerException if buffer is null
 387    */
 388   public String(StringBuffer buffer)
 389   {
 390     synchronized (buffer)
 391       {
 392         // Share unless buffer is 3/4 empty.
 393         boolean should_copy = ((buffer.count << 2) < buffer.value.length);
 394         if (! should_copy)
 395           buffer.shared = true;
 396         init (buffer.value, 0, buffer.count, ! should_copy);
 397       }
 398   }
 399
 400   /**
 401    * Special constructor which can share an array when safe to do so.
 402    *
 403    * @param data the characters to copy
 404    * @param offset the location to start from
 405    * @param count the number of characters to use
 406    * @param dont_copy true if the array is trusted, and need not be copied
 407    * @throws NullPointerException if chars is null
 408    * @throws StringIndexOutOfBoundsException if bounds check fails
 409    */
 410   String(char[] data, int offset, int count, boolean dont_copy)
 411   {
 412     init(data, offset, count, dont_copy);
 413   }
 414
 415   // This is used by gnu.gcj.runtime.StringBuffer, so it must have
 416   // package-private protection.  It is accessed via CNI and so avoids
 417   // ordinary protection mechanisms.
 418   String(gnu.gcj.runtime.StringBuffer buffer)
 419   {
 420     // No need to synchronize or mark the buffer, since we know it is
 421     // only used once.
 422     init (buffer);
 423   }
 424
 425   /**
 426    * Returns the number of characters contained in this String.
 427    *
 428    * @return the length of this String
 429    */
 430   public int length()
 431   {
 432     return count;
 433   }
 434
 435   /**
 436    * Returns the character located at the specified index within this String.
 437    *
 438    * @param index position of character to return (base 0)
 439    * @return character located at position index
 440    * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= length()
 441    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 442    */
 443   public native char charAt(int index);
 444
 445   /**
 446    * Copies characters from this String starting at a specified start index,
 447    * ending at a specified stop index, to a character array starting at
 448    * a specified destination begin index.
 449    *
 450    * @param srcBegin index to begin copying characters from this String
 451    * @param srcEnd index after the last character to be copied from this String
 452    * @param dst character array which this String is copied into
 453    * @param dstBegin index to start writing characters into dst
 454    * @throws NullPointerException if dst is null
 455    * @throws IndexOutOfBoundsException if any indices are out of bounds
 456    *         (while unspecified, source problems cause a
 457    *         StringIndexOutOfBoundsException, and dst problems cause an
 458    *         ArrayIndexOutOfBoundsException)
 459    */
 460   public native void getChars(int srcBegin, int srcEnd,
 461                               char[] dst, int dstBegin);
 462
 463   /**
 464    * Copies the low byte of each character from this String starting at a
 465    * specified start index, ending at a specified stop index, to a byte array
 466    * starting at a specified destination begin index.
 467    *
 468    * @param srcBegin index to being copying characters from this String
 469    * @param srcEnd index after the last character to be copied from this String
 470    * @param dst byte array which each low byte of this String is copied into
 471    * @param dstBegin index to start writing characters into dst
 472    * @throws NullPointerException if dst is null and copy length is non-zero
 473    * @throws IndexOutOfBoundsException if any indices are out of bounds
 474    *         (while unspecified, source problems cause a
 475    *         StringIndexOutOfBoundsException, and dst problems cause an
 476    *         ArrayIndexOutOfBoundsException)
 477    * @see #getBytes()
 478    * @see #getBytes(String)
 479    * @deprecated use {@link #getBytes()}, which uses a char to byte encoder
 480    */
 481   public native void getBytes(int srcBegin, int srcEnd,
 482                               byte[] dst, int dstBegin);
 483
 484   /**
 485    * Converts the Unicode characters in this String to a byte array. Uses the
 486    * specified encoding method, so the result may be longer or shorter than
 487    * the String. For more encoding control, use
 488    * {@link java.nio.charset.CharsetEncoder}, and for valid character sets,
 489    * see {@link java.nio.charset.Charset}. The behavior is not specified if
 490    * the encoder encounters a problem; this implementation returns null.
 491    *
 492    * @param enc encoding name
 493    * @return the resulting byte array, or null on a problem
 494    * @throws NullPointerException if enc is null
 495    * @throws UnsupportedEncodingException if encoding is not supported
 496    * @since 1.1
 497    */
 498   public native byte[] getBytes(String enc)
 499     throws UnsupportedEncodingException;
 500
 501   /**
 502    * Converts the Unicode characters in this String to a byte array. Uses the
 503    * encoding of the platform's default charset, so the result may be longer
 504    * or shorter than the String. For more encoding control, use
 505    * {@link java.nio.charset.CharsetEncoder}.  The behavior is not specified if
 506    * the encoder encounters a problem; this implementation returns null.
 507    *
 508    * @return the resulting byte array, or null on a problem
 509    * @since 1.1
 510    */
 511   public byte[] getBytes()
 512   {
 513     try
 514       {
 515         return getBytes (System.getProperty("file.encoding", "8859_1"));
 516       }
 517     catch (UnsupportedEncodingException x)
 518       {
 519         // This probably shouldn't happen, but could if file.encoding
 520         // is somehow changed to a value we don't understand.
 521         try
 522           {
 523             return getBytes ("8859_1");
 524           }
 525         catch (UnsupportedEncodingException x2)
 526           {
 527             // This really shouldn't happen, because the 8859_1
 528             // encoding should always be available.
 529             throw new InternalError ("couldn't find 8859_1 encoder");
 530           }
 531       }
 532   }
 533
 534   /**
 535    * Predicate which compares anObject to this. This is true only for Strings
 536    * with the same character sequence.
 537    *
 538    * @param anObject the object to compare
 539    * @return true if anObject is semantically equal to this
 540    * @see #compareTo(String)
 541    * @see #equalsIgnoreCase(String)
 542    */
 543   public native boolean equals(Object anObject);
 544
 545   /**
 546    * Compares the given StringBuffer to this String. This is true if the
 547    * StringBuffer has the same content as this String at this moment.
 548    *
 549    * @param buffer the StringBuffer to compare to
 550    * @return true if StringBuffer has the same character sequence
 551    * @throws NullPointerException if the given StringBuffer is null
 552    * @since 1.4
 553    */
 554   public native boolean contentEquals(StringBuffer buffer);
 555
 556   /**
 557    * Compares a String to this String, ignoring case. This does not handle
 558    * multi-character capitalization exceptions; instead the comparison is
 559    * made on a character-by-character basis, and is true if:<br><ul>
 560    * <li><code>c1 == c2</code></li>
 561    * <li><code>Character.toUpperCase(c1)
 562    *     == Character.toUpperCase(c2)</code></li>
 563    * <li><code>Character.toLowerCase(c1)
 564    *     == Character.toLowerCase(c2)</code></li>
 565    * </ul>
 566    *
 567    * @param anotherString String to compare to this String
 568    * @return true if anotherString is equal, ignoring case
 569    * @see #equals(Object)
 570    * @see Character#toUpperCase(char)
 571    * @see Character#toLowerCase(char)
 572    */
 573   public native boolean equalsIgnoreCase(String anotherString);
 574
 575   /**
 576    * Compares this String and another String (case sensitive,
 577    * lexicographically). The result is less than 0 if this string sorts
 578    * before the other, 0 if they are equal, and greater than 0 otherwise.
 579    * After any common starting sequence is skipped, the result is
 580    * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings
 581    * have characters remaining, or
 582    * <code>this.length() - anotherString.length()</code> if one string is
 583    * a subsequence of the other.
 584    *
 585    * @param anotherString the String to compare against
 586    * @return the comparison
 587    * @throws NullPointerException if anotherString is null
 588    */
 589   public native int compareTo(String anotherString);
 590
 591   /**
 592    * Behaves like <code>compareTo(java.lang.String)</code> unless the Object
 593    * is not a <code>String</code>.  Then it throws a
 594    * <code>ClassCastException</code>.
 595    *
 596    * @param o the object to compare against
 597    * @return the comparison
 598    * @throws NullPointerException if o is null
 599    * @throws ClassCastException if o is not a <code>String</code>
 600    * @since 1.2
 601    */
 602   public int compareTo(Object o)
 603   {
 604     return compareTo((String) o);
 605   }
 606
 607   /**
 608    * Compares this String and another String (case insensitive). This
 609    * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores
 610    * locale and multi-characater capitalization, and compares characters
 611    * after performing
 612    * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each
 613    * character of the string. This is unsatisfactory for locale-based
 614    * comparison, in which case you should use {@link java.text.Collator}.
 615    *
 616    * @param str the string to compare against
 617    * @return the comparison
 618    * @see Collator#compare(String, String)
 619    * @since 1.2
 620    */
 621   public int compareToIgnoreCase(String str)
 622   {
 623     return this.toUpperCase().toLowerCase().compareTo(
 624      str.toUpperCase().toLowerCase());
 625   }
 626
 627   /**
 628    * Predicate which determines if this String matches another String
 629    * starting at a specified offset for each String and continuing
 630    * for a specified length. Indices out of bounds are harmless, and give
 631    * a false result.
 632    *
 633    * @param toffset index to start comparison at for this String
 634    * @param other String to compare region to this String
 635    * @param ooffset index to start comparison at for other
 636    * @param len number of characters to compare
 637    * @return true if regions match (case sensitive)
 638    * @throws NullPointerException if other is null
 639    */
 640   public native boolean regionMatches(int toffset,
 641                                       String other, int ooffset, int len);
 642
 643   /**
 644    * Predicate which determines if this String matches another String
 645    * starting at a specified offset for each String and continuing
 646    * for a specified length, optionally ignoring case. Indices out of bounds
 647    * are harmless, and give a false result. Case comparisons are based on
 648    * <code>Character.toLowerCase()</code> and
 649    * <code>Character.toUpperCase()</code>, not on multi-character
 650    * capitalization expansions.
 651    *
 652    * @param ignoreCase true if case should be ignored in comparision
 653    * @param toffset index to start comparison at for this String
 654    * @param other String to compare region to this String
 655    * @param oofset index to start comparison at for other
 656    * @param len number of characters to compare
 657    * @return true if regions match, false otherwise
 658    * @throws NullPointerException if other is null
 659    */
 660   public native boolean regionMatches(boolean ignoreCase, int toffset,
 661                                       String other, int ooffset, int len);
 662
 663   /**
 664    * Predicate which determines if this String contains the given prefix,
 665    * beginning comparison at toffset. The result is false if toffset is
 666    * negative or greater than this.length(), otherwise it is the same as
 667    * <code>this.subString(toffset).startsWith(prefix)</code>.
 668    *
 669    * @param prefix String to compare
 670    * @param toffset offset for this String where comparison starts
 671    * @return true if this String starts with prefix
 672    * @throws NullPointerException if prefix is null
 673    * @see #regionMatches(boolean, int, String, int, int)
 674    */
 675   public native boolean startsWith(String prefix, int toffset);
 676
 677   /**
 678    * Predicate which determines if this String starts with a given prefix.
 679    * If the prefix is an empty String, true is returned.
 680    *
 681    * @param prefix String to compare
 682    * @return true if this String starts with the prefix
 683    * @throws NullPointerException if prefix is null
 684    * @see #startsWith(String, int)
 685    */
 686   public boolean startsWith(String prefix)
 687   {
 688     return startsWith (prefix, 0);
 689   }
 690
 691   /**
 692    * Predicate which determines if this String ends with a given suffix.
 693    * If the suffix is an empty String, true is returned.
 694    *
 695    * @param suffix String to compare
 696    * @return true if this String ends with the suffix
 697    * @throws NullPointerException if suffix is null
 698    * @see #regionMatches(boolean, int, String, int, int)
 699    */
 700   public boolean endsWith(String suffix)
 701   {
 702     return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
 703   }
 704
 705   /**
 706    * Computes the hashcode for this String. This is done with int arithmetic,
 707    * where ** represents exponentiation, by this formula:<br>
 708    * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>.
 709    *
 710    * @return hashcode value of this String
 711    */
 712   public native int hashCode();
 713
 714   /**
 715    * Finds the first instance of a character in this String.
 716    *
 717    * @param ch character to find
 718    * @return location (base 0) of the character, or -1 if not found
 719    */
 720   public int indexOf(int ch)
 721   {
 722     return indexOf(ch, 0);
 723   }
 724
 725   /**
 726    * Finds the first instance of a character in this String, starting at
 727    * a given index.  If starting index is less than 0, the search
 728    * starts at the beginning of this String.  If the starting index
 729    * is greater than the length of this String, -1 is returned.
 730    *
 731    * @param ch character to find
 732    * @param fromIndex index to start the search
 733    * @return location (base 0) of the character, or -1 if not found
 734    */
 735   public native int indexOf(int ch, int fromIndex);
 736
 737   /**
 738    * Finds the last instance of a character in this String.
 739    *
 740    * @param ch character to find
 741    * @return location (base 0) of the character, or -1 if not found
 742    */
 743   public int lastIndexOf(int ch)
 744   {
 745     return lastIndexOf(ch, count - 1);
 746   }
 747
 748   /**
 749    * Finds the last instance of a character in this String, starting at
 750    * a given index.  If starting index is greater than the maximum valid
 751    * index, then the search begins at the end of this String.  If the
 752    * starting index is less than zero, -1 is returned.
 753    *
 754    * @param ch character to find
 755    * @param fromIndex index to start the search
 756    * @return location (base 0) of the character, or -1 if not found
 757    */
 758   public native int lastIndexOf(int ch, int fromIndex);
 759
 760   /**
 761    * Finds the first instance of a String in this String.
 762    *
 763    * @param str String to find
 764    * @return location (base 0) of the String, or -1 if not found
 765    * @throws NullPointerException if str is null
 766    */
 767   public int indexOf(String str)
 768   {
 769     return indexOf(str, 0);
 770   }
 771
 772   /**
 773    * Finds the first instance of a String in this String, starting at
 774    * a given index.  If starting index is less than 0, the search
 775    * starts at the beginning of this String.  If the starting index
 776    * is greater than the length of this String, -1 is returned.
 777    *
 778    * @param str String to find
 779    * @param fromIndex index to start the search
 780    * @return location (base 0) of the String, or -1 if not found
 781    * @throws NullPointerException if str is null
 782    */
 783   public native int indexOf(String str, int fromIndex);
 784
 785   /**
 786    * Finds the last instance of a String in this String.
 787    *
 788    * @param str String to find
 789    * @return location (base 0) of the String, or -1 if not found
 790    * @throws NullPointerException if str is null
 791    */
 792   public int lastIndexOf(String str)
 793   {
 794     return lastIndexOf(str, count - str.count);
 795   }
 796
 797   /**
 798    * Finds the last instance of a String in this String, starting at
 799    * a given index.  If starting index is greater than the maximum valid
 800    * index, then the search begins at the end of this String.  If the
 801    * starting index is less than zero, -1 is returned.
 802    *
 803    * @param str String to find
 804    * @param fromIndex index to start the search
 805    * @return location (base 0) of the String, or -1 if not found
 806    * @throws NullPointerException if str is null
 807    */
 808   public int lastIndexOf(String str, int fromIndex)
 809   {
 810     if (fromIndex >= count)
 811       fromIndex = count - str.count;
 812     for (;; --fromIndex)
 813       {
 814         if (fromIndex < 0)
 815           return -1;
 816         if (startsWith(str, fromIndex))
 817           return fromIndex;
 818       }
 819   }
 820
 821   /**
 822    * Creates a substring of this String, starting at a specified index
 823    * and ending at the end of this String.
 824    *
 825    * @param begin index to start substring (base 0)
 826    * @return new String which is a substring of this String
 827    * @throws IndexOutOfBoundsException if begin &lt; 0 || begin &gt; length()
 828    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 829    */
 830   public String substring(int begin)
 831   {
 832     return substring(begin, count);
 833   }
 834
 835   /**
 836    * Creates a substring of this String, starting at a specified index
 837    * and ending at one character before a specified index.
 838    *
 839    * @param begin index to start substring (inclusive, base 0)
 840    * @param end index to end at (exclusive)
 841    * @return new String which is a substring of this String
 842    * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
 843    *         || begin &gt; end (while unspecified, this is a
 844    *         StringIndexOutOfBoundsException)
 845    */
 846   public native String substring(int begin, int end);
 847
 848   /**
 849    * Creates a substring of this String, starting at a specified index
 850    * and ending at one character before a specified index. This behaves like
 851    * <code>substring(begin, end)</code>.
 852    *
 853    * @param begin index to start substring (inclusive, base 0)
 854    * @param end index to end at (exclusive)
 855    * @return new String which is a substring of this String
 856    * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
 857    *         || begin &gt; end
 858    * @since 1.4
 859    */
 860   public CharSequence subSequence(int begin, int end)
 861   {
 862     return substring(begin, end);
 863   }
 864
 865   /**
 866    * Concatenates a String to this String. This results in a new string unless
 867    * one of the two originals is "".
 868    *
 869    * @param str String to append to this String
 870    * @return newly concatenated String
 871    * @throws NullPointerException if str is null
 872    */
 873   public native String concat(String str);
 874
 875   /**
 876    * Replaces every instance of a character in this String with a new
 877    * character. If no replacements occur, this is returned.
 878    *
 879    * @param oldChar the old character to replace
 880    * @param newChar the new character
 881    * @return new String with all instances of oldChar replaced with newChar
 882    */
 883   public native String replace(char oldChar, char newChar);
 884
 885   /**
 886    * Test if this String matches a regular expression. This is shorthand for
 887    * <code>{@link Pattern}.matches(regex, this)</code>.
 888    *
 889    * @param regex the pattern to match
 890    * @return true if the pattern matches
 891    * @throws NullPointerException if regex is null
 892    * @throws PatternSyntaxException if regex is invalid
 893    * @see Pattern#matches(String, CharSequence)
 894    * @since 1.4
 895    */
 896   public boolean matches(String regex)
 897   {
 898     return Pattern.matches(regex, this);
 899   }
 900
 901   /**
 902    * Replaces the first substring match of the regular expression with a
 903    * given replacement. This is shorthand for <code>{@link Pattern}
 904    *   .compile(regex).matcher(this).replaceFirst(replacement)</code>.
 905    *
 906    * @param regex the pattern to match
 907    * @param replacement the replacement string
 908    * @return the modified string
 909    * @throws NullPointerException if regex or replacement is null
 910    * @throws PatternSyntaxException if regex is invalid
 911    * @see #replaceAll(String, String)
 912    * @see Pattern#compile(String)
 913    * @see Pattern#matcher(CharSequence)
 914    * @see Matcher#replaceFirst(String)
 915    * @since 1.4
 916    */
 917   public String replaceFirst(String regex, String replacement)
 918   {
 919     return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
 920   }
 921
 922   /**
 923    * Replaces all matching substrings of the regular expression with a
 924    * given replacement. This is shorthand for <code>{@link Pattern}
 925    *   .compile(regex).matcher(this).replaceAll(replacement)</code>.
 926    *
 927    * @param regex the pattern to match
 928    * @param replacement the replacement string
 929    * @return the modified string
 930    * @throws NullPointerException if regex or replacement is null
 931    * @throws PatternSyntaxException if regex is invalid
 932    * @see #replaceFirst(String, String)
 933    * @see Pattern#compile(String)
 934    * @see Pattern#matcher(CharSequence)
 935    * @see Matcher#replaceAll(String)
 936    * @since 1.4
 937    */
 938   public String replaceAll(String regex, String replacement)
 939   {
 940     return Pattern.compile(regex).matcher(this).replaceAll(replacement);
 941   }
 942
 943   /**
 944    * Split this string around the matches of a regular expression. Each
 945    * element of the returned array is the largest block of characters not
 946    * terminated by the regular expression, in the order the matches are found.
 947    *
 948    * <p>The limit affects the length of the array. If it is positive, the
 949    * array will contain at most n elements (n - 1 pattern matches). If
 950    * negative, the array length is unlimited, but there can be trailing empty
 951    * entries. if 0, the array length is unlimited, and trailing empty entries
 952    * are discarded.
 953    *
 954    * <p>For example, splitting "boo:and:foo" yields:<br>
 955    * <table border=0>
 956    * <th><td>Regex</td> <td>Limit</td> <td>Result</td></th>
 957    * <tr><td>":"</td>   <td>2</td>  <td>{ "boo", "and:foo" }</td></tr>
 958    * <tr><td>":"</td>   <td>t</td>  <td>{ "boo", "and", "foo" }</td></tr>
 959    * <tr><td>":"</td>   <td>-2</td> <td>{ "boo", "and", "foo" }</td></tr>
 960    * <tr><td>"o"</td>   <td>5</td>  <td>{ "b", "", ":and:f", "", "" }</td></tr>
 961    * <tr><td>"o"</td>   <td>-2</td> <td>{ "b", "", ":and:f", "", "" }</td></tr>
 962    * <tr><td>"o"</td>   <td>0</td>  <td>{ "b", "", ":and:f" }</td></tr>
 963    * </table>
 964    *
 965    * <p>This is shorthand for
 966    * <code>{@link Pattern}.compile(regex).split(this, limit)</code>.
 967    *
 968    * @param regex the pattern to match
 969    * @param limit the limit threshold
 970    * @return the array of split strings
 971    * @throws NullPointerException if regex or replacement is null
 972    * @throws PatternSyntaxException if regex is invalid
 973    * @see Pattern#compile(String)
 974    * @see Pattern#split(CharSequence, int)
 975    * @since 1.4
 976    */
 977   public String[] split(String regex, int limit)
 978   {
 979     return Pattern.compile(regex).split(this, limit);
 980   }
 981
 982   /**
 983    * Split this string around the matches of a regular expression. Each
 984    * element of the returned array is the largest block of characters not
 985    * terminated by the regular expression, in the order the matches are found.
 986    * The array length is unlimited, and trailing empty entries are discarded,
 987    * as though calling <code>split(regex, 0)</code>.
 988    *
 989    * @param regex the pattern to match
 990    * @return the array of split strings
 991    * @throws NullPointerException if regex or replacement is null
 992    * @throws PatternSyntaxException if regex is invalid
 993    * @see #split(String, int)
 994    * @see Pattern#compile(String)
 995    * @see Pattern#split(CharSequence, int)
 996    * @since 1.4
 997    */
 998   public String[] split(String regex)
 999   {
1000     return Pattern.compile(regex).split(this, 0);
1001   }
1002
1003   /**
1004    * Lowercases this String according to a particular locale. This uses
1005    * Unicode's special case mappings, as applied to the given Locale, so the
1006    * resulting string may be a different length.
1007    *
1008    * @param loc locale to use
1009    * @return new lowercased String, or this if no characters were lowercased
1010    * @throws NullPointerException if loc is null
1011    * @see #toUpperCase(Locale)
1012    * @since 1.1
1013    */
1014   public native String toLowerCase(Locale locale);
1015
1016   /**
1017    * Lowercases this String. This uses Unicode's special case mappings, as
1018    * applied to the platform's default Locale, so the resulting string may
1019    * be a different length.
1020    *
1021    * @return new lowercased String, or this if no characters were lowercased
1022    * @see #toLowerCase(Locale)
1023    * @see #toUpperCase()
1024    */
1025   public String toLowerCase()
1026   {
1027     // The JDK is a bit confused about what to do here.  If we pass in
1028     // the default Locale then special Locale handling might be
1029     // invoked.  However, the docs also say that Character.toLowerCase
1030     // rules here.  We go with the latter.
1031     return toLowerCase (null);
1032   }
1033
1034   /**
1035    * Uppercases this String according to a particular locale. This uses
1036    * Unicode's special case mappings, as applied to the given Locale, so the
1037    * resulting string may be a different length.
1038    *
1039    * @param loc locale to use
1040    * @return new uppercased String, or this if no characters were uppercased
1041    * @throws NullPointerException if loc is null
1042    * @see #toLowerCase(Locale)
1043    * @since 1.1
1044    */
1045   public native String toUpperCase(Locale locale);
1046
1047   /**
1048    * Uppercases this String. This uses Unicode's special case mappings, as
1049    * applied to the platform's default Locale, so the resulting string may
1050    * be a different length.
1051    *
1052    * @return new uppercased String, or this if no characters were uppercased
1053    * @see #toUpperCase(Locale)
1054    * @see #toLowerCase()
1055    */
1056   public String toUpperCase()
1057   {
1058     // The JDK is a bit confused about what to do here.  If we pass in
1059     // the default Locale then special Locale handling might be
1060     // invoked.  However, the docs also say that Character.toLowerCase
1061     // rules here.  We go with the latter.
1062     return toUpperCase (null);
1063   }
1064
1065   /**
1066    * Trims all characters less than or equal to <code>'\u0020'</code>
1067    * (<code>' '</code>) from the beginning and end of this String. This
1068    * includes many, but not all, ASCII control characters, and all
1069    * {@link Character#whitespace(char)}.
1070    *
1071    * @return new trimmed String, or this if nothing trimmed
1072    */
1073   public native String trim();
1074
1075   /**
1076    * Returns this, as it is already a String!
1077    *
1078    * @return this
1079    */
1080   public String toString()
1081   {
1082     return this;
1083   }
1084
1085   /**
1086    * Copies the contents of this String into a character array. Subsequent
1087    * changes to the array do not affect the String.
1088    *
1089    * @return character array copying the String
1090    */
1091   public native char[] toCharArray();
1092
1093   /**
1094    * Returns a String representation of an Object. This is "null" if the
1095    * object is null, otherwise it is <code>obj.toString()</code> (which
1096    * can be null).
1097    *
1098    * @param obj the Object
1099    * @return the string conversion of obj
1100    */
1101   public static String valueOf(Object obj)
1102   {
1103     return obj == null ? "null" : obj.toString();
1104   }
1105
1106   /**
1107    * Returns a String representation of a character array. Subsequent
1108    * changes to the array do not affect the String.
1109    *
1110    * @param data the character array
1111    * @return a String containing the same character sequence as data
1112    * @throws NullPointerException if data is null
1113    * @see #valueOf(char[], int, int)
1114    * @see #String(char[])
1115    */
1116   public static String valueOf(char[] data)
1117   {
1118     return valueOf (data, 0, data.length);
1119   }
1120
1121   /**
1122    * Returns a String representing the character sequence of the char array,
1123    * starting at the specified offset, and copying chars up to the specified
1124    * count. Subsequent changes to the array do not affect the String.
1125    *
1126    * @param data character array
1127    * @param offset position (base 0) to start copying out of data
1128    * @param count the number of characters from data to copy
1129    * @return String containing the chars from data[offset..offset+count]
1130    * @throws NullPointerException if data is null
1131    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1132    *         || offset + count &gt; data.length)
1133    *         (while unspecified, this is a StringIndexOutOfBoundsException)
1134    * @see #String(char[], int, int)
1135    */
1136   public static native String valueOf(char[] data, int offset, int count);
1137
1138   /**
1139    * Returns a String representing the character sequence of the char array,
1140    * starting at the specified offset, and copying chars up to the specified
1141    * count. Subsequent changes to the array do not affect the String.
1142    *
1143    * @param data character array
1144    * @param offset position (base 0) to start copying out of data
1145    * @param count the number of characters from data to copy
1146    * @return String containing the chars from data[offset..offset+count]
1147    * @throws NullPointerException if data is null
1148    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1149    *         || offset + count &gt; data.length)
1150    *         (while unspecified, this is a StringIndexOutOfBoundsException)
1151    * @see #String(char[], int, int)
1152    */
1153   public static String copyValueOf(char[] data, int offset, int count)
1154   {
1155     String r = new String ();
1156     r.init(data, offset, count, false);
1157     return r;
1158   }
1159
1160   /**
1161    * Returns a String representation of a character array. Subsequent
1162    * changes to the array do not affect the String.
1163    *
1164    * @param data the character array
1165    * @return a String containing the same character sequence as data
1166    * @throws NullPointerException if data is null
1167    * @see #copyValueOf(char[], int, int)
1168    * @see #String(char[])
1169    */
1170   public static String copyValueOf(char[] data)
1171   {
1172     return copyValueOf (data, 0, data.length);
1173   }
1174
1175   /**
1176    * Returns a String representing a boolean.
1177    *
1178    * @param b the boolean
1179    * @return "true" if b is true, else "false"
1180    */
1181   public static String valueOf(boolean b)
1182   {
1183     return b ? "true" : "false";
1184   }
1185
1186   /**
1187    * Returns a String representing a character.
1188    *
1189    * @param c the character
1190    * @return String containing the single character c
1191    */
1192   public static native String valueOf(char c);
1193
1194   /**
1195    * Returns a String representing an integer.
1196    *
1197    * @param i the integer
1198    * @return String containing the integer in base 10
1199    * @see Integer#toString(int)
1200    */
1201   public static native String valueOf(int i);
1202
1203   /**
1204    * Returns a String representing a long.
1205    *
1206    * @param l the long
1207    * @return String containing the long in base 10
1208    * @see Long#toString(long)
1209    */
1210   public static String valueOf(long l)
1211   {
1212     return Long.toString(l);
1213   }
1214
1215   /**
1216    * Returns a String representing a float.
1217    *
1218    * @param f the float
1219    * @return String containing the float
1220    * @see Float#toString(float)
1221    */
1222   public static String valueOf(float f)
1223   {
1224     return Float.toString(f);
1225   }
1226
1227   /**
1228    * Returns a String representing a double.
1229    *
1230    * @param d the double
1231    * @return String containing the double
1232    * @see Double#toString(double)
1233    */
1234   public static String valueOf(double d)
1235   {
1236     return Double.toString(d);
1237   }
1238
1239   /**
1240    * Fetches this String from the intern hashtable. If two Strings are
1241    * considered equal, by the equals() method, then intern() will return the
1242    * same String instance. ie. if (s1.equals(s2)) then
1243    * (s1.intern() == s2.intern()). All string literals and string-valued
1244    * constant expressions are already interned.
1245    *
1246    * @return the interned String
1247    */
1248   public native String intern();
1249
1250
1251   private native void init(char[] chars, int offset, int count,
1252                            boolean dont_copy);
1253   private native void init(byte[] chars, int hibyte, int offset, int count);
1254   private native void init(byte[] chars, int offset, int count, String enc)
1255     throws UnsupportedEncodingException;
1256   private native void init(gnu.gcj.runtime.StringBuffer buffer);
1257   private static native void rehash();
1258 }