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, 2004, 2005, 2006
   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., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 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    * Creates a new String using the character sequence represented by
 402    * the StringBuilder. Subsequent changes to buf do not affect the String.
 403    *
 404    * @param buffer StringBuilder to copy
 405    * @throws NullPointerException if buffer is null
 406    */
 407   public String(StringBuilder buffer)
 408   {
 409     this(buffer.value, 0, buffer.count);
 410   }
 411
 412   /**
 413    * Special constructor which can share an array when safe to do so.
 414    *
 415    * @param data the characters to copy
 416    * @param offset the location to start from
 417    * @param count the number of characters to use
 418    * @param dont_copy true if the array is trusted, and need not be copied
 419    * @throws NullPointerException if chars is null
 420    * @throws StringIndexOutOfBoundsException if bounds check fails
 421    */
 422   String(char[] data, int offset, int count, boolean dont_copy)
 423   {
 424     init(data, offset, count, dont_copy);
 425   }
 426
 427   // This is used by gnu.gcj.runtime.StringBuffer, so it must have
 428   // package-private protection.  It is accessed via CNI and so avoids
 429   // ordinary protection mechanisms.
 430   String(gnu.gcj.runtime.StringBuffer buffer)
 431   {
 432     // No need to synchronize or mark the buffer, since we know it is
 433     // only used once.
 434     init (buffer);
 435   }
 436
 437   /**
 438    * Returns the number of characters contained in this String.
 439    *
 440    * @return the length of this String
 441    */
 442   public int length()
 443   {
 444     return count;
 445   }
 446
 447   /**
 448    * Returns the character located at the specified index within this String.
 449    *
 450    * @param index position of character to return (base 0)
 451    * @return character located at position index
 452    * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= length()
 453    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 454    */
 455   public native char charAt(int index);
 456
 457   /**
 458    * Get the code point at the specified index.  This is like #charAt(int),
 459    * but if the character is the start of a surrogate pair, and the
 460    * following character completes the pair, then the corresponding
 461    * supplementary code point is returned.
 462    * @param index the index of the codepoint to get, starting at 0
 463    * @return the codepoint at the specified index
 464    * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
 465    * @since 1.5
 466    */
 467   public synchronized int codePointAt(int index)
 468   {
 469     // Use the CharSequence overload as we get better range checking
 470     // this way.
 471     return Character.codePointAt(this, index);
 472   }
 473
 474   /**
 475    * Get the code point before the specified index.  This is like
 476    * #codePointAt(int), but checks the characters at <code>index-1</code> and
 477    * <code>index-2</code> to see if they form a supplementary code point.
 478    * @param index the index just past the codepoint to get, starting at 0
 479    * @return the codepoint at the specified index
 480    * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
 481    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 482    * @since 1.5
 483    */
 484   public synchronized int codePointBefore(int index)
 485   {
 486     // Use the CharSequence overload as we get better range checking
 487     // this way.
 488     return Character.codePointBefore(this, index);
 489   }
 490
 491   /**
 492    * Copies characters from this String starting at a specified start index,
 493    * ending at a specified stop index, to a character array starting at
 494    * a specified destination begin index.
 495    *
 496    * @param srcBegin index to begin copying characters from this String
 497    * @param srcEnd index after the last character to be copied from this String
 498    * @param dst character array which this String is copied into
 499    * @param dstBegin index to start writing characters into dst
 500    * @throws NullPointerException if dst is null
 501    * @throws IndexOutOfBoundsException if any indices are out of bounds
 502    *         (while unspecified, source problems cause a
 503    *         StringIndexOutOfBoundsException, and dst problems cause an
 504    *         ArrayIndexOutOfBoundsException)
 505    */
 506   public native void getChars(int srcBegin, int srcEnd,
 507                               char[] dst, int dstBegin);
 508
 509   /**
 510    * Copies the low byte of each character from this String starting at a
 511    * specified start index, ending at a specified stop index, to a byte array
 512    * starting at a specified destination begin index.
 513    *
 514    * @param srcBegin index to being copying characters from this String
 515    * @param srcEnd index after the last character to be copied from this String
 516    * @param dst byte array which each low byte of this String is copied into
 517    * @param dstBegin index to start writing characters into dst
 518    * @throws NullPointerException if dst is null and copy length is non-zero
 519    * @throws IndexOutOfBoundsException if any indices are out of bounds
 520    *         (while unspecified, source problems cause a
 521    *         StringIndexOutOfBoundsException, and dst problems cause an
 522    *         ArrayIndexOutOfBoundsException)
 523    * @see #getBytes()
 524    * @see #getBytes(String)
 525    * @deprecated use {@link #getBytes()}, which uses a char to byte encoder
 526    */
 527   public native void getBytes(int srcBegin, int srcEnd,
 528                               byte[] dst, int dstBegin);
 529
 530   /**
 531    * Converts the Unicode characters in this String to a byte array. Uses the
 532    * specified encoding method, so the result may be longer or shorter than
 533    * the String. For more encoding control, use
 534    * {@link java.nio.charset.CharsetEncoder}, and for valid character sets,
 535    * see {@link java.nio.charset.Charset}. The behavior is not specified if
 536    * the encoder encounters a problem; this implementation returns null.
 537    *
 538    * @param enc encoding name
 539    * @return the resulting byte array, or null on a problem
 540    * @throws NullPointerException if enc is null
 541    * @throws UnsupportedEncodingException if encoding is not supported
 542    * @since 1.1
 543    */
 544   public native byte[] getBytes(String enc)
 545     throws UnsupportedEncodingException;
 546
 547   /**
 548    * Converts the Unicode characters in this String to a byte array. Uses the
 549    * encoding of the platform's default charset, so the result may be longer
 550    * or shorter than the String. For more encoding control, use
 551    * {@link java.nio.charset.CharsetEncoder}.  The behavior is not specified if
 552    * the encoder encounters a problem; this implementation returns null.
 553    *
 554    * @return the resulting byte array, or null on a problem
 555    * @since 1.1
 556    */
 557   public byte[] getBytes()
 558   {
 559     try
 560       {
 561         return getBytes (System.getProperty("file.encoding", "8859_1"));
 562       }
 563     catch (UnsupportedEncodingException x)
 564       {
 565         // This probably shouldn't happen, but could if file.encoding
 566         // is somehow changed to a value we don't understand.
 567         try
 568           {
 569             return getBytes ("8859_1");
 570           }
 571         catch (UnsupportedEncodingException x2)
 572           {
 573             // This really shouldn't happen, because the 8859_1
 574             // encoding should always be available.
 575             throw new InternalError ("couldn't find 8859_1 encoder");
 576           }
 577       }
 578   }
 579
 580   /**
 581    * Predicate which compares anObject to this. This is true only for Strings
 582    * with the same character sequence.
 583    *
 584    * @param anObject the object to compare
 585    * @return true if anObject is semantically equal to this
 586    * @see #compareTo(String)
 587    * @see #equalsIgnoreCase(String)
 588    */
 589   public native boolean equals(Object anObject);
 590
 591   /**
 592    * Compares the given StringBuffer to this String. This is true if the
 593    * StringBuffer has the same content as this String at this moment.
 594    *
 595    * @param buffer the StringBuffer to compare to
 596    * @return true if StringBuffer has the same character sequence
 597    * @throws NullPointerException if the given StringBuffer is null
 598    * @since 1.4
 599    */
 600   public native boolean contentEquals(StringBuffer buffer);
 601
 602   /**
 603    * Compares the given CharSequence to this String. This is true if
 604    * the CharSequence has the same content as this String at this
 605    * moment.
 606    *
 607    * @param seq the CharSequence to compare to
 608    * @return true if CharSequence has the same character sequence
 609    * @throws NullPointerException if the given CharSequence is null
 610    * @since 1.5
 611    */
 612   public native boolean contentEquals(CharSequence seq);
 613
 614   /**
 615    * Compares a String to this String, ignoring case. This does not handle
 616    * multi-character capitalization exceptions; instead the comparison is
 617    * made on a character-by-character basis, and is true if:<br><ul>
 618    * <li><code>c1 == c2</code></li>
 619    * <li><code>Character.toUpperCase(c1)
 620    *     == Character.toUpperCase(c2)</code></li>
 621    * <li><code>Character.toLowerCase(c1)
 622    *     == Character.toLowerCase(c2)</code></li>
 623    * </ul>
 624    *
 625    * @param anotherString String to compare to this String
 626    * @return true if anotherString is equal, ignoring case
 627    * @see #equals(Object)
 628    * @see Character#toUpperCase(char)
 629    * @see Character#toLowerCase(char)
 630    */
 631   public native boolean equalsIgnoreCase(String anotherString);
 632
 633   /**
 634    * Compares this String and another String (case sensitive,
 635    * lexicographically). The result is less than 0 if this string sorts
 636    * before the other, 0 if they are equal, and greater than 0 otherwise.
 637    * After any common starting sequence is skipped, the result is
 638    * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings
 639    * have characters remaining, or
 640    * <code>this.length() - anotherString.length()</code> if one string is
 641    * a subsequence of the other.
 642    *
 643    * @param anotherString the String to compare against
 644    * @return the comparison
 645    * @throws NullPointerException if anotherString is null
 646    */
 647   public native int compareTo(String anotherString);
 648
 649   /**
 650    * Behaves like <code>compareTo(java.lang.String)</code> unless the Object
 651    * is not a <code>String</code>.  Then it throws a
 652    * <code>ClassCastException</code>.
 653    *
 654    * @param o the object to compare against
 655    * @return the comparison
 656    * @throws NullPointerException if o is null
 657    * @throws ClassCastException if o is not a <code>String</code>
 658    * @since 1.2
 659    */
 660   public int compareTo(Object o)
 661   {
 662     return compareTo((String) o);
 663   }
 664
 665   /**
 666    * Compares this String and another String (case insensitive). This
 667    * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores
 668    * locale and multi-characater capitalization, and compares characters
 669    * after performing
 670    * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each
 671    * character of the string. This is unsatisfactory for locale-based
 672    * comparison, in which case you should use {@link java.text.Collator}.
 673    *
 674    * @param str the string to compare against
 675    * @return the comparison
 676    * @see Collator#compare(String, String)
 677    * @since 1.2
 678    */
 679   public int compareToIgnoreCase(String str)
 680   {
 681     return this.toUpperCase().toLowerCase().compareTo(
 682      str.toUpperCase().toLowerCase());
 683   }
 684
 685   /**
 686    * Predicate which determines if this String matches another String
 687    * starting at a specified offset for each String and continuing
 688    * for a specified length. Indices out of bounds are harmless, and give
 689    * a false result.
 690    *
 691    * @param toffset index to start comparison at for this String
 692    * @param other String to compare region to this String
 693    * @param ooffset index to start comparison at for other
 694    * @param len number of characters to compare
 695    * @return true if regions match (case sensitive)
 696    * @throws NullPointerException if other is null
 697    */
 698   public native boolean regionMatches(int toffset,
 699                                       String other, int ooffset, int len);
 700
 701   /**
 702    * Predicate which determines if this String matches another String
 703    * starting at a specified offset for each String and continuing
 704    * for a specified length, optionally ignoring case. Indices out of bounds
 705    * are harmless, and give a false result. Case comparisons are based on
 706    * <code>Character.toLowerCase()</code> and
 707    * <code>Character.toUpperCase()</code>, not on multi-character
 708    * capitalization expansions.
 709    *
 710    * @param ignoreCase true if case should be ignored in comparision
 711    * @param toffset index to start comparison at for this String
 712    * @param other String to compare region to this String
 713    * @param oofset index to start comparison at for other
 714    * @param len number of characters to compare
 715    * @return true if regions match, false otherwise
 716    * @throws NullPointerException if other is null
 717    */
 718   public native boolean regionMatches(boolean ignoreCase, int toffset,
 719                                       String other, int ooffset, int len);
 720
 721   /**
 722    * Predicate which determines if this String contains the given prefix,
 723    * beginning comparison at toffset. The result is false if toffset is
 724    * negative or greater than this.length(), otherwise it is the same as
 725    * <code>this.substring(toffset).startsWith(prefix)</code>.
 726    *
 727    * @param prefix String to compare
 728    * @param toffset offset for this String where comparison starts
 729    * @return true if this String starts with prefix
 730    * @throws NullPointerException if prefix is null
 731    * @see #regionMatches(boolean, int, String, int, int)
 732    */
 733   public native boolean startsWith(String prefix, int toffset);
 734
 735   /**
 736    * Predicate which determines if this String starts with a given prefix.
 737    * If the prefix is an empty String, true is returned.
 738    *
 739    * @param prefix String to compare
 740    * @return true if this String starts with the prefix
 741    * @throws NullPointerException if prefix is null
 742    * @see #startsWith(String, int)
 743    */
 744   public boolean startsWith(String prefix)
 745   {
 746     return startsWith (prefix, 0);
 747   }
 748
 749   /**
 750    * Predicate which determines if this String ends with a given suffix.
 751    * If the suffix is an empty String, true is returned.
 752    *
 753    * @param suffix String to compare
 754    * @return true if this String ends with the suffix
 755    * @throws NullPointerException if suffix is null
 756    * @see #regionMatches(boolean, int, String, int, int)
 757    */
 758   public boolean endsWith(String suffix)
 759   {
 760     return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
 761   }
 762
 763   /**
 764    * Computes the hashcode for this String. This is done with int arithmetic,
 765    * where ** represents exponentiation, by this formula:<br>
 766    * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>.
 767    *
 768    * @return hashcode value of this String
 769    */
 770   public native int hashCode();
 771
 772   /**
 773    * Finds the first instance of a character in this String.
 774    *
 775    * @param ch character to find
 776    * @return location (base 0) of the character, or -1 if not found
 777    */
 778   public int indexOf(int ch)
 779   {
 780     return indexOf(ch, 0);
 781   }
 782
 783   /**
 784    * Finds the first instance of a character in this String, starting at
 785    * a given index.  If starting index is less than 0, the search
 786    * starts at the beginning of this String.  If the starting index
 787    * is greater than the length of this String, -1 is returned.
 788    *
 789    * @param ch character to find
 790    * @param fromIndex index to start the search
 791    * @return location (base 0) of the character, or -1 if not found
 792    */
 793   public native int indexOf(int ch, int fromIndex);
 794
 795   /**
 796    * Finds the last instance of a character in this String.
 797    *
 798    * @param ch character to find
 799    * @return location (base 0) of the character, or -1 if not found
 800    */
 801   public int lastIndexOf(int ch)
 802   {
 803     return lastIndexOf(ch, count - 1);
 804   }
 805
 806   /**
 807    * Finds the last instance of a character in this String, starting at
 808    * a given index.  If starting index is greater than the maximum valid
 809    * index, then the search begins at the end of this String.  If the
 810    * starting index is less than zero, -1 is returned.
 811    *
 812    * @param ch character to find
 813    * @param fromIndex index to start the search
 814    * @return location (base 0) of the character, or -1 if not found
 815    */
 816   public native int lastIndexOf(int ch, int fromIndex);
 817
 818   /**
 819    * Finds the first instance of a String in this String.
 820    *
 821    * @param str String to find
 822    * @return location (base 0) of the String, or -1 if not found
 823    * @throws NullPointerException if str is null
 824    */
 825   public int indexOf(String str)
 826   {
 827     return indexOf(str, 0);
 828   }
 829
 830   /**
 831    * Finds the first instance of a String in this String, starting at
 832    * a given index.  If starting index is less than 0, the search
 833    * starts at the beginning of this String.  If the starting index
 834    * is greater than the length of this String, -1 is returned.
 835    *
 836    * @param str String to find
 837    * @param fromIndex index to start the search
 838    * @return location (base 0) of the String, or -1 if not found
 839    * @throws NullPointerException if str is null
 840    */
 841   public native int indexOf(String str, int fromIndex);
 842
 843   /**
 844    * Finds the last instance of a String in this String.
 845    *
 846    * @param str String to find
 847    * @return location (base 0) of the String, or -1 if not found
 848    * @throws NullPointerException if str is null
 849    */
 850   public int lastIndexOf(String str)
 851   {
 852     return lastIndexOf(str, count - str.count);
 853   }
 854
 855   /**
 856    * Finds the last instance of a String in this String, starting at
 857    * a given index.  If starting index is greater than the maximum valid
 858    * index, then the search begins at the end of this String.  If the
 859    * starting index is less than zero, -1 is returned.
 860    *
 861    * @param str String to find
 862    * @param fromIndex index to start the search
 863    * @return location (base 0) of the String, or -1 if not found
 864    * @throws NullPointerException if str is null
 865    */
 866   public int lastIndexOf(String str, int fromIndex)
 867   {
 868     if (fromIndex >= count)
 869       fromIndex = count - str.count;
 870     for (;; --fromIndex)
 871       {
 872         if (fromIndex < 0)
 873           return -1;
 874         if (startsWith(str, fromIndex))
 875           return fromIndex;
 876       }
 877   }
 878
 879   /**
 880    * Creates a substring of this String, starting at a specified index
 881    * and ending at the end of this String.
 882    *
 883    * @param begin index to start substring (base 0)
 884    * @return new String which is a substring of this String
 885    * @throws IndexOutOfBoundsException if begin &lt; 0 || begin &gt; length()
 886    *         (while unspecified, this is a StringIndexOutOfBoundsException)
 887    */
 888   public String substring(int begin)
 889   {
 890     return substring(begin, count);
 891   }
 892
 893   /**
 894    * Creates a substring of this String, starting at a specified index
 895    * and ending at one character before a specified index.
 896    *
 897    * @param begin index to start substring (inclusive, base 0)
 898    * @param end index to end at (exclusive)
 899    * @return new String which is a substring of this String
 900    * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
 901    *         || begin &gt; end (while unspecified, this is a
 902    *         StringIndexOutOfBoundsException)
 903    */
 904   public native String substring(int begin, int end);
 905
 906   /**
 907    * Creates a substring of this String, starting at a specified index
 908    * and ending at one character before a specified index. This behaves like
 909    * <code>substring(begin, end)</code>.
 910    *
 911    * @param begin index to start substring (inclusive, base 0)
 912    * @param end index to end at (exclusive)
 913    * @return new String which is a substring of this String
 914    * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
 915    *         || begin &gt; end
 916    * @since 1.4
 917    */
 918   public CharSequence subSequence(int begin, int end)
 919   {
 920     return substring(begin, end);
 921   }
 922
 923   /**
 924    * Concatenates a String to this String. This results in a new string unless
 925    * one of the two originals is "".
 926    *
 927    * @param str String to append to this String
 928    * @return newly concatenated String
 929    * @throws NullPointerException if str is null
 930    */
 931   public native String concat(String str);
 932
 933   /**
 934    * Replaces every instance of a character in this String with a new
 935    * character. If no replacements occur, this is returned.
 936    *
 937    * @param oldChar the old character to replace
 938    * @param newChar the new character
 939    * @return new String with all instances of oldChar replaced with newChar
 940    */
 941   public native String replace(char oldChar, char newChar);
 942
 943   /**
 944    * Test if this String matches a regular expression. This is shorthand for
 945    * <code>{@link Pattern}.matches(regex, this)</code>.
 946    *
 947    * @param regex the pattern to match
 948    * @return true if the pattern matches
 949    * @throws NullPointerException if regex is null
 950    * @throws PatternSyntaxException if regex is invalid
 951    * @see Pattern#matches(String, CharSequence)
 952    * @since 1.4
 953    */
 954   public boolean matches(String regex)
 955   {
 956     return Pattern.matches(regex, this);
 957   }
 958
 959   /**
 960    * Replaces the first substring match of the regular expression with a
 961    * given replacement. This is shorthand for <code>{@link Pattern}
 962    *   .compile(regex).matcher(this).replaceFirst(replacement)</code>.
 963    *
 964    * @param regex the pattern to match
 965    * @param replacement the replacement string
 966    * @return the modified string
 967    * @throws NullPointerException if regex or replacement is null
 968    * @throws PatternSyntaxException if regex is invalid
 969    * @see #replaceAll(String, String)
 970    * @see Pattern#compile(String)
 971    * @see Pattern#matcher(CharSequence)
 972    * @see Matcher#replaceFirst(String)
 973    * @since 1.4
 974    */
 975   public String replaceFirst(String regex, String replacement)
 976   {
 977     return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
 978   }
 979
 980   /**
 981    * Replaces all matching substrings of the regular expression with a
 982    * given replacement. This is shorthand for <code>{@link Pattern}
 983    *   .compile(regex).matcher(this).replaceAll(replacement)</code>.
 984    *
 985    * @param regex the pattern to match
 986    * @param replacement the replacement string
 987    * @return the modified string
 988    * @throws NullPointerException if regex or replacement is null
 989    * @throws PatternSyntaxException if regex is invalid
 990    * @see #replaceFirst(String, String)
 991    * @see Pattern#compile(String)
 992    * @see Pattern#matcher(CharSequence)
 993    * @see Matcher#replaceAll(String)
 994    * @since 1.4
 995    */
 996   public String replaceAll(String regex, String replacement)
 997   {
 998     return Pattern.compile(regex).matcher(this).replaceAll(replacement);
 999   }
1000
1001   /**
1002    * Split this string around the matches of a regular expression. Each
1003    * element of the returned array is the largest block of characters not
1004    * terminated by the regular expression, in the order the matches are found.
1005    *
1006    * <p>The limit affects the length of the array. If it is positive, the
1007    * array will contain at most n elements (n - 1 pattern matches). If
1008    * negative, the array length is unlimited, but there can be trailing empty
1009    * entries. if 0, the array length is unlimited, and trailing empty entries
1010    * are discarded.
1011    *
1012    * <p>For example, splitting "boo:and:foo" yields:<br>
1013    * <table border=0>
1014    * <th><td>Regex</td> <td>Limit</td> <td>Result</td></th>
1015    * <tr><td>":"</td>   <td>2</td>  <td>{ "boo", "and:foo" }</td></tr>
1016    * <tr><td>":"</td>   <td>t</td>  <td>{ "boo", "and", "foo" }</td></tr>
1017    * <tr><td>":"</td>   <td>-2</td> <td>{ "boo", "and", "foo" }</td></tr>
1018    * <tr><td>"o"</td>   <td>5</td>  <td>{ "b", "", ":and:f", "", "" }</td></tr>
1019    * <tr><td>"o"</td>   <td>-2</td> <td>{ "b", "", ":and:f", "", "" }</td></tr>
1020    * <tr><td>"o"</td>   <td>0</td>  <td>{ "b", "", ":and:f" }</td></tr>
1021    * </table>
1022    *
1023    * <p>This is shorthand for
1024    * <code>{@link Pattern}.compile(regex).split(this, limit)</code>.
1025    *
1026    * @param regex the pattern to match
1027    * @param limit the limit threshold
1028    * @return the array of split strings
1029    * @throws NullPointerException if regex or replacement is null
1030    * @throws PatternSyntaxException if regex is invalid
1031    * @see Pattern#compile(String)
1032    * @see Pattern#split(CharSequence, int)
1033    * @since 1.4
1034    */
1035   public String[] split(String regex, int limit)
1036   {
1037     return Pattern.compile(regex).split(this, limit);
1038   }
1039
1040   /**
1041    * Split this string around the matches of a regular expression. Each
1042    * element of the returned array is the largest block of characters not
1043    * terminated by the regular expression, in the order the matches are found.
1044    * The array length is unlimited, and trailing empty entries are discarded,
1045    * as though calling <code>split(regex, 0)</code>.
1046    *
1047    * @param regex the pattern to match
1048    * @return the array of split strings
1049    * @throws NullPointerException if regex or replacement is null
1050    * @throws PatternSyntaxException if regex is invalid
1051    * @see #split(String, int)
1052    * @see Pattern#compile(String)
1053    * @see Pattern#split(CharSequence, int)
1054    * @since 1.4
1055    */
1056   public String[] split(String regex)
1057   {
1058     return Pattern.compile(regex).split(this, 0);
1059   }
1060
1061   /**
1062    * Lowercases this String according to a particular locale. This uses
1063    * Unicode's special case mappings, as applied to the given Locale, so the
1064    * resulting string may be a different length.
1065    *
1066    * @param loc locale to use
1067    * @return new lowercased String, or this if no characters were lowercased
1068    * @throws NullPointerException if loc is null
1069    * @see #toUpperCase(Locale)
1070    * @since 1.1
1071    */
1072   public native String toLowerCase(Locale locale);
1073
1074   /**
1075    * Lowercases this String. This uses Unicode's special case mappings, as
1076    * applied to the platform's default Locale, so the resulting string may
1077    * be a different length.
1078    *
1079    * @return new lowercased String, or this if no characters were lowercased
1080    * @see #toLowerCase(Locale)
1081    * @see #toUpperCase()
1082    */
1083   public String toLowerCase()
1084   {
1085     // The JDK is a bit confused about what to do here.  If we pass in
1086     // the default Locale then special Locale handling might be
1087     // invoked.  However, the docs also say that Character.toLowerCase
1088     // rules here.  We go with the latter.
1089     return toLowerCase (null);
1090   }
1091
1092   /**
1093    * Uppercases this String according to a particular locale. This uses
1094    * Unicode's special case mappings, as applied to the given Locale, so the
1095    * resulting string may be a different length.
1096    *
1097    * @param loc locale to use
1098    * @return new uppercased String, or this if no characters were uppercased
1099    * @throws NullPointerException if loc is null
1100    * @see #toLowerCase(Locale)
1101    * @since 1.1
1102    */
1103   public native String toUpperCase(Locale locale);
1104
1105   /**
1106    * Uppercases this String. This uses Unicode's special case mappings, as
1107    * applied to the platform's default Locale, so the resulting string may
1108    * be a different length.
1109    *
1110    * @return new uppercased String, or this if no characters were uppercased
1111    * @see #toUpperCase(Locale)
1112    * @see #toLowerCase()
1113    */
1114   public String toUpperCase()
1115   {
1116     // The JDK is a bit confused about what to do here.  If we pass in
1117     // the default Locale then special Locale handling might be
1118     // invoked.  However, the docs also say that Character.toLowerCase
1119     // rules here.  We go with the latter.
1120     return toUpperCase (null);
1121   }
1122
1123   /**
1124    * Trims all characters less than or equal to <code>'\u0020'</code>
1125    * (<code>' '</code>) from the beginning and end of this String. This
1126    * includes many, but not all, ASCII control characters, and all
1127    * {@link Character#whitespace(char)}.
1128    *
1129    * @return new trimmed String, or this if nothing trimmed
1130    */
1131   public native String trim();
1132
1133   /**
1134    * Returns this, as it is already a String!
1135    *
1136    * @return this
1137    */
1138   public String toString()
1139   {
1140     return this;
1141   }
1142
1143   /**
1144    * Copies the contents of this String into a character array. Subsequent
1145    * changes to the array do not affect the String.
1146    *
1147    * @return character array copying the String
1148    */
1149   public native char[] toCharArray();
1150
1151   /**
1152    * Returns a String representation of an Object. This is "null" if the
1153    * object is null, otherwise it is <code>obj.toString()</code> (which
1154    * can be null).
1155    *
1156    * @param obj the Object
1157    * @return the string conversion of obj
1158    */
1159   public static String valueOf(Object obj)
1160   {
1161     return obj == null ? "null" : obj.toString();
1162   }
1163
1164   /**
1165    * Returns a String representation of a character array. Subsequent
1166    * changes to the array do not affect the String.
1167    *
1168    * @param data the character array
1169    * @return a String containing the same character sequence as data
1170    * @throws NullPointerException if data is null
1171    * @see #valueOf(char[], int, int)
1172    * @see #String(char[])
1173    */
1174   public static String valueOf(char[] data)
1175   {
1176     return valueOf (data, 0, data.length);
1177   }
1178
1179   /**
1180    * Returns a String representing the character sequence of the char array,
1181    * starting at the specified offset, and copying chars up to the specified
1182    * count. Subsequent changes to the array do not affect the String.
1183    *
1184    * @param data character array
1185    * @param offset position (base 0) to start copying out of data
1186    * @param count the number of characters from data to copy
1187    * @return String containing the chars from data[offset..offset+count]
1188    * @throws NullPointerException if data is null
1189    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1190    *         || offset + count &gt; data.length)
1191    *         (while unspecified, this is a StringIndexOutOfBoundsException)
1192    * @see #String(char[], int, int)
1193    */
1194   public static native String valueOf(char[] data, int offset, int count);
1195
1196   /**
1197    * Returns a String representing the character sequence of the char array,
1198    * starting at the specified offset, and copying chars up to the specified
1199    * count. Subsequent changes to the array do not affect the String.
1200    *
1201    * @param data character array
1202    * @param offset position (base 0) to start copying out of data
1203    * @param count the number of characters from data to copy
1204    * @return String containing the chars from data[offset..offset+count]
1205    * @throws NullPointerException if data is null
1206    * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1207    *         || offset + count &gt; data.length)
1208    *         (while unspecified, this is a StringIndexOutOfBoundsException)
1209    * @see #String(char[], int, int)
1210    */
1211   public static String copyValueOf(char[] data, int offset, int count)
1212   {
1213     String r = new String ();
1214     r.init(data, offset, count, false);
1215     return r;
1216   }
1217
1218   /**
1219    * Returns a String representation of a character array. Subsequent
1220    * changes to the array do not affect the String.
1221    *
1222    * @param data the character array
1223    * @return a String containing the same character sequence as data
1224    * @throws NullPointerException if data is null
1225    * @see #copyValueOf(char[], int, int)
1226    * @see #String(char[])
1227    */
1228   public static String copyValueOf(char[] data)
1229   {
1230     return copyValueOf (data, 0, data.length);
1231   }
1232
1233   /**
1234    * Returns a String representing a boolean.
1235    *
1236    * @param b the boolean
1237    * @return "true" if b is true, else "false"
1238    */
1239   public static String valueOf(boolean b)
1240   {
1241     return b ? "true" : "false";
1242   }
1243
1244   /**
1245    * Returns a String representing a character.
1246    *
1247    * @param c the character
1248    * @return String containing the single character c
1249    */
1250   public static native String valueOf(char c);
1251
1252   /**
1253    * Returns a String representing an integer.
1254    *
1255    * @param i the integer
1256    * @return String containing the integer in base 10
1257    * @see Integer#toString(int)
1258    */
1259   public static native String valueOf(int i);
1260
1261   /**
1262    * Returns a String representing a long.
1263    *
1264    * @param l the long
1265    * @return String containing the long in base 10
1266    * @see Long#toString(long)
1267    */
1268   public static String valueOf(long l)
1269   {
1270     return Long.toString(l);
1271   }
1272
1273   /**
1274    * Returns a String representing a float.
1275    *
1276    * @param f the float
1277    * @return String containing the float
1278    * @see Float#toString(float)
1279    */
1280   public static String valueOf(float f)
1281   {
1282     return Float.toString(f);
1283   }
1284
1285   /**
1286    * Returns a String representing a double.
1287    *
1288    * @param d the double
1289    * @return String containing the double
1290    * @see Double#toString(double)
1291    */
1292   public static String valueOf(double d)
1293   {
1294     return Double.toString(d);
1295   }
1296
1297   /**
1298    * Fetches this String from the intern hashtable. If two Strings are
1299    * considered equal, by the equals() method, then intern() will return the
1300    * same String instance. ie. if (s1.equals(s2)) then
1301    * (s1.intern() == s2.intern()). All string literals and string-valued
1302    * constant expressions are already interned.
1303    *
1304    * @return the interned String
1305    */
1306   public native String intern();
1307
1308   /**
1309    * Return the number of code points between two indices in the
1310    * <code>String</code>.  An unpaired surrogate counts as a
1311    * code point for this purpose.  Characters outside the indicated
1312    * range are not examined, even if the range ends in the middle of a
1313    * surrogate pair.
1314    *
1315    * @param start the starting index
1316    * @param end one past the ending index
1317    * @return the number of code points
1318    * @since 1.5
1319    */
1320   public synchronized int codePointCount(int start, int end)
1321   {
1322     if (start < 0 || end > count || start > end)
1323       throw new StringIndexOutOfBoundsException();
1324
1325     int count = 0;
1326     while (start < end)
1327       {
1328         char base = charAt(start);
1329         if (base < Character.MIN_HIGH_SURROGATE
1330             || base > Character.MAX_HIGH_SURROGATE
1331             || start == end
1332             || start == count
1333             || charAt(start + 1) < Character.MIN_LOW_SURROGATE
1334             || charAt(start + 1) > Character.MAX_LOW_SURROGATE)
1335           {
1336             // Nothing.
1337           }
1338         else
1339           {
1340             // Surrogate pair.
1341             ++start;
1342           }
1343         ++start;
1344         ++count;
1345       }
1346     return count;
1347   }
1348
1349   /**
1350    * Returns true iff this String contains the sequence of Characters
1351    * described in s.
1352    * @param s the CharSequence
1353    * @return true iff this String contains s
1354    *
1355    * @since 1.5
1356    */
1357   public boolean contains (CharSequence s)
1358   {
1359     return this.indexOf(s.toString()) != -1;
1360   }
1361
1362   /**
1363    * Returns a string that is this string with all instances of the sequence
1364    * represented by <code>target</code> replaced by the sequence in
1365    * <code>replacement</code>.
1366    * @param target the sequence to be replaced
1367    * @param replacement the sequence used as the replacement
1368    * @return the string constructed as above
1369    */
1370   public String replace (CharSequence target, CharSequence replacement)
1371   {
1372     String targetString = target.toString();
1373     String replaceString = replacement.toString();
1374     int targetLength = target.length();
1375     int replaceLength = replacement.length();
1376
1377     int startPos = this.indexOf(targetString);
1378     StringBuilder result = new StringBuilder(this);
1379     while (startPos != -1)
1380       {
1381         // Replace the target with the replacement
1382         result.replace(startPos, startPos + targetLength, replaceString);
1383
1384         // Search for a new occurrence of the target
1385         startPos = result.indexOf(targetString, startPos + replaceLength);
1386       }
1387     return result.toString();
1388   }
1389
1390
1391   private native void init(char[] chars, int offset, int count,
1392                            boolean dont_copy);
1393   private native void init(byte[] chars, int hibyte, int offset, int count);
1394   private native void init(byte[] chars, int offset, int count, String enc)
1395     throws UnsupportedEncodingException;
1396   private native void init(gnu.gcj.runtime.StringBuffer buffer);
1397 }