< prev index next >

src/java.base/share/classes/java/lang/String.java

Print this page




  85  * {@code toString}, defined by {@code Object} and
  86  * inherited by all classes in Java. For additional information on
  87  * string concatenation and conversion, see Gosling, Joy, and Steele,
  88  * <i>The Java Language Specification</i>.
  89  *
  90  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  91  * or method in this class will cause a {@link NullPointerException} to be
  92  * thrown.
  93  *
  94  * <p>A {@code String} represents a string in the UTF-16 format
  95  * in which <em>supplementary characters</em> are represented by <em>surrogate
  96  * pairs</em> (see the section <a href="Character.html#unicode">Unicode
  97  * Character Representations</a> in the {@code Character} class for
  98  * more information).
  99  * Index values refer to {@code char} code units, so a supplementary
 100  * character uses two positions in a {@code String}.
 101  * <p>The {@code String} class provides methods for dealing with
 102  * Unicode code points (i.e., characters), in addition to those for
 103  * dealing with Unicode code units (i.e., {@code char} values).
 104  *




 105  * @author  Lee Boynton
 106  * @author  Arthur van Hoff
 107  * @author  Martin Buchholz
 108  * @author  Ulf Zibis
 109  * @see     java.lang.Object#toString()
 110  * @see     java.lang.StringBuffer
 111  * @see     java.lang.StringBuilder
 112  * @see     java.nio.charset.Charset
 113  * @since   1.0
 114  */
 115 
 116 public final class String
 117     implements java.io.Serializable, Comparable<String>, CharSequence {
 118     /** The value is used for character storage. */
 119     private final char value[];
 120 
 121     /** Cache the hash code for the string */
 122     private int hash; // Default to 0
 123 
 124     /** use serialVersionUID from JDK 1.0.2 for interoperability */


 954      *
 955      * <p> The behavior of this method when this string cannot be encoded in
 956      * the default charset is unspecified.  The {@link
 957      * java.nio.charset.CharsetEncoder} class should be used when more control
 958      * over the encoding process is required.
 959      *
 960      * @return  The resultant byte array
 961      *
 962      * @since      1.1
 963      */
 964     public byte[] getBytes() {
 965         return StringCoding.encode(value, 0, value.length);
 966     }
 967 
 968     /**
 969      * Compares this string to the specified object.  The result is {@code
 970      * true} if and only if the argument is not {@code null} and is a {@code
 971      * String} object that represents the same sequence of characters as this
 972      * object.
 973      *



 974      * @param  anObject
 975      *         The object to compare this {@code String} against
 976      *
 977      * @return  {@code true} if the given object represents a {@code String}
 978      *          equivalent to this string, {@code false} otherwise
 979      *
 980      * @see  #compareTo(String)
 981      * @see  #equalsIgnoreCase(String)

 982      */
 983     @HotSpotIntrinsicCandidate
 984     public boolean equals(Object anObject) {
 985         if (this == anObject) {
 986             return true;
 987         }
 988         if (anObject instanceof String) {
 989             char[] v1 = value;
 990             char[] v2 = ((String)anObject).value;
 991             int n = v1.length;
 992             if (n == v2.length) {
 993                 int i = 0;
 994                 while (n-- != 0) {
 995                     if (v1[i] != v2[i])
 996                         return false;
 997                     i++;
 998                 }
 999                 return true;
1000             }
1001         }
1002         return false;
1003     }
1004 
1005     /**
1006      * Compares this string to the specified {@code StringBuffer}.  The result
1007      * is {@code true} if and only if this {@code String} represents the same
1008      * sequence of characters as the specified {@code StringBuffer}. This method
1009      * synchronizes on the {@code StringBuffer}.
1010      *



1011      * @param  sb
1012      *         The {@code StringBuffer} to compare this {@code String} against
1013      *
1014      * @return  {@code true} if this {@code String} represents the same
1015      *          sequence of characters as the specified {@code StringBuffer},
1016      *          {@code false} otherwise

1017      *
1018      * @since  1.4
1019      */
1020     public boolean contentEquals(StringBuffer sb) {
1021         return contentEquals((CharSequence)sb);
1022     }
1023 
1024     private boolean nonSyncContentEquals(AbstractStringBuilder sb) {
1025         char[] v1 = value;
1026         char[] v2 = sb.getValue();
1027         int n = v1.length;
1028         if (n != sb.length()) {
1029             return false;
1030         }
1031         for (int i = 0; i < n; i++) {
1032             if (v1[i] != v2[i]) {
1033                 return false;
1034             }
1035         }
1036         return true;
1037     }
1038 
1039     /**
1040      * Compares this string to the specified {@code CharSequence}.  The
1041      * result is {@code true} if and only if this {@code String} represents the
1042      * same sequence of char values as the specified sequence. Note that if the
1043      * {@code CharSequence} is a {@code StringBuffer} then the method
1044      * synchronizes on it.
1045      *



1046      * @param  cs
1047      *         The sequence to compare this {@code String} against
1048      *
1049      * @return  {@code true} if this {@code String} represents the same
1050      *          sequence of char values as the specified sequence, {@code
1051      *          false} otherwise

1052      *
1053      * @since  1.5
1054      */
1055     public boolean contentEquals(CharSequence cs) {
1056         // Argument is a StringBuffer, StringBuilder
1057         if (cs instanceof AbstractStringBuilder) {
1058             if (cs instanceof StringBuffer) {
1059                 synchronized(cs) {
1060                    return nonSyncContentEquals((AbstractStringBuilder)cs);
1061                 }
1062             } else {
1063                 return nonSyncContentEquals((AbstractStringBuilder)cs);
1064             }
1065         }
1066         // Argument is a String
1067         if (cs instanceof String) {
1068             return equals(cs);
1069         }
1070         // Argument is a generic CharSequence
1071         char[] v1 = value;


1075         }
1076         for (int i = 0; i < n; i++) {
1077             if (v1[i] != cs.charAt(i)) {
1078                 return false;
1079             }
1080         }
1081         return true;
1082     }
1083 
1084     /**
1085      * Compares this {@code String} to another {@code String}, ignoring case
1086      * considerations.  Two strings are considered equal ignoring case if they
1087      * are of the same length and corresponding characters in the two strings
1088      * are equal ignoring case.
1089      *
1090      * <p> Two characters {@code c1} and {@code c2} are considered the same
1091      * ignoring case if at least one of the following is true:
1092      * <ul>
1093      *   <li> The two characters are the same (as compared by the
1094      *        {@code ==} operator)
1095      *   <li> Applying the method {@link
1096      *        java.lang.Character#toUpperCase(char)} to each character
1097      *        produces the same result
1098      *   <li> Applying the method {@link
1099      *        java.lang.Character#toLowerCase(char)} to each character
1100      *        produces the same result
1101      * </ul>
1102      *




1103      * @param  anotherString
1104      *         The {@code String} to compare this {@code String} against
1105      *
1106      * @return  {@code true} if the argument is not {@code null} and it
1107      *          represents an equivalent {@code String} ignoring case; {@code
1108      *          false} otherwise
1109      *

1110      * @see  #equals(Object)
1111      */
1112     public boolean equalsIgnoreCase(String anotherString) {
1113         return (this == anotherString) ? true
1114                 : (anotherString != null)
1115                 && (anotherString.value.length == value.length)
1116                 && regionMatches(true, 0, anotherString, 0, value.length);
1117     }
1118 
1119     /**
1120      * Compares two strings lexicographically.
1121      * The comparison is based on the Unicode value of each character in
1122      * the strings. The character sequence represented by this
1123      * {@code String} object is compared lexicographically to the
1124      * character sequence represented by the argument string. The result is
1125      * a negative integer if this {@code String} object
1126      * lexicographically precedes the argument string. The result is a
1127      * positive integer if this {@code String} object lexicographically
1128      * follows the argument string. The result is zero if the strings
1129      * are equal; {@code compareTo} returns {@code 0} exactly when


1133      * different, then either they have different characters at some index
1134      * that is a valid index for both strings, or their lengths are different,
1135      * or both. If they have different characters at one or more index
1136      * positions, let <i>k</i> be the smallest such index; then the string
1137      * whose character at position <i>k</i> has the smaller value, as
1138      * determined by using the {@code <} operator, lexicographically precedes the
1139      * other string. In this case, {@code compareTo} returns the
1140      * difference of the two character values at position {@code k} in
1141      * the two string -- that is, the value:
1142      * <blockquote><pre>
1143      * this.charAt(k)-anotherString.charAt(k)
1144      * </pre></blockquote>
1145      * If there is no index position at which they differ, then the shorter
1146      * string lexicographically precedes the longer string. In this case,
1147      * {@code compareTo} returns the difference of the lengths of the
1148      * strings -- that is, the value:
1149      * <blockquote><pre>
1150      * this.length()-anotherString.length()
1151      * </pre></blockquote>
1152      *



1153      * @param   anotherString   the {@code String} to be compared.
1154      * @return  the value {@code 0} if the argument string is equal to
1155      *          this string; a value less than {@code 0} if this string
1156      *          is lexicographically less than the string argument; and a
1157      *          value greater than {@code 0} if this string is
1158      *          lexicographically greater than the string argument.

1159      */
1160     @HotSpotIntrinsicCandidate
1161     public int compareTo(String anotherString) {
1162         char[] v1 = value;
1163         char[] v2 = anotherString.value;
1164         int len1 = v1.length;
1165         int len2 = v2.length;
1166         int lim = Math.min(len1, len2);
1167 
1168         for (int k = 0; k < lim; k++) {
1169             char c1 = v1[k];
1170             char c2 = v2[k];
1171             if (c1 != c2) {
1172                 return c1 - c2;
1173             }
1174         }
1175         return len1 - len2;
1176     }
1177 
1178     /**
1179      * A Comparator that orders {@code String} objects as by
1180      * {@code compareToIgnoreCase}. This comparator is serializable.
1181      * <p>
1182      * Note that this Comparator does <em>not</em> take locale into account,
1183      * and will result in an unsatisfactory ordering for certain locales.
1184      * The java.text package provides <em>Collators</em> to allow
1185      * locale-sensitive ordering.
1186      *
1187      * @see     java.text.Collator#compare(String, String)
1188      * @since   1.2
1189      */
1190     public static final Comparator<String> CASE_INSENSITIVE_ORDER
1191                                          = new CaseInsensitiveComparator();
1192     private static class CaseInsensitiveComparator
1193             implements Comparator<String>, java.io.Serializable {
1194         // use serialVersionUID from JDK 1.2.2 for interoperability
1195         private static final long serialVersionUID = 8575799808933029326L;
1196 
1197         public int compare(String s1, String s2) {
1198             int n1 = s1.length();
1199             int n2 = s2.length();
1200             int min = Math.min(n1, n2);
1201             for (int i = 0; i < min; i++) {
1202                 char c1 = s1.charAt(i);
1203                 char c2 = s2.charAt(i);
1204                 if (c1 != c2) {
1205                     c1 = Character.toUpperCase(c1);
1206                     c2 = Character.toUpperCase(c2);
1207                     if (c1 != c2) {


1214                     }
1215                 }
1216             }
1217             return n1 - n2;
1218         }
1219 
1220         /** Replaces the de-serialized object. */
1221         private Object readResolve() { return CASE_INSENSITIVE_ORDER; }
1222     }
1223 
1224     /**
1225      * Compares two strings lexicographically, ignoring case
1226      * differences. This method returns an integer whose sign is that of
1227      * calling {@code compareTo} with normalized versions of the strings
1228      * where case differences have been eliminated by calling
1229      * {@code Character.toLowerCase(Character.toUpperCase(character))} on
1230      * each character.
1231      * <p>
1232      * Note that this method does <em>not</em> take locale into account,
1233      * and will result in an unsatisfactory ordering for certain locales.
1234      * The java.text package provides <em>collators</em> to allow
1235      * locale-sensitive ordering.
1236      *
1237      * @param   str   the {@code String} to be compared.
1238      * @return  a negative integer, zero, or a positive integer as the
1239      *          specified String is greater than, equal to, or less
1240      *          than this String, ignoring case considerations.
1241      * @see     java.text.Collator#compare(String, String)
1242      * @since   1.2
1243      */
1244     public int compareToIgnoreCase(String str) {
1245         return CASE_INSENSITIVE_ORDER.compare(this, str);
1246     }
1247 
1248     /**
1249      * Tests if two string regions are equal.
1250      * <p>
1251      * A substring of this {@code String} object is compared to a substring
1252      * of the argument other. The result is true if these substrings
1253      * represent identical character sequences. The substring of this
1254      * {@code String} object to be compared begins at index {@code toffset}
1255      * and has length {@code len}. The substring of other to be compared
1256      * begins at index {@code ooffset} and has length {@code len}. The
1257      * result is {@code false} if and only if at least one of the following
1258      * is true:
1259      * <ul><li>{@code toffset} is negative.
1260      * <li>{@code ooffset} is negative.
1261      * <li>{@code toffset+len} is greater than the length of this
1262      * {@code String} object.
1263      * <li>{@code ooffset+len} is greater than the length of the other
1264      * argument.
1265      * <li>There is some nonnegative integer <i>k</i> less than {@code len}
1266      * such that:
1267      * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
1268      * <i>k</i>{@code )}
1269      * </ul>
1270      *



1271      * @param   toffset   the starting offset of the subregion in this string.
1272      * @param   other     the string argument.
1273      * @param   ooffset   the starting offset of the subregion in the string
1274      *                    argument.
1275      * @param   len       the number of characters to compare.
1276      * @return  {@code true} if the specified subregion of this string
1277      *          exactly matches the specified subregion of the string argument;
1278      *          {@code false} otherwise.

1279      */
1280     public boolean regionMatches(int toffset, String other, int ooffset,
1281             int len) {
1282         char[] ta = value;
1283         int to = toffset;
1284         char[] pa = other.value;
1285         int po = ooffset;
1286         // Note: toffset, ooffset, or len might be near -1>>>1.
1287         if ((ooffset < 0) || (toffset < 0)
1288                 || (toffset > (long)ta.length - len)
1289                 || (ooffset > (long)pa.length - len)) {
1290             return false;
1291         }
1292         while (len-- > 0) {
1293             if (ta[to++] != pa[po++]) {
1294                 return false;
1295             }
1296         }
1297         return true;
1298     }


1306      * case if and only if {@code ignoreCase} is true. The substring of
1307      * this {@code String} object to be compared begins at index
1308      * {@code toffset} and has length {@code len}. The substring of
1309      * {@code other} to be compared begins at index {@code ooffset} and
1310      * has length {@code len}. The result is {@code false} if and only if
1311      * at least one of the following is true:
1312      * <ul><li>{@code toffset} is negative.
1313      * <li>{@code ooffset} is negative.
1314      * <li>{@code toffset+len} is greater than the length of this
1315      * {@code String} object.
1316      * <li>{@code ooffset+len} is greater than the length of the other
1317      * argument.
1318      * <li>{@code ignoreCase} is {@code false} and there is some nonnegative
1319      * integer <i>k</i> less than {@code len} such that:
1320      * <blockquote><pre>
1321      * this.charAt(toffset+k) != other.charAt(ooffset+k)
1322      * </pre></blockquote>
1323      * <li>{@code ignoreCase} is {@code true} and there is some nonnegative
1324      * integer <i>k</i> less than {@code len} such that:
1325      * <blockquote><pre>
1326      * Character.toLowerCase(this.charAt(toffset+k)) !=
1327      Character.toLowerCase(other.charAt(ooffset+k))
1328      * </pre></blockquote>
1329      * and:
1330      * <blockquote><pre>
1331      * Character.toUpperCase(this.charAt(toffset+k)) !=
1332      *         Character.toUpperCase(other.charAt(ooffset+k))
1333      * </pre></blockquote>
1334      * </ul>
1335      *





1336      * @param   ignoreCase   if {@code true}, ignore case when comparing
1337      *                       characters.
1338      * @param   toffset      the starting offset of the subregion in this
1339      *                       string.
1340      * @param   other        the string argument.
1341      * @param   ooffset      the starting offset of the subregion in the string
1342      *                       argument.
1343      * @param   len          the number of characters to compare.
1344      * @return  {@code true} if the specified subregion of this string
1345      *          matches the specified subregion of the string argument;
1346      *          {@code false} otherwise. Whether the matching is exact
1347      *          or case insensitive depends on the {@code ignoreCase}
1348      *          argument.

1349      */
1350     public boolean regionMatches(boolean ignoreCase, int toffset,
1351             String other, int ooffset, int len) {
1352         char[] ta = value;
1353         int to = toffset;
1354         char[] pa = other.value;
1355         int po = ooffset;
1356         // Note: toffset, ooffset, or len might be near -1>>>1.
1357         if ((ooffset < 0) || (toffset < 0)
1358                 || (toffset > (long)ta.length - len)
1359                 || (ooffset > (long)pa.length - len)) {
1360             return false;
1361         }
1362         while (len-- > 0) {
1363             char c1 = ta[to++];
1364             char c2 = pa[po++];
1365             if (c1 == c2) {
1366                 continue;
1367             }
1368             if (ignoreCase) {




  85  * {@code toString}, defined by {@code Object} and
  86  * inherited by all classes in Java. For additional information on
  87  * string concatenation and conversion, see Gosling, Joy, and Steele,
  88  * <i>The Java Language Specification</i>.
  89  *
  90  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  91  * or method in this class will cause a {@link NullPointerException} to be
  92  * thrown.
  93  *
  94  * <p>A {@code String} represents a string in the UTF-16 format
  95  * in which <em>supplementary characters</em> are represented by <em>surrogate
  96  * pairs</em> (see the section <a href="Character.html#unicode">Unicode
  97  * Character Representations</a> in the {@code Character} class for
  98  * more information).
  99  * Index values refer to {@code char} code units, so a supplementary
 100  * character uses two positions in a {@code String}.
 101  * <p>The {@code String} class provides methods for dealing with
 102  * Unicode code points (i.e., characters), in addition to those for
 103  * dealing with Unicode code units (i.e., {@code char} values).
 104  *
 105  * <p>Unless otherwise noted, methods for comparing Strings do not take locale
 106  * into account.  The {@code java.text.Collator} class provides methods for
 107  * finer-grain, locale-sensitive String comparison.
 108  * 
 109  * @author  Lee Boynton
 110  * @author  Arthur van Hoff
 111  * @author  Martin Buchholz
 112  * @author  Ulf Zibis
 113  * @see     java.lang.Object#toString()
 114  * @see     java.lang.StringBuffer
 115  * @see     java.lang.StringBuilder
 116  * @see     java.nio.charset.Charset
 117  * @since   1.0
 118  */
 119 
 120 public final class String
 121     implements java.io.Serializable, Comparable<String>, CharSequence {
 122     /** The value is used for character storage. */
 123     private final char value[];
 124 
 125     /** Cache the hash code for the string */
 126     private int hash; // Default to 0
 127 
 128     /** use serialVersionUID from JDK 1.0.2 for interoperability */


 958      *
 959      * <p> The behavior of this method when this string cannot be encoded in
 960      * the default charset is unspecified.  The {@link
 961      * java.nio.charset.CharsetEncoder} class should be used when more control
 962      * over the encoding process is required.
 963      *
 964      * @return  The resultant byte array
 965      *
 966      * @since      1.1
 967      */
 968     public byte[] getBytes() {
 969         return StringCoding.encode(value, 0, value.length);
 970     }
 971 
 972     /**
 973      * Compares this string to the specified object.  The result is {@code
 974      * true} if and only if the argument is not {@code null} and is a {@code
 975      * String} object that represents the same sequence of characters as this
 976      * object.
 977      *
 978      * <p>For finer-grained String comparison, refer to
 979      * {@code java.text.Collator}.
 980      * 
 981      * @param  anObject
 982      *         The object to compare this {@code String} against
 983      *
 984      * @return  {@code true} if the given object represents a {@code String}
 985      *          equivalent to this string, {@code false} otherwise
 986      *
 987      * @see  #compareTo(String)
 988      * @see  #equalsIgnoreCase(String)
 989      * @see  java.text.Collator
 990      */
 991     @HotSpotIntrinsicCandidate
 992     public boolean equals(Object anObject) {
 993         if (this == anObject) {
 994             return true;
 995         }
 996         if (anObject instanceof String) {
 997             char[] v1 = value;
 998             char[] v2 = ((String)anObject).value;
 999             int n = v1.length;
1000             if (n == v2.length) {
1001                 int i = 0;
1002                 while (n-- != 0) {
1003                     if (v1[i] != v2[i])
1004                         return false;
1005                     i++;
1006                 }
1007                 return true;
1008             }
1009         }
1010         return false;
1011     }
1012 
1013     /**
1014      * Compares this string to the specified {@code StringBuffer}.  The result
1015      * is {@code true} if and only if this {@code String} represents the same
1016      * sequence of characters as the specified {@code StringBuffer}. This method
1017      * synchronizes on the {@code StringBuffer}.
1018      *
1019      * <p>For finer-grained String comparison, refer to
1020      * {@code java.text.Collator}.
1021      *
1022      * @param  sb
1023      *         The {@code StringBuffer} to compare this {@code String} against
1024      *
1025      * @return  {@code true} if this {@code String} represents the same
1026      *          sequence of characters as the specified {@code StringBuffer},
1027      *          {@code false} otherwise
1028      * @see  java.text.Collator
1029      *
1030      * @since  1.4
1031      */
1032     public boolean contentEquals(StringBuffer sb) {
1033         return contentEquals((CharSequence)sb);
1034     }
1035 
1036     private boolean nonSyncContentEquals(AbstractStringBuilder sb) {
1037         char[] v1 = value;
1038         char[] v2 = sb.getValue();
1039         int n = v1.length;
1040         if (n != sb.length()) {
1041             return false;
1042         }
1043         for (int i = 0; i < n; i++) {
1044             if (v1[i] != v2[i]) {
1045                 return false;
1046             }
1047         }
1048         return true;
1049     }
1050 
1051     /**
1052      * Compares this string to the specified {@code CharSequence}.  The
1053      * result is {@code true} if and only if this {@code String} represents the
1054      * same sequence of char values as the specified sequence. Note that if the
1055      * {@code CharSequence} is a {@code StringBuffer} then the method
1056      * synchronizes on it.
1057      *
1058      * <p>For finer-grained String comparison, refer to
1059      * {@code java.text.Collator}.
1060      *
1061      * @param  cs
1062      *         The sequence to compare this {@code String} against
1063      *
1064      * @return  {@code true} if this {@code String} represents the same
1065      *          sequence of char values as the specified sequence, {@code
1066      *          false} otherwise
1067      * @see  java.text.Collator
1068      *
1069      * @since  1.5
1070      */
1071     public boolean contentEquals(CharSequence cs) {
1072         // Argument is a StringBuffer, StringBuilder
1073         if (cs instanceof AbstractStringBuilder) {
1074             if (cs instanceof StringBuffer) {
1075                 synchronized(cs) {
1076                    return nonSyncContentEquals((AbstractStringBuilder)cs);
1077                 }
1078             } else {
1079                 return nonSyncContentEquals((AbstractStringBuilder)cs);
1080             }
1081         }
1082         // Argument is a String
1083         if (cs instanceof String) {
1084             return equals(cs);
1085         }
1086         // Argument is a generic CharSequence
1087         char[] v1 = value;


1091         }
1092         for (int i = 0; i < n; i++) {
1093             if (v1[i] != cs.charAt(i)) {
1094                 return false;
1095             }
1096         }
1097         return true;
1098     }
1099 
1100     /**
1101      * Compares this {@code String} to another {@code String}, ignoring case
1102      * considerations.  Two strings are considered equal ignoring case if they
1103      * are of the same length and corresponding characters in the two strings
1104      * are equal ignoring case.
1105      *
1106      * <p> Two characters {@code c1} and {@code c2} are considered the same
1107      * ignoring case if at least one of the following is true:
1108      * <ul>
1109      *   <li> The two characters are the same (as compared by the
1110      *        {@code ==} operator)
1111      *   <li> Calling {@code Character.toLowerCase(Character.toUpperCase(character))}
1112      *        on each character produces the same result




1113      * </ul>
1114      * 
1115      * <p>Note that this method does <em>not</em> take locale into account, and
1116      * will result in unsatisfactory results for certain locales.  The
1117      * {@code java.text.Collator} class provides locale-sensitive comparison.
1118      * 
1119      * @param  anotherString
1120      *         The {@code String} to compare this {@code String} against
1121      *
1122      * @return  {@code true} if the argument is not {@code null} and it
1123      *          represents an equivalent {@code String} ignoring case; {@code
1124      *          false} otherwise
1125      *
1126      * @see  java.text.Collator
1127      * @see  #equals(Object)
1128      */
1129     public boolean equalsIgnoreCase(String anotherString) {
1130         return (this == anotherString) ? true
1131                 : (anotherString != null)
1132                 && (anotherString.value.length == value.length)
1133                 && regionMatches(true, 0, anotherString, 0, value.length);
1134     }
1135 
1136     /**
1137      * Compares two strings lexicographically.
1138      * The comparison is based on the Unicode value of each character in
1139      * the strings. The character sequence represented by this
1140      * {@code String} object is compared lexicographically to the
1141      * character sequence represented by the argument string. The result is
1142      * a negative integer if this {@code String} object
1143      * lexicographically precedes the argument string. The result is a
1144      * positive integer if this {@code String} object lexicographically
1145      * follows the argument string. The result is zero if the strings
1146      * are equal; {@code compareTo} returns {@code 0} exactly when


1150      * different, then either they have different characters at some index
1151      * that is a valid index for both strings, or their lengths are different,
1152      * or both. If they have different characters at one or more index
1153      * positions, let <i>k</i> be the smallest such index; then the string
1154      * whose character at position <i>k</i> has the smaller value, as
1155      * determined by using the {@code <} operator, lexicographically precedes the
1156      * other string. In this case, {@code compareTo} returns the
1157      * difference of the two character values at position {@code k} in
1158      * the two string -- that is, the value:
1159      * <blockquote><pre>
1160      * this.charAt(k)-anotherString.charAt(k)
1161      * </pre></blockquote>
1162      * If there is no index position at which they differ, then the shorter
1163      * string lexicographically precedes the longer string. In this case,
1164      * {@code compareTo} returns the difference of the lengths of the
1165      * strings -- that is, the value:
1166      * <blockquote><pre>
1167      * this.length()-anotherString.length()
1168      * </pre></blockquote>
1169      *
1170      * <p>For finer-grained String comparison, refer to
1171      * {@code java.text.Collator}.
1172      * 
1173      * @param   anotherString   the {@code String} to be compared.
1174      * @return  the value {@code 0} if the argument string is equal to
1175      *          this string; a value less than {@code 0} if this string
1176      *          is lexicographically less than the string argument; and a
1177      *          value greater than {@code 0} if this string is
1178      *          lexicographically greater than the string argument.
1179      * @see     java.text.Collator
1180      */
1181     @HotSpotIntrinsicCandidate
1182     public int compareTo(String anotherString) {
1183         char[] v1 = value;
1184         char[] v2 = anotherString.value;
1185         int len1 = v1.length;
1186         int len2 = v2.length;
1187         int lim = Math.min(len1, len2);
1188 
1189         for (int k = 0; k < lim; k++) {
1190             char c1 = v1[k];
1191             char c2 = v2[k];
1192             if (c1 != c2) {
1193                 return c1 - c2;
1194             }
1195         }
1196         return len1 - len2;
1197     }
1198 
1199     /**
1200      * A Comparator that orders {@code String} objects as by
1201      * {@code compareToIgnoreCase}. This comparator is serializable.
1202      * <p>
1203      * Note that this Comparator does <em>not</em> take locale into account,
1204      * and will result in an unsatisfactory ordering for certain locales.
1205      * The {@code java.text.Collator} class provides locale-sensitive comparison.

1206      *
1207      * @see     java.text.Collator
1208      * @since   1.2
1209      */
1210     public static final Comparator<String> CASE_INSENSITIVE_ORDER
1211                                          = new CaseInsensitiveComparator();
1212     private static class CaseInsensitiveComparator
1213             implements Comparator<String>, java.io.Serializable {
1214         // use serialVersionUID from JDK 1.2.2 for interoperability
1215         private static final long serialVersionUID = 8575799808933029326L;
1216 
1217         public int compare(String s1, String s2) {
1218             int n1 = s1.length();
1219             int n2 = s2.length();
1220             int min = Math.min(n1, n2);
1221             for (int i = 0; i < min; i++) {
1222                 char c1 = s1.charAt(i);
1223                 char c2 = s2.charAt(i);
1224                 if (c1 != c2) {
1225                     c1 = Character.toUpperCase(c1);
1226                     c2 = Character.toUpperCase(c2);
1227                     if (c1 != c2) {


1234                     }
1235                 }
1236             }
1237             return n1 - n2;
1238         }
1239 
1240         /** Replaces the de-serialized object. */
1241         private Object readResolve() { return CASE_INSENSITIVE_ORDER; }
1242     }
1243 
1244     /**
1245      * Compares two strings lexicographically, ignoring case
1246      * differences. This method returns an integer whose sign is that of
1247      * calling {@code compareTo} with normalized versions of the strings
1248      * where case differences have been eliminated by calling
1249      * {@code Character.toLowerCase(Character.toUpperCase(character))} on
1250      * each character.
1251      * <p>
1252      * Note that this method does <em>not</em> take locale into account,
1253      * and will result in an unsatisfactory ordering for certain locales.
1254      * The {@code java.text.Collator} class provides locale-sensitive comparison.

1255      *
1256      * @param   str   the {@code String} to be compared.
1257      * @return  a negative integer, zero, or a positive integer as the
1258      *          specified String is greater than, equal to, or less
1259      *          than this String, ignoring case considerations.
1260      * @see     java.text.Collator
1261      * @since   1.2
1262      */
1263     public int compareToIgnoreCase(String str) {
1264         return CASE_INSENSITIVE_ORDER.compare(this, str);
1265     }
1266 
1267     /**
1268      * Tests if two string regions are equal.
1269      * <p>
1270      * A substring of this {@code String} object is compared to a substring
1271      * of the argument other. The result is true if these substrings
1272      * represent identical character sequences. The substring of this
1273      * {@code String} object to be compared begins at index {@code toffset}
1274      * and has length {@code len}. The substring of other to be compared
1275      * begins at index {@code ooffset} and has length {@code len}. The
1276      * result is {@code false} if and only if at least one of the following
1277      * is true:
1278      * <ul><li>{@code toffset} is negative.
1279      * <li>{@code ooffset} is negative.
1280      * <li>{@code toffset+len} is greater than the length of this
1281      * {@code String} object.
1282      * <li>{@code ooffset+len} is greater than the length of the other
1283      * argument.
1284      * <li>There is some nonnegative integer <i>k</i> less than {@code len}
1285      * such that:
1286      * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
1287      * <i>k</i>{@code )}
1288      * </ul>
1289      *
1290      * <p>Note that this method does <em>not</em> take locale into account.  The
1291      * {@code java.text.Collator} class provides locale-sensitive comparison.
1292      * 
1293      * @param   toffset   the starting offset of the subregion in this string.
1294      * @param   other     the string argument.
1295      * @param   ooffset   the starting offset of the subregion in the string
1296      *                    argument.
1297      * @param   len       the number of characters to compare.
1298      * @return  {@code true} if the specified subregion of this string
1299      *          exactly matches the specified subregion of the string argument;
1300      *          {@code false} otherwise.
1301      * @see     java.text.Collator
1302      */
1303     public boolean regionMatches(int toffset, String other, int ooffset,
1304             int len) {
1305         char[] ta = value;
1306         int to = toffset;
1307         char[] pa = other.value;
1308         int po = ooffset;
1309         // Note: toffset, ooffset, or len might be near -1>>>1.
1310         if ((ooffset < 0) || (toffset < 0)
1311                 || (toffset > (long)ta.length - len)
1312                 || (ooffset > (long)pa.length - len)) {
1313             return false;
1314         }
1315         while (len-- > 0) {
1316             if (ta[to++] != pa[po++]) {
1317                 return false;
1318             }
1319         }
1320         return true;
1321     }


1329      * case if and only if {@code ignoreCase} is true. The substring of
1330      * this {@code String} object to be compared begins at index
1331      * {@code toffset} and has length {@code len}. The substring of
1332      * {@code other} to be compared begins at index {@code ooffset} and
1333      * has length {@code len}. The result is {@code false} if and only if
1334      * at least one of the following is true:
1335      * <ul><li>{@code toffset} is negative.
1336      * <li>{@code ooffset} is negative.
1337      * <li>{@code toffset+len} is greater than the length of this
1338      * {@code String} object.
1339      * <li>{@code ooffset+len} is greater than the length of the other
1340      * argument.
1341      * <li>{@code ignoreCase} is {@code false} and there is some nonnegative
1342      * integer <i>k</i> less than {@code len} such that:
1343      * <blockquote><pre>
1344      * this.charAt(toffset+k) != other.charAt(ooffset+k)
1345      * </pre></blockquote>
1346      * <li>{@code ignoreCase} is {@code true} and there is some nonnegative
1347      * integer <i>k</i> less than {@code len} such that:
1348      * <blockquote><pre>
1349      * Character.toLowerCase(Character.toUpperCase(this.charAt(toffset+k))) !=
1350      Character.toLowerCase(Character.toUpperCase(other.charAt(ooffset+k)))





1351      * </pre></blockquote>
1352      * </ul>
1353      * 
1354      * <p>Note that this method does <em>not</em> take locale into account,
1355      * and will result in unsatisfactory results for certain locales when
1356      * {@code ignoreCase} is {@code true}.  The {@code java.text.Collator} class
1357      * provides locale-sensitive comparison.
1358      * 
1359      * @param   ignoreCase   if {@code true}, ignore case when comparing
1360      *                       characters.
1361      * @param   toffset      the starting offset of the subregion in this
1362      *                       string.
1363      * @param   other        the string argument.
1364      * @param   ooffset      the starting offset of the subregion in the string
1365      *                       argument.
1366      * @param   len          the number of characters to compare.
1367      * @return  {@code true} if the specified subregion of this string
1368      *          matches the specified subregion of the string argument;
1369      *          {@code false} otherwise. Whether the matching is exact
1370      *          or case insensitive depends on the {@code ignoreCase}
1371      *          argument.
1372      * @see     java.text.Collator
1373      */
1374     public boolean regionMatches(boolean ignoreCase, int toffset,
1375             String other, int ooffset, int len) {
1376         char[] ta = value;
1377         int to = toffset;
1378         char[] pa = other.value;
1379         int po = ooffset;
1380         // Note: toffset, ooffset, or len might be near -1>>>1.
1381         if ((ooffset < 0) || (toffset < 0)
1382                 || (toffset > (long)ta.length - len)
1383                 || (ooffset > (long)pa.length - len)) {
1384             return false;
1385         }
1386         while (len-- > 0) {
1387             char c1 = ta[to++];
1388             char c2 = pa[po++];
1389             if (c1 == c2) {
1390                 continue;
1391             }
1392             if (ignoreCase) {


< prev index next >