Java > Open Source Codes > java > lang > String


1 /*
2  * @(#)String.java 1.189 05/10/21
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.lang;
9
10 import java.io.ObjectStreamClass ;
11 import java.io.ObjectStreamField ;
12 import java.io.UnsupportedEncodingException ;
13 import java.util.ArrayList ;
14 import java.util.Comparator ;
15 import java.util.Formatter ;
16 import java.util.Locale ;
17 import java.util.regex.Matcher ;
18 import java.util.regex.Pattern ;
19 import java.util.regex.PatternSyntaxException ;
20
21
22 /**
23  * The <code>String</code> class represents character strings. All
24  * string literals in Java programs, such as <code>"abc"</code>, are
25  * implemented as instances of this class.
26  * <p>
27  * Strings are constant; their values cannot be changed after they
28  * are created. String buffers support mutable strings.
29  * Because String objects are immutable they can be shared. For example:
30  * <p><blockquote><pre>
31  * String str = "abc";
32  * </pre></blockquote><p>
33  * is equivalent to:
34  * <p><blockquote><pre>
35  * char data[] = {'a', 'b', 'c'};
36  * String str = new String(data);
37  * </pre></blockquote><p>
38  * Here are some more examples of how strings can be used:
39  * <p><blockquote><pre>
40  * System.out.println("abc");
41  * String cde = "cde";
42  * System.out.println("abc" + cde);
43  * String c = "abc".substring(2,3);
44  * String d = cde.substring(1, 2);
45  * </pre></blockquote>
46  * <p>
47  * The class <code>String</code> includes methods for examining
48  * individual characters of the sequence, for comparing strings, for
49  * searching strings, for extracting substrings, and for creating a
50  * copy of a string with all characters translated to uppercase or to
51  * lowercase. Case mapping is based on the Unicode Standard version
52  * specified by the {@link java.lang.Character Character} class.
53  * <p>
54  * The Java language provides special support for the string
55  * concatenation operator (&nbsp;+&nbsp;), and for conversion of
56  * other objects to strings. String concatenation is implemented
57  * through the <code>StringBuilder</code>(or <code>StringBuffer</code>)
58  * class and its <code>append</code> method.
59  * String conversions are implemented through the method
60  * <code>toString</code>, defined by <code>Object</code> and
61  * inherited by all classes in Java. For additional information on
62  * string concatenation and conversion, see Gosling, Joy, and Steele,
63  * <i>The Java Language Specification</i>.
64  *
65  * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
66  * or method in this class will cause a {@link NullPointerException} to be
67  * thrown.
68  *
69  * <p>A <code>String</code> represents a string in the UTF-16 format
70  * in which <em>supplementary characters</em> are represented by <em>surrogate
71  * pairs</em> (see the section <a HREF="Character.html#unicode">Unicode
72  * Character Representations</a> in the <code>Character</code> class for
73  * more information).
74  * Index values refer to <code>char</code> code units, so a supplementary
75  * character uses two positions in a <code>String</code>.
76  * <p>The <code>String</code> class provides methods for dealing with
77  * Unicode code points (i.e., characters), in addition to those for
78  * dealing with Unicode code units (i.e., <code>char</code> values).
79  *
80  * @author Lee Boynton
81  * @author Arthur van Hoff
82  * @version 1.189, 10/21/05
83  * @see java.lang.Object#toString()
84  * @see java.lang.StringBuffer
85  * @see java.lang.StringBuilder
86  * @see java.nio.charset.Charset
87  * @since JDK1.0
88  */
89
90 public final class String
91     implements java.io.Serializable , Comparable <String >, CharSequence
92 {
93     /** The value is used for character storage. */
94     private final char value[];
95
96     /** The offset is the first index of the storage that is used. */
97     private final int offset;
98
99     /** The count is the number of characters in the String. */
100     private final int count;
101
102     /** Cache the hash code for the string */
103     private int hash; // Default to 0
104
105     /** use serialVersionUID from JDK 1.0.2 for interoperability */
106     private static final long serialVersionUID = -6849794470754667710L;
107
108     /**
109      * Class String is special cased within the Serialization Stream Protocol.
110      *
111      * A String instance is written initially into an ObjectOutputStream in the
112      * following format:
113      * <pre>
114      * <code>TC_STRING</code> (utf String)
115      * </pre>
116      * The String is written by method <code>DataOutput.writeUTF</code>.
117      * A new handle is generated to refer to all future references to the
118      * string instance within the stream.
119      */
120     private static final ObjectStreamField [] serialPersistentFields =
121         new ObjectStreamField [0];
122
123     /**
124      * Initializes a newly created <code>String</code> object so that it
125      * represents an empty character sequence. Note that use of this
126      * constructor is unnecessary since Strings are immutable.
127      */
128     public String() {
129     this.offset = 0;
130     this.count = 0;
131     this.value = new char[0];
132     }
133
134     /**
135      * Initializes a newly created <code>String</code> object so that it
136      * represents the same sequence of characters as the argument; in other
137      * words, the newly created string is a copy of the argument string. Unless
138      * an explicit copy of <code>original</code> is needed, use of this
139      * constructor is unnecessary since Strings are immutable.
140      *
141      * @param original a <code>String</code>.
142      */
143     public String(String original) {
144     int size = original.count;
145     char[] originalValue = original.value;
146     char[] v;
147     if (originalValue.length > size) {
148         // The array representing the String is bigger than the new
149 // String itself. Perhaps this constructor is being called
150 // in order to trim the baggage, so make a copy of the array.
151 v = new char[size];
152         System.arraycopy(originalValue, original.offset, v, 0, size);
153     } else {
154         // The array representing the String is the same
155 // size as the String, so no point in making a copy.
156 v = originalValue;
157     }
158     this.offset = 0;
159     this.count = size;
160     this.value = v;
161     }
162
163     /**
164      * Allocates a new <code>String</code> so that it represents the
165      * sequence of characters currently contained in the character array
166      * argument. The contents of the character array are copied; subsequent
167      * modification of the character array does not affect the newly created
168      * string.
169      *
170      * @param value the initial value of the string.
171      */
172     public String(char value[]) {
173     int size = value.length;
174     char[] v = new char[size];
175     System.arraycopy(value, 0, v, 0, size);
176     this.offset = 0;
177     this.count = size;
178     this.value = v;
179     }
180
181     /**
182      * Allocates a new <code>String</code> that contains characters from
183      * a subarray of the character array argument. The <code>offset</code>
184      * argument is the index of the first character of the subarray and
185      * the <code>count</code> argument specifies the length of the
186      * subarray. The contents of the subarray are copied; subsequent
187      * modification of the character array does not affect the newly
188      * created string.
189      *
190      * @param value array that is the source of characters.
191      * @param offset the initial offset.
192      * @param count the length.
193      * @exception IndexOutOfBoundsException if the <code>offset</code>
194      * and <code>count</code> arguments index characters outside
195      * the bounds of the <code>value</code> array.
196      */
197     public String(char value[], int offset, int count) {
198         if (offset < 0) {
199             throw new StringIndexOutOfBoundsException (offset);
200         }
201         if (count < 0) {
202             throw new StringIndexOutOfBoundsException (count);
203         }
204         // Note: offset or count might be near -1>>>1.
205 if (offset > value.length - count) {
206             throw new StringIndexOutOfBoundsException (offset + count);
207         }
208         char[] v = new char[count];
209         System.arraycopy(value, offset, v, 0, count);
210         this.offset = 0;
211         this.count = count;
212         this.value = v;
213     }
214
215     /**
216      * Allocates a new <code>String</code> that contains characters
217      * from a subarray of the Unicode code point array argument. The
218      * <code>offset</code> argument is the index of the first code
219      * point of the subarray and the <code>count</code> argument
220      * specifies the length of the subarray. The contents of the
221      * subarray are converted to <code>char</code>s; subsequent
222      * modification of the <code>int</code> array does not affect the
223      * newly created string.
224      *
225      * @param codePoints array that is the source of Unicode code points.
226      * @param offset the initial offset.
227      * @param count the length.
228      * @exception IllegalArgumentException if any invalid Unicode code point
229      * is found in <code>codePoints</code>
230      * @exception IndexOutOfBoundsException if the <code>offset</code>
231      * and <code>count</code> arguments index characters outside
232      * the bounds of the <code>codePoints</code> array.
233      * @since 1.5
234      */
235     public String(int[] codePoints, int offset, int count) {
236         if (offset < 0) {
237             throw new StringIndexOutOfBoundsException (offset);
238         }
239         if (count < 0) {
240             throw new StringIndexOutOfBoundsException (count);
241         }
242         // Note: offset or count might be near -1>>>1.
243 if (offset > codePoints.length - count) {
244             throw new StringIndexOutOfBoundsException (offset + count);
245         }
246
247     int expansion = 0;
248     int margin = 1;
249     char[] v = new char[count + margin];
250     int x = offset;
251     int j = 0;
252     for (int i = 0; i < count; i++) {
253         int c = codePoints[x++];
254         if (c < 0) {
255         throw new IllegalArgumentException ();
256         }
257         if (margin <= 0 && (j+1) >= v.length) {
258         if (expansion == 0) {
259             expansion = (((-margin + 1) * count) << 10) / i;
260             expansion >>= 10;
261             if (expansion <= 0) {
262             expansion = 1;
263             }
264         } else {
265             expansion *= 2;
266         }
267         char[] tmp = new char[Math.min(v.length+expansion, count*2)];
268         margin = (tmp.length - v.length) - (count - i);
269         System.arraycopy(v, 0, tmp, 0, j);
270         v = tmp;
271         }
272         if (c < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
273         v[j++] = (char) c;
274         } else if (c <= Character.MAX_CODE_POINT) {
275         Character.toSurrogates(c, v, j);
276         j += 2;
277         margin--;
278         } else {
279         throw new IllegalArgumentException ();
280         }
281     }
282     this.offset = 0;
283     this.value = v;
284     this.count = j;
285     }
286
287     /**
288      * Allocates a new <code>String</code> constructed from a subarray
289      * of an array of 8-bit integer values.
290      * <p>
291      * The <code>offset</code> argument is the index of the first byte
292      * of the subarray, and the <code>count</code> argument specifies the
293      * length of the subarray.
294      * <p>
295      * Each <code>byte</code> in the subarray is converted to a
296      * <code>char</code> as specified in the method above.
297      *
298      * @deprecated This method does not properly convert bytes into characters.
299      * As of JDK&nbsp;1.1, the preferred way to do this is via the
300      * <code>String</code> constructors that take a charset name or that use
301      * the platform's default charset.
302      *
303      * @param ascii the bytes to be converted to characters.
304      * @param hibyte the top 8 bits of each 16-bit Unicode character.
305      * @param offset the initial offset.
306      * @param count the length.
307      * @exception IndexOutOfBoundsException if the <code>offset</code>
308      * or <code>count</code> argument is invalid.
309      * @see java.lang.String#String(byte[], int)
310      * @see java.lang.String#String(byte[], int, int, java.lang.String)
311      * @see java.lang.String#String(byte[], int, int)
312      * @see java.lang.String#String(byte[], java.lang.String)
313      * @see java.lang.String#String(byte[])
314      */
315     @Deprecated
316     public String(byte ascii[], int hibyte, int offset, int count) {
317     checkBounds(ascii, offset, count);
318         char value[] = new char[count];
319
320         if (hibyte == 0) {
321             for (int i = count ; i-- > 0 ;) {
322                 value[i] = (char) (ascii[i + offset] & 0xff);
323             }
324         } else {
325             hibyte <<= 8;
326             for (int i = count ; i-- > 0 ;) {
327                 value[i] = (char) (hibyte | (ascii[i + offset] & 0xff));
328             }
329         }
330     this.offset = 0;
331     this.count = count;
332     this.value = value;
333     }
334
335     /**
336      * Allocates a new <code>String</code> containing characters
337      * constructed from an array of 8-bit integer values. Each character
338      * <i>c</i>in the resulting string is constructed from the
339      * corresponding component <i>b</i> in the byte array such that:
340      * <p><blockquote><pre>
341      * <b><i>c</i></b> == (char)(((hibyte &amp; 0xff) &lt;&lt; 8)
342      * | (<b><i>b</i></b> &amp; 0xff))
343      * </pre></blockquote>
344      *
345      * @deprecated This method does not properly convert bytes into characters.
346      * As of JDK&nbsp;1.1, the preferred way to do this is via the
347      * <code>String</code> constructors that take a charset name or
348      * that use the platform's default charset.
349      *
350      * @param ascii the bytes to be converted to characters.
351      * @param hibyte the top 8 bits of each 16-bit Unicode character.
352      * @see java.lang.String#String(byte[], int, int, java.lang.String)
353      * @see java.lang.String#String(byte[], int, int)
354      * @see java.lang.String#String(byte[], java.lang.String)
355      * @see java.lang.String#String(byte[])
356      */
357     @Deprecated
358     public String(byte ascii[], int hibyte) {
359         this(ascii, hibyte, 0, ascii.length);
360     }
361
362     /* Common private utility method used to bounds check the byte array
363      * and requested offset & length values used by the String(byte[],..)
364      * constructors.
365      */
366     private static void checkBounds(byte[] bytes, int offset, int length) {
367     if (length < 0)
368         throw new StringIndexOutOfBoundsException (length);
369     if (offset < 0)
370         throw new StringIndexOutOfBoundsException (offset);
371     if (offset > bytes.length - length)
372         throw new StringIndexOutOfBoundsException (offset + length);
373     }
374
375     /**
376      * Constructs a new <tt>String</tt> by decoding the specified subarray of
377      * bytes using the specified charset. The length of the new
378      * <tt>String</tt> is a function of the charset, and hence may not be equal
379      * to the length of the subarray.
380      *
381      * <p> The behavior of this constructor when the given bytes are not valid
382      * in the given charset is unspecified. The {@link
383      * java.nio.charset.CharsetDecoder} class should be used when more control
384      * over the decoding process is required.
385      *
386      * @param bytes the bytes to be decoded into characters
387      * @param offset the index of the first byte to decode
388      * @param length the number of bytes to decode
389      * @param charsetName the name of a supported
390      * {@link java.nio.charset.Charset </code>charset<code>}
391      * @throws UnsupportedEncodingException
392      * if the named charset is not supported
393      * @throws IndexOutOfBoundsException
394      * if the <tt>offset</tt> and <tt>length</tt> arguments
395      * index characters outside the bounds of the <tt>bytes</tt>
396      * array
397      * @since JDK1.1
398      */
399     public String(byte bytes[], int offset, int length, String charsetName)
400     throws UnsupportedEncodingException
401     {
402     if (charsetName == null)
403         throw new NullPointerException ("charsetName");
404     checkBounds(bytes, offset, length);
405     char[] v = StringCoding.decode(charsetName, bytes, offset, length);
406     this.offset = 0;
407     this.count = v.length;
408     this.value = v;
409     }
410
411     /**
412      * Constructs a new <tt>String</tt> by decoding the specified array of
413      * bytes using the specified charset. The length of the new
414      * <tt>String</tt> is a function of the charset, and hence may not be equal
415      * to the length of the byte array.
416      *
417      * <p> The behavior of this constructor when the given bytes are not valid
418      * in the given charset is unspecified. The {@link
419      * java.nio.charset.CharsetDecoder} class should be used when more control
420      * over the decoding process is required.
421      *
422      * @param bytes the bytes to be decoded into characters
423      * @param charsetName the name of a supported
424      * {@link java.nio.charset.Charset </code>charset<code>}
425      *
426      * @exception UnsupportedEncodingException
427      * If the named charset is not supported
428      * @since JDK1.1
429      */
430     public String(byte bytes[], String charsetName)
431     throws UnsupportedEncodingException
432     {
433     this(bytes, 0, bytes.length, charsetName);
434     }
435
436     /**
437      * Constructs a new <tt>String</tt> by decoding the specified subarray of
438      * bytes using the platform's default charset. The length of the new
439      * <tt>String</tt> is a function of the charset, and hence may not be equal
440      * to the length of the subarray.
441      *
442      * <p> The behavior of this constructor when the given bytes are not valid
443      * in the default charset is unspecified. The {@link
444      * java.nio.charset.CharsetDecoder} class should be used when more control
445      * over the decoding process is required.
446      *
447      * @param bytes the bytes to be decoded into characters
448      * @param offset the index of the first byte to decode
449      * @param length the number of bytes to decode
450      * @throws IndexOutOfBoundsException
451      * if the <code>offset</code> and the <code>length</code>
452      * arguments index characters outside the bounds of the
453      * <code>bytes</code> array
454      * @since JDK1.1
455      */
456     public String(byte bytes[], int offset, int length) {
457     checkBounds(bytes, offset, length);
458     char[] v = StringCoding.decode(bytes, offset, length);
459     this.offset = 0;
460     this.count = v.length;
461     this.value = v;
462     }
463
464     /**
465      * Constructs a new <tt>String</tt> by decoding the specified array of
466      * bytes using the platform's default charset. The length of the new
467      * <tt>String</tt> is a function of the charset, and hence may not be equal
468      * to the length of the byte array.
469      *
470      * <p> The behavior of this constructor when the given bytes are not valid
471      * in the default charset is unspecified. The {@link
472      * java.nio.charset.CharsetDecoder} class should be used when more control
473      * over the decoding process is required.
474      *
475      * @param bytes the bytes to be decoded into characters
476      * @since JDK1.1
477      */
478     public String(byte bytes[]) {
479     this(bytes, 0, bytes.length);
480     }
481
482     /**
483      * Allocates a new string that contains the sequence of characters
484      * currently contained in the string buffer argument. The contents of
485      * the string buffer are copied; subsequent modification of the string
486      * buffer does not affect the newly created string.
487      *
488      * @param buffer a <code>StringBuffer</code>.
489      */
490     public String(StringBuffer buffer) {
491         String result = buffer.toString();
492         this.value = result.value;
493         this.count = result.count;
494         this.offset = result.offset;
495     }
496
497     /**
498      * Allocates a new string that contains the sequence of characters
499      * currently contained in the string builder argument. The contents of
500      * the string builder are copied; subsequent modification of the string
501      * builder does not affect the newly created string.
502      *
503      * <p>This constructor is provided to ease migration to
504      * <code>StringBuilder</code>. Obtaining a string from a string builder
505      * via the <code>toString</code> method is likely to run faster and is
506      * generally preferred.
507      *
508      * @param builder a <code>StringBuilder</code>
509      * @since 1.5
510      */
511     public String(StringBuilder builder) {
512         String result = builder.toString();
513         this.value = result.value;
514         this.count = result.count;
515         this.offset = result.offset;
516     }
517
518
519     // Package private constructor which shares value array for speed.
520 String(int offset, int count, char value[]) {
521     this.value = value;
522     this.offset = offset;
523     this.count = count;
524     }
525
526     /**
527      * Returns the length of this string.
528      * The length is equal to the number of 16-bit
529      * Unicode characters in the string.
530      *
531      * @return the length of the sequence of characters represented by this
532      * object.
533      */
534     public int length() {
535         return count;
536     }
537
538     /**
539      * Returns the <code>char</code> value at the
540      * specified index. An index ranges from <code>0</code> to
541      * <code>length() - 1</code>. The first <code>char</code> value of the sequence
542      * is at index <code>0</code>, the next at index <code>1</code>,
543      * and so on, as for array indexing.
544      *
545      * <p>If the <code>char</code> value specified by the index is a
546      * <a HREF="Character.html#unicode">surrogate</a>, the surrogate
547      * value is returned.
548      *
549      * @param index the index of the <code>char</code> value.
550      * @return the <code>char</code> value at the specified index of this string.
551      * The first <code>char</code> value is at index <code>0</code>.
552      * @exception IndexOutOfBoundsException if the <code>index</code>
553      * argument is negative or not less than the length of this
554      * string.
555      */
556     public char charAt(int index) {
557         if ((index < 0) || (index >= count)) {
558             throw new StringIndexOutOfBoundsException (index);
559         }
560         return value[index + offset];
561     }
562
563     /**
564      * Returns the character (Unicode code point) at the specified
565      * index. The index refers to <code>char</code> values
566      * (Unicode code units) and ranges from <code>0</code> to
567      * {@link #length()}<code> - 1</code>.
568      *
569      * <p> If the <code>char</code> value specified at the given index
570      * is in the high-surrogate range, the following index is less
571      * than the length of this <code>String</code>, and the
572      * <code>char</code> value at the following index is in the
573      * low-surrogate range, then the supplementary code point
574      * corresponding to this surrogate pair is returned. Otherwise,
575      * the <code>char</code> value at the given index is returned.
576      *
577      * @param index the index to the <code>char</code> values
578      * @return the code point value of the character at the
579      * <code>index</code>
580      * @exception IndexOutOfBoundsException if the <code>index</code>
581      * argument is negative or not less than the length of this
582      * string.
583      * @since 1.5
584      */
585     public int codePointAt(int index) {
586         if ((index < 0) || (index >= count)) {
587             throw new StringIndexOutOfBoundsException (index);
588         }
589         return Character.codePointAtImpl(value, offset + index, offset + count);
590     }
591
592     /**
593      * Returns the character (Unicode code point) before the specified
594      * index. The index refers to <code>char</code> values
595      * (Unicode code units) and ranges from <code>1</code> to {@link
596      * CharSequence#length() length}.
597      *
598      * <p> If the <code>char</code> value at <code>(index - 1)</code>
599      * is in the low-surrogate range, <code>(index - 2)</code> is not
600      * negative, and the <code>char</code> value at <code>(index -
601      * 2)</code> is in the high-surrogate range, then the
602      * supplementary code point value of the surrogate pair is
603      * returned. If the <code>char</code> value at <code>index -
604      * 1</code> is an unpaired low-surrogate or a high-surrogate, the
605      * surrogate value is returned.
606      *
607      * @param index the index following the code point that should be returned
608      * @return the Unicode code point value before the given index.
609      * @exception IndexOutOfBoundsException if the <code>index</code>
610      * argument is less than 1 or greater than the length
611      * of this string.
612      * @since 1.5
613      */
614     public int codePointBefore(int index) {
615     int i = index - 1;
616         if ((i < 0) || (i >= count)) {
617             throw new StringIndexOutOfBoundsException (index);
618         }
619         return Character.codePointBeforeImpl(value, offset + index, offset);
620     }
621
622     /**
623      * Returns the number of Unicode code points in the specified text
624      * range of this <code>String</code>. The text range begins at the
625      * specified <code>beginIndex</code> and extends to the
626      * <code>char</code> at index <code>endIndex - 1</code>. Thus the
627      * length (in <code>char</code>s) of the text range is
628      * <code>endIndex-beginIndex</code>. Unpaired surrogates within
629      * the text range count as one code point each.
630      *
631      * @param beginIndex the index to the first <code>char</code> of
632      * the text range.
633      * @param endIndex the index after the last <code>char</code> of
634      * the text range.
635      * @return the number of Unicode code points in the specified text
636      * range
637      * @exception IndexOutOfBoundsException if the
638      * <code>beginIndex</code> is negative, or <code>endIndex</code>
639      * is larger than the length of this <code>String</code>, or
640      * <code>beginIndex</code> is larger than <code>endIndex</code>.
641      * @since 1.5
642      */
643     public int codePointCount(int beginIndex, int endIndex) {
644     if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
645         throw new IndexOutOfBoundsException ();
646     }
647     return Character.codePointCountImpl(value, offset+beginIndex, endIndex-beginIndex);
648     }
649
650     /**
651      * Returns the index within this <code>String</code> that is
652      * offset from the given <code>index</code> by
653      * <code>codePointOffset</code> code points. Unpaired surrogates
654      * within the text range given by <code>index</code> and
655      * <code>codePointOffset</code> count as one code point each.
656      *
657      * @param index the index to be offset
658      * @param codePointOffset the offset in code points
659      * @return the index within this <code>String</code>
660      * @exception IndexOutOfBoundsException if <code>index</code>
661      * is negative or larger then the length of this
662      * <code>String</code>, or if <code>codePointOffset</code> is positive
663      * and the substring starting with <code>index</code> has fewer
664      * than <code>codePointOffset</code> code points,
665      * or if <code>codePointOffset</code> is negative and the substring
666      * before <code>index</code> has fewer than the absolute value
667      * of <code>codePointOffset</code> code points.
668      * @since 1.5
669      */
670     public int offsetByCodePoints(int index, int codePointOffset) {
671     if (index < 0 || index > count) {
672         throw new IndexOutOfBoundsException ();
673     }
674     return Character.offsetByCodePointsImpl(value, offset, count,
675                         offset+index, codePointOffset);
676     }
677
678     /**
679      * Copy characters from this string into dst starting at dstBegin.
680      * This method doesn't perform any range checking.
681      */
682     void getChars(char dst[], int dstBegin) {
683         System.arraycopy(value, offset, dst, dstBegin, count);
684     }
685
686     /**
687      * Copies characters from this string into the destination character
688      * array.
689      * <p>
690      * The first character to be copied is at index <code>srcBegin</code>;
691      * the last character to be copied is at index <code>srcEnd-1</code>
692      * (thus the total number of characters to be copied is
693      * <code>srcEnd-srcBegin</code>). The characters are copied into the
694      * subarray of <code>dst</code> starting at index <code>dstBegin</code>
695      * and ending at index:
696      * <p><blockquote><pre>
697      * dstbegin + (srcEnd-srcBegin) - 1
698      * </pre></blockquote>
699      *
700      * @param srcBegin index of the first character in the string
701      * to copy.
702      * @param srcEnd index after the last character in the string
703      * to copy.
704      * @param dst the destination array.
705      * @param dstBegin the start offset in the destination array.
706      * @exception IndexOutOfBoundsException If any of the following
707      * is true:
708      * <ul><li><code>srcBegin</code> is negative.
709      * <li><code>srcBegin</code> is greater than <code>srcEnd</code>
710      * <li><code>srcEnd</code> is greater than the length of this
711      * string
712      * <li><code>dstBegin</code> is negative
713      * <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than
714      * <code>dst.length</code></ul>
715      */
716     public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
717         if (srcBegin < 0) {
718             throw new StringIndexOutOfBoundsException (srcBegin);
719         }
720         if (srcEnd > count) {
721             throw new StringIndexOutOfBoundsException (srcEnd);
722         }
723         if (srcBegin > srcEnd) {
724             throw new StringIndexOutOfBoundsException (srcEnd - srcBegin);
725         }
726         System.arraycopy(value, offset + srcBegin, dst, dstBegin,
727              srcEnd - srcBegin);
728     }
729
730     /**
731      * Copies characters from this string into the destination byte
732      * array. Each byte receives the 8 low-order bits of the
733      * corresponding character. The eight high-order bits of each character
734      * are not copied and do not participate in the transfer in any way.
735      * <p>
736      * The first character to be copied is at index <code>srcBegin</code>;
737      * the last character to be copied is at index <code>srcEnd-1</code>.
738      * The total number of characters to be copied is
739      * <code>srcEnd-srcBegin</code>. The characters, converted to bytes,
740      * are copied into the subarray of <code>dst</code> starting at index
741      * <code>dstBegin</code> and ending at index:
742      * <p><blockquote><pre>
743      * dstbegin + (srcEnd-srcBegin) - 1
744      * </pre></blockquote>
745      *
746      * @deprecated This method does not properly convert characters into bytes.
747      * As of JDK&nbsp;1.1, the preferred way to do this is via the
748      * <code>getBytes()</code> method, which uses the platform's default
749      * charset.
750      *
751      * @param srcBegin index of the first character in the string
752      * to copy.
753      * @param srcEnd index after the last character in the string
754      * to copy.
755      * @param dst the destination array.
756      * @param dstBegin the start offset in the destination array.
757      * @exception IndexOutOfBoundsException if any of the following
758      * is true:
759      * <ul><li><code>srcBegin</code> is negative
760      * <li><code>srcBegin</code> is greater than <code>srcEnd</code>
761      * <li><code>srcEnd</code> is greater than the length of this
762      * String
763      * <li><code>dstBegin</code> is negative
764      * <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than
765      * <code>dst.length</code></ul>
766      */
767     @Deprecated
768     public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) {
769         if (srcBegin < 0) {
770             throw new StringIndexOutOfBoundsException (srcBegin);
771         }
772         if (srcEnd > count) {
773             throw new StringIndexOutOfBoundsException (srcEnd);
774         }
775         if (srcBegin > srcEnd) {
776             throw new StringIndexOutOfBoundsException (srcEnd - srcBegin);
777         }
778         int j = dstBegin;
779         int n = offset + srcEnd;
780         int i = offset + srcBegin;
781         char[] val = value; /* avoid getfield opcode */
782
783         while (i < n) {
784             dst[j++] = (byte)val[i++];
785         }
786     }
787
788     /**
789      * Encodes this <tt>String</tt> into a sequence of bytes using the
790      * named charset, storing the result into a new byte array.
791      *
792      * <p> The behavior of this method when this string cannot be encoded in
793      * the given charset is unspecified. The {@link
794      * java.nio.charset.CharsetEncoder} class should be used when more control
795      * over the encoding process is required.
796      *
797      * @param charsetName
798      * the name of a supported
799      * {@link java.nio.charset.Charset </code>charset<code>}
800      *
801      * @return The resultant byte array
802      *
803      * @exception UnsupportedEncodingException
804      * If the named charset is not supported
805      *
806      * @since JDK1.1
807      */
808     public byte[] getBytes(String charsetName)
809     throws UnsupportedEncodingException
810     {
811     if (charsetName == null) throw new NullPointerException ();
812     return StringCoding.encode(charsetName, value, offset, count);
813     }
814
815     /**
816      * Encodes this <tt>String</tt> into a sequence of bytes using the
817      * platform's default charset, storing the result into a new byte array.
818      *
819      * <p> The behavior of this method when this string cannot be encoded in
820      * the default charset is unspecified. The {@link
821      * java.nio.charset.CharsetEncoder} class should be used when more control
822      * over the encoding process is required.
823      *
824      * @return The resultant byte array
825      *
826      * @since JDK1.1
827      */
828     public byte[] getBytes() {
829     return StringCoding.encode(value, offset, count);
830     }
831
832     /**
833      * Compares this string to the specified object.
834      * The result is <code>true</code> if and only if the argument is not
835      * <code>null</code> and is a <code>String</code> object that represents
836      * the same sequence of characters as this object.
837      *
838      * @param anObject the object to compare this <code>String</code>
839      * against.
840      * @return <code>true</code> if the <code>String </code>are equal;
841      * <code>false</code> otherwise.
842      * @see java.lang.String#compareTo(java.lang.String)
843      * @see java.lang.String#equalsIgnoreCase(java.lang.String)
844      */
845     public boolean equals(Object anObject) {
846     if (this == anObject) {
847         return true;
848     }
849     if (anObject instanceof String ) {
850         String anotherString = (String )anObject;
851         int n = count;
852         if (n == anotherString.count) {
853         char v1[] = value;
854         char v2[] = anotherString.value;
855         int i = offset;
856         int j = anotherString.offset;
857         while (n-- != 0) {
858             if (v1[i++] != v2[j++])
859             return false;
860         }
861         return true;
862         }
863     }
864     return false;
865     }
866
867     /**
868      * Returns <tt>true</tt> if and only if this <tt>String</tt> represents
869      * the same sequence of characters as the specified <tt>StringBuffer</tt>.
870      *
871      * @param sb the <tt>StringBuffer</tt> to compare to.
872      * @return <tt>true</tt> if and only if this <tt>String</tt> represents
873      * the same sequence of characters as the specified
874      * <tt>StringBuffer</tt>, otherwise <tt>false</tt>.
875      * @throws NullPointerException if <code>sb</code> is <code>null</code>
876      * @since 1.4
877      */
878     public boolean contentEquals(StringBuffer sb) {
879         synchronized(sb) {
880             return contentEquals((CharSequence )sb);
881         }
882     }
883
884     /**
885      * Returns <tt>true</tt> if and only if this <tt>String</tt> represents
886      * the same sequence of char values as the specified sequence.
887      *
888      * @param cs the sequence to compare to.
889      * @return <tt>true</tt> if and only if this <tt>String</tt> represents
890      * the same sequence of char values as the specified
891      * sequence, otherwise <tt>false</tt>.
892      * @throws NullPointerException if <code>cs</code> is <code>null</code>
893      * @since 1.5
894      */
895     public boolean contentEquals(CharSequence cs) {
896         if (count != cs.length())
897             return false;
898         // Argument is a StringBuffer, StringBuilder
899 if (cs instanceof AbstractStringBuilder ) {
900             char v1[] = value;
901             char v2[] = ((AbstractStringBuilder )cs).getValue();
902             int i = offset;
903             int j = 0;
904             int n = count;
905             while (n-- != 0) {
906                 if (v1[i++] != v2[j++])
907                     return false;
908             }
909         }
910         // Argument is a String
911 if (cs.equals(this))
912             return true;
913         // Argument is a generic CharSequence
914 char v1[] = value;
915         int i = offset;
916         int j = 0;
917         int n = count;
918         while (n-- != 0) {
919             if (v1[i++] != cs.charAt(j++))
920                 return false;
921         }
922         return true;
923     }
924
925     /**
926      * Compares this <code>String</code> to another <code>String</code>,
927      * ignoring case considerations. Two strings are considered equal
928