001    /* String.java -- immutable character sequences; the object of string literals
002       Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
003       Free Software Foundation, Inc.
004    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    
040    package java.lang;
041    
042    import java.io.Serializable;
043    import java.io.UnsupportedEncodingException;
044    import java.util.Comparator;
045    import java.text.Collator;
046    import java.util.Formatter;
047    import java.util.Locale;
048    import java.util.regex.Matcher;
049    import java.util.regex.Pattern;
050    import java.util.regex.PatternSyntaxException;
051    
052    /**
053     * Strings represent an immutable set of characters.  All String literals
054     * are instances of this class, and two string literals with the same contents
055     * refer to the same String object.
056     *
057     * <p>This class also includes a number of methods for manipulating the
058     * contents of strings (of course, creating a new object if there are any
059     * changes, as String is immutable). Case mapping relies on Unicode 3.0.0
060     * standards, where some character sequences have a different number of
061     * characters in the uppercase version than the lower case.
062     *
063     * <p>Strings are special, in that they are the only object with an overloaded
064     * operator. When you use '+' with at least one String argument, both
065     * arguments have String conversion performed on them, and another String (not
066     * guaranteed to be unique) results.
067     *
068     * <p>String is special-cased when doing data serialization - rather than
069     * listing the fields of this class, a String object is converted to a string
070     * literal in the object stream.
071     *
072     * @author Paul N. Fisher
073     * @author Eric Blake (ebb9@email.byu.edu)
074     * @author Per Bothner (bothner@cygnus.com)
075     * @author Tom Tromey (tromey@redhat.com)
076     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
077     * @since 1.0
078     * @status updated to 1.4
079     */
080    public final class String
081      implements Serializable, Comparable<String>, CharSequence
082    {
083      // WARNING: String is a CORE class in the bootstrap cycle. See the comments
084      // in vm/reference/java/lang/Runtime for implications of this fact.
085    
086      /**
087       * This is probably not necessary because this class is special cased already
088       * but it will avoid showing up as a discrepancy when comparing SUIDs.
089       */
090      private static final long serialVersionUID = -6849794470754667710L;
091    
092      /**
093       * This is the object that holds the characters that make up the
094       * String.  It might be a char[], or it could be String.  It could
095       * even be `this'.  The actual characters can't be located using
096       * pure Java code.
097       * @see #boffset
098       */
099      private Object data;
100    
101      /**
102       * This is a <emph>byte</emph> offset of the actual characters from
103       * the start of the character-holding object.  Don't use this field
104       * in Java code.
105       */
106      private int boffset;
107    
108      /**
109       * Holds the number of characters in value.  Package visible for use
110       * by trusted code.
111       */
112      int count;
113    
114      /**
115       * Caches the result of hashCode().  If this value is zero, the hashcode
116       * is considered uncached (even if 0 is the correct hash value).
117       */
118      private int cachedHashCode;
119    
120      /**
121       * An implementation for {@link #CASE_INSENSITIVE_ORDER}.
122       * This must be {@link Serializable}. The class name is dictated by
123       * compatibility with Sun's JDK.
124       */
125      private static final class CaseInsensitiveComparator
126        implements Comparator<String>, Serializable
127      {
128        /**
129         * Compatible with JDK 1.2.
130         */
131        private static final long serialVersionUID = 8575799808933029326L;
132    
133        /**
134         * The default private constructor generates unnecessary overhead.
135         */
136        CaseInsensitiveComparator() {}
137    
138        /**
139         * Compares to Strings, using
140         * <code>String.compareToIgnoreCase(String)</code>.
141         *
142         * @param o1 the first string
143         * @param o2 the second string
144         * @return &lt; 0, 0, or &gt; 0 depending on the case-insensitive
145         *         comparison of the two strings.
146         * @throws NullPointerException if either argument is null
147         * @throws ClassCastException if either argument is not a String
148         * @see #compareToIgnoreCase(String)
149         */
150        public int compare(String o1, String o2)
151        {
152          return o1.compareToIgnoreCase(o2);
153        }
154      } // class CaseInsensitiveComparator
155    
156      /**
157       * A Comparator that uses <code>String.compareToIgnoreCase(String)</code>.
158       * This comparator is {@link Serializable}. Note that it ignores Locale,
159       * for that, you want a Collator.
160       *
161       * @see Collator#compare(String, String)
162       * @since 1.2
163       */
164      public static final Comparator<String> CASE_INSENSITIVE_ORDER
165        = new CaseInsensitiveComparator();
166    
167      /**
168       * Creates an empty String (length 0). Unless you really need a new object,
169       * consider using <code>""</code> instead.
170       */
171      public String()
172      {
173        data = "".data;
174        boffset = 0;
175        count = 0;
176      }
177    
178      /**
179       * Copies the contents of a String to a new String. Since Strings are
180       * immutable, only a shallow copy is performed.
181       *
182       * @param str String to copy
183       * @throws NullPointerException if value is null
184       */
185      public String(String str)
186      {
187        data = str.data;
188        boffset = str.boffset;
189        count = str.count;
190        cachedHashCode = str.cachedHashCode;
191      }
192    
193      /**
194       * Creates a new String using the character sequence of the char array.
195       * Subsequent changes to data do not affect the String.
196       *
197       * @param data char array to copy
198       * @throws NullPointerException if data is null
199       */
200      public String(char[] data)
201      {
202        init(data, 0, data.length, false);
203      }
204    
205      /**
206       * Creates a new String using the character sequence of a subarray of
207       * characters. The string starts at offset, and copies count chars.
208       * Subsequent changes to data do not affect the String.
209       *
210       * @param data char array to copy
211       * @param offset position (base 0) to start copying out of data
212       * @param count the number of characters from data to copy
213       * @throws NullPointerException if data is null
214       * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
215       *         || offset + count &lt; 0 (overflow)
216       *         || offset + count &gt; data.length)
217       *         (while unspecified, this is a StringIndexOutOfBoundsException)
218       */
219      public String(char[] data, int offset, int count)
220      {
221        init(data, offset, count, false);
222      }
223    
224      /**
225       * Creates a new String using an 8-bit array of integer values, starting at
226       * an offset, and copying up to the count. Each character c, using
227       * corresponding byte b, is created in the new String as if by performing:
228       *
229       * <pre>
230       * c = (char) (((hibyte &amp; 0xff) &lt;&lt; 8) | (b &amp; 0xff))
231       * </pre>
232       *
233       * @param ascii array of integer values
234       * @param hibyte top byte of each Unicode character
235       * @param offset position (base 0) to start copying out of ascii
236       * @param count the number of characters from ascii to copy
237       * @throws NullPointerException if ascii is null
238       * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
239       *         || offset + count &lt; 0 (overflow)
240       *         || offset + count &gt; ascii.length)
241       *         (while unspecified, this is a StringIndexOutOfBoundsException)
242       * @see #String(byte[])
243       * @see #String(byte[], String)
244       * @see #String(byte[], int, int)
245       * @see #String(byte[], int, int, String)
246       * @deprecated use {@link #String(byte[], int, int, String)} to perform
247       *             correct encoding
248       */
249      public String(byte[] ascii, int hibyte, int offset, int count)
250      {
251        init(ascii, hibyte, offset, count);
252      }
253    
254      /**
255       * Creates a new String using an 8-bit array of integer values. Each
256       * character c, using corresponding byte b, is created in the new String
257       * as if by performing:
258       *
259       * <pre>
260       * c = (char) (((hibyte &amp; 0xff) &lt;&lt; 8) | (b &amp; 0xff))
261       * </pre>
262       *
263       * @param ascii array of integer values
264       * @param hibyte top byte of each Unicode character
265       * @throws NullPointerException if ascii is null
266       * @see #String(byte[])
267       * @see #String(byte[], String)
268       * @see #String(byte[], int, int)
269       * @see #String(byte[], int, int, String)
270       * @see #String(byte[], int, int, int)
271       * @deprecated use {@link #String(byte[], String)} to perform
272       *             correct encoding
273       */
274      public String(byte[] ascii, int hibyte)
275      {
276        init(ascii, hibyte, 0, ascii.length);
277      }
278    
279      /**
280       * Creates a new String using the portion of the byte array starting at the
281       * offset and ending at offset + count. Uses the specified encoding type
282       * to decode the byte array, so the resulting string may be longer or
283       * shorter than the byte array. For more decoding control, use
284       * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
285       * see {@link java.nio.charset.Charset}. The behavior is not specified if
286       * the decoder encounters invalid characters; this implementation throws
287       * an Error.
288       *
289       * @param data byte array to copy
290       * @param offset the offset to start at
291       * @param count the number of bytes in the array to use
292       * @param encoding the name of the encoding to use
293       * @throws NullPointerException if data or encoding is null
294       * @throws IndexOutOfBoundsException if offset or count is incorrect
295       *         (while unspecified, this is a StringIndexOutOfBoundsException)
296       * @throws UnsupportedEncodingException if encoding is not found
297       * @throws Error if the decoding fails
298       * @since 1.1
299       */
300      public String(byte[] data, int offset, int count, String encoding)
301        throws UnsupportedEncodingException
302      {
303        init (data, offset, count, encoding);
304      }
305    
306      /**
307       * Creates a new String using the byte array. Uses the specified encoding
308       * type to decode the byte array, so the resulting string may be longer or
309       * shorter than the byte array. For more decoding control, use
310       * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
311       * see {@link java.nio.charset.Charset}. The behavior is not specified if
312       * the decoder encounters invalid characters; this implementation throws
313       * an Error.
314       *
315       * @param data byte array to copy
316       * @param encoding the name of the encoding to use
317       * @throws NullPointerException if data or encoding is null
318       * @throws UnsupportedEncodingException if encoding is not found
319       * @throws Error if the decoding fails
320       * @see #String(byte[], int, int, String)
321       * @since 1.1
322       */
323      public String(byte[] data, String encoding)
324        throws UnsupportedEncodingException
325      {
326        this(data, 0, data.length, encoding);
327      }
328    
329      /**
330       * Creates a new String using the portion of the byte array starting at the
331       * offset and ending at offset + count. Uses the encoding of the platform's
332       * default charset, so the resulting string may be longer or shorter than
333       * the byte array. For more decoding control, use
334       * {@link java.nio.charset.CharsetDecoder}.  The behavior is not specified
335       * if the decoder encounters invalid characters; this implementation throws
336       * an Error.
337       *
338       * @param data byte array to copy
339       * @param offset the offset to start at
340       * @param count the number of bytes in the array to use
341       * @throws NullPointerException if data is null
342       * @throws IndexOutOfBoundsException if offset or count is incorrect
343       * @throws Error if the decoding fails
344       * @see #String(byte[], int, int, String)
345       * @since 1.1
346       */
347      public String(byte[] data, int offset, int count)
348      {
349        try
350          {
351            init (data, offset, count,
352                  System.getProperty("file.encoding", "8859_1"));
353          }
354        catch (UnsupportedEncodingException x1)
355          {
356            // Maybe the default encoding is bad.
357            try
358              {
359                init (data, offset, count, "8859_1");
360              }
361            catch (UnsupportedEncodingException x2)
362              {
363                // We know this can't happen.
364              }
365          }
366      }
367    
368      /**
369       * Creates a new String using the byte array. Uses the encoding of the
370       * platform's default charset, so the resulting string may be longer or
371       * shorter than the byte array. For more decoding control, use
372       * {@link java.nio.charset.CharsetDecoder}.  The behavior is not specified
373       * if the decoder encounters invalid characters; this implementation throws
374       * an Error.
375       *
376       * @param data byte array to copy
377       * @throws NullPointerException if data is null
378       * @throws Error if the decoding fails
379       * @see #String(byte[], int, int)
380       * @see #String(byte[], int, int, String)
381       * @since 1.1
382       */
383      public String(byte[] data)
384      {
385        this(data, 0, data.length);
386      }
387    
388      /**
389       * Creates a new String using the character sequence represented by
390       * the StringBuffer. Subsequent changes to buf do not affect the String.
391       *
392       * @param buffer StringBuffer to copy
393       * @throws NullPointerException if buffer is null
394       */
395      public String(StringBuffer buffer)
396      {
397        synchronized (buffer)
398          {
399            // Share unless buffer is 3/4 empty.
400            boolean should_copy = ((buffer.count << 2) < buffer.value.length);
401            if (! should_copy)
402              buffer.shared = true;
403            init (buffer.value, 0, buffer.count, ! should_copy);
404          }
405      }
406    
407      /**
408       * Creates a new String using the character sequence represented by
409       * the StringBuilder. Subsequent changes to buf do not affect the String.
410       *
411       * @param buffer StringBuilder to copy
412       * @throws NullPointerException if buffer is null
413       */
414      public String(StringBuilder buffer)
415      {
416        this(buffer.value, 0, buffer.count);
417      }
418    
419      /**
420       * Special constructor which can share an array when safe to do so.
421       *
422       * @param data the characters to copy
423       * @param offset the location to start from
424       * @param count the number of characters to use
425       * @param dont_copy true if the array is trusted, and need not be copied
426       * @throws NullPointerException if chars is null
427       * @throws StringIndexOutOfBoundsException if bounds check fails
428       */
429      String(char[] data, int offset, int count, boolean dont_copy)
430      {
431        init(data, offset, count, dont_copy);
432      }
433    
434      // This is used by gnu.gcj.runtime.StringBuffer, so it must have
435      // package-private protection.  It is accessed via CNI and so avoids
436      // ordinary protection mechanisms.
437      String(gnu.gcj.runtime.StringBuffer buffer)
438      {
439        // No need to synchronize or mark the buffer, since we know it is
440        // only used once.
441        init (buffer);
442      }
443    
444      /**
445       * Returns the number of characters contained in this String.
446       *
447       * @return the length of this String
448       */
449      public int length()
450      {
451        return count;
452      }
453    
454      /**
455       * Returns the character located at the specified index within this String.
456       *
457       * @param index position of character to return (base 0)
458       * @return character located at position index
459       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= length()
460       *         (while unspecified, this is a StringIndexOutOfBoundsException)
461       */
462      public native char charAt(int index);
463    
464      /**
465       * Get the code point at the specified index.  This is like #charAt(int),
466       * but if the character is the start of a surrogate pair, and the
467       * following character completes the pair, then the corresponding
468       * supplementary code point is returned.
469       * @param index the index of the codepoint to get, starting at 0
470       * @return the codepoint at the specified index
471       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
472       * @since 1.5
473       */
474      public synchronized int codePointAt(int index)
475      {
476        // Use the CharSequence overload as we get better range checking
477        // this way.
478        return Character.codePointAt(this, index);
479      }
480    
481      /**
482       * Get the code point before the specified index.  This is like
483       * #codePointAt(int), but checks the characters at <code>index-1</code> and
484       * <code>index-2</code> to see if they form a supplementary code point.
485       * @param index the index just past the codepoint to get, starting at 0
486       * @return the codepoint at the specified index
487       * @throws IndexOutOfBoundsException if index is negative or &gt;= length()
488       *         (while unspecified, this is a StringIndexOutOfBoundsException)
489       * @since 1.5
490       */
491      public synchronized int codePointBefore(int index)
492      {
493        // Use the CharSequence overload as we get better range checking
494        // this way.
495        return Character.codePointBefore(this, index);
496      }
497    
498      /**
499       * Copies characters from this String starting at a specified start index,
500       * ending at a specified stop index, to a character array starting at
501       * a specified destination begin index.
502       *
503       * @param srcBegin index to begin copying characters from this String
504       * @param srcEnd index after the last character to be copied from this String
505       * @param dst character array which this String is copied into
506       * @param dstBegin index to start writing characters into dst
507       * @throws NullPointerException if dst is null
508       * @throws IndexOutOfBoundsException if any indices are out of bounds
509       *         (while unspecified, source problems cause a
510       *         StringIndexOutOfBoundsException, and dst problems cause an
511       *         ArrayIndexOutOfBoundsException)
512       */
513      public native void getChars(int srcBegin, int srcEnd,
514                                  char[] dst, int dstBegin);
515    
516      /**
517       * Copies the low byte of each character from this String starting at a
518       * specified start index, ending at a specified stop index, to a byte array
519       * starting at a specified destination begin index.
520       *
521       * @param srcBegin index to being copying characters from this String
522       * @param srcEnd index after the last character to be copied from this String
523       * @param dst byte array which each low byte of this String is copied into
524       * @param dstBegin index to start writing characters into dst
525       * @throws NullPointerException if dst is null and copy length is non-zero
526       * @throws IndexOutOfBoundsException if any indices are out of bounds
527       *         (while unspecified, source problems cause a
528       *         StringIndexOutOfBoundsException, and dst problems cause an
529       *         ArrayIndexOutOfBoundsException)
530       * @see #getBytes()
531       * @see #getBytes(String)
532       * @deprecated use {@link #getBytes()}, which uses a char to byte encoder
533       */
534      public native void getBytes(int srcBegin, int srcEnd,
535                                  byte[] dst, int dstBegin);
536    
537      /**
538       * Converts the Unicode characters in this String to a byte array. Uses the
539       * specified encoding method, so the result may be longer or shorter than
540       * the String. For more encoding control, use
541       * {@link java.nio.charset.CharsetEncoder}, and for valid character sets,
542       * see {@link java.nio.charset.Charset}. The behavior is not specified if
543       * the encoder encounters a problem; this implementation returns null.
544       *
545       * @param enc encoding name
546       * @return the resulting byte array, or null on a problem
547       * @throws NullPointerException if enc is null
548       * @throws UnsupportedEncodingException if encoding is not supported
549       * @since 1.1
550       */
551      public native byte[] getBytes(String enc)
552        throws UnsupportedEncodingException;
553    
554      /**
555       * Converts the Unicode characters in this String to a byte array. Uses the
556       * encoding of the platform's default charset, so the result may be longer
557       * or shorter than the String. For more encoding control, use
558       * {@link java.nio.charset.CharsetEncoder}.  The behavior is not specified if
559       * the encoder encounters a problem; this implementation returns null.
560       *
561       * @return the resulting byte array, or null on a problem
562       * @since 1.1
563       */
564      public byte[] getBytes()
565      {
566        try
567          {
568            return getBytes (System.getProperty("file.encoding", "8859_1"));
569          }
570        catch (UnsupportedEncodingException x)
571          {
572            // This probably shouldn't happen, but could if file.encoding
573            // is somehow changed to a value we don't understand.
574            try
575              {
576                return getBytes ("8859_1");
577              }
578            catch (UnsupportedEncodingException x2)
579              {
580                // This really shouldn't happen, because the 8859_1
581                // encoding should always be available.
582                throw new InternalError ("couldn't find 8859_1 encoder");
583              }
584          }
585      }
586    
587      /**
588       * Predicate which compares anObject to this. This is true only for Strings
589       * with the same character sequence.
590       *
591       * @param anObject the object to compare
592       * @return true if anObject is semantically equal to this
593       * @see #compareTo(String)
594       * @see #equalsIgnoreCase(String)
595       */
596      public native boolean equals(Object anObject);
597    
598      /**
599       * Compares the given StringBuffer to this String. This is true if the
600       * StringBuffer has the same content as this String at this moment.
601       *
602       * @param buffer the StringBuffer to compare to
603       * @return true if StringBuffer has the same character sequence
604       * @throws NullPointerException if the given StringBuffer is null
605       * @since 1.4
606       */
607      public native boolean contentEquals(StringBuffer buffer);
608    
609      /**
610       * Compares the given CharSequence to this String. This is true if
611       * the CharSequence has the same content as this String at this
612       * moment.
613       *
614       * @param seq the CharSequence to compare to
615       * @return true if CharSequence has the same character sequence
616       * @throws NullPointerException if the given CharSequence is null
617       * @since 1.5
618       */
619      public native boolean contentEquals(CharSequence seq);
620    
621      /**
622       * Compares a String to this String, ignoring case. This does not handle
623       * multi-character capitalization exceptions; instead the comparison is
624       * made on a character-by-character basis, and is true if:<br><ul>
625       * <li><code>c1 == c2</code></li>
626       * <li><code>Character.toUpperCase(c1)
627       *     == Character.toUpperCase(c2)</code></li>
628       * <li><code>Character.toLowerCase(c1)
629       *     == Character.toLowerCase(c2)</code></li>
630       * </ul>
631       *
632       * @param anotherString String to compare to this String
633       * @return true if anotherString is equal, ignoring case
634       * @see #equals(Object)
635       * @see Character#toUpperCase(char)
636       * @see Character#toLowerCase(char)
637       */
638      public native boolean equalsIgnoreCase(String anotherString);
639    
640      /**
641       * Compares this String and another String (case sensitive,
642       * lexicographically). The result is less than 0 if this string sorts
643       * before the other, 0 if they are equal, and greater than 0 otherwise.
644       * After any common starting sequence is skipped, the result is
645       * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings
646       * have characters remaining, or
647       * <code>this.length() - anotherString.length()</code> if one string is
648       * a subsequence of the other.
649       *
650       * @param anotherString the String to compare against
651       * @return the comparison
652       * @throws NullPointerException if anotherString is null
653       */
654      public int compareTo(String anotherString)
655      {
656        return nativeCompareTo(anotherString);
657      }
658    
659      /**
660       * The native implementation of compareTo(). Must be named different
661       * since cni doesn't understand the bridge method generated from
662       * the compareTo() method because of the Comparable<String> interface.
663       */
664      private native int nativeCompareTo(String anotherString);
665    
666      /**
667       * Compares this String and another String (case insensitive). This
668       * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores
669       * locale and multi-characater capitalization, and compares characters
670       * after performing
671       * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each
672       * character of the string. This is unsatisfactory for locale-based
673       * comparison, in which case you should use {@link java.text.Collator}.
674       *
675       * @param str the string to compare against
676       * @return the comparison
677       * @see Collator#compare(String, String)
678       * @since 1.2
679       */
680      public int compareToIgnoreCase(String str)
681      {
682        return this.toUpperCase().toLowerCase().compareTo(
683         str.toUpperCase().toLowerCase());
684      }  
685    
686      /**
687       * Predicate which determines if this String matches another String
688       * starting at a specified offset for each String and continuing
689       * for a specified length. Indices out of bounds are harmless, and give
690       * a false result.
691       *
692       * @param toffset index to start comparison at for this String
693       * @param other String to compare region to this String
694       * @param ooffset index to start comparison at for other
695       * @param len number of characters to compare
696       * @return true if regions match (case sensitive)
697       * @throws NullPointerException if other is null
698       */
699      public native boolean regionMatches(int toffset,
700                                          String other, int ooffset, int len);
701    
702      /**
703       * Predicate which determines if this String matches another String
704       * starting at a specified offset for each String and continuing
705       * for a specified length, optionally ignoring case. Indices out of bounds
706       * are harmless, and give a false result. Case comparisons are based on
707       * <code>Character.toLowerCase()</code> and
708       * <code>Character.toUpperCase()</code>, not on multi-character
709       * capitalization expansions.
710       *
711       * @param ignoreCase true if case should be ignored in comparision
712       * @param toffset index to start comparison at for this String
713       * @param other String to compare region to this String
714       * @param ooffset index to start comparison at for other
715       * @param len number of characters to compare
716       * @return true if regions match, false otherwise
717       * @throws NullPointerException if other is null
718       */
719      public native boolean regionMatches(boolean ignoreCase, int toffset,
720                                          String other, int ooffset, int len);
721    
722      /**
723       * Predicate which determines if this String contains the given prefix,
724       * beginning comparison at toffset. The result is false if toffset is
725       * negative or greater than this.length(), otherwise it is the same as
726       * <code>this.substring(toffset).startsWith(prefix)</code>.
727       *
728       * @param prefix String to compare
729       * @param toffset offset for this String where comparison starts
730       * @return true if this String starts with prefix
731       * @throws NullPointerException if prefix is null
732       * @see #regionMatches(boolean, int, String, int, int)
733       */
734      public native boolean startsWith(String prefix, int toffset);
735    
736      /**
737       * Predicate which determines if this String starts with a given prefix.
738       * If the prefix is an empty String, true is returned.
739       *
740       * @param prefix String to compare
741       * @return true if this String starts with the prefix
742       * @throws NullPointerException if prefix is null
743       * @see #startsWith(String, int)
744       */
745      public boolean startsWith(String prefix)
746      {
747        return startsWith (prefix, 0);
748      }
749    
750      /**
751       * Predicate which determines if this String ends with a given suffix.
752       * If the suffix is an empty String, true is returned.
753       *
754       * @param suffix String to compare
755       * @return true if this String ends with the suffix
756       * @throws NullPointerException if suffix is null
757       * @see #regionMatches(boolean, int, String, int, int)
758       */
759      public boolean endsWith(String suffix)
760      {
761        return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
762      }
763    
764      /**
765       * Computes the hashcode for this String. This is done with int arithmetic,
766       * where ** represents exponentiation, by this formula:<br>
767       * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>.
768       *
769       * @return hashcode value of this String
770       */
771      public native int hashCode();
772    
773      /**
774       * Finds the first instance of a character in this String.
775       *
776       * @param ch character to find
777       * @return location (base 0) of the character, or -1 if not found
778       */
779      public int indexOf(int ch)
780      {
781        return indexOf(ch, 0);
782      }
783    
784      /**
785       * Finds the first instance of a character in this String, starting at
786       * a given index.  If starting index is less than 0, the search
787       * starts at the beginning of this String.  If the starting index
788       * is greater than the length of this String, -1 is returned.
789       *
790       * @param ch character to find
791       * @param fromIndex index to start the search
792       * @return location (base 0) of the character, or -1 if not found
793       */
794      public native int indexOf(int ch, int fromIndex);
795    
796      /**
797       * Finds the last instance of a character in this String.
798       *
799       * @param ch character to find
800       * @return location (base 0) of the character, or -1 if not found
801       */
802      public int lastIndexOf(int ch)
803      {
804        return lastIndexOf(ch, count - 1);
805      }
806    
807      /**
808       * Finds the last instance of a character in this String, starting at
809       * a given index.  If starting index is greater than the maximum valid
810       * index, then the search begins at the end of this String.  If the
811       * starting index is less than zero, -1 is returned.
812       *
813       * @param ch character to find
814       * @param fromIndex index to start the search
815       * @return location (base 0) of the character, or -1 if not found
816       */
817      public native int lastIndexOf(int ch, int fromIndex);
818    
819      /**
820       * Finds the first instance of a String in this String.
821       *
822       * @param str String to find
823       * @return location (base 0) of the String, or -1 if not found
824       * @throws NullPointerException if str is null
825       */
826      public int indexOf(String str)
827      {
828        return indexOf(str, 0);
829      }
830    
831      /**
832       * Finds the first instance of a String in this String, starting at
833       * a given index.  If starting index is less than 0, the search
834       * starts at the beginning of this String.  If the starting index
835       * is greater than the length of this String, -1 is returned.
836       *
837       * @param str String to find
838       * @param fromIndex index to start the search
839       * @return location (base 0) of the String, or -1 if not found
840       * @throws NullPointerException if str is null
841       */
842      public native int indexOf(String str, int fromIndex);
843    
844      /**
845       * Finds the last instance of a String in this String.
846       *
847       * @param str String to find
848       * @return location (base 0) of the String, or -1 if not found
849       * @throws NullPointerException if str is null
850       */
851      public int lastIndexOf(String str)
852      {
853        return lastIndexOf(str, count - str.count);
854      }
855    
856      /**
857       * Finds the last instance of a String in this String, starting at
858       * a given index.  If starting index is greater than the maximum valid
859       * index, then the search begins at the end of this String.  If the
860       * starting index is less than zero, -1 is returned.
861       *
862       * @param str String to find
863       * @param fromIndex index to start the search
864       * @return location (base 0) of the String, or -1 if not found
865       * @throws NullPointerException if str is null
866       */
867      public int lastIndexOf(String str, int fromIndex)
868      {
869        if (fromIndex >= count)
870          fromIndex = count - str.count;
871        for (;; --fromIndex)
872          {
873            if (fromIndex < 0)
874              return -1;
875            if (startsWith(str, fromIndex))
876              return fromIndex;
877          }
878      }
879    
880      /**
881       * Creates a substring of this String, starting at a specified index
882       * and ending at the end of this String.
883       *
884       * @param begin index to start substring (base 0)
885       * @return new String which is a substring of this String
886       * @throws IndexOutOfBoundsException if begin &lt; 0 || begin &gt; length()
887       *         (while unspecified, this is a StringIndexOutOfBoundsException)
888       */
889      public String substring(int begin)
890      {
891        return substring(begin, count);
892      }
893    
894      /**
895       * Creates a substring of this String, starting at a specified index
896       * and ending at one character before a specified index.
897       *
898       * @param begin index to start substring (inclusive, base 0)
899       * @param end index to end at (exclusive)
900       * @return new String which is a substring of this String
901       * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
902       *         || begin &gt; end (while unspecified, this is a
903       *         StringIndexOutOfBoundsException)
904       */
905      public native String substring(int begin, int end);
906    
907      /**
908       * Creates a substring of this String, starting at a specified index
909       * and ending at one character before a specified index. This behaves like
910       * <code>substring(begin, end)</code>.
911       *
912       * @param begin index to start substring (inclusive, base 0)
913       * @param end index to end at (exclusive)
914       * @return new String which is a substring of this String
915       * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
916       *         || begin &gt; end
917       * @since 1.4
918       */
919      public CharSequence subSequence(int begin, int end)
920      {
921        return substring(begin, end);
922      }
923    
924      /**
925       * Concatenates a String to this String. This results in a new string unless
926       * one of the two originals is "".
927       *
928       * @param str String to append to this String
929       * @return newly concatenated String
930       * @throws NullPointerException if str is null
931       */
932      public native String concat(String str);
933    
934      /**
935       * Replaces every instance of a character in this String with a new
936       * character. If no replacements occur, this is returned.
937       *
938       * @param oldChar the old character to replace
939       * @param newChar the new character
940       * @return new String with all instances of oldChar replaced with newChar
941       */
942      public native String replace(char oldChar, char newChar);
943    
944      /**
945       * Test if this String matches a regular expression. This is shorthand for
946       * <code>{@link Pattern}.matches(regex, this)</code>.
947       *
948       * @param regex the pattern to match
949       * @return true if the pattern matches
950       * @throws NullPointerException if regex is null
951       * @throws PatternSyntaxException if regex is invalid
952       * @see Pattern#matches(String, CharSequence)
953       * @since 1.4
954       */
955      public boolean matches(String regex)
956      {
957        return Pattern.matches(regex, this);
958      }
959    
960      /**
961       * Replaces the first substring match of the regular expression with a
962       * given replacement. This is shorthand for <code>{@link Pattern}
963       *   .compile(regex).matcher(this).replaceFirst(replacement)</code>.
964       *
965       * @param regex the pattern to match
966       * @param replacement the replacement string
967       * @return the modified string
968       * @throws NullPointerException if regex or replacement is null
969       * @throws PatternSyntaxException if regex is invalid
970       * @see #replaceAll(String, String)
971       * @see Pattern#compile(String)
972       * @see Pattern#matcher(CharSequence)
973       * @see Matcher#replaceFirst(String)
974       * @since 1.4
975       */
976      public String replaceFirst(String regex, String replacement)
977      {
978        return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
979      }
980    
981      /**
982       * Replaces all matching substrings of the regular expression with a
983       * given replacement. This is shorthand for <code>{@link Pattern}
984       *   .compile(regex).matcher(this).replaceAll(replacement)</code>.
985       *
986       * @param regex the pattern to match
987       * @param replacement the replacement string
988       * @return the modified string
989       * @throws NullPointerException if regex or replacement is null
990       * @throws PatternSyntaxException if regex is invalid
991       * @see #replaceFirst(String, String)
992       * @see Pattern#compile(String)
993       * @see Pattern#matcher(CharSequence)
994       * @see Matcher#replaceAll(String)
995       * @since 1.4
996       */
997      public String replaceAll(String regex, String replacement)
998      {
999        return Pattern.compile(regex).matcher(this).replaceAll(replacement);
1000      }
1001    
1002      /**
1003       * Split this string around the matches of a regular expression. Each
1004       * element of the returned array is the largest block of characters not
1005       * terminated by the regular expression, in the order the matches are found.
1006       *
1007       * <p>The limit affects the length of the array. If it is positive, the
1008       * array will contain at most n elements (n - 1 pattern matches). If
1009       * negative, the array length is unlimited, but there can be trailing empty
1010       * entries. if 0, the array length is unlimited, and trailing empty entries
1011       * are discarded.
1012       *
1013       * <p>For example, splitting "boo:and:foo" yields:<br>
1014       * <table border=0>
1015       * <th><td>Regex</td> <td>Limit</td> <td>Result</td></th>
1016       * <tr><td>":"</td>   <td>2</td>  <td>{ "boo", "and:foo" }</td></tr>
1017       * <tr><td>":"</td>   <td>t</td>  <td>{ "boo", "and", "foo" }</td></tr>
1018       * <tr><td>":"</td>   <td>-2</td> <td>{ "boo", "and", "foo" }</td></tr>
1019       * <tr><td>"o"</td>   <td>5</td>  <td>{ "b", "", ":and:f", "", "" }</td></tr>
1020       * <tr><td>"o"</td>   <td>-2</td> <td>{ "b", "", ":and:f", "", "" }</td></tr>
1021       * <tr><td>"o"</td>   <td>0</td>  <td>{ "b", "", ":and:f" }</td></tr>
1022       * </table>
1023       *
1024       * <p>This is shorthand for
1025       * <code>{@link Pattern}.compile(regex).split(this, limit)</code>.
1026       *
1027       * @param regex the pattern to match
1028       * @param limit the limit threshold
1029       * @return the array of split strings
1030       * @throws NullPointerException if regex or replacement is null
1031       * @throws PatternSyntaxException if regex is invalid
1032       * @see Pattern#compile(String)
1033       * @see Pattern#split(CharSequence, int)
1034       * @since 1.4
1035       */
1036      public String[] split(String regex, int limit)
1037      {
1038        return Pattern.compile(regex).split(this, limit);
1039      }
1040    
1041      /**
1042       * Split this string around the matches of a regular expression. Each
1043       * element of the returned array is the largest block of characters not
1044       * terminated by the regular expression, in the order the matches are found.
1045       * The array length is unlimited, and trailing empty entries are discarded,
1046       * as though calling <code>split(regex, 0)</code>.
1047       *
1048       * @param regex the pattern to match
1049       * @return the array of split strings
1050       * @throws NullPointerException if regex or replacement is null
1051       * @throws PatternSyntaxException if regex is invalid
1052       * @see #split(String, int)
1053       * @see Pattern#compile(String)
1054       * @see Pattern#split(CharSequence, int)
1055       * @since 1.4
1056       */
1057      public String[] split(String regex)
1058      {
1059        return Pattern.compile(regex).split(this, 0);
1060      }
1061    
1062      /**
1063       * Lowercases this String according to a particular locale. This uses
1064       * Unicode's special case mappings, as applied to the given Locale, so the
1065       * resulting string may be a different length.
1066       *
1067       * @param loc locale to use
1068       * @return new lowercased String, or this if no characters were lowercased
1069       * @throws NullPointerException if loc is null
1070       * @see #toUpperCase(Locale)
1071       * @since 1.1
1072       */
1073      public native String toLowerCase(Locale locale);
1074    
1075      /**
1076       * Lowercases this String. This uses Unicode's special case mappings, as
1077       * applied to the platform's default Locale, so the resulting string may
1078       * be a different length.
1079       *
1080       * @return new lowercased String, or this if no characters were lowercased
1081       * @see #toLowerCase(Locale)
1082       * @see #toUpperCase()
1083       */
1084      public String toLowerCase()
1085      {
1086        // The JDK is a bit confused about what to do here.  If we pass in
1087        // the default Locale then special Locale handling might be
1088        // invoked.  However, the docs also say that Character.toLowerCase
1089        // rules here.  We go with the latter.
1090        return toLowerCase (null);
1091      }
1092    
1093      /**
1094       * Uppercases this String according to a particular locale. This uses
1095       * Unicode's special case mappings, as applied to the given Locale, so the
1096       * resulting string may be a different length.
1097       *
1098       * @param loc locale to use
1099       * @return new uppercased String, or this if no characters were uppercased
1100       * @throws NullPointerException if loc is null
1101       * @see #toLowerCase(Locale)
1102       * @since 1.1
1103       */
1104      public native String toUpperCase(Locale locale);
1105    
1106      /**
1107       * Uppercases this String. This uses Unicode's special case mappings, as
1108       * applied to the platform's default Locale, so the resulting string may
1109       * be a different length.
1110       *
1111       * @return new uppercased String, or this if no characters were uppercased
1112       * @see #toUpperCase(Locale)
1113       * @see #toLowerCase()
1114       */
1115      public String toUpperCase()
1116      {
1117        // The JDK is a bit confused about what to do here.  If we pass in
1118        // the default Locale then special Locale handling might be
1119        // invoked.  However, the docs also say that Character.toLowerCase
1120        // rules here.  We go with the latter.
1121        return toUpperCase (null);
1122      }
1123    
1124      /**
1125       * Trims all characters less than or equal to <code>'\u0020'</code>
1126       * (<code>' '</code>) from the beginning and end of this String. This
1127       * includes many, but not all, ASCII control characters, and all
1128       * {@link Character#isWhitespace(char)}.
1129       *
1130       * @return new trimmed String, or this if nothing trimmed
1131       */
1132      public native String trim();
1133    
1134      /**
1135       * Returns this, as it is already a String!
1136       *
1137       * @return this
1138       */
1139      public String toString()
1140      {
1141        return this;
1142      }
1143    
1144      /**
1145       * Copies the contents of this String into a character array. Subsequent
1146       * changes to the array do not affect the String.
1147       *
1148       * @return character array copying the String
1149       */
1150      public native char[] toCharArray();
1151    
1152      /**
1153       * Returns a String representation of an Object. This is "null" if the
1154       * object is null, otherwise it is <code>obj.toString()</code> (which
1155       * can be null).
1156       *
1157       * @param obj the Object
1158       * @return the string conversion of obj
1159       */
1160      public static String valueOf(Object obj)
1161      {
1162        return obj == null ? "null" : obj.toString();
1163      }
1164    
1165      /**
1166       * Returns a String representation of a character array. Subsequent
1167       * changes to the array do not affect the String.
1168       *
1169       * @param data the character array
1170       * @return a String containing the same character sequence as data
1171       * @throws NullPointerException if data is null
1172       * @see #valueOf(char[], int, int)
1173       * @see #String(char[])
1174       */
1175      public static String valueOf(char[] data)
1176      {
1177        return valueOf (data, 0, data.length);
1178      }
1179    
1180      /**
1181       * Returns a String representing the character sequence of the char array,
1182       * starting at the specified offset, and copying chars up to the specified
1183       * count. Subsequent changes to the array do not affect the String.
1184       *
1185       * @param data character array
1186       * @param offset position (base 0) to start copying out of data
1187       * @param count the number of characters from data to copy
1188       * @return String containing the chars from data[offset..offset+count]
1189       * @throws NullPointerException if data is null
1190       * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1191       *         || offset + count &gt; data.length)
1192       *         (while unspecified, this is a StringIndexOutOfBoundsException)
1193       * @see #String(char[], int, int)
1194       */
1195      public static native String valueOf(char[] data, int offset, int count);
1196    
1197      /**
1198       * Returns a String representing the character sequence of the char array,
1199       * starting at the specified offset, and copying chars up to the specified
1200       * count. Subsequent changes to the array do not affect the String.
1201       *
1202       * @param data character array
1203       * @param offset position (base 0) to start copying out of data
1204       * @param count the number of characters from data to copy
1205       * @return String containing the chars from data[offset..offset+count]
1206       * @throws NullPointerException if data is null
1207       * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1208       *         || offset + count &lt; 0 (overflow)
1209       *         || offset + count &gt; data.length)
1210       *         (while unspecified, this is a StringIndexOutOfBoundsException)
1211       * @see #String(char[], int, int)
1212       */
1213      public static String copyValueOf(char[] data, int offset, int count)
1214      {
1215        String r = new String ();
1216        r.init(data, offset, count, false);
1217        return r;
1218      }
1219    
1220      /**
1221       * Returns a String representation of a character array. Subsequent
1222       * changes to the array do not affect the String.
1223       *
1224       * @param data the character array
1225       * @return a String containing the same character sequence as data
1226       * @throws NullPointerException if data is null
1227       * @see #copyValueOf(char[], int, int)
1228       * @see #String(char[])
1229       */
1230      public static String copyValueOf(char[] data)
1231      {
1232        return copyValueOf (data, 0, data.length);
1233      }
1234    
1235      /**
1236       * Returns a String representing a boolean.
1237       *
1238       * @param b the boolean
1239       * @return "true" if b is true, else "false"
1240       */
1241      public static String valueOf(boolean b)
1242      {
1243        return b ? "true" : "false";
1244      }
1245    
1246      /**
1247       * Returns a String representing a character.
1248       *
1249       * @param c the character
1250       * @return String containing the single character c
1251       */
1252      public static native String valueOf(char c);
1253    
1254      /**
1255       * Returns a String representing an integer.
1256       *
1257       * @param i the integer
1258       * @return String containing the integer in base 10
1259       * @see Integer#toString(int)
1260       */
1261      public static native String valueOf(int i);
1262    
1263      /**
1264       * Returns a String representing a long.
1265       *
1266       * @param l the long
1267       * @return String containing the long in base 10
1268       * @see Long#toString(long)
1269       */
1270      public static String valueOf(long l)
1271      {
1272        return Long.toString(l);
1273      }
1274    
1275      /**
1276       * Returns a String representing a float.
1277       *
1278       * @param f the float
1279       * @return String containing the float
1280       * @see Float#toString(float)
1281       */
1282      public static String valueOf(float f)
1283      {
1284        return Float.toString(f);
1285      }
1286    
1287      /**
1288       * Returns a String representing a double.
1289       *
1290       * @param d the double
1291       * @return String containing the double
1292       * @see Double#toString(double)
1293       */
1294      public static String valueOf(double d)
1295      {
1296        return Double.toString(d);
1297      }
1298    
1299    
1300      /** @since 1.5 */
1301      public static String format(Locale locale, String format, Object... args)
1302      {
1303        Formatter f = new Formatter(locale);
1304        return f.format(format, args).toString();
1305      }
1306    
1307      /** @since 1.5 */
1308      public static String format(String format, Object... args)
1309      {
1310        return format(Locale.getDefault(), format, args);
1311      }
1312    
1313      /**
1314       * Fetches this String from the intern hashtable.
1315       * If two Strings are considered equal, by the equals() method, 
1316       * then intern() will return the same String instance. ie. 
1317       * if (s1.equals(s2)) then (s1.intern() == s2.intern()). 
1318       * All string literals and string-valued constant expressions 
1319       * are already interned.
1320       *
1321       * @return the interned String
1322       */
1323      public native String intern();
1324    
1325      /**
1326       * Return the number of code points between two indices in the
1327       * <code>String</code>.  An unpaired surrogate counts as a
1328       * code point for this purpose.  Characters outside the indicated
1329       * range are not examined, even if the range ends in the middle of a
1330       * surrogate pair.
1331       *
1332       * @param start the starting index
1333       * @param end one past the ending index
1334       * @return the number of code points
1335       * @since 1.5
1336       */
1337      public synchronized int codePointCount(int start, int end)
1338      {
1339        if (start < 0 || end > count || start > end)
1340          throw new StringIndexOutOfBoundsException();
1341    
1342        int count = 0;
1343        while (start < end)
1344          {
1345            char base = charAt(start);
1346            if (base < Character.MIN_HIGH_SURROGATE
1347                || base > Character.MAX_HIGH_SURROGATE
1348                || start == end
1349                || start == count
1350                || charAt(start + 1) < Character.MIN_LOW_SURROGATE
1351                || charAt(start + 1) > Character.MAX_LOW_SURROGATE)
1352              {
1353                // Nothing.
1354              }
1355            else
1356              {
1357                // Surrogate pair.
1358                ++start;
1359              }
1360            ++start;
1361            ++count;
1362          }
1363        return count;
1364      }
1365      
1366      /**
1367       * Returns true iff this String contains the sequence of Characters
1368       * described in s.
1369       * @param s the CharSequence
1370       * @return true iff this String contains s
1371       * 
1372       * @since 1.5
1373       */
1374      public boolean contains (CharSequence s)
1375      {
1376        return this.indexOf(s.toString()) != -1;
1377      }
1378      
1379      /**
1380       * Returns a string that is this string with all instances of the sequence
1381       * represented by <code>target</code> replaced by the sequence in 
1382       * <code>replacement</code>.
1383       * @param target the sequence to be replaced
1384       * @param replacement the sequence used as the replacement
1385       * @return the string constructed as above
1386       */
1387      public String replace (CharSequence target, CharSequence replacement)
1388      {
1389        String targetString = target.toString();
1390        String replaceString = replacement.toString();
1391        int targetLength = target.length();
1392        int replaceLength = replacement.length();
1393        
1394        int startPos = this.indexOf(targetString);
1395        StringBuilder result = new StringBuilder(this);    
1396        while (startPos != -1)
1397          {
1398            // Replace the target with the replacement
1399            result.replace(startPos, startPos + targetLength, replaceString);
1400    
1401            // Search for a new occurrence of the target
1402            startPos = result.indexOf(targetString, startPos + replaceLength);
1403          }
1404        return result.toString();
1405      }
1406      
1407      /**
1408       * Return the index into this String that is offset from the given index by 
1409       * <code>codePointOffset</code> code points.
1410       * @param index the index at which to start
1411       * @param codePointOffset the number of code points to offset
1412       * @return the index into this String that is <code>codePointOffset</code>
1413       * code points offset from <code>index</code>.
1414       * 
1415       * @throws IndexOutOfBoundsException if index is negative or larger than the
1416       * length of this string.
1417       * @throws IndexOutOfBoundsException if codePointOffset is positive and the
1418       * substring starting with index has fewer than codePointOffset code points.
1419       * @throws IndexOutOfBoundsException if codePointOffset is negative and the
1420       * substring ending with index has fewer than (-codePointOffset) code points.
1421       * @since 1.5
1422       */
1423      public int offsetByCodePoints(int index, int codePointOffset)
1424      {
1425        if (index < 0 || index > count)
1426          throw new IndexOutOfBoundsException();
1427        
1428        return Character.offsetByCodePoints(this, index, codePointOffset);
1429      }
1430    
1431      /**
1432       * Returns true if, and only if, {@link #length()}
1433       * is <code>0</code>.
1434       *
1435       * @return true if the length of the string is zero.
1436       * @since 1.6
1437       */
1438      public boolean isEmpty()
1439      {
1440        return count == 0;
1441      }
1442    
1443      // Generate a String that shares the value array: subsequent changes
1444      // to this array will affect the String.  A private internal method
1445      // that is called from CPStringBuilder by compiler-generated code.
1446      private static String toString(char[] value, int startIndex, int count)
1447      {
1448        return new String(value, startIndex, count, true);
1449      }
1450    
1451      private native void init(char[] chars, int offset, int count,
1452                               boolean dont_copy);
1453      private native void init(byte[] chars, int hibyte, int offset, int count);
1454      private native void init(byte[] chars, int offset, int count, String enc)
1455        throws UnsupportedEncodingException;
1456      private native void init(gnu.gcj.runtime.StringBuffer buffer);
1457    }