1 /* String.java -- immutable character sequences; the object of string literals 2 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 3 Free Software Foundation, Inc. 4 5 This file is part of GNU Classpath. 6 7 GNU Classpath is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 2, or (at your option) 10 any later version. 11 12 GNU Classpath is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with GNU Classpath; see the file COPYING. If not, write to the 19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20 02110-1301 USA. 21 22 Linking this library statically or dynamically with other modules is 23 making a combined work based on this library. Thus, the terms and 24 conditions of the GNU General Public License cover the whole 25 combination. 26 27 As a special exception, the copyright holders of this library give you 28 permission to link this library with independent modules to produce an 29 executable, regardless of the license terms of these independent 30 modules, and to copy and distribute the resulting executable under 31 terms of your choice, provided that you also meet, for each linked 32 independent module, the terms and conditions of the license of that 33 module. An independent module is a module which is not derived from 34 or based on this library. If you modify this library, you may extend 35 this exception to your version of the library, but you are not 36 obligated to do so. If you do not wish to do so, delete this 37 exception statement from your version. */ 38 39 40 package java.lang; 41 42 import java.io.Serializable; 43 import java.io.UnsupportedEncodingException; 44 import java.util.Comparator; 45 import java.text.Collator; 46 import java.util.Formatter; 47 import java.util.Locale; 48 import java.util.regex.Matcher; 49 import java.util.regex.Pattern; 50 import java.util.regex.PatternSyntaxException; 51 52 /** 53 * Strings represent an immutable set of characters. All String literals 54 * are instances of this class, and two string literals with the same contents 55 * refer to the same String object. 56 * 57 * <p>This class also includes a number of methods for manipulating the 58 * contents of strings (of course, creating a new object if there are any 59 * changes, as String is immutable). Case mapping relies on Unicode 3.0.0 60 * standards, where some character sequences have a different number of 61 * characters in the uppercase version than the lower case. 62 * 63 * <p>Strings are special, in that they are the only object with an overloaded 64 * operator. When you use '+' with at least one String argument, both 65 * arguments have String conversion performed on them, and another String (not 66 * guaranteed to be unique) results. 67 * 68 * <p>String is special-cased when doing data serialization - rather than 69 * listing the fields of this class, a String object is converted to a string 70 * literal in the object stream. 71 * 72 * @author Paul N. Fisher 73 * @author Eric Blake (ebb9@email.byu.edu) 74 * @author Per Bothner (bothner@cygnus.com) 75 * @author Tom Tromey (tromey@redhat.com) 76 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 77 * @since 1.0 78 * @status updated to 1.4 79 */ 80 public final class String 81 implements Serializable, Comparable<String>, CharSequence 82 { 83 // WARNING: String is a CORE class in the bootstrap cycle. See the comments 84 // in vm/reference/java/lang/Runtime for implications of this fact. 85 86 /** 87 * This is probably not necessary because this class is special cased already 88 * but it will avoid showing up as a discrepancy when comparing SUIDs. 89 */ 90 private static final long serialVersionUID = -6849794470754667710L; 91 92 /** 93 * This is the object that holds the characters that make up the 94 * String. It might be a char[], or it could be String. It could 95 * even be `this'. The actual characters can't be located using 96 * pure Java code. 97 * @see #boffset 98 */ 99 private Object data; 100 101 /** 102 * This is a <emph>byte</emph> offset of the actual characters from 103 * the start of the character-holding object. Don't use this field 104 * in Java code. 105 */ 106 private int boffset; 107 108 /** 109 * Holds the number of characters in value. Package visible for use 110 * by trusted code. 111 */ 112 int count; 113 114 /** 115 * Caches the result of hashCode(). If this value is zero, the hashcode 116 * is considered uncached (even if 0 is the correct hash value). 117 */ 118 private int cachedHashCode; 119 120 /** 121 * An implementation for {@link #CASE_INSENSITIVE_ORDER}. 122 * This must be {@link Serializable}. The class name is dictated by 123 * compatibility with Sun's JDK. 124 */ 125 private static final class CaseInsensitiveComparator 126 implements Comparator<String>, Serializable 127 { 128 /** 129 * Compatible with JDK 1.2. 130 */ 131 private static final long serialVersionUID = 8575799808933029326L; 132 133 /** 134 * The default private constructor generates unnecessary overhead. 135 */ CaseInsensitiveComparator()136 CaseInsensitiveComparator() {} 137 138 /** 139 * Compares to Strings, using 140 * <code>String.compareToIgnoreCase(String)</code>. 141 * 142 * @param o1 the first string 143 * @param o2 the second string 144 * @return < 0, 0, or > 0 depending on the case-insensitive 145 * comparison of the two strings. 146 * @throws NullPointerException if either argument is null 147 * @throws ClassCastException if either argument is not a String 148 * @see #compareToIgnoreCase(String) 149 */ compare(String o1, String o2)150 public int compare(String o1, String o2) 151 { 152 return o1.compareToIgnoreCase(o2); 153 } 154 } // class CaseInsensitiveComparator 155 156 /** 157 * A Comparator that uses <code>String.compareToIgnoreCase(String)</code>. 158 * This comparator is {@link Serializable}. Note that it ignores Locale, 159 * for that, you want a Collator. 160 * 161 * @see Collator#compare(String, String) 162 * @since 1.2 163 */ 164 public static final Comparator<String> CASE_INSENSITIVE_ORDER 165 = new CaseInsensitiveComparator(); 166 167 /** 168 * Creates an empty String (length 0). Unless you really need a new object, 169 * consider using <code>""</code> instead. 170 */ String()171 public String() 172 { 173 data = "".data; 174 boffset = 0; 175 count = 0; 176 } 177 178 /** 179 * Copies the contents of a String to a new String. Since Strings are 180 * immutable, only a shallow copy is performed. 181 * 182 * @param str String to copy 183 * @throws NullPointerException if value is null 184 */ String(String str)185 public String(String str) 186 { 187 data = str.data; 188 boffset = str.boffset; 189 count = str.count; 190 cachedHashCode = str.cachedHashCode; 191 } 192 193 /** 194 * Creates a new String using the character sequence of the char array. 195 * Subsequent changes to data do not affect the String. 196 * 197 * @param data char array to copy 198 * @throws NullPointerException if data is null 199 */ String(char[] data)200 public String(char[] data) 201 { 202 init(data, 0, data.length, false); 203 } 204 205 /** 206 * Creates a new String using the character sequence of a subarray of 207 * characters. The string starts at offset, and copies count chars. 208 * Subsequent changes to data do not affect the String. 209 * 210 * @param data char array to copy 211 * @param offset position (base 0) to start copying out of data 212 * @param count the number of characters from data to copy 213 * @throws NullPointerException if data is null 214 * @throws IndexOutOfBoundsException if (offset < 0 || count < 0 215 * || offset + count < 0 (overflow) 216 * || offset + count > data.length) 217 * (while unspecified, this is a StringIndexOutOfBoundsException) 218 */ String(char[] data, int offset, int count)219 public String(char[] data, int offset, int count) 220 { 221 init(data, offset, count, false); 222 } 223 224 /** 225 * Creates a new String using an 8-bit array of integer values, starting at 226 * an offset, and copying up to the count. Each character c, using 227 * corresponding byte b, is created in the new String as if by performing: 228 * 229 * <pre> 230 * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff)) 231 * </pre> 232 * 233 * @param ascii array of integer values 234 * @param hibyte top byte of each Unicode character 235 * @param offset position (base 0) to start copying out of ascii 236 * @param count the number of characters from ascii to copy 237 * @throws NullPointerException if ascii is null 238 * @throws IndexOutOfBoundsException if (offset < 0 || count < 0 239 * || offset + count < 0 (overflow) 240 * || offset + count > ascii.length) 241 * (while unspecified, this is a StringIndexOutOfBoundsException) 242 * @see #String(byte[]) 243 * @see #String(byte[], String) 244 * @see #String(byte[], int, int) 245 * @see #String(byte[], int, int, String) 246 * @deprecated use {@link #String(byte[], int, int, String)} to perform 247 * correct encoding 248 */ String(byte[] ascii, int hibyte, int offset, int count)249 public String(byte[] ascii, int hibyte, int offset, int count) 250 { 251 init(ascii, hibyte, offset, count); 252 } 253 254 /** 255 * Creates a new String using an 8-bit array of integer values. Each 256 * character c, using corresponding byte b, is created in the new String 257 * as if by performing: 258 * 259 * <pre> 260 * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff)) 261 * </pre> 262 * 263 * @param ascii array of integer values 264 * @param hibyte top byte of each Unicode character 265 * @throws NullPointerException if ascii is null 266 * @see #String(byte[]) 267 * @see #String(byte[], String) 268 * @see #String(byte[], int, int) 269 * @see #String(byte[], int, int, String) 270 * @see #String(byte[], int, int, int) 271 * @deprecated use {@link #String(byte[], String)} to perform 272 * correct encoding 273 */ String(byte[] ascii, int hibyte)274 public String(byte[] ascii, int hibyte) 275 { 276 init(ascii, hibyte, 0, ascii.length); 277 } 278 279 /** 280 * Creates a new String using the portion of the byte array starting at the 281 * offset and ending at offset + count. Uses the specified encoding type 282 * to decode the byte array, so the resulting string may be longer or 283 * shorter than the byte array. For more decoding control, use 284 * {@link java.nio.charset.CharsetDecoder}, and for valid character sets, 285 * see {@link java.nio.charset.Charset}. The behavior is not specified if 286 * the decoder encounters invalid characters; this implementation throws 287 * an Error. 288 * 289 * @param data byte array to copy 290 * @param offset the offset to start at 291 * @param count the number of bytes in the array to use 292 * @param encoding the name of the encoding to use 293 * @throws NullPointerException if data or encoding is null 294 * @throws IndexOutOfBoundsException if offset or count is incorrect 295 * (while unspecified, this is a StringIndexOutOfBoundsException) 296 * @throws UnsupportedEncodingException if encoding is not found 297 * @throws Error if the decoding fails 298 * @since 1.1 299 */ String(byte[] data, int offset, int count, String encoding)300 public String(byte[] data, int offset, int count, String encoding) 301 throws UnsupportedEncodingException 302 { 303 init (data, offset, count, encoding); 304 } 305 306 /** 307 * Creates a new String using the byte array. Uses the specified encoding 308 * type to decode the byte array, so the resulting string may be longer or 309 * shorter than the byte array. For more decoding control, use 310 * {@link java.nio.charset.CharsetDecoder}, and for valid character sets, 311 * see {@link java.nio.charset.Charset}. The behavior is not specified if 312 * the decoder encounters invalid characters; this implementation throws 313 * an Error. 314 * 315 * @param data byte array to copy 316 * @param encoding the name of the encoding to use 317 * @throws NullPointerException if data or encoding is null 318 * @throws UnsupportedEncodingException if encoding is not found 319 * @throws Error if the decoding fails 320 * @see #String(byte[], int, int, String) 321 * @since 1.1 322 */ String(byte[] data, String encoding)323 public String(byte[] data, String encoding) 324 throws UnsupportedEncodingException 325 { 326 this(data, 0, data.length, encoding); 327 } 328 329 /** 330 * Creates a new String using the portion of the byte array starting at the 331 * offset and ending at offset + count. Uses the encoding of the platform's 332 * default charset, so the resulting string may be longer or shorter than 333 * the byte array. For more decoding control, use 334 * {@link java.nio.charset.CharsetDecoder}. The behavior is not specified 335 * if the decoder encounters invalid characters; this implementation throws 336 * an Error. 337 * 338 * @param data byte array to copy 339 * @param offset the offset to start at 340 * @param count the number of bytes in the array to use 341 * @throws NullPointerException if data is null 342 * @throws IndexOutOfBoundsException if offset or count is incorrect 343 * @throws Error if the decoding fails 344 * @see #String(byte[], int, int, String) 345 * @since 1.1 346 */ String(byte[] data, int offset, int count)347 public String(byte[] data, int offset, int count) 348 { 349 try 350 { 351 init (data, offset, count, 352 System.getProperty("file.encoding", "8859_1")); 353 } 354 catch (UnsupportedEncodingException x1) 355 { 356 // Maybe the default encoding is bad. 357 try 358 { 359 init (data, offset, count, "8859_1"); 360 } 361 catch (UnsupportedEncodingException x2) 362 { 363 // We know this can't happen. 364 } 365 } 366 } 367 368 /** 369 * Creates a new String using the byte array. Uses the encoding of the 370 * platform's default charset, so the resulting string may be longer or 371 * shorter than the byte array. For more decoding control, use 372 * {@link java.nio.charset.CharsetDecoder}. The behavior is not specified 373 * if the decoder encounters invalid characters; this implementation throws 374 * an Error. 375 * 376 * @param data byte array to copy 377 * @throws NullPointerException if data is null 378 * @throws Error if the decoding fails 379 * @see #String(byte[], int, int) 380 * @see #String(byte[], int, int, String) 381 * @since 1.1 382 */ String(byte[] data)383 public String(byte[] data) 384 { 385 this(data, 0, data.length); 386 } 387 388 /** 389 * Creates a new String using the character sequence represented by 390 * the StringBuffer. Subsequent changes to buf do not affect the String. 391 * 392 * @param buffer StringBuffer to copy 393 * @throws NullPointerException if buffer is null 394 */ String(StringBuffer buffer)395 public String(StringBuffer buffer) 396 { 397 synchronized (buffer) 398 { 399 // Share unless buffer is 3/4 empty. 400 boolean should_copy = ((buffer.count << 2) < buffer.value.length); 401 if (! should_copy) 402 buffer.shared = true; 403 init (buffer.value, 0, buffer.count, ! should_copy); 404 } 405 } 406 407 /** 408 * Creates a new String using the character sequence represented by 409 * the StringBuilder. Subsequent changes to buf do not affect the String. 410 * 411 * @param buffer StringBuilder to copy 412 * @throws NullPointerException if buffer is null 413 */ String(StringBuilder buffer)414 public String(StringBuilder buffer) 415 { 416 this(buffer.value, 0, buffer.count); 417 } 418 419 /** 420 * Special constructor which can share an array when safe to do so. 421 * 422 * @param data the characters to copy 423 * @param offset the location to start from 424 * @param count the number of characters to use 425 * @param dont_copy true if the array is trusted, and need not be copied 426 * @throws NullPointerException if chars is null 427 * @throws StringIndexOutOfBoundsException if bounds check fails 428 */ String(char[] data, int offset, int count, boolean dont_copy)429 String(char[] data, int offset, int count, boolean dont_copy) 430 { 431 init(data, offset, count, dont_copy); 432 } 433 434 // This is used by gnu.gcj.runtime.StringBuffer, so it must have 435 // package-private protection. It is accessed via CNI and so avoids 436 // ordinary protection mechanisms. String(gnu.gcj.runtime.StringBuffer buffer)437 String(gnu.gcj.runtime.StringBuffer buffer) 438 { 439 // No need to synchronize or mark the buffer, since we know it is 440 // only used once. 441 init (buffer); 442 } 443 444 /** 445 * Returns the number of characters contained in this String. 446 * 447 * @return the length of this String 448 */ length()449 public int length() 450 { 451 return count; 452 } 453 454 /** 455 * Returns the character located at the specified index within this String. 456 * 457 * @param index position of character to return (base 0) 458 * @return character located at position index 459 * @throws IndexOutOfBoundsException if index < 0 || index >= length() 460 * (while unspecified, this is a StringIndexOutOfBoundsException) 461 */ charAt(int index)462 public native char charAt(int index); 463 464 /** 465 * Get the code point at the specified index. This is like #charAt(int), 466 * but if the character is the start of a surrogate pair, and the 467 * following character completes the pair, then the corresponding 468 * supplementary code point is returned. 469 * @param index the index of the codepoint to get, starting at 0 470 * @return the codepoint at the specified index 471 * @throws IndexOutOfBoundsException if index is negative or >= length() 472 * @since 1.5 473 */ codePointAt(int index)474 public synchronized int codePointAt(int index) 475 { 476 // Use the CharSequence overload as we get better range checking 477 // this way. 478 return Character.codePointAt(this, index); 479 } 480 481 /** 482 * Get the code point before the specified index. This is like 483 * #codePointAt(int), but checks the characters at <code>index-1</code> and 484 * <code>index-2</code> to see if they form a supplementary code point. 485 * @param index the index just past the codepoint to get, starting at 0 486 * @return the codepoint at the specified index 487 * @throws IndexOutOfBoundsException if index is negative or >= length() 488 * (while unspecified, this is a StringIndexOutOfBoundsException) 489 * @since 1.5 490 */ codePointBefore(int index)491 public synchronized int codePointBefore(int index) 492 { 493 // Use the CharSequence overload as we get better range checking 494 // this way. 495 return Character.codePointBefore(this, index); 496 } 497 498 /** 499 * Copies characters from this String starting at a specified start index, 500 * ending at a specified stop index, to a character array starting at 501 * a specified destination begin index. 502 * 503 * @param srcBegin index to begin copying characters from this String 504 * @param srcEnd index after the last character to be copied from this String 505 * @param dst character array which this String is copied into 506 * @param dstBegin index to start writing characters into dst 507 * @throws NullPointerException if dst is null 508 * @throws IndexOutOfBoundsException if any indices are out of bounds 509 * (while unspecified, source problems cause a 510 * StringIndexOutOfBoundsException, and dst problems cause an 511 * ArrayIndexOutOfBoundsException) 512 */ getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)513 public native void getChars(int srcBegin, int srcEnd, 514 char[] dst, int dstBegin); 515 516 /** 517 * Copies the low byte of each character from this String starting at a 518 * specified start index, ending at a specified stop index, to a byte array 519 * starting at a specified destination begin index. 520 * 521 * @param srcBegin index to being copying characters from this String 522 * @param srcEnd index after the last character to be copied from this String 523 * @param dst byte array which each low byte of this String is copied into 524 * @param dstBegin index to start writing characters into dst 525 * @throws NullPointerException if dst is null and copy length is non-zero 526 * @throws IndexOutOfBoundsException if any indices are out of bounds 527 * (while unspecified, source problems cause a 528 * StringIndexOutOfBoundsException, and dst problems cause an 529 * ArrayIndexOutOfBoundsException) 530 * @see #getBytes() 531 * @see #getBytes(String) 532 * @deprecated use {@link #getBytes()}, which uses a char to byte encoder 533 */ getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)534 public native void getBytes(int srcBegin, int srcEnd, 535 byte[] dst, int dstBegin); 536 537 /** 538 * Converts the Unicode characters in this String to a byte array. Uses the 539 * specified encoding method, so the result may be longer or shorter than 540 * the String. For more encoding control, use 541 * {@link java.nio.charset.CharsetEncoder}, and for valid character sets, 542 * see {@link java.nio.charset.Charset}. The behavior is not specified if 543 * the encoder encounters a problem; this implementation returns null. 544 * 545 * @param enc encoding name 546 * @return the resulting byte array, or null on a problem 547 * @throws NullPointerException if enc is null 548 * @throws UnsupportedEncodingException if encoding is not supported 549 * @since 1.1 550 */ getBytes(String enc)551 public native byte[] getBytes(String enc) 552 throws UnsupportedEncodingException; 553 554 /** 555 * Converts the Unicode characters in this String to a byte array. Uses the 556 * encoding of the platform's default charset, so the result may be longer 557 * or shorter than the String. For more encoding control, use 558 * {@link java.nio.charset.CharsetEncoder}. The behavior is not specified if 559 * the encoder encounters a problem; this implementation returns null. 560 * 561 * @return the resulting byte array, or null on a problem 562 * @since 1.1 563 */ getBytes()564 public byte[] getBytes() 565 { 566 try 567 { 568 return getBytes (System.getProperty("file.encoding", "8859_1")); 569 } 570 catch (UnsupportedEncodingException x) 571 { 572 // This probably shouldn't happen, but could if file.encoding 573 // is somehow changed to a value we don't understand. 574 try 575 { 576 return getBytes ("8859_1"); 577 } 578 catch (UnsupportedEncodingException x2) 579 { 580 // This really shouldn't happen, because the 8859_1 581 // encoding should always be available. 582 throw new InternalError ("couldn't find 8859_1 encoder"); 583 } 584 } 585 } 586 587 /** 588 * Predicate which compares anObject to this. This is true only for Strings 589 * with the same character sequence. 590 * 591 * @param anObject the object to compare 592 * @return true if anObject is semantically equal to this 593 * @see #compareTo(String) 594 * @see #equalsIgnoreCase(String) 595 */ equals(Object anObject)596 public native boolean equals(Object anObject); 597 598 /** 599 * Compares the given StringBuffer to this String. This is true if the 600 * StringBuffer has the same content as this String at this moment. 601 * 602 * @param buffer the StringBuffer to compare to 603 * @return true if StringBuffer has the same character sequence 604 * @throws NullPointerException if the given StringBuffer is null 605 * @since 1.4 606 */ contentEquals(StringBuffer buffer)607 public native boolean contentEquals(StringBuffer buffer); 608 609 /** 610 * Compares the given CharSequence to this String. This is true if 611 * the CharSequence has the same content as this String at this 612 * moment. 613 * 614 * @param seq the CharSequence to compare to 615 * @return true if CharSequence has the same character sequence 616 * @throws NullPointerException if the given CharSequence is null 617 * @since 1.5 618 */ contentEquals(CharSequence seq)619 public native boolean contentEquals(CharSequence seq); 620 621 /** 622 * Compares a String to this String, ignoring case. This does not handle 623 * multi-character capitalization exceptions; instead the comparison is 624 * made on a character-by-character basis, and is true if:<br><ul> 625 * <li><code>c1 == c2</code></li> 626 * <li><code>Character.toUpperCase(c1) 627 * == Character.toUpperCase(c2)</code></li> 628 * <li><code>Character.toLowerCase(c1) 629 * == Character.toLowerCase(c2)</code></li> 630 * </ul> 631 * 632 * @param anotherString String to compare to this String 633 * @return true if anotherString is equal, ignoring case 634 * @see #equals(Object) 635 * @see Character#toUpperCase(char) 636 * @see Character#toLowerCase(char) 637 */ equalsIgnoreCase(String anotherString)638 public native boolean equalsIgnoreCase(String anotherString); 639 640 /** 641 * Compares this String and another String (case sensitive, 642 * lexicographically). The result is less than 0 if this string sorts 643 * before the other, 0 if they are equal, and greater than 0 otherwise. 644 * After any common starting sequence is skipped, the result is 645 * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings 646 * have characters remaining, or 647 * <code>this.length() - anotherString.length()</code> if one string is 648 * a subsequence of the other. 649 * 650 * @param anotherString the String to compare against 651 * @return the comparison 652 * @throws NullPointerException if anotherString is null 653 */ compareTo(String anotherString)654 public int compareTo(String anotherString) 655 { 656 return nativeCompareTo(anotherString); 657 } 658 659 /** 660 * The native implementation of compareTo(). Must be named different 661 * since cni doesn't understand the bridge method generated from 662 * the compareTo() method because of the Comparable<String> interface. 663 */ nativeCompareTo(String anotherString)664 private native int nativeCompareTo(String anotherString); 665 666 /** 667 * Compares this String and another String (case insensitive). This 668 * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores 669 * locale and multi-characater capitalization, and compares characters 670 * after performing 671 * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each 672 * character of the string. This is unsatisfactory for locale-based 673 * comparison, in which case you should use {@link java.text.Collator}. 674 * 675 * @param str the string to compare against 676 * @return the comparison 677 * @see Collator#compare(String, String) 678 * @since 1.2 679 */ compareToIgnoreCase(String str)680 public int compareToIgnoreCase(String str) 681 { 682 return this.toUpperCase().toLowerCase().compareTo( 683 str.toUpperCase().toLowerCase()); 684 } 685 686 /** 687 * Predicate which determines if this String matches another String 688 * starting at a specified offset for each String and continuing 689 * for a specified length. Indices out of bounds are harmless, and give 690 * a false result. 691 * 692 * @param toffset index to start comparison at for this String 693 * @param other String to compare region to this String 694 * @param ooffset index to start comparison at for other 695 * @param len number of characters to compare 696 * @return true if regions match (case sensitive) 697 * @throws NullPointerException if other is null 698 */ regionMatches(int toffset, String other, int ooffset, int len)699 public native boolean regionMatches(int toffset, 700 String other, int ooffset, int len); 701 702 /** 703 * Predicate which determines if this String matches another String 704 * starting at a specified offset for each String and continuing 705 * for a specified length, optionally ignoring case. Indices out of bounds 706 * are harmless, and give a false result. Case comparisons are based on 707 * <code>Character.toLowerCase()</code> and 708 * <code>Character.toUpperCase()</code>, not on multi-character 709 * capitalization expansions. 710 * 711 * @param ignoreCase true if case should be ignored in comparision 712 * @param toffset index to start comparison at for this String 713 * @param other String to compare region to this String 714 * @param ooffset index to start comparison at for other 715 * @param len number of characters to compare 716 * @return true if regions match, false otherwise 717 * @throws NullPointerException if other is null 718 */ regionMatches(boolean ignoreCase, int toffset, String other, int ooffset, int len)719 public native boolean regionMatches(boolean ignoreCase, int toffset, 720 String other, int ooffset, int len); 721 722 /** 723 * Predicate which determines if this String contains the given prefix, 724 * beginning comparison at toffset. The result is false if toffset is 725 * negative or greater than this.length(), otherwise it is the same as 726 * <code>this.substring(toffset).startsWith(prefix)</code>. 727 * 728 * @param prefix String to compare 729 * @param toffset offset for this String where comparison starts 730 * @return true if this String starts with prefix 731 * @throws NullPointerException if prefix is null 732 * @see #regionMatches(boolean, int, String, int, int) 733 */ startsWith(String prefix, int toffset)734 public native boolean startsWith(String prefix, int toffset); 735 736 /** 737 * Predicate which determines if this String starts with a given prefix. 738 * If the prefix is an empty String, true is returned. 739 * 740 * @param prefix String to compare 741 * @return true if this String starts with the prefix 742 * @throws NullPointerException if prefix is null 743 * @see #startsWith(String, int) 744 */ startsWith(String prefix)745 public boolean startsWith(String prefix) 746 { 747 return startsWith (prefix, 0); 748 } 749 750 /** 751 * Predicate which determines if this String ends with a given suffix. 752 * If the suffix is an empty String, true is returned. 753 * 754 * @param suffix String to compare 755 * @return true if this String ends with the suffix 756 * @throws NullPointerException if suffix is null 757 * @see #regionMatches(boolean, int, String, int, int) 758 */ endsWith(String suffix)759 public boolean endsWith(String suffix) 760 { 761 return regionMatches (this.count - suffix.count, suffix, 0, suffix.count); 762 } 763 764 /** 765 * Computes the hashcode for this String. This is done with int arithmetic, 766 * where ** represents exponentiation, by this formula:<br> 767 * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>. 768 * 769 * @return hashcode value of this String 770 */ hashCode()771 public native int hashCode(); 772 773 /** 774 * Finds the first instance of a character in this String. 775 * 776 * @param ch character to find 777 * @return location (base 0) of the character, or -1 if not found 778 */ indexOf(int ch)779 public int indexOf(int ch) 780 { 781 return indexOf(ch, 0); 782 } 783 784 /** 785 * Finds the first instance of a character in this String, starting at 786 * a given index. If starting index is less than 0, the search 787 * starts at the beginning of this String. If the starting index 788 * is greater than the length of this String, -1 is returned. 789 * 790 * @param ch character to find 791 * @param fromIndex index to start the search 792 * @return location (base 0) of the character, or -1 if not found 793 */ indexOf(int ch, int fromIndex)794 public native int indexOf(int ch, int fromIndex); 795 796 /** 797 * Finds the last instance of a character in this String. 798 * 799 * @param ch character to find 800 * @return location (base 0) of the character, or -1 if not found 801 */ lastIndexOf(int ch)802 public int lastIndexOf(int ch) 803 { 804 return lastIndexOf(ch, count - 1); 805 } 806 807 /** 808 * Finds the last instance of a character in this String, starting at 809 * a given index. If starting index is greater than the maximum valid 810 * index, then the search begins at the end of this String. If the 811 * starting index is less than zero, -1 is returned. 812 * 813 * @param ch character to find 814 * @param fromIndex index to start the search 815 * @return location (base 0) of the character, or -1 if not found 816 */ lastIndexOf(int ch, int fromIndex)817 public native int lastIndexOf(int ch, int fromIndex); 818 819 /** 820 * Finds the first instance of a String in this String. 821 * 822 * @param str String to find 823 * @return location (base 0) of the String, or -1 if not found 824 * @throws NullPointerException if str is null 825 */ indexOf(String str)826 public int indexOf(String str) 827 { 828 return indexOf(str, 0); 829 } 830 831 /** 832 * Finds the first instance of a String in this String, starting at 833 * a given index. If starting index is less than 0, the search 834 * starts at the beginning of this String. If the starting index 835 * is greater than the length of this String, -1 is returned. 836 * 837 * @param str String to find 838 * @param fromIndex index to start the search 839 * @return location (base 0) of the String, or -1 if not found 840 * @throws NullPointerException if str is null 841 */ indexOf(String str, int fromIndex)842 public native int indexOf(String str, int fromIndex); 843 844 /** 845 * Finds the last instance of a String in this String. 846 * 847 * @param str String to find 848 * @return location (base 0) of the String, or -1 if not found 849 * @throws NullPointerException if str is null 850 */ lastIndexOf(String str)851 public int lastIndexOf(String str) 852 { 853 return lastIndexOf(str, count - str.count); 854 } 855 856 /** 857 * Finds the last instance of a String in this String, starting at 858 * a given index. If starting index is greater than the maximum valid 859 * index, then the search begins at the end of this String. If the 860 * starting index is less than zero, -1 is returned. 861 * 862 * @param str String to find 863 * @param fromIndex index to start the search 864 * @return location (base 0) of the String, or -1 if not found 865 * @throws NullPointerException if str is null 866 */ lastIndexOf(String str, int fromIndex)867 public int lastIndexOf(String str, int fromIndex) 868 { 869 if (fromIndex >= count) 870 fromIndex = count - str.count; 871 for (;; --fromIndex) 872 { 873 if (fromIndex < 0) 874 return -1; 875 if (startsWith(str, fromIndex)) 876 return fromIndex; 877 } 878 } 879 880 /** 881 * Creates a substring of this String, starting at a specified index 882 * and ending at the end of this String. 883 * 884 * @param begin index to start substring (base 0) 885 * @return new String which is a substring of this String 886 * @throws IndexOutOfBoundsException if begin < 0 || begin > length() 887 * (while unspecified, this is a StringIndexOutOfBoundsException) 888 */ substring(int begin)889 public String substring(int begin) 890 { 891 return substring(begin, count); 892 } 893 894 /** 895 * Creates a substring of this String, starting at a specified index 896 * and ending at one character before a specified index. 897 * 898 * @param begin index to start substring (inclusive, base 0) 899 * @param end index to end at (exclusive) 900 * @return new String which is a substring of this String 901 * @throws IndexOutOfBoundsException if begin < 0 || end > length() 902 * || begin > end (while unspecified, this is a 903 * StringIndexOutOfBoundsException) 904 */ substring(int begin, int end)905 public native String substring(int begin, int end); 906 907 /** 908 * Creates a substring of this String, starting at a specified index 909 * and ending at one character before a specified index. This behaves like 910 * <code>substring(begin, end)</code>. 911 * 912 * @param begin index to start substring (inclusive, base 0) 913 * @param end index to end at (exclusive) 914 * @return new String which is a substring of this String 915 * @throws IndexOutOfBoundsException if begin < 0 || end > length() 916 * || begin > end 917 * @since 1.4 918 */ subSequence(int begin, int end)919 public CharSequence subSequence(int begin, int end) 920 { 921 return substring(begin, end); 922 } 923 924 /** 925 * Concatenates a String to this String. This results in a new string unless 926 * one of the two originals is "". 927 * 928 * @param str String to append to this String 929 * @return newly concatenated String 930 * @throws NullPointerException if str is null 931 */ concat(String str)932 public native String concat(String str); 933 934 /** 935 * Replaces every instance of a character in this String with a new 936 * character. If no replacements occur, this is returned. 937 * 938 * @param oldChar the old character to replace 939 * @param newChar the new character 940 * @return new String with all instances of oldChar replaced with newChar 941 */ replace(char oldChar, char newChar)942 public native String replace(char oldChar, char newChar); 943 944 /** 945 * Test if this String matches a regular expression. This is shorthand for 946 * <code>{@link Pattern}.matches(regex, this)</code>. 947 * 948 * @param regex the pattern to match 949 * @return true if the pattern matches 950 * @throws NullPointerException if regex is null 951 * @throws PatternSyntaxException if regex is invalid 952 * @see Pattern#matches(String, CharSequence) 953 * @since 1.4 954 */ matches(String regex)955 public boolean matches(String regex) 956 { 957 return Pattern.matches(regex, this); 958 } 959 960 /** 961 * Replaces the first substring match of the regular expression with a 962 * given replacement. This is shorthand for <code>{@link Pattern} 963 * .compile(regex).matcher(this).replaceFirst(replacement)</code>. 964 * 965 * @param regex the pattern to match 966 * @param replacement the replacement string 967 * @return the modified string 968 * @throws NullPointerException if regex or replacement is null 969 * @throws PatternSyntaxException if regex is invalid 970 * @see #replaceAll(String, String) 971 * @see Pattern#compile(String) 972 * @see Pattern#matcher(CharSequence) 973 * @see Matcher#replaceFirst(String) 974 * @since 1.4 975 */ replaceFirst(String regex, String replacement)976 public String replaceFirst(String regex, String replacement) 977 { 978 return Pattern.compile(regex).matcher(this).replaceFirst(replacement); 979 } 980 981 /** 982 * Replaces all matching substrings of the regular expression with a 983 * given replacement. This is shorthand for <code>{@link Pattern} 984 * .compile(regex).matcher(this).replaceAll(replacement)</code>. 985 * 986 * @param regex the pattern to match 987 * @param replacement the replacement string 988 * @return the modified string 989 * @throws NullPointerException if regex or replacement is null 990 * @throws PatternSyntaxException if regex is invalid 991 * @see #replaceFirst(String, String) 992 * @see Pattern#compile(String) 993 * @see Pattern#matcher(CharSequence) 994 * @see Matcher#replaceAll(String) 995 * @since 1.4 996 */ replaceAll(String regex, String replacement)997 public String replaceAll(String regex, String replacement) 998 { 999 return Pattern.compile(regex).matcher(this).replaceAll(replacement); 1000 } 1001 1002 /** 1003 * Split this string around the matches of a regular expression. Each 1004 * element of the returned array is the largest block of characters not 1005 * terminated by the regular expression, in the order the matches are found. 1006 * 1007 * <p>The limit affects the length of the array. If it is positive, the 1008 * array will contain at most n elements (n - 1 pattern matches). If 1009 * negative, the array length is unlimited, but there can be trailing empty 1010 * entries. if 0, the array length is unlimited, and trailing empty entries 1011 * are discarded. 1012 * 1013 * <p>For example, splitting "boo:and:foo" yields:<br> 1014 * <table border=0> 1015 * <th><td>Regex</td> <td>Limit</td> <td>Result</td></th> 1016 * <tr><td>":"</td> <td>2</td> <td>{ "boo", "and:foo" }</td></tr> 1017 * <tr><td>":"</td> <td>t</td> <td>{ "boo", "and", "foo" }</td></tr> 1018 * <tr><td>":"</td> <td>-2</td> <td>{ "boo", "and", "foo" }</td></tr> 1019 * <tr><td>"o"</td> <td>5</td> <td>{ "b", "", ":and:f", "", "" }</td></tr> 1020 * <tr><td>"o"</td> <td>-2</td> <td>{ "b", "", ":and:f", "", "" }</td></tr> 1021 * <tr><td>"o"</td> <td>0</td> <td>{ "b", "", ":and:f" }</td></tr> 1022 * </table> 1023 * 1024 * <p>This is shorthand for 1025 * <code>{@link Pattern}.compile(regex).split(this, limit)</code>. 1026 * 1027 * @param regex the pattern to match 1028 * @param limit the limit threshold 1029 * @return the array of split strings 1030 * @throws NullPointerException if regex or replacement is null 1031 * @throws PatternSyntaxException if regex is invalid 1032 * @see Pattern#compile(String) 1033 * @see Pattern#split(CharSequence, int) 1034 * @since 1.4 1035 */ split(String regex, int limit)1036 public String[] split(String regex, int limit) 1037 { 1038 return Pattern.compile(regex).split(this, limit); 1039 } 1040 1041 /** 1042 * Split this string around the matches of a regular expression. Each 1043 * element of the returned array is the largest block of characters not 1044 * terminated by the regular expression, in the order the matches are found. 1045 * The array length is unlimited, and trailing empty entries are discarded, 1046 * as though calling <code>split(regex, 0)</code>. 1047 * 1048 * @param regex the pattern to match 1049 * @return the array of split strings 1050 * @throws NullPointerException if regex or replacement is null 1051 * @throws PatternSyntaxException if regex is invalid 1052 * @see #split(String, int) 1053 * @see Pattern#compile(String) 1054 * @see Pattern#split(CharSequence, int) 1055 * @since 1.4 1056 */ split(String regex)1057 public String[] split(String regex) 1058 { 1059 return Pattern.compile(regex).split(this, 0); 1060 } 1061 1062 /** 1063 * Lowercases this String according to a particular locale. This uses 1064 * Unicode's special case mappings, as applied to the given Locale, so the 1065 * resulting string may be a different length. 1066 * 1067 * @param loc locale to use 1068 * @return new lowercased String, or this if no characters were lowercased 1069 * @throws NullPointerException if loc is null 1070 * @see #toUpperCase(Locale) 1071 * @since 1.1 1072 */ toLowerCase(Locale locale)1073 public native String toLowerCase(Locale locale); 1074 1075 /** 1076 * Lowercases this String. This uses Unicode's special case mappings, as 1077 * applied to the platform's default Locale, so the resulting string may 1078 * be a different length. 1079 * 1080 * @return new lowercased String, or this if no characters were lowercased 1081 * @see #toLowerCase(Locale) 1082 * @see #toUpperCase() 1083 */ toLowerCase()1084 public String toLowerCase() 1085 { 1086 // The JDK is a bit confused about what to do here. If we pass in 1087 // the default Locale then special Locale handling might be 1088 // invoked. However, the docs also say that Character.toLowerCase 1089 // rules here. We go with the latter. 1090 return toLowerCase (null); 1091 } 1092 1093 /** 1094 * Uppercases this String according to a particular locale. This uses 1095 * Unicode's special case mappings, as applied to the given Locale, so the 1096 * resulting string may be a different length. 1097 * 1098 * @param loc locale to use 1099 * @return new uppercased String, or this if no characters were uppercased 1100 * @throws NullPointerException if loc is null 1101 * @see #toLowerCase(Locale) 1102 * @since 1.1 1103 */ toUpperCase(Locale locale)1104 public native String toUpperCase(Locale locale); 1105 1106 /** 1107 * Uppercases this String. This uses Unicode's special case mappings, as 1108 * applied to the platform's default Locale, so the resulting string may 1109 * be a different length. 1110 * 1111 * @return new uppercased String, or this if no characters were uppercased 1112 * @see #toUpperCase(Locale) 1113 * @see #toLowerCase() 1114 */ toUpperCase()1115 public String toUpperCase() 1116 { 1117 // The JDK is a bit confused about what to do here. If we pass in 1118 // the default Locale then special Locale handling might be 1119 // invoked. However, the docs also say that Character.toLowerCase 1120 // rules here. We go with the latter. 1121 return toUpperCase (null); 1122 } 1123 1124 /** 1125 * Trims all characters less than or equal to <code>'\u0020'</code> 1126 * (<code>' '</code>) from the beginning and end of this String. This 1127 * includes many, but not all, ASCII control characters, and all 1128 * {@link Character#isWhitespace(char)}. 1129 * 1130 * @return new trimmed String, or this if nothing trimmed 1131 */ trim()1132 public native String trim(); 1133 1134 /** 1135 * Returns this, as it is already a String! 1136 * 1137 * @return this 1138 */ toString()1139 public String toString() 1140 { 1141 return this; 1142 } 1143 1144 /** 1145 * Copies the contents of this String into a character array. Subsequent 1146 * changes to the array do not affect the String. 1147 * 1148 * @return character array copying the String 1149 */ toCharArray()1150 public native char[] toCharArray(); 1151 1152 /** 1153 * Returns a String representation of an Object. This is "null" if the 1154 * object is null, otherwise it is <code>obj.toString()</code> (which 1155 * can be null). 1156 * 1157 * @param obj the Object 1158 * @return the string conversion of obj 1159 */ valueOf(Object obj)1160 public static String valueOf(Object obj) 1161 { 1162 return obj == null ? "null" : obj.toString(); 1163 } 1164 1165 /** 1166 * Returns a String representation of a character array. Subsequent 1167 * changes to the array do not affect the String. 1168 * 1169 * @param data the character array 1170 * @return a String containing the same character sequence as data 1171 * @throws NullPointerException if data is null 1172 * @see #valueOf(char[], int, int) 1173 * @see #String(char[]) 1174 */ valueOf(char[] data)1175 public static String valueOf(char[] data) 1176 { 1177 return valueOf (data, 0, data.length); 1178 } 1179 1180 /** 1181 * Returns a String representing the character sequence of the char array, 1182 * starting at the specified offset, and copying chars up to the specified 1183 * count. Subsequent changes to the array do not affect the String. 1184 * 1185 * @param data character array 1186 * @param offset position (base 0) to start copying out of data 1187 * @param count the number of characters from data to copy 1188 * @return String containing the chars from data[offset..offset+count] 1189 * @throws NullPointerException if data is null 1190 * @throws IndexOutOfBoundsException if (offset < 0 || count < 0 1191 * || offset + count > data.length) 1192 * (while unspecified, this is a StringIndexOutOfBoundsException) 1193 * @see #String(char[], int, int) 1194 */ valueOf(char[] data, int offset, int count)1195 public static native String valueOf(char[] data, int offset, int count); 1196 1197 /** 1198 * Returns a String representing the character sequence of the char array, 1199 * starting at the specified offset, and copying chars up to the specified 1200 * count. Subsequent changes to the array do not affect the String. 1201 * 1202 * @param data character array 1203 * @param offset position (base 0) to start copying out of data 1204 * @param count the number of characters from data to copy 1205 * @return String containing the chars from data[offset..offset+count] 1206 * @throws NullPointerException if data is null 1207 * @throws IndexOutOfBoundsException if (offset < 0 || count < 0 1208 * || offset + count < 0 (overflow) 1209 * || offset + count > data.length) 1210 * (while unspecified, this is a StringIndexOutOfBoundsException) 1211 * @see #String(char[], int, int) 1212 */ copyValueOf(char[] data, int offset, int count)1213 public static String copyValueOf(char[] data, int offset, int count) 1214 { 1215 String r = new String (); 1216 r.init(data, offset, count, false); 1217 return r; 1218 } 1219 1220 /** 1221 * Returns a String representation of a character array. Subsequent 1222 * changes to the array do not affect the String. 1223 * 1224 * @param data the character array 1225 * @return a String containing the same character sequence as data 1226 * @throws NullPointerException if data is null 1227 * @see #copyValueOf(char[], int, int) 1228 * @see #String(char[]) 1229 */ copyValueOf(char[] data)1230 public static String copyValueOf(char[] data) 1231 { 1232 return copyValueOf (data, 0, data.length); 1233 } 1234 1235 /** 1236 * Returns a String representing a boolean. 1237 * 1238 * @param b the boolean 1239 * @return "true" if b is true, else "false" 1240 */ valueOf(boolean b)1241 public static String valueOf(boolean b) 1242 { 1243 return b ? "true" : "false"; 1244 } 1245 1246 /** 1247 * Returns a String representing a character. 1248 * 1249 * @param c the character 1250 * @return String containing the single character c 1251 */ valueOf(char c)1252 public static native String valueOf(char c); 1253 1254 /** 1255 * Returns a String representing an integer. 1256 * 1257 * @param i the integer 1258 * @return String containing the integer in base 10 1259 * @see Integer#toString(int) 1260 */ valueOf(int i)1261 public static native String valueOf(int i); 1262 1263 /** 1264 * Returns a String representing a long. 1265 * 1266 * @param l the long 1267 * @return String containing the long in base 10 1268 * @see Long#toString(long) 1269 */ valueOf(long l)1270 public static String valueOf(long l) 1271 { 1272 return Long.toString(l); 1273 } 1274 1275 /** 1276 * Returns a String representing a float. 1277 * 1278 * @param f the float 1279 * @return String containing the float 1280 * @see Float#toString(float) 1281 */ valueOf(float f)1282 public static String valueOf(float f) 1283 { 1284 return Float.toString(f); 1285 } 1286 1287 /** 1288 * Returns a String representing a double. 1289 * 1290 * @param d the double 1291 * @return String containing the double 1292 * @see Double#toString(double) 1293 */ valueOf(double d)1294 public static String valueOf(double d) 1295 { 1296 return Double.toString(d); 1297 } 1298 1299 1300 /** @since 1.5 */ format(Locale locale, String format, Object... args)1301 public static String format(Locale locale, String format, Object... args) 1302 { 1303 Formatter f = new Formatter(locale); 1304 return f.format(format, args).toString(); 1305 } 1306 1307 /** @since 1.5 */ format(String format, Object... args)1308 public static String format(String format, Object... args) 1309 { 1310 return format(Locale.getDefault(), format, args); 1311 } 1312 1313 /** 1314 * Fetches this String from the intern hashtable. 1315 * If two Strings are considered equal, by the equals() method, 1316 * then intern() will return the same String instance. ie. 1317 * if (s1.equals(s2)) then (s1.intern() == s2.intern()). 1318 * All string literals and string-valued constant expressions 1319 * are already interned. 1320 * 1321 * @return the interned String 1322 */ intern()1323 public native String intern(); 1324 1325 /** 1326 * Return the number of code points between two indices in the 1327 * <code>String</code>. An unpaired surrogate counts as a 1328 * code point for this purpose. Characters outside the indicated 1329 * range are not examined, even if the range ends in the middle of a 1330 * surrogate pair. 1331 * 1332 * @param start the starting index 1333 * @param end one past the ending index 1334 * @return the number of code points 1335 * @since 1.5 1336 */ codePointCount(int start, int end)1337 public synchronized int codePointCount(int start, int end) 1338 { 1339 if (start < 0 || end > count || start > end) 1340 throw new StringIndexOutOfBoundsException(); 1341 1342 int count = 0; 1343 while (start < end) 1344 { 1345 char base = charAt(start); 1346 if (base < Character.MIN_HIGH_SURROGATE 1347 || base > Character.MAX_HIGH_SURROGATE 1348 || start == end 1349 || start == count 1350 || charAt(start + 1) < Character.MIN_LOW_SURROGATE 1351 || charAt(start + 1) > Character.MAX_LOW_SURROGATE) 1352 { 1353 // Nothing. 1354 } 1355 else 1356 { 1357 // Surrogate pair. 1358 ++start; 1359 } 1360 ++start; 1361 ++count; 1362 } 1363 return count; 1364 } 1365 1366 /** 1367 * Returns true iff this String contains the sequence of Characters 1368 * described in s. 1369 * @param s the CharSequence 1370 * @return true iff this String contains s 1371 * 1372 * @since 1.5 1373 */ contains(CharSequence s)1374 public boolean contains (CharSequence s) 1375 { 1376 return this.indexOf(s.toString()) != -1; 1377 } 1378 1379 /** 1380 * Returns a string that is this string with all instances of the sequence 1381 * represented by <code>target</code> replaced by the sequence in 1382 * <code>replacement</code>. 1383 * @param target the sequence to be replaced 1384 * @param replacement the sequence used as the replacement 1385 * @return the string constructed as above 1386 */ replace(CharSequence target, CharSequence replacement)1387 public String replace (CharSequence target, CharSequence replacement) 1388 { 1389 String targetString = target.toString(); 1390 String replaceString = replacement.toString(); 1391 int targetLength = target.length(); 1392 int replaceLength = replacement.length(); 1393 1394 int startPos = this.indexOf(targetString); 1395 StringBuilder result = new StringBuilder(this); 1396 while (startPos != -1) 1397 { 1398 // Replace the target with the replacement 1399 result.replace(startPos, startPos + targetLength, replaceString); 1400 1401 // Search for a new occurrence of the target 1402 startPos = result.indexOf(targetString, startPos + replaceLength); 1403 } 1404 return result.toString(); 1405 } 1406 1407 /** 1408 * Return the index into this String that is offset from the given index by 1409 * <code>codePointOffset</code> code points. 1410 * @param index the index at which to start 1411 * @param codePointOffset the number of code points to offset 1412 * @return the index into this String that is <code>codePointOffset</code> 1413 * code points offset from <code>index</code>. 1414 * 1415 * @throws IndexOutOfBoundsException if index is negative or larger than the 1416 * length of this string. 1417 * @throws IndexOutOfBoundsException if codePointOffset is positive and the 1418 * substring starting with index has fewer than codePointOffset code points. 1419 * @throws IndexOutOfBoundsException if codePointOffset is negative and the 1420 * substring ending with index has fewer than (-codePointOffset) code points. 1421 * @since 1.5 1422 */ offsetByCodePoints(int index, int codePointOffset)1423 public int offsetByCodePoints(int index, int codePointOffset) 1424 { 1425 if (index < 0 || index > count) 1426 throw new IndexOutOfBoundsException(); 1427 1428 return Character.offsetByCodePoints(this, index, codePointOffset); 1429 } 1430 1431 /** 1432 * Returns true if, and only if, {@link #length()} 1433 * is <code>0</code>. 1434 * 1435 * @return true if the length of the string is zero. 1436 * @since 1.6 1437 */ isEmpty()1438 public boolean isEmpty() 1439 { 1440 return count == 0; 1441 } 1442 1443 // Generate a String that shares the value array: subsequent changes 1444 // to this array will affect the String. A private internal method 1445 // that is called from CPStringBuilder by compiler-generated code. toString(char[] value, int startIndex, int count)1446 private static String toString(char[] value, int startIndex, int count) 1447 { 1448 return new String(value, startIndex, count, true); 1449 } 1450 init(char[] chars, int offset, int count, boolean dont_copy)1451 private native void init(char[] chars, int offset, int count, 1452 boolean dont_copy); init(byte[] chars, int hibyte, int offset, int count)1453 private native void init(byte[] chars, int hibyte, int offset, int count); init(byte[] chars, int offset, int count, String enc)1454 private native void init(byte[] chars, int offset, int count, String enc) 1455 throws UnsupportedEncodingException; init(gnu.gcj.runtime.StringBuffer buffer)1456 private native void init(gnu.gcj.runtime.StringBuffer buffer); 1457 } 1458