History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/lang/String.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/lang/String.java+3077−0
@@ -0,0 +1,3077 @@
1+/*
2+ * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.lang;
27+
28+import java.io.ObjectStreamClass;
29+import java.io.ObjectStreamField;
30+import java.io.UnsupportedEncodingException;
31+import java.nio.charset.Charset;
32+import java.util.ArrayList;
33+import java.util.Arrays;
34+import java.util.Comparator;
35+import java.util.Formatter;
36+import java.util.Locale;
37+import java.util.regex.Matcher;
38+import java.util.regex.Pattern;
39+import java.util.regex.PatternSyntaxException;
40+
41+/**
42+ * The <code>String</code> class represents character strings. All
43+ * string literals in Java programs, such as <code>"abc"</code>, are
44+ * implemented as instances of this class.
45+ * <p>
46+ * Strings are constant; their values cannot be changed after they
47+ * are created. String buffers support mutable strings.
48+ * Because String objects are immutable they can be shared. For example:
49+ * <p><blockquote><pre>
50+ * String str = "abc";
51+ * </pre></blockquote><p>
52+ * is equivalent to:
53+ * <p><blockquote><pre>
54+ * char data[] = {'a', 'b', 'c'};
55+ * String str = new String(data);
56+ * </pre></blockquote><p>
57+ * Here are some more examples of how strings can be used:
58+ * <p><blockquote><pre>
59+ * System.out.println("abc");
60+ * String cde = "cde";
61+ * System.out.println("abc" + cde);
62+ * String c = "abc".substring(2,3);
63+ * String d = cde.substring(1, 2);
64+ * </pre></blockquote>
65+ * <p>
66+ * The class <code>String</code> includes methods for examining
67+ * individual characters of the sequence, for comparing strings, for
68+ * searching strings, for extracting substrings, and for creating a
69+ * copy of a string with all characters translated to uppercase or to
70+ * lowercase. Case mapping is based on the Unicode Standard version
71+ * specified by the {@link java.lang.Character Character} class.
72+ * <p>
73+ * The Java language provides special support for the string
74+ * concatenation operator (&nbsp;+&nbsp;), and for conversion of
75+ * other objects to strings. String concatenation is implemented
76+ * through the <code>StringBuilder</code>(or <code>StringBuffer</code>)
77+ * class and its <code>append</code> method.
78+ * String conversions are implemented through the method
79+ * <code>toString</code>, defined by <code>Object</code> and
80+ * inherited by all classes in Java. For additional information on
81+ * string concatenation and conversion, see Gosling, Joy, and Steele,
82+ * <i>The Java Language Specification</i>.
83+ *
84+ * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
85+ * or method in this class will cause a {@link NullPointerException} to be
86+ * thrown.
87+ *
88+ * <p>A <code>String</code> represents a string in the UTF-16 format
89+ * in which <em>supplementary characters</em> are represented by <em>surrogate
90+ * pairs</em> (see the section <a href="Character.html#unicode">Unicode
91+ * Character Representations</a> in the <code>Character</code> class for
92+ * more information).
93+ * Index values refer to <code>char</code> code units, so a supplementary
94+ * character uses two positions in a <code>String</code>.
95+ * <p>The <code>String</code> class provides methods for dealing with
96+ * Unicode code points (i.e., characters), in addition to those for
97+ * dealing with Unicode code units (i.e., <code>char</code> values).
98+ *
99+ * @author Lee Boynton
100+ * @author Arthur van Hoff
101+ * @author Martin Buchholz
102+ * @author Ulf Zibis
103+ * @see java.lang.Object#toString()
104+ * @see java.lang.StringBuffer
105+ * @see java.lang.StringBuilder
106+ * @see java.nio.charset.Charset
107+ * @since JDK1.0
108+ */
109+
110+public final class String
111+ implements java.io.Serializable, Comparable<String>, CharSequence
112+{
113+ /** The value is used for character storage. */
114+ private final char value[];
115+
116+ /** The offset is the first index of the storage that is used. */
117+ private final int offset;
118+
119+ /** The count is the number of characters in the String. */
120+ private final int count;
121+
122+ /** Cache the hash code for the string */
123+ private int hash; // Default to 0
124+
125+ /** use serialVersionUID from JDK 1.0.2 for interoperability */
126+ private static final long serialVersionUID = -6849794470754667710L;
127+
128+ /**
129+ * Class String is special cased within the Serialization Stream Protocol.
130+ *
131+ * A String instance is written initially into an ObjectOutputStream in the
132+ * following format:
133+ * <pre>
134+ * <code>TC_STRING</code> (utf String)
135+ * </pre>
136+ * The String is written by method <code>DataOutput.writeUTF</code>.
137+ * A new handle is generated to refer to all future references to the
138+ * string instance within the stream.
139+ */
140+ private static final ObjectStreamField[] serialPersistentFields =
141+ new ObjectStreamField[0];
142+
143+ /**
144+ * Initializes a newly created {@code String} object so that it represents
145+ * an empty character sequence. Note that use of this constructor is
146+ * unnecessary since Strings are immutable.
147+ */
148+ public String() {
149+ this.offset = 0;
150+ this.count = 0;
151+ this.value = new char[0];
152+ }
153+
154+ /**
155+ * Initializes a newly created {@code String} object so that it represents
156+ * the same sequence of characters as the argument; in other words, the
157+ * newly created string is a copy of the argument string. Unless an
158+ * explicit copy of {@code original} is needed, use of this constructor is
159+ * unnecessary since Strings are immutable.
160+ *
161+ * @param original
162+ * A {@code String}
163+ */
164+ public String(String original) {
165+ int size = original.count;
166+ char[] originalValue = original.value;
167+ char[] v;
168+ if (originalValue.length > size) {
169+ // The array representing the String is bigger than the new
170+ // String itself. Perhaps this constructor is being called
171+ // in order to trim the baggage, so make a copy of the array.
172+ int off = original.offset;
173+ v = Arrays.copyOfRange(originalValue, off, off+size);
174+ } else {
175+ // The array representing the String is the same
176+ // size as the String, so no point in making a copy.
177+ v = originalValue;
178+ }
179+ this.offset = 0;
180+ this.count = size;
181+ this.value = v;
182+ }
183+
184+ /**
185+ * Allocates a new {@code String} so that it represents the sequence of
186+ * characters currently contained in the character array argument. The
187+ * contents of the character array are copied; subsequent modification of
188+ * the character array does not affect the newly created string.
189+ *
190+ * @param value
191+ * The initial value of the string
192+ */
193+ public String(char value[]) {
194+ int size = value.length;
195+ this.offset = 0;
196+ this.count = size;
197+ this.value = Arrays.copyOf(value, size);
198+ }
199+
200+ /**
201+ * Allocates a new {@code String} that contains characters from a subarray
202+ * of the character array argument. The {@code offset} argument is the
203+ * index of the first character of the subarray and the {@code count}
204+ * argument specifies the length of the subarray. The contents of the
205+ * subarray are copied; subsequent modification of the character array does
206+ * not affect the newly created string.
207+ *
208+ * @param value
209+ * Array that is the source of characters
210+ *
211+ * @param offset
212+ * The initial offset
213+ *
214+ * @param count
215+ * The length
216+ *
217+ * @throws IndexOutOfBoundsException
218+ * If the {@code offset} and {@code count} arguments index
219+ * characters outside the bounds of the {@code value} array
220+ */
221+ public String(char value[], int offset, int count) {
222+ if (offset < 0) {
223+ throw new StringIndexOutOfBoundsException(offset);
224+ }
225+ if (count < 0) {
226+ throw new StringIndexOutOfBoundsException(count);
227+ }
228+ // Note: offset or count might be near -1>>>1.
229+ if (offset > value.length - count) {
230+ throw new StringIndexOutOfBoundsException(offset + count);
231+ }
232+ this.offset = 0;
233+ this.count = count;
234+ this.value = Arrays.copyOfRange(value, offset, offset+count);
235+ }
236+
237+ /**
238+ * Allocates a new {@code String} that contains characters from a subarray
239+ * of the <a href="Character.html#unicode">Unicode code point</a> array
240+ * argument. The {@code offset} argument is the index of the first code
241+ * point of the subarray and the {@code count} argument specifies the
242+ * length of the subarray. The contents of the subarray are converted to
243+ * {@code char}s; subsequent modification of the {@code int} array does not
244+ * affect the newly created string.
245+ *
246+ * @param codePoints
247+ * Array that is the source of Unicode code points
248+ *
249+ * @param offset
250+ * The initial offset
251+ *
252+ * @param count
253+ * The length
254+ *
255+ * @throws IllegalArgumentException
256+ * If any invalid Unicode code point is found in {@code
257+ * codePoints}
258+ *
259+ * @throws IndexOutOfBoundsException
260+ * If the {@code offset} and {@code count} arguments index
261+ * characters outside the bounds of the {@code codePoints} array
262+ *
263+ * @since 1.5
264+ */
265+ public String(int[] codePoints, int offset, int count) {
266+ if (offset < 0) {
267+ throw new StringIndexOutOfBoundsException(offset);
268+ }
269+ if (count < 0) {
270+ throw new StringIndexOutOfBoundsException(count);
271+ }
272+ // Note: offset or count might be near -1>>>1.
273+ if (offset > codePoints.length - count) {
274+ throw new StringIndexOutOfBoundsException(offset + count);
275+ }
276+
277+ final int end = offset + count;
278+
279+ // Pass 1: Compute precise size of char[]
280+ int n = count;
281+ for (int i = offset; i < end; i++) {
282+ int c = codePoints[i];
283+ if (Character.isBmpCodePoint(c))
284+ continue;
285+ else if (Character.isValidCodePoint(c))
286+ n++;
287+ else throw new IllegalArgumentException(Integer.toString(c));
288+ }
289+
290+ // Pass 2: Allocate and fill in char[]
291+ final char[] v = new char[n];
292+
293+ for (int i = offset, j = 0; i < end; i++, j++) {
294+ int c = codePoints[i];
295+ if (Character.isBmpCodePoint(c))
296+ v[j] = (char) c;
297+ else
298+ Character.toSurrogates(c, v, j++);
299+ }
300+
301+ this.value = v;
302+ this.count = n;
303+ this.offset = 0;
304+ }
305+
306+ /**
307+ * Allocates a new {@code String} constructed from a subarray of an array
308+ * of 8-bit integer values.
309+ *
310+ * <p> The {@code offset} argument is the index of the first byte of the
311+ * subarray, and the {@code count} argument specifies the length of the
312+ * subarray.
313+ *
314+ * <p> Each {@code byte} in the subarray is converted to a {@code char} as
315+ * specified in the method above.
316+ *
317+ * @deprecated This method does not properly convert bytes into characters.
318+ * As of JDK&nbsp;1.1, the preferred way to do this is via the
319+ * {@code String} constructors that take a {@link
320+ * java.nio.charset.Charset}, charset name, or that use the platform's
321+ * default charset.
322+ *
323+ * @param ascii
324+ * The bytes to be converted to characters
325+ *
326+ * @param hibyte
327+ * The top 8 bits of each 16-bit Unicode code unit
328+ *
329+ * @param offset
330+ * The initial offset
331+ * @param count
332+ * The length
333+ *
334+ * @throws IndexOutOfBoundsException
335+ * If the {@code offset} or {@code count} argument is invalid
336+ *
337+ * @see #String(byte[], int)
338+ * @see #String(byte[], int, int, java.lang.String)
339+ * @see #String(byte[], int, int, java.nio.charset.Charset)
340+ * @see #String(byte[], int, int)
341+ * @see #String(byte[], java.lang.String)
342+ * @see #String(byte[], java.nio.charset.Charset)
343+ * @see #String(byte[])
344+ */
345+ @Deprecated
346+ public String(byte ascii[], int hibyte, int offset, int count) {
347+ checkBounds(ascii, offset, count);
348+ char value[] = new char[count];
349+
350+ if (hibyte == 0) {
351+ for (int i = count ; i-- > 0 ;) {
352+ value[i] = (char) (ascii[i + offset] & 0xff);
353+ }
354+ } else {
355+ hibyte <<= 8;
356+ for (int i = count ; i-- > 0 ;) {
357+ value[i] = (char) (hibyte | (ascii[i + offset] & 0xff));
358+ }
359+ }
360+ this.offset = 0;
361+ this.count = count;
362+ this.value = value;
363+ }
364+
365+ /**
366+ * Allocates a new {@code String} containing characters constructed from
367+ * an array of 8-bit integer values. Each character <i>c</i>in the
368+ * resulting string is constructed from the corresponding component
369+ * <i>b</i> in the byte array such that:
370+ *
371+ * <blockquote><pre>
372+ * <b><i>c</i></b> == (char)(((hibyte &amp; 0xff) &lt;&lt; 8)
373+ * | (<b><i>b</i></b> &amp; 0xff))
374+ * </pre></blockquote>
375+ *
376+ * @deprecated This method does not properly convert bytes into
377+ * characters. As of JDK&nbsp;1.1, the preferred way to do this is via the
378+ * {@code String} constructors that take a {@link
379+ * java.nio.charset.Charset}, charset name, or that use the platform's
380+ * default charset.
381+ *
382+ * @param ascii
383+ * The bytes to be converted to characters
384+ *
385+ * @param hibyte
386+ * The top 8 bits of each 16-bit Unicode code unit
387+ *
388+ * @see #String(byte[], int, int, java.lang.String)
389+ * @see #String(byte[], int, int, java.nio.charset.Charset)
390+ * @see #String(byte[], int, int)
391+ * @see #String(byte[], java.lang.String)
392+ * @see #String(byte[], java.nio.charset.Charset)
393+ * @see #String(byte[])
394+ */
395+ @Deprecated
396+ public String(byte ascii[], int hibyte) {
397+ this(ascii, hibyte, 0, ascii.length);
398+ }
399+
400+ /* Common private utility method used to bounds check the byte array
401+ * and requested offset & length values used by the String(byte[],..)
402+ * constructors.
403+ */
404+ private static void checkBounds(byte[] bytes, int offset, int length) {
405+ if (length < 0)
406+ throw new StringIndexOutOfBoundsException(length);
407+ if (offset < 0)
408+ throw new StringIndexOutOfBoundsException(offset);
409+ if (offset > bytes.length - length)
410+ throw new StringIndexOutOfBoundsException(offset + length);
411+ }
412+
413+ /**
414+ * Constructs a new {@code String} by decoding the specified subarray of
415+ * bytes using the specified charset. The length of the new {@code String}
416+ * is a function of the charset, and hence may not be equal to the length
417+ * of the subarray.
418+ *
419+ * <p> The behavior of this constructor when the given bytes are not valid
420+ * in the given charset is unspecified. The {@link
421+ * java.nio.charset.CharsetDecoder} class should be used when more control
422+ * over the decoding process is required.
423+ *
424+ * @param bytes
425+ * The bytes to be decoded into characters
426+ *
427+ * @param offset
428+ * The index of the first byte to decode
429+ *
430+ * @param length
431+ * The number of bytes to decode
432+
433+ * @param charsetName
434+ * The name of a supported {@linkplain java.nio.charset.Charset
435+ * charset}
436+ *
437+ * @throws UnsupportedEncodingException
438+ * If the named charset is not supported
439+ *
440+ * @throws IndexOutOfBoundsException
441+ * If the {@code offset} and {@code length} arguments index
442+ * characters outside the bounds of the {@code bytes} array
443+ *
444+ * @since JDK1.1
445+ */
446+ public String(byte bytes[], int offset, int length, String charsetName)
447+ throws UnsupportedEncodingException
448+ {
449+ if (charsetName == null)
450+ throw new NullPointerException("charsetName");
451+ checkBounds(bytes, offset, length);
452+ char[] v = StringCoding.decode(charsetName, bytes, offset, length);
453+ this.offset = 0;
454+ this.count = v.length;
455+ this.value = v;
456+ }
457+
458+ /**
459+ * Constructs a new {@code String} by decoding the specified subarray of
460+ * bytes using the specified {@linkplain java.nio.charset.Charset charset}.
461+ * The length of the new {@code String} is a function of the charset, and
462+ * hence may not be equal to the length of the subarray.
463+ *
464+ * <p> This method always replaces malformed-input and unmappable-character
465+ * sequences with this charset's default replacement string. The {@link
466+ * java.nio.charset.CharsetDecoder} class should be used when more control
467+ * over the decoding process is required.
468+ *
469+ * @param bytes
470+ * The bytes to be decoded into characters
471+ *
472+ * @param offset
473+ * The index of the first byte to decode
474+ *
475+ * @param length
476+ * The number of bytes to decode
477+ *
478+ * @param charset
479+ * The {@linkplain java.nio.charset.Charset charset} to be used to
480+ * decode the {@code bytes}
481+ *
482+ * @throws IndexOutOfBoundsException
483+ * If the {@code offset} and {@code length} arguments index
484+ * characters outside the bounds of the {@code bytes} array
485+ *
486+ * @since 1.6
487+ */
488+ public String(byte bytes[], int offset, int length, Charset charset) {
489+ if (charset == null)
490+ throw new NullPointerException("charset");
491+ checkBounds(bytes, offset, length);
492+ char[] v = StringCoding.decode(charset, bytes, offset, length);
493+ this.offset = 0;
494+ this.count = v.length;
495+ this.value = v;
496+ }
497+
498+ /**
499+ * Constructs a new {@code String} by decoding the specified array of bytes
500+ * using the specified {@linkplain java.nio.charset.Charset charset}. The
501+ * length of the new {@code String} is a function of the charset, and hence
502+ * may not be equal to the length of the byte array.
503+ *
504+ * <p> The behavior of this constructor when the given bytes are not valid
505+ * in the given charset is unspecified. The {@link
506+ * java.nio.charset.CharsetDecoder} class should be used when more control
507+ * over the decoding process is required.
508+ *
509+ * @param bytes
510+ * The bytes to be decoded into characters
511+ *
512+ * @param charsetName
513+ * The name of a supported {@linkplain java.nio.charset.Charset
514+ * charset}
515+ *
516+ * @throws UnsupportedEncodingException
517+ * If the named charset is not supported
518+ *
519+ * @since JDK1.1
520+ */
521+ public String(byte bytes[], String charsetName)
522+ throws UnsupportedEncodingException
523+ {
524+ this(bytes, 0, bytes.length, charsetName);
525+ }
526+
527+ /**
528+ * Constructs a new {@code String} by decoding the specified array of
529+ * bytes using the specified {@linkplain java.nio.charset.Charset charset}.
530+ * The length of the new {@code String} is a function of the charset, and
531+ * hence may not be equal to the length of the byte array.
532+ *
533+ * <p> This method always replaces malformed-input and unmappable-character
534+ * sequences with this charset's default replacement string. The {@link
535+ * java.nio.charset.CharsetDecoder} class should be used when more control
536+ * over the decoding process is required.
537+ *
538+ * @param bytes
539+ * The bytes to be decoded into characters
540+ *
541+ * @param charset
542+ * The {@linkplain java.nio.charset.Charset charset} to be used to
543+ * decode the {@code bytes}
544+ *
545+ * @since 1.6
546+ */
547+ public String(byte bytes[], Charset charset) {
548+ this(bytes, 0, bytes.length, charset);
549+ }
550+
551+ /**
552+ * Constructs a new {@code String} by decoding the specified subarray of
553+ * bytes using the platform's default charset. The length of the new
554+ * {@code String} is a function of the charset, and hence may not be equal
555+ * to the length of the subarray.
556+ *
557+ * <p> The behavior of this constructor when the given bytes are not valid
558+ * in the default charset is unspecified. The {@link
559+ * java.nio.charset.CharsetDecoder} class should be used when more control
560+ * over the decoding process is required.
561+ *
562+ * @param bytes
563+ * The bytes to be decoded into characters
564+ *
565+ * @param offset
566+ * The index of the first byte to decode
567+ *
568+ * @param length
569+ * The number of bytes to decode
570+ *
571+ * @throws IndexOutOfBoundsException
572+ * If the {@code offset} and the {@code length} arguments index
573+ * characters outside the bounds of the {@code bytes} array
574+ *
575+ * @since JDK1.1
576+ */
577+ public String(byte bytes[], int offset, int length) {
578+ checkBounds(bytes, offset, length);
579+ char[] v = StringCoding.decode(bytes, offset, length);
580+ this.offset = 0;
581+ this.count = v.length;
582+ this.value = v;
583+ }
584+
585+ /**
586+ * Constructs a new {@code String} by decoding the specified array of bytes
587+ * using the platform's default charset. The length of the new {@code
588+ * String} is a function of the charset, and hence may not be equal to the
589+ * length of the byte array.
590+ *
591+ * <p> The behavior of this constructor when the given bytes are not valid
592+ * in the default charset is unspecified. The {@link
593+ * java.nio.charset.CharsetDecoder} class should be used when more control
594+ * over the decoding process is required.
595+ *
596+ * @param bytes
597+ * The bytes to be decoded into characters
598+ *
599+ * @since JDK1.1
600+ */
601+ public String(byte bytes[]) {
602+ this(bytes, 0, bytes.length);
603+ }
604+
605+ /**
606+ * Allocates a new string that contains the sequence of characters
607+ * currently contained in the string buffer argument. The contents of the
608+ * string buffer are copied; subsequent modification of the string buffer
609+ * does not affect the newly created string.
610+ *
611+ * @param buffer
612+ * A {@code StringBuffer}
613+ */
614+ public String(StringBuffer buffer) {
615+ String result = buffer.toString();
616+ this.value = result.value;
617+ this.count = result.count;
618+ this.offset = result.offset;
619+ }
620+
621+ /**
622+ * Allocates a new string that contains the sequence of characters
623+ * currently contained in the string builder argument. The contents of the
624+ * string builder are copied; subsequent modification of the string builder
625+ * does not affect the newly created string.
626+ *
627+ * <p> This constructor is provided to ease migration to {@code
628+ * StringBuilder}. Obtaining a string from a string builder via the {@code
629+ * toString} method is likely to run faster and is generally preferred.
630+ *
631+ * @param builder
632+ * A {@code StringBuilder}
633+ *
634+ * @since 1.5
635+ */
636+ public String(StringBuilder builder) {
637+ String result = builder.toString();
638+ this.value = result.value;
639+ this.count = result.count;
640+ this.offset = result.offset;
641+ }
642+
643+
644+ // Package private constructor which shares value array for speed.
645+ String(int offset, int count, char value[]) {
646+ this.value = value;
647+ this.offset = offset;
648+ this.count = count;
649+ }
650+
651+ /**
652+ * Returns the length of this string.
653+ * The length is equal to the number of <a href="Character.html#unicode">Unicode
654+ * code units</a> in the string.
655+ *
656+ * @return the length of the sequence of characters represented by this
657+ * object.
658+ */
659+ public int length() {
660+ return count;
661+ }
662+
663+ /**
664+ * Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>.
665+ *
666+ * @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise
667+ * <tt>false</tt>
668+ *
669+ * @since 1.6
670+ */
671+ public boolean isEmpty() {
672+ return count == 0;
673+ }
674+
675+ /**
676+ * Returns the <code>char</code> value at the
677+ * specified index. An index ranges from <code>0</code> to
678+ * <code>length() - 1</code>. The first <code>char</code> value of the sequence
679+ * is at index <code>0</code>, the next at index <code>1</code>,
680+ * and so on, as for array indexing.
681+ *
682+ * <p>If the <code>char</code> value specified by the index is a
683+ * <a href="Character.html#unicode">surrogate</a>, the surrogate
684+ * value is returned.
685+ *
686+ * @param index the index of the <code>char</code> value.
687+ * @return the <code>char</code> value at the specified index of this string.
688+ * The first <code>char</code> value is at index <code>0</code>.
689+ * @exception IndexOutOfBoundsException if the <code>index</code>
690+ * argument is negative or not less than the length of this
691+ * string.
692+ */
693+ public char charAt(int index) {
694+ if ((index < 0) || (index >= count)) {
695+ throw new StringIndexOutOfBoundsException(index);
696+ }
697+ return value[index + offset];
698+ }
699+
700+ /**
701+ * Returns the character (Unicode code point) at the specified
702+ * index. The index refers to <code>char</code> values
703+ * (Unicode code units) and ranges from <code>0</code> to
704+ * {@link #length()}<code> - 1</code>.
705+ *
706+ * <p> If the <code>char</code> value specified at the given index
707+ * is in the high-surrogate range, the following index is less
708+ * than the length of this <code>String</code>, and the
709+ * <code>char</code> value at the following index is in the
710+ * low-surrogate range, then the supplementary code point
711+ * corresponding to this surrogate pair is returned. Otherwise,
712+ * the <code>char</code> value at the given index is returned.
713+ *
714+ * @param index the index to the <code>char</code> values
715+ * @return the code point value of the character at the
716+ * <code>index</code>
717+ * @exception IndexOutOfBoundsException if the <code>index</code>
718+ * argument is negative or not less than the length of this
719+ * string.
720+ * @since 1.5
721+ */
722+ public int codePointAt(int index) {
723+ if ((index < 0) || (index >= count)) {
724+ throw new StringIndexOutOfBoundsException(index);
725+ }
726+ return Character.codePointAtImpl(value, offset + index, offset + count);
727+ }
728+
729+ /**
730+ * Returns the character (Unicode code point) before the specified
731+ * index. The index refers to <code>char</code> values
732+ * (Unicode code units) and ranges from <code>1</code> to {@link
733+ * CharSequence#length() length}.
734+ *
735+ * <p> If the <code>char</code> value at <code>(index - 1)</code>
736+ * is in the low-surrogate range, <code>(index - 2)</code> is not
737+ * negative, and the <code>char</code> value at <code>(index -
738+ * 2)</code> is in the high-surrogate range, then the
739+ * supplementary code point value of the surrogate pair is
740+ * returned. If the <code>char</code> value at <code>index -
741+ * 1</code> is an unpaired low-surrogate or a high-surrogate, the
742+ * surrogate value is returned.
743+ *
744+ * @param index the index following the code point that should be returned
745+ * @return the Unicode code point value before the given index.
746+ * @exception IndexOutOfBoundsException if the <code>index</code>
747+ * argument is less than 1 or greater than the length
748+ * of this string.
749+ * @since 1.5
750+ */
751+ public int codePointBefore(int index) {
752+ int i = index - 1;
753+ if ((i < 0) || (i >= count)) {
754+ throw new StringIndexOutOfBoundsException(index);
755+ }
756+ return Character.codePointBeforeImpl(value, offset + index, offset);
757+ }
758+
759+ /**
760+ * Returns the number of Unicode code points in the specified text
761+ * range of this <code>String</code>. The text range begins at the
762+ * specified <code>beginIndex</code> and extends to the
763+ * <code>char</code> at index <code>endIndex - 1</code>. Thus the
764+ * length (in <code>char</code>s) of the text range is
765+ * <code>endIndex-beginIndex</code>. Unpaired surrogates within
766+ * the text range count as one code point each.
767+ *
768+ * @param beginIndex the index to the first <code>char</code> of
769+ * the text range.
770+ * @param endIndex the index after the last <code>char</code> of
771+ * the text range.
772+ * @return the number of Unicode code points in the specified text
773+ * range
774+ * @exception IndexOutOfBoundsException if the
775+ * <code>beginIndex</code> is negative, or <code>endIndex</code>
776+ * is larger than the length of this <code>String</code>, or
777+ * <code>beginIndex</code> is larger than <code>endIndex</code>.
778+ * @since 1.5
779+ */
780+ public int codePointCount(int beginIndex, int endIndex) {
781+ if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
782+ throw new IndexOutOfBoundsException();
783+ }
784+ return Character.codePointCountImpl(value, offset+beginIndex, endIndex-beginIndex);
785+ }
786+
787+ /**
788+ * Returns the index within this <code>String</code> that is
789+ * offset from the given <code>index</code> by
790+ * <code>codePointOffset</code> code points. Unpaired surrogates
791+ * within the text range given by <code>index</code> and
792+ * <code>codePointOffset</code> count as one code point each.
793+ *
794+ * @param index the index to be offset
795+ * @param codePointOffset the offset in code points
796+ * @return the index within this <code>String</code>
797+ * @exception IndexOutOfBoundsException if <code>index</code>
798+ * is negative or larger then the length of this
799+ * <code>String</code>, or if <code>codePointOffset</code> is positive
800+ * and the substring starting with <code>index</code> has fewer
801+ * than <code>codePointOffset</code> code points,
802+ * or if <code>codePointOffset</code> is negative and the substring
803+ * before <code>index</code> has fewer than the absolute value
804+ * of <code>codePointOffset</code> code points.
805+ * @since 1.5
806+ */
807+ public int offsetByCodePoints(int index, int codePointOffset) {
808+ if (index < 0 || index > count) {
809+ throw new IndexOutOfBoundsException();
810+ }
811+ return Character.offsetByCodePointsImpl(value, offset, count,
812+ offset+index, codePointOffset) - offset;
813+ }
814+
815+ /**
816+ * Copy characters from this string into dst starting at dstBegin.
817+ * This method doesn't perform any range checking.
818+ */
819+ void getChars(char dst[], int dstBegin) {
820+ System.arraycopy(value, offset, dst, dstBegin, count);
821+ }
822+
823+ /**
824+ * Copies characters from this string into the destination character
825+ * array.
826+ * <p>
827+ * The first character to be copied is at index <code>srcBegin</code>;
828+ * the last character to be copied is at index <code>srcEnd-1</code>
829+ * (thus the total number of characters to be copied is
830+ * <code>srcEnd-srcBegin</code>). The characters are copied into the
831+ * subarray of <code>dst</code> starting at index <code>dstBegin</code>
832+ * and ending at index:
833+ * <p><blockquote><pre>
834+ * dstbegin + (srcEnd-srcBegin) - 1
835+ * </pre></blockquote>
836+ *
837+ * @param srcBegin index of the first character in the string
838+ * to copy.
839+ * @param srcEnd index after the last character in the string
840+ * to copy.
841+ * @param dst the destination array.
842+ * @param dstBegin the start offset in the destination array.
843+ * @exception IndexOutOfBoundsException If any of the following
844+ * is true:
845+ * <ul><li><code>srcBegin</code> is negative.
846+ * <li><code>srcBegin</code> is greater than <code>srcEnd</code>
847+ * <li><code>srcEnd</code> is greater than the length of this
848+ * string
849+ * <li><code>dstBegin</code> is negative
850+ * <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than
851+ * <code>dst.length</code></ul>
852+ */
853+ public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
854+ if (srcBegin < 0) {
855+ throw new StringIndexOutOfBoundsException(srcBegin);
856+ }
857+ if (srcEnd > count) {
858+ throw new StringIndexOutOfBoundsException(srcEnd);
859+ }
860+ if (srcBegin > srcEnd) {
861+ throw new StringIndexOutOfBoundsException(srcEnd - srcBegin);
862+ }
863+ System.arraycopy(value, offset + srcBegin, dst, dstBegin,
864+ srcEnd - srcBegin);
865+ }
866+
867+ /**
868+ * Copies characters from this string into the destination byte array. Each
869+ * byte receives the 8 low-order bits of the corresponding character. The
870+ * eight high-order bits of each character are not copied and do not
871+ * participate in the transfer in any way.
872+ *
873+ * <p> The first character to be copied is at index {@code srcBegin}; the
874+ * last character to be copied is at index {@code srcEnd-1}. The total
875+ * number of characters to be copied is {@code srcEnd-srcBegin}. The
876+ * characters, converted to bytes, are copied into the subarray of {@code
877+ * dst} starting at index {@code dstBegin} and ending at index:
878+ *
879+ * <blockquote><pre>
880+ * dstbegin + (srcEnd-srcBegin) - 1
881+ * </pre></blockquote>
882+ *
883+ * @deprecated This method does not properly convert characters into
884+ * bytes. As of JDK&nbsp;1.1, the preferred way to do this is via the
885+ * {@link #getBytes()} method, which uses the platform's default charset.
886+ *
887+ * @param srcBegin
888+ * Index of the first character in the string to copy
889+ *
890+ * @param srcEnd
891+ * Index after the last character in the string to copy
892+ *
893+ * @param dst
894+ * The destination array
895+ *
896+ * @param dstBegin
897+ * The start offset in the destination array
898+ *
899+ * @throws IndexOutOfBoundsException
900+ * If any of the following is true:
901+ * <ul>
902+ * <li> {@code srcBegin} is negative
903+ * <li> {@code srcBegin} is greater than {@code srcEnd}
904+ * <li> {@code srcEnd} is greater than the length of this String
905+ * <li> {@code dstBegin} is negative
906+ * <li> {@code dstBegin+(srcEnd-srcBegin)} is larger than {@code
907+ * dst.length}
908+ * </ul>
909+ */
910+ @Deprecated
911+ public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) {
912+ if (srcBegin < 0) {
913+ throw new StringIndexOutOfBoundsException(srcBegin);
914+ }
915+ if (srcEnd > count) {
916+ throw new StringIndexOutOfBoundsException(srcEnd);
917+ }
918+ if (srcBegin > srcEnd) {
919+ throw new StringIndexOutOfBoundsException(srcEnd - srcBegin);
920+ }
921+ int j = dstBegin;
922+ int n = offset + srcEnd;
923+ int i = offset + srcBegin;
924+ char[] val = value; /* avoid getfield opcode */
925+
926+ while (i < n) {
927+ dst[j++] = (byte)val[i++];
928+ }
929+ }
930+
931+ /**
932+ * Encodes this {@code String} into a sequence of bytes using the named
933+ * charset, storing the result into a new byte array.
934+ *
935+ * <p> The behavior of this method when this string cannot be encoded in
936+ * the given charset is unspecified. The {@link
937+ * java.nio.charset.CharsetEncoder} class should be used when more control
938+ * over the encoding process is required.
939+ *
940+ * @param charsetName
941+ * The name of a supported {@linkplain java.nio.charset.Charset
942+ * charset}
943+ *
944+ * @return The resultant byte array
945+ *
946+ * @throws UnsupportedEncodingException
947+ * If the named charset is not supported
948+ *
949+ * @since JDK1.1
950+ */
951+ public byte[] getBytes(String charsetName)
952+ throws UnsupportedEncodingException
953+ {
954+ if (charsetName == null) throw new NullPointerException();
955+ return StringCoding.encode(charsetName, value, offset, count);
956+ }
957+
958+ /**
959+ * Encodes this {@code String} into a sequence of bytes using the given
960+ * {@linkplain java.nio.charset.Charset charset}, storing the result into a
961+ * new byte array.
962+ *
963+ * <p> This method always replaces malformed-input and unmappable-character
964+ * sequences with this charset's default replacement byte array. The
965+ * {@link java.nio.charset.CharsetEncoder} class should be used when more
966+ * control over the encoding process is required.
967+ *
968+ * @param charset
969+ * The {@linkplain java.nio.charset.Charset} to be used to encode
970+ * the {@code String}
971+ *
972+ * @return The resultant byte array
973+ *
974+ * @since 1.6
975+ */
976+ public byte[] getBytes(Charset charset) {
977+ if (charset == null) throw new NullPointerException();
978+ return StringCoding.encode(charset, value, offset, count);
979+ }
980+
981+ /**
982+ * Encodes this {@code String} into a sequence of bytes using the
983+ * platform's default charset, storing the result into a new byte array.
984+ *
985+ * <p> The behavior of this method when this string cannot be encoded in
986+ * the default charset is unspecified. The {@link
987+ * java.nio.charset.CharsetEncoder} class should be used when more control
988+ * over the encoding process is required.
989+ *
990+ * @return The resultant byte array
991+ *
992+ * @since JDK1.1
993+ */
994+ public byte[] getBytes() {
995+ return StringCoding.encode(value, offset, count);
996+ }
997+
998+ /**
999+ * Compares this string to the specified object. The result is {@code
1000+ * true} if and only if the argument is not {@code null} and is a {@code
1001+ * String} object that represents the same sequence of characters as this
1002+ * object.
1003+ *
1004+ * @param anObject
1005+ * The object to compare this {@code String} against
1006+ *
1007+ * @return {@code true} if the given object represents a {@code String}
1008+ * equivalent to this string, {@code false} otherwise
1009+ *
1010+ * @see #compareTo(String)
1011+ * @see #equalsIgnoreCase(String)
1012+ */
1013+ public boolean equals(Object anObject) {
1014+ if (this == anObject) {
1015+ return true;
1016+ }
1017+ if (anObject instanceof String) {
1018+ String anotherString = (String)anObject;
1019+ int n = count;
1020+ if (n == anotherString.count) {
1021+ char v1[] = value;
1022+ char v2[] = anotherString.value;
1023+ int i = offset;
1024+ int j = anotherString.offset;
1025+ while (n-- != 0) {
1026+ if (v1[i++] != v2[j++])
1027+ return false;
1028+ }
1029+ return true;
1030+ }
1031+ }
1032+ return false;
1033+ }
1034+
1035+ /**
1036+ * Compares this string to the specified {@code StringBuffer}. The result
1037+ * is {@code true} if and only if this {@code String} represents the same
1038+ * sequence of characters as the specified {@code StringBuffer}.
1039+ *
1040+ * @param sb
1041+ * The {@code StringBuffer} to compare this {@code String} against
1042+ *
1043+ * @return {@code true} if this {@code String} represents the same
1044+ * sequence of characters as the specified {@code StringBuffer},
1045+ * {@code false} otherwise
1046+ *
1047+ * @since 1.4
1048+ */
1049+ public boolean contentEquals(StringBuffer sb) {
1050+ synchronized(sb) {
1051+ return contentEquals((CharSequence)sb);
1052+ }
1053+ }
1054+
1055+ /**
1056+ * Compares this string to the specified {@code CharSequence}. The result
1057+ * is {@code true} if and only if this {@code String} represents the same
1058+ * sequence of char values as the specified sequence.
1059+ *
1060+ * @param cs
1061+ * The sequence to compare this {@code String} against
1062+ *
1063+ * @return {@code true} if this {@code String} represents the same
1064+ * sequence of char values as the specified sequence, {@code
1065+ * false} otherwise
1066+ *
1067+ * @since 1.5
1068+ */
1069+ public boolean contentEquals(CharSequence cs) {
1070+ if (count != cs.length())
1071+ return false;
1072+ // Argument is a StringBuffer, StringBuilder
1073+ if (cs instanceof AbstractStringBuilder) {
1074+ char v1[] = value;
1075+ char v2[] = ((AbstractStringBuilder)cs).getValue();
1076+ int i = offset;
1077+ int j = 0;
1078+ int n = count;
1079+ while (n-- != 0) {
1080+ if (v1[i++] != v2[j++])
1081+ return false;
1082+ }
1083+ return true;
1084+ }
1085+ // Argument is a String
1086+ if (cs.equals(this))
1087+ return true;
1088+ // Argument is a generic CharSequence
1089+ char v1[] = value;
1090+ int i = offset;
1091+ int j = 0;
1092+ int n = count;
1093+ while (n-- != 0) {
1094+ if (v1[i++] != cs.charAt(j++))
1095+ return false;
1096+ }
1097+ return true;
1098+ }
1099+
1100+ /**
1101+ * Compares this {@code String} to another {@code String}, ignoring case
1102+ * considerations. Two strings are considered equal ignoring case if they
1103+ * are of the same length and corresponding characters in the two strings
1104+ * are equal ignoring case.
1105+ *
1106+ * <p> Two characters {@code c1} and {@code c2} are considered the same
1107+ * ignoring case if at least one of the following is true:
1108+ * <ul>
1109+ * <li> The two characters are the same (as compared by the
1110+ * {@code ==} operator)
1111+ * <li> Applying the method {@link
1112+ * java.lang.Character#toUpperCase(char)} to each character
1113+ * produces the same result
1114+ * <li> Applying the method {@link
1115+ * java.lang.Character#toLowerCase(char)} to each character
1116+ * produces the same result
1117+ * </ul>
1118+ *
1119+ * @param anotherString
1120+ * The {@code String} to compare this {@code String} against
1121+ *
1122+ * @return {@code true} if the argument is not {@code null} and it
1123+ * represents an equivalent {@code String} ignoring case; {@code
1124+ * false} otherwise
1125+ *
1126+ * @see #equals(Object)
1127+ */
1128+ public boolean equalsIgnoreCase(String anotherString) {
1129+ return (this == anotherString) ? true :
1130+ (anotherString != null) && (anotherString.count == count) &&
1131+ regionMatches(true, 0, anotherString, 0, count);
1132+ }
1133+
1134+ /**
1135+ * Compares two strings lexicographically.
1136+ * The comparison is based on the Unicode value of each character in
1137+ * the strings. The character sequence represented by this
1138+ * <code>String</code> object is compared lexicographically to the
1139+ * character sequence represented by the argument string. The result is
1140+ * a negative integer if this <code>String</code> object
1141+ * lexicographically precedes the argument string. The result is a
1142+ * positive integer if this <code>String</code> object lexicographically
1143+ * follows the argument string. The result is zero if the strings
1144+ * are equal; <code>compareTo</code> returns <code>0</code> exactly when
1145+ * the {@link #equals(Object)} method would return <code>true</code>.
1146+ * <p>
1147+ * This is the definition of lexicographic ordering. If two strings are
1148+ * different, then either they have different characters at some index
1149+ * that is a valid index for both strings, or their lengths are different,
1150+ * or both. If they have different characters at one or more index
1151+ * positions, let <i>k</i> be the smallest such index; then the string
1152+ * whose character at position <i>k</i> has the smaller value, as
1153+ * determined by using the &lt; operator, lexicographically precedes the
1154+ * other string. In this case, <code>compareTo</code> returns the
1155+ * difference of the two character values at position <code>k</code> in
1156+ * the two string -- that is, the value:
1157+ * <blockquote><pre>
1158+ * this.charAt(k)-anotherString.charAt(k)
1159+ * </pre></blockquote>
1160+ * If there is no index position at which they differ, then the shorter
1161+ * string lexicographically precedes the longer string. In this case,
1162+ * <code>compareTo</code> returns the difference of the lengths of the
1163+ * strings -- that is, the value:
1164+ * <blockquote><pre>
1165+ * this.length()-anotherString.length()
1166+ * </pre></blockquote>
1167+ *
1168+ * @param anotherString the <code>String</code> to be compared.
1169+ * @return the value <code>0</code> if the argument string is equal to
1170+ * this string; a value less than <code>0</code> if this string
1171+ * is lexicographically less than the string argument; and a
1172+ * value greater than <code>0</code> if this string is
1173+ * lexicographically greater than the string argument.
1174+ */
1175+ public int compareTo(String anotherString) {
1176+ int len1 = count;
1177+ int len2 = anotherString.count;
1178+ int n = Math.min(len1, len2);
1179+ char v1[] = value;
1180+ char v2[] = anotherString.value;
1181+ int i = offset;
1182+ int j = anotherString.offset;
1183+
1184+ if (i == j) {
1185+ int k = i;
1186+ int lim = n + i;
1187+ while (k < lim) {
1188+ char c1 = v1[k];
1189+ char c2 = v2[k];
1190+ if (c1 != c2) {
1191+ return c1 - c2;
1192+ }
1193+ k++;
1194+ }
1195+ } else {
1196+ while (n-- != 0) {
1197+ char c1 = v1[i++];
1198+ char c2 = v2[j++];
1199+ if (c1 != c2) {
1200+ return c1 - c2;
1201+ }
1202+ }
1203+ }
1204+ return len1 - len2;
1205+ }
1206+
1207+ /**
1208+ * A Comparator that orders <code>String</code> objects as by
1209+ * <code>compareToIgnoreCase</code>. This comparator is serializable.
1210+ * <p>
1211+ * Note that this Comparator does <em>not</em> take locale into account,
1212+ * and will result in an unsatisfactory ordering for certain locales.
1213+ * The java.text package provides <em>Collators</em> to allow
1214+ * locale-sensitive ordering.
1215+ *
1216+ * @see java.text.Collator#compare(String, String)
1217+ * @since 1.2
1218+ */
1219+ public static final Comparator<String> CASE_INSENSITIVE_ORDER
1220+ = new CaseInsensitiveComparator();
1221+ private static class CaseInsensitiveComparator
1222+ implements Comparator<String>, java.io.Serializable {
1223+ // use serialVersionUID from JDK 1.2.2 for interoperability
1224+ private static final long serialVersionUID = 8575799808933029326L;
1225+
1226+ public int compare(String s1, String s2) {
1227+ int n1 = s1.length();
1228+ int n2 = s2.length();
1229+ int min = Math.min(n1, n2);
1230+ for (int i = 0; i < min; i++) {
1231+ char c1 = s1.charAt(i);
1232+ char c2 = s2.charAt(i);
1233+ if (c1 != c2) {
1234+ c1 = Character.toUpperCase(c1);
1235+ c2 = Character.toUpperCase(c2);
1236+ if (c1 != c2) {
1237+ c1 = Character.toLowerCase(c1);
1238+ c2 = Character.toLowerCase(c2);
1239+ if (c1 != c2) {
1240+ // No overflow because of numeric promotion
1241+ return c1 - c2;
1242+ }
1243+ }
1244+ }
1245+ }
1246+ return n1 - n2;
1247+ }
1248+ }
1249+
1250+ /**
1251+ * Compares two strings lexicographically, ignoring case
1252+ * differences. This method returns an integer whose sign is that of
1253+ * calling <code>compareTo</code> with normalized versions of the strings
1254+ * where case differences have been eliminated by calling
1255+ * <code>Character.toLowerCase(Character.toUpperCase(character))</code> on
1256+ * each character.
1257+ * <p>
1258+ * Note that this method does <em>not</em> take locale into account,
1259+ * and will result in an unsatisfactory ordering for certain locales.
1260+ * The java.text package provides <em>collators</em> to allow
1261+ * locale-sensitive ordering.
1262+ *
1263+ * @param str the <code>String</code> to be compared.
1264+ * @return a negative integer, zero, or a positive integer as the
1265+ * specified String is greater than, equal to, or less
1266+ * than this String, ignoring case considerations.
1267+ * @see java.text.Collator#compare(String, String)
1268+ * @since 1.2
1269+ */
1270+ public int compareToIgnoreCase(String str) {
1271+ return CASE_INSENSITIVE_ORDER.compare(this, str);
1272+ }
1273+
1274+ /**
1275+ * Tests if two string regions are equal.
1276+ * <p>
1277+ * A substring of this <tt>String</tt> object is compared to a substring
1278+ * of the argument other. The result is true if these substrings
1279+ * represent identical character sequences. The substring of this
1280+ * <tt>String</tt> object to be compared begins at index <tt>toffset</tt>
1281+ * and has length <tt>len</tt>. The substring of other to be compared
1282+ * begins at index <tt>ooffset</tt> and has length <tt>len</tt>. The
1283+ * result is <tt>false</tt> if and only if at least one of the following
1284+ * is true:
1285+ * <ul><li><tt>toffset</tt> is negative.
1286+ * <li><tt>ooffset</tt> is negative.
1287+ * <li><tt>toffset+len</tt> is greater than the length of this
1288+ * <tt>String</tt> object.
1289+ * <li><tt>ooffset+len</tt> is greater than the length of the other
1290+ * argument.
1291+ * <li>There is some nonnegative integer <i>k</i> less than <tt>len</tt>
1292+ * such that:
1293+ * <tt>this.charAt(toffset+<i>k</i>)&nbsp;!=&nbsp;other.charAt(ooffset+<i>k</i>)</tt>
1294+ * </ul>
1295+ *
1296+ * @param toffset the starting offset of the subregion in this string.
1297+ * @param other the string argument.
1298+ * @param ooffset the starting offset of the subregion in the string
1299+ * argument.
1300+ * @param len the number of characters to compare.
1301+ * @return <code>true</code> if the specified subregion of this string
1302+ * exactly matches the specified subregion of the string argument;
1303+ * <code>false</code> otherwise.
1304+ */
1305+ public boolean regionMatches(int toffset, String other, int ooffset,
1306+ int len) {
1307+ char ta[] = value;
1308+ int to = offset + toffset;
1309+ char pa[] = other.value;
1310+ int po = other.offset + ooffset;
1311+ // Note: toffset, ooffset, or len might be near -1>>>1.
1312+ if ((ooffset < 0) || (toffset < 0) || (toffset > (long)count - len)
1313+ || (ooffset > (long)other.count - len)) {
1314+ return false;
1315+ }
1316+ while (len-- > 0) {
1317+ if (ta[to++] != pa[po++]) {
1318+ return false;
1319+ }
1320+ }
1321+ return true;
1322+ }
1323+
1324+ /**
1325+ * Tests if two string regions are equal.
1326+ * <p>
1327+ * A substring of this <tt>String</tt> object is compared to a substring
1328+ * of the argument <tt>other</tt>. The result is <tt>true</tt> if these
1329+ * substrings represent character sequences that are the same, ignoring
1330+ * case if and only if <tt>ignoreCase</tt> is true. The substring of
1331+ * this <tt>String</tt> object to be compared begins at index
1332+ * <tt>toffset</tt> and has length <tt>len</tt>. The substring of
1333+ * <tt>other</tt> to be compared begins at index <tt>ooffset</tt> and
1334+ * has length <tt>len</tt>. The result is <tt>false</tt> if and only if
1335+ * at least one of the following is true:
1336+ * <ul><li><tt>toffset</tt> is negative.
1337+ * <li><tt>ooffset</tt> is negative.
1338+ * <li><tt>toffset+len</tt> is greater than the length of this
1339+ * <tt>String</tt> object.
1340+ * <li><tt>ooffset+len</tt> is greater than the length of the other
1341+ * argument.
1342+ * <li><tt>ignoreCase</tt> is <tt>false</tt> and there is some nonnegative
1343+ * integer <i>k</i> less than <tt>len</tt> such that:
1344+ * <blockquote><pre>
1345+ * this.charAt(toffset+k) != other.charAt(ooffset+k)
1346+ * </pre></blockquote>
1347+ * <li><tt>ignoreCase</tt> is <tt>true</tt> and there is some nonnegative
1348+ * integer <i>k</i> less than <tt>len</tt> such that:
1349+ * <blockquote><pre>
1350+ * Character.toLowerCase(this.charAt(toffset+k)) !=
1351+ Character.toLowerCase(other.charAt(ooffset+k))
1352+ * </pre></blockquote>
1353+ * and:
1354+ * <blockquote><pre>
1355+ * Character.toUpperCase(this.charAt(toffset+k)) !=
1356+ * Character.toUpperCase(other.charAt(ooffset+k))
1357+ * </pre></blockquote>
1358+ * </ul>
1359+ *
1360+ * @param ignoreCase if <code>true</code>, ignore case when comparing
1361+ * characters.
1362+ * @param toffset the starting offset of the subregion in this
1363+ * string.
1364+ * @param other the string argument.
1365+ * @param ooffset the starting offset of the subregion in the string
1366+ * argument.
1367+ * @param len the number of characters to compare.
1368+ * @return <code>true</code> if the specified subregion of this string
1369+ * matches the specified subregion of the string argument;
1370+ * <code>false</code> otherwise. Whether the matching is exact
1371+ * or case insensitive depends on the <code>ignoreCase</code>
1372+ * argument.
1373+ */
1374+ public boolean regionMatches(boolean ignoreCase, int toffset,
1375+ String other, int ooffset, int len) {
1376+ char ta[] = value;
1377+ int to = offset + toffset;
1378+ char pa[] = other.value;
1379+ int po = other.offset + ooffset;
1380+ // Note: toffset, ooffset, or len might be near -1>>>1.
1381+ if ((ooffset < 0) || (toffset < 0) || (toffset > (long)count - len) ||
1382+ (ooffset > (long)other.count - len)) {
1383+ return false;
1384+ }
1385+ while (len-- > 0) {
1386+ char c1 = ta[to++];
1387+ char c2 = pa[po++];
1388+ if (c1 == c2) {
1389+ continue;
1390+ }
1391+ if (ignoreCase) {
1392+ // If characters don't match but case may be ignored,
1393+ // try converting both characters to uppercase.
1394+ // If the results match, then the comparison scan should
1395+ // continue.
1396+ char u1 = Character.toUpperCase(c1);
1397+ char u2 = Character.toUpperCase(c2);
1398+ if (u1 == u2) {
1399+ continue;
1400+ }
1401+ // Unfortunately, conversion to uppercase does not work properly
1402+ // for the Georgian alphabet, which has strange rules about case
1403+ // conversion. So we need to make one last check before
1404+ // exiting.
1405+ if (Character.toLowerCase(u1) == Character.toLowerCase(u2)) {
1406+ continue;
1407+ }
1408+ }
1409+ return false;
1410+ }
1411+ return true;
1412+ }
1413+
1414+ /**
1415+ * Tests if the substring of this string beginning at the
1416+ * specified index starts with the specified prefix.
1417+ *
1418+ * @param prefix the prefix.
1419+ * @param toffset where to begin looking in this string.
1420+ * @return <code>true</code> if the character sequence represented by the
1421+ * argument is a prefix of the substring of this object starting
1422+ * at index <code>toffset</code>; <code>false</code> otherwise.
1423+ * The result is <code>false</code> if <code>toffset</code> is
1424+ * negative or greater than the length of this
1425+ * <code>String</code> object; otherwise the result is the same
1426+ * as the result of the expression
1427+ * <pre>
1428+ * this.substring(toffset).startsWith(prefix)
1429+ * </pre>
1430+ */
1431+ public boolean startsWith(String prefix, int toffset) {
1432+ char ta[] = value;
1433+ int to = offset + toffset;
1434+ char pa[] = prefix.value;
1435+ int po = prefix.offset;
1436+ int pc = prefix.count;
1437+ // Note: toffset might be near -1>>>1.
1438+ if ((toffset < 0) || (toffset > count - pc)) {
1439+ return false;
1440+ }
1441+ while (--pc >= 0) {
1442+ if (ta[to++] != pa[po++]) {
1443+ return false;
1444+ }
1445+ }
1446+ return true;
1447+ }
1448+
1449+ /**
1450+ * Tests if this string starts with the specified prefix.
1451+ *
1452+ * @param prefix the prefix.
1453+ * @return <code>true</code> if the character sequence represented by the
1454+ * argument is a prefix of the character sequence represented by
1455+ * this string; <code>false</code> otherwise.
1456+ * Note also that <code>true</code> will be returned if the
1457+ * argument is an empty string or is equal to this
1458+ * <code>String</code> object as determined by the
1459+ * {@link #equals(Object)} method.
1460+ * @since 1. 0
1461+ */
1462+ public boolean startsWith(String prefix) {
1463+ return startsWith(prefix, 0);
1464+ }
1465+
1466+ /**
1467+ * Tests if this string ends with the specified suffix.
1468+ *
1469+ * @param suffix the suffix.
1470+ * @return <code>true</code> if the character sequence represented by the
1471+ * argument is a suffix of the character sequence represented by
1472+ * this object; <code>false</code> otherwise. Note that the
1473+ * result will be <code>true</code> if the argument is the
1474+ * empty string or is equal to this <code>String</code> object
1475+ * as determined by the {@link #equals(Object)} method.
1476+ */
1477+ public boolean endsWith(String suffix) {
1478+ return startsWith(suffix, count - suffix.count);
1479+ }
1480+
1481+ /**
1482+ * Returns a hash code for this string. The hash code for a
1483+ * <code>String</code> object is computed as
1484+ * <blockquote><pre>
1485+ * s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
1486+ * </pre></blockquote>
1487+ * using <code>int</code> arithmetic, where <code>s[i]</code> is the
1488+ * <i>i</i>th character of the string, <code>n</code> is the length of
1489+ * the string, and <code>^</code> indicates exponentiation.
1490+ * (The hash value of the empty string is zero.)
1491+ *
1492+ * @return a hash code value for this object.
1493+ */
1494+ public int hashCode() {
1495+ int h = hash;
1496+ if (h == 0 && count > 0) {
1497+ int off = offset;
1498+ char val[] = value;
1499+ int len = count;
1500+
1501+ for (int i = 0; i < len; i++) {
1502+ h = 31*h + val[off++];
1503+ }
1504+ hash = h;
1505+ }
1506+ return h;
1507+ }
1508+
1509+ /**
1510+ * Returns the index within this string of the first occurrence of
1511+ * the specified character. If a character with value
1512+ * <code>ch</code> occurs in the character sequence represented by
1513+ * this <code>String</code> object, then the index (in Unicode
1514+ * code units) of the first such occurrence is returned. For
1515+ * values of <code>ch</code> in the range from 0 to 0xFFFF
1516+ * (inclusive), this is the smallest value <i>k</i> such that:
1517+ * <blockquote><pre>
1518+ * this.charAt(<i>k</i>) == ch
1519+ * </pre></blockquote>
1520+ * is true. For other values of <code>ch</code>, it is the
1521+ * smallest value <i>k</i> such that:
1522+ * <blockquote><pre>
1523+ * this.codePointAt(<i>k</i>) == ch
1524+ * </pre></blockquote>
1525+ * is true. In either case, if no such character occurs in this
1526+ * string, then <code>-1</code> is returned.
1527+ *
1528+ * @param ch a character (Unicode code point).
1529+ * @return the index of the first occurrence of the character in the
1530+ * character sequence represented by this object, or
1531+ * <code>-1</code> if the character does not occur.
1532+ */
1533+ public int indexOf(int ch) {
1534+ return indexOf(ch, 0);
1535+ }
1536+
1537+ /**
1538+ * Returns the index within this string of the first occurrence of the
1539+ * specified character, starting the search at the specified index.
1540+ * <p>
1541+ * If a character with value <code>ch</code> occurs in the
1542+ * character sequence represented by this <code>String</code>
1543+ * object at an index no smaller than <code>fromIndex</code>, then
1544+ * the index of the first such occurrence is returned. For values
1545+ * of <code>ch</code> in the range from 0 to 0xFFFF (inclusive),
1546+ * this is the smallest value <i>k</i> such that:
1547+ * <blockquote><pre>
1548+ * (this.charAt(<i>k</i>) == ch) && (<i>k</i> &gt;= fromIndex)
1549+ * </pre></blockquote>
1550+ * is true. For other values of <code>ch</code>, it is the
1551+ * smallest value <i>k</i> such that:
1552+ * <blockquote><pre>
1553+ * (this.codePointAt(<i>k</i>) == ch) && (<i>k</i> &gt;= fromIndex)
1554+ * </pre></blockquote>
1555+ * is true. In either case, if no such character occurs in this
1556+ * string at or after position <code>fromIndex</code>, then
1557+ * <code>-1</code> is returned.
1558+ *
1559+ * <p>
1560+ * There is no restriction on the value of <code>fromIndex</code>. If it
1561+ * is negative, it has the same effect as if it were zero: this entire
1562+ * string may be searched. If it is greater than the length of this
1563+ * string, it has the same effect as if it were equal to the length of
1564+ * this string: <code>-1</code> is returned.
1565+ *
1566+ * <p>All indices are specified in <code>char</code> values
1567+ * (Unicode code units).
1568+ *
1569+ * @param ch a character (Unicode code point).
1570+ * @param fromIndex the index to start the search from.
1571+ * @return the index of the first occurrence of the character in the
1572+ * character sequence represented by this object that is greater
1573+ * than or equal to <code>fromIndex</code>, or <code>-1</code>
1574+ * if the character does not occur.
1575+ */
1576+ public int indexOf(int ch, int fromIndex) {
1577+ if (fromIndex < 0) {
1578+ fromIndex = 0;
1579+ } else if (fromIndex >= count) {
1580+ // Note: fromIndex might be near -1>>>1.
1581+ return -1;
1582+ }
1583+
1584+ if (ch < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
1585+ // handle most cases here (ch is a BMP code point or a
1586+ // negative value (invalid code point))
1587+ final char[] value = this.value;
1588+ final int offset = this.offset;
1589+ final int max = offset + count;
1590+ for (int i = offset + fromIndex; i < max ; i++) {
1591+ if (value[i] == ch) {
1592+ return i - offset;
1593+ }
1594+ }
1595+ return -1;
1596+ } else {
1597+ return indexOfSupplementary(ch, fromIndex);
1598+ }
1599+ }
1600+
1601+ /**
1602+ * Handles (rare) calls of indexOf with a supplementary character.
1603+ */
1604+ private int indexOfSupplementary(int ch, int fromIndex) {
1605+ if (Character.isValidCodePoint(ch)) {
1606+ final char[] value = this.value;
1607+ final int offset = this.offset;
1608+ final char hi = Character.highSurrogate(ch);
1609+ final char lo = Character.lowSurrogate(ch);
1610+ final int max = offset + count - 1;
1611+ for (int i = offset + fromIndex; i < max; i++) {
1612+ if (value[i] == hi && value[i+1] == lo) {
1613+ return i - offset;
1614+ }
1615+ }
1616+ }
1617+ return -1;
1618+ }
1619+
1620+ /**
1621+ * Returns the index within this string of the last occurrence of
1622+ * the specified character. For values of <code>ch</code> in the
1623+ * range from 0 to 0xFFFF (inclusive), the index (in Unicode code
1624+ * units) returned is the largest value <i>k</i> such that:
1625+ * <blockquote><pre>
1626+ * this.charAt(<i>k</i>) == ch
1627+ * </pre></blockquote>
1628+ * is true. For other values of <code>ch</code>, it is the
1629+ * largest value <i>k</i> such that:
1630+ * <blockquote><pre>
1631+ * this.codePointAt(<i>k</i>) == ch
1632+ * </pre></blockquote>
1633+ * is true. In either case, if no such character occurs in this
1634+ * string, then <code>-1</code> is returned. The
1635+ * <code>String</code> is searched backwards starting at the last
1636+ * character.
1637+ *
1638+ * @param ch a character (Unicode code point).
1639+ * @return the index of the last occurrence of the character in the
1640+ * character sequence represented by this object, or
1641+ * <code>-1</code> if the character does not occur.
1642+ */
1643+ public int lastIndexOf(int ch) {
1644+ return lastIndexOf(ch, count - 1);
1645+ }
1646+
1647+ /**
1648+ * Returns the index within this string of the last occurrence of
1649+ * the specified character, searching backward starting at the
1650+ * specified index. For values of <code>ch</code> in the range
1651+ * from 0 to 0xFFFF (inclusive), the index returned is the largest
1652+ * value <i>k</i> such that:
1653+ * <blockquote><pre>
1654+ * (this.charAt(<i>k</i>) == ch) && (<i>k</i> &lt;= fromIndex)
1655+ * </pre></blockquote>
1656+ * is true. For other values of <code>ch</code>, it is the
1657+ * largest value <i>k</i> such that:
1658+ * <blockquote><pre>
1659+ * (this.codePointAt(<i>k</i>) == ch) && (<i>k</i> &lt;= fromIndex)
1660+ * </pre></blockquote>
1661+ * is true. In either case, if no such character occurs in this
1662+ * string at or before position <code>fromIndex</code>, then
1663+ * <code>-1</code> is returned.
1664+ *
1665+ * <p>All indices are specified in <code>char</code> values
1666+ * (Unicode code units).
1667+ *
1668+ * @param ch a character (Unicode code point).
1669+ * @param fromIndex the index to start the search from. There is no
1670+ * restriction on the value of <code>fromIndex</code>. If it is
1671+ * greater than or equal to the length of this string, it has
1672+ * the same effect as if it were equal to one less than the
1673+ * length of this string: this entire string may be searched.
1674+ * If it is negative, it has the same effect as if it were -1:
1675+ * -1 is returned.
1676+ * @return the index of the last occurrence of the character in the
1677+ * character sequence represented by this object that is less
1678+ * than or equal to <code>fromIndex</code>, or <code>-1</code>
1679+ * if the character does not occur before that point.
1680+ */
1681+ public int lastIndexOf(int ch, int fromIndex) {
1682+ if (ch < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
1683+ // handle most cases here (ch is a BMP code point or a
1684+ // negative value (invalid code point))
1685+ final char[] value = this.value;
1686+ final int offset = this.offset;
1687+ int i = offset + Math.min(fromIndex, count - 1);
1688+ for (; i >= offset ; i--) {
1689+ if (value[i] == ch) {
1690+ return i - offset;
1691+ }
1692+ }
1693+ return -1;
1694+ } else {
1695+ return lastIndexOfSupplementary(ch, fromIndex);
1696+ }
1697+ }
1698+
1699+ /**
1700+ * Handles (rare) calls of lastIndexOf with a supplementary character.
1701+ */
1702+ private int lastIndexOfSupplementary(int ch, int fromIndex) {
1703+ if (Character.isValidCodePoint(ch)) {
1704+ final char[] value = this.value;
1705+ final int offset = this.offset;
1706+ char hi = Character.highSurrogate(ch);
1707+ char lo = Character.lowSurrogate(ch);
1708+ int i = offset + Math.min(fromIndex, count - 2);
1709+ for (; i >= offset; i--) {
1710+ if (value[i] == hi && value[i+1] == lo) {
1711+ return i - offset;
1712+ }
1713+ }
1714+ }
1715+ return -1;
1716+ }
1717+
1718+ /**
1719+ * Returns the index within this string of the first occurrence of the
1720+ * specified substring.
1721+ *
1722+ * <p>The returned index is the smallest value <i>k</i> for which:
1723+ * <blockquote><pre>
1724+ * this.startsWith(str, <i>k</i>)
1725+ * </pre></blockquote>
1726+ * If no such value of <i>k</i> exists, then {@code -1} is returned.
1727+ *
1728+ * @param str the substring to search for.
1729+ * @return the index of the first occurrence of the specified substring,
1730+ * or {@code -1} if there is no such occurrence.
1731+ */
1732+ public int indexOf(String str) {
1733+ return indexOf(str, 0);
1734+ }
1735+
1736+ /**
1737+ * Returns the index within this string of the first occurrence of the
1738+ * specified substring, starting at the specified index.
1739+ *
1740+ * <p>The returned index is the smallest value <i>k</i> for which:
1741+ * <blockquote><pre>
1742+ * <i>k</i> &gt;= fromIndex && this.startsWith(str, <i>k</i>)
1743+ * </pre></blockquote>
1744+ * If no such value of <i>k</i> exists, then {@code -1} is returned.
1745+ *
1746+ * @param str the substring to search for.
1747+ * @param fromIndex the index from which to start the search.
1748+ * @return the index of the first occurrence of the specified substring,
1749+ * starting at the specified index,
1750+ * or {@code -1} if there is no such occurrence.
1751+ */
1752+ public int indexOf(String str, int fromIndex) {
1753+ return indexOf(value, offset, count,
1754+ str.value, str.offset, str.count, fromIndex);
1755+ }
1756+
1757+ /**
1758+ * Code shared by String and StringBuffer to do searches. The
1759+ * source is the character array being searched, and the target
1760+ * is the string being searched for.
1761+ *
1762+ * @param source the characters being searched.
1763+ * @param sourceOffset offset of the source string.
1764+ * @param sourceCount count of the source string.
1765+ * @param target the characters being searched for.
1766+ * @param targetOffset offset of the target string.
1767+ * @param targetCount count of the target string.
1768+ * @param fromIndex the index to begin searching from.
1769+ */
1770+ static int indexOf(char[] source, int sourceOffset, int sourceCount,
1771+ char[] target, int targetOffset, int targetCount,
1772+ int fromIndex) {
1773+ if (fromIndex >= sourceCount) {
1774+ return (targetCount == 0 ? sourceCount : -1);
1775+ }
1776+ if (fromIndex < 0) {
1777+ fromIndex = 0;
1778+ }
1779+ if (targetCount == 0) {
1780+ return fromIndex;
1781+ }
1782+
1783+ char first = target[targetOffset];
1784+ int max = sourceOffset + (sourceCount - targetCount);
1785+
1786+ for (int i = sourceOffset + fromIndex; i <= max; i++) {
1787+ /* Look for first character. */
1788+ if (source[i] != first) {
1789+ while (++i <= max && source[i] != first);
1790+ }
1791+
1792+ /* Found first character, now look at the rest of v2 */
1793+ if (i <= max) {
1794+ int j = i + 1;
1795+ int end = j + targetCount - 1;
1796+ for (int k = targetOffset + 1; j < end && source[j] ==
1797+ target[k]; j++, k++);
1798+
1799+ if (j == end) {
1800+ /* Found whole string. */
1801+ return i - sourceOffset;
1802+ }
1803+ }
1804+ }
1805+ return -1;
1806+ }
1807+
1808+ /**
1809+ * Returns the index within this string of the last occurrence of the
1810+ * specified substring. The last occurrence of the empty string ""
1811+ * is considered to occur at the index value {@code this.length()}.
1812+ *
1813+ * <p>The returned index is the largest value <i>k</i> for which:
1814+ * <blockquote><pre>
1815+ * this.startsWith(str, <i>k</i>)
1816+ * </pre></blockquote>
1817+ * If no such value of <i>k</i> exists, then {@code -1} is returned.
1818+ *
1819+ * @param str the substring to search for.
1820+ * @return the index of the last occurrence of the specified substring,
1821+ * or {@code -1} if there is no such occurrence.
1822+ */
1823+ public int lastIndexOf(String str) {
1824+ return lastIndexOf(str, count);
1825+ }
1826+
1827+ /**
1828+ * Returns the index within this string of the last occurrence of the
1829+ * specified substring, searching backward starting at the specified index.
1830+ *
1831+ * <p>The returned index is the largest value <i>k</i> for which:
1832+ * <blockquote><pre>
1833+ * <i>k</i> &lt;= fromIndex && this.startsWith(str, <i>k</i>)
1834+ * </pre></blockquote>
1835+ * If no such value of <i>k</i> exists, then {@code -1} is returned.
1836+ *
1837+ * @param str the substring to search for.
1838+ * @param fromIndex the index to start the search from.
1839+ * @return the index of the last occurrence of the specified substring,
1840+ * searching backward from the specified index,
1841+ * or {@code -1} if there is no such occurrence.
1842+ */
1843+ public int lastIndexOf(String str, int fromIndex) {
1844+ return lastIndexOf(value, offset, count,
1845+ str.value, str.offset, str.count, fromIndex);
1846+ }
1847+
1848+ /**
1849+ * Code shared by String and StringBuffer to do searches. The
1850+ * source is the character array being searched, and the target
1851+ * is the string being searched for.
1852+ *
1853+ * @param source the characters being searched.
1854+ * @param sourceOffset offset of the source string.
1855+ * @param sourceCount count of the source string.
1856+ * @param target the characters being searched for.
1857+ * @param targetOffset offset of the target string.
1858+ * @param targetCount count of the target string.
1859+ * @param fromIndex the index to begin searching from.
1860+ */
1861+ static int lastIndexOf(char[] source, int sourceOffset, int sourceCount,
1862+ char[] target, int targetOffset, int targetCount,
1863+ int fromIndex) {
1864+ /*
1865+ * Check arguments; return immediately where possible. For
1866+ * consistency, don't check for null str.
1867+ */
1868+ int rightIndex = sourceCount - targetCount;
1869+ if (fromIndex < 0) {
1870+ return -1;
1871+ }
1872+ if (fromIndex > rightIndex) {
1873+ fromIndex = rightIndex;
1874+ }
1875+ /* Empty string always matches. */
1876+ if (targetCount == 0) {
1877+ return fromIndex;
1878+ }
1879+
1880+ int strLastIndex = targetOffset + targetCount - 1;
1881+ char strLastChar = target[strLastIndex];
1882+ int min = sourceOffset + targetCount - 1;
1883+ int i = min + fromIndex;
1884+
1885+ startSearchForLastChar:
1886+ while (true) {
1887+ while (i >= min && source[i] != strLastChar) {
1888+ i--;
1889+ }
1890+ if (i < min) {
1891+ return -1;
1892+ }
1893+ int j = i - 1;
1894+ int start = j - (targetCount - 1);
1895+ int k = strLastIndex - 1;
1896+
1897+ while (j > start) {
1898+ if (source[j--] != target[k--]) {
1899+ i--;
1900+ continue startSearchForLastChar;
1901+ }
1902+ }
1903+ return start - sourceOffset + 1;
1904+ }
1905+ }
1906+
1907+ /**
1908+ * Returns a new string that is a substring of this string. The
1909+ * substring begins with the character at the specified index and
1910+ * extends to the end of this string. <p>
1911+ * Examples:
1912+ * <blockquote><pre>
1913+ * "unhappy".substring(2) returns "happy"
1914+ * "Harbison".substring(3) returns "bison"
1915+ * "emptiness".substring(9) returns "" (an empty string)
1916+ * </pre></blockquote>
1917+ *
1918+ * @param beginIndex the beginning index, inclusive.
1919+ * @return the specified substring.
1920+ * @exception IndexOutOfBoundsException if
1921+ * <code>beginIndex</code> is negative or larger than the
1922+ * length of this <code>String</code> object.
1923+ */
1924+ public String substring(int beginIndex) {
1925+ return substring(beginIndex, count);
1926+ }
1927+
1928+ /**
1929+ * Returns a new string that is a substring of this string. The
1930+ * substring begins at the specified <code>beginIndex</code> and
1931+ * extends to the character at index <code>endIndex - 1</code>.
1932+ * Thus the length of the substring is <code>endIndex-beginIndex</code>.
1933+ * <p>
1934+ * Examples:
1935+ * <blockquote><pre>
1936+ * "hamburger".substring(4, 8) returns "urge"
1937+ * "smiles".substring(1, 5) returns "mile"
1938+ * </pre></blockquote>
1939+ *
1940+ * @param beginIndex the beginning index, inclusive.
1941+ * @param endIndex the ending index, exclusive.
1942+ * @return the specified substring.
1943+ * @exception IndexOutOfBoundsException if the
1944+ * <code>beginIndex</code> is negative, or
1945+ * <code>endIndex</code> is larger than the length of
1946+ * this <code>String</code> object, or
1947+ * <code>beginIndex</code> is larger than
1948+ * <code>endIndex</code>.
1949+ */
1950+ public String substring(int beginIndex, int endIndex) {
1951+ if (beginIndex < 0) {
1952+ throw new StringIndexOutOfBoundsException(beginIndex);
1953+ }
1954+ if (endIndex > count) {
1955+ throw new StringIndexOutOfBoundsException(endIndex);
1956+ }
1957+ if (beginIndex > endIndex) {
1958+ throw new StringIndexOutOfBoundsException(endIndex - beginIndex);
1959+ }
1960+ return ((beginIndex == 0) && (endIndex == count)) ? this :
1961+ new String(offset + beginIndex, endIndex - beginIndex, value);
1962+ }
1963+
1964+ /**
1965+ * Returns a new character sequence that is a subsequence of this sequence.
1966+ *
1967+ * <p> An invocation of this method of the form
1968+ *
1969+ * <blockquote><pre>
1970+ * str.subSequence(begin,&nbsp;end)</pre></blockquote>
1971+ *
1972+ * behaves in exactly the same way as the invocation
1973+ *
1974+ * <blockquote><pre>
1975+ * str.substring(begin,&nbsp;end)</pre></blockquote>
1976+ *
1977+ * This method is defined so that the <tt>String</tt> class can implement
1978+ * the {@link CharSequence} interface. </p>
1979+ *
1980+ * @param beginIndex the begin index, inclusive.
1981+ * @param endIndex the end index, exclusive.
1982+ * @return the specified subsequence.
1983+ *
1984+ * @throws IndexOutOfBoundsException
1985+ * if <tt>beginIndex</tt> or <tt>endIndex</tt> are negative,
1986+ * if <tt>endIndex</tt> is greater than <tt>length()</tt>,
1987+ * or if <tt>beginIndex</tt> is greater than <tt>startIndex</tt>
1988+ *
1989+ * @since 1.4
1990+ * @spec JSR-51
1991+ */
1992+ public CharSequence subSequence(int beginIndex, int endIndex) {
1993+ return this.substring(beginIndex, endIndex);
1994+ }
1995+
1996+ /**
1997+ * Concatenates the specified string to the end of this string.
1998+ * <p>
1999+ * If the length of the argument string is <code>0</code>, then this
2000+ * <code>String</code> object is returned. Otherwise, a new
2001+ * <code>String</code> object is created, representing a character
2002+ * sequence that is the concatenation of the character sequence
2003+ * represented by this <code>String</code> object and the character
2004+ * sequence represented by the argument string.<p>
2005+ * Examples:
2006+ * <blockquote><pre>
2007+ * "cares".concat("s") returns "caress"
2008+ * "to".concat("get").concat("her") returns "together"
2009+ * </pre></blockquote>
2010+ *
2011+ * @param str the <code>String</code> that is concatenated to the end
2012+ * of this <code>String</code>.
2013+ * @return a string that represents the concatenation of this object's
2014+ * characters followed by the string argument's characters.
2015+ */
2016+ public String concat(String str) {
2017+ int otherLen = str.length();
2018+ if (otherLen == 0) {
2019+ return this;
2020+ }
2021+ char buf[] = new char[count + otherLen];
2022+ getChars(0, count, buf, 0);
2023+ str.getChars(0, otherLen, buf, count);
2024+ return new String(0, count + otherLen, buf);
2025+ }
2026+
2027+ /**
2028+ * Returns a new string resulting from replacing all occurrences of
2029+ * <code>oldChar</code> in this string with <code>newChar</code>.
2030+ * <p>
2031+ * If the character <code>oldChar</code> does not occur in the
2032+ * character sequence represented by this <code>String</code> object,
2033+ * then a reference to this <code>String</code> object is returned.
2034+ * Otherwise, a new <code>String</code> object is created that
2035+ * represents a character sequence identical to the character sequence
2036+ * represented by this <code>String</code> object, except that every
2037+ * occurrence of <code>oldChar</code> is replaced by an occurrence
2038+ * of <code>newChar</code>.
2039+ * <p>
2040+ * Examples:
2041+ * <blockquote><pre>
2042+ * "mesquite in your cellar".replace('e', 'o')
2043+ * returns "mosquito in your collar"
2044+ * "the war of baronets".replace('r', 'y')
2045+ * returns "the way of bayonets"
2046+ * "sparring with a purple porpoise".replace('p', 't')
2047+ * returns "starring with a turtle tortoise"
2048+ * "JonL".replace('q', 'x') returns "JonL" (no change)
2049+ * </pre></blockquote>
2050+ *
2051+ * @param oldChar the old character.
2052+ * @param newChar the new character.
2053+ * @return a string derived from this string by replacing every
2054+ * occurrence of <code>oldChar</code> with <code>newChar</code>.
2055+ */
2056+ public String replace(char oldChar, char newChar) {
2057+ if (oldChar != newChar) {
2058+ int len = count;
2059+ int i = -1;
2060+ char[] val = value; /* avoid getfield opcode */
2061+ int off = offset; /* avoid getfield opcode */
2062+
2063+ while (++i < len) {
2064+ if (val[off + i] == oldChar) {
2065+ break;
2066+ }
2067+ }
2068+ if (i < len) {
2069+ char buf[] = new char[len];
2070+ for (int j = 0 ; j < i ; j++) {
2071+ buf[j] = val[off+j];
2072+ }
2073+ while (i < len) {
2074+ char c = val[off + i];
2075+ buf[i] = (c == oldChar) ? newChar : c;
2076+ i++;
2077+ }
2078+ return new String(0, len, buf);
2079+ }
2080+ }
2081+ return this;
2082+ }
2083+
2084+ /**
2085+ * Tells whether or not this string matches the given <a
2086+ * href="../util/regex/Pattern.html#sum">regular expression</a>.
2087+ *
2088+ * <p> An invocation of this method of the form
2089+ * <i>str</i><tt>.matches(</tt><i>regex</i><tt>)</tt> yields exactly the
2090+ * same result as the expression
2091+ *
2092+ * <blockquote><tt> {@link java.util.regex.Pattern}.{@link
2093+ * java.util.regex.Pattern#matches(String,CharSequence)
2094+ * matches}(</tt><i>regex</i><tt>,</tt> <i>str</i><tt>)</tt></blockquote>
2095+ *
2096+ * @param regex
2097+ * the regular expression to which this string is to be matched
2098+ *
2099+ * @return <tt>true</tt> if, and only if, this string matches the
2100+ * given regular expression
2101+ *
2102+ * @throws PatternSyntaxException
2103+ * if the regular expression's syntax is invalid
2104+ *
2105+ * @see java.util.regex.Pattern
2106+ *
2107+ * @since 1.4
2108+ * @spec JSR-51
2109+ */
2110+ public boolean matches(String regex) {
2111+ return Pattern.matches(regex, this);
2112+ }
2113+
2114+ /**
2115+ * Returns true if and only if this string contains the specified
2116+ * sequence of char values.
2117+ *
2118+ * @param s the sequence to search for
2119+ * @return true if this string contains <code>s</code>, false otherwise
2120+ * @throws NullPointerException if <code>s</code> is <code>null</code>
2121+ * @since 1.5
2122+ */
2123+ public boolean contains(CharSequence s) {
2124+ return indexOf(s.toString()) > -1;
2125+ }
2126+
2127+ /**
2128+ * Replaces the first substring of this string that matches the given <a
2129+ * href="../util/regex/Pattern.html#sum">regular expression</a> with the
2130+ * given replacement.
2131+ *
2132+ * <p> An invocation of this method of the form
2133+ * <i>str</i><tt>.replaceFirst(</tt><i>regex</i><tt>,</tt> <i>repl</i><tt>)</tt>
2134+ * yields exactly the same result as the expression
2135+ *
2136+ * <blockquote><tt>
2137+ * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile
2138+ * compile}(</tt><i>regex</i><tt>).{@link
2139+ * java.util.regex.Pattern#matcher(java.lang.CharSequence)
2140+ * matcher}(</tt><i>str</i><tt>).{@link java.util.regex.Matcher#replaceFirst
2141+ * replaceFirst}(</tt><i>repl</i><tt>)</tt></blockquote>
2142+ *
2143+ *<p>
2144+ * Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in the
2145+ * replacement string may cause the results to be different than if it were
2146+ * being treated as a literal replacement string; see
2147+ * {@link java.util.regex.Matcher#replaceFirst}.
2148+ * Use {@link java.util.regex.Matcher#quoteReplacement} to suppress the special
2149+ * meaning of these characters, if desired.
2150+ *
2151+ * @param regex
2152+ * the regular expression to which this string is to be matched
2153+ * @param replacement
2154+ * the string to be substituted for the first match
2155+ *
2156+ * @return The resulting <tt>String</tt>
2157+ *
2158+ * @throws PatternSyntaxException
2159+ * if the regular expression's syntax is invalid
2160+ *
2161+ * @see java.util.regex.Pattern
2162+ *
2163+ * @since 1.4
2164+ * @spec JSR-51
2165+ */
2166+ public String replaceFirst(String regex, String replacement) {
2167+ return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
2168+ }
2169+
2170+ /**
2171+ * Replaces each substring of this string that matches the given <a
2172+ * href="../util/regex/Pattern.html#sum">regular expression</a> with the
2173+ * given replacement.
2174+ *
2175+ * <p> An invocation of this method of the form
2176+ * <i>str</i><tt>.replaceAll(</tt><i>regex</i><tt>,</tt> <i>repl</i><tt>)</tt>
2177+ * yields exactly the same result as the expression
2178+ *
2179+ * <blockquote><tt>
2180+ * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile
2181+ * compile}(</tt><i>regex</i><tt>).{@link
2182+ * java.util.regex.Pattern#matcher(java.lang.CharSequence)
2183+ * matcher}(</tt><i>str</i><tt>).{@link java.util.regex.Matcher#replaceAll
2184+ * replaceAll}(</tt><i>repl</i><tt>)</tt></blockquote>
2185+ *
2186+ *<p>
2187+ * Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in the
2188+ * replacement string may cause the results to be different than if it were
2189+ * being treated as a literal replacement string; see
2190+ * {@link java.util.regex.Matcher#replaceAll Matcher.replaceAll}.
2191+ * Use {@link java.util.regex.Matcher#quoteReplacement} to suppress the special
2192+ * meaning of these characters, if desired.
2193+ *
2194+ * @param regex
2195+ * the regular expression to which this string is to be matched
2196+ * @param replacement
2197+ * the string to be substituted for each match
2198+ *
2199+ * @return The resulting <tt>String</tt>
2200+ *
2201+ * @throws PatternSyntaxException
2202+ * if the regular expression's syntax is invalid
2203+ *
2204+ * @see java.util.regex.Pattern
2205+ *
2206+ * @since 1.4
2207+ * @spec JSR-51
2208+ */
2209+ public String replaceAll(String regex, String replacement) {
2210+ return Pattern.compile(regex).matcher(this).replaceAll(replacement);
2211+ }
2212+
2213+ /**
2214+ * Replaces each substring of this string that matches the literal target
2215+ * sequence with the specified literal replacement sequence. The
2216+ * replacement proceeds from the beginning of the string to the end, for
2217+ * example, replacing "aa" with "b" in the string "aaa" will result in
2218+ * "ba" rather than "ab".
2219+ *
2220+ * @param target The sequence of char values to be replaced
2221+ * @param replacement The replacement sequence of char values
2222+ * @return The resulting string
2223+ * @throws NullPointerException if <code>target</code> or
2224+ * <code>replacement</code> is <code>null</code>.
2225+ * @since 1.5
2226+ */
2227+ public String replace(CharSequence target, CharSequence replacement) {
2228+ return Pattern.compile(target.toString(), Pattern.LITERAL).matcher(
2229+ this).replaceAll(Matcher.quoteReplacement(replacement.toString()));
2230+ }
2231+
2232+ /**
2233+ * Splits this string around matches of the given
2234+ * <a href="../util/regex/Pattern.html#sum">regular expression</a>.
2235+ *
2236+ * <p> The array returned by this method contains each substring of this
2237+ * string that is terminated by another substring that matches the given
2238+ * expression or is terminated by the end of the string. The substrings in
2239+ * the array are in the order in which they occur in this string. If the
2240+ * expression does not match any part of the input then the resulting array
2241+ * has just one element, namely this string.
2242+ *
2243+ * <p> The <tt>limit</tt> parameter controls the number of times the
2244+ * pattern is applied and therefore affects the length of the resulting
2245+ * array. If the limit <i>n</i> is greater than zero then the pattern
2246+ * will be applied at most <i>n</i>&nbsp;-&nbsp;1 times, the array's
2247+ * length will be no greater than <i>n</i>, and the array's last entry
2248+ * will contain all input beyond the last matched delimiter. If <i>n</i>
2249+ * is non-positive then the pattern will be applied as many times as
2250+ * possible and the array can have any length. If <i>n</i> is zero then
2251+ * the pattern will be applied as many times as possible, the array can
2252+ * have any length, and trailing empty strings will be discarded.
2253+ *
2254+ * <p> The string <tt>"boo:and:foo"</tt>, for example, yields the
2255+ * following results with these parameters:
2256+ *
2257+ * <blockquote><table cellpadding=1 cellspacing=0 summary="Split example showing regex, limit, and result">
2258+ * <tr>
2259+ * <th>Regex</th>
2260+ * <th>Limit</th>
2261+ * <th>Result</th>
2262+ * </tr>
2263+ * <tr><td align=center>:</td>
2264+ * <td align=center>2</td>
2265+ * <td><tt>{ "boo", "and:foo" }</tt></td></tr>
2266+ * <tr><td align=center>:</td>
2267+ * <td align=center>5</td>
2268+ * <td><tt>{ "boo", "and", "foo" }</tt></td></tr>
2269+ * <tr><td align=center>:</td>
2270+ * <td align=center>-2</td>
2271+ * <td><tt>{ "boo", "and", "foo" }</tt></td></tr>
2272+ * <tr><td align=center>o</td>
2273+ * <td align=center>5</td>
2274+ * <td><tt>{ "b", "", ":and:f", "", "" }</tt></td></tr>
2275+ * <tr><td align=center>o</td>
2276+ * <td align=center>-2</td>
2277+ * <td><tt>{ "b", "", ":and:f", "", "" }</tt></td></tr>
2278+ * <tr><td align=center>o</td>
2279+ * <td align=center>0</td>
2280+ * <td><tt>{ "b", "", ":and:f" }</tt></td></tr>
2281+ * </table></blockquote>
2282+ *
2283+ * <p> An invocation of this method of the form
2284+ * <i>str.</i><tt>split(</tt><i>regex</i><tt>,</tt>&nbsp;<i>n</i><tt>)</tt>
2285+ * yields the same result as the expression
2286+ *
2287+ * <blockquote>
2288+ * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#compile
2289+ * compile}<tt>(</tt><i>regex</i><tt>)</tt>.{@link
2290+ * java.util.regex.Pattern#split(java.lang.CharSequence,int)
2291+ * split}<tt>(</tt><i>str</i><tt>,</tt>&nbsp;<i>n</i><tt>)</tt>
2292+ * </blockquote>
2293+ *
2294+ *
2295+ * @param regex
2296+ * the delimiting regular expression
2297+ *
2298+ * @param limit
2299+ * the result threshold, as described above
2300+ *
2301+ * @return the array of strings computed by splitting this string
2302+ * around matches of the given regular expression
2303+ *
2304+ * @throws PatternSyntaxException
2305+ * if the regular expression's syntax is invalid
2306+ *
2307+ * @see java.util.regex.Pattern
2308+ *
2309+ * @since 1.4
2310+ * @spec JSR-51
2311+ */
2312+ public String[] split(String regex, int limit) {
2313+ /* fastpath if the regex is a
2314+ (1)one-char String and this character is not one of the
2315+ RegEx's meta characters ".$|()[{^?*+\\", or
2316+ (2)two-char String and the first char is the backslash and
2317+ the second is not the ascii digit or ascii letter.
2318+ */
2319+ char ch = 0;
2320+ if (((regex.count == 1 &&
2321+ ".$|()[{^?*+\\".indexOf(ch = regex.charAt(0)) == -1) ||
2322+ (regex.length() == 2 &&
2323+ regex.charAt(0) == '\\' &&
2324+ (((ch = regex.charAt(1))-'0')|('9'-ch)) < 0 &&
2325+ ((ch-'a')|('z'-ch)) < 0 &&
2326+ ((ch-'A')|('Z'-ch)) < 0)) &&
2327+ (ch < Character.MIN_HIGH_SURROGATE ||
2328+ ch > Character.MAX_LOW_SURROGATE))
2329+ {
2330+ int off = 0;
2331+ int next = 0;
2332+ boolean limited = limit > 0;
2333+ ArrayList<String> list = new ArrayList<>();
2334+ while ((next = indexOf(ch, off)) != -1) {
2335+ if (!limited || list.size() < limit - 1) {
2336+ list.add(substring(off, next));
2337+ off = next + 1;
2338+ } else { // last one
2339+ //assert (list.size() == limit - 1);
2340+ list.add(substring(off, count));
2341+ off = count;
2342+ break;
2343+ }
2344+ }
2345+ // If no match was found, return this
2346+ if (off == 0)
2347+ return new String[] { this };
2348+
2349+ // Add remaining segment
2350+ if (!limited || list.size() < limit)
2351+ list.add(substring(off, count));
2352+
2353+ // Construct result
2354+ int resultSize = list.size();
2355+ if (limit == 0)
2356+ while (resultSize > 0 && list.get(resultSize-1).length() == 0)
2357+ resultSize--;
2358+ String[] result = new String[resultSize];
2359+ return list.subList(0, resultSize).toArray(result);
2360+ }
2361+ return Pattern.compile(regex).split(this, limit);
2362+ }
2363+
2364+ /**
2365+ * Splits this string around matches of the given <a
2366+ * href="../util/regex/Pattern.html#sum">regular expression</a>.
2367+ *
2368+ * <p> This method works as if by invoking the two-argument {@link
2369+ * #split(String, int) split} method with the given expression and a limit
2370+ * argument of zero. Trailing empty strings are therefore not included in
2371+ * the resulting array.
2372+ *
2373+ * <p> The string <tt>"boo:and:foo"</tt>, for example, yields the following
2374+ * results with these expressions:
2375+ *
2376+ * <blockquote><table cellpadding=1 cellspacing=0 summary="Split examples showing regex and result">
2377+ * <tr>
2378+ * <th>Regex</th>
2379+ * <th>Result</th>
2380+ * </tr>
2381+ * <tr><td align=center>:</td>
2382+ * <td><tt>{ "boo", "and", "foo" }</tt></td></tr>
2383+ * <tr><td align=center>o</td>
2384+ * <td><tt>{ "b", "", ":and:f" }</tt></td></tr>
2385+ * </table></blockquote>
2386+ *
2387+ *
2388+ * @param regex
2389+ * the delimiting regular expression
2390+ *
2391+ * @return the array of strings computed by splitting this string
2392+ * around matches of the given regular expression
2393+ *
2394+ * @throws PatternSyntaxException
2395+ * if the regular expression's syntax is invalid
2396+ *
2397+ * @see java.util.regex.Pattern
2398+ *
2399+ * @since 1.4
2400+ * @spec JSR-51
2401+ */
2402+ public String[] split(String regex) {
2403+ return split(regex, 0);
2404+ }
2405+
2406+ /**
2407+ * Converts all of the characters in this <code>String</code> to lower
2408+ * case using the rules of the given <code>Locale</code>. Case mapping is based
2409+ * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2410+ * class. Since case mappings are not always 1:1 char mappings, the resulting
2411+ * <code>String</code> may be a different length than the original <code>String</code>.
2412+ * <p>
2413+ * Examples of lowercase mappings are in the following table:
2414+ * <table border="1" summary="Lowercase mapping examples showing language code of locale, upper case, lower case, and description">
2415+ * <tr>
2416+ * <th>Language Code of Locale</th>
2417+ * <th>Upper Case</th>
2418+ * <th>Lower Case</th>
2419+ * <th>Description</th>
2420+ * </tr>
2421+ * <tr>
2422+ * <td>tr (Turkish)</td>
2423+ * <td>&#92;u0130</td>
2424+ * <td>&#92;u0069</td>
2425+ * <td>capital letter I with dot above -&gt; small letter i</td>
2426+ * </tr>
2427+ * <tr>
2428+ * <td>tr (Turkish)</td>
2429+ * <td>&#92;u0049</td>
2430+ * <td>&#92;u0131</td>
2431+ * <td>capital letter I -&gt; small letter dotless i </td>
2432+ * </tr>
2433+ * <tr>
2434+ * <td>(all)</td>
2435+ * <td>French Fries</td>
2436+ * <td>french fries</td>
2437+ * <td>lowercased all chars in String</td>
2438+ * </tr>
2439+ * <tr>
2440+ * <td>(all)</td>
2441+ * <td><img src="doc-files/capiota.gif" alt="capiota"><img src="doc-files/capchi.gif" alt="capchi">
2442+ * <img src="doc-files/captheta.gif" alt="captheta"><img src="doc-files/capupsil.gif" alt="capupsil">
2443+ * <img src="doc-files/capsigma.gif" alt="capsigma"></td>
2444+ * <td><img src="doc-files/iota.gif" alt="iota"><img src="doc-files/chi.gif" alt="chi">
2445+ * <img src="doc-files/theta.gif" alt="theta"><img src="doc-files/upsilon.gif" alt="upsilon">
2446+ * <img src="doc-files/sigma1.gif" alt="sigma"></td>
2447+ * <td>lowercased all chars in String</td>
2448+ * </tr>
2449+ * </table>
2450+ *
2451+ * @param locale use the case transformation rules for this locale
2452+ * @return the <code>String</code>, converted to lowercase.
2453+ * @see java.lang.String#toLowerCase()
2454+ * @see java.lang.String#toUpperCase()
2455+ * @see java.lang.String#toUpperCase(Locale)
2456+ * @since 1.1
2457+ */
2458+ public String toLowerCase(Locale locale) {
2459+ if (locale == null) {
2460+ throw new NullPointerException();
2461+ }
2462+
2463+ int firstUpper;
2464+
2465+ /* Now check if there are any characters that need to be changed. */
2466+ scan: {
2467+ for (firstUpper = 0 ; firstUpper < count; ) {
2468+ char c = value[offset+firstUpper];
2469+ if ((c >= Character.MIN_HIGH_SURROGATE) &&
2470+ (c <= Character.MAX_HIGH_SURROGATE)) {
2471+ int supplChar = codePointAt(firstUpper);
2472+ if (supplChar != Character.toLowerCase(supplChar)) {
2473+ break scan;
2474+ }
2475+ firstUpper += Character.charCount(supplChar);
2476+ } else {
2477+ if (c != Character.toLowerCase(c)) {
2478+ break scan;
2479+ }
2480+ firstUpper++;
2481+ }
2482+ }
2483+ return this;
2484+ }
2485+
2486+ char[] result = new char[count];
2487+ int resultOffset = 0; /* result may grow, so i+resultOffset
2488+ * is the write location in result */
2489+
2490+ /* Just copy the first few lowerCase characters. */
2491+ System.arraycopy(value, offset, result, 0, firstUpper);
2492+
2493+ String lang = locale.getLanguage();
2494+ boolean localeDependent =
2495+ (lang == "tr" || lang == "az" || lang == "lt");
2496+ char[] lowerCharArray;
2497+ int lowerChar;
2498+ int srcChar;
2499+ int srcCount;
2500+ for (int i = firstUpper; i < count; i += srcCount) {
2501+ srcChar = (int)value[offset+i];
2502+ if ((char)srcChar >= Character.MIN_HIGH_SURROGATE &&
2503+ (char)srcChar <= Character.MAX_HIGH_SURROGATE) {
2504+ srcChar = codePointAt(i);
2505+ srcCount = Character.charCount(srcChar);
2506+ } else {
2507+ srcCount = 1;
2508+ }
2509+ if (localeDependent || srcChar == '\u03A3') { // GREEK CAPITAL LETTER SIGMA
2510+ lowerChar = ConditionalSpecialCasing.toLowerCaseEx(this, i, locale);
2511+ } else if (srcChar == '\u0130') { // LATIN CAPITAL LETTER I DOT
2512+ lowerChar = Character.ERROR;
2513+ } else {
2514+ lowerChar = Character.toLowerCase(srcChar);
2515+ }
2516+ if ((lowerChar == Character.ERROR) ||
2517+ (lowerChar >= Character.MIN_SUPPLEMENTARY_CODE_POINT)) {
2518+ if (lowerChar == Character.ERROR) {
2519+ if (!localeDependent && srcChar == '\u0130') {
2520+ lowerCharArray =
2521+ ConditionalSpecialCasing.toLowerCaseCharArray(this, i, Locale.ENGLISH);
2522+ } else {
2523+ lowerCharArray =
2524+ ConditionalSpecialCasing.toLowerCaseCharArray(this, i, locale);
2525+ }
2526+ } else if (srcCount == 2) {
2527+ resultOffset += Character.toChars(lowerChar, result, i + resultOffset) - srcCount;
2528+ continue;
2529+ } else {
2530+ lowerCharArray = Character.toChars(lowerChar);
2531+ }
2532+
2533+ /* Grow result if needed */
2534+ int mapLen = lowerCharArray.length;
2535+ if (mapLen > srcCount) {
2536+ char[] result2 = new char[result.length + mapLen - srcCount];
2537+ System.arraycopy(result, 0, result2, 0,
2538+ i + resultOffset);
2539+ result = result2;
2540+ }
2541+ for (int x=0; x<mapLen; ++x) {
2542+ result[i+resultOffset+x] = lowerCharArray[x];
2543+ }
2544+ resultOffset += (mapLen - srcCount);
2545+ } else {
2546+ result[i+resultOffset] = (char)lowerChar;
2547+ }
2548+ }
2549+ return new String(0, count+resultOffset, result);
2550+ }
2551+
2552+ /**
2553+ * Converts all of the characters in this <code>String</code> to lower
2554+ * case using the rules of the default locale. This is equivalent to calling
2555+ * <code>toLowerCase(Locale.getDefault())</code>.
2556+ * <p>
2557+ * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2558+ * results if used for strings that are intended to be interpreted locale
2559+ * independently.
2560+ * Examples are programming language identifiers, protocol keys, and HTML
2561+ * tags.
2562+ * For instance, <code>"TITLE".toLowerCase()</code> in a Turkish locale
2563+ * returns <code>"t\u005Cu0131tle"</code>, where '\u005Cu0131' is the
2564+ * LATIN SMALL LETTER DOTLESS I character.
2565+ * To obtain correct results for locale insensitive strings, use
2566+ * <code>toLowerCase(Locale.ENGLISH)</code>.
2567+ * <p>
2568+ * @return the <code>String</code>, converted to lowercase.
2569+ * @see java.lang.String#toLowerCase(Locale)
2570+ */
2571+ public String toLowerCase() {
2572+ return toLowerCase(Locale.getDefault());
2573+ }
2574+
2575+ /**
2576+ * Converts all of the characters in this <code>String</code> to upper
2577+ * case using the rules of the given <code>Locale</code>. Case mapping is based
2578+ * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2579+ * class. Since case mappings are not always 1:1 char mappings, the resulting
2580+ * <code>String</code> may be a different length than the original <code>String</code>.
2581+ * <p>
2582+ * Examples of locale-sensitive and 1:M case mappings are in the following table.
2583+ * <p>
2584+ * <table border="1" summary="Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description.">
2585+ * <tr>
2586+ * <th>Language Code of Locale</th>
2587+ * <th>Lower Case</th>
2588+ * <th>Upper Case</th>
2589+ * <th>Description</th>
2590+ * </tr>
2591+ * <tr>
2592+ * <td>tr (Turkish)</td>
2593+ * <td>&#92;u0069</td>
2594+ * <td>&#92;u0130</td>
2595+ * <td>small letter i -&gt; capital letter I with dot above</td>
2596+ * </tr>
2597+ * <tr>
2598+ * <td>tr (Turkish)</td>
2599+ * <td>&#92;u0131</td>
2600+ * <td>&#92;u0049</td>
2601+ * <td>small letter dotless i -&gt; capital letter I</td>
2602+ * </tr>
2603+ * <tr>
2604+ * <td>(all)</td>
2605+ * <td>&#92;u00df</td>
2606+ * <td>&#92;u0053 &#92;u0053</td>
2607+ * <td>small letter sharp s -&gt; two letters: SS</td>
2608+ * </tr>
2609+ * <tr>
2610+ * <td>(all)</td>
2611+ * <td>Fahrvergn&uuml;gen</td>
2612+ * <td>FAHRVERGN&Uuml;GEN</td>
2613+ * <td></td>
2614+ * </tr>
2615+ * </table>
2616+ * @param locale use the case transformation rules for this locale
2617+ * @return the <code>String</code>, converted to uppercase.
2618+ * @see java.lang.String#toUpperCase()
2619+ * @see java.lang.String#toLowerCase()
2620+ * @see java.lang.String#toLowerCase(Locale)
2621+ * @since 1.1
2622+ */
2623+ public String toUpperCase(Locale locale) {
2624+ if (locale == null) {
2625+ throw new NullPointerException();
2626+ }
2627+
2628+ int firstLower;
2629+
2630+ /* Now check if there are any characters that need to be changed. */
2631+ scan: {
2632+ for (firstLower = 0 ; firstLower < count; ) {
2633+ int c = (int)value[offset+firstLower];
2634+ int srcCount;
2635+ if ((c >= Character.MIN_HIGH_SURROGATE) &&
2636+ (c <= Character.MAX_HIGH_SURROGATE)) {
2637+ c = codePointAt(firstLower);
2638+ srcCount = Character.charCount(c);
2639+ } else {
2640+ srcCount = 1;
2641+ }
2642+ int upperCaseChar = Character.toUpperCaseEx(c);
2643+ if ((upperCaseChar == Character.ERROR) ||
2644+ (c != upperCaseChar)) {
2645+ break scan;
2646+ }
2647+ firstLower += srcCount;
2648+ }
2649+ return this;
2650+ }
2651+
2652+ char[] result = new char[count]; /* may grow */
2653+ int resultOffset = 0; /* result may grow, so i+resultOffset
2654+ * is the write location in result */
2655+
2656+ /* Just copy the first few upperCase characters. */
2657+ System.arraycopy(value, offset, result, 0, firstLower);
2658+
2659+ String lang = locale.getLanguage();
2660+ boolean localeDependent =
2661+ (lang == "tr" || lang == "az" || lang == "lt");
2662+ char[] upperCharArray;
2663+ int upperChar;
2664+ int srcChar;
2665+ int srcCount;
2666+ for (int i = firstLower; i < count; i += srcCount) {
2667+ srcChar = (int)value[offset+i];
2668+ if ((char)srcChar >= Character.MIN_HIGH_SURROGATE &&
2669+ (char)srcChar <= Character.MAX_HIGH_SURROGATE) {
2670+ srcChar = codePointAt(i);
2671+ srcCount = Character.charCount(srcChar);
2672+ } else {
2673+ srcCount = 1;
2674+ }
2675+ if (localeDependent) {
2676+ upperChar = ConditionalSpecialCasing.toUpperCaseEx(this, i, locale);
2677+ } else {
2678+ upperChar = Character.toUpperCaseEx(srcChar);
2679+ }
2680+ if ((upperChar == Character.ERROR) ||
2681+ (upperChar >= Character.MIN_SUPPLEMENTARY_CODE_POINT)) {
2682+ if (upperChar == Character.ERROR) {
2683+ if (localeDependent) {
2684+ upperCharArray =
2685+ ConditionalSpecialCasing.toUpperCaseCharArray(this, i, locale);
2686+ } else {
2687+ upperCharArray = Character.toUpperCaseCharArray(srcChar);
2688+ }
2689+ } else if (srcCount == 2) {
2690+ resultOffset += Character.toChars(upperChar, result, i + resultOffset) - srcCount;
2691+ continue;
2692+ } else {
2693+ upperCharArray = Character.toChars(upperChar);
2694+ }
2695+
2696+ /* Grow result if needed */
2697+ int mapLen = upperCharArray.length;
2698+ if (mapLen > srcCount) {
2699+ char[] result2 = new char[result.length + mapLen - srcCount];
2700+ System.arraycopy(result, 0, result2, 0,
2701+ i + resultOffset);
2702+ result = result2;
2703+ }
2704+ for (int x=0; x<mapLen; ++x) {
2705+ result[i+resultOffset+x] = upperCharArray[x];
2706+ }
2707+ resultOffset += (mapLen - srcCount);
2708+ } else {
2709+ result[i+resultOffset] = (char)upperChar;
2710+ }
2711+ }
2712+ return new String(0, count+resultOffset, result);
2713+ }
2714+
2715+ /**
2716+ * Converts all of the characters in this <code>String</code> to upper
2717+ * case using the rules of the default locale. This method is equivalent to
2718+ * <code>toUpperCase(Locale.getDefault())</code>.
2719+ * <p>
2720+ * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2721+ * results if used for strings that are intended to be interpreted locale
2722+ * independently.
2723+ * Examples are programming language identifiers, protocol keys, and HTML
2724+ * tags.
2725+ * For instance, <code>"title".toUpperCase()</code> in a Turkish locale
2726+ * returns <code>"T\u005Cu0130TLE"</code>, where '\u005Cu0130' is the
2727+ * LATIN CAPITAL LETTER I WITH DOT ABOVE character.
2728+ * To obtain correct results for locale insensitive strings, use
2729+ * <code>toUpperCase(Locale.ENGLISH)</code>.
2730+ * <p>
2731+ * @return the <code>String</code>, converted to uppercase.
2732+ * @see java.lang.String#toUpperCase(Locale)
2733+ */
2734+ public String toUpperCase() {
2735+ return toUpperCase(Locale.getDefault());
2736+ }
2737+
2738+ /**
2739+ * Returns a copy of the string, with leading and trailing whitespace
2740+ * omitted.
2741+ * <p>
2742+ * If this <code>String</code> object represents an empty character
2743+ * sequence, or the first and last characters of character sequence
2744+ * represented by this <code>String</code> object both have codes
2745+ * greater than <code>'&#92;u0020'</code> (the space character), then a
2746+ * reference to this <code>String</code> object is returned.
2747+ * <p>
2748+ * Otherwise, if there is no character with a code greater than
2749+ * <code>'&#92;u0020'</code> in the string, then a new
2750+ * <code>String</code> object representing an empty string is created
2751+ * and returned.
2752+ * <p>
2753+ * Otherwise, let <i>k</i> be the index of the first character in the
2754+ * string whose code is greater than <code>'&#92;u0020'</code>, and let
2755+ * <i>m</i> be the index of the last character in the string whose code
2756+ * is greater than <code>'&#92;u0020'</code>. A new <code>String</code>
2757+ * object is created, representing the substring of this string that
2758+ * begins with the character at index <i>k</i> and ends with the
2759+ * character at index <i>m</i>-that is, the result of
2760+ * <code>this.substring(<i>k</i>,&nbsp;<i>m</i>+1)</code>.
2761+ * <p>
2762+ * This method may be used to trim whitespace (as defined above) from
2763+ * the beginning and end of a string.
2764+ *
2765+ * @return A copy of this string with leading and trailing white
2766+ * space removed, or this string if it has no leading or
2767+ * trailing white space.
2768+ */
2769+ public String trim() {
2770+ int len = count;
2771+ int st = 0;
2772+ int off = offset; /* avoid getfield opcode */
2773+ char[] val = value; /* avoid getfield opcode */
2774+
2775+ while ((st < len) && (val[off + st] <= ' ')) {
2776+ st++;
2777+ }
2778+ while ((st < len) && (val[off + len - 1] <= ' ')) {
2779+ len--;
2780+ }
2781+ return ((st > 0) || (len < count)) ? substring(st, len) : this;
2782+ }
2783+
2784+ /**
2785+ * This object (which is already a string!) is itself returned.
2786+ *
2787+ * @return the string itself.
2788+ */
2789+ public String toString() {
2790+ return this;
2791+ }
2792+
2793+ /**
2794+ * Converts this string to a new character array.
2795+ *
2796+ * @return a newly allocated character array whose length is the length
2797+ * of this string and whose contents are initialized to contain
2798+ * the character sequence represented by this string.
2799+ */
2800+ public char[] toCharArray() {
2801+ char result[] = new char[count];
2802+ getChars(0, count, result, 0);
2803+ return result;
2804+ }
2805+
2806+ /**
2807+ * Returns a formatted string using the specified format string and
2808+ * arguments.
2809+ *
2810+ * <p> The locale always used is the one returned by {@link
2811+ * java.util.Locale#getDefault() Locale.getDefault()}.
2812+ *
2813+ * @param format
2814+ * A <a href="../util/Formatter.html#syntax">format string</a>
2815+ *
2816+ * @param args
2817+ * Arguments referenced by the format specifiers in the format
2818+ * string. If there are more arguments than format specifiers, the
2819+ * extra arguments are ignored. The number of arguments is
2820+ * variable and may be zero. The maximum number of arguments is
2821+ * limited by the maximum dimension of a Java array as defined by
2822+ * <cite>The Java&trade; Virtual Machine Specification</cite>.
2823+ * The behaviour on a
2824+ * <tt>null</tt> argument depends on the <a
2825+ * href="../util/Formatter.html#syntax">conversion</a>.
2826+ *
2827+ * @throws IllegalFormatException
2828+ * If a format string contains an illegal syntax, a format
2829+ * specifier that is incompatible with the given arguments,
2830+ * insufficient arguments given the format string, or other
2831+ * illegal conditions. For specification of all possible
2832+ * formatting errors, see the <a
2833+ * href="../util/Formatter.html#detail">Details</a> section of the
2834+ * formatter class specification.
2835+ *
2836+ * @throws NullPointerException
2837+ * If the <tt>format</tt> is <tt>null</tt>
2838+ *
2839+ * @return A formatted string
2840+ *
2841+ * @see java.util.Formatter
2842+ * @since 1.5
2843+ */
2844+ public static String format(String format, Object ... args) {
2845+ return new Formatter().format(format, args).toString();
2846+ }
2847+
2848+ /**
2849+ * Returns a formatted string using the specified locale, format string,
2850+ * and arguments.
2851+ *
2852+ * @param l
2853+ * The {@linkplain java.util.Locale locale} to apply during
2854+ * formatting. If <tt>l</tt> is <tt>null</tt> then no localization
2855+ * is applied.
2856+ *
2857+ * @param format
2858+ * A <a href="../util/Formatter.html#syntax">format string</a>
2859+ *
2860+ * @param args
2861+ * Arguments referenced by the format specifiers in the format
2862+ * string. If there are more arguments than format specifiers, the
2863+ * extra arguments are ignored. The number of arguments is
2864+ * variable and may be zero. The maximum number of arguments is
2865+ * limited by the maximum dimension of a Java array as defined by
2866+ * <cite>The Java&trade; Virtual Machine Specification</cite>.
2867+ * The behaviour on a
2868+ * <tt>null</tt> argument depends on the <a
2869+ * href="../util/Formatter.html#syntax">conversion</a>.
2870+ *
2871+ * @throws IllegalFormatException
2872+ * If a format string contains an illegal syntax, a format
2873+ * specifier that is incompatible with the given arguments,
2874+ * insufficient arguments given the format string, or other
2875+ * illegal conditions. For specification of all possible
2876+ * formatting errors, see the <a
2877+ * href="../util/Formatter.html#detail">Details</a> section of the
2878+ * formatter class specification
2879+ *
2880+ * @throws NullPointerException
2881+ * If the <tt>format</tt> is <tt>null</tt>
2882+ *
2883+ * @return A formatted string
2884+ *
2885+ * @see java.util.Formatter
2886+ * @since 1.5
2887+ */
2888+ public static String format(Locale l, String format, Object ... args) {
2889+ return new Formatter(l).format(format, args).toString();
2890+ }
2891+
2892+ /**
2893+ * Returns the string representation of the <code>Object</code> argument.
2894+ *
2895+ * @param obj an <code>Object</code>.
2896+ * @return if the argument is <code>null</code>, then a string equal to
2897+ * <code>"null"</code>; otherwise, the value of
2898+ * <code>obj.toString()</code> is returned.
2899+ * @see java.lang.Object#toString()
2900+ */
2901+ public static String valueOf(Object obj) {
2902+ return (obj == null) ? "null" : obj.toString();
2903+ }
2904+
2905+ /**
2906+ * Returns the string representation of the <code>char</code> array
2907+ * argument. The contents of the character array are copied; subsequent
2908+ * modification of the character array does not affect the newly
2909+ * created string.
2910+ *
2911+ * @param data a <code>char</code> array.
2912+ * @return a newly allocated string representing the same sequence of
2913+ * characters contained in the character array argument.
2914+ */
2915+ public static String valueOf(char data[]) {
2916+ return new String(data);
2917+ }
2918+
2919+ /**
2920+ * Returns the string representation of a specific subarray of the
2921+ * <code>char</code> array argument.
2922+ * <p>
2923+ * The <code>offset</code> argument is the index of the first
2924+ * character of the subarray. The <code>count</code> argument
2925+ * specifies the length of the subarray. The contents of the subarray
2926+ * are copied; subsequent modification of the character array does not
2927+ * affect the newly created string.
2928+ *
2929+ * @param data the character array.
2930+ * @param offset the initial offset into the value of the
2931+ * <code>String</code>.
2932+ * @param count the length of the value of the <code>String</code>.
2933+ * @return a string representing the sequence of characters contained
2934+ * in the subarray of the character array argument.
2935+ * @exception IndexOutOfBoundsException if <code>offset</code> is
2936+ * negative, or <code>count</code> is negative, or
2937+ * <code>offset+count</code> is larger than
2938+ * <code>data.length</code>.
2939+ */
2940+ public static String valueOf(char data[], int offset, int count) {
2941+ return new String(data, offset, count);
2942+ }
2943+
2944+ /**
2945+ * Returns a String that represents the character sequence in the
2946+ * array specified.
2947+ *
2948+ * @param data the character array.
2949+ * @param offset initial offset of the subarray.
2950+ * @param count length of the subarray.
2951+ * @return a <code>String</code> that contains the characters of the
2952+ * specified subarray of the character array.
2953+ */
2954+ public static String copyValueOf(char data[], int offset, int count) {
2955+ // All public String constructors now copy the data.
2956+ return new String(data, offset, count);
2957+ }
2958+
2959+ /**
2960+ * Returns a String that represents the character sequence in the
2961+ * array specified.
2962+ *
2963+ * @param data the character array.
2964+ * @return a <code>String</code> that contains the characters of the
2965+ * character array.
2966+ */
2967+ public static String copyValueOf(char data[]) {
2968+ return copyValueOf(data, 0, data.length);
2969+ }
2970+
2971+ /**
2972+ * Returns the string representation of the <code>boolean</code> argument.
2973+ *
2974+ * @param b a <code>boolean</code>.
2975+ * @return if the argument is <code>true</code>, a string equal to
2976+ * <code>"true"</code> is returned; otherwise, a string equal to
2977+ * <code>"false"</code> is returned.
2978+ */
2979+ public static String valueOf(boolean b) {
2980+ return b ? "true" : "false";
2981+ }
2982+
2983+ /**
2984+ * Returns the string representation of the <code>char</code>
2985+ * argument.
2986+ *
2987+ * @param c a <code>char</code>.
2988+ * @return a string of length <code>1</code> containing
2989+ * as its single character the argument <code>c</code>.
2990+ */
2991+ public static String valueOf(char c) {
2992+ char data[] = {c};
2993+ return new String(0, 1, data);
2994+ }
2995+
2996+ /**
2997+ * Returns the string representation of the <code>int</code> argument.
2998+ * <p>
2999+ * The representation is exactly the one returned by the
3000+ * <code>Integer.toString</code> method of one argument.
3001+ *
3002+ * @param i an <code>int</code>.
3003+ * @return a string representation of the <code>int</code> argument.
3004+ * @see java.lang.Integer#toString(int, int)
3005+ */
3006+ public static String valueOf(int i) {
3007+ return Integer.toString(i);
3008+ }
3009+
3010+ /**
3011+ * Returns the string representation of the <code>long</code> argument.
3012+ * <p>
3013+ * The representation is exactly the one returned by the
3014+ * <code>Long.toString</code> method of one argument.
3015+ *
3016+ * @param l a <code>long</code>.
3017+ * @return a string representation of the <code>long</code> argument.
3018+ * @see java.lang.Long#toString(long)
3019+ */
3020+ public static String valueOf(long l) {
3021+ return Long.toString(l);
3022+ }
3023+
3024+ /**
3025+ * Returns the string representation of the <code>float</code> argument.
3026+ * <p>
3027+ * The representation is exactly the one returned by the
3028+ * <code>Float.toString</code> method of one argument.
3029+ *
3030+ * @param f a <code>float</code>.
3031+ * @return a string representation of the <code>float</code> argument.
3032+ * @see java.lang.Float#toString(float)
3033+ */
3034+ public static String valueOf(float f) {
3035+ return Float.toString(f);
3036+ }
3037+
3038+ /**
3039+ * Returns the string representation of the <code>double</code> argument.
3040+ * <p>
3041+ * The representation is exactly the one returned by the
3042+ * <code>Double.toString</code> method of one argument.
3043+ *
3044+ * @param d a <code>double</code>.
3045+ * @return a string representation of the <code>double</code> argument.
3046+ * @see java.lang.Double#toString(double)
3047+ */
3048+ public static String valueOf(double d) {
3049+ return Double.toString(d);
3050+ }
3051+
3052+ /**
3053+ * Returns a canonical representation for the string object.
3054+ * <p>
3055+ * A pool of strings, initially empty, is maintained privately by the
3056+ * class <code>String</code>.
3057+ * <p>
3058+ * When the intern method is invoked, if the pool already contains a
3059+ * string equal to this <code>String</code> object as determined by
3060+ * the {@link #equals(Object)} method, then the string from the pool is
3061+ * returned. Otherwise, this <code>String</code> object is added to the
3062+ * pool and a reference to this <code>String</code> object is returned.
3063+ * <p>
3064+ * It follows that for any two strings <code>s</code> and <code>t</code>,
3065+ * <code>s.intern()&nbsp;==&nbsp;t.intern()</code> is <code>true</code>
3066+ * if and only if <code>s.equals(t)</code> is <code>true</code>.
3067+ * <p>
3068+ * All literal strings and string-valued constant expressions are
3069+ * interned. String literals are defined in section 3.10.5 of the
3070+ * <cite>The Java&trade; Language Specification</cite>.
3071+ *
3072+ * @return a string that has the same contents as this string, but is
3073+ * guaranteed to be from a pool of unique strings.
3074+ */
3075+ public native String intern();
3076+
3077+}