2186 *
2187 * <p> When there is a positive-width match at the beginning of this
2188 * string then an empty leading substring is included at the beginning
2189 * of the resulting array. A zero-width match at the beginning however
2190 * never produces such empty leading substring.
2191 *
2192 * <p> The {@code limit} parameter controls the number of times the
2193 * pattern is applied and therefore affects the length of the resulting
2194 * array. If the limit <i>n</i> is greater than zero then the pattern
2195 * will be applied at most <i>n</i> - 1 times, the array's
2196 * length will be no greater than <i>n</i>, and the array's last entry
2197 * will contain all input beyond the last matched delimiter. If <i>n</i>
2198 * is non-positive then the pattern will be applied as many times as
2199 * possible and the array can have any length. If <i>n</i> is zero then
2200 * the pattern will be applied as many times as possible, the array can
2201 * have any length, and trailing empty strings will be discarded.
2202 *
2203 * <p> The string {@code "boo:and:foo"}, for example, yields the
2204 * following results with these parameters:
2205 *
2206 * <blockquote><table cellpadding=1 cellspacing=0 summary="Split example showing regex, limit, and result">
2207 * <tr>
2208 * <th>Regex</th>
2209 * <th>Limit</th>
2210 * <th>Result</th>
2211 * </tr>
2212 * <tr><td style="text-align:center">:</td>
2213 * <td style="text-align:center">2</td>
2214 * <td>{@code { "boo", "and:foo" }}</td></tr>
2215 * <tr><td style="text-align:center">:</td>
2216 * <td style="text-align:center">5</td>
2217 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2218 * <tr><td style="text-align:center">:</td>
2219 * <td style="text-align:center">-2</td>
2220 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2221 * <tr><td style="text-align:center">o</td>
2222 * <td style="text-align:center">5</td>
2223 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr>
2224 * <tr><td style="text-align:center">o</td>
2225 * <td style="text-align:center">-2</td>
2226 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr>
2227 * <tr><td style="text-align:center">o</td>
2228 * <td style="text-align:center">0</td>
2229 * <td>{@code { "b", "", ":and:f" }}</td></tr>
2230 * </table></blockquote>
2231 *
2232 * <p> An invocation of this method of the form
2233 * <i>str.</i>{@code split(}<i>regex</i>{@code ,} <i>n</i>{@code )}
2234 * yields the same result as the expression
2235 *
2236 * <blockquote>
2237 * <code>
2238 * {@link java.util.regex.Pattern}.{@link
2239 * java.util.regex.Pattern#compile compile}(<i>regex</i>).{@link
2240 * java.util.regex.Pattern#split(java.lang.CharSequence,int) split}(<i>str</i>, <i>n</i>)
2241 * </code>
2242 * </blockquote>
2243 *
2244 *
2245 * @param regex
2246 * the delimiting regular expression
2247 *
2248 * @param limit
2249 * the result threshold, as described above
2309 }
2310 }
2311 String[] result = new String[resultSize];
2312 return list.subList(0, resultSize).toArray(result);
2313 }
2314 return Pattern.compile(regex).split(this, limit);
2315 }
2316
2317 /**
2318 * Splits this string around matches of the given <a
2319 * href="../util/regex/Pattern.html#sum">regular expression</a>.
2320 *
2321 * <p> This method works as if by invoking the two-argument {@link
2322 * #split(String, int) split} method with the given expression and a limit
2323 * argument of zero. Trailing empty strings are therefore not included in
2324 * the resulting array.
2325 *
2326 * <p> The string {@code "boo:and:foo"}, for example, yields the following
2327 * results with these expressions:
2328 *
2329 * <blockquote><table cellpadding=1 cellspacing=0 summary="Split examples showing regex and result">
2330 * <tr>
2331 * <th>Regex</th>
2332 * <th>Result</th>
2333 * </tr>
2334 * <tr><td style="text-align:center">:</td>
2335 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2336 * <tr><td style="text-align:center">o</td>
2337 * <td>{@code { "b", "", ":and:f" }}</td></tr>
2338 * </table></blockquote>
2339 *
2340 *
2341 * @param regex
2342 * the delimiting regular expression
2343 *
2344 * @return the array of strings computed by splitting this string
2345 * around matches of the given regular expression
2346 *
2347 * @throws PatternSyntaxException
2348 * if the regular expression's syntax is invalid
2349 *
2350 * @see java.util.regex.Pattern
2351 *
2352 * @since 1.4
2353 * @spec JSR-51
2354 */
2355 public String[] split(String regex) {
2356 return split(regex, 0);
2357 }
2428 */
2429 public static String join(CharSequence delimiter,
2430 Iterable<? extends CharSequence> elements) {
2431 Objects.requireNonNull(delimiter);
2432 Objects.requireNonNull(elements);
2433 StringJoiner joiner = new StringJoiner(delimiter);
2434 for (CharSequence cs: elements) {
2435 joiner.add(cs);
2436 }
2437 return joiner.toString();
2438 }
2439
2440 /**
2441 * Converts all of the characters in this {@code String} to lower
2442 * case using the rules of the given {@code Locale}. Case mapping is based
2443 * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2444 * class. Since case mappings are not always 1:1 char mappings, the resulting
2445 * {@code String} may be a different length than the original {@code String}.
2446 * <p>
2447 * Examples of lowercase mappings are in the following table:
2448 * <table border="1" summary="Lowercase mapping examples showing language code of locale, upper case, lower case, and description">
2449 * <tr>
2450 * <th>Language Code of Locale</th>
2451 * <th>Upper Case</th>
2452 * <th>Lower Case</th>
2453 * <th>Description</th>
2454 * </tr>
2455 * <tr>
2456 * <td>tr (Turkish)</td>
2457 * <td>\u0130</td>
2458 * <td>\u0069</td>
2459 * <td>capital letter I with dot above -> small letter i</td>
2460 * </tr>
2461 * <tr>
2462 * <td>tr (Turkish)</td>
2463 * <td>\u0049</td>
2464 * <td>\u0131</td>
2465 * <td>capital letter I -> small letter dotless i </td>
2466 * </tr>
2467 * <tr>
2468 * <td>(all)</td>
2469 * <td>French Fries</td>
2470 * <td>french fries</td>
2471 * <td>lowercased all chars in String</td>
2472 * </tr>
2473 * <tr>
2474 * <td>(all)</td>
2475 * <td><img src="doc-files/capiota.gif" alt="capiota"><img src="doc-files/capchi.gif" alt="capchi">
2476 * <img src="doc-files/captheta.gif" alt="captheta"><img src="doc-files/capupsil.gif" alt="capupsil">
2477 * <img src="doc-files/capsigma.gif" alt="capsigma"></td>
2478 * <td><img src="doc-files/iota.gif" alt="iota"><img src="doc-files/chi.gif" alt="chi">
2479 * <img src="doc-files/theta.gif" alt="theta"><img src="doc-files/upsilon.gif" alt="upsilon">
2480 * <img src="doc-files/sigma1.gif" alt="sigma"></td>
2481 * <td>lowercased all chars in String</td>
2482 * </tr>
2483 * </table>
2484 *
2485 * @param locale use the case transformation rules for this locale
2486 * @return the {@code String}, converted to lowercase.
2487 * @see java.lang.String#toLowerCase()
2488 * @see java.lang.String#toUpperCase()
2489 * @see java.lang.String#toUpperCase(Locale)
2490 * @since 1.1
2491 */
2492 public String toLowerCase(Locale locale) {
2493 return isLatin1() ? StringLatin1.toLowerCase(this, value, locale)
2494 : StringUTF16.toLowerCase(this, value, locale);
2495 }
2496
2497 /**
2498 * Converts all of the characters in this {@code String} to lower
2499 * case using the rules of the default locale. This is equivalent to calling
2500 * {@code toLowerCase(Locale.getDefault())}.
2501 * <p>
2502 * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2509 * LATIN SMALL LETTER DOTLESS I character.
2510 * To obtain correct results for locale insensitive strings, use
2511 * {@code toLowerCase(Locale.ROOT)}.
2512 *
2513 * @return the {@code String}, converted to lowercase.
2514 * @see java.lang.String#toLowerCase(Locale)
2515 */
2516 public String toLowerCase() {
2517 return toLowerCase(Locale.getDefault());
2518 }
2519
2520 /**
2521 * Converts all of the characters in this {@code String} to upper
2522 * case using the rules of the given {@code Locale}. Case mapping is based
2523 * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2524 * class. Since case mappings are not always 1:1 char mappings, the resulting
2525 * {@code String} may be a different length than the original {@code String}.
2526 * <p>
2527 * Examples of locale-sensitive and 1:M case mappings are in the following table.
2528 *
2529 * <table border="1" summary="Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description.">
2530 * <tr>
2531 * <th>Language Code of Locale</th>
2532 * <th>Lower Case</th>
2533 * <th>Upper Case</th>
2534 * <th>Description</th>
2535 * </tr>
2536 * <tr>
2537 * <td>tr (Turkish)</td>
2538 * <td>\u0069</td>
2539 * <td>\u0130</td>
2540 * <td>small letter i -> capital letter I with dot above</td>
2541 * </tr>
2542 * <tr>
2543 * <td>tr (Turkish)</td>
2544 * <td>\u0131</td>
2545 * <td>\u0049</td>
2546 * <td>small letter dotless i -> capital letter I</td>
2547 * </tr>
2548 * <tr>
2549 * <td>(all)</td>
2550 * <td>\u00df</td>
2551 * <td>\u0053 \u0053</td>
2552 * <td>small letter sharp s -> two letters: SS</td>
2553 * </tr>
2554 * <tr>
2555 * <td>(all)</td>
2556 * <td>Fahrvergnügen</td>
2557 * <td>FAHRVERGNÜGEN</td>
2558 * <td></td>
2559 * </tr>
2560 * </table>
2561 * @param locale use the case transformation rules for this locale
2562 * @return the {@code String}, converted to uppercase.
2563 * @see java.lang.String#toUpperCase()
2564 * @see java.lang.String#toLowerCase()
2565 * @see java.lang.String#toLowerCase(Locale)
2566 * @since 1.1
2567 */
2568 public String toUpperCase(Locale locale) {
2569 return isLatin1() ? StringLatin1.toUpperCase(this, value, locale)
2570 : StringUTF16.toUpperCase(this, value, locale);
2571 }
2572
2573 /**
2574 * Converts all of the characters in this {@code String} to upper
2575 * case using the rules of the default locale. This method is equivalent to
2576 * {@code toUpperCase(Locale.getDefault())}.
2577 * <p>
2578 * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2579 * results if used for strings that are intended to be interpreted locale
|
2186 *
2187 * <p> When there is a positive-width match at the beginning of this
2188 * string then an empty leading substring is included at the beginning
2189 * of the resulting array. A zero-width match at the beginning however
2190 * never produces such empty leading substring.
2191 *
2192 * <p> The {@code limit} parameter controls the number of times the
2193 * pattern is applied and therefore affects the length of the resulting
2194 * array. If the limit <i>n</i> is greater than zero then the pattern
2195 * will be applied at most <i>n</i> - 1 times, the array's
2196 * length will be no greater than <i>n</i>, and the array's last entry
2197 * will contain all input beyond the last matched delimiter. If <i>n</i>
2198 * is non-positive then the pattern will be applied as many times as
2199 * possible and the array can have any length. If <i>n</i> is zero then
2200 * the pattern will be applied as many times as possible, the array can
2201 * have any length, and trailing empty strings will be discarded.
2202 *
2203 * <p> The string {@code "boo:and:foo"}, for example, yields the
2204 * following results with these parameters:
2205 *
2206 * <blockquote><table class="plain">
2207 * <caption style="display:none">Split example showing regex, limit, and result</caption>
2208 * <thead>
2209 * <tr>
2210 * <th>Regex</th>
2211 * <th>Limit</th>
2212 * <th>Result</th>
2213 * </tr>
2214 * </thead>
2215 * <tbody>
2216 * <tr><td style="text-align:center">:</td>
2217 * <td style="text-align:center">2</td>
2218 * <td>{@code { "boo", "and:foo" }}</td></tr>
2219 * <tr><td style="text-align:center">:</td>
2220 * <td style="text-align:center">5</td>
2221 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2222 * <tr><td style="text-align:center">:</td>
2223 * <td style="text-align:center">-2</td>
2224 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2225 * <tr><td style="text-align:center">o</td>
2226 * <td style="text-align:center">5</td>
2227 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr>
2228 * <tr><td style="text-align:center">o</td>
2229 * <td style="text-align:center">-2</td>
2230 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr>
2231 * <tr><td style="text-align:center">o</td>
2232 * <td style="text-align:center">0</td>
2233 * <td>{@code { "b", "", ":and:f" }}</td></tr>
2234 * </tbody>
2235 * </table></blockquote>
2236 *
2237 * <p> An invocation of this method of the form
2238 * <i>str.</i>{@code split(}<i>regex</i>{@code ,} <i>n</i>{@code )}
2239 * yields the same result as the expression
2240 *
2241 * <blockquote>
2242 * <code>
2243 * {@link java.util.regex.Pattern}.{@link
2244 * java.util.regex.Pattern#compile compile}(<i>regex</i>).{@link
2245 * java.util.regex.Pattern#split(java.lang.CharSequence,int) split}(<i>str</i>, <i>n</i>)
2246 * </code>
2247 * </blockquote>
2248 *
2249 *
2250 * @param regex
2251 * the delimiting regular expression
2252 *
2253 * @param limit
2254 * the result threshold, as described above
2314 }
2315 }
2316 String[] result = new String[resultSize];
2317 return list.subList(0, resultSize).toArray(result);
2318 }
2319 return Pattern.compile(regex).split(this, limit);
2320 }
2321
2322 /**
2323 * Splits this string around matches of the given <a
2324 * href="../util/regex/Pattern.html#sum">regular expression</a>.
2325 *
2326 * <p> This method works as if by invoking the two-argument {@link
2327 * #split(String, int) split} method with the given expression and a limit
2328 * argument of zero. Trailing empty strings are therefore not included in
2329 * the resulting array.
2330 *
2331 * <p> The string {@code "boo:and:foo"}, for example, yields the following
2332 * results with these expressions:
2333 *
2334 * <blockquote><table class="plain">
2335 * <caption style="display:none">Split examples showing regex and result</caption>
2336 * <thead>
2337 * <tr>
2338 * <th>Regex</th>
2339 * <th>Result</th>
2340 * </tr>
2341 * </thead>
2342 * <tbody>
2343 * <tr><td style="text-align:center">:</td>
2344 * <td>{@code { "boo", "and", "foo" }}</td></tr>
2345 * <tr><td style="text-align:center">o</td>
2346 * <td>{@code { "b", "", ":and:f" }}</td></tr>
2347 * </tbody>
2348 * </table></blockquote>
2349 *
2350 *
2351 * @param regex
2352 * the delimiting regular expression
2353 *
2354 * @return the array of strings computed by splitting this string
2355 * around matches of the given regular expression
2356 *
2357 * @throws PatternSyntaxException
2358 * if the regular expression's syntax is invalid
2359 *
2360 * @see java.util.regex.Pattern
2361 *
2362 * @since 1.4
2363 * @spec JSR-51
2364 */
2365 public String[] split(String regex) {
2366 return split(regex, 0);
2367 }
2438 */
2439 public static String join(CharSequence delimiter,
2440 Iterable<? extends CharSequence> elements) {
2441 Objects.requireNonNull(delimiter);
2442 Objects.requireNonNull(elements);
2443 StringJoiner joiner = new StringJoiner(delimiter);
2444 for (CharSequence cs: elements) {
2445 joiner.add(cs);
2446 }
2447 return joiner.toString();
2448 }
2449
2450 /**
2451 * Converts all of the characters in this {@code String} to lower
2452 * case using the rules of the given {@code Locale}. Case mapping is based
2453 * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2454 * class. Since case mappings are not always 1:1 char mappings, the resulting
2455 * {@code String} may be a different length than the original {@code String}.
2456 * <p>
2457 * Examples of lowercase mappings are in the following table:
2458 * <table class="plain">
2459 * <caption style="display:none">Lowercase mapping examples showing language code of locale, upper case, lower case, and description</caption>
2460 * <thead>
2461 * <tr>
2462 * <th>Language Code of Locale</th>
2463 * <th>Upper Case</th>
2464 * <th>Lower Case</th>
2465 * <th>Description</th>
2466 * </tr>
2467 * </thead>
2468 * <tbody>
2469 * <tr>
2470 * <td>tr (Turkish)</td>
2471 * <td>\u0130</td>
2472 * <td>\u0069</td>
2473 * <td>capital letter I with dot above -> small letter i</td>
2474 * </tr>
2475 * <tr>
2476 * <td>tr (Turkish)</td>
2477 * <td>\u0049</td>
2478 * <td>\u0131</td>
2479 * <td>capital letter I -> small letter dotless i </td>
2480 * </tr>
2481 * <tr>
2482 * <td>(all)</td>
2483 * <td>French Fries</td>
2484 * <td>french fries</td>
2485 * <td>lowercased all chars in String</td>
2486 * </tr>
2487 * <tr>
2488 * <td>(all)</td>
2489 * <td><img src="doc-files/capiota.gif" alt="capiota"><img src="doc-files/capchi.gif" alt="capchi">
2490 * <img src="doc-files/captheta.gif" alt="captheta"><img src="doc-files/capupsil.gif" alt="capupsil">
2491 * <img src="doc-files/capsigma.gif" alt="capsigma"></td>
2492 * <td><img src="doc-files/iota.gif" alt="iota"><img src="doc-files/chi.gif" alt="chi">
2493 * <img src="doc-files/theta.gif" alt="theta"><img src="doc-files/upsilon.gif" alt="upsilon">
2494 * <img src="doc-files/sigma1.gif" alt="sigma"></td>
2495 * <td>lowercased all chars in String</td>
2496 * </tr>
2497 * </tbody>
2498 * </table>
2499 *
2500 * @param locale use the case transformation rules for this locale
2501 * @return the {@code String}, converted to lowercase.
2502 * @see java.lang.String#toLowerCase()
2503 * @see java.lang.String#toUpperCase()
2504 * @see java.lang.String#toUpperCase(Locale)
2505 * @since 1.1
2506 */
2507 public String toLowerCase(Locale locale) {
2508 return isLatin1() ? StringLatin1.toLowerCase(this, value, locale)
2509 : StringUTF16.toLowerCase(this, value, locale);
2510 }
2511
2512 /**
2513 * Converts all of the characters in this {@code String} to lower
2514 * case using the rules of the default locale. This is equivalent to calling
2515 * {@code toLowerCase(Locale.getDefault())}.
2516 * <p>
2517 * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2524 * LATIN SMALL LETTER DOTLESS I character.
2525 * To obtain correct results for locale insensitive strings, use
2526 * {@code toLowerCase(Locale.ROOT)}.
2527 *
2528 * @return the {@code String}, converted to lowercase.
2529 * @see java.lang.String#toLowerCase(Locale)
2530 */
2531 public String toLowerCase() {
2532 return toLowerCase(Locale.getDefault());
2533 }
2534
2535 /**
2536 * Converts all of the characters in this {@code String} to upper
2537 * case using the rules of the given {@code Locale}. Case mapping is based
2538 * on the Unicode Standard version specified by the {@link java.lang.Character Character}
2539 * class. Since case mappings are not always 1:1 char mappings, the resulting
2540 * {@code String} may be a different length than the original {@code String}.
2541 * <p>
2542 * Examples of locale-sensitive and 1:M case mappings are in the following table.
2543 *
2544 * <table class="plain">
2545 * <caption style="display:none">Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description.</caption>
2546 * <thead>
2547 * <tr>
2548 * <th>Language Code of Locale</th>
2549 * <th>Lower Case</th>
2550 * <th>Upper Case</th>
2551 * <th>Description</th>
2552 * </tr>
2553 * </thead>
2554 * <tbody>
2555 * <tr>
2556 * <td>tr (Turkish)</td>
2557 * <td>\u0069</td>
2558 * <td>\u0130</td>
2559 * <td>small letter i -> capital letter I with dot above</td>
2560 * </tr>
2561 * <tr>
2562 * <td>tr (Turkish)</td>
2563 * <td>\u0131</td>
2564 * <td>\u0049</td>
2565 * <td>small letter dotless i -> capital letter I</td>
2566 * </tr>
2567 * <tr>
2568 * <td>(all)</td>
2569 * <td>\u00df</td>
2570 * <td>\u0053 \u0053</td>
2571 * <td>small letter sharp s -> two letters: SS</td>
2572 * </tr>
2573 * <tr>
2574 * <td>(all)</td>
2575 * <td>Fahrvergnügen</td>
2576 * <td>FAHRVERGNÜGEN</td>
2577 * <td></td>
2578 * </tr>
2579 * </tbody>
2580 * </table>
2581 * @param locale use the case transformation rules for this locale
2582 * @return the {@code String}, converted to uppercase.
2583 * @see java.lang.String#toUpperCase()
2584 * @see java.lang.String#toLowerCase()
2585 * @see java.lang.String#toLowerCase(Locale)
2586 * @since 1.1
2587 */
2588 public String toUpperCase(Locale locale) {
2589 return isLatin1() ? StringLatin1.toUpperCase(this, value, locale)
2590 : StringUTF16.toUpperCase(this, value, locale);
2591 }
2592
2593 /**
2594 * Converts all of the characters in this {@code String} to upper
2595 * case using the rules of the default locale. This method is equivalent to
2596 * {@code toUpperCase(Locale.getDefault())}.
2597 * <p>
2598 * <b>Note:</b> This method is locale sensitive, and may produce unexpected
2599 * results if used for strings that are intended to be interpreted locale
|