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 }
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
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;
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;
|
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 {@link 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 * {@link 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 */
990 @HotSpotIntrinsicCandidate
991 public boolean equals(Object anObject) {
992 if (this == anObject) {
993 return true;
994 }
995 if (anObject instanceof String) {
996 char[] v1 = value;
997 char[] v2 = ((String)anObject).value;
998 int n = v1.length;
999 if (n == v2.length) {
1000 int i = 0;
1001 while (n-- != 0) {
1002 if (v1[i] != v2[i])
1003 return false;
1004 i++;
1005 }
1006 return true;
1007 }
1008 }
1009 return false;
1010 }
1011
1012 /**
1013 * Compares this string to the specified {@code StringBuffer}. The result
1014 * is {@code true} if and only if this {@code String} represents the same
1015 * sequence of characters as the specified {@code StringBuffer}. This method
1016 * synchronizes on the {@code StringBuffer}.
1017 *
1018 * <p>For finer-grained String comparison, refer to
1019 * {@link java.text.Collator}.
1020 *
1021 * @param sb
1022 * The {@code StringBuffer} to compare this {@code String} against
1023 *
1024 * @return {@code true} if this {@code String} represents the same
1025 * sequence of characters as the specified {@code StringBuffer},
1026 * {@code false} otherwise
1027 *
1028 * @since 1.4
1029 */
1030 public boolean contentEquals(StringBuffer sb) {
1031 return contentEquals((CharSequence)sb);
1032 }
1033
1034 private boolean nonSyncContentEquals(AbstractStringBuilder sb) {
1035 char[] v1 = value;
1036 char[] v2 = sb.getValue();
1037 int n = v1.length;
1038 if (n != sb.length()) {
1039 return false;
1040 }
1041 for (int i = 0; i < n; i++) {
1042 if (v1[i] != v2[i]) {
1043 return false;
1044 }
1045 }
1046 return true;
1047 }
1048
1049 /**
1050 * Compares this string to the specified {@code CharSequence}. The
1051 * result is {@code true} if and only if this {@code String} represents the
1052 * same sequence of char values as the specified sequence. Note that if the
1053 * {@code CharSequence} is a {@code StringBuffer} then the method
1054 * synchronizes on it.
1055 *
1056 * <p>For finer-grained String comparison, refer to
1057 * {@link java.text.Collator}.
1058 *
1059 * @param cs
1060 * The sequence to compare this {@code String} against
1061 *
1062 * @return {@code true} if this {@code String} represents the same
1063 * sequence of char values as the specified sequence, {@code
1064 * false} otherwise
1065 *
1066 * @since 1.5
1067 */
1068 public boolean contentEquals(CharSequence cs) {
1069 // Argument is a StringBuffer, StringBuilder
1070 if (cs instanceof AbstractStringBuilder) {
1071 if (cs instanceof StringBuffer) {
1072 synchronized(cs) {
1073 return nonSyncContentEquals((AbstractStringBuilder)cs);
1074 }
1075 } else {
1076 return nonSyncContentEquals((AbstractStringBuilder)cs);
1077 }
1078 }
1088 }
1089 for (int i = 0; i < n; i++) {
1090 if (v1[i] != cs.charAt(i)) {
1091 return false;
1092 }
1093 }
1094 return true;
1095 }
1096
1097 /**
1098 * Compares this {@code String} to another {@code String}, ignoring case
1099 * considerations. Two strings are considered equal ignoring case if they
1100 * are of the same length and corresponding characters in the two strings
1101 * are equal ignoring case.
1102 *
1103 * <p> Two characters {@code c1} and {@code c2} are considered the same
1104 * ignoring case if at least one of the following is true:
1105 * <ul>
1106 * <li> The two characters are the same (as compared by the
1107 * {@code ==} operator)
1108 * <li> Calling {@code Character.toLowerCase(Character.toUpperCase(char))}
1109 * on each character produces the same result
1110 * </ul>
1111 *
1112 * <p>Note that this method does <em>not</em> take locale into account, and
1113 * will result in unsatisfactory results for certain locales. The
1114 * {@link java.text.Collator} class provides locale-sensitive comparison.
1115 *
1116 * @param anotherString
1117 * The {@code String} to compare this {@code String} against
1118 *
1119 * @return {@code true} if the argument is not {@code null} and it
1120 * represents an equivalent {@code String} ignoring case; {@code
1121 * false} otherwise
1122 *
1123 * @see #equals(Object)
1124 */
1125 public boolean equalsIgnoreCase(String anotherString) {
1126 return (this == anotherString) ? true
1127 : (anotherString != null)
1128 && (anotherString.value.length == value.length)
1129 && regionMatches(true, 0, anotherString, 0, value.length);
1130 }
1131
1132 /**
1133 * Compares two strings lexicographically.
1134 * The comparison is based on the Unicode value of each character in
1135 * the strings. The character sequence represented by this
1146 * different, then either they have different characters at some index
1147 * that is a valid index for both strings, or their lengths are different,
1148 * or both. If they have different characters at one or more index
1149 * positions, let <i>k</i> be the smallest such index; then the string
1150 * whose character at position <i>k</i> has the smaller value, as
1151 * determined by using the {@code <} operator, lexicographically precedes the
1152 * other string. In this case, {@code compareTo} returns the
1153 * difference of the two character values at position {@code k} in
1154 * the two string -- that is, the value:
1155 * <blockquote><pre>
1156 * this.charAt(k)-anotherString.charAt(k)
1157 * </pre></blockquote>
1158 * If there is no index position at which they differ, then the shorter
1159 * string lexicographically precedes the longer string. In this case,
1160 * {@code compareTo} returns the difference of the lengths of the
1161 * strings -- that is, the value:
1162 * <blockquote><pre>
1163 * this.length()-anotherString.length()
1164 * </pre></blockquote>
1165 *
1166 * <p>For finer-grained String comparison, refer to
1167 * {@link java.text.Collator}.
1168 *
1169 * @param anotherString the {@code String} to be compared.
1170 * @return the value {@code 0} if the argument string is equal to
1171 * this string; a value less than {@code 0} if this string
1172 * is lexicographically less than the string argument; and a
1173 * value greater than {@code 0} if this string is
1174 * lexicographically greater than the string argument.
1175 */
1176 @HotSpotIntrinsicCandidate
1177 public int compareTo(String anotherString) {
1178 char[] v1 = value;
1179 char[] v2 = anotherString.value;
1180 int len1 = v1.length;
1181 int len2 = v2.length;
1182 int lim = Math.min(len1, len2);
1183
1184 for (int k = 0; k < lim; k++) {
1185 char c1 = v1[k];
1186 char c2 = v2[k];
1187 if (c1 != c2) {
1188 return c1 - c2;
1189 }
1190 }
1191 return len1 - len2;
1192 }
1193
1194 /**
1195 * A Comparator that orders {@code String} objects as by
1196 * {@code compareToIgnoreCase}. This comparator is serializable.
1197 * <p>
1198 * Note that this Comparator does <em>not</em> take locale into account,
1199 * and will result in an unsatisfactory ordering for certain locales.
1200 * The {@link java.text.Collator} class provides locale-sensitive comparison.
1201 *
1202 * @see java.text.Collator
1203 * @since 1.2
1204 */
1205 public static final Comparator<String> CASE_INSENSITIVE_ORDER
1206 = new CaseInsensitiveComparator();
1207 private static class CaseInsensitiveComparator
1208 implements Comparator<String>, java.io.Serializable {
1209 // use serialVersionUID from JDK 1.2.2 for interoperability
1210 private static final long serialVersionUID = 8575799808933029326L;
1211
1212 public int compare(String s1, String s2) {
1213 int n1 = s1.length();
1214 int n2 = s2.length();
1215 int min = Math.min(n1, n2);
1216 for (int i = 0; i < min; i++) {
1217 char c1 = s1.charAt(i);
1218 char c2 = s2.charAt(i);
1219 if (c1 != c2) {
1220 c1 = Character.toUpperCase(c1);
1221 c2 = Character.toUpperCase(c2);
1222 if (c1 != c2) {
1229 }
1230 }
1231 }
1232 return n1 - n2;
1233 }
1234
1235 /** Replaces the de-serialized object. */
1236 private Object readResolve() { return CASE_INSENSITIVE_ORDER; }
1237 }
1238
1239 /**
1240 * Compares two strings lexicographically, ignoring case
1241 * differences. This method returns an integer whose sign is that of
1242 * calling {@code compareTo} with normalized versions of the strings
1243 * where case differences have been eliminated by calling
1244 * {@code Character.toLowerCase(Character.toUpperCase(character))} on
1245 * each character.
1246 * <p>
1247 * Note that this method does <em>not</em> take locale into account,
1248 * and will result in an unsatisfactory ordering for certain locales.
1249 * The {@link java.text.Collator} class provides locale-sensitive comparison.
1250 *
1251 * @param str the {@code String} to be compared.
1252 * @return a negative integer, zero, or a positive integer as the
1253 * specified String is greater than, equal to, or less
1254 * than this String, ignoring case considerations.
1255 * @see java.text.Collator
1256 * @since 1.2
1257 */
1258 public int compareToIgnoreCase(String str) {
1259 return CASE_INSENSITIVE_ORDER.compare(this, str);
1260 }
1261
1262 /**
1263 * Tests if two string regions are equal.
1264 * <p>
1265 * A substring of this {@code String} object is compared to a substring
1266 * of the argument other. The result is true if these substrings
1267 * represent identical character sequences. The substring of this
1268 * {@code String} object to be compared begins at index {@code toffset}
1269 * and has length {@code len}. The substring of other to be compared
1270 * begins at index {@code ooffset} and has length {@code len}. The
1271 * result is {@code false} if and only if at least one of the following
1272 * is true:
1273 * <ul><li>{@code toffset} is negative.
1274 * <li>{@code ooffset} is negative.
1275 * <li>{@code toffset+len} is greater than the length of this
1276 * {@code String} object.
1277 * <li>{@code ooffset+len} is greater than the length of the other
1278 * argument.
1279 * <li>There is some nonnegative integer <i>k</i> less than {@code len}
1280 * such that:
1281 * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
1282 * <i>k</i>{@code )}
1283 * </ul>
1284 *
1285 * <p>Note that this method does <em>not</em> take locale into account. The
1286 * {@link java.text.Collator} class provides locale-sensitive comparison.
1287 *
1288 * @param toffset the starting offset of the subregion in this string.
1289 * @param other the string argument.
1290 * @param ooffset the starting offset of the subregion in the string
1291 * argument.
1292 * @param len the number of characters to compare.
1293 * @return {@code true} if the specified subregion of this string
1294 * exactly matches the specified subregion of the string argument;
1295 * {@code false} otherwise.
1296 */
1297 public boolean regionMatches(int toffset, String other, int ooffset,
1298 int len) {
1299 char[] ta = value;
1300 int to = toffset;
1301 char[] pa = other.value;
1302 int po = ooffset;
1303 // Note: toffset, ooffset, or len might be near -1>>>1.
1304 if ((ooffset < 0) || (toffset < 0)
1305 || (toffset > (long)ta.length - len)
1306 || (ooffset > (long)pa.length - len)) {
1307 return false;
1323 * case if and only if {@code ignoreCase} is true. The substring of
1324 * this {@code String} object to be compared begins at index
1325 * {@code toffset} and has length {@code len}. The substring of
1326 * {@code other} to be compared begins at index {@code ooffset} and
1327 * has length {@code len}. The result is {@code false} if and only if
1328 * at least one of the following is true:
1329 * <ul><li>{@code toffset} is negative.
1330 * <li>{@code ooffset} is negative.
1331 * <li>{@code toffset+len} is greater than the length of this
1332 * {@code String} object.
1333 * <li>{@code ooffset+len} is greater than the length of the other
1334 * argument.
1335 * <li>{@code ignoreCase} is {@code false} and there is some nonnegative
1336 * integer <i>k</i> less than {@code len} such that:
1337 * <blockquote><pre>
1338 * this.charAt(toffset+k) != other.charAt(ooffset+k)
1339 * </pre></blockquote>
1340 * <li>{@code ignoreCase} is {@code true} and there is some nonnegative
1341 * integer <i>k</i> less than {@code len} such that:
1342 * <blockquote><pre>
1343 * Character.toLowerCase(Character.toUpperCase(this.charAt(toffset+k))) !=
1344 Character.toLowerCase(Character.toUpperCase(other.charAt(ooffset+k)))
1345 * </pre></blockquote>
1346 * </ul>
1347 *
1348 * <p>Note that this method does <em>not</em> take locale into account,
1349 * and will result in unsatisfactory results for certain locales when
1350 * {@code ignoreCase} is {@code true}. The {@link java.text.Collator} class
1351 * provides locale-sensitive comparison.
1352 *
1353 * @param ignoreCase if {@code true}, ignore case when comparing
1354 * characters.
1355 * @param toffset the starting offset of the subregion in this
1356 * string.
1357 * @param other the string argument.
1358 * @param ooffset the starting offset of the subregion in the string
1359 * argument.
1360 * @param len the number of characters to compare.
1361 * @return {@code true} if the specified subregion of this string
1362 * matches the specified subregion of the string argument;
1363 * {@code false} otherwise. Whether the matching is exact
1364 * or case insensitive depends on the {@code ignoreCase}
1365 * argument.
1366 */
1367 public boolean regionMatches(boolean ignoreCase, int toffset,
1368 String other, int ooffset, int len) {
1369 char[] ta = value;
1370 int to = toffset;
1371 char[] pa = other.value;
1372 int po = ooffset;
|