1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 package java.lang; 27 28 import dalvik.annotation.optimization.FastNative; 29 import java.io.ObjectStreamField; 30 import java.io.UnsupportedEncodingException; 31 import java.lang.ArrayIndexOutOfBoundsException; 32 import java.nio.charset.Charset; 33 import java.nio.ByteBuffer; 34 import java.util.ArrayList; 35 import java.util.Arrays; 36 import java.util.Comparator; 37 import java.util.Formatter; 38 import java.util.Locale; 39 import java.util.Objects; 40 import java.util.StringJoiner; 41 import java.util.regex.Matcher; 42 import java.util.regex.Pattern; 43 import java.util.regex.PatternSyntaxException; 44 45 import libcore.util.CharsetUtils; 46 import libcore.util.EmptyArray; 47 48 /** 49 * The {@code String} class represents character strings. All 50 * string literals in Java programs, such as {@code "abc"}, are 51 * implemented as instances of this class. 52 * <p> 53 * Strings are constant; their values cannot be changed after they 54 * are created. String buffers support mutable strings. 55 * Because String objects are immutable they can be shared. For example: 56 * <blockquote><pre> 57 * String str = "abc"; 58 * </pre></blockquote><p> 59 * is equivalent to: 60 * <blockquote><pre> 61 * char data[] = {'a', 'b', 'c'}; 62 * String str = new String(data); 63 * </pre></blockquote><p> 64 * Here are some more examples of how strings can be used: 65 * <blockquote><pre> 66 * System.out.println("abc"); 67 * String cde = "cde"; 68 * System.out.println("abc" + cde); 69 * String c = "abc".substring(2,3); 70 * String d = cde.substring(1, 2); 71 * </pre></blockquote> 72 * <p> 73 * The class {@code String} includes methods for examining 74 * individual characters of the sequence, for comparing strings, for 75 * searching strings, for extracting substrings, and for creating a 76 * copy of a string with all characters translated to uppercase or to 77 * lowercase. Case mapping is based on the Unicode Standard version 78 * specified by the {@link java.lang.Character Character} class. 79 * <p> 80 * The Java language provides special support for the string 81 * concatenation operator ( + ), and for conversion of 82 * other objects to strings. String concatenation is implemented 83 * through the {@code StringBuilder}(or {@code StringBuffer}) 84 * class and its {@code append} method. 85 * String conversions are implemented through the method 86 * {@code toString}, defined by {@code Object} and 87 * inherited by all classes in Java. For additional information on 88 * string concatenation and conversion, see Gosling, Joy, and Steele, 89 * <i>The Java Language Specification</i>. 90 * 91 * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor 92 * or method in this class will cause a {@link NullPointerException} to be 93 * thrown. 94 * 95 * <p>A {@code String} represents a string in the UTF-16 format 96 * in which <em>supplementary characters</em> are represented by <em>surrogate 97 * pairs</em> (see the section <a href="Character.html#unicode">Unicode 98 * Character Representations</a> in the {@code Character} class for 99 * more information). 100 * Index values refer to {@code char} code units, so a supplementary 101 * character uses two positions in a {@code String}. 102 * <p>The {@code String} class provides methods for dealing with 103 * Unicode code points (i.e., characters), in addition to those for 104 * dealing with Unicode code units (i.e., {@code char} values). 105 * 106 * @author Lee Boynton 107 * @author Arthur van Hoff 108 * @author Martin Buchholz 109 * @author Ulf Zibis 110 * @see java.lang.Object#toString() 111 * @see java.lang.StringBuffer 112 * @see java.lang.StringBuilder 113 * @see java.nio.charset.Charset 114 * @since JDK1.0 115 */ 116 117 public final class String 118 implements java.io.Serializable, Comparable<String>, CharSequence { 119 120 // The associated character storage is managed by the runtime. We only 121 // keep track of the length here. 122 // 123 // private final char value[]; 124 private final int count; 125 126 /** Cache the hash code for the string */ 127 private int hash; // Default to 0 128 129 /** use serialVersionUID from JDK 1.0.2 for interoperability */ 130 private static final long serialVersionUID = -6849794470754667710L; 131 132 /** 133 * Class String is special cased within the Serialization Stream Protocol. 134 * 135 * A String instance is written into an ObjectOutputStream according to 136 * <a href="{@docRoot}/../platform/serialization/spec/output.html"> 137 * Object Serialization Specification, Section 6.2, "Stream Elements"</a> 138 */ 139 private static final ObjectStreamField[] serialPersistentFields = 140 new ObjectStreamField[0]; 141 142 /** 143 * Initializes a newly created {@code String} object so that it represents 144 * an empty character sequence. Note that use of this constructor is 145 * unnecessary since Strings are immutable. 146 */ 147 public String() { 148 throw new UnsupportedOperationException("Use StringFactory instead."); 149 } 150 151 /** 152 * Initializes a newly created {@code String} object so that it represents 153 * the same sequence of characters as the argument; in other words, the 154 * newly created string is a copy of the argument string. Unless an 155 * explicit copy of {@code original} is needed, use of this constructor is 156 * unnecessary since Strings are immutable. 157 * 158 * @param original 159 * A {@code String} 160 */ 161 public String(String original) { 162 throw new UnsupportedOperationException("Use StringFactory instead."); 163 } 164 165 /** 166 * Allocates a new {@code String} so that it represents the sequence of 167 * characters currently contained in the character array argument. The 168 * contents of the character array are copied; subsequent modification of 169 * the character array does not affect the newly created string. 170 * 171 * @param value 172 * The initial value of the string 173 */ 174 public String(char value[]) { 175 throw new UnsupportedOperationException("Use StringFactory instead."); 176 } 177 178 /** 179 * Allocates a new {@code String} that contains characters from a subarray 180 * of the character array argument. The {@code offset} argument is the 181 * index of the first character of the subarray and the {@code count} 182 * argument specifies the length of the subarray. The contents of the 183 * subarray are copied; subsequent modification of the character array does 184 * not affect the newly created string. 185 * 186 * @param value 187 * Array that is the source of characters 188 * 189 * @param offset 190 * The initial offset 191 * 192 * @param count 193 * The length 194 * 195 * @throws IndexOutOfBoundsException 196 * If the {@code offset} and {@code count} arguments index 197 * characters outside the bounds of the {@code value} array 198 */ 199 public String(char value[], int offset, int count) { 200 throw new UnsupportedOperationException("Use StringFactory instead."); 201 } 202 203 /** 204 * Allocates a new {@code String} that contains characters from a subarray 205 * of the <a href="Character.html#unicode">Unicode code point</a> array 206 * argument. The {@code offset} argument is the index of the first code 207 * point of the subarray and the {@code count} argument specifies the 208 * length of the subarray. The contents of the subarray are converted to 209 * {@code char}s; subsequent modification of the {@code int} array does not 210 * affect the newly created string. 211 * 212 * @param codePoints 213 * Array that is the source of Unicode code points 214 * 215 * @param offset 216 * The initial offset 217 * 218 * @param count 219 * The length 220 * 221 * @throws IllegalArgumentException 222 * If any invalid Unicode code point is found in {@code 223 * codePoints} 224 * 225 * @throws IndexOutOfBoundsException 226 * If the {@code offset} and {@code count} arguments index 227 * characters outside the bounds of the {@code codePoints} array 228 * 229 * @since 1.5 230 */ 231 public String(int[] codePoints, int offset, int count) { 232 throw new UnsupportedOperationException("Use StringFactory instead."); 233 } 234 235 /** 236 * Allocates a new {@code String} constructed from a subarray of an array 237 * of 8-bit integer values. 238 * 239 * <p> The {@code offset} argument is the index of the first byte of the 240 * subarray, and the {@code count} argument specifies the length of the 241 * subarray. 242 * 243 * <p> Each {@code byte} in the subarray is converted to a {@code char} as 244 * specified in the method above. 245 * 246 * @deprecated This method does not properly convert bytes into characters. 247 * As of JDK 1.1, the preferred way to do this is via the 248 * {@code String} constructors that take a {@link 249 * java.nio.charset.Charset}, charset name, or that use the platform's 250 * default charset. 251 * 252 * @param ascii 253 * The bytes to be converted to characters 254 * 255 * @param hibyte 256 * The top 8 bits of each 16-bit Unicode code unit 257 * 258 * @param offset 259 * The initial offset 260 * @param count 261 * The length 262 * 263 * @throws IndexOutOfBoundsException 264 * If the {@code offset} or {@code count} argument is invalid 265 * 266 * @see #String(byte[], int) 267 * @see #String(byte[], int, int, java.lang.String) 268 * @see #String(byte[], int, int, java.nio.charset.Charset) 269 * @see #String(byte[], int, int) 270 * @see #String(byte[], java.lang.String) 271 * @see #String(byte[], java.nio.charset.Charset) 272 * @see #String(byte[]) 273 */ 274 @Deprecated 275 public String(byte ascii[], int hibyte, int offset, int count) { 276 throw new UnsupportedOperationException("Use StringFactory instead."); 277 } 278 279 /** 280 * Allocates a new {@code String} containing characters constructed from 281 * an array of 8-bit integer values. Each character <i>c</i>in the 282 * resulting string is constructed from the corresponding component 283 * <i>b</i> in the byte array such that: 284 * 285 * <blockquote><pre> 286 * <b><i>c</i></b> == (char)(((hibyte & 0xff) << 8) 287 * | (<b><i>b</i></b> & 0xff)) 288 * </pre></blockquote> 289 * 290 * @deprecated This method does not properly convert bytes into 291 * characters. As of JDK 1.1, the preferred way to do this is via the 292 * {@code String} constructors that take a {@link 293 * java.nio.charset.Charset}, charset name, or that use the platform's 294 * default charset. 295 * 296 * @param ascii 297 * The bytes to be converted to characters 298 * 299 * @param hibyte 300 * The top 8 bits of each 16-bit Unicode code unit 301 * 302 * @see #String(byte[], int, int, java.lang.String) 303 * @see #String(byte[], int, int, java.nio.charset.Charset) 304 * @see #String(byte[], int, int) 305 * @see #String(byte[], java.lang.String) 306 * @see #String(byte[], java.nio.charset.Charset) 307 * @see #String(byte[]) 308 */ 309 @Deprecated 310 public String(byte ascii[], int hibyte) { 311 throw new UnsupportedOperationException("Use StringFactory instead."); 312 } 313 314 /** 315 * Constructs a new {@code String} by decoding the specified subarray of 316 * bytes using the specified charset. The length of the new {@code String} 317 * is a function of the charset, and hence may not be equal to the length 318 * of the subarray. 319 * 320 * <p> The behavior of this constructor when the given bytes are not valid 321 * in the given charset is unspecified. The {@link 322 * java.nio.charset.CharsetDecoder} class should be used when more control 323 * over the decoding process is required. 324 * 325 * @param bytes 326 * The bytes to be decoded into characters 327 * 328 * @param offset 329 * The index of the first byte to decode 330 * 331 * @param length 332 * The number of bytes to decode 333 334 * @param charsetName 335 * The name of a supported {@linkplain java.nio.charset.Charset 336 * charset} 337 * 338 * @throws UnsupportedEncodingException 339 * If the named charset is not supported 340 * 341 * @throws IndexOutOfBoundsException 342 * If the {@code offset} and {@code length} arguments index 343 * characters outside the bounds of the {@code bytes} array 344 * 345 * @since JDK1.1 346 */ 347 public String(byte bytes[], int offset, int length, String charsetName) 348 throws UnsupportedEncodingException { 349 throw new UnsupportedOperationException("Use StringFactory instead."); 350 } 351 352 /** 353 * Constructs a new {@code String} by decoding the specified subarray of 354 * bytes using the specified {@linkplain java.nio.charset.Charset charset}. 355 * The length of the new {@code String} is a function of the charset, and 356 * hence may not be equal to the length of the subarray. 357 * 358 * <p> This method always replaces malformed-input and unmappable-character 359 * sequences with this charset's default replacement string. The {@link 360 * java.nio.charset.CharsetDecoder} class should be used when more control 361 * over the decoding process is required. 362 * 363 * @param bytes 364 * The bytes to be decoded into characters 365 * 366 * @param offset 367 * The index of the first byte to decode 368 * 369 * @param length 370 * The number of bytes to decode 371 * 372 * @param charset 373 * The {@linkplain java.nio.charset.Charset charset} to be used to 374 * decode the {@code bytes} 375 * 376 * @throws IndexOutOfBoundsException 377 * If the {@code offset} and {@code length} arguments index 378 * characters outside the bounds of the {@code bytes} array 379 * 380 * @since 1.6 381 */ 382 public String(byte bytes[], int offset, int length, Charset charset) { 383 throw new UnsupportedOperationException("Use StringFactory instead."); 384 } 385 386 /** 387 * Constructs a new {@code String} by decoding the specified array of bytes 388 * using the specified {@linkplain java.nio.charset.Charset charset}. The 389 * length of the new {@code String} is a function of the charset, and hence 390 * may not be equal to the length of the byte array. 391 * 392 * <p> The behavior of this constructor when the given bytes are not valid 393 * in the given charset is unspecified. The {@link 394 * java.nio.charset.CharsetDecoder} class should be used when more control 395 * over the decoding process is required. 396 * 397 * @param bytes 398 * The bytes to be decoded into characters 399 * 400 * @param charsetName 401 * The name of a supported {@linkplain java.nio.charset.Charset 402 * charset} 403 * 404 * @throws UnsupportedEncodingException 405 * If the named charset is not supported 406 * 407 * @since JDK1.1 408 */ 409 public String(byte bytes[], String charsetName) 410 throws UnsupportedEncodingException { 411 throw new UnsupportedOperationException("Use StringFactory instead."); 412 } 413 414 /** 415 * Constructs a new {@code String} by decoding the specified array of 416 * bytes using the specified {@linkplain java.nio.charset.Charset charset}. 417 * The length of the new {@code String} is a function of the charset, and 418 * hence may not be equal to the length of the byte array. 419 * 420 * <p> This method always replaces malformed-input and unmappable-character 421 * sequences with this charset's default replacement string. The {@link 422 * java.nio.charset.CharsetDecoder} class should be used when more control 423 * over the decoding process is required. 424 * 425 * @param bytes 426 * The bytes to be decoded into characters 427 * 428 * @param charset 429 * The {@linkplain java.nio.charset.Charset charset} to be used to 430 * decode the {@code bytes} 431 * 432 * @since 1.6 433 */ 434 public String(byte bytes[], Charset charset) { 435 throw new UnsupportedOperationException("Use StringFactory instead."); 436 } 437 438 /** 439 * Constructs a new {@code String} by decoding the specified subarray of 440 * bytes using the platform's default charset. The length of the new 441 * {@code String} is a function of the charset, and hence may not be equal 442 * to the length of the subarray. 443 * 444 * <p> The behavior of this constructor when the given bytes are not valid 445 * in the default charset is unspecified. The {@link 446 * java.nio.charset.CharsetDecoder} class should be used when more control 447 * over the decoding process is required. 448 * 449 * @param bytes 450 * The bytes to be decoded into characters 451 * 452 * @param offset 453 * The index of the first byte to decode 454 * 455 * @param length 456 * The number of bytes to decode 457 * 458 * @throws IndexOutOfBoundsException 459 * If the {@code offset} and the {@code length} arguments index 460 * characters outside the bounds of the {@code bytes} array 461 * 462 * @since JDK1.1 463 */ 464 public String(byte bytes[], int offset, int length) { 465 throw new UnsupportedOperationException("Use StringFactory instead."); 466 } 467 468 /** 469 * Constructs a new {@code String} by decoding the specified array of bytes 470 * using the platform's default charset. The length of the new {@code 471 * String} is a function of the charset, and hence may not be equal to the 472 * length of the byte array. 473 * 474 * <p> The behavior of this constructor when the given bytes are not valid 475 * in the default charset is unspecified. The {@link 476 * java.nio.charset.CharsetDecoder} class should be used when more control 477 * over the decoding process is required. 478 * 479 * @param bytes 480 * The bytes to be decoded into characters 481 * 482 * @since JDK1.1 483 */ 484 public String(byte bytes[]) { 485 throw new UnsupportedOperationException("Use StringFactory instead."); 486 } 487 488 /** 489 * Allocates a new string that contains the sequence of characters 490 * currently contained in the string buffer argument. The contents of the 491 * string buffer are copied; subsequent modification of the string buffer 492 * does not affect the newly created string. 493 * 494 * @param buffer 495 * A {@code StringBuffer} 496 */ 497 public String(StringBuffer buffer) { 498 throw new UnsupportedOperationException("Use StringFactory instead."); 499 } 500 501 /** 502 * Allocates a new string that contains the sequence of characters 503 * currently contained in the string builder argument. The contents of the 504 * string builder are copied; subsequent modification of the string builder 505 * does not affect the newly created string. 506 * 507 * <p> This constructor is provided to ease migration to {@code 508 * StringBuilder}. Obtaining a string from a string builder via the {@code 509 * toString} method is likely to run faster and is generally preferred. 510 * 511 * @param builder 512 * A {@code StringBuilder} 513 * 514 * @since 1.5 515 */ 516 public String(StringBuilder builder) { 517 throw new UnsupportedOperationException("Use StringFactory instead."); 518 } 519 520 521 /** 522 * Package private constructor 523 * 524 * @deprecated Use {@link #String(char[],int,int)} instead. 525 */ 526 @Deprecated 527 String(int offset, int count, char[] value) { 528 throw new UnsupportedOperationException("Use StringFactory instead."); 529 } 530 531 /** 532 * Returns the length of this string. 533 * The length is equal to the number of <a href="Character.html#unicode">Unicode 534 * code units</a> in the string. 535 * 536 * @return the length of the sequence of characters represented by this 537 * object. 538 */ 539 public int length() { 540 final boolean STRING_COMPRESSION_ENABLED = true; 541 if (STRING_COMPRESSION_ENABLED) { 542 // For the compression purposes (save the characters as 8-bit if all characters 543 // are ASCII), the least significant bit of "count" is used as the compression flag. 544 return (count >>> 1); 545 } else { 546 return count; 547 } 548 } 549 550 /** 551 * Returns {@code true} if, and only if, {@link #length()} is {@code 0}. 552 * 553 * @return {@code true} if {@link #length()} is {@code 0}, otherwise 554 * {@code false} 555 * 556 * @since 1.6 557 */ 558 public boolean isEmpty() { 559 // Empty string has {@code count == 0} with or without string compression enabled. 560 return count == 0; 561 } 562 563 /** 564 * Returns the {@code char} value at the 565 * specified index. An index ranges from {@code 0} to 566 * {@code length() - 1}. The first {@code char} value of the sequence 567 * is at index {@code 0}, the next at index {@code 1}, 568 * and so on, as for array indexing. 569 * 570 * <p>If the {@code char} value specified by the index is a 571 * <a href="Character.html#unicode">surrogate</a>, the surrogate 572 * value is returned. 573 * 574 * @param index the index of the {@code char} value. 575 * @return the {@code char} value at the specified index of this string. 576 * The first {@code char} value is at index {@code 0}. 577 * @exception IndexOutOfBoundsException if the {@code index} 578 * argument is negative or not less than the length of this 579 * string. 580 */ 581 @FastNative 582 public native char charAt(int index); 583 584 /** 585 * Returns the character (Unicode code point) at the specified 586 * index. The index refers to {@code char} values 587 * (Unicode code units) and ranges from {@code 0} to 588 * {@link #length()}{@code - 1}. 589 * 590 * <p> If the {@code char} value specified at the given index 591 * is in the high-surrogate range, the following index is less 592 * than the length of this {@code String}, and the 593 * {@code char} value at the following index is in the 594 * low-surrogate range, then the supplementary code point 595 * corresponding to this surrogate pair is returned. Otherwise, 596 * the {@code char} value at the given index is returned 597 * 598 * @param index the index to the {@code char} values 599 * @return the code point value of the character at the 600 * {@code index} 601 * @exception IndexOutOfBoundsException if the {@code index} 602 * argument is negative or not less than the length of this 603 * string. 604 * @since 1.5 605 */ 606 public int codePointAt(int index) { 607 if ((index < 0) || (index >= length())) { 608 throw new StringIndexOutOfBoundsException(index); 609 } 610 return Character.codePointAt(this, index); 611 } 612 613 /** 614 * Returns the character (Unicode code point) before the specified 615 * index. The index refers to {@code char} values 616 * (Unicode code units) and ranges from {@code 1} to {@link 617 * CharSequence#length() length}. 618 * 619 * <p> If the {@code char} value at {@code (index - 1)} 620 * is in the low-surrogate range, {@code (index - 2)} is not 621 * negative, and the {@code char} value at {@code (index - 622 * 2)} is in the high-surrogate range, then the 623 * supplementary code point value of the surrogate pair is 624 * returned. If the {@code char} value at {@code index - 625 * 1} is an unpaired low-surrogate or a high-surrogate, the 626 * surrogate value is returned. 627 * 628 * @param index the index following the code point that should be returned 629 * @return the Unicode code point value before the given index. 630 * @exception IndexOutOfBoundsException if the {@code index} 631 * argument is less than 1 or greater than the length 632 * of this string. 633 * @since 1.5 634 */ 635 public int codePointBefore(int index) { 636 int i = index - 1; 637 if ((i < 0) || (i >= length())) { 638 throw new StringIndexOutOfBoundsException(index); 639 } 640 return Character.codePointBefore(this, index); 641 } 642 643 /** 644 * Returns the number of Unicode code points in the specified text 645 * range of this {@code String}. The text range begins at the 646 * specified {@code beginIndex} and extends to the 647 * {@code char} at index {@code endIndex - 1}. Thus the 648 * length (in {@code char}s) of the text range is 649 * {@code endIndex-beginIndex}. Unpaired surrogates within 650 * the text range count as one code point each. 651 * 652 * @param beginIndex the index to the first {@code char} of 653 * the text range. 654 * @param endIndex the index after the last {@code char} of 655 * the text range. 656 * @return the number of Unicode code points in the specified text 657 * range 658 * @exception IndexOutOfBoundsException if the 659 * {@code beginIndex} is negative, or {@code endIndex} 660 * is larger than the length of this {@code String}, or 661 * {@code beginIndex} is larger than {@code endIndex}. 662 * @since 1.5 663 */ 664 public int codePointCount(int beginIndex, int endIndex) { 665 if (beginIndex < 0 || endIndex > length() || beginIndex > endIndex) { 666 throw new IndexOutOfBoundsException(); 667 } 668 return Character.codePointCount(this, beginIndex, endIndex); 669 } 670 671 /** 672 * Returns the index within this {@code String} that is 673 * offset from the given {@code index} by 674 * {@code codePointOffset} code points. Unpaired surrogates 675 * within the text range given by {@code index} and 676 * {@code codePointOffset} count as one code point each. 677 * 678 * @param index the index to be offset 679 * @param codePointOffset the offset in code points 680 * @return the index within this {@code String} 681 * @exception IndexOutOfBoundsException if {@code index} 682 * is negative or larger then the length of this 683 * {@code String}, or if {@code codePointOffset} is positive 684 * and the substring starting with {@code index} has fewer 685 * than {@code codePointOffset} code points, 686 * or if {@code codePointOffset} is negative and the substring 687 * before {@code index} has fewer than the absolute value 688 * of {@code codePointOffset} code points. 689 * @since 1.5 690 */ 691 public int offsetByCodePoints(int index, int codePointOffset) { 692 if (index < 0 || index > length()) { 693 throw new IndexOutOfBoundsException(); 694 } 695 return Character.offsetByCodePoints(this, index, codePointOffset); 696 } 697 698 /** 699 * Copy characters from this string into dst starting at dstBegin. 700 * This method doesn't perform any range checking. 701 */ 702 void getChars(char dst[], int dstBegin) { 703 getCharsNoCheck(0, length(), dst, dstBegin); 704 } 705 706 /** 707 * Copies characters from this string into the destination character 708 * array. 709 * <p> 710 * The first character to be copied is at index {@code srcBegin}; 711 * the last character to be copied is at index {@code srcEnd-1} 712 * (thus the total number of characters to be copied is 713 * {@code srcEnd-srcBegin}). The characters are copied into the 714 * subarray of {@code dst} starting at index {@code dstBegin} 715 * and ending at index: 716 * <blockquote><pre> 717 * dstBegin + (srcEnd-srcBegin) - 1 718 * </pre></blockquote> 719 * 720 * @param srcBegin index of the first character in the string 721 * to copy. 722 * @param srcEnd index after the last character in the string 723 * to copy. 724 * @param dst the destination array. 725 * @param dstBegin the start offset in the destination array. 726 * @exception IndexOutOfBoundsException If any of the following 727 * is true: 728 * <ul><li>{@code srcBegin} is negative. 729 * <li>{@code srcBegin} is greater than {@code srcEnd} 730 * <li>{@code srcEnd} is greater than the length of this 731 * string 732 * <li>{@code dstBegin} is negative 733 * <li>{@code dstBegin+(srcEnd-srcBegin)} is larger than 734 * {@code dst.length}</ul> 735 */ 736 public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) { 737 if (dst == null) { 738 throw new NullPointerException("dst == null"); 739 } 740 741 if (srcBegin < 0) { 742 throw new StringIndexOutOfBoundsException(this, srcBegin); 743 } 744 if (srcEnd > length()) { 745 throw new StringIndexOutOfBoundsException(this, srcEnd); 746 } 747 748 int n = srcEnd - srcBegin; 749 if (srcEnd < srcBegin) { 750 throw new StringIndexOutOfBoundsException(this, srcBegin, n); 751 } 752 753 if (dstBegin < 0) { 754 throw new ArrayIndexOutOfBoundsException("dstBegin < 0. dstBegin=" + dstBegin); 755 } 756 // dstBegin can be equal to dst.length, but only in the case where zero chars are to be 757 // copied. 758 if (dstBegin > dst.length) { 759 throw new ArrayIndexOutOfBoundsException( 760 "dstBegin > dst.length. dstBegin=" + dstBegin + ", dst.length=" + dst.length); 761 } 762 if (n > dst.length - dstBegin) { 763 throw new ArrayIndexOutOfBoundsException( 764 "n > dst.length - dstBegin. n=" + n + ", dst.length=" + dst.length 765 + "dstBegin=" + dstBegin); 766 } 767 768 getCharsNoCheck(srcBegin, srcEnd, dst, dstBegin); 769 } 770 771 /** 772 * getChars without bounds checks, for use by other classes 773 * within the java.lang package only. The caller is responsible for 774 * ensuring that start >= 0 && start <= end && end <= count. 775 */ 776 @FastNative 777 native void getCharsNoCheck(int start, int end, char[] buffer, int index); 778 779 780 /** 781 * Copies characters from this string into the destination byte array. Each 782 * byte receives the 8 low-order bits of the corresponding character. The 783 * eight high-order bits of each character are not copied and do not 784 * participate in the transfer in any way. 785 * 786 * <p> The first character to be copied is at index {@code srcBegin}; the 787 * last character to be copied is at index {@code srcEnd-1}. The total 788 * number of characters to be copied is {@code srcEnd-srcBegin}. The 789 * characters, converted to bytes, are copied into the subarray of {@code 790 * dst} starting at index {@code dstBegin} and ending at index: 791 * 792 * <blockquote><pre> 793 * dstBegin + (srcEnd-srcBegin) - 1 794 * </pre></blockquote> 795 * 796 * @deprecated This method does not properly convert characters into 797 * bytes. As of JDK 1.1, the preferred way to do this is via the 798 * {@link #getBytes()} method, which uses the platform's default charset. 799 * 800 * @param srcBegin 801 * Index of the first character in the string to copy 802 * 803 * @param srcEnd 804 * Index after the last character in the string to copy 805 * 806 * @param dst 807 * The destination array 808 * 809 * @param dstBegin 810 * The start offset in the destination array 811 * 812 * @throws IndexOutOfBoundsException 813 * If any of the following is true: 814 * <ul> 815 * <li> {@code srcBegin} is negative 816 * <li> {@code srcBegin} is greater than {@code srcEnd} 817 * <li> {@code srcEnd} is greater than the length of this String 818 * <li> {@code dstBegin} is negative 819 * <li> {@code dstBegin+(srcEnd-srcBegin)} is larger than {@code 820 * dst.length} 821 * </ul> 822 */ 823 @Deprecated 824 public void getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin) { 825 if (srcBegin < 0) { 826 throw new StringIndexOutOfBoundsException(this, srcBegin); 827 } 828 if (srcEnd > length()) { 829 throw new StringIndexOutOfBoundsException(this, srcEnd); 830 } 831 if (srcBegin > srcEnd) { 832 throw new StringIndexOutOfBoundsException(this, (srcEnd - srcBegin)); 833 } 834 835 int j = dstBegin; 836 int n = srcEnd; 837 int i = srcBegin; 838 839 while (i < n) { 840 dst[j++] = (byte)charAt(i++); 841 } 842 } 843 844 /** 845 * Encodes this {@code String} into a sequence of bytes using the named 846 * charset, storing the result into a new byte array. 847 * 848 * <p> The behavior of this method when this string cannot be encoded in 849 * the given charset is unspecified. The {@link 850 * java.nio.charset.CharsetEncoder} class should be used when more control 851 * over the encoding process is required. 852 * 853 * @param charsetName 854 * The name of a supported {@linkplain java.nio.charset.Charset 855 * charset} 856 * 857 * @return The resultant byte array 858 * 859 * @throws UnsupportedEncodingException 860 * If the named charset is not supported 861 * 862 * @since JDK1.1 863 */ 864 public byte[] getBytes(String charsetName) 865 throws UnsupportedEncodingException { 866 if (charsetName == null) throw new NullPointerException(); 867 return getBytes(Charset.forNameUEE(charsetName)); 868 } 869 870 /** 871 * Encodes this {@code String} into a sequence of bytes using the given 872 * {@linkplain java.nio.charset.Charset charset}, storing the result into a 873 * new byte array. 874 * 875 * <p> This method always replaces malformed-input and unmappable-character 876 * sequences with this charset's default replacement byte array. The 877 * {@link java.nio.charset.CharsetEncoder} class should be used when more 878 * control over the encoding process is required. 879 * 880 * @param charset 881 * The {@linkplain java.nio.charset.Charset} to be used to encode 882 * the {@code String} 883 * 884 * @return The resultant byte array 885 * 886 * @since 1.6 887 */ 888 public byte[] getBytes(Charset charset) { 889 if (charset == null) { 890 throw new NullPointerException("charset == null"); 891 } 892 893 final int len = length(); 894 final String name = charset.name(); 895 if ("UTF-8".equals(name)) { 896 return CharsetUtils.toUtf8Bytes(this, 0, len); 897 } else if ("ISO-8859-1".equals(name)) { 898 return CharsetUtils.toIsoLatin1Bytes(this, 0, len); 899 } else if ("US-ASCII".equals(name)) { 900 return CharsetUtils.toAsciiBytes(this, 0, len); 901 } else if ("UTF-16BE".equals(name)) { 902 return CharsetUtils.toBigEndianUtf16Bytes(this, 0, len); 903 } 904 905 ByteBuffer buffer = charset.encode(this); 906 byte[] bytes = new byte[buffer.limit()]; 907 buffer.get(bytes); 908 return bytes; 909 } 910 911 /** 912 * Encodes this {@code String} into a sequence of bytes using the 913 * platform's default charset, storing the result into a new byte array. 914 * 915 * <p> The behavior of this method when this string cannot be encoded in 916 * the default charset is unspecified. The {@link 917 * java.nio.charset.CharsetEncoder} class should be used when more control 918 * over the encoding process is required. 919 * 920 * @return The resultant byte array 921 * 922 * @since JDK1.1 923 */ 924 public byte[] getBytes() { 925 return getBytes(Charset.defaultCharset()); 926 } 927 928 /** 929 * Compares this string to the specified object. The result is {@code 930 * true} if and only if the argument is not {@code null} and is a {@code 931 * String} object that represents the same sequence of characters as this 932 * object. 933 * 934 * @param anObject 935 * The object to compare this {@code String} against 936 * 937 * @return {@code true} if the given object represents a {@code String} 938 * equivalent to this string, {@code false} otherwise 939 * 940 * @see #compareTo(String) 941 * @see #equalsIgnoreCase(String) 942 */ 943 public boolean equals(Object anObject) { 944 if (this == anObject) { 945 return true; 946 } 947 if (anObject instanceof String) { 948 String anotherString = (String) anObject; 949 int n = length(); 950 if (n == anotherString.length()) { 951 int i = 0; 952 while (n-- != 0) { 953 if (charAt(i) != anotherString.charAt(i)) 954 return false; 955 i++; 956 } 957 return true; 958 } 959 } 960 return false; 961 } 962 963 /** 964 * Compares this string to the specified {@code StringBuffer}. The result 965 * is {@code true} if and only if this {@code String} represents the same 966 * sequence of characters as the specified {@code StringBuffer}. This method 967 * synchronizes on the {@code StringBuffer}. 968 * 969 * @param sb 970 * The {@code StringBuffer} to compare this {@code String} against 971 * 972 * @return {@code true} if this {@code String} represents the same 973 * sequence of characters as the specified {@code StringBuffer}, 974 * {@code false} otherwise 975 * 976 * @since 1.4 977 */ 978 public boolean contentEquals(StringBuffer sb) { 979 return contentEquals((CharSequence)sb); 980 } 981 982 private boolean nonSyncContentEquals(AbstractStringBuilder sb) { 983 char v2[] = sb.getValue(); 984 int n = length(); 985 if (n != sb.length()) { 986 return false; 987 } 988 for (int i = 0; i < n; i++) { 989 if (charAt(i) != v2[i]) { 990 return false; 991 } 992 } 993 return true; 994 } 995 996 /** 997 * Compares this string to the specified {@code CharSequence}. The 998 * result is {@code true} if and only if this {@code String} represents the 999 * same sequence of char values as the specified sequence. Note that if the 1000 * {@code CharSequence} is a {@code StringBuffer} then the method 1001 * synchronizes on it. 1002 * 1003 * @param cs 1004 * The sequence to compare this {@code String} against 1005 * 1006 * @return {@code true} if this {@code String} represents the same 1007 * sequence of char values as the specified sequence, {@code 1008 * false} otherwise 1009 * 1010 * @since 1.5 1011 */ 1012 public boolean contentEquals(CharSequence cs) { 1013 // Argument is a StringBuffer, StringBuilder 1014 if (cs instanceof AbstractStringBuilder) { 1015 if (cs instanceof StringBuffer) { 1016 synchronized(cs) { 1017 return nonSyncContentEquals((AbstractStringBuilder)cs); 1018 } 1019 } else { 1020 return nonSyncContentEquals((AbstractStringBuilder)cs); 1021 } 1022 } 1023 // Argument is a String 1024 if (cs instanceof String) { 1025 return equals(cs); 1026 } 1027 // Argument is a generic CharSequence 1028 int n = length(); 1029 if (n != cs.length()) { 1030 return false; 1031 } 1032 for (int i = 0; i < n; i++) { 1033 if (charAt(i) != cs.charAt(i)) { 1034 return false; 1035 } 1036 } 1037 return true; 1038 } 1039 1040 /** 1041 * Compares this {@code String} to another {@code String}, ignoring case 1042 * considerations. Two strings are considered equal ignoring case if they 1043 * are of the same length and corresponding characters in the two strings 1044 * are equal ignoring case. 1045 * 1046 * <p> Two characters {@code c1} and {@code c2} are considered the same 1047 * ignoring case if at least one of the following is true: 1048 * <ul> 1049 * <li> The two characters are the same (as compared by the 1050 * {@code ==} operator) 1051 * <li> Applying the method {@link 1052 * java.lang.Character#toUpperCase(char)} to each character 1053 * produces the same result 1054 * <li> Applying the method {@link 1055 * java.lang.Character#toLowerCase(char)} to each character 1056 * produces the same result 1057 * </ul> 1058 * 1059 * @param anotherString 1060 * The {@code String} to compare this {@code String} against 1061 * 1062 * @return {@code true} if the argument is not {@code null} and it 1063 * represents an equivalent {@code String} ignoring case; {@code 1064 * false} otherwise 1065 * 1066 * @see #equals(Object) 1067 */ 1068 public boolean equalsIgnoreCase(String anotherString) { 1069 final int len = length(); 1070 return (this == anotherString) ? true 1071 : (anotherString != null) 1072 && (anotherString.length() == len) 1073 && regionMatches(true, 0, anotherString, 0, len); 1074 } 1075 1076 /** 1077 * Compares two strings lexicographically. 1078 * The comparison is based on the Unicode value of each character in 1079 * the strings. The character sequence represented by this 1080 * {@code String} object is compared lexicographically to the 1081 * character sequence represented by the argument string. The result is 1082 * a negative integer if this {@code String} object 1083 * lexicographically precedes the argument string. The result is a 1084 * positive integer if this {@code String} object lexicographically 1085 * follows the argument string. The result is zero if the strings 1086 * are equal; {@code compareTo} returns {@code 0} exactly when 1087 * the {@link #equals(Object)} method would return {@code true}. 1088 * <p> 1089 * This is the definition of lexicographic ordering. If two strings are 1090 * different, then either they have different characters at some index 1091 * that is a valid index for both strings, or their lengths are different, 1092 * or both. If they have different characters at one or more index 1093 * positions, let <i>k</i> be the smallest such index; then the string 1094 * whose character at position <i>k</i> has the smaller value, as 1095 * determined by using the < operator, lexicographically precedes the 1096 * other string. In this case, {@code compareTo} returns the 1097 * difference of the two character values at position {@code k} in 1098 * the two string -- that is, the value: 1099 * <blockquote><pre> 1100 * this.charAt(k)-anotherString.charAt(k) 1101 * </pre></blockquote> 1102 * If there is no index position at which they differ, then the shorter 1103 * string lexicographically precedes the longer string. In this case, 1104 * {@code compareTo} returns the difference of the lengths of the 1105 * strings -- that is, the value: 1106 * <blockquote><pre> 1107 * this.length()-anotherString.length() 1108 * </pre></blockquote> 1109 * 1110 * @param anotherString the {@code String} to be compared. 1111 * @return the value {@code 0} if the argument string is equal to 1112 * this string; a value less than {@code 0} if this string 1113 * is lexicographically less than the string argument; and a 1114 * value greater than {@code 0} if this string is 1115 * lexicographically greater than the string argument. 1116 */ 1117 @FastNative 1118 public native int compareTo(String anotherString); 1119 1120 /** 1121 * A Comparator that orders {@code String} objects as by 1122 * {@code compareToIgnoreCase}. This comparator is serializable. 1123 * <p> 1124 * Note that this Comparator does <em>not</em> take locale into account, 1125 * and will result in an unsatisfactory ordering for certain locales. 1126 * The java.text package provides <em>Collators</em> to allow 1127 * locale-sensitive ordering. 1128 * 1129 * @see java.text.Collator#compare(String, String) 1130 * @since 1.2 1131 */ 1132 public static final Comparator<String> CASE_INSENSITIVE_ORDER 1133 = new CaseInsensitiveComparator(); 1134 private static class CaseInsensitiveComparator 1135 implements Comparator<String>, java.io.Serializable { 1136 // use serialVersionUID from JDK 1.2.2 for interoperability 1137 private static final long serialVersionUID = 8575799808933029326L; 1138 1139 public int compare(String s1, String s2) { 1140 int n1 = s1.length(); 1141 int n2 = s2.length(); 1142 int min = Math.min(n1, n2); 1143 for (int i = 0; i < min; i++) { 1144 char c1 = s1.charAt(i); 1145 char c2 = s2.charAt(i); 1146 if (c1 != c2) { 1147 c1 = Character.toUpperCase(c1); 1148 c2 = Character.toUpperCase(c2); 1149 if (c1 != c2) { 1150 c1 = Character.toLowerCase(c1); 1151 c2 = Character.toLowerCase(c2); 1152 if (c1 != c2) { 1153 // No overflow because of numeric promotion 1154 return c1 - c2; 1155 } 1156 } 1157 } 1158 } 1159 return n1 - n2; 1160 } 1161 1162 /** Replaces the de-serialized object. */ 1163 private Object readResolve() { return CASE_INSENSITIVE_ORDER; } 1164 } 1165 1166 /** 1167 * Compares two strings lexicographically, ignoring case 1168 * differences. This method returns an integer whose sign is that of 1169 * calling {@code compareTo} with normalized versions of the strings 1170 * where case differences have been eliminated by calling 1171 * {@code Character.toLowerCase(Character.toUpperCase(character))} on 1172 * each character. 1173 * <p> 1174 * Note that this method does <em>not</em> take locale into account, 1175 * and will result in an unsatisfactory ordering for certain locales. 1176 * The java.text package provides <em>collators</em> to allow 1177 * locale-sensitive ordering. 1178 * 1179 * @param str the {@code String} to be compared. 1180 * @return a negative integer, zero, or a positive integer as the 1181 * specified String is greater than, equal to, or less 1182 * than this String, ignoring case considerations. 1183 * @see java.text.Collator#compare(String, String) 1184 * @since 1.2 1185 */ 1186 public int compareToIgnoreCase(String str) { 1187 return CASE_INSENSITIVE_ORDER.compare(this, str); 1188 } 1189 1190 /** 1191 * Tests if two string regions are equal. 1192 * <p> 1193 * A substring of this {@code String} object is compared to a substring 1194 * of the argument other. The result is true if these substrings 1195 * represent identical character sequences. The substring of this 1196 * {@code String} object to be compared begins at index {@code toffset} 1197 * and has length {@code len}. The substring of other to be compared 1198 * begins at index {@code ooffset} and has length {@code len}. The 1199 * result is {@code false} if and only if at least one of the following 1200 * is true: 1201 * <ul><li>{@code toffset} is negative. 1202 * <li>{@code ooffset} is negative. 1203 * <li>{@code toffset+len} is greater than the length of this 1204 * {@code String} object. 1205 * <li>{@code ooffset+len} is greater than the length of the other 1206 * argument. 1207 * <li>There is some nonnegative integer <i>k</i> less than {@code len} 1208 * such that: 1209 * {@code this.charAt(toffset + }<i>k</i>{@code ) != other.charAt(ooffset + } 1210 * <i>k</i>{@code )} 1211 * </ul> 1212 * 1213 * @param toffset the starting offset of the subregion in this string. 1214 * @param other the string argument. 1215 * @param ooffset the starting offset of the subregion in the string 1216 * argument. 1217 * @param len the number of characters to compare. 1218 * @return {@code true} if the specified subregion of this string 1219 * exactly matches the specified subregion of the string argument; 1220 * {@code false} otherwise. 1221 */ 1222 public boolean regionMatches(int toffset, String other, int ooffset, 1223 int len) { 1224 int to = toffset; 1225 int po = ooffset; 1226 // Note: toffset, ooffset, or len might be near -1>>>1. 1227 if ((ooffset < 0) || (toffset < 0) 1228 || (toffset > (long)length() - len) 1229 || (ooffset > (long)other.length() - len)) { 1230 return false; 1231 } 1232 while (len-- > 0) { 1233 if (charAt(to++) != other.charAt(po++)) { 1234 return false; 1235 } 1236 } 1237 return true; 1238 } 1239 1240 /** 1241 * Tests if two string regions are equal. 1242 * <p> 1243 * A substring of this {@code String} object is compared to a substring 1244 * of the argument {@code other}. The result is {@code true} if these 1245 * substrings represent character sequences that are the same, ignoring 1246 * case if and only if {@code ignoreCase} is true. The substring of 1247 * this {@code String} object to be compared begins at index 1248 * {@code toffset} and has length {@code len}. The substring of 1249 * {@code other} to be compared begins at index {@code ooffset} and 1250 * has length {@code len}. The result is {@code false} if and only if 1251 * at least one of the following is true: 1252 * <ul><li>{@code toffset} is negative. 1253 * <li>{@code ooffset} is negative. 1254 * <li>{@code toffset+len} is greater than the length of this 1255 * {@code String} object. 1256 * <li>{@code ooffset+len} is greater than the length of the other 1257 * argument. 1258 * <li>{@code ignoreCase} is {@code false} and there is some nonnegative 1259 * integer <i>k</i> less than {@code len} such that: 1260 * <blockquote><pre> 1261 * this.charAt(toffset+k) != other.charAt(ooffset+k) 1262 * </pre></blockquote> 1263 * <li>{@code ignoreCase} is {@code true} and there is some nonnegative 1264 * integer <i>k</i> less than {@code len} such that: 1265 * <blockquote><pre> 1266 * Character.toLowerCase(this.charAt(toffset+k)) != 1267 Character.toLowerCase(other.charAt(ooffset+k)) 1268 * </pre></blockquote> 1269 * and: 1270 * <blockquote><pre> 1271 * Character.toUpperCase(this.charAt(toffset+k)) != 1272 * Character.toUpperCase(other.charAt(ooffset+k)) 1273 * </pre></blockquote> 1274 * </ul> 1275 * 1276 * @param ignoreCase if {@code true}, ignore case when comparing 1277 * characters. 1278 * @param toffset the starting offset of the subregion in this 1279 * string. 1280 * @param other the string argument. 1281 * @param ooffset the starting offset of the subregion in the string 1282 * argument. 1283 * @param len the number of characters to compare. 1284 * @return {@code true} if the specified subregion of this string 1285 * matches the specified subregion of the string argument; 1286 * {@code false} otherwise. Whether the matching is exact 1287 * or case insensitive depends on the {@code ignoreCase} 1288 * argument. 1289 */ 1290 public boolean regionMatches(boolean ignoreCase, int toffset, 1291 String other, int ooffset, int len) { 1292 int to = toffset; 1293 int po = ooffset; 1294 // Note: toffset, ooffset, or len might be near -1>>>1. 1295 if ((ooffset < 0) || (toffset < 0) 1296 || (toffset > (long)length() - len) 1297 || (ooffset > (long)other.length() - len)) { 1298 return false; 1299 } 1300 while (len-- > 0) { 1301 char c1 = charAt(to++); 1302 char c2 = other.charAt(po++); 1303 if (c1 == c2) { 1304 continue; 1305 } 1306 if (ignoreCase) { 1307 // If characters don't match but case may be ignored, 1308 // try converting both characters to uppercase. 1309 // If the results match, then the comparison scan should 1310 // continue. 1311 char u1 = Character.toUpperCase(c1); 1312 char u2 = Character.toUpperCase(c2); 1313 if (u1 == u2) { 1314 continue; 1315 } 1316 // Unfortunately, conversion to uppercase does not work properly 1317 // for the Georgian alphabet, which has strange rules about case 1318 // conversion. So we need to make one last check before 1319 // exiting. 1320 if (Character.toLowerCase(u1) == Character.toLowerCase(u2)) { 1321 continue; 1322 } 1323 } 1324 return false; 1325 } 1326 return true; 1327 } 1328 1329 /** 1330 * Tests if the substring of this string beginning at the 1331 * specified index starts with the specified prefix. 1332 * 1333 * @param prefix the prefix. 1334 * @param toffset where to begin looking in this string. 1335 * @return {@code true} if the character sequence represented by the 1336 * argument is a prefix of the substring of this object starting 1337 * at index {@code toffset}; {@code false} otherwise. 1338 * The result is {@code false} if {@code toffset} is 1339 * negative or greater than the length of this 1340 * {@code String} object; otherwise the result is the same 1341 * as the result of the expression 1342 * <pre> 1343 * this.substring(toffset).startsWith(prefix) 1344 * </pre> 1345 */ 1346 public boolean startsWith(String prefix, int toffset) { 1347 int to = toffset; 1348 int po = 0; 1349 int pc = prefix.length(); 1350 // Note: toffset might be near -1>>>1. 1351 if ((toffset < 0) || (toffset > length() - pc)) { 1352 return false; 1353 } 1354 while (--pc >= 0) { 1355 if (charAt(to++) != prefix.charAt(po++)) { 1356 return false; 1357 } 1358 } 1359 return true; 1360 } 1361 1362 /** 1363 * Tests if this string starts with the specified prefix. 1364 * 1365 * @param prefix the prefix. 1366 * @return {@code true} if the character sequence represented by the 1367 * argument is a prefix of the character sequence represented by 1368 * this string; {@code false} otherwise. 1369 * Note also that {@code true} will be returned if the 1370 * argument is an empty string or is equal to this 1371 * {@code String} object as determined by the 1372 * {@link #equals(Object)} method. 1373 * @since 1. 0 1374 */ 1375 public boolean startsWith(String prefix) { 1376 return startsWith(prefix, 0); 1377 } 1378 1379 /** 1380 * Tests if this string ends with the specified suffix. 1381 * 1382 * @param suffix the suffix. 1383 * @return {@code true} if the character sequence represented by the 1384 * argument is a suffix of the character sequence represented by 1385 * this object; {@code false} otherwise. Note that the 1386 * result will be {@code true} if the argument is the 1387 * empty string or is equal to this {@code String} object 1388 * as determined by the {@link #equals(Object)} method. 1389 */ 1390 public boolean endsWith(String suffix) { 1391 return startsWith(suffix, length() - suffix.length()); 1392 } 1393 1394 /** 1395 * Returns a hash code for this string. The hash code for a 1396 * {@code String} object is computed as 1397 * <blockquote><pre> 1398 * s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] 1399 * </pre></blockquote> 1400 * using {@code int} arithmetic, where {@code s[i]} is the 1401 * <i>i</i>th character of the string, {@code n} is the length of 1402 * the string, and {@code ^} indicates exponentiation. 1403 * (The hash value of the empty string is zero.) 1404 * 1405 * @return a hash code value for this object. 1406 */ 1407 public int hashCode() { 1408 int h = hash; 1409 final int len = length(); 1410 if (h == 0 && len > 0) { 1411 for (int i = 0; i < len; i++) { 1412 h = 31 * h + charAt(i); 1413 } 1414 hash = h; 1415 } 1416 return h; 1417 } 1418 1419 /** 1420 * Returns the index within this string of the first occurrence of 1421 * the specified character. If a character with value 1422 * {@code ch} occurs in the character sequence represented by 1423 * this {@code String} object, then the index (in Unicode 1424 * code units) of the first such occurrence is returned. For 1425 * values of {@code ch} in the range from 0 to 0xFFFF 1426 * (inclusive), this is the smallest value <i>k</i> such that: 1427 * <blockquote><pre> 1428 * this.charAt(<i>k</i>) == ch 1429 * </pre></blockquote> 1430 * is true. For other values of {@code ch}, it is the 1431 * smallest value <i>k</i> such that: 1432 * <blockquote><pre> 1433 * this.codePointAt(<i>k</i>) == ch 1434 * </pre></blockquote> 1435 * is true. In either case, if no such character occurs in this 1436 * string, then {@code -1} is returned. 1437 * 1438 * @param ch a character (Unicode code point). 1439 * @return the index of the first occurrence of the character in the 1440 * character sequence represented by this object, or 1441 * {@code -1} if the character does not occur. 1442 */ 1443 public int indexOf(int ch) { 1444 return indexOf(ch, 0); 1445 } 1446 1447 /** 1448 * Returns the index within this string of the first occurrence of the 1449 * specified character, starting the search at the specified index. 1450 * <p> 1451 * If a character with value {@code ch} occurs in the 1452 * character sequence represented by this {@code String} 1453 * object at an index no smaller than {@code fromIndex}, then 1454 * the index of the first such occurrence is returned. For values 1455 * of {@code ch} in the range from 0 to 0xFFFF (inclusive), 1456 * this is the smallest value <i>k</i> such that: 1457 * <blockquote><pre> 1458 * (this.charAt(<i>k</i>) == ch) {@code &&} (<i>k</i> >= fromIndex) 1459 * </pre></blockquote> 1460 * is true. For other values of {@code ch}, it is the 1461 * smallest value <i>k</i> such that: 1462 * <blockquote><pre> 1463 * (this.codePointAt(<i>k</i>) == ch) {@code &&} (<i>k</i> >= fromIndex) 1464 * </pre></blockquote> 1465 * is true. In either case, if no such character occurs in this 1466 * string at or after position {@code fromIndex}, then 1467 * {@code -1} is returned. 1468 * 1469 * <p> 1470 * There is no restriction on the value of {@code fromIndex}. If it 1471 * is negative, it has the same effect as if it were zero: this entire 1472 * string may be searched. If it is greater than the length of this 1473 * string, it has the same effect as if it were equal to the length of 1474 * this string: {@code -1} is returned. 1475 * 1476 * <p>All indices are specified in {@code char} values 1477 * (Unicode code units). 1478 * 1479 * @param ch a character (Unicode code point). 1480 * @param fromIndex the index to start the search from. 1481 * @return the index of the first occurrence of the character in the 1482 * character sequence represented by this object that is greater 1483 * than or equal to {@code fromIndex}, or {@code -1} 1484 * if the character does not occur. 1485 */ 1486 public int indexOf(int ch, int fromIndex) { 1487 final int max = length(); 1488 if (fromIndex < 0) { 1489 fromIndex = 0; 1490 } else if (fromIndex >= max) { 1491 // Note: fromIndex might be near -1>>>1. 1492 return -1; 1493 } 1494 1495 if (ch < Character.MIN_SUPPLEMENTARY_CODE_POINT) { 1496 // handle most cases here (ch is a BMP code point or a 1497 // negative value (invalid code point)) 1498 for (int i = fromIndex; i < max; i++) { 1499 if (charAt(i) == ch) { 1500 return i; 1501 } 1502 } 1503 return -1; 1504 } else { 1505 return indexOfSupplementary(ch, fromIndex); 1506 } 1507 } 1508 1509 @FastNative 1510 private native int fastIndexOf(int c, int start); 1511 1512 /** 1513 * Handles (rare) calls of indexOf with a supplementary character. 1514 */ 1515 private int indexOfSupplementary(int ch, int fromIndex) { 1516 if (Character.isValidCodePoint(ch)) { 1517 final char hi = Character.highSurrogate(ch); 1518 final char lo = Character.lowSurrogate(ch); 1519 final int max = length() - 1; 1520 for (int i = fromIndex; i < max; i++) { 1521 if (charAt(i) == hi && charAt(i + 1) == lo) { 1522 return i; 1523 } 1524 } 1525 } 1526 return -1; 1527 } 1528 1529 /** 1530 * Returns the index within this string of the last occurrence of 1531 * the specified character. For values of {@code ch} in the 1532 * range from 0 to 0xFFFF (inclusive), the index (in Unicode code 1533 * units) returned is the largest value <i>k</i> such that: 1534 * <blockquote><pre> 1535 * this.charAt(<i>k</i>) == ch 1536 * </pre></blockquote> 1537 * is true. For other values of {@code ch}, it is the 1538 * largest value <i>k</i> such that: 1539 * <blockquote><pre> 1540 * this.codePointAt(<i>k</i>) == ch 1541 * </pre></blockquote> 1542 * is true. In either case, if no such character occurs in this 1543 * string, then {@code -1} is returned. The 1544 * {@code String} is searched backwards starting at the last 1545 * character. 1546 * 1547 * @param ch a character (Unicode code point). 1548 * @return the index of the last occurrence of the character in the 1549 * character sequence represented by this object, or 1550 * {@code -1} if the character does not occur. 1551 */ 1552 public int lastIndexOf(int ch) { 1553 return lastIndexOf(ch, length() - 1); 1554 } 1555 1556 /** 1557 * Returns the index within this string of the last occurrence of 1558 * the specified character, searching backward starting at the 1559 * specified index. For values of {@code ch} in the range 1560 * from 0 to 0xFFFF (inclusive), the index returned is the largest 1561 * value <i>k</i> such that: 1562 * <blockquote><pre> 1563 * (this.charAt(<i>k</i>) == ch) {@code &&} (<i>k</i> <= fromIndex) 1564 * </pre></blockquote> 1565 * is true. For other values of {@code ch}, it is the 1566 * largest value <i>k</i> such that: 1567 * <blockquote><pre> 1568 * (this.codePointAt(<i>k</i>) == ch) {@code &&} (<i>k</i> <= fromIndex) 1569 * </pre></blockquote> 1570 * is true. In either case, if no such character occurs in this 1571 * string at or before position {@code fromIndex}, then 1572 * {@code -1} is returned. 1573 * 1574 * <p>All indices are specified in {@code char} values 1575 * (Unicode code units). 1576 * 1577 * @param ch a character (Unicode code point). 1578 * @param fromIndex the index to start the search from. There is no 1579 * restriction on the value of {@code fromIndex}. If it is 1580 * greater than or equal to the length of this string, it has 1581 * the same effect as if it were equal to one less than the 1582 * length of this string: this entire string may be searched. 1583 * If it is negative, it has the same effect as if it were -1: 1584 * -1 is returned. 1585 * @return the index of the last occurrence of the character in the 1586 * character sequence represented by this object that is less 1587 * than or equal to {@code fromIndex}, or {@code -1} 1588 * if the character does not occur before that point. 1589 */ 1590 public int lastIndexOf(int ch, int fromIndex) { 1591 if (ch < Character.MIN_SUPPLEMENTARY_CODE_POINT) { 1592 // handle most cases here (ch is a BMP code point or a 1593 // negative value (invalid code point)) 1594 int i = Math.min(fromIndex, length() - 1); 1595 for (; i >= 0; i--) { 1596 if (charAt(i) == ch) { 1597 return i; 1598 } 1599 } 1600 return -1; 1601 } else { 1602 return lastIndexOfSupplementary(ch, fromIndex); 1603 } 1604 } 1605 1606 /** 1607 * Handles (rare) calls of lastIndexOf with a supplementary character. 1608 */ 1609 private int lastIndexOfSupplementary(int ch, int fromIndex) { 1610 if (Character.isValidCodePoint(ch)) { 1611 char hi = Character.highSurrogate(ch); 1612 char lo = Character.lowSurrogate(ch); 1613 int i = Math.min(fromIndex, length() - 2); 1614 for (; i >= 0; i--) { 1615 if (charAt(i) == hi && charAt(i + 1) == lo) { 1616 return i; 1617 } 1618 } 1619 } 1620 return -1; 1621 } 1622 1623 /** 1624 * Returns the index within this string of the first occurrence of the 1625 * specified substring. 1626 * 1627 * <p>The returned index is the smallest value <i>k</i> for which: 1628 * <blockquote><pre> 1629 * this.startsWith(str, <i>k</i>) 1630 * </pre></blockquote> 1631 * If no such value of <i>k</i> exists, then {@code -1} is returned. 1632 * 1633 * @param str the substring to search for. 1634 * @return the index of the first occurrence of the specified substring, 1635 * or {@code -1} if there is no such occurrence. 1636 */ 1637 public int indexOf(String str) { 1638 return indexOf(str, 0); 1639 } 1640 1641 /** 1642 * Returns the index within this string of the first occurrence of the 1643 * specified substring, starting at the specified index. 1644 * 1645 * <p>The returned index is the smallest value <i>k</i> for which: 1646 * <blockquote><pre> 1647 * <i>k</i> >= fromIndex {@code &&} this.startsWith(str, <i>k</i>) 1648 * </pre></blockquote> 1649 * If no such value of <i>k</i> exists, then {@code -1} is returned. 1650 * 1651 * @param str the substring to search for. 1652 * @param fromIndex the index from which to start the search. 1653 * @return the index of the first occurrence of the specified substring, 1654 * starting at the specified index, 1655 * or {@code -1} if there is no such occurrence. 1656 */ 1657 public int indexOf(String str, int fromIndex) { 1658 return indexOf(this, str, fromIndex); 1659 } 1660 1661 /** 1662 * Code shared by String and AbstractStringBuilder to do searches. The 1663 * source is the character array being searched, and the target 1664 * is the string being searched for. 1665 * 1666 * @param source the characters being searched. 1667 * @param target the characters being searched for. 1668 * @param fromIndex the index to begin searching from. 1669 */ 1670 static int indexOf(String source, 1671 String target, 1672 int fromIndex) { 1673 final int sourceLength = source.length(); 1674 final int targetLength = target.length(); 1675 if (fromIndex >= sourceLength) { 1676 return (targetLength == 0 ? sourceLength : -1); 1677 } 1678 if (fromIndex < 0) { 1679 fromIndex = 0; 1680 } 1681 if (targetLength == 0) { 1682 return fromIndex; 1683 } 1684 1685 char first = target.charAt(0); 1686 int max = (sourceLength - targetLength); 1687 1688 for (int i = fromIndex; i <= max; i++) { 1689 /* Look for first character. */ 1690 if (source.charAt(i)!= first) { 1691 while (++i <= max && source.charAt(i) != first); 1692 } 1693 1694 /* Found first character, now look at the rest of v2 */ 1695 if (i <= max) { 1696 int j = i + 1; 1697 int end = j + targetLength - 1; 1698 for (int k = 1; j < end && source.charAt(j) 1699 == target.charAt(k); j++, k++); 1700 1701 if (j == end) { 1702 /* Found whole string. */ 1703 return i; 1704 } 1705 } 1706 } 1707 return -1; 1708 } 1709 1710 /** 1711 * Code shared by String and StringBuffer to do searches. The 1712 * source is the character array being searched, and the target 1713 * is the string being searched for. 1714 * 1715 * @param source the characters being searched. 1716 * @param sourceOffset offset of the source string. 1717 * @param sourceCount count of the source string. 1718 * @param target the characters being searched for. 1719 * @param targetOffset offset of the target string. 1720 * @param targetCount count of the target string. 1721 * @param fromIndex the index to begin searching from. 1722 */ 1723 static int indexOf(char[] source, int sourceOffset, int sourceCount, 1724 char[] target, int targetOffset, int targetCount, 1725 int fromIndex) { 1726 if (fromIndex >= sourceCount) { 1727 return (targetCount == 0 ? sourceCount : -1); 1728 } 1729 if (fromIndex < 0) { 1730 fromIndex = 0; 1731 } 1732 if (targetCount == 0) { 1733 return fromIndex; 1734 } 1735 1736 char first = target[targetOffset]; 1737 int max = sourceOffset + (sourceCount - targetCount); 1738 1739 for (int i = sourceOffset + fromIndex; i <= max; i++) { 1740 /* Look for first character. */ 1741 if (source[i] != first) { 1742 while (++i <= max && source[i] != first); 1743 } 1744 1745 /* Found first character, now look at the rest of v2 */ 1746 if (i <= max) { 1747 int j = i + 1; 1748 int end = j + targetCount - 1; 1749 for (int k = targetOffset + 1; j < end && source[j] 1750 == target[k]; j++, k++); 1751 1752 if (j == end) { 1753 /* Found whole string. */ 1754 return i - sourceOffset; 1755 } 1756 } 1757 } 1758 return -1; 1759 } 1760 1761 /** 1762 * Returns the index within this string of the last occurrence of the 1763 * specified substring. The last occurrence of the empty string "" 1764 * is considered to occur at the index value {@code this.length()}. 1765 * 1766 * <p>The returned index is the largest value <i>k</i> for which: 1767 * <blockquote><pre> 1768 * this.startsWith(str, <i>k</i>) 1769 * </pre></blockquote> 1770 * If no such value of <i>k</i> exists, then {@code -1} is returned. 1771 * 1772 * @param str the substring to search for. 1773 * @return the index of the last occurrence of the specified substring, 1774 * or {@code -1} if there is no such occurrence. 1775 */ 1776 public int lastIndexOf(String str) { 1777 return lastIndexOf(str, length()); 1778 } 1779 1780 /** 1781 * Returns the index within this string of the last occurrence of the 1782 * specified substring, searching backward starting at the specified index. 1783 * 1784 * <p>The returned index is the largest value <i>k</i> for which: 1785 * <blockquote><pre> 1786 * <i>k</i> {@code <=} fromIndex {@code &&} this.startsWith(str, <i>k</i>) 1787 * </pre></blockquote> 1788 * If no such value of <i>k</i> exists, then {@code -1} is returned. 1789 * 1790 * @param str the substring to search for. 1791 * @param fromIndex the index to start the search from. 1792 * @return the index of the last occurrence of the specified substring, 1793 * searching backward from the specified index, 1794 * or {@code -1} if there is no such occurrence. 1795 */ 1796 public int lastIndexOf(String str, int fromIndex) { 1797 return lastIndexOf(this, str, fromIndex); 1798 } 1799 1800 /** 1801 * Code shared by String and AbstractStringBuilder to do searches. The 1802 * source is the character array being searched, and the target 1803 * is the string being searched for. 1804 * 1805 * @param source the characters being searched. 1806 * @param target the characters being searched for. 1807 * @param fromIndex the index to begin searching from. 1808 */ 1809 static int lastIndexOf(String source, 1810 String target, 1811 int fromIndex) { 1812 /* 1813 * Check arguments; return immediately where possible. For 1814 * consistency, don't check for null str. 1815 */ 1816 final int sourceLength = source.length(); 1817 final int targetLength = target.length(); 1818 int rightIndex = sourceLength - targetLength; 1819 if (fromIndex < 0) { 1820 return -1; 1821 } 1822 if (fromIndex > rightIndex) { 1823 fromIndex = rightIndex; 1824 } 1825 /* Empty string always matches. */ 1826 if (targetLength == 0) { 1827 return fromIndex; 1828 } 1829 1830 int strLastIndex = targetLength - 1; 1831 char strLastChar = target.charAt(strLastIndex); 1832 int min = targetLength - 1; 1833 int i = min + fromIndex; 1834 1835 startSearchForLastChar: 1836 while (true) { 1837 while (i >= min && source.charAt(i) != strLastChar) { 1838 i--; 1839 } 1840 if (i < min) { 1841 return -1; 1842 } 1843 int j = i - 1; 1844 int start = j - (targetLength - 1); 1845 int k = strLastIndex - 1; 1846 1847 while (j > start) { 1848 if (source.charAt(j--) != target.charAt(k--)) { 1849 i--; 1850 continue startSearchForLastChar; 1851 } 1852 } 1853 return start + 1; 1854 } 1855 } 1856 1857 /** 1858 * Code shared by String and StringBuffer to do searches. The 1859 * source is the character array being searched, and the target 1860 * is the string being searched for. 1861 * 1862 * @param source the characters being searched. 1863 * @param sourceOffset offset of the source string. 1864 * @param sourceCount count of the source string. 1865 * @param target the characters being searched for. 1866 * @param targetOffset offset of the target string. 1867 * @param targetCount count of the target string. 1868 * @param fromIndex the index to begin searching from. 1869 */ 1870 static int lastIndexOf(char[] source, int sourceOffset, int sourceCount, 1871 char[] target, int targetOffset, int targetCount, 1872 int fromIndex) { 1873 /* 1874 * Check arguments; return immediately where possible. For 1875 * consistency, don't check for null str. 1876 */ 1877 int rightIndex = sourceCount - targetCount; 1878 if (fromIndex < 0) { 1879 return -1; 1880 } 1881 if (fromIndex > rightIndex) { 1882 fromIndex = rightIndex; 1883 } 1884 /* Empty string always matches. */ 1885 if (targetCount == 0) { 1886 return fromIndex; 1887 } 1888 1889 int strLastIndex = targetOffset + targetCount - 1; 1890 char strLastChar = target[strLastIndex]; 1891 int min = sourceOffset + targetCount - 1; 1892 int i = min + fromIndex; 1893 1894 startSearchForLastChar: 1895 while (true) { 1896 while (i >= min && source[i] != strLastChar) { 1897 i--; 1898 } 1899 if (i < min) { 1900 return -1; 1901 } 1902 int j = i - 1; 1903 int start = j - (targetCount - 1); 1904 int k = strLastIndex - 1; 1905 1906 while (j > start) { 1907 if (source[j--] != target[k--]) { 1908 i--; 1909 continue startSearchForLastChar; 1910 } 1911 } 1912 return start - sourceOffset + 1; 1913 } 1914 } 1915 1916 /** 1917 * Returns a string that is a substring of this string. The 1918 * substring begins with the character at the specified index and 1919 * extends to the end of this string. <p> 1920 * Examples: 1921 * <blockquote><pre> 1922 * "unhappy".substring(2) returns "happy" 1923 * "Harbison".substring(3) returns "bison" 1924 * "emptiness".substring(9) returns "" (an empty string) 1925 * </pre></blockquote> 1926 * 1927 * @param beginIndex the beginning index, inclusive. 1928 * @return the specified substring. 1929 * @exception IndexOutOfBoundsException if 1930 * {@code beginIndex} is negative or larger than the 1931 * length of this {@code String} object. 1932 */ 1933 public String substring(int beginIndex) { 1934 if (beginIndex < 0) { 1935 throw new StringIndexOutOfBoundsException(this, beginIndex); 1936 } 1937 int subLen = length() - beginIndex; 1938 if (subLen < 0) { 1939 throw new StringIndexOutOfBoundsException(this, beginIndex); 1940 } 1941 return (beginIndex == 0) ? this : fastSubstring(beginIndex, subLen); 1942 } 1943 1944 /** 1945 * Returns a string that is a substring of this string. The 1946 * substring begins at the specified {@code beginIndex} and 1947 * extends to the character at index {@code endIndex - 1}. 1948 * Thus the length of the substring is {@code endIndex-beginIndex}. 1949 * <p> 1950 * Examples: 1951 * <blockquote><pre> 1952 * "hamburger".substring(4, 8) returns "urge" 1953 * "smiles".substring(1, 5) returns "mile" 1954 * </pre></blockquote> 1955 * 1956 * @param beginIndex the beginning index, inclusive. 1957 * @param endIndex the ending index, exclusive. 1958 * @return the specified substring. 1959 * @exception IndexOutOfBoundsException if the 1960 * {@code beginIndex} is negative, or 1961 * {@code endIndex} is larger than the length of 1962 * this {@code String} object, or 1963 * {@code beginIndex} is larger than 1964 * {@code endIndex}. 1965 */ 1966 public String substring(int beginIndex, int endIndex) { 1967 if (beginIndex < 0) { 1968 throw new StringIndexOutOfBoundsException(this, beginIndex); 1969 } 1970 if (endIndex > length()) { 1971 throw new StringIndexOutOfBoundsException(this, endIndex); 1972 } 1973 int subLen = endIndex - beginIndex; 1974 if (subLen < 0) { 1975 throw new StringIndexOutOfBoundsException(subLen); 1976 } 1977 1978 return ((beginIndex == 0) && (endIndex == length())) ? this 1979 : fastSubstring(beginIndex, subLen); 1980 } 1981 1982 @FastNative 1983 private native String fastSubstring(int start, int length); 1984 1985 /** 1986 * Returns a character sequence that is a subsequence of this sequence. 1987 * 1988 * <p> An invocation of this method of the form 1989 * 1990 * <blockquote><pre> 1991 * str.subSequence(begin, end)</pre></blockquote> 1992 * 1993 * behaves in exactly the same way as the invocation 1994 * 1995 * <blockquote><pre> 1996 * str.substring(begin, end)</pre></blockquote> 1997 * 1998 * @apiNote 1999 * This method is defined so that the {@code String} class can implement 2000 * the {@link CharSequence} interface. 2001 * 2002 * @param beginIndex the begin index, inclusive. 2003 * @param endIndex the end index, exclusive. 2004 * @return the specified subsequence. 2005 * 2006 * @throws IndexOutOfBoundsException 2007 * if {@code beginIndex} or {@code endIndex} is negative, 2008 * if {@code endIndex} is greater than {@code length()}, 2009 * or if {@code beginIndex} is greater than {@code endIndex} 2010 * 2011 * @since 1.4 2012 * @spec JSR-51 2013 */ 2014 public CharSequence subSequence(int beginIndex, int endIndex) { 2015 return this.substring(beginIndex, endIndex); 2016 } 2017 2018 /** 2019 * Concatenates the specified string to the end of this string. 2020 * <p> 2021 * If the length of the argument string is {@code 0}, then this 2022 * {@code String} object is returned. Otherwise, a 2023 * {@code String} object is returned that represents a character 2024 * sequence that is the concatenation of the character sequence 2025 * represented by this {@code String} object and the character 2026 * sequence represented by the argument string.<p> 2027 * Examples: 2028 * <blockquote><pre> 2029 * "cares".concat("s") returns "caress" 2030 * "to".concat("get").concat("her") returns "together" 2031 * </pre></blockquote> 2032 * 2033 * @param str the {@code String} that is concatenated to the end 2034 * of this {@code String}. 2035 * @return a string that represents the concatenation of this object's 2036 * characters followed by the string argument's characters. 2037 */ 2038 @FastNative 2039 public native String concat(String str); 2040 2041 /** 2042 * Returns a string resulting from replacing all occurrences of 2043 * {@code oldChar} in this string with {@code newChar}. 2044 * <p> 2045 * If the character {@code oldChar} does not occur in the 2046 * character sequence represented by this {@code String} object, 2047 * then a reference to this {@code String} object is returned. 2048 * Otherwise, a {@code String} object is returned that 2049 * represents a character sequence identical to the character sequence 2050 * represented by this {@code String} object, except that every 2051 * occurrence of {@code oldChar} is replaced by an occurrence 2052 * of {@code newChar}. 2053 * <p> 2054 * Examples: 2055 * <blockquote><pre> 2056 * "mesquite in your cellar".replace('e', 'o') 2057 * returns "mosquito in your collar" 2058 * "the war of baronets".replace('r', 'y') 2059 * returns "the way of bayonets" 2060 * "sparring with a purple porpoise".replace('p', 't') 2061 * returns "starring with a turtle tortoise" 2062 * "JonL".replace('q', 'x') returns "JonL" (no change) 2063 * </pre></blockquote> 2064 * 2065 * @param oldChar the old character. 2066 * @param newChar the new character. 2067 * @return a string derived from this string by replacing every 2068 * occurrence of {@code oldChar} with {@code newChar}. 2069 */ 2070 public String replace(char oldChar, char newChar) { 2071 if (oldChar != newChar) { 2072 final int len = length(); 2073 for (int i = 0; i < len; ++i) { 2074 if (charAt(i) == oldChar) { 2075 return doReplace(oldChar, newChar); 2076 } 2077 } 2078 } 2079 return this; 2080 } 2081 2082 // Implementation of replace(char oldChar, char newChar) called when we found a match. 2083 @FastNative 2084 private native String doReplace(char oldChar, char newChar); 2085 2086 /** 2087 * Tells whether or not this string matches the given <a 2088 * href="../util/regex/Pattern.html#sum">regular expression</a>. 2089 * 2090 * <p> An invocation of this method of the form 2091 * <i>str</i>{@code .matches(}<i>regex</i>{@code )} yields exactly the 2092 * same result as the expression 2093 * 2094 * <blockquote> 2095 * {@link java.util.regex.Pattern}.{@link java.util.regex.Pattern#matches(String,CharSequence) 2096 * matches(<i>regex</i>, <i>str</i>)} 2097 * </blockquote> 2098 * 2099 * @param regex 2100 * the regular expression to which this string is to be matched 2101 * 2102 * @return {@code true} if, and only if, this string matches the 2103 * given regular expression 2104 * 2105 * @throws PatternSyntaxException 2106 * if the regular expression's syntax is invalid 2107 * 2108 * @see java.util.regex.Pattern 2109 * 2110 * @since 1.4 2111 * @spec JSR-51 2112 */ 2113 public boolean matches(String regex) { 2114 return Pattern.matches(regex, this); 2115 } 2116 2117 /** 2118 * Returns true if and only if this string contains the specified 2119 * sequence of char values. 2120 * 2121 * @param s the sequence to search for 2122 * @return true if this string contains {@code s}, false otherwise 2123 * @since 1.5 2124 */ 2125 public boolean contains(CharSequence s) { 2126 return indexOf(s.toString()) > -1; 2127 } 2128 2129 /** 2130 * Replaces the first substring of this string that matches the given <a 2131 * href="../util/regex/Pattern.html#sum">regular expression</a> with the 2132 * given replacement. 2133 * 2134 * <p> An invocation of this method of the form 2135 * <i>str</i>{@code .replaceFirst(}<i>regex</i>{@code ,} <i>repl</i>{@code )} 2136 * yields exactly the same result as the expression 2137 * 2138 * <blockquote> 2139 * <code> 2140 * {@link java.util.regex.Pattern}.{@link 2141 * java.util.regex.Pattern#compile compile}(<i>regex</i>).{@link 2142 * java.util.regex.Pattern#matcher(java.lang.CharSequence) matcher}(<i>str</i>).{@link 2143 * java.util.regex.Matcher#replaceFirst replaceFirst}(<i>repl</i>) 2144 * </code> 2145 * </blockquote> 2146 * 2147 *<p> 2148 * Note that backslashes ({@code \}) and dollar signs ({@code $}) in the 2149 * replacement string may cause the results to be different than if it were 2150 * being treated as a literal replacement string; see 2151 * {@link java.util.regex.Matcher#replaceFirst}. 2152 * Use {@link java.util.regex.Matcher#quoteReplacement} to suppress the special 2153 * meaning of these characters, if desired. 2154 * 2155 * @param regex 2156 * the regular expression to which this string is to be matched 2157 * @param replacement 2158 * the string to be substituted for the first match 2159 * 2160 * @return The resulting {@code String} 2161 * 2162 * @throws PatternSyntaxException 2163 * if the regular expression's syntax is invalid 2164 * 2165 * @see java.util.regex.Pattern 2166 * 2167 * @since 1.4 2168 * @spec JSR-51 2169 */ 2170 public String replaceFirst(String regex, String replacement) { 2171 return Pattern.compile(regex).matcher(this).replaceFirst(replacement); 2172 } 2173 2174 /** 2175 * Replaces each substring of this string that matches the given <a 2176 * href="../util/regex/Pattern.html#sum">regular expression</a> with the 2177 * given replacement. 2178 * 2179 * <p> An invocation of this method of the form 2180 * <i>str</i>{@code .replaceAll(}<i>regex</i>{@code ,} <i>repl</i>{@code )} 2181 * yields exactly the same result as the expression 2182 * 2183 * <blockquote> 2184 * <code> 2185 * {@link java.util.regex.Pattern}.{@link 2186 * java.util.regex.Pattern#compile compile}(<i>regex</i>).{@link 2187 * java.util.regex.Pattern#matcher(java.lang.CharSequence) matcher}(<i>str</i>).{@link 2188 * java.util.regex.Matcher#replaceAll replaceAll}(<i>repl</i>) 2189 * </code> 2190 * </blockquote> 2191 * 2192 *<p> 2193 * Note that backslashes ({@code \}) and dollar signs ({@code $}) in the 2194 * replacement string may cause the results to be different than if it were 2195 * being treated as a literal replacement string; see 2196 * {@link java.util.regex.Matcher#replaceAll Matcher.replaceAll}. 2197 * Use {@link java.util.regex.Matcher#quoteReplacement} to suppress the special 2198 * meaning of these characters, if desired. 2199 * 2200 * @param regex 2201 * the regular expression to which this string is to be matched 2202 * @param replacement 2203 * the string to be substituted for each match 2204 * 2205 * @return The resulting {@code String} 2206 * 2207 * @throws PatternSyntaxException 2208 * if the regular expression's syntax is invalid 2209 * 2210 * @see java.util.regex.Pattern 2211 * 2212 * @since 1.4 2213 * @spec JSR-51 2214 */ 2215 public String replaceAll(String regex, String replacement) { 2216 return Pattern.compile(regex).matcher(this).replaceAll(replacement); 2217 } 2218 2219 /** 2220 * Replaces each substring of this string that matches the literal target 2221 * sequence with the specified literal replacement sequence. The 2222 * replacement proceeds from the beginning of the string to the end, for 2223 * example, replacing "aa" with "b" in the string "aaa" will result in 2224 * "ba" rather than "ab". 2225 * 2226 * @param target The sequence of char values to be replaced 2227 * @param replacement The replacement sequence of char values 2228 * @return The resulting string 2229 * @throws NullPointerException if <code>target</code> or 2230 * <code>replacement</code> is <code>null</code>. 2231 * @since 1.5 2232 */ 2233 public String replace(CharSequence target, CharSequence replacement) { 2234 if (target == null) { 2235 throw new NullPointerException("target == null"); 2236 } 2237 2238 if (replacement == null) { 2239 throw new NullPointerException("replacement == null"); 2240 } 2241 2242 String replacementStr = replacement.toString(); 2243 String targetStr = target.toString(); 2244 2245 // Special case when target == "". This is a pretty nonsensical transformation and nobody 2246 // should be hitting this. 2247 // 2248 // See commit 870b23b3febc85 and http://code.google.com/p/android/issues/detail?id=8807 2249 // An empty target is inserted at the start of the string, the end of the string and 2250 // between all characters. 2251 final int len = length(); 2252 if (targetStr.isEmpty()) { 2253 // Note that overallocates by |replacement.size()| if |this| is the empty string, but 2254 // that should be a rare case within an already nonsensical case. 2255 StringBuilder sb = new StringBuilder(replacementStr.length() * (len + 2) + len); 2256 sb.append(replacementStr); 2257 for (int i = 0; i < len; ++i) { 2258 sb.append(charAt(i)); 2259 sb.append(replacementStr); 2260 } 2261 2262 return sb.toString(); 2263 } 2264 2265 // This is the "regular" case. 2266 int lastMatch = 0; 2267 StringBuilder sb = null; 2268 for (;;) { 2269 int currentMatch = indexOf(this, targetStr, lastMatch); 2270 if (currentMatch == -1) { 2271 break; 2272 } 2273 2274 if (sb == null) { 2275 sb = new StringBuilder(len); 2276 } 2277 2278 sb.append(this, lastMatch, currentMatch); 2279 sb.append(replacementStr); 2280 lastMatch = currentMatch + targetStr.length(); 2281 } 2282 2283 if (sb != null) { 2284 sb.append(this, lastMatch, len); 2285 return sb.toString(); 2286 } else { 2287 return this; 2288 } 2289 } 2290 2291 /** 2292 * Splits this string around matches of the given 2293 * <a href="../util/regex/Pattern.html#sum">regular expression</a>. 2294 * 2295 * <p> The array returned by this method contains each substring of this 2296 * string that is terminated by another substring that matches the given 2297 * expression or is terminated by the end of the string. The substrings in 2298 * the array are in the order in which they occur in this string. If the 2299 * expression does not match any part of the input then the resulting array 2300 * has just one element, namely this string. 2301 * 2302 * <p> When there is a positive-width match at the beginning of this 2303 * string then an empty leading substring is included at the beginning 2304 * of the resulting array. A zero-width match at the beginning however 2305 * never produces such empty leading substring. 2306 * 2307 * <p> The {@code limit} parameter controls the number of times the 2308 * pattern is applied and therefore affects the length of the resulting 2309 * array. If the limit <i>n</i> is greater than zero then the pattern 2310 * will be applied at most <i>n</i> - 1 times, the array's 2311 * length will be no greater than <i>n</i>, and the array's last entry 2312 * will contain all input beyond the last matched delimiter. If <i>n</i> 2313 * is non-positive then the pattern will be applied as many times as 2314 * possible and the array can have any length. If <i>n</i> is zero then 2315 * the pattern will be applied as many times as possible, the array can 2316 * have any length, and trailing empty strings will be discarded. 2317 * 2318 * <p> The string {@code "boo:and:foo"}, for example, yields the 2319 * following results with these parameters: 2320 * 2321 * <blockquote><table cellpadding=1 cellspacing=0 summary="Split example showing regex, limit, and result"> 2322 * <tr> 2323 * <th>Regex</th> 2324 * <th>Limit</th> 2325 * <th>Result</th> 2326 * </tr> 2327 * <tr><td align=center>:</td> 2328 * <td align=center>2</td> 2329 * <td>{@code { "boo", "and:foo" }}</td></tr> 2330 * <tr><td align=center>:</td> 2331 * <td align=center>5</td> 2332 * <td>{@code { "boo", "and", "foo" }}</td></tr> 2333 * <tr><td align=center>:</td> 2334 * <td align=center>-2</td> 2335 * <td>{@code { "boo", "and", "foo" }}</td></tr> 2336 * <tr><td align=center>o</td> 2337 * <td align=center>5</td> 2338 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr> 2339 * <tr><td align=center>o</td> 2340 * <td align=center>-2</td> 2341 * <td>{@code { "b", "", ":and:f", "", "" }}</td></tr> 2342 * <tr><td align=center>o</td> 2343 * <td align=center>0</td> 2344 * <td>{@code { "b", "", ":and:f" }}</td></tr> 2345 * </table></blockquote> 2346 * 2347 * <p> An invocation of this method of the form 2348 * <i>str.</i>{@code split(}<i>regex</i>{@code ,} <i>n</i>{@code )} 2349 * yields the same result as the expression 2350 * 2351 * <blockquote> 2352 * <code> 2353 * {@link java.util.regex.Pattern}.{@link 2354 * java.util.regex.Pattern#compile compile}(<i>regex</i>).{@link 2355 * java.util.regex.Pattern#split(java.lang.CharSequence,int) split}(<i>str</i>, <i>n</i>) 2356 * </code> 2357 * </blockquote> 2358 * 2359 * 2360 * @param regex 2361 * the delimiting regular expression 2362 * 2363 * @param limit 2364 * the result threshold, as described above 2365 * 2366 * @return the array of strings computed by splitting this string 2367 * around matches of the given regular expression 2368 * 2369 * @throws PatternSyntaxException 2370 * if the regular expression's syntax is invalid 2371 * 2372 * @see java.util.regex.Pattern 2373 * 2374 * @since 1.4 2375 * @spec JSR-51 2376 */ 2377 public String[] split(String regex, int limit) { 2378 // Try fast splitting without allocating Pattern object 2379 String[] fast = Pattern.fastSplit(regex, this, limit); 2380 if (fast != null) { 2381 return fast; 2382 } 2383 2384 return Pattern.compile(regex).split(this, limit); 2385 } 2386 2387 /** 2388 * Splits this string around matches of the given <a 2389 * href="../util/regex/Pattern.html#sum">regular expression</a>. 2390 * 2391 * <p> This method works as if by invoking the two-argument {@link 2392 * #split(String, int) split} method with the given expression and a limit 2393 * argument of zero. Trailing empty strings are therefore not included in 2394 * the resulting array. 2395 * 2396 * <p> The string {@code "boo:and:foo"}, for example, yields the following 2397 * results with these expressions: 2398 * 2399 * <blockquote><table cellpadding=1 cellspacing=0 summary="Split examples showing regex and result"> 2400 * <tr> 2401 * <th>Regex</th> 2402 * <th>Result</th> 2403 * </tr> 2404 * <tr><td align=center>:</td> 2405 * <td>{@code { "boo", "and", "foo" }}</td></tr> 2406 * <tr><td align=center>o</td> 2407 * <td>{@code { "b", "", ":and:f" }}</td></tr> 2408 * </table></blockquote> 2409 * 2410 * 2411 * @param regex 2412 * the delimiting regular expression 2413 * 2414 * @return the array of strings computed by splitting this string 2415 * around matches of the given regular expression 2416 * 2417 * @throws PatternSyntaxException 2418 * if the regular expression's syntax is invalid 2419 * 2420 * @see java.util.regex.Pattern 2421 * 2422 * @since 1.4 2423 * @spec JSR-51 2424 */ 2425 public String[] split(String regex) { 2426 return split(regex, 0); 2427 } 2428 2429 /** 2430 * Returns a new String composed of copies of the 2431 * {@code CharSequence elements} joined together with a copy of 2432 * the specified {@code delimiter}. 2433 * 2434 * <blockquote>For example, 2435 * <pre>{@code 2436 * String message = String.join("-", "Java", "is", "cool"); 2437 * // message returned is: "Java-is-cool" 2438 * }</pre></blockquote> 2439 * 2440 * Note that if an element is null, then {@code "null"} is added. 2441 * 2442 * @param delimiter the delimiter that separates each element 2443 * @param elements the elements to join together. 2444 * 2445 * @return a new {@code String} that is composed of the {@code elements} 2446 * separated by the {@code delimiter} 2447 * 2448 * @throws NullPointerException If {@code delimiter} or {@code elements} 2449 * is {@code null} 2450 * 2451 * @see java.util.StringJoiner 2452 * @since 1.8 2453 */ 2454 public static String join(CharSequence delimiter, CharSequence... elements) { 2455 Objects.requireNonNull(delimiter); 2456 Objects.requireNonNull(elements); 2457 // Number of elements not likely worth Arrays.stream overhead. 2458 StringJoiner joiner = new StringJoiner(delimiter); 2459 for (CharSequence cs: elements) { 2460 joiner.add(cs); 2461 } 2462 return joiner.toString(); 2463 } 2464 2465 /** 2466 * Returns a new {@code String} composed of copies of the 2467 * {@code CharSequence elements} joined together with a copy of the 2468 * specified {@code delimiter}. 2469 * 2470 * <blockquote>For example, 2471 * <pre>{@code 2472 * List<String> strings = new LinkedList<>(); 2473 * strings.add("Java");strings.add("is"); 2474 * strings.add("cool"); 2475 * String message = String.join(" ", strings); 2476 * //message returned is: "Java is cool" 2477 * 2478 * Set<String> strings = new LinkedHashSet<>(); 2479 * strings.add("Java"); strings.add("is"); 2480 * strings.add("very"); strings.add("cool"); 2481 * String message = String.join("-", strings); 2482 * //message returned is: "Java-is-very-cool" 2483 * }</pre></blockquote> 2484 * 2485 * Note that if an individual element is {@code null}, then {@code "null"} is added. 2486 * 2487 * @param delimiter a sequence of characters that is used to separate each 2488 * of the {@code elements} in the resulting {@code String} 2489 * @param elements an {@code Iterable} that will have its {@code elements} 2490 * joined together. 2491 * 2492 * @return a new {@code String} that is composed from the {@code elements} 2493 * argument 2494 * 2495 * @throws NullPointerException If {@code delimiter} or {@code elements} 2496 * is {@code null} 2497 * 2498 * @see #join(CharSequence,CharSequence...) 2499 * @see java.util.StringJoiner 2500 * @since 1.8 2501 */ 2502 public static String join(CharSequence delimiter, 2503 Iterable<? extends CharSequence> elements) { 2504 Objects.requireNonNull(delimiter); 2505 Objects.requireNonNull(elements); 2506 StringJoiner joiner = new StringJoiner(delimiter); 2507 for (CharSequence cs: elements) { 2508 joiner.add(cs); 2509 } 2510 return joiner.toString(); 2511 } 2512 2513 /** 2514 * Converts all of the characters in this {@code String} to lower 2515 * case using the rules of the given {@code Locale}. Case mapping is based 2516 * on the Unicode Standard version specified by the {@link java.lang.Character Character} 2517 * class. Since case mappings are not always 1:1 char mappings, the resulting 2518 * {@code String} may be a different length than the original {@code String}. 2519 * <p> 2520 * Examples of lowercase mappings are in the following table: 2521 * <table border="1" summary="Lowercase mapping examples showing language code of locale, upper case, lower case, and description"> 2522 * <tr> 2523 * <th>Language Code of Locale</th> 2524 * <th>Upper Case</th> 2525 * <th>Lower Case</th> 2526 * <th>Description</th> 2527 * </tr> 2528 * <tr> 2529 * <td>tr (Turkish)</td> 2530 * <td>\u0130</td> 2531 * <td>\u0069</td> 2532 * <td>capital letter I with dot above -> small letter i</td> 2533 * </tr> 2534 * <tr> 2535 * <td>tr (Turkish)</td> 2536 * <td>\u0049</td> 2537 * <td>\u0131</td> 2538 * <td>capital letter I -> small letter dotless i </td> 2539 * </tr> 2540 * <tr> 2541 * <td>(all)</td> 2542 * <td>French Fries</td> 2543 * <td>french fries</td> 2544 * <td>lowercased all chars in String</td> 2545 * </tr> 2546 * <tr> 2547 * <td>(all)</td> 2548 * <td><img src="doc-files/capiota.gif" alt="capiota"><img src="doc-files/capchi.gif" alt="capchi"> 2549 * <img src="doc-files/captheta.gif" alt="captheta"><img src="doc-files/capupsil.gif" alt="capupsil"> 2550 * <img src="doc-files/capsigma.gif" alt="capsigma"></td> 2551 * <td><img src="doc-files/iota.gif" alt="iota"><img src="doc-files/chi.gif" alt="chi"> 2552 * <img src="doc-files/theta.gif" alt="theta"><img src="doc-files/upsilon.gif" alt="upsilon"> 2553 * <img src="doc-files/sigma1.gif" alt="sigma"></td> 2554 * <td>lowercased all chars in String</td> 2555 * </tr> 2556 * </table> 2557 * 2558 * @param locale use the case transformation rules for this locale 2559 * @return the {@code String}, converted to lowercase. 2560 * @see java.lang.String#toLowerCase() 2561 * @see java.lang.String#toUpperCase() 2562 * @see java.lang.String#toUpperCase(Locale) 2563 * @since 1.1 2564 */ 2565 public String toLowerCase(Locale locale) { 2566 return CaseMapper.toLowerCase(locale, this); 2567 } 2568 2569 /** 2570 * Converts all of the characters in this {@code String} to lower 2571 * case using the rules of the default locale. This is equivalent to calling 2572 * {@code toLowerCase(Locale.getDefault())}. 2573 * <p> 2574 * <b>Note:</b> This method is locale sensitive, and may produce unexpected 2575 * results if used for strings that are intended to be interpreted locale 2576 * independently. 2577 * Examples are programming language identifiers, protocol keys, and HTML 2578 * tags. 2579 * For instance, {@code "TITLE".toLowerCase()} in a Turkish locale 2580 * returns {@code "t\u005Cu0131tle"}, where '\u005Cu0131' is the 2581 * LATIN SMALL LETTER DOTLESS I character. 2582 * To obtain correct results for locale insensitive strings, use 2583 * {@code toLowerCase(Locale.ROOT)}. 2584 * <p> 2585 * @return the {@code String}, converted to lowercase. 2586 * @see java.lang.String#toLowerCase(Locale) 2587 */ 2588 public String toLowerCase() { 2589 return toLowerCase(Locale.getDefault()); 2590 } 2591 2592 /** 2593 * Converts all of the characters in this {@code String} to upper 2594 * case using the rules of the given {@code Locale}. Case mapping is based 2595 * on the Unicode Standard version specified by the {@link java.lang.Character Character} 2596 * class. Since case mappings are not always 1:1 char mappings, the resulting 2597 * {@code String} may be a different length than the original {@code String}. 2598 * <p> 2599 * Examples of locale-sensitive and 1:M case mappings are in the following table. 2600 * 2601 * <table border="1" summary="Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description."> 2602 * <tr> 2603 * <th>Language Code of Locale</th> 2604 * <th>Lower Case</th> 2605 * <th>Upper Case</th> 2606 * <th>Description</th> 2607 * </tr> 2608 * <tr> 2609 * <td>tr (Turkish)</td> 2610 * <td>\u0069</td> 2611 * <td>\u0130</td> 2612 * <td>small letter i -> capital letter I with dot above</td> 2613 * </tr> 2614 * <tr> 2615 * <td>tr (Turkish)</td> 2616 * <td>\u0131</td> 2617 * <td>\u0049</td> 2618 * <td>small letter dotless i -> capital letter I</td> 2619 * </tr> 2620 * <tr> 2621 * <td>(all)</td> 2622 * <td>\u00df</td> 2623 * <td>\u0053 \u0053</td> 2624 * <td>small letter sharp s -> two letters: SS</td> 2625 * </tr> 2626 * <tr> 2627 * <td>(all)</td> 2628 * <td>Fahrvergnügen</td> 2629 * <td>FAHRVERGNÜGEN</td> 2630 * <td></td> 2631 * </tr> 2632 * </table> 2633 * @param locale use the case transformation rules for this locale 2634 * @return the {@code String}, converted to uppercase. 2635 * @see java.lang.String#toUpperCase() 2636 * @see java.lang.String#toLowerCase() 2637 * @see java.lang.String#toLowerCase(Locale) 2638 * @since 1.1 2639 */ 2640 public String toUpperCase(Locale locale) { 2641 return CaseMapper.toUpperCase(locale, this, length()); 2642 } 2643 2644 /** 2645 * Converts all of the characters in this {@code String} to upper 2646 * case using the rules of the default locale. This method is equivalent to 2647 * {@code toUpperCase(Locale.getDefault())}. 2648 * <p> 2649 * <b>Note:</b> This method is locale sensitive, and may produce unexpected 2650 * results if used for strings that are intended to be interpreted locale 2651 * independently. 2652 * Examples are programming language identifiers, protocol keys, and HTML 2653 * tags. 2654 * For instance, {@code "title".toUpperCase()} in a Turkish locale 2655 * returns {@code "T\u005Cu0130TLE"}, where '\u005Cu0130' is the 2656 * LATIN CAPITAL LETTER I WITH DOT ABOVE character. 2657 * To obtain correct results for locale insensitive strings, use 2658 * {@code toUpperCase(Locale.ROOT)}. 2659 * <p> 2660 * @return the {@code String}, converted to uppercase. 2661 * @see java.lang.String#toUpperCase(Locale) 2662 */ 2663 public String toUpperCase() { 2664 return toUpperCase(Locale.getDefault()); 2665 } 2666 2667 /** 2668 * Returns a string whose value is this string, with any leading and trailing 2669 * whitespace removed. 2670 * <p> 2671 * If this {@code String} object represents an empty character 2672 * sequence, or the first and last characters of character sequence 2673 * represented by this {@code String} object both have codes 2674 * greater than {@code '\u005Cu0020'} (the space character), then a 2675 * reference to this {@code String} object is returned. 2676 * <p> 2677 * Otherwise, if there is no character with a code greater than 2678 * {@code '\u005Cu0020'} in the string, then a 2679 * {@code String} object representing an empty string is 2680 * returned. 2681 * <p> 2682 * Otherwise, let <i>k</i> be the index of the first character in the 2683 * string whose code is greater than {@code '\u005Cu0020'}, and let 2684 * <i>m</i> be the index of the last character in the string whose code 2685 * is greater than {@code '\u005Cu0020'}. A {@code String} 2686 * object is returned, representing the substring of this string that 2687 * begins with the character at index <i>k</i> and ends with the 2688 * character at index <i>m</i>-that is, the result of 2689 * {@code this.substring(k, m + 1)}. 2690 * <p> 2691 * This method may be used to trim whitespace (as defined above) from 2692 * the beginning and end of a string. 2693 * 2694 * @return A string whose value is this string, with any leading and trailing white 2695 * space removed, or this string if it has no leading or 2696 * trailing white space. 2697 */ 2698 public String trim() { 2699 int len = length(); 2700 int st = 0; 2701 2702 while ((st < len) && (charAt(st) <= ' ')) { 2703 st++; 2704 } 2705 while ((st < len) && (charAt(len - 1) <= ' ')) { 2706 len--; 2707 } 2708 return ((st > 0) || (len < length())) ? substring(st, len) : this; 2709 } 2710 2711 /** 2712 * This object (which is already a string!) is itself returned. 2713 * 2714 * @return the string itself. 2715 */ 2716 public String toString() { 2717 return this; 2718 } 2719 2720 /** 2721 * Converts this string to a new character array. 2722 * 2723 * @return a newly allocated character array whose length is the length 2724 * of this string and whose contents are initialized to contain 2725 * the character sequence represented by this string. 2726 */ 2727 @FastNative 2728 public native char[] toCharArray(); 2729 2730 2731 /** 2732 * Returns a formatted string using the specified format string and 2733 * arguments. 2734 * 2735 * <p> The locale always used is the one returned by {@link 2736 * java.util.Locale#getDefault() Locale.getDefault()}. 2737 * 2738 * @param format 2739 * A <a href="../util/Formatter.html#syntax">format string</a> 2740 * 2741 * @param args 2742 * Arguments referenced by the format specifiers in the format 2743 * string. If there are more arguments than format specifiers, the 2744 * extra arguments are ignored. The number of arguments is 2745 * variable and may be zero. The maximum number of arguments is 2746 * limited by the maximum dimension of a Java array as defined by 2747 * <cite>The Java™ Virtual Machine Specification</cite>. 2748 * The behaviour on a 2749 * {@code null} argument depends on the <a 2750 * href="../util/Formatter.html#syntax">conversion</a>. 2751 * 2752 * @throws java.util.IllegalFormatException 2753 * If a format string contains an illegal syntax, a format 2754 * specifier that is incompatible with the given arguments, 2755 * insufficient arguments given the format string, or other 2756 * illegal conditions. For specification of all possible 2757 * formatting errors, see the <a 2758 * href="../util/Formatter.html#detail">Details</a> section of the 2759 * formatter class specification. 2760 * 2761 * @throws NullPointerException 2762 * If the <tt>format</tt> is <tt>null</tt> 2763 * 2764 * @return A formatted string 2765 * 2766 * @see java.util.Formatter 2767 * @since 1.5 2768 */ 2769 public static String format(String format, Object... args) { 2770 return new Formatter().format(format, args).toString(); 2771 } 2772 2773 /** 2774 * Returns a formatted string using the specified locale, format string, 2775 * and arguments. 2776 * 2777 * @param l 2778 * The {@linkplain java.util.Locale locale} to apply during 2779 * formatting. If {@code l} is {@code null} then no localization 2780 * is applied. 2781 * 2782 * @param format 2783 * A <a href="../util/Formatter.html#syntax">format string</a> 2784 * 2785 * @param args 2786 * Arguments referenced by the format specifiers in the format 2787 * string. If there are more arguments than format specifiers, the 2788 * extra arguments are ignored. The number of arguments is 2789 * variable and may be zero. The maximum number of arguments is 2790 * limited by the maximum dimension of a Java array as defined by 2791 * <cite>The Java™ Virtual Machine Specification</cite>. 2792 * The behaviour on a 2793 * {@code null} argument depends on the 2794 * <a href="../util/Formatter.html#syntax">conversion</a>. 2795 * 2796 * @throws java.util.IllegalFormatException 2797 * If a format string contains an illegal syntax, a format 2798 * specifier that is incompatible with the given arguments, 2799 * insufficient arguments given the format string, or other 2800 * illegal conditions. For specification of all possible 2801 * formatting errors, see the <a 2802 * href="../util/Formatter.html#detail">Details</a> section of the 2803 * formatter class specification 2804 * 2805 * @throws NullPointerException 2806 * If the <tt>format</tt> is <tt>null</tt> 2807 * 2808 * @return A formatted string 2809 * 2810 * @see java.util.Formatter 2811 * @since 1.5 2812 */ 2813 public static String format(Locale l, String format, Object... args) { 2814 return new Formatter(l).format(format, args).toString(); 2815 } 2816 2817 /** 2818 * Returns the string representation of the {@code Object} argument. 2819 * 2820 * @param obj an {@code Object}. 2821 * @return if the argument is {@code null}, then a string equal to 2822 * {@code "null"}; otherwise, the value of 2823 * {@code obj.toString()} is returned. 2824 * @see java.lang.Object#toString() 2825 */ 2826 public static String valueOf(Object obj) { 2827 return (obj == null) ? "null" : obj.toString(); 2828 } 2829 2830 /** 2831 * Returns the string representation of the {@code char} array 2832 * argument. The contents of the character array are copied; subsequent 2833 * modification of the character array does not affect the returned 2834 * string. 2835 * 2836 * @param data the character array. 2837 * @return a {@code String} that contains the characters of the 2838 * character array. 2839 */ 2840 public static String valueOf(char data[]) { 2841 return StringFactory.newStringFromChars(data); 2842 } 2843 2844 /** 2845 * Returns the string representation of a specific subarray of the 2846 * {@code char} array argument. 2847 * <p> 2848 * The {@code offset} argument is the index of the first 2849 * character of the subarray. The {@code count} argument 2850 * specifies the length of the subarray. The contents of the subarray 2851 * are copied; subsequent modification of the character array does not 2852 * affect the returned string. 2853 * 2854 * @param data the character array. 2855 * @param offset initial offset of the subarray. 2856 * @param count length of the subarray. 2857 * @return a {@code String} that contains the characters of the 2858 * specified subarray of the character array. 2859 * @exception IndexOutOfBoundsException if {@code offset} is 2860 * negative, or {@code count} is negative, or 2861 * {@code offset+count} is larger than 2862 * {@code data.length}. 2863 */ 2864 public static String valueOf(char data[], int offset, int count) { 2865 return StringFactory.newStringFromChars(data, offset, count); 2866 } 2867 2868 /** 2869 * Equivalent to {@link #valueOf(char[], int, int)}. 2870 * 2871 * @param data the character array. 2872 * @param offset initial offset of the subarray. 2873 * @param count length of the subarray. 2874 * @return a {@code String} that contains the characters of the 2875 * specified subarray of the character array. 2876 * @exception IndexOutOfBoundsException if {@code offset} is 2877 * negative, or {@code count} is negative, or 2878 * {@code offset+count} is larger than 2879 * {@code data.length}. 2880 */ 2881 public static String copyValueOf(char data[], int offset, int count) { 2882 // All public String constructors now copy the data. 2883 return StringFactory.newStringFromChars(data, offset, count); 2884 } 2885 2886 /** 2887 * Equivalent to {@link #valueOf(char[])}. 2888 * 2889 * @param data the character array. 2890 * @return a {@code String} that contains the characters of the 2891 * character array. 2892 */ 2893 public static String copyValueOf(char data[]) { 2894 return StringFactory.newStringFromChars(data); 2895 } 2896 2897 /** 2898 * Returns the string representation of the {@code boolean} argument. 2899 * 2900 * @param b a {@code boolean}. 2901 * @return if the argument is {@code true}, a string equal to 2902 * {@code "true"} is returned; otherwise, a string equal to 2903 * {@code "false"} is returned. 2904 */ 2905 public static String valueOf(boolean b) { 2906 return b ? "true" : "false"; 2907 } 2908 2909 /** 2910 * Returns the string representation of the {@code char} 2911 * argument. 2912 * 2913 * @param c a {@code char}. 2914 * @return a string of length {@code 1} containing 2915 * as its single character the argument {@code c}. 2916 */ 2917 public static String valueOf(char c) { 2918 return StringFactory.newStringFromChars(0, 1, new char[] { c }); 2919 } 2920 2921 /** 2922 * Returns the string representation of the {@code int} argument. 2923 * <p> 2924 * The representation is exactly the one returned by the 2925 * {@code Integer.toString} method of one argument. 2926 * 2927 * @param i an {@code int}. 2928 * @return a string representation of the {@code int} argument. 2929 * @see java.lang.Integer#toString(int, int) 2930 */ 2931 public static String valueOf(int i) { 2932 return Integer.toString(i); 2933 } 2934 2935 /** 2936 * Returns the string representation of the {@code long} argument. 2937 * <p> 2938 * The representation is exactly the one returned by the 2939 * {@code Long.toString} method of one argument. 2940 * 2941 * @param l a {@code long}. 2942 * @return a string representation of the {@code long} argument. 2943 * @see java.lang.Long#toString(long) 2944 */ 2945 public static String valueOf(long l) { 2946 return Long.toString(l); 2947 } 2948 2949 /** 2950 * Returns the string representation of the {@code float} argument. 2951 * <p> 2952 * The representation is exactly the one returned by the 2953 * {@code Float.toString} method of one argument. 2954 * 2955 * @param f a {@code float}. 2956 * @return a string representation of the {@code float} argument. 2957 * @see java.lang.Float#toString(float) 2958 */ 2959 public static String valueOf(float f) { 2960 return Float.toString(f); 2961 } 2962 2963 /** 2964 * Returns the string representation of the {@code double} argument. 2965 * <p> 2966 * The representation is exactly the one returned by the 2967 * {@code Double.toString} method of one argument. 2968 * 2969 * @param d a {@code double}. 2970 * @return a string representation of the {@code double} argument. 2971 * @see java.lang.Double#toString(double) 2972 */ 2973 public static String valueOf(double d) { 2974 return Double.toString(d); 2975 } 2976 2977 /** 2978 * Returns a canonical representation for the string object. 2979 * <p> 2980 * A pool of strings, initially empty, is maintained privately by the 2981 * class {@code String}. 2982 * <p> 2983 * When the intern method is invoked, if the pool already contains a 2984 * string equal to this {@code String} object as determined by 2985 * the {@link #equals(Object)} method, then the string from the pool is 2986 * returned. Otherwise, this {@code String} object is added to the 2987 * pool and a reference to this {@code String} object is returned. 2988 * <p> 2989 * It follows that for any two strings {@code s} and {@code t}, 2990 * {@code s.intern() == t.intern()} is {@code true} 2991 * if and only if {@code s.equals(t)} is {@code true}. 2992 * <p> 2993 * All literal strings and string-valued constant expressions are 2994 * interned. String literals are defined in section 3.10.5 of the 2995 * <cite>The Java™ Language Specification</cite>. 2996 * 2997 * @return a string that has the same contents as this string, but is 2998 * guaranteed to be from a pool of unique strings. 2999 */ 3000 @FastNative 3001 public native String intern(); 3002 } 3003