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