关闭

java String源码

标签: javastring源码
682人阅读 评论(0) 收藏 举报
分类:
  1. /* 
  2.  * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved. 
  3.  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 
  4.  * 
  5.  * 
  6.  * 
  7.  * 
  8.  * 
  9.  * 
  10.  * 
  11.  * 
  12.  * 
  13.  * 
  14.  * 
  15.  * 
  16.  * 
  17.  * 
  18.  * 
  19.  * 
  20.  * 
  21.  * 
  22.  * 
  23.  * 
  24.  */  
  25. package java.lang;  
  26.   
  27. import java.io.ObjectStreamField;  
  28. import java.io.UnsupportedEncodingException;  
  29. import java.nio.charset.Charset;  
  30. import java.util.ArrayList;  
  31. import java.util.Arrays;  
  32. import java.util.Comparator;  
  33. import java.util.Formatter;  
  34. import java.util.Locale;  
  35. import java.util.regex.Matcher;  
  36. import java.util.regex.Pattern;  
  37. import java.util.regex.PatternSyntaxException;  
  38.   
  39. /** 
  40.  * The <code>String</code> class represents character strings. All 
  41.  * string literals in Java programs, such as <code>"abc"</code>, are 
  42.  * implemented as instances of this class. 
  43.  * <p> 
  44.  * Strings are constant; their values cannot be changed after they 
  45.  * are created. String buffers support mutable strings. 
  46.  * Because String objects are immutable they can be shared. For example: 
  47.  * <p><blockquote><pre> 
  48.  *     String str = "abc"; 
  49.  * </pre></blockquote><p> 
  50.  * is equivalent to: 
  51.  * <p><blockquote><pre> 
  52.  *     char data[] = {'a', 'b', 'c'}; 
  53.  *     String str = new String(data); 
  54.  * </pre></blockquote><p> 
  55.  * Here are some more examples of how strings can be used: 
  56.  * <p><blockquote><pre> 
  57.  *     System.out.println("abc"); 
  58.  *     String cde = "cde"; 
  59.  *     System.out.println("abc" + cde); 
  60.  *     String c = "abc".substring(2,3); 
  61.  *     String d = cde.substring(1, 2); 
  62.  * </pre></blockquote> 
  63.  * <p> 
  64.  * The class <code>String</code> includes methods for examining 
  65.  * individual characters of the sequence, for comparing strings, for 
  66.  * searching strings, for extracting substrings, and for creating a 
  67.  * copy of a string with all characters translated to uppercase or to 
  68.  * lowercase. Case mapping is based on the Unicode Standard version 
  69.  * specified by the {@link java.lang.Character Character} class. 
  70.  * <p> 
  71.  * The Java language provides special support for the string 
  72.  * concatenation operator ( + ), and for conversion of 
  73.  * other objects to strings. String concatenation is implemented 
  74.  * through the <code>StringBuilder</code>(or <code>StringBuffer</code>) 
  75.  * class and its <code>append</code> method. 
  76.  * String conversions are implemented through the method 
  77.  * <code>toString</code>, defined by <code>Object</code> and 
  78.  * inherited by all classes in Java. For additional information on 
  79.  * string concatenation and conversion, see Gosling, Joy, and Steele, 
  80.  * <i>The Java Language Specification</i>. 
  81.  * 
  82.  * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor 
  83.  * or method in this class will cause a {@link NullPointerException} to be 
  84.  * thrown. 
  85.  * 
  86.  * <p>A <code>String</code> represents a string in the UTF-16 format 
  87.  * in which <em>supplementary characters</em> are represented by <em>surrogate 
  88.  * pairs</em> (see the section <a href="Character.html#unicode">Unicode 
  89.  * Character Representations</a> in the <code>Character</code> class for 
  90.  * more information). 
  91.  * Index values refer to <code>char</code> code units, so a supplementary 
  92.  * character uses two positions in a <code>String</code>. 
  93.  * <p>The <code>String</code> class provides methods for dealing with 
  94.  * Unicode code points (i.e., characters), in addition to those for 
  95.  * dealing with Unicode code units (i.e., <code>char</code> values). 
  96.  * 
  97.  * @author  Lee Boynton 
  98.  * @author  Arthur van Hoff 
  99.  * @author  Martin Buchholz 
  100.  * @author  Ulf Zibis 
  101.  * @see     java.lang.Object#toString() 
  102.  * @see     java.lang.StringBuffer 
  103.  * @see     java.lang.StringBuilder 
  104.  * @see     java.nio.charset.Charset 
  105.  * @since   JDK1.0 
  106.  */  
  107.   
  108. public final class String  
  109.     implements java.io.Serializable, Comparable<String>, CharSequence {  
  110.     /** The value is used for character storage. */  
  111.     private final char value[];  
  112.   
  113.     /** Cache the hash code for the string */  
  114.     private int hash; // Default to 0  
  115.   
  116.     /** use serialVersionUID from JDK 1.0.2 for interoperability */  
  117.     private static final long serialVersionUID = -6849794470754667710L;  
  118.   
  119.     /** 
  120.      * Class String is special cased within the Serialization Stream Protocol. 
  121.      * 
  122.      * A String instance is written initially into an ObjectOutputStream in the 
  123.      * following format: 
  124.      * <pre> 
  125.      *      <code>TC_STRING</code> (utf String) 
  126.      * </pre> 
  127.      * The String is written by method <code>DataOutput.writeUTF</code>. 
  128.      * A new handle is generated to  refer to all future references to the 
  129.      * string instance within the stream. 
  130.      */  
  131.     private static final ObjectStreamField[] serialPersistentFields =  
  132.             new ObjectStreamField[0];  
  133.   
  134.     /** 
  135.      * Initializes a newly created {@code String} object so that it represents 
  136.      * an empty character sequence.  Note that use of this constructor is 
  137.      * unnecessary since Strings are immutable. 
  138.      */  
  139.     public String() {  
  140.         this.value = new char[0];  
  141.     }  
  142.   
  143.     /** 
  144.      * Initializes a newly created {@code String} object so that it represents 
  145.      * the same sequence of characters as the argument; in other words, the 
  146.      * newly created string is a copy of the argument string. Unless an 
  147.      * explicit copy of {@code original} is needed, use of this constructor is 
  148.      * unnecessary since Strings are immutable. 
  149.      * 
  150.      * @param  original 
  151.      *         A {@code String} 
  152.      */  
  153.     public String(String original) {  
  154.         this.value = original.value;  
  155.         this.hash = original.hash;  
  156.     }  
  157.   
  158.     /** 
  159.      * Allocates a new {@code String} so that it represents the sequence of 
  160.      * characters currently contained in the character array argument. The 
  161.      * contents of the character array are copied; subsequent modification of 
  162.      * the character array does not affect the newly created string. 
  163.      * 
  164.      * @param  value 
  165.      *         The initial value of the string 
  166.      */  
  167.     public String(char value[]) {  
  168.         this.value = Arrays.copyOf(value, value.length);  
  169.     }  
  170.   
  171.     /** 
  172.      * Allocates a new {@code String} that contains characters from a subarray 
  173.      * of the character array argument. The {@code offset} argument is the 
  174.      * index of the first character of the subarray and the {@code count} 
  175.      * argument specifies the length of the subarray. The contents of the 
  176.      * subarray are copied; subsequent modification of the character array does 
  177.      * not affect the newly created string. 
  178.      * 
  179.      * @param  value 
  180.      *         Array that is the source of characters 
  181.      * 
  182.      * @param  offset 
  183.      *         The initial offset 
  184.      * 
  185.      * @param  count 
  186.      *         The length 
  187.      * 
  188.      * @throws  IndexOutOfBoundsException 
  189.      *          If the {@code offset} and {@code count} arguments index 
  190.      *          characters outside the bounds of the {@code value} array 
  191.      */  
  192.     public String(char value[], int offset, int count) {  
  193.         if (offset < 0) {  
  194.             throw new StringIndexOutOfBoundsException(offset);  
  195.         }  
  196.         if (count < 0) {  
  197.             throw new StringIndexOutOfBoundsException(count);  
  198.         }  
  199.         // Note: offset or count might be near -1>>>1.  
  200.         if (offset > value.length - count) {  
  201.             throw new StringIndexOutOfBoundsException(offset + count);  
  202.         }  
  203.         this.value = Arrays.copyOfRange(value, offset, offset+count);  
  204.     }  
  205.   
  206.     /** 
  207.      * Allocates a new {@code String} that contains characters from a subarray 
  208.      * of the <a href="Character.html#unicode">Unicode code point</a> array 
  209.      * argument.  The {@code offset} argument is the index of the first code 
  210.      * point of the subarray and the {@code count} argument specifies the 
  211.      * length of the subarray.  The contents of the subarray are converted to 
  212.      * {@code char}s; subsequent modification of the {@code int} array does not 
  213.      * affect the newly created string. 
  214.      * 
  215.      * @param  codePoints 
  216.      *         Array that is the source of Unicode code points 
  217.      * 
  218.      * @param  offset 
  219.      *         The initial offset 
  220.      * 
  221.      * @param  count 
  222.      *         The length 
  223.      * 
  224.      * @throws  IllegalArgumentException 
  225.      *          If any invalid Unicode code point is found in {@code 
  226.      *          codePoints} 
  227.      * 
  228.      * @throws  IndexOutOfBoundsException 
  229.      *          If the {@code offset} and {@code count} arguments index 
  230.      *          characters outside the bounds of the {@code codePoints} array 
  231.      * 
  232.      * @since  1.5 
  233.      */  
  234.     public String(int[] codePoints, int offset, int count) {  
  235.         if (offset < 0) {  
  236.             throw new StringIndexOutOfBoundsException(offset);  
  237.         }  
  238.         if (count < 0) {  
  239.             throw new StringIndexOutOfBoundsException(count);  
  240.         }  
  241.         // Note: offset or count might be near -1>>>1.  
  242.         if (offset > codePoints.length - count) {  
  243.             throw new StringIndexOutOfBoundsException(offset + count);  
  244.         }  
  245.   
  246.         final int end = offset + count;  
  247.   
  248.         // Pass 1: Compute precise size of char[]  
  249.         int n = count;  
  250.         for (int i = offset; i < end; i++) {  
  251.             int c = codePoints[i];  
  252.             if (Character.isBmpCodePoint(c))  
  253.                 continue;  
  254.             else if (Character.isValidCodePoint(c))  
  255.                 n++;  
  256.             else throw new IllegalArgumentException(Integer.toString(c));  
  257.         }  
  258.   
  259.         // Pass 2: Allocate and fill in char[]  
  260.         final char[] v = new char[n];  
  261.   
  262.         for (int i = offset, j = 0; i < end; i++, j++) {  
  263.             int c = codePoints[i];  
  264.             if (Character.isBmpCodePoint(c))  
  265.                 v[j] = (char)c;  
  266.             else  
  267.                 Character.toSurrogates(c, v, j++);  
  268.         }  
  269.   
  270.         this.value = v;  
  271.     }  
  272.   
  273.     /** 
  274.      * Allocates a new {@code String} constructed from a subarray of an array 
  275.      * of 8-bit integer values. 
  276.      * 
  277.      * <p> The {@code offset} argument is the index of the first byte of the 
  278.      * subarray, and the {@code count} argument specifies the length of the 
  279.      * subarray. 
  280.      * 
  281.      * <p> Each {@code byte} in the subarray is converted to a {@code char} as 
  282.      * specified in the method above. 
  283.      * 
  284.      * @deprecated This method does not properly convert bytes into characters. 
  285.      * As of JDK 1.1, the preferred way to do this is via the 
  286.      * {@code String} constructors that take a {@link 
  287.      * java.nio.charset.Charset}, charset name, or that use the platform's 
  288.      * default charset. 
  289.      * 
  290.      * @param  ascii 
  291.      *         The bytes to be converted to characters 
  292.      * 
  293.      * @param  hibyte 
  294.      *         The top 8 bits of each 16-bit Unicode code unit 
  295.      * 
  296.      * @param  offset 
  297.      *         The initial offset 
  298.      * @param  count 
  299.      *         The length 
  300.      * 
  301.      * @throws  IndexOutOfBoundsException 
  302.      *          If the {@code offset} or {@code count} argument is invalid 
  303.      * 
  304.      * @see  #String(byte[], int) 
  305.      * @see  #String(byte[], int, int, java.lang.String) 
  306.      * @see  #String(byte[], int, int, java.nio.charset.Charset) 
  307.      * @see  #String(byte[], int, int) 
  308.      * @see  #String(byte[], java.lang.String) 
  309.      * @see  #String(byte[], java.nio.charset.Charset) 
  310.      * @see  #String(byte[]) 
  311.      */  
  312.     @Deprecated  
  313.     public String(byte ascii[], int hibyte, int offset, int count) {  
  314.         checkBounds(ascii, offset, count);  
  315.         char value[] = new char[count];  
  316.   
  317.         if (hibyte == 0) {  
  318.             for (int i = count; i-- > 0;) {  
  319.                 value[i] = (char)(ascii[i + offset] & 0xff);  
  320.             }  
  321.         } else {  
  322.             hibyte <<= 8;  
  323.             for (int i = count; i-- > 0;) {  
  324.                 value[i] = (char)(hibyte | (ascii[i + offset] & 0xff));  
  325.             }  
  326.         }  
  327.         this.value = value;  
  328.     }  
  329.   
  330.     /** 
  331.      * Allocates a new {@code String} containing characters constructed from 
  332.      * an array of 8-bit integer values. Each character <i>c</i>in the 
  333.      * resulting string is constructed from the corresponding component 
  334.      * <i>b</i> in the byte array such that: 
  335.      * 
  336.      * <blockquote><pre> 
  337.      *     <b><i>c</i></b> == (char)(((hibyte & 0xff) << 8) 
  338.      *                         | (<b><i>b</i></b> & 0xff)) 
  339.      * </pre></blockquote> 
  340.      * 
  341.      * @deprecated  This method does not properly convert bytes into 
  342.      * characters.  As of JDK 1.1, the preferred way to do this is via the 
  343.      * {@code String} constructors that take a {@link 
  344.      * java.nio.charset.Charset}, charset name, or that use the platform's 
  345.      * default charset. 
  346.      * 
  347.      * @param  ascii 
  348.      *         The bytes to be converted to characters 
  349.      * 
  350.      * @param  hibyte 
  351.      *         The top 8 bits of each 16-bit Unicode code unit 
  352.      * 
  353.      * @see  #String(byte[], int, int, java.lang.String) 
  354.      * @see  #String(byte[], int, int, java.nio.charset.Charset) 
  355.      * @see  #String(byte[], int, int) 
  356.      * @see  #String(byte[], java.lang.String) 
  357.      * @see  #String(byte[], java.nio.charset.Charset) 
  358.      * @see  #String(byte[]) 
  359.      */  
  360.     @Deprecated  
  361.     public String(byte ascii[], int hibyte) {  
  362.         this(ascii, hibyte, 0, ascii.length);  
  363.     }  
  364.   
  365.     /* Common private utility method used to bounds check the byte array 
  366.      * and requested offset & length values used by the String(byte[],..) 
  367.      * constructors. 
  368.      */  
  369.     private static void checkBounds(byte[] bytes, int offset, int length) {  
  370.         if (length < 0)  
  371.             throw new StringIndexOutOfBoundsException(length);  
  372.         if (offset < 0)  
  373.             throw new StringIndexOutOfBoundsException(offset);  
  374.         if (offset > bytes.length - length)  
  375.             throw new StringIndexOutOfBoundsException(offset + length);  
  376.     }  
  377.   
  378.     /** 
  379.      * Constructs a new {@code String} by decoding the specified subarray of 
  380.      * bytes using the specified charset.  The length of the new {@code String} 
  381.      * is a function of the charset, and hence may not be equal to the length 
  382.      * of the subarray. 
  383.      * 
  384.      * <p> The behavior of this constructor when the given bytes are not valid 
  385.      * in the given charset is unspecified.  The {@link 
  386.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  387.      * over the decoding process is required. 
  388.      * 
  389.      * @param  bytes 
  390.      *         The bytes to be decoded into characters 
  391.      * 
  392.      * @param  offset 
  393.      *         The index of the first byte to decode 
  394.      * 
  395.      * @param  length 
  396.      *         The number of bytes to decode 
  397.  
  398.      * @param  charsetName 
  399.      *         The name of a supported {@linkplain java.nio.charset.Charset 
  400.      *         charset} 
  401.      * 
  402.      * @throws  UnsupportedEncodingException 
  403.      *          If the named charset is not supported 
  404.      * 
  405.      * @throws  IndexOutOfBoundsException 
  406.      *          If the {@code offset} and {@code length} arguments index 
  407.      *          characters outside the bounds of the {@code bytes} array 
  408.      * 
  409.      * @since  JDK1.1 
  410.      */  
  411.     public String(byte bytes[], int offset, int length, String charsetName)  
  412.             throws UnsupportedEncodingException {  
  413.         if (charsetName == null)  
  414.             throw new NullPointerException("charsetName");  
  415.         checkBounds(bytes, offset, length);  
  416.         this.value = StringCoding.decode(charsetName, bytes, offset, length);  
  417.     }  
  418.   
  419.     /** 
  420.      * Constructs a new {@code String} by decoding the specified subarray of 
  421.      * bytes using the specified {@linkplain java.nio.charset.Charset charset}. 
  422.      * The length of the new {@code String} is a function of the charset, and 
  423.      * hence may not be equal to the length of the subarray. 
  424.      * 
  425.      * <p> This method always replaces malformed-input and unmappable-character 
  426.      * sequences with this charset's default replacement string.  The {@link 
  427.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  428.      * over the decoding process is required. 
  429.      * 
  430.      * @param  bytes 
  431.      *         The bytes to be decoded into characters 
  432.      * 
  433.      * @param  offset 
  434.      *         The index of the first byte to decode 
  435.      * 
  436.      * @param  length 
  437.      *         The number of bytes to decode 
  438.      * 
  439.      * @param  charset 
  440.      *         The {@linkplain java.nio.charset.Charset charset} to be used to 
  441.      *         decode the {@code bytes} 
  442.      * 
  443.      * @throws  IndexOutOfBoundsException 
  444.      *          If the {@code offset} and {@code length} arguments index 
  445.      *          characters outside the bounds of the {@code bytes} array 
  446.      * 
  447.      * @since  1.6 
  448.      */  
  449.     public String(byte bytes[], int offset, int length, Charset charset) {  
  450.         if (charset == null)  
  451.             throw new NullPointerException("charset");  
  452.         checkBounds(bytes, offset, length);  
  453.         this.value =  StringCoding.decode(charset, bytes, offset, length);  
  454.     }  
  455.   
  456.     /** 
  457.      * Constructs a new {@code String} by decoding the specified array of bytes 
  458.      * using the specified {@linkplain java.nio.charset.Charset charset}.  The 
  459.      * length of the new {@code String} is a function of the charset, and hence 
  460.      * may not be equal to the length of the byte array. 
  461.      * 
  462.      * <p> The behavior of this constructor when the given bytes are not valid 
  463.      * in the given charset is unspecified.  The {@link 
  464.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  465.      * over the decoding process is required. 
  466.      * 
  467.      * @param  bytes 
  468.      *         The bytes to be decoded into characters 
  469.      * 
  470.      * @param  charsetName 
  471.      *         The name of a supported {@linkplain java.nio.charset.Charset 
  472.      *         charset} 
  473.      * 
  474.      * @throws  UnsupportedEncodingException 
  475.      *          If the named charset is not supported 
  476.      * 
  477.      * @since  JDK1.1 
  478.      */  
  479.     public String(byte bytes[], String charsetName)  
  480.             throws UnsupportedEncodingException {  
  481.         this(bytes, 0, bytes.length, charsetName);  
  482.     }  
  483.   
  484.     /** 
  485.      * Constructs a new {@code String} by decoding the specified array of 
  486.      * bytes using the specified {@linkplain java.nio.charset.Charset charset}. 
  487.      * The length of the new {@code String} is a function of the charset, and 
  488.      * hence may not be equal to the length of the byte array. 
  489.      * 
  490.      * <p> This method always replaces malformed-input and unmappable-character 
  491.      * sequences with this charset's default replacement string.  The {@link 
  492.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  493.      * over the decoding process is required. 
  494.      * 
  495.      * @param  bytes 
  496.      *         The bytes to be decoded into characters 
  497.      * 
  498.      * @param  charset 
  499.      *         The {@linkplain java.nio.charset.Charset charset} to be used to 
  500.      *         decode the {@code bytes} 
  501.      * 
  502.      * @since  1.6 
  503.      */  
  504.     public String(byte bytes[], Charset charset) {  
  505.         this(bytes, 0, bytes.length, charset);  
  506.     }  
  507.   
  508.     /** 
  509.      * Constructs a new {@code String} by decoding the specified subarray of 
  510.      * bytes using the platform's default charset.  The length of the new 
  511.      * {@code String} is a function of the charset, and hence may not be equal 
  512.      * to the length of the subarray. 
  513.      * 
  514.      * <p> The behavior of this constructor when the given bytes are not valid 
  515.      * in the default charset is unspecified.  The {@link 
  516.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  517.      * over the decoding process is required. 
  518.      * 
  519.      * @param  bytes 
  520.      *         The bytes to be decoded into characters 
  521.      * 
  522.      * @param  offset 
  523.      *         The index of the first byte to decode 
  524.      * 
  525.      * @param  length 
  526.      *         The number of bytes to decode 
  527.      * 
  528.      * @throws  IndexOutOfBoundsException 
  529.      *          If the {@code offset} and the {@code length} arguments index 
  530.      *          characters outside the bounds of the {@code bytes} array 
  531.      * 
  532.      * @since  JDK1.1 
  533.      */  
  534.     public String(byte bytes[], int offset, int length) {  
  535.         checkBounds(bytes, offset, length);  
  536.         this.value = StringCoding.decode(bytes, offset, length);  
  537.     }  
  538.   
  539.     /** 
  540.      * Constructs a new {@code String} by decoding the specified array of bytes 
  541.      * using the platform's default charset.  The length of the new {@code 
  542.      * String} is a function of the charset, and hence may not be equal to the 
  543.      * length of the byte array. 
  544.      * 
  545.      * <p> The behavior of this constructor when the given bytes are not valid 
  546.      * in the default charset is unspecified.  The {@link 
  547.      * java.nio.charset.CharsetDecoder} class should be used when more control 
  548.      * over the decoding process is required. 
  549.      * 
  550.      * @param  bytes 
  551.      *         The bytes to be decoded into characters 
  552.      * 
  553.      * @since  JDK1.1 
  554.      */  
  555.     public String(byte bytes[]) {  
  556.         this(bytes, 0, bytes.length);  
  557.     }  
  558.   
  559.     /** 
  560.      * Allocates a new string that contains the sequence of characters 
  561.      * currently contained in the string buffer argument. The contents of the 
  562.      * string buffer are copied; subsequent modification of the string buffer 
  563.      * does not affect the newly created string. 
  564.      * 
  565.      * @param  buffer 
  566.      *         A {@code StringBuffer} 
  567.      */  
  568.     public String(StringBuffer buffer) {  
  569.         synchronized(buffer) {  
  570.             this.value = Arrays.copyOf(buffer.getValue(), buffer.length());  
  571.         }  
  572.     }  
  573.   
  574.     /** 
  575.      * Allocates a new string that contains the sequence of characters 
  576.      * currently contained in the string builder argument. The contents of the 
  577.      * string builder are copied; subsequent modification of the string builder 
  578.      * does not affect the newly created string. 
  579.      * 
  580.      * <p> This constructor is provided to ease migration to {@code 
  581.      * StringBuilder}. Obtaining a string from a string builder via the {@code 
  582.      * toString} method is likely to run faster and is generally preferred. 
  583.      * 
  584.      * @param   builder 
  585.      *          A {@code StringBuilder} 
  586.      * 
  587.      * @since  1.5 
  588.      */  
  589.     public String(StringBuilder builder) {  
  590.         this.value = Arrays.copyOf(builder.getValue(), builder.length());  
  591.     }  
  592.   
  593.     /* 
  594.     * Package private constructor which shares value array for speed. 
  595.     * this constructor is always expected to be called with share==true. 
  596.     * a separate constructor is needed because we already have a public 
  597.     * String(char[]) constructor that makes a copy of the given char[]. 
  598.     */  
  599.     String(char[] value, boolean share) {  
  600.         // assert share : "unshared not supported";  
  601.         this.value = value;  
  602.     }  
  603.   
  604.     /** 
  605.      * Package private constructor 
  606.      * 
  607.      * @deprecated Use {@link #String(char[],int,int)} instead. 
  608.      */  
  609.     @Deprecated  
  610.     String(int offset, int count, char[] value) {  
  611.         this(value, offset, count);  
  612.     }  
  613.   
  614.     /** 
  615.      * Returns the length of this string. 
  616.      * The length is equal to the number of <a href="Character.html#unicode">Unicode 
  617.      * code units</a> in the string. 
  618.      * 
  619.      * @return  the length of the sequence of characters represented by this 
  620.      *          object. 
  621.      */  
  622.     public int length() {  
  623.         return value.length;  
  624.     }  
  625.   
  626.     /** 
  627.      * Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>. 
  628.      * 
  629.      * @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise 
  630.      * <tt>false</tt> 
  631.      * 
  632.      * @since 1.6 
  633.      */  
  634.     public boolean isEmpty() {  
  635.         return value.length == 0;  
  636.     }  
  637.   
  638.     /** 
  639.      * Returns the <code>char</code> value at the 
  640.      * specified index. An index ranges from <code>0</code> to 
  641.      * <code>length() - 1</code>. The first <code>char</code> value of the sequence 
  642.      * is at index <code>0</code>, the next at index <code>1</code>, 
  643.      * and so on, as for array indexing. 
  644.      * 
  645.      * <p>If the <code>char</code> value specified by the index is a 
  646.      * <a href="Character.html#unicode">surrogate</a>, the surrogate 
  647.      * value is returned. 
  648.      * 
  649.      * @param      index   the index of the <code>char</code> value. 
  650.      * @return     the <code>char</code> value at the specified index of this string. 
  651.      *             The first <code>char</code> value is at index <code>0</code>. 
  652.      * @exception  IndexOutOfBoundsException  if the <code>index</code> 
  653.      *             argument is negative or not less than the length of this 
  654.      *             string. 
  655.      */  
  656.     public char charAt(int index) {  
  657.         if ((index < 0) || (index >= value.length)) {  
  658.             throw new StringIndexOutOfBoundsException(index);  
  659.         }  
  660.         return value[index];  
  661.     }  
  662.   
  663.     /** 
  664.      * Returns the character (Unicode code point) at the specified 
  665.      * index. The index refers to <code>char</code> values 
  666.      * (Unicode code units) and ranges from <code>0</code> to 
  667.      * {@link #length()}<code> - 1</code>. 
  668.      * 
  669.      * <p> If the <code>char</code> value specified at the given index 
  670.      * is in the high-surrogate range, the following index is less 
  671.      * than the length of this <code>String</code>, and the 
  672.      * <code>char</code> value at the following index is in the 
  673.      * low-surrogate range, then the supplementary code point 
  674.      * corresponding to this surrogate pair is returned. Otherwise, 
  675.      * the <code>char</code> value at the given index is returned. 
  676.      * 
  677.      * @param      index the index to the <code>char</code> values 
  678.      * @return     the code point value of the character at the 
  679.      *             <code>index</code> 
  680.      * @exception  IndexOutOfBoundsException  if the <code>index</code> 
  681.      *             argument is negative or not less than the length of this 
  682.      *             string. 
  683.      * @since      1.5 
  684.      */  
  685.     public int codePointAt(int index) {  
  686.         if ((index < 0) || (index >= value.length)) {  
  687.             throw new StringIndexOutOfBoundsException(index);  
  688.         }  
  689.         return Character.codePointAtImpl(value, index, value.length);  
  690.     }  
  691.   
  692.     /** 
  693.      * Returns the character (Unicode code point) before the specified 
  694.      * index. The index refers to <code>char</code> values 
  695.      * (Unicode code units) and ranges from <code>1</code> to {@link 
  696.      * CharSequence#length() length}. 
  697.      * 
  698.      * <p> If the <code>char</code> value at <code>(index - 1)</code> 
  699.      * is in the low-surrogate range, <code>(index - 2)</code> is not 
  700.      * negative, and the <code>char</code> value at <code>(index - 
  701.      * 2)</code> is in the high-surrogate range, then the 
  702.      * supplementary code point value of the surrogate pair is 
  703.      * returned. If the <code>char</code> value at <code>index - 
  704.      * 1</code> is an unpaired low-surrogate or a high-surrogate, the 
  705.      * surrogate value is returned. 
  706.      * 
  707.      * @param     index the index following the code point that should be returned 
  708.      * @return    the Unicode code point value before the given index. 
  709.      * @exception IndexOutOfBoundsException if the <code>index</code> 
  710.      *            argument is less than 1 or greater than the length 
  711.      *            of this string. 
  712.      * @since     1.5 
  713.      */  
  714.     public int codePointBefore(int index) {  
  715.         int i = index - 1;  
  716.         if ((i < 0) || (i >= value.length)) {  
  717.             throw new StringIndexOutOfBoundsException(index);  
  718.         }  
  719.         return Character.codePointBeforeImpl(value, index, 0);  
  720.     }  
  721.   
  722.     /** 
  723.      * Returns the number of Unicode code points in the specified text 
  724.      * range of this <code>String</code>. The text range begins at the 
  725.      * specified <code>beginIndex</code> and extends to the 
  726.      * <code>char</code> at index <code>endIndex - 1</code>. Thus the 
  727.      * length (in <code>char</code>s) of the text range is 
  728.      * <code>endIndex-beginIndex</code>. Unpaired surrogates within 
  729.      * the text range count as one code point each. 
  730.      * 
  731.      * @param beginIndex the index to the first <code>char</code> of 
  732.      * the text range. 
  733.      * @param endIndex the index after the last <code>char</code> of 
  734.      * the text range. 
  735.      * @return the number of Unicode code points in the specified text 
  736.      * range 
  737.      * @exception IndexOutOfBoundsException if the 
  738.      * <code>beginIndex</code> is negative, or <code>endIndex</code> 
  739.      * is larger than the length of this <code>String</code>, or 
  740.      * <code>beginIndex</code> is larger than <code>endIndex</code>. 
  741.      * @since  1.5 
  742.      */  
  743.     public int codePointCount(int beginIndex, int endIndex) {  
  744.         if (beginIndex < 0 || endIndex > value.length || beginIndex > endIndex) {  
  745.             throw new IndexOutOfBoundsException();  
  746.         }  
  747.         return Character.codePointCountImpl(value, beginIndex, endIndex - beginIndex);  
  748.     }  
  749.   
  750.     /** 
  751.      * Returns the index within this <code>String</code> that is 
  752.      * offset from the given <code>index</code> by 
  753.      * <code>codePointOffset</code> code points. Unpaired surrogates 
  754.      * within the text range given by <code>index</code> and 
  755.      * <code>codePointOffset</code> count as one code point each. 
  756.      * 
  757.      * @param index the index to be offset 
  758.      * @param codePointOffset the offset in code points 
  759.      * @return the index within this <code>String</code> 
  760.      * @exception IndexOutOfBoundsException if <code>index</code> 
  761.      *   is negative or larger then the length of this 
  762.      *   <code>String</code>, or if <code>codePointOffset</code> is positive 
  763.      *   and the substring starting with <code>index</code> has fewer 
  764.      *   than <code>codePointOffset</code> code points, 
  765.      *   or if <code>codePointOffset</code> is negative and the substring 
  766.      *   before <code>index</code> has fewer than the absolute value 
  767.      *   of <code>codePointOffset</code> code points. 
  768.      * @since 1.5 
  769.      */  
  770.     public int offsetByCodePoints(int index, int codePointOffset) {  
  771.         if (index < 0 || index > value.length) {  
  772.             throw new IndexOutOfBoundsException();  
  773.         }  
  774.         return Character.offsetByCodePointsImpl(value, 0, value.length,  
  775.                 index, codePointOffset);  
  776.     }  
  777.   
  778.     /** 
  779.      * Copy characters from this string into dst starting at dstBegin. 
  780.      * This method doesn't perform any range checking. 
  781.      */  
  782.     void getChars(char dst[], int dstBegin) {  
  783.         System.arraycopy(value, 0, dst, dstBegin, value.length);  
  784.     }  
  785.   
  786.     /** 
  787.      * Copies characters from this string into the destination character 
  788.      * array. 
  789.      * <p> 
  790.      * The first character to be copied is at index <code>srcBegin</code>; 
  791.      * the last character to be copied is at index <code>srcEnd-1</code> 
  792.      * (thus the total number of characters to be copied is 
  793.      * <code>srcEnd-srcBegin</code>). The characters are copied into the 
  794.      * subarray of <code>dst</code> starting at index <code>dstBegin</code> 
  795.      * and ending at index: 
  796.      * <p><blockquote><pre> 
  797.      *     dstbegin + (srcEnd-srcBegin) - 1 
  798.      * </pre></blockquote> 
  799.      * 
  800.      * @param      srcBegin   index of the first character in the string 
  801.      *                        to copy. 
  802.      * @param      srcEnd     index after the last character in the string 
  803.      *                        to copy. 
  804.      * @param      dst        the destination array. 
  805.      * @param      dstBegin   the start offset in the destination array. 
  806.      * @exception IndexOutOfBoundsException If any of the following 
  807.      *            is true: 
  808.      *            <ul><li><code>srcBegin</code> is negative. 
  809.      *            <li><code>srcBegin</code> is greater than <code>srcEnd</code> 
  810.      *            <li><code>srcEnd</code> is greater than the length of this 
  811.      *                string 
  812.      *            <li><code>dstBegin</code> is negative 
  813.      *            <li><code>dstBegin+(srcEnd-srcBegin)</code> is larger than 
  814.      *                <code>dst.length</code></ul> 
  815.      */  
  816.     public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {  
  817.         if (srcBegin < 0) {  
  818.             throw new StringIndexOutOfBoundsException(srcBegin);  
  819.         }  
  820.         if (srcEnd > value.length) {  
  821.             throw new StringIndexOutOfBoundsException(srcEnd);  
  822.         }  
  823.         if (srcBegin > srcEnd) {  
  824.             throw new StringIndexOutOfBoundsException(srcEnd - srcBegin);  
  825.         }  
  826.         System.arraycopy(value, srcBegin, dst, dstBegin, srcEnd - srcBegin);  
  827.     }  
  828.   
  829.     /** 
  830.      * Copies characters from this string into the destination byte array. Each 
  831.      * byte receives the 8 low-order bits of the corresponding character. The 
  832.      * eight high-order bits of each character are not copied and do not 
  833.      * participate in the transfer in any way. 
  834.      * 
  835.      * <p> The first character to be copied is at index {@code srcBegin}; the 
  836.      * last character to be copied is at index {@code srcEnd-1}.  The total 
  837.      * number of characters to be copied is {@code srcEnd-srcBegin}. The 
  838.      * characters, converted to bytes, are copied into the subarray of {@code 
  839.      * dst} starting at index {@code dstBegin} and ending at index: 
  840.      * 
  841.      * <blockquote><pre> 
  842.      *     dstbegin + (srcEnd-srcBegin) - 1 
  843.      * </pre></blockquote> 
  844.      * 
  845.      * @deprecated  This method does not properly convert characters into 
  846.      * bytes.  As of JDK 1.1, the preferred way to do this is via the 
  847.      * {@link #getBytes()} method, which uses the platform's default charset. 
  848.      * 
  849.      * @param  srcBegin 
  850.      *         Index of the first character in the string to copy 
  851.      * 
  852.      * @param  srcEnd 
  853.      *         Index after the last character in the string to copy 
  854.      * 
  855.      * @param  dst 
  856.      *         The destination array 
  857.      * 
  858.      * @param  dstBegin 
  859.      *         The start offset in the destination array 
  860.      * 
  861.      * @throws  IndexOutOfBoundsException 
  862.      *          If any of the following is true: 
  863.      *          <ul> 
  864.      *            <li> {@code srcBegin} is negative 
  865.      *            <li> {@code srcBegin} is greater than {@code srcEnd} 
  866.      *            <li> {@code srcEnd} is greater than the length of this String 
  867.      *            <li> {@code dstBegin} is negative 
  868.      *            <li> {@code dstBegin+(srcEnd-srcBegin)} is larger than {@code 
  869.      *                 dst.length} 
  870.      *          </ul> 
  871.      */  
  872.     @Deprecated  
  873.     public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) {  
  874.         if (srcBegin < 0) {  
  875.             throw new StringIndexOutOfBoundsException(srcBegin);  
  876.         }  
  877.         if (srcEnd > value.length) {  
  878.             throw new StringIndexOutOfBoundsException(srcEnd);  
  879.         }  
  880.         if (srcBegin > srcEnd) {  
  881.             throw new StringIndexOutOfBoundsException(srcEnd - srcBegin);  
  882.         }  
  883.         int j = dstBegin;  
  884.         int n = srcEnd;  
  885.         int i = srcBegin;  
  886.         char[] val = value;   /* avoid getfield opcode */  
  887.   
  888.         while (i < n) {  
  889.             dst[j++] = (byte)val[i++];  
  890.         }  
  891.     }  
  892.   
  893.     /** 
  894.      * Encodes this {@code String} into a sequence of bytes using the named 
  895.      * charset, storing the result into a new byte array. 
  896.      * 
  897.      * <p> The behavior of this method when this string cannot be encoded in 
  898.      * the given charset is unspecified.  The {@link 
  899.      * java.nio.charset.CharsetEncoder} class should be used when more control 
  900.      * over the encoding process is required. 
  901.      * 
  902.      * @param  charsetName 
  903.      *         The name of a supported {@linkplain java.nio.charset.Charset 
  904.      *         charset} 
  905.      * 
  906.      * @return  The resultant byte array 
  907.      * 
  908.      * @throws  UnsupportedEncodingException 
  909.      *          If the named charset is not supported 
  910.      * 
  911.      * @since  JDK1.1 
  912.      */  
  913.     public byte[] getBytes(String charsetName)  
  914.             throws UnsupportedEncodingException {  
  915.         if (charsetName == nullthrow new NullPointerException();  
  916.         return StringCoding.encode(charsetName, value, 0, value.length);  
  917.     }  
  918.   
  919.     /** 
  920.      * Encodes this {@code String} into a sequence of bytes using the given 
  921.      * {@linkplain java.nio.charset.Charset charset}, storing the result into a 
  922.      * new byte array. 
  923.      * 
  924.      * <p> This method always replaces malformed-input and unmappable-character 
  925.      * sequences with this charset's default replacement byte array.  The 
  926.      * {@link java.nio.charset.CharsetEncoder} class should be used when more 
  927.      * control over the encoding process is required. 
  928.      * 
  929.      * @param  charset 
  930.      *         The {@linkplain java.nio.charset.Charset} to be used to encode 
  931.      *         the {@code String} 
  932.      * 
  933.      * @return  The resultant byte array 
  934.      * 
  935.      * @since  1.6 
  936.      */  
  937.     public byte[] getBytes(Charset charset) {  
  938.         if (charset == nullthrow new NullPointerException();  
  939.         return StringCoding.encode(charset, value, 0, value.length);  
  940.     }  
  941.   
  942.     /** 
  943.      * Encodes this {@code String} into a sequence of bytes using the 
  944.      * platform's default charset, storing the result into a new byte array. 
  945.      * 
  946.      * <p> The behavior of this method when this string cannot be encoded in 
  947.      * the default charset is unspecified.  The {@link 
  948.      * java.nio.charset.CharsetEncoder} class should be used when more control 
  949.      * over the encoding process is required. 
  950.      * 
  951.      * @return  The resultant byte array 
  952.      * 
  953.      * @since      JDK1.1 
  954.      */  
  955.     public byte[] getBytes() {  
  956.         return StringCoding.encode(value, 0, value.length);  
  957.     }  
  958.   
  959.     /** 
  960.      * Compares this string to the specified object.  The result is {@code 
  961.      * true} if and only if the argument is not {@code null} and is a {@code 
  962.      * String} object that represents the same sequence of characters as this 
  963.      * object. 
  964.      * 
  965.      * @param  anObject 
  966.      *         The object to compare this {@code String} against 
  967.      * 
  968.      * @return  {@code true} if the given object represents a {@code String} 
  969.      *          equivalent to this string, {@code false} otherwise 
  970.      * 
  971.      * @see  #compareTo(String) 
  972.      * @see  #equalsIgnoreCase(String) 
  973.      */  
  974.     public boolean equals(Object anObject) {  
  975.         if (this == anObject) {  
  976.             return true;  
  977.         }  
  978.         if (anObject instanceof String) {  
  979.             String anotherString = (String) anObject;  
  980.             int n = value.length;  
  981.             if (n == anotherString.value.length) {  
  982.                 char v1[] = value;  
  983.                 char v2[] = anotherString.value;  
  984.                 int i = 0;  
  985.                 while (n-- != 0) {  
  986.                     if (v1[i] != v2[i])  
  987.                             return false;  
  988.                     i++;  
  989.                 }  
  990.                 return true;  
  991.             }  
  992.         }  
  993.         return false;  
  994.     }  
  995.   
  996.     /** 
  997.      * Compares this string to the specified {@code StringBuffer}.  The result 
  998.      * is {@code true} if and only if this {@code String} represents the same 
  999.      * sequence of characters as the specified {@code StringBuffer}. 
  1000.      * 
  1001.      * @param  sb 
  1002.      *         The {@code StringBuffer} to compare this {@code String} against 
  1003.      * 
  1004.      * @return  {@code true} if this {@code String} represents the same 
  1005.      *          sequence of characters as the specified {@code StringBuffer}, 
  1006.      *          {@code false} otherwise 
  1007.      * 
  1008.      * @since  1.4 
  1009.      */  
  1010.     public boolean contentEquals(StringBuffer sb) {  
  1011.         synchronized (sb) {  
  1012.             return contentEquals((CharSequence) sb);  
  1013.         }  
  1014.     }  
  1015.   
  1016.     /** 
  1017.      * Compares this string to the specified {@code CharSequence}.  The result 
  1018.      * is {@code true} if and only if this {@code String} represents the same 
  1019.      * sequence of char values as the specified sequence. 
  1020.      * 
  1021.      * @param  cs 
  1022.      *         The sequence to compare this {@code String} against 
  1023.      * 
  1024.      * @return  {@code true} if this {@code String} represents the same 
  1025.      *          sequence of char values as the specified sequence, {@code 
  1026.      *          false} otherwise 
  1027.      * 
  1028.      * @since  1.5 
  1029.      */  
  1030.     public boolean contentEquals(CharSequence cs) {  
  1031.         if (value.length != cs.length())  
  1032.             return false;  
  1033.         // Argument is a StringBuffer, StringBuilder  
  1034.         if (cs instanceof AbstractStringBuilder) {  
  1035.             char v1[] = value;  
  1036.             char v2[] = ((AbstractStringBuilder) cs).getValue();  
  1037.             int i = 0;  
  1038.             int n = value.length;  
  1039.             while (n-- != 0) {  
  1040.                 if (v1[i] != v2[i])  
  1041.                     return false;  
  1042.                 i++;  
  1043.             }  
  1044.             return true;  
  1045.         }  
  1046.         // Argument is a String  
  1047.         if (cs.equals(this))  
  1048.             return true;  
  1049.         // Argument is a generic CharSequence  
  1050.         char v1[] = value;  
  1051.         int i = 0;  
  1052.         int n = value.length;  
  1053.         while (n-- != 0) {  
  1054.             if (v1[i] != cs.charAt(i))  
  1055.                 return false;  
  1056.             i++;  
  1057.         }  
  1058.         return true;  
  1059.     }  
  1060.   
  1061.     /** 
  1062.      * Compares this {@code String} to another {@code String}, ignoring case 
  1063.      * considerations.  Two strings are considered equal ignoring case if they 
  1064.      * are of the same length and corresponding characters in the two strings 
  1065.      * are equal ignoring case. 
  1066.      * 
  1067.      * <p> Two characters {@code c1} and {@code c2} are considered the same 
  1068.      * ignoring case if at least one of the following is true: 
  1069.      * <ul> 
  1070.      *   <li> The two characters are the same (as compared by the 
  1071.      *        {@code ==} operator) 
  1072.      *   <li> Applying the method {@link 
  1073.      *        java.lang.Character#toUpperCase(char)} to each character 
  1074.      *        produces the same result 
  1075.      *   <li> Applying the method {@link 
  1076.      *        java.lang.Character#toLowerCase(char)} to each character 
  1077.      *        produces the same result 
  1078.      * </ul> 
  1079.      * 
  1080.      * @param  anotherString 
  1081.      *         The {@code String} to compare this {@code String} against 
  1082.      * 
  1083.      * @return  {@code true} if the argument is not {@code null} and it 
  1084.      *          represents an equivalent {@code String} ignoring case; {@code 
  1085.      *          false} otherwise 
  1086.      * 
  1087.      * @see  #equals(Object) 
  1088.      */  
  1089.     public boolean equalsIgnoreCase(String anotherString) {  
  1090.         return (this == anotherString) ? true  
  1091.                 : (anotherString != null)  
  1092.                 && (anotherString.value.length == value.length)  
  1093.                 && regionMatches(true0, anotherString, 0, value.length);  
  1094.     }  
  1095.   
  1096.     /** 
  1097.      * Compares two strings lexicographically. 
  1098.      * The comparison is based on the Unicode value of each character in 
  1099.      * the strings. The character sequence represented by this 
  1100.      * <code>String</code> object is compared lexicographically to the 
  1101.      * character sequence represented by the argument string. The result is 
  1102.      * a negative integer if this <code>String</code> object 
  1103.      * lexicographically precedes the argument string. The result is a 
  1104.      * positive integer if this <code>String</code> object lexicographically 
  1105.      * follows the argument string. The result is zero if the strings 
  1106.      * are equal; <code>compareTo</code> returns <code>0</code> exactly when 
  1107.      * the {@link #equals(Object)} method would return <code>true</code>. 
  1108.      * <p> 
  1109.      * This is the definition of lexicographic ordering. If two strings are 
  1110.      * different, then either they have different characters at some index 
  1111.      * that is a valid index for both strings, or their lengths are different, 
  1112.      * or both. If they have different characters at one or more index 
  1113.      * positions, let <i>k</i> be the smallest such index; then the string 
  1114.      * whose character at position <i>k</i> has the smaller value, as 
  1115.      * determined by using the < operator, lexicographically precedes the 
  1116.      * other string. In this case, <code>compareTo</code> returns the 
  1117.      * difference of the two character values at position <code>k</code> in 
  1118.      * the two string -- that is, the value: 
  1119.      * <blockquote><pre> 
  1120.      * this.charAt(k)-anotherString.charAt(k) 
  1121.      * </pre></blockquote> 
  1122.      * If there is no index position at which they differ, then the shorter 
  1123.      * string lexicographically precedes the longer string. In this case, 
  1124.      * <code>compareTo</code> returns the difference of the lengths of the 
  1125.      * strings -- that is, the value: 
  1126.      * <blockquote><pre> 
  1127.      * this.length()-anotherString.length() 
  1128.      * </pre></blockquote> 
  1129.      * 
  1130.      * @param   anotherString   the <code>String</code> to be compared. 
  1131.      * @return  the value <code>0</code> if the argument string is equal to 
  1132.      *          this string; a value less than <code>0</code> if this string 
  1133.      *          is lexicographically less than the string argument; and a 
  1134.      *          value greater than <code>0</code> if this string is 
  1135.      *          lexicographically greater than the string argument. 
  1136.      */  
  1137.     public int compareTo(String anotherString) {  
  1138.         int len1 = value.length;  
  1139.         int len2 = anotherString.value.length;  
  1140.         int lim = Math.min(len1, len2);  
  1141.         char v1[] = value;  
  1142.         char v2[] = anotherString.value;  
  1143.   
  1144.         int k = 0;  
  1145.         while (k < lim) {  
  1146.             char c1 = v1[k];  
  1147.             char c2 = v2[k];  
  1148.             if (c1 != c2) {  
  1149.                 return c1 - c2;  
  1150.             }  
  1151.             k++;  
  1152.         }  
  1153.         return len1 - len2;  
  1154.     }  
  1155.   
  1156.     /** 
  1157.      * A Comparator that orders <code>String</code> objects as by 
  1158.      * <code>compareToIgnoreCase</code>. This comparator is serializable. 
  1159.      * <p> 
  1160.      * Note that this Comparator does <em>not</em> take locale into account, 
  1161.      * and will result in an unsatisfactory ordering for certain locales. 
  1162.      * The java.text package provides <em>Collators</em> to allow 
  1163.      * locale-sensitive ordering. 
  1164.      * 
  1165.      * @see     java.text.Collator#compare(String, String) 
  1166.      * @since   1.2 
  1167.      */  
  1168.     public static final Comparator<String> CASE_INSENSITIVE_ORDER  
  1169.                                          = new CaseInsensitiveComparator();  
  1170.     private static class CaseInsensitiveComparator  
  1171.             implements Comparator<String>, java.io.Serializable {  
  1172.         // use serialVersionUID from JDK 1.2.2 for interoperability  
  1173.         private static final long serialVersionUID = 8575799808933029326L;  
  1174.   
  1175.         public int compare(String s1, String s2) {  
  1176.             int n1 = s1.length();  
  1177.             int n2 = s2.length();  
  1178.             int min = Math.min(n1, n2);  
  1179.             for (int i = 0; i < min; i++) {  
  1180.                 char c1 = s1.charAt(i);  
  1181.                 char c2 = s2.charAt(i);  
  1182.                 if (c1 != c2) {  
  1183.                     c1 = Character.toUpperCase(c1);  
  1184.                     c2 = Character.toUpperCase(c2);  
  1185.                     if (c1 != c2) {  
  1186.                         c1 = Character.toLowerCase(c1);  
  1187.                         c2 = Character.toLowerCase(c2);  
  1188.                         if (c1 != c2) {  
  1189.                             // No overflow because of numeric promotion  
  1190.                             return c1 - c2;  
  1191.                         }  
  1192.                     }  
  1193.                 }  
  1194.             }  
  1195.             return n1 - n2;  
  1196.         }  
  1197.     }  
  1198.   
  1199.     /** 
  1200.      * Compares two strings lexicographically, ignoring case 
  1201.      * differences. This method returns an integer whose sign is that of 
  1202.      * calling <code>compareTo</code> with normalized versions of the strings 
  1203.      * where case differences have been eliminated by calling 
  1204.      * <code>Character.toLowerCase(Character.toUpperCase(character))</code> on 
  1205.      * each character. 
  1206.      * <p> 
  1207.      * Note that this method does <em>not</em> take locale into account, 
  1208.      * and will result in an unsatisfactory ordering for certain locales. 
  1209.      * The java.text package provides <em>collators</em> to allow 
  1210.      * locale-sensitive ordering. 
  1211.      * 
  1212.      * @param   str   the <code>String</code> to be compared. 
  1213.      * @return  a negative integer, zero, or a positive integer as the 
  1214.      *          specified String is greater than, equal to, or less 
  1215.      *          than this String, ignoring case considerations. 
  1216.      * @see     java.text.Collator#compare(String, String) 
  1217.      * @since   1.2 
  1218.      */  
  1219.     public int compareToIgnoreCase(String str) {  
  1220.         return CASE_INSENSITIVE_ORDER.compare(this, str);  
  1221.     }  
  1222.   
  1223.     /** 
  1224.      * Tests if two string regions are equal. 
  1225.      * <p> 
  1226.      * A substring of this <tt>String</tt> object is compared to a substring 
  1227.      * of the argument other. The result is true if these substrings 
  1228.      * represent identical character sequences. The substring of this 
  1229.      * <tt>String</tt> object to be compared begins at index <tt>toffset</tt> 
  1230.      * and has length <tt>len</tt>. The substring of other to be compared 
  1231.      * begins at index <tt>ooffset</tt> and has length <tt>len</tt>. The 
  1232.      * result is <tt>false</tt> if and only if at least one of the following 
  1233.      * is true: 
  1234.      * <ul><li><tt>toffset</tt> is negative. 
  1235.      * <li><tt>ooffset</tt> is negative. 
  1236.      * <li><tt>toffset+len</tt> is greater than the length of this 
  1237.      * <tt>String</tt> object. 
  1238.      * <li><tt>ooffset+len</tt> is greater than the length of the other 
  1239.      * argument. 
  1240.      * <li>There is some nonnegative integer <i>k</i> less than <tt>len</tt> 
  1241.      * such that: 
  1242.      * <tt>this.charAt(toffset+<i>k</i>) != other.charAt(ooffset+<i>k</i>)</tt> 
  1243.      * </ul> 
  1244.      * 
  1245.      * @param   toffset   the starting offset of the subregion in this string. 
  1246.      * @param   other     the string argument. 
  1247.      * @param   ooffset   the starting offset of the subregion in the string 
  1248.      *                    argument. 
  1249.      * @param   len       the number of characters to compare. 
  1250.      * @return  <code>true</code> if the specified subregion of this string 
  1251.      *          exactly matches the specified subregion of the string argument; 
  1252.      *          <code>false</code> otherwise. 
  1253.      */  
  1254.     public boolean regionMatches(int toffset, String other, int ooffset,  
  1255.             int len) {  
  1256.         char ta[] = value;  
  1257.         int to = toffset;  
  1258.         char pa[] = other.value;  
  1259.         int po = ooffset;  
  1260.         // Note: toffset, ooffset, or len might be near -1>>>1.  
  1261.         if ((ooffset < 0) || (toffset < 0)  
  1262.                 || (toffset > (long)value.length - len)  
  1263.                 || (ooffset > (long)other.value.length - len)) {  
  1264.             return false;  
  1265.         }  
  1266.         while (len-- > 0) {  
  1267.             if (ta[to++] != pa[po++]) {  
  1268.                 return false;  
  1269.             }  
  1270.         }  
  1271.         return true;  
  1272.     }  
  1273.   
  1274.     /** 
  1275.      * Tests if two string regions are equal. 
  1276.      * <p> 
  1277.      * A substring of this <tt>String</tt> object is compared to a substring 
  1278.      * of the argument <tt>other</tt>. The result is <tt>true</tt> if these 
  1279.      * substrings represent character sequences that are the same, ignoring 
  1280.      * case if and only if <tt>ignoreCase</tt> is true. The substring of 
  1281.      * this <tt>String</tt> object to be compared begins at index 
  1282.      * <tt>toffset</tt> and has length <tt>len</tt>. The substring of 
  1283.      * <tt>other</tt> to be compared begins at index <tt>ooffset</tt> and 
  1284.      * has length <tt>len</tt>. The result is <tt>false</tt> if and only if 
  1285.      * at least one of the following is true: 
  1286.      * <ul><li><tt>toffset</tt> is negative. 
  1287.      * <li><tt>ooffset</tt> is negative. 
  1288.      * <li><tt>toffset+len</tt> is greater than the length of this 
  1289.      * <tt>String</tt> object. 
  1290.      * <li><tt>ooffset+len</tt> is greater than the length of the other 
  1291.      * argument. 
  1292.      * <li><tt>ignoreCase</tt> is <tt>false</tt> and there is some nonnegative 
  1293.      * integer <i>k</i> less than <tt>len</tt> such that: 
  1294.      * <blockquote><pre> 
  1295.      * this.charAt(toffset+k) != other.charAt(ooffset+k) 
  1296.      * </pre></blockquote> 
  1297.      * <li><tt>ignoreCase</tt> is <tt>true</tt> and there is some nonnegative 
  1298.      * integer <i>k</i> less than <tt>len</tt> such that: 
  1299.      * <blockquote><pre> 
  1300.      * Character.toLowerCase(this.charAt(toffset+k)) != 
  1301.      Character.toLowerCase(other.charAt(ooffset+k)) 
  1302.      * </pre></blockquote> 
  1303.      * and: 
  1304.      * <blockquote><pre> 
  1305.      * Character.toUpperCase(this.charAt(toffset+k)) != 
  1306.      *         Character.toUpperCase(other.charAt(ooffset+k)) 
  1307.      * </pre></blockquote> 
  1308.      * </ul> 
  1309.      * 
  1310.      * @param   ignoreCase   if <code>true</code>, ignore case when comparing 
  1311.      *                       characters. 
  1312.      * @param   toffset      the starting offset of the subregion in this 
  1313.      *                       string. 
  1314.      * @param   other        the string argument. 
  1315.      * @param   ooffset      the starting offset of the subregion in the string 
  1316.      *                       argument. 
  1317.      * @param   len          the number of characters to compare. 
  1318.      * @return  <code>true</code> if the specified subregion of this string 
  1319.      *          matches the specified subregion of the string argument; 
  1320.      *          <code>false</code> otherwise. Whether the matching is exact 
  1321.      *          or case insensitive depends on the <code>ignoreCase</code> 
  1322.      *          argument. 
  1323.      */  
  1324.     public boolean regionMatches(boolean ignoreCase, int toffset,  
  1325.             String other, int ooffset, int len) {  
  1326.         char ta[] = value;  
  1327.         int to = toffset;  
  1328.         char pa[] = other.value;  
  1329.         int po = ooffset;  
  1330.         // Note: toffset, ooffset, or len might be near -1>>>1.  
  1331.         if ((ooffset < 0) || (toffset < 0)  
  1332.                 || (toffset > (long)value.length - len)  
  1333.                 || (ooffset > (long)other.value.length - len)) {  
  1334.             return false;  
  1335.         }  
  1336.         while (len-- > 0) {  
  1337.             char c1 = ta[to++];  
  1338.             char c2 = pa[po++];  
  1339.             if (c1 == c2) {  
  1340.                 continue;  
  1341.             }  
  1342.             if (ignoreCase) {  
  1343.                 // If characters don't match but case may be ignored,  
  1344.                 // try converting both characters to uppercase.  
  1345.                 // If the results match, then the comparison scan should  
  1346.                 // continue.  
  1347.                 char u1 = Character.toUpperCase(c1);  
  1348.                 char u2 = Character.toUpperCase(c2);  
  1349.                 if (u1 == u2) {  
  1350.                     continue;  
  1351.                 }  
  1352.                 // Unfortunately, conversion to uppercase does not work properly  
  1353.                 // for the Georgian alphabet, which has strange rules about case  
  1354.                 // conversion.  So we need to make one last check before  
  1355.                 // exiting.  
  1356.                 if (Character.toLowerCase(u1) == Character.toLowerCase(u2)) {  
  1357.                     continue;  
  1358.                 }  
  1359.             }  
  1360.             return false;  
  1361.         }  
  1362.         return true;  
  1363.     }  
  1364.   
  1365.     /** 
  1366.      * Tests if the substring of this string beginning at the 
  1367.      * specified index starts with the specified prefix. 
  1368.      * 
  1369.      * @param   prefix    the prefix. 
  1370.      * @param   toffset   where to begin looking in this string. 
  1371.      * @return  <code>true</code> if the character sequence represented by the 
  1372.      *          argument is a prefix of the substring of this object starting 
  1373.      *          at index <code>toffset</code>; <code>false</code> otherwise. 
  1374.      *          The result is <code>false</code> if <code>toffset</code> is 
  1375.      *          negative or greater than the length of this 
  1376.      *          <code>String</code> object; otherwise the result is the same 
  1377.      *          as the result of the expression 
  1378.      *          <pre> 
  1379.      *          this.substring(toffset).startsWith(prefix) 
  1380.      *          </pre> 
  1381.      */  
  1382.     public boolean startsWith(String prefix, int toffset) {  
  1383.         char ta[] = value;  
  1384.         int to = toffset;  
  1385.         char pa[] = prefix.value;  
  1386.         int po = 0;  
  1387.         int pc = prefix.value.length;  
  1388.         // Note: toffset might be near -1>>>1.  
  1389.         if ((toffset < 0) || (toffset > value.length - pc)) {  
  1390.             return false;  
  1391.         }  
  1392.         while (--pc >= 0) {  
  1393.             if (ta[to++] != pa[po++]) {  
  1394.                 return false;  
  1395.             }  
  1396.         }  
  1397.         return true;  
  1398.     }  
  1399.   
  1400.     /** 
  1401.      * Tests if this string starts with the specified prefix. 
  1402.      * 
  1403.      * @param   prefix   the prefix. 
  1404.      * @return  <code>true</code> if the character sequence represented by the 
  1405.      *          argument is a prefix of the character sequence represented by 
  1406.      *          this string; <code>false</code> otherwise. 
  1407.      *          Note also that <code>true</code> will be returned if the 
  1408.      *          argument is an empty string or is equal to this 
  1409.      *          <code>String</code> object as determined by the 
  1410.      *          {@link #equals(Object)} method. 
  1411.      * @since   1. 0 
  1412.      */  
  1413.     public boolean startsWith(String prefix) {  
  1414.         return startsWith(prefix, 0);  
  1415.     }  
  1416.   
  1417.     /** 
  1418.      * Tests if this string ends with the specified suffix. 
  1419.      * 
  1420.      * @param   suffix   the suffix. 
  1421.      * @return  <code>true</code> if the character sequence represented by the 
  1422.      *          argument is a suffix of the character sequence represented by 
  1423.      *          this object; <code>false</code> otherwise. Note that the 
  1424.      *          result will be <code>true</code> if the argument is the 
  1425.      *          empty string or is equal to this <code>String</code> object 
  1426.      *          as determined by the {@link #equals(Object)} method. 
  1427.      */  
  1428.     public boolean endsWith(String suffix) {  
  1429.         return startsWith(suffix, value.length - suffix.value.length);  
  1430.     }  
  1431.   
  1432.     /** 
  1433.      * Returns a hash code for this string. The hash code for a 
  1434.      * <code>String</code> object is computed as 
  1435.      * <blockquote><pre> 
  1436.      * s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] 
  1437.      * </pre></blockquote> 
  1438.      * using <code>int</code> arithmetic, where <code>s[i]</code> is the 
  1439.      * <i>i</i>th character of the string, <code>n</code> is the length of 
  1440.      * the string, and <code>^</code> indicates exponentiation. 
  1441.      * (The hash value of the empty string is zero.) 
  1442.      * 
  1443.      * @return  a hash code value for this object. 
  1444.      */  
  1445.     public int hashCode() {  
  1446.         int h = hash;  
  1447.         if (h == 0 && value.length > 0) {  
  1448.             char val[] = value;  
  1449.   
  1450.             for (int i = 0; i < value.length; i++) {  
  1451.                 h = 31 * h + val[i];  
  1452.             }  
  1453.             hash = h;  
  1454.         }  
  1455.         return h;  
  1456.     }  
  1457.   
  1458.     /** 
  1459.      * Returns the index within this string of the first occurrence of 
  1460.      * the specified character. If a character with value 
  1461.      * <code>ch</code> occurs in the character sequence represented by 
  1462.      * this <code>String</code> object, then the index (in Unicode 
  1463.      * code units) of the first such occurrence is returned. For 
  1464.      * values of <code>ch</code> in the range from 0 to 0xFFFF 
  1465.      * (inclusive), this is the smallest value <i>k</i> such that: 
  1466.      * <blockquote><pre> 
  1467.      * this.charAt(<i>k</i>) == ch 
  1468.      * </pre></blockquote> 
  1469.      * is true. For other values of <code>ch</code>, it is the 
  1470.      * smallest value <i>k</i> such that: 
  1471.      * <blockquote><pre> 
  1472.      * this.codePointAt(<i>k</i>) == ch 
  1473.      * </pre></blockquote> 
  1474.      * is true. In either case, if no such character occurs in this 
  1475.      * string, then <code>-1</code> is returned. 
  1476.      * 
  1477.      * @param   ch   a character (Unicode code point). 
  1478.      * @return  the index of the first occurrence of the character in the 
  1479.      *          character sequence represented by this object, or 
  1480.      *          <code>-1</code> if the character does not occur. 
  1481.      */  
  1482.     public int indexOf(int ch) {  
  1483.         return indexOf(ch, 0);  
  1484.     }  
  1485.   
  1486.     /** 
  1487.      * Returns the index within this string of the first occurrence of the 
  1488.      * specified character, starting the search at the specified index. 
  1489.      * <p> 
  1490.      * If a character with value <code>ch</code> occurs in the 
  1491.      * character sequence represented by this <code>String</code> 
  1492.      * object at an index no smaller than <code>fromIndex</code>, then 
  1493.      * the index of the first such occurrence is returned. For values 
  1494.      * of <code>ch</code> in the range from 0 to 0xFFFF (inclusive), 
  1495.      * this is the smallest value <i>k</i> such that: 
  1496.      * <blockquote><pre> 
  1497.      * (this.charAt(<i>k</i>) == ch) && (<i>k</i> >= fromIndex) 
  1498.      * </pre></blockquote> 
  1499.      * is true. For other values of <code>ch</code>, it is the 
  1500.      * smallest value <i>k</i> such that: 
  1501.      * <blockquote><pre> 
  1502.      * (this.codePointAt(<i>k</i>) == ch) && (<i>k</i> >= fromIndex) 
  1503.      * </pre></blockquote> 
  1504.      * is true. In either case, if no such character occurs in this 
  1505.      * string at or after position <code>fromIndex</code>, then 
  1506.      * <code>-1</code> is returned. 
  1507.      * 
  1508.      * <p> 
  1509.      * There is no restriction on the value of <code>fromIndex</code>. If it 
  1510.      * is negative, it has the same effect as if it were zero: this entire 
  1511.      * string may be searched. If it is greater than the length of this 
  1512.      * string, it has the same effect as if it were equal to the length of 
  1513.      * this string: <code>-1</code> is returned. 
  1514.      * 
  1515.      * <p>All indices are specified in <code>char</code> values 
  1516.      * (Unicode code units). 
  1517.      * 
  1518.      * @param   ch          a character (Unicode code point). 
  1519.      * @param   fromIndex   the index to start the search from. 
  1520.      * @return  the index of the first occurrence of the character in the 
  1521.      *          character sequence represented by this object that is greater 
  1522.      *          than or equal to <code>fromIndex</code>, or <code>-1</code> 
  1523.      *          if the character does not occur. 
  1524.      */  
  1525.     public int indexOf(int ch, int fromIndex) {  
  1526.         final int max = value.length;  
  1527.         if (fromIndex < 0) {  
  1528.             fromIndex = 0;  
  1529.         } else if (fromIndex >= max) {  
  1530.             // Note: fromIndex might be near -1>>>1.  
  1531.             return -1;  
  1532.         }  
  1533.   
  1534.         if (ch < Character.MIN_SUPPLEMENTARY_CODE_POINT) {  
  1535.             // handle most cases here (ch is a BMP code point or a  
  1536.             // negative value (invalid code point))  
  1537.             final char[] value = this.value;  
  1538.             for (int i = fromIndex; i < max; i++) {  
  1539.                 if (value[i] == ch) {  
  1540.                     return i;  
  1541.                 }  
  1542.             }  
  1543.             return -1;  
  1544.         } else {  
  1545.             return indexOfSupplementary(ch, fromIndex);  
  1546.         }  
  1547.     }  
  1548.   
  1549.     /** 
  1550.      * Handles (rare) calls of indexOf with a supplementary character. 
  1551.      */  
  1552.     private int indexOfSupplementary(int ch, int fromIndex) {  
  1553.         if (Character.isValidCodePoint(ch)) {  
  1554.             final char[] value = this.value;  
  1555.             final char hi = Character.highSurrogate(ch);  
  1556.             final char lo = Character.lowSurrogate(ch);  
  1557.             final int max = value.length - 1;  
  1558.             for (int i = fromIndex; i < max; i++) {  
  1559.                 if (value[i] == hi && value[i + 1] == lo) {  
  1560.                     return i;  
  1561.                 }  
  1562.             }  
  1563.         }  
  1564.         return -1;  
  1565.     }  
  1566.   
  1567.     /** 
  1568.      * Returns the index within this string of the last occurrence of 
  1569.      * the specified character. For values of <code>ch</code> in the 
  1570.      * range from 0 to 0xFFFF (inclusive), the index (in Unicode code 
  1571.      * units) returned is the largest value <i>k</i> such that: 
  1572.      * <blockquote><pre> 
  1573.      * this.charAt(<i>k</i>) == ch 
  1574.      * </pre></blockquote> 
  1575.      * is true. For other values of <code>ch</code>, it is the 
  1576.      * largest value <i>k</i> such that: 
  1577.      * <blockquote><pre> 
  1578.      * this.codePointAt(<i>k</i>) == ch 
  1579.      * </pre></blockquote> 
  1580.      * is true.  In either case, if no such character occurs in this 
  1581.      * string, then <code>-1</code> is returned.  The 
  1582.      * <code>String</code> is searched backwards starting at the last 
  1583.      * character. 
  1584.      * 
  1585.      * @param   ch   a character (Unicode code point). 
  1586.      * @return  the index of the last occurrence of the character in the 
  1587.      *          character sequence represented by this object, or 
  1588.      *          <code>-1</code> if the character does not occur. 
  1589.      */  
  1590.     public int lastIndexOf(int ch) {  
  1591.         return lastIndexOf(ch, value.length - 1);  
  1592.     }  
  1593.   
  1594.     /** 
  1595.      * Returns the index within this string of the last occurrence of 
  1596.      * the specified character, searching backward starting at the 
  1597.      * specified index. For values of <code>ch</code> in the range 
  1598.      * from 0 to 0xFFFF (inclusive), the index returned is the largest 
  1599.      * value <i>k</i> such that: 
  1600.      * <blockquote><pre> 
  1601.      * (this.charAt(<i>k</i>) == ch) && (<i>k</i> <= fromIndex) 
  1602.      * </pre></blockquote> 
  1603.      * is true. For other values of <code>ch</code>, it is the 
  1604.      * largest value <i>k</i> such that: 
  1605.      * <blockquote><pre> 
  1606.      * (this.codePointAt(<i>k</i>) == ch) && (<i>k</i> <= fromIndex) 
  1607.      * </pre></blockquote> 
  1608.      * is true. In either case, if no such character occurs in this 
  1609.      * string at or before position <code>fromIndex</code>, then 
  1610.      * <code>-1</code> is returned. 
  1611.      * 
  1612.      * <p>All indices are specified in <code>char</code> values 
  1613.      * (Unicode code units). 
  1614.      * 
  1615.      * @param   ch          a character (Unicode code point). 
  1616.      * @param   fromIndex   the index to start the search from. There is no 
  1617.      *          restriction on the value of <code>fromIndex</code>. If it is 
  1618.      *          greater than or equal to the length of this string, it has 
  1619.      *          the same effect as if it were equal to one less than the 
  1620.      *          length of this string: this entire string may be searched. 
  1621.      *          If it is negative, it has the same effect as if it were -1: 
  1622.      *          -1 is returned. 
  1623.      * @return  the index of the last occurrence of the character in the 
  1624.      *          character sequence represented by this object that is less 
  1625.      *          than or equal to <code>fromIndex</code>, or <code>-1</code> 
  1626.      *          if the character does not occur before that point. 
  1627.      */  
  1628.     public int lastIndexOf(int ch, int fromIndex) {