310 * @param offset
311 * The initial offset
312 * @param count
313 * The length
314 *
315 * @throws IndexOutOfBoundsException
316 * If {@code offset} is negative, {@code count} is negative, or
317 * {@code offset} is greater than {@code ascii.length - count}
318 *
319 * @see #String(byte[], int)
320 * @see #String(byte[], int, int, java.lang.String)
321 * @see #String(byte[], int, int, java.nio.charset.Charset)
322 * @see #String(byte[], int, int)
323 * @see #String(byte[], java.lang.String)
324 * @see #String(byte[], java.nio.charset.Charset)
325 * @see #String(byte[])
326 */
327 @Deprecated
328 public String(byte ascii[], int hibyte, int offset, int count) {
329 checkBounds(ascii, offset, count);
330 char value[] = new char[count];
331
332 if (hibyte == 0) {
333 for (int i = count; i-- > 0;) {
334 value[i] = (char)(ascii[i + offset] & 0xff);
335 }
336 } else {
337 hibyte <<= 8;
338 for (int i = count; i-- > 0;) {
339 value[i] = (char)(hibyte | (ascii[i + offset] & 0xff));
340 }
341 }
342 this.value = value;
343 }
344
345 /**
346 * Allocates a new {@code String} containing characters constructed from
347 * an array of 8-bit integer values. Each character <i>c</i>in the
348 * resulting string is constructed from the corresponding component
349 * <i>b</i> in the byte array such that:
350 *
966 /**
967 * Compares this string to the specified object. The result is {@code
968 * true} if and only if the argument is not {@code null} and is a {@code
969 * String} object that represents the same sequence of characters as this
970 * object.
971 *
972 * @param anObject
973 * The object to compare this {@code String} against
974 *
975 * @return {@code true} if the given object represents a {@code String}
976 * equivalent to this string, {@code false} otherwise
977 *
978 * @see #compareTo(String)
979 * @see #equalsIgnoreCase(String)
980 */
981 public boolean equals(Object anObject) {
982 if (this == anObject) {
983 return true;
984 }
985 if (anObject instanceof String) {
986 String anotherString = (String)anObject;
987 int n = value.length;
988 if (n == anotherString.value.length) {
989 char v1[] = value;
990 char v2[] = anotherString.value;
991 int i = 0;
992 while (n-- != 0) {
993 if (v1[i] != v2[i])
994 return false;
995 i++;
996 }
997 return true;
998 }
999 }
1000 return false;
1001 }
1002
1003 /**
1004 * Compares this string to the specified {@code StringBuffer}. The result
1005 * is {@code true} if and only if this {@code String} represents the same
1006 * sequence of characters as the specified {@code StringBuffer}. This method
1007 * synchronizes on the {@code StringBuffer}.
1008 *
1009 * @param sb
1010 * The {@code StringBuffer} to compare this {@code String} against
1011 *
1012 * @return {@code true} if this {@code String} represents the same
1013 * sequence of characters as the specified {@code StringBuffer},
1014 * {@code false} otherwise
1015 *
1016 * @since 1.4
1017 */
1018 public boolean contentEquals(StringBuffer sb) {
1019 return contentEquals((CharSequence)sb);
1020 }
1021
1022 private boolean nonSyncContentEquals(AbstractStringBuilder sb) {
1023 char v1[] = value;
1024 char v2[] = sb.getValue();
1025 int n = v1.length;
1026 if (n != sb.length()) {
1027 return false;
1028 }
1029 for (int i = 0; i < n; i++) {
1030 if (v1[i] != v2[i]) {
1031 return false;
1032 }
1033 }
1034 return true;
1035 }
1036
1037 /**
1038 * Compares this string to the specified {@code CharSequence}. The
1039 * result is {@code true} if and only if this {@code String} represents the
1040 * same sequence of char values as the specified sequence. Note that if the
1041 * {@code CharSequence} is a {@code StringBuffer} then the method
1042 * synchronizes on it.
1043 *
1044 * @param cs
1049 * false} otherwise
1050 *
1051 * @since 1.5
1052 */
1053 public boolean contentEquals(CharSequence cs) {
1054 // Argument is a StringBuffer, StringBuilder
1055 if (cs instanceof AbstractStringBuilder) {
1056 if (cs instanceof StringBuffer) {
1057 synchronized(cs) {
1058 return nonSyncContentEquals((AbstractStringBuilder)cs);
1059 }
1060 } else {
1061 return nonSyncContentEquals((AbstractStringBuilder)cs);
1062 }
1063 }
1064 // Argument is a String
1065 if (cs instanceof String) {
1066 return equals(cs);
1067 }
1068 // Argument is a generic CharSequence
1069 char v1[] = value;
1070 int n = v1.length;
1071 if (n != cs.length()) {
1072 return false;
1073 }
1074 for (int i = 0; i < n; i++) {
1075 if (v1[i] != cs.charAt(i)) {
1076 return false;
1077 }
1078 }
1079 return true;
1080 }
1081
1082 /**
1083 * Compares this {@code String} to another {@code String}, ignoring case
1084 * considerations. Two strings are considered equal ignoring case if they
1085 * are of the same length and corresponding characters in the two strings
1086 * are equal ignoring case.
1087 *
1088 * <p> Two characters {@code c1} and {@code c2} are considered the same
1089 * ignoring case if at least one of the following is true:
1139 * the two string -- that is, the value:
1140 * <blockquote><pre>
1141 * this.charAt(k)-anotherString.charAt(k)
1142 * </pre></blockquote>
1143 * If there is no index position at which they differ, then the shorter
1144 * string lexicographically precedes the longer string. In this case,
1145 * {@code compareTo} returns the difference of the lengths of the
1146 * strings -- that is, the value:
1147 * <blockquote><pre>
1148 * this.length()-anotherString.length()
1149 * </pre></blockquote>
1150 *
1151 * @param anotherString the {@code String} to be compared.
1152 * @return the value {@code 0} if the argument string is equal to
1153 * this string; a value less than {@code 0} if this string
1154 * is lexicographically less than the string argument; and a
1155 * value greater than {@code 0} if this string is
1156 * lexicographically greater than the string argument.
1157 */
1158 public int compareTo(String anotherString) {
1159 int len1 = value.length;
1160 int len2 = anotherString.value.length;
1161 int lim = Math.min(len1, len2);
1162 char v1[] = value;
1163 char v2[] = anotherString.value;
1164
1165 int k = 0;
1166 while (k < lim) {
1167 char c1 = v1[k];
1168 char c2 = v2[k];
1169 if (c1 != c2) {
1170 return c1 - c2;
1171 }
1172 k++;
1173 }
1174 return len1 - len2;
1175 }
1176
1177 /**
1178 * A Comparator that orders {@code String} objects as by
1179 * {@code compareToIgnoreCase}. This comparator is serializable.
1180 * <p>
1181 * Note that this Comparator does <em>not</em> take locale into account,
1182 * and will result in an unsatisfactory ordering for certain locales.
1183 * The java.text package provides <em>Collators</em> to allow
1184 * locale-sensitive ordering.
1185 *
1186 * @see java.text.Collator#compare(String, String)
1187 * @since 1.2
1188 */
1189 public static final Comparator<String> CASE_INSENSITIVE_ORDER
1190 = new CaseInsensitiveComparator();
1191 private static class CaseInsensitiveComparator
1192 implements Comparator<String>, java.io.Serializable {
1261 * {@code String} object.
1262 * <li>{@code ooffset+len} is greater than the length of the other
1263 * argument.
1264 * <li>There is some nonnegative integer <i>k</i> less than {@code len}
1265 * such that:
1266 * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
1267 * <i>k</i>{@code )}
1268 * </ul>
1269 *
1270 * @param toffset the starting offset of the subregion in this string.
1271 * @param other the string argument.
1272 * @param ooffset the starting offset of the subregion in the string
1273 * argument.
1274 * @param len the number of characters to compare.
1275 * @return {@code true} if the specified subregion of this string
1276 * exactly matches the specified subregion of the string argument;
1277 * {@code false} otherwise.
1278 */
1279 public boolean regionMatches(int toffset, String other, int ooffset,
1280 int len) {
1281 char ta[] = value;
1282 int to = toffset;
1283 char pa[] = other.value;
1284 int po = ooffset;
1285 // Note: toffset, ooffset, or len might be near -1>>>1.
1286 if ((ooffset < 0) || (toffset < 0)
1287 || (toffset > (long)value.length - len)
1288 || (ooffset > (long)other.value.length - len)) {
1289 return false;
1290 }
1291 while (len-- > 0) {
1292 if (ta[to++] != pa[po++]) {
1293 return false;
1294 }
1295 }
1296 return true;
1297 }
1298
1299 /**
1300 * Tests if two string regions are equal.
1301 * <p>
1302 * A substring of this {@code String} object is compared to a substring
1303 * of the argument {@code other}. The result is {@code true} if these
1304 * substrings represent character sequences that are the same, ignoring
1305 * case if and only if {@code ignoreCase} is true. The substring of
1306 * this {@code String} object to be compared begins at index
1307 * {@code toffset} and has length {@code len}. The substring of
1308 * {@code other} to be compared begins at index {@code ooffset} and
1331 * Character.toUpperCase(other.charAt(ooffset+k))
1332 * </pre></blockquote>
1333 * </ul>
1334 *
1335 * @param ignoreCase if {@code true}, ignore case when comparing
1336 * characters.
1337 * @param toffset the starting offset of the subregion in this
1338 * string.
1339 * @param other the string argument.
1340 * @param ooffset the starting offset of the subregion in the string
1341 * argument.
1342 * @param len the number of characters to compare.
1343 * @return {@code true} if the specified subregion of this string
1344 * matches the specified subregion of the string argument;
1345 * {@code false} otherwise. Whether the matching is exact
1346 * or case insensitive depends on the {@code ignoreCase}
1347 * argument.
1348 */
1349 public boolean regionMatches(boolean ignoreCase, int toffset,
1350 String other, int ooffset, int len) {
1351 char ta[] = value;
1352 int to = toffset;
1353 char pa[] = other.value;
1354 int po = ooffset;
1355 // Note: toffset, ooffset, or len might be near -1>>>1.
1356 if ((ooffset < 0) || (toffset < 0)
1357 || (toffset > (long)value.length - len)
1358 || (ooffset > (long)other.value.length - len)) {
1359 return false;
1360 }
1361 while (len-- > 0) {
1362 char c1 = ta[to++];
1363 char c2 = pa[po++];
1364 if (c1 == c2) {
1365 continue;
1366 }
1367 if (ignoreCase) {
1368 // If characters don't match but case may be ignored,
1369 // try converting both characters to uppercase.
1370 // If the results match, then the comparison scan should
1371 // continue.
1372 char u1 = Character.toUpperCase(c1);
1373 char u2 = Character.toUpperCase(c2);
1374 if (u1 == u2) {
1375 continue;
1376 }
1377 // Unfortunately, conversion to uppercase does not work properly
1378 // for the Georgian alphabet, which has strange rules about case
1388 }
1389
1390 /**
1391 * Tests if the substring of this string beginning at the
1392 * specified index starts with the specified prefix.
1393 *
1394 * @param prefix the prefix.
1395 * @param toffset where to begin looking in this string.
1396 * @return {@code true} if the character sequence represented by the
1397 * argument is a prefix of the substring of this object starting
1398 * at index {@code toffset}; {@code false} otherwise.
1399 * The result is {@code false} if {@code toffset} is
1400 * negative or greater than the length of this
1401 * {@code String} object; otherwise the result is the same
1402 * as the result of the expression
1403 * <pre>
1404 * this.substring(toffset).startsWith(prefix)
1405 * </pre>
1406 */
1407 public boolean startsWith(String prefix, int toffset) {
1408 char ta[] = value;
1409 int to = toffset;
1410 char pa[] = prefix.value;
1411 int po = 0;
1412 int pc = prefix.value.length;
1413 // Note: toffset might be near -1>>>1.
1414 if ((toffset < 0) || (toffset > value.length - pc)) {
1415 return false;
1416 }
1417 while (--pc >= 0) {
1418 if (ta[to++] != pa[po++]) {
1419 return false;
1420 }
1421 }
1422 return true;
1423 }
1424
1425 /**
1426 * Tests if this string starts with the specified prefix.
1427 *
1428 * @param prefix the prefix.
1429 * @return {@code true} if the character sequence represented by the
1430 * argument is a prefix of the character sequence represented by
1431 * this string; {@code false} otherwise.
1432 * Note also that {@code true} will be returned if the
1433 * argument is an empty string or is equal to this
1434 * {@code String} object as determined by the
1911 }
1912
1913 /**
1914 * Returns a string that is a substring of this string. The
1915 * substring begins with the character at the specified index and
1916 * extends to the end of this string. <p>
1917 * Examples:
1918 * <blockquote><pre>
1919 * "unhappy".substring(2) returns "happy"
1920 * "Harbison".substring(3) returns "bison"
1921 * "emptiness".substring(9) returns "" (an empty string)
1922 * </pre></blockquote>
1923 *
1924 * @param beginIndex the beginning index, inclusive.
1925 * @return the specified substring.
1926 * @exception IndexOutOfBoundsException if
1927 * {@code beginIndex} is negative or larger than the
1928 * length of this {@code String} object.
1929 */
1930 public String substring(int beginIndex) {
1931 if (beginIndex < 0) {
1932 throw new StringIndexOutOfBoundsException(beginIndex);
1933 }
1934 int subLen = value.length - beginIndex;
1935 if (subLen < 0) {
1936 throw new StringIndexOutOfBoundsException(subLen);
1937 }
1938 return (beginIndex == 0) ? this : new String(value, beginIndex, subLen);
1939 }
1940
1941 /**
1942 * Returns a string that is a substring of this string. The
1943 * substring begins at the specified {@code beginIndex} and
1944 * extends to the character at index {@code endIndex - 1}.
1945 * Thus the length of the substring is {@code endIndex-beginIndex}.
1946 * <p>
1947 * Examples:
1948 * <blockquote><pre>
1949 * "hamburger".substring(4, 8) returns "urge"
1950 * "smiles".substring(1, 5) returns "mile"
1951 * </pre></blockquote>
1952 *
1953 * @param beginIndex the beginning index, inclusive.
1954 * @param endIndex the ending index, exclusive.
1955 * @return the specified substring.
1956 * @exception IndexOutOfBoundsException if the
1957 * {@code beginIndex} is negative, or
1958 * {@code endIndex} is larger than the length of
1959 * this {@code String} object, or
1960 * {@code beginIndex} is larger than
1961 * {@code endIndex}.
1962 */
1963 public String substring(int beginIndex, int endIndex) {
1964 if (beginIndex < 0) {
1965 throw new StringIndexOutOfBoundsException(beginIndex);
1966 }
1967 if (endIndex > value.length) {
1968 throw new StringIndexOutOfBoundsException(endIndex);
1969 }
1970 int subLen = endIndex - beginIndex;
1971 if (subLen < 0) {
1972 throw new StringIndexOutOfBoundsException(subLen);
1973 }
1974 return ((beginIndex == 0) && (endIndex == value.length)) ? this
1975 : new String(value, beginIndex, subLen);
1976 }
1977
1978 /**
1979 * Returns a character sequence that is a subsequence of this sequence.
1980 *
1981 * <p> An invocation of this method of the form
1982 *
1983 * <blockquote><pre>
1984 * str.subSequence(begin, end)</pre></blockquote>
1985 *
1986 * behaves in exactly the same way as the invocation
1987 *
1988 * <blockquote><pre>
1989 * str.substring(begin, end)</pre></blockquote>
1990 *
1991 * @apiNote
1992 * This method is defined so that the {@code String} class can implement
1993 * the {@link CharSequence} interface.
1994 *
1995 * @param beginIndex the begin index, inclusive.
2017 * sequence that is the concatenation of the character sequence
2018 * represented by this {@code String} object and the character
2019 * sequence represented by the argument string.<p>
2020 * Examples:
2021 * <blockquote><pre>
2022 * "cares".concat("s") returns "caress"
2023 * "to".concat("get").concat("her") returns "together"
2024 * </pre></blockquote>
2025 *
2026 * @param str the {@code String} that is concatenated to the end
2027 * of this {@code String}.
2028 * @return a string that represents the concatenation of this object's
2029 * characters followed by the string argument's characters.
2030 */
2031 public String concat(String str) {
2032 int otherLen = str.length();
2033 if (otherLen == 0) {
2034 return this;
2035 }
2036 int len = value.length;
2037 char buf[] = Arrays.copyOf(value, len + otherLen);
2038 str.getChars(buf, len);
2039 return new String(buf, true);
2040 }
2041
2042 /**
2043 * Returns a string resulting from replacing all occurrences of
2044 * {@code oldChar} in this string with {@code newChar}.
2045 * <p>
2046 * If the character {@code oldChar} does not occur in the
2047 * character sequence represented by this {@code String} object,
2048 * then a reference to this {@code String} object is returned.
2049 * Otherwise, a {@code String} object is returned that
2050 * represents a character sequence identical to the character sequence
2051 * represented by this {@code String} object, except that every
2052 * occurrence of {@code oldChar} is replaced by an occurrence
2053 * of {@code newChar}.
2054 * <p>
2055 * Examples:
2056 * <blockquote><pre>
2057 * "mesquite in your cellar".replace('e', 'o')
2058 * returns "mosquito in your collar"
2059 * "the war of baronets".replace('r', 'y')
2060 * returns "the way of bayonets"
2061 * "sparring with a purple porpoise".replace('p', 't')
2062 * returns "starring with a turtle tortoise"
2063 * "JonL".replace('q', 'x') returns "JonL" (no change)
2064 * </pre></blockquote>
2065 *
2066 * @param oldChar the old character.
2067 * @param newChar the new character.
2068 * @return a string derived from this string by replacing every
2069 * occurrence of {@code oldChar} with {@code newChar}.
2070 */
2071 public String replace(char oldChar, char newChar) {
2072 if (oldChar != newChar) {
2073 int len = value.length;
2074 int i = -1;
2075 char[] val = value; /* avoid getfield opcode */
2076
2077 while (++i < len) {
2078 if (val[i] == oldChar) {
2079 break;
2080 }
2081 }
2082 if (i < len) {
2083 char buf[] = new char[len];
2084 for (int j = 0; j < i; j++) {
2085 buf[j] = val[j];
2086 }
2087 while (i < len) {
2088 char c = val[i];
2089 buf[i] = (c == oldChar) ? newChar : c;
2090 i++;
2091 }
2092 return new String(buf, true);
2093 }
2094 }
2095 return this;
2096 }
2097
2098 /**
2099 * Tells whether or not this string matches the given <a
2100 * href="../util/regex/Pattern.html#sum">regular expression</a>.
2101 *
2102 * <p> An invocation of this method of the form
2103 * <i>str</i>{@code .matches(}<i>regex</i>{@code )} yields exactly the
2859 * {@code String} object representing an empty string is
2860 * returned.
2861 * <p>
2862 * Otherwise, let <i>k</i> be the index of the first character in the
2863 * string whose code is greater than {@code '\u005Cu0020'}, and let
2864 * <i>m</i> be the index of the last character in the string whose code
2865 * is greater than {@code '\u005Cu0020'}. A {@code String}
2866 * object is returned, representing the substring of this string that
2867 * begins with the character at index <i>k</i> and ends with the
2868 * character at index <i>m</i>-that is, the result of
2869 * {@code this.substring(k, m + 1)}.
2870 * <p>
2871 * This method may be used to trim whitespace (as defined above) from
2872 * the beginning and end of a string.
2873 *
2874 * @return A string whose value is this string, with any leading and trailing white
2875 * space removed, or this string if it has no leading or
2876 * trailing white space.
2877 */
2878 public String trim() {
2879 int len = value.length;
2880 int st = 0;
2881 char[] val = value; /* avoid getfield opcode */
2882
2883 while ((st < len) && (val[st] <= ' ')) {
2884 st++;
2885 }
2886 while ((st < len) && (val[len - 1] <= ' ')) {
2887 len--;
2888 }
2889 return ((st > 0) || (len < value.length)) ? substring(st, len) : this;
2890 }
2891
2892 /**
2893 * This object (which is already a string!) is itself returned.
2894 *
2895 * @return the string itself.
2896 */
2897 public String toString() {
2898 return this;
2899 }
2900
2901 static class IntCharArraySpliterator implements Spliterator.OfInt {
2902 private final char[] array;
2903 private int index; // current index, modified on advance/split
2904 private final int fence; // one past last index
2905 private final int cs;
2906
2907 IntCharArraySpliterator(char[] array, int acs) {
2908 this(array, 0, array.length, acs);
2909 }
3064 * {@code int} values which are then passed to the stream.
3065 *
3066 * @return an IntStream of Unicode code points from this sequence
3067 * @since 1.9
3068 */
3069 @Override
3070 public IntStream codePoints() {
3071 return StreamSupport.intStream(
3072 new CodePointsSpliterator(value, Spliterator.IMMUTABLE), false);
3073 }
3074
3075 /**
3076 * Converts this string to a new character array.
3077 *
3078 * @return a newly allocated character array whose length is the length
3079 * of this string and whose contents are initialized to contain
3080 * the character sequence represented by this string.
3081 */
3082 public char[] toCharArray() {
3083 // Cannot use Arrays.copyOf because of class initialization order issues
3084 char result[] = new char[value.length];
3085 System.arraycopy(value, 0, result, 0, value.length);
3086 return result;
3087 }
3088
3089 /**
3090 * Returns a formatted string using the specified format string and
3091 * arguments.
3092 *
3093 * <p> The locale always used is the one returned by {@link
3094 * java.util.Locale#getDefault() Locale.getDefault()}.
3095 *
3096 * @param format
3097 * A <a href="../util/Formatter.html#syntax">format string</a>
3098 *
3099 * @param args
3100 * Arguments referenced by the format specifiers in the format
3101 * string. If there are more arguments than format specifiers, the
3102 * extra arguments are ignored. The number of arguments is
3103 * variable and may be zero. The maximum number of arguments is
3104 * limited by the maximum dimension of a Java array as defined by
3249 * Returns the string representation of the {@code boolean} argument.
3250 *
3251 * @param b a {@code boolean}.
3252 * @return if the argument is {@code true}, a string equal to
3253 * {@code "true"} is returned; otherwise, a string equal to
3254 * {@code "false"} is returned.
3255 */
3256 public static String valueOf(boolean b) {
3257 return b ? "true" : "false";
3258 }
3259
3260 /**
3261 * Returns the string representation of the {@code char}
3262 * argument.
3263 *
3264 * @param c a {@code char}.
3265 * @return a string of length {@code 1} containing
3266 * as its single character the argument {@code c}.
3267 */
3268 public static String valueOf(char c) {
3269 char data[] = {c};
3270 return new String(data, true);
3271 }
3272
3273 /**
3274 * Returns the string representation of the {@code int} argument.
3275 * <p>
3276 * The representation is exactly the one returned by the
3277 * {@code Integer.toString} method of one argument.
3278 *
3279 * @param i an {@code int}.
3280 * @return a string representation of the {@code int} argument.
3281 * @see java.lang.Integer#toString(int, int)
3282 */
3283 public static String valueOf(int i) {
3284 return Integer.toString(i);
3285 }
3286
3287 /**
3288 * Returns the string representation of the {@code long} argument.
3289 * <p>
3290 * The representation is exactly the one returned by the
|
310 * @param offset
311 * The initial offset
312 * @param count
313 * The length
314 *
315 * @throws IndexOutOfBoundsException
316 * If {@code offset} is negative, {@code count} is negative, or
317 * {@code offset} is greater than {@code ascii.length - count}
318 *
319 * @see #String(byte[], int)
320 * @see #String(byte[], int, int, java.lang.String)
321 * @see #String(byte[], int, int, java.nio.charset.Charset)
322 * @see #String(byte[], int, int)
323 * @see #String(byte[], java.lang.String)
324 * @see #String(byte[], java.nio.charset.Charset)
325 * @see #String(byte[])
326 */
327 @Deprecated
328 public String(byte ascii[], int hibyte, int offset, int count) {
329 checkBounds(ascii, offset, count);
330 char[] value = new char[count];
331
332 if (hibyte == 0) {
333 for (int i = count; i-- > 0;) {
334 value[i] = (char)(ascii[i + offset] & 0xff);
335 }
336 } else {
337 hibyte <<= 8;
338 for (int i = count; i-- > 0;) {
339 value[i] = (char)(hibyte | (ascii[i + offset] & 0xff));
340 }
341 }
342 this.value = value;
343 }
344
345 /**
346 * Allocates a new {@code String} containing characters constructed from
347 * an array of 8-bit integer values. Each character <i>c</i>in the
348 * resulting string is constructed from the corresponding component
349 * <i>b</i> in the byte array such that:
350 *
966 /**
967 * Compares this string to the specified object. The result is {@code
968 * true} if and only if the argument is not {@code null} and is a {@code
969 * String} object that represents the same sequence of characters as this
970 * object.
971 *
972 * @param anObject
973 * The object to compare this {@code String} against
974 *
975 * @return {@code true} if the given object represents a {@code String}
976 * equivalent to this string, {@code false} otherwise
977 *
978 * @see #compareTo(String)
979 * @see #equalsIgnoreCase(String)
980 */
981 public boolean equals(Object anObject) {
982 if (this == anObject) {
983 return true;
984 }
985 if (anObject instanceof String) {
986 char[] v1 = value;
987 char[] v2 = ((String)anObject).value;
988 int n = v1.length;
989 if (n == v2.length) {
990 int i = 0;
991 while (n-- != 0) {
992 if (v1[i] != v2[i])
993 return false;
994 i++;
995 }
996 return true;
997 }
998 }
999 return false;
1000 }
1001
1002 /**
1003 * Compares this string to the specified {@code StringBuffer}. The result
1004 * is {@code true} if and only if this {@code String} represents the same
1005 * sequence of characters as the specified {@code StringBuffer}. This method
1006 * synchronizes on the {@code StringBuffer}.
1007 *
1008 * @param sb
1009 * The {@code StringBuffer} to compare this {@code String} against
1010 *
1011 * @return {@code true} if this {@code String} represents the same
1012 * sequence of characters as the specified {@code StringBuffer},
1013 * {@code false} otherwise
1014 *
1015 * @since 1.4
1016 */
1017 public boolean contentEquals(StringBuffer sb) {
1018 return contentEquals((CharSequence)sb);
1019 }
1020
1021 private boolean nonSyncContentEquals(AbstractStringBuilder sb) {
1022 char[] v1 = value;
1023 char[] v2 = sb.getValue();
1024 int n = v1.length;
1025 if (n != sb.length()) {
1026 return false;
1027 }
1028 for (int i = 0; i < n; i++) {
1029 if (v1[i] != v2[i]) {
1030 return false;
1031 }
1032 }
1033 return true;
1034 }
1035
1036 /**
1037 * Compares this string to the specified {@code CharSequence}. The
1038 * result is {@code true} if and only if this {@code String} represents the
1039 * same sequence of char values as the specified sequence. Note that if the
1040 * {@code CharSequence} is a {@code StringBuffer} then the method
1041 * synchronizes on it.
1042 *
1043 * @param cs
1048 * false} otherwise
1049 *
1050 * @since 1.5
1051 */
1052 public boolean contentEquals(CharSequence cs) {
1053 // Argument is a StringBuffer, StringBuilder
1054 if (cs instanceof AbstractStringBuilder) {
1055 if (cs instanceof StringBuffer) {
1056 synchronized(cs) {
1057 return nonSyncContentEquals((AbstractStringBuilder)cs);
1058 }
1059 } else {
1060 return nonSyncContentEquals((AbstractStringBuilder)cs);
1061 }
1062 }
1063 // Argument is a String
1064 if (cs instanceof String) {
1065 return equals(cs);
1066 }
1067 // Argument is a generic CharSequence
1068 char[] v1 = value;
1069 int n = v1.length;
1070 if (n != cs.length()) {
1071 return false;
1072 }
1073 for (int i = 0; i < n; i++) {
1074 if (v1[i] != cs.charAt(i)) {
1075 return false;
1076 }
1077 }
1078 return true;
1079 }
1080
1081 /**
1082 * Compares this {@code String} to another {@code String}, ignoring case
1083 * considerations. Two strings are considered equal ignoring case if they
1084 * are of the same length and corresponding characters in the two strings
1085 * are equal ignoring case.
1086 *
1087 * <p> Two characters {@code c1} and {@code c2} are considered the same
1088 * ignoring case if at least one of the following is true:
1138 * the two string -- that is, the value:
1139 * <blockquote><pre>
1140 * this.charAt(k)-anotherString.charAt(k)
1141 * </pre></blockquote>
1142 * If there is no index position at which they differ, then the shorter
1143 * string lexicographically precedes the longer string. In this case,
1144 * {@code compareTo} returns the difference of the lengths of the
1145 * strings -- that is, the value:
1146 * <blockquote><pre>
1147 * this.length()-anotherString.length()
1148 * </pre></blockquote>
1149 *
1150 * @param anotherString the {@code String} to be compared.
1151 * @return the value {@code 0} if the argument string is equal to
1152 * this string; a value less than {@code 0} if this string
1153 * is lexicographically less than the string argument; and a
1154 * value greater than {@code 0} if this string is
1155 * lexicographically greater than the string argument.
1156 */
1157 public int compareTo(String anotherString) {
1158 char[] v1 = value;
1159 char[] v2 = anotherString.value;
1160 int len1 = v1.length;
1161 int len2 = v2.length;
1162 int lim = Math.min(len1, len2);
1163
1164 for (int k = 0; k < lim; k++) {
1165 char c1 = v1[k];
1166 char c2 = v2[k];
1167 if (c1 != c2) {
1168 return c1 - c2;
1169 }
1170 }
1171 return len1 - len2;
1172 }
1173
1174 /**
1175 * A Comparator that orders {@code String} objects as by
1176 * {@code compareToIgnoreCase}. This comparator is serializable.
1177 * <p>
1178 * Note that this Comparator does <em>not</em> take locale into account,
1179 * and will result in an unsatisfactory ordering for certain locales.
1180 * The java.text package provides <em>Collators</em> to allow
1181 * locale-sensitive ordering.
1182 *
1183 * @see java.text.Collator#compare(String, String)
1184 * @since 1.2
1185 */
1186 public static final Comparator<String> CASE_INSENSITIVE_ORDER
1187 = new CaseInsensitiveComparator();
1188 private static class CaseInsensitiveComparator
1189 implements Comparator<String>, java.io.Serializable {
1258 * {@code String} object.
1259 * <li>{@code ooffset+len} is greater than the length of the other
1260 * argument.
1261 * <li>There is some nonnegative integer <i>k</i> less than {@code len}
1262 * such that:
1263 * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + }
1264 * <i>k</i>{@code )}
1265 * </ul>
1266 *
1267 * @param toffset the starting offset of the subregion in this string.
1268 * @param other the string argument.
1269 * @param ooffset the starting offset of the subregion in the string
1270 * argument.
1271 * @param len the number of characters to compare.
1272 * @return {@code true} if the specified subregion of this string
1273 * exactly matches the specified subregion of the string argument;
1274 * {@code false} otherwise.
1275 */
1276 public boolean regionMatches(int toffset, String other, int ooffset,
1277 int len) {
1278 char[] ta = value;
1279 int to = toffset;
1280 char[] pa = other.value;
1281 int po = ooffset;
1282 // Note: toffset, ooffset, or len might be near -1>>>1.
1283 if ((ooffset < 0) || (toffset < 0)
1284 || (toffset > (long)ta.length - len)
1285 || (ooffset > (long)pa.length - len)) {
1286 return false;
1287 }
1288 while (len-- > 0) {
1289 if (ta[to++] != pa[po++]) {
1290 return false;
1291 }
1292 }
1293 return true;
1294 }
1295
1296 /**
1297 * Tests if two string regions are equal.
1298 * <p>
1299 * A substring of this {@code String} object is compared to a substring
1300 * of the argument {@code other}. The result is {@code true} if these
1301 * substrings represent character sequences that are the same, ignoring
1302 * case if and only if {@code ignoreCase} is true. The substring of
1303 * this {@code String} object to be compared begins at index
1304 * {@code toffset} and has length {@code len}. The substring of
1305 * {@code other} to be compared begins at index {@code ooffset} and
1328 * Character.toUpperCase(other.charAt(ooffset+k))
1329 * </pre></blockquote>
1330 * </ul>
1331 *
1332 * @param ignoreCase if {@code true}, ignore case when comparing
1333 * characters.
1334 * @param toffset the starting offset of the subregion in this
1335 * string.
1336 * @param other the string argument.
1337 * @param ooffset the starting offset of the subregion in the string
1338 * argument.
1339 * @param len the number of characters to compare.
1340 * @return {@code true} if the specified subregion of this string
1341 * matches the specified subregion of the string argument;
1342 * {@code false} otherwise. Whether the matching is exact
1343 * or case insensitive depends on the {@code ignoreCase}
1344 * argument.
1345 */
1346 public boolean regionMatches(boolean ignoreCase, int toffset,
1347 String other, int ooffset, int len) {
1348 char[] ta = value;
1349 int to = toffset;
1350 char[] pa = other.value;
1351 int po = ooffset;
1352 // Note: toffset, ooffset, or len might be near -1>>>1.
1353 if ((ooffset < 0) || (toffset < 0)
1354 || (toffset > (long)ta.length - len)
1355 || (ooffset > (long)pa.length - len)) {
1356 return false;
1357 }
1358 while (len-- > 0) {
1359 char c1 = ta[to++];
1360 char c2 = pa[po++];
1361 if (c1 == c2) {
1362 continue;
1363 }
1364 if (ignoreCase) {
1365 // If characters don't match but case may be ignored,
1366 // try converting both characters to uppercase.
1367 // If the results match, then the comparison scan should
1368 // continue.
1369 char u1 = Character.toUpperCase(c1);
1370 char u2 = Character.toUpperCase(c2);
1371 if (u1 == u2) {
1372 continue;
1373 }
1374 // Unfortunately, conversion to uppercase does not work properly
1375 // for the Georgian alphabet, which has strange rules about case
1385 }
1386
1387 /**
1388 * Tests if the substring of this string beginning at the
1389 * specified index starts with the specified prefix.
1390 *
1391 * @param prefix the prefix.
1392 * @param toffset where to begin looking in this string.
1393 * @return {@code true} if the character sequence represented by the
1394 * argument is a prefix of the substring of this object starting
1395 * at index {@code toffset}; {@code false} otherwise.
1396 * The result is {@code false} if {@code toffset} is
1397 * negative or greater than the length of this
1398 * {@code String} object; otherwise the result is the same
1399 * as the result of the expression
1400 * <pre>
1401 * this.substring(toffset).startsWith(prefix)
1402 * </pre>
1403 */
1404 public boolean startsWith(String prefix, int toffset) {
1405 char[] ta = value;
1406 int to = toffset;
1407 char[] pa = prefix.value;
1408 int po = 0;
1409 int pc = pa.length;
1410 // Note: toffset might be near -1>>>1.
1411 if ((toffset < 0) || (toffset > ta.length - pc)) {
1412 return false;
1413 }
1414 while (--pc >= 0) {
1415 if (ta[to++] != pa[po++]) {
1416 return false;
1417 }
1418 }
1419 return true;
1420 }
1421
1422 /**
1423 * Tests if this string starts with the specified prefix.
1424 *
1425 * @param prefix the prefix.
1426 * @return {@code true} if the character sequence represented by the
1427 * argument is a prefix of the character sequence represented by
1428 * this string; {@code false} otherwise.
1429 * Note also that {@code true} will be returned if the
1430 * argument is an empty string or is equal to this
1431 * {@code String} object as determined by the
1908 }
1909
1910 /**
1911 * Returns a string that is a substring of this string. The
1912 * substring begins with the character at the specified index and
1913 * extends to the end of this string. <p>
1914 * Examples:
1915 * <blockquote><pre>
1916 * "unhappy".substring(2) returns "happy"
1917 * "Harbison".substring(3) returns "bison"
1918 * "emptiness".substring(9) returns "" (an empty string)
1919 * </pre></blockquote>
1920 *
1921 * @param beginIndex the beginning index, inclusive.
1922 * @return the specified substring.
1923 * @exception IndexOutOfBoundsException if
1924 * {@code beginIndex} is negative or larger than the
1925 * length of this {@code String} object.
1926 */
1927 public String substring(int beginIndex) {
1928 if (beginIndex <= 0) {
1929 if (beginIndex < 0) {
1930 throw new StringIndexOutOfBoundsException(beginIndex);
1931 }
1932 return this;
1933 }
1934 int subLen = value.length - beginIndex;
1935 if (subLen < 0) {
1936 throw new StringIndexOutOfBoundsException(subLen);
1937 }
1938 return new String(value, beginIndex, subLen);
1939 }
1940
1941 /**
1942 * Returns a string that is a substring of this string. The
1943 * substring begins at the specified {@code beginIndex} and
1944 * extends to the character at index {@code endIndex - 1}.
1945 * Thus the length of the substring is {@code endIndex-beginIndex}.
1946 * <p>
1947 * Examples:
1948 * <blockquote><pre>
1949 * "hamburger".substring(4, 8) returns "urge"
1950 * "smiles".substring(1, 5) returns "mile"
1951 * </pre></blockquote>
1952 *
1953 * @param beginIndex the beginning index, inclusive.
1954 * @param endIndex the ending index, exclusive.
1955 * @return the specified substring.
1956 * @exception IndexOutOfBoundsException if the
1957 * {@code beginIndex} is negative, or
1958 * {@code endIndex} is larger than the length of
1959 * this {@code String} object, or
1960 * {@code beginIndex} is larger than
1961 * {@code endIndex}.
1962 */
1963 public String substring(int beginIndex, int endIndex) {
1964 if (beginIndex <= 0) {
1965 if (beginIndex < 0) {
1966 throw new StringIndexOutOfBoundsException(beginIndex);
1967 }
1968 if (endIndex == value.length) {
1969 return this;
1970 }
1971 }
1972 if (endIndex > value.length) {
1973 throw new StringIndexOutOfBoundsException(endIndex);
1974 }
1975 int subLen = endIndex - beginIndex;
1976 if (subLen < 0) {
1977 throw new StringIndexOutOfBoundsException(subLen);
1978 }
1979 return new String(value, beginIndex, subLen);
1980 }
1981
1982 /**
1983 * Returns a character sequence that is a subsequence of this sequence.
1984 *
1985 * <p> An invocation of this method of the form
1986 *
1987 * <blockquote><pre>
1988 * str.subSequence(begin, end)</pre></blockquote>
1989 *
1990 * behaves in exactly the same way as the invocation
1991 *
1992 * <blockquote><pre>
1993 * str.substring(begin, end)</pre></blockquote>
1994 *
1995 * @apiNote
1996 * This method is defined so that the {@code String} class can implement
1997 * the {@link CharSequence} interface.
1998 *
1999 * @param beginIndex the begin index, inclusive.
2021 * sequence that is the concatenation of the character sequence
2022 * represented by this {@code String} object and the character
2023 * sequence represented by the argument string.<p>
2024 * Examples:
2025 * <blockquote><pre>
2026 * "cares".concat("s") returns "caress"
2027 * "to".concat("get").concat("her") returns "together"
2028 * </pre></blockquote>
2029 *
2030 * @param str the {@code String} that is concatenated to the end
2031 * of this {@code String}.
2032 * @return a string that represents the concatenation of this object's
2033 * characters followed by the string argument's characters.
2034 */
2035 public String concat(String str) {
2036 int otherLen = str.length();
2037 if (otherLen == 0) {
2038 return this;
2039 }
2040 int len = value.length;
2041 char[] buf = Arrays.copyOf(value, len + otherLen);
2042 str.getChars(buf, len);
2043 return new String(buf, true);
2044 }
2045
2046 /**
2047 * Returns a string resulting from replacing all occurrences of
2048 * {@code oldChar} in this string with {@code newChar}.
2049 * <p>
2050 * If the character {@code oldChar} does not occur in the
2051 * character sequence represented by this {@code String} object,
2052 * then a reference to this {@code String} object is returned.
2053 * Otherwise, a {@code String} object is returned that
2054 * represents a character sequence identical to the character sequence
2055 * represented by this {@code String} object, except that every
2056 * occurrence of {@code oldChar} is replaced by an occurrence
2057 * of {@code newChar}.
2058 * <p>
2059 * Examples:
2060 * <blockquote><pre>
2061 * "mesquite in your cellar".replace('e', 'o')
2062 * returns "mosquito in your collar"
2063 * "the war of baronets".replace('r', 'y')
2064 * returns "the way of bayonets"
2065 * "sparring with a purple porpoise".replace('p', 't')
2066 * returns "starring with a turtle tortoise"
2067 * "JonL".replace('q', 'x') returns "JonL" (no change)
2068 * </pre></blockquote>
2069 *
2070 * @param oldChar the old character.
2071 * @param newChar the new character.
2072 * @return a string derived from this string by replacing every
2073 * occurrence of {@code oldChar} with {@code newChar}.
2074 */
2075 public String replace(char oldChar, char newChar) {
2076 if (oldChar != newChar) {
2077 char[] val = value; /* avoid getfield opcode */
2078 int len = val.length;
2079 int i = -1;
2080
2081 while (++i < len) {
2082 if (val[i] == oldChar) {
2083 break;
2084 }
2085 }
2086 if (i < len) {
2087 char[] buf = new char[len];
2088 for (int j = 0; j < i; j++) {
2089 buf[j] = val[j];
2090 }
2091 while (i < len) {
2092 char c = val[i];
2093 buf[i] = (c == oldChar) ? newChar : c;
2094 i++;
2095 }
2096 return new String(buf, true);
2097 }
2098 }
2099 return this;
2100 }
2101
2102 /**
2103 * Tells whether or not this string matches the given <a
2104 * href="../util/regex/Pattern.html#sum">regular expression</a>.
2105 *
2106 * <p> An invocation of this method of the form
2107 * <i>str</i>{@code .matches(}<i>regex</i>{@code )} yields exactly the
2863 * {@code String} object representing an empty string is
2864 * returned.
2865 * <p>
2866 * Otherwise, let <i>k</i> be the index of the first character in the
2867 * string whose code is greater than {@code '\u005Cu0020'}, and let
2868 * <i>m</i> be the index of the last character in the string whose code
2869 * is greater than {@code '\u005Cu0020'}. A {@code String}
2870 * object is returned, representing the substring of this string that
2871 * begins with the character at index <i>k</i> and ends with the
2872 * character at index <i>m</i>-that is, the result of
2873 * {@code this.substring(k, m + 1)}.
2874 * <p>
2875 * This method may be used to trim whitespace (as defined above) from
2876 * the beginning and end of a string.
2877 *
2878 * @return A string whose value is this string, with any leading and trailing white
2879 * space removed, or this string if it has no leading or
2880 * trailing white space.
2881 */
2882 public String trim() {
2883 char[] val = value; /* avoid getfield opcode */
2884 int end = val.length;
2885 int beg = 0;
2886
2887 while ((beg < end) && (val[beg] <= ' ')) {
2888 beg++;
2889 }
2890 while ((beg < end) && (val[end - 1] <= ' ')) {
2891 end--;
2892 }
2893 return substring(beg, end);
2894 }
2895
2896 /**
2897 * This object (which is already a string!) is itself returned.
2898 *
2899 * @return the string itself.
2900 */
2901 public String toString() {
2902 return this;
2903 }
2904
2905 static class IntCharArraySpliterator implements Spliterator.OfInt {
2906 private final char[] array;
2907 private int index; // current index, modified on advance/split
2908 private final int fence; // one past last index
2909 private final int cs;
2910
2911 IntCharArraySpliterator(char[] array, int acs) {
2912 this(array, 0, array.length, acs);
2913 }
3068 * {@code int} values which are then passed to the stream.
3069 *
3070 * @return an IntStream of Unicode code points from this sequence
3071 * @since 1.9
3072 */
3073 @Override
3074 public IntStream codePoints() {
3075 return StreamSupport.intStream(
3076 new CodePointsSpliterator(value, Spliterator.IMMUTABLE), false);
3077 }
3078
3079 /**
3080 * Converts this string to a new character array.
3081 *
3082 * @return a newly allocated character array whose length is the length
3083 * of this string and whose contents are initialized to contain
3084 * the character sequence represented by this string.
3085 */
3086 public char[] toCharArray() {
3087 // Cannot use Arrays.copyOf because of class initialization order issues
3088 char[] result = new char[value.length];
3089 System.arraycopy(value, 0, result, 0, value.length);
3090 return result;
3091 }
3092
3093 /**
3094 * Returns a formatted string using the specified format string and
3095 * arguments.
3096 *
3097 * <p> The locale always used is the one returned by {@link
3098 * java.util.Locale#getDefault() Locale.getDefault()}.
3099 *
3100 * @param format
3101 * A <a href="../util/Formatter.html#syntax">format string</a>
3102 *
3103 * @param args
3104 * Arguments referenced by the format specifiers in the format
3105 * string. If there are more arguments than format specifiers, the
3106 * extra arguments are ignored. The number of arguments is
3107 * variable and may be zero. The maximum number of arguments is
3108 * limited by the maximum dimension of a Java array as defined by
3253 * Returns the string representation of the {@code boolean} argument.
3254 *
3255 * @param b a {@code boolean}.
3256 * @return if the argument is {@code true}, a string equal to
3257 * {@code "true"} is returned; otherwise, a string equal to
3258 * {@code "false"} is returned.
3259 */
3260 public static String valueOf(boolean b) {
3261 return b ? "true" : "false";
3262 }
3263
3264 /**
3265 * Returns the string representation of the {@code char}
3266 * argument.
3267 *
3268 * @param c a {@code char}.
3269 * @return a string of length {@code 1} containing
3270 * as its single character the argument {@code c}.
3271 */
3272 public static String valueOf(char c) {
3273 return new String(new char[]{c}, true);
3274 }
3275
3276 /**
3277 * Returns the string representation of the {@code int} argument.
3278 * <p>
3279 * The representation is exactly the one returned by the
3280 * {@code Integer.toString} method of one argument.
3281 *
3282 * @param i an {@code int}.
3283 * @return a string representation of the {@code int} argument.
3284 * @see java.lang.Integer#toString(int, int)
3285 */
3286 public static String valueOf(int i) {
3287 return Integer.toString(i);
3288 }
3289
3290 /**
3291 * Returns the string representation of the {@code long} argument.
3292 * <p>
3293 * The representation is exactly the one returned by the
|