fixes for host gcc 4.6.1
[zpugcc/jano.git] / toolchain / gcc / libjava / java / lang / String.java
blob6844405e34c525437009c6d998e402b0fd6dc4bc
1 /* String.java -- immutable character sequences; the object of string literals
2 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
3 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
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.
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.
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., 59 Temple Place, Suite 330, Boston, MA
20 02111-1307 USA.
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.
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. */
40 package java.lang;
42 import java.io.UnsupportedEncodingException;
43 import java.io.Serializable;
44 import java.lang.Comparable;
45 import java.util.Comparator;
46 import java.util.Locale;
47 import java.util.regex.Pattern;
48 import java.util.regex.PatternSyntaxException;
50 /**
51 * Strings represent an immutable set of characters. All String literals
52 * are instances of this class, and two string literals with the same contents
53 * refer to the same String object.
55 * <p>This class also includes a number of methods for manipulating the
56 * contents of strings (of course, creating a new object if there are any
57 * changes, as String is immutable). Case mapping relies on Unicode 3.0.0
58 * standards, where some character sequences have a different number of
59 * characters in the uppercase version than the lower case.
61 * <p>Strings are special, in that they are the only object with an overloaded
62 * operator. When you use '+' with at least one String argument, both
63 * arguments have String conversion performed on them, and another String (not
64 * guaranteed to be unique) results.
66 * <p>String is special-cased when doing data serialization - rather than
67 * listing the fields of this class, a String object is converted to a string
68 * literal in the object stream.
70 * @author Paul N. Fisher
71 * @author Eric Blake <ebb9@email.byu.edu>
72 * @author Per Bothner <bothner@cygnus.com>
73 * @since 1.0
74 * @status updated to 1.4
76 public final class String implements Serializable, Comparable, CharSequence
78 // WARNING: String is a CORE class in the bootstrap cycle. See the comments
79 // in vm/reference/java/lang/Runtime for implications of this fact.
81 /**
82 * This is probably not necessary because this class is special cased already
83 * but it will avoid showing up as a discrepancy when comparing SUIDs.
85 private static final long serialVersionUID = -6849794470754667710L;
87 /**
88 * This is the object that holds the characters that make up the
89 * String. It might be a char[], or it could be String. It could
90 * even be `this'. The actual characters can't be located using
91 * pure Java code.
92 * @see #boffset
94 private Object data;
96 /**
97 * This is a <emph>byte</emph> offset of the actual characters from
98 * the start of the character-holding object. Don't use this field
99 * in Java code.
101 private int boffset;
104 * Holds the number of characters in value. Package visible for use
105 * by trusted code.
107 int count;
110 * Caches the result of hashCode(). If this value is zero, the hashcode
111 * is considered uncached (even if 0 is the correct hash value).
113 private int cachedHashCode;
116 * An implementation for {@link CASE_INSENSITIVE_ORDER}.
117 * This must be {@link Serializable}. The class name is dictated by
118 * compatibility with Sun's JDK.
120 private static final class CaseInsensitiveComparator
121 implements Comparator, Serializable
124 * Compatible with JDK 1.2.
126 private static final long serialVersionUID = 8575799808933029326L;
129 * The default private constructor generates unnecessary overhead.
131 CaseInsensitiveComparator() {}
134 * Compares to Strings, using
135 * <code>String.compareToIgnoreCase(String)</code>.
137 * @param o1 the first string
138 * @param o2 the second string
139 * @return &lt; 0, 0, or &gt; 0 depending on the case-insensitive
140 * comparison of the two strings.
141 * @throws NullPointerException if either argument is null
142 * @throws ClassCastException if either argument is not a String
143 * @see #compareToIgnoreCase(String)
145 public int compare(Object o1, Object o2)
147 return ((String) o1).compareToIgnoreCase((String) o2);
149 } // class CaseInsensitiveComparator
152 * A Comparator that uses <code>String.compareToIgnoreCase(String)</code>.
153 * This comparator is {@link Serializable}. Note that it ignores Locale,
154 * for that, you want a Collator.
156 * @see Collator#compare(String, String)
157 * @since 1.2
159 public static final Comparator CASE_INSENSITIVE_ORDER
160 = new CaseInsensitiveComparator();
163 * Creates an empty String (length 0). Unless you really need a new object,
164 * consider using <code>""</code> instead.
166 public String()
168 data = "".data;
169 boffset = 0;
170 count = 0;
174 * Copies the contents of a String to a new String. Since Strings are
175 * immutable, only a shallow copy is performed.
177 * @param str String to copy
178 * @throws NullPointerException if value is null
180 public String(String str)
182 data = str.data;
183 boffset = str.boffset;
184 count = str.count;
185 cachedHashCode = str.cachedHashCode;
189 * Creates a new String using the character sequence of the char array.
190 * Subsequent changes to data do not affect the String.
192 * @param data char array to copy
193 * @throws NullPointerException if data is null
195 public String(char[] data)
197 init(data, 0, data.length, false);
201 * Creates a new String using the character sequence of a subarray of
202 * characters. The string starts at offset, and copies count chars.
203 * Subsequent changes to data do not affect the String.
205 * @param data char array to copy
206 * @param offset position (base 0) to start copying out of data
207 * @param count the number of characters from data to copy
208 * @throws NullPointerException if data is null
209 * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
210 * || offset + count > data.length)
211 * (while unspecified, this is a StringIndexOutOfBoundsException)
213 public String(char[] data, int offset, int count)
215 init(data, offset, count, false);
219 * Creates a new String using an 8-bit array of integer values, starting at
220 * an offset, and copying up to the count. Each character c, using
221 * corresponding byte b, is created in the new String as if by performing:
223 * <pre>
224 * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
225 * </pre>
227 * @param ascii array of integer values
228 * @param hibyte top byte of each Unicode character
229 * @param offset position (base 0) to start copying out of ascii
230 * @param count the number of characters from ascii to copy
231 * @throws NullPointerException if ascii is null
232 * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
233 * || offset + count > ascii.length)
234 * (while unspecified, this is a StringIndexOutOfBoundsException)
235 * @see #String(byte[])
236 * @see #String(byte[], String)
237 * @see #String(byte[], int, int)
238 * @see #String(byte[], int, int, String)
239 * @deprecated use {@link #String(byte[], int, int, String)} to perform
240 * correct encoding
242 public String(byte[] ascii, int hibyte, int offset, int count)
244 init(ascii, hibyte, offset, count);
248 * Creates a new String using an 8-bit array of integer values. Each
249 * character c, using corresponding byte b, is created in the new String
250 * as if by performing:
252 * <pre>
253 * c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
254 * </pre>
256 * @param ascii array of integer values
257 * @param hibyte top byte of each Unicode character
258 * @throws NullPointerException if ascii is null
259 * @see #String(byte[])
260 * @see #String(byte[], String)
261 * @see #String(byte[], int, int)
262 * @see #String(byte[], int, int, String)
263 * @see #String(byte[], int, int, int)
264 * @deprecated use {@link #String(byte[], String)} to perform
265 * correct encoding
267 public String(byte[] ascii, int hibyte)
269 init(ascii, hibyte, 0, ascii.length);
273 * Creates a new String using the portion of the byte array starting at the
274 * offset and ending at offset + count. Uses the specified encoding type
275 * to decode the byte array, so the resulting string may be longer or
276 * shorter than the byte array. For more decoding control, use
277 * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
278 * see {@link java.nio.charset.Charset}. The behavior is not specified if
279 * the decoder encounters invalid characters; this implementation throws
280 * an Error.
282 * @param data byte array to copy
283 * @param offset the offset to start at
284 * @param count the number of characters in the array to use
285 * @param encoding the name of the encoding to use
286 * @throws NullPointerException if data or encoding is null
287 * @throws IndexOutOfBoundsException if offset or count is incorrect
288 * (while unspecified, this is a StringIndexOutOfBoundsException)
289 * @throws UnsupportedEncodingException if encoding is not found
290 * @throws Error if the decoding fails
291 * @since 1.1
293 public String(byte[] data, int offset, int count, String encoding)
294 throws UnsupportedEncodingException
296 init (data, offset, count, encoding);
300 * Creates a new String using the byte array. Uses the specified encoding
301 * type to decode the byte array, so the resulting string may be longer or
302 * shorter than the byte array. For more decoding control, use
303 * {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
304 * see {@link java.nio.charset.Charset}. The behavior is not specified if
305 * the decoder encounters invalid characters; this implementation throws
306 * an Error.
308 * @param data byte array to copy
309 * @param encoding the name of the encoding to use
310 * @throws NullPointerException if data or encoding is null
311 * @throws UnsupportedEncodingException if encoding is not found
312 * @throws Error if the decoding fails
313 * @see #String(byte[], int, int, String)
314 * @since 1.1
316 public String(byte[] data, String encoding)
317 throws UnsupportedEncodingException
319 this(data, 0, data.length, encoding);
323 * Creates a new String using the portion of the byte array starting at the
324 * offset and ending at offset + count. Uses the encoding of the platform's
325 * default charset, so the resulting string may be longer or shorter than
326 * the byte array. For more decoding control, use
327 * {@link java.nio.charset.CharsetDecoder}. The behavior is not specified
328 * if the decoder encounters invalid characters; this implementation throws
329 * an Error.
331 * @param data byte array to copy
332 * @param offset the offset to start at
333 * @param count the number of characters in the array to use
334 * @throws NullPointerException if data is null
335 * @throws IndexOutOfBoundsException if offset or count is incorrect
336 * @throws Error if the decoding fails
337 * @see #String(byte[], int, int, String)
338 * @since 1.1
340 public String(byte[] data, int offset, int count)
344 init (data, offset, count,
345 System.getProperty("file.encoding", "8859_1"));
347 catch (UnsupportedEncodingException x1)
349 // Maybe the default encoding is bad.
352 init (data, offset, count, "8859_1");
354 catch (UnsupportedEncodingException x2)
356 // We know this can't happen.
362 * Creates a new String using the byte array. Uses the encoding of the
363 * platform's default charset, so the resulting string may be longer or
364 * shorter than the byte array. For more decoding control, use
365 * {@link java.nio.charset.CharsetDecoder}. The behavior is not specified
366 * if the decoder encounters invalid characters; this implementation throws
367 * an Error.
369 * @param data byte array to copy
370 * @throws NullPointerException if data is null
371 * @throws Error if the decoding fails
372 * @see #String(byte[], int, int)
373 * @see #String(byte[], int, int, String)
374 * @since 1.1
376 public String(byte[] data)
378 this(data, 0, data.length);
382 * Creates a new String using the character sequence represented by
383 * the StringBuffer. Subsequent changes to buf do not affect the String.
385 * @param buffer StringBuffer to copy
386 * @throws NullPointerException if buffer is null
388 public String(StringBuffer buffer)
390 synchronized (buffer)
392 // Share unless buffer is 3/4 empty.
393 boolean should_copy = ((buffer.count << 2) < buffer.value.length);
394 if (! should_copy)
395 buffer.shared = true;
396 init (buffer.value, 0, buffer.count, ! should_copy);
401 * Special constructor which can share an array when safe to do so.
403 * @param data the characters to copy
404 * @param offset the location to start from
405 * @param count the number of characters to use
406 * @param dont_copy true if the array is trusted, and need not be copied
407 * @throws NullPointerException if chars is null
408 * @throws StringIndexOutOfBoundsException if bounds check fails
410 String(char[] data, int offset, int count, boolean dont_copy)
412 init(data, offset, count, dont_copy);
415 // This is used by gnu.gcj.runtime.StringBuffer, so it must have
416 // package-private protection. It is accessed via CNI and so avoids
417 // ordinary protection mechanisms.
418 String(gnu.gcj.runtime.StringBuffer buffer)
420 // No need to synchronize or mark the buffer, since we know it is
421 // only used once.
422 init (buffer);
426 * Returns the number of characters contained in this String.
428 * @return the length of this String
430 public int length()
432 return count;
436 * Returns the character located at the specified index within this String.
438 * @param index position of character to return (base 0)
439 * @return character located at position index
440 * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= length()
441 * (while unspecified, this is a StringIndexOutOfBoundsException)
443 public native char charAt(int index);
446 * Copies characters from this String starting at a specified start index,
447 * ending at a specified stop index, to a character array starting at
448 * a specified destination begin index.
450 * @param srcBegin index to begin copying characters from this String
451 * @param srcEnd index after the last character to be copied from this String
452 * @param dst character array which this String is copied into
453 * @param dstBegin index to start writing characters into dst
454 * @throws NullPointerException if dst is null
455 * @throws IndexOutOfBoundsException if any indices are out of bounds
456 * (while unspecified, source problems cause a
457 * StringIndexOutOfBoundsException, and dst problems cause an
458 * ArrayIndexOutOfBoundsException)
460 public native void getChars(int srcBegin, int srcEnd,
461 char[] dst, int dstBegin);
464 * Copies the low byte of each character from this String starting at a
465 * specified start index, ending at a specified stop index, to a byte array
466 * starting at a specified destination begin index.
468 * @param srcBegin index to being copying characters from this String
469 * @param srcEnd index after the last character to be copied from this String
470 * @param dst byte array which each low byte of this String is copied into
471 * @param dstBegin index to start writing characters into dst
472 * @throws NullPointerException if dst is null and copy length is non-zero
473 * @throws IndexOutOfBoundsException if any indices are out of bounds
474 * (while unspecified, source problems cause a
475 * StringIndexOutOfBoundsException, and dst problems cause an
476 * ArrayIndexOutOfBoundsException)
477 * @see #getBytes()
478 * @see #getBytes(String)
479 * @deprecated use {@link #getBytes()}, which uses a char to byte encoder
481 public native void getBytes(int srcBegin, int srcEnd,
482 byte[] dst, int dstBegin);
485 * Converts the Unicode characters in this String to a byte array. Uses the
486 * specified encoding method, so the result may be longer or shorter than
487 * the String. For more encoding control, use
488 * {@link java.nio.charset.CharsetEncoder}, and for valid character sets,
489 * see {@link java.nio.charset.Charset}. The behavior is not specified if
490 * the encoder encounters a problem; this implementation returns null.
492 * @param enc encoding name
493 * @return the resulting byte array, or null on a problem
494 * @throws NullPointerException if enc is null
495 * @throws UnsupportedEncodingException if encoding is not supported
496 * @since 1.1
498 public native byte[] getBytes(String enc)
499 throws UnsupportedEncodingException;
502 * Converts the Unicode characters in this String to a byte array. Uses the
503 * encoding of the platform's default charset, so the result may be longer
504 * or shorter than the String. For more encoding control, use
505 * {@link java.nio.charset.CharsetEncoder}. The behavior is not specified if
506 * the encoder encounters a problem; this implementation returns null.
508 * @return the resulting byte array, or null on a problem
509 * @since 1.1
511 public byte[] getBytes()
515 return getBytes (System.getProperty("file.encoding", "8859_1"));
517 catch (UnsupportedEncodingException x)
519 // This probably shouldn't happen, but could if file.encoding
520 // is somehow changed to a value we don't understand.
523 return getBytes ("8859_1");
525 catch (UnsupportedEncodingException x2)
527 // This really shouldn't happen, because the 8859_1
528 // encoding should always be available.
529 throw new InternalError ("couldn't find 8859_1 encoder");
535 * Predicate which compares anObject to this. This is true only for Strings
536 * with the same character sequence.
538 * @param anObject the object to compare
539 * @return true if anObject is semantically equal to this
540 * @see #compareTo(String)
541 * @see #equalsIgnoreCase(String)
543 public native boolean equals(Object anObject);
546 * Compares the given StringBuffer to this String. This is true if the
547 * StringBuffer has the same content as this String at this moment.
549 * @param buffer the StringBuffer to compare to
550 * @return true if StringBuffer has the same character sequence
551 * @throws NullPointerException if the given StringBuffer is null
552 * @since 1.4
554 public native boolean contentEquals(StringBuffer buffer);
557 * Compares a String to this String, ignoring case. This does not handle
558 * multi-character capitalization exceptions; instead the comparison is
559 * made on a character-by-character basis, and is true if:<br><ul>
560 * <li><code>c1 == c2</code></li>
561 * <li><code>Character.toUpperCase(c1)
562 * == Character.toUpperCase(c2)</code></li>
563 * <li><code>Character.toLowerCase(c1)
564 * == Character.toLowerCase(c2)</code></li>
565 * </ul>
567 * @param anotherString String to compare to this String
568 * @return true if anotherString is equal, ignoring case
569 * @see #equals(Object)
570 * @see Character#toUpperCase(char)
571 * @see Character#toLowerCase(char)
573 public native boolean equalsIgnoreCase(String anotherString);
576 * Compares this String and another String (case sensitive,
577 * lexicographically). The result is less than 0 if this string sorts
578 * before the other, 0 if they are equal, and greater than 0 otherwise.
579 * After any common starting sequence is skipped, the result is
580 * <code>this.charAt(k) - anotherString.charAt(k)</code> if both strings
581 * have characters remaining, or
582 * <code>this.length() - anotherString.length()</code> if one string is
583 * a subsequence of the other.
585 * @param anotherString the String to compare against
586 * @return the comparison
587 * @throws NullPointerException if anotherString is null
589 public native int compareTo(String anotherString);
592 * Behaves like <code>compareTo(java.lang.String)</code> unless the Object
593 * is not a <code>String</code>. Then it throws a
594 * <code>ClassCastException</code>.
596 * @param o the object to compare against
597 * @return the comparison
598 * @throws NullPointerException if o is null
599 * @throws ClassCastException if o is not a <code>String</code>
600 * @since 1.2
602 public int compareTo(Object o)
604 return compareTo((String) o);
608 * Compares this String and another String (case insensitive). This
609 * comparison is <em>similar</em> to equalsIgnoreCase, in that it ignores
610 * locale and multi-characater capitalization, and compares characters
611 * after performing
612 * <code>Character.toLowerCase(Character.toUpperCase(c))</code> on each
613 * character of the string. This is unsatisfactory for locale-based
614 * comparison, in which case you should use {@link java.text.Collator}.
616 * @param s the string to compare against
617 * @return the comparison
618 * @see Collator#compare(String, String)
619 * @since 1.2
621 public int compareToIgnoreCase(String str)
623 return this.toUpperCase().toLowerCase().compareTo(
624 str.toUpperCase().toLowerCase());
628 * Predicate which determines if this String matches another String
629 * starting at a specified offset for each String and continuing
630 * for a specified length. Indices out of bounds are harmless, and give
631 * a false result.
633 * @param toffset index to start comparison at for this String
634 * @param other String to compare region to this String
635 * @param oofset index to start comparison at for other
636 * @param len number of characters to compare
637 * @return true if regions match (case sensitive)
638 * @throws NullPointerException if other is null
640 public native boolean regionMatches(int toffset,
641 String other, int ooffset, int len);
644 * Predicate which determines if this String matches another String
645 * starting at a specified offset for each String and continuing
646 * for a specified length, optionally ignoring case. Indices out of bounds
647 * are harmless, and give a false result. Case comparisons are based on
648 * <code>Character.toLowerCase()</code> and
649 * <code>Character.toUpperCase()</code>, not on multi-character
650 * capitalization expansions.
652 * @param ignoreCase true if case should be ignored in comparision
653 * @param toffset index to start comparison at for this String
654 * @param other String to compare region to this String
655 * @param oofset index to start comparison at for other
656 * @param len number of characters to compare
657 * @return true if regions match, false otherwise
658 * @throws NullPointerException if other is null
660 public native boolean regionMatches(boolean ignoreCase, int toffset,
661 String other, int ooffset, int len);
664 * Predicate which determines if this String contains the given prefix,
665 * beginning comparison at toffset. The result is false if toffset is
666 * negative or greater than this.length(), otherwise it is the same as
667 * <code>this.subString(toffset).startsWith(prefix)</code>.
669 * @param prefix String to compare
670 * @param toffset offset for this String where comparison starts
671 * @return true if this String starts with prefix
672 * @throws NullPointerException if prefix is null
673 * @see #regionMatches(boolean, int, String, int, int)
675 public native boolean startsWith(String prefix, int toffset);
678 * Predicate which determines if this String starts with a given prefix.
679 * If the prefix is an empty String, true is returned.
681 * @param prefex String to compare
682 * @return true if this String starts with the prefix
683 * @throws NullPointerException if prefix is null
684 * @see #startsWith(String, int)
686 public boolean startsWith(String prefix)
688 return startsWith (prefix, 0);
692 * Predicate which determines if this String ends with a given suffix.
693 * If the suffix is an empty String, true is returned.
695 * @param suffix String to compare
696 * @return true if this String ends with the suffix
697 * @throws NullPointerException if suffix is null
698 * @see #regionMatches(boolean, int, String, int, int)
700 public boolean endsWith(String suffix)
702 return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
706 * Computes the hashcode for this String. This is done with int arithmetic,
707 * where ** represents exponentiation, by this formula:<br>
708 * <code>s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1]</code>.
710 * @return hashcode value of this String
712 public native int hashCode();
715 * Finds the first instance of a character in this String.
717 * @param ch character to find
718 * @return location (base 0) of the character, or -1 if not found
720 public int indexOf(int ch)
722 return indexOf(ch, 0);
726 * Finds the first instance of a character in this String, starting at
727 * a given index. If starting index is less than 0, the search
728 * starts at the beginning of this String. If the starting index
729 * is greater than the length of this String, -1 is returned.
731 * @param ch character to find
732 * @param fromIndex index to start the search
733 * @return location (base 0) of the character, or -1 if not found
735 public native int indexOf(int ch, int fromIndex);
738 * Finds the last instance of a character in this String.
740 * @param ch character to find
741 * @return location (base 0) of the character, or -1 if not found
743 public int lastIndexOf(int ch)
745 return lastIndexOf(ch, count - 1);
749 * Finds the last instance of a character in this String, starting at
750 * a given index. If starting index is greater than the maximum valid
751 * index, then the search begins at the end of this String. If the
752 * starting index is less than zero, -1 is returned.
754 * @param ch character to find
755 * @param fromIndex index to start the search
756 * @return location (base 0) of the character, or -1 if not found
758 public native int lastIndexOf(int ch, int fromIndex);
761 * Finds the first instance of a String in this String.
763 * @param str String to find
764 * @return location (base 0) of the String, or -1 if not found
765 * @throws NullPointerException if str is null
767 public int indexOf(String str)
769 return indexOf(str, 0);
773 * Finds the first instance of a String in this String, starting at
774 * a given index. If starting index is less than 0, the search
775 * starts at the beginning of this String. If the starting index
776 * is greater than the length of this String, -1 is returned.
778 * @param str String to find
779 * @param fromIndex index to start the search
780 * @return location (base 0) of the String, or -1 if not found
781 * @throws NullPointerException if str is null
783 public native int indexOf(String str, int fromIndex);
786 * Finds the last instance of a String in this String.
788 * @param str String to find
789 * @return location (base 0) of the String, or -1 if not found
790 * @throws NullPointerException if str is null
792 public int lastIndexOf(String str)
794 return lastIndexOf(str, count - str.count);
798 * Finds the last instance of a String in this String, starting at
799 * a given index. If starting index is greater than the maximum valid
800 * index, then the search begins at the end of this String. If the
801 * starting index is less than zero, -1 is returned.
803 * @param str String to find
804 * @param fromIndex index to start the search
805 * @return location (base 0) of the String, or -1 if not found
806 * @throws NullPointerException if str is null
808 public int lastIndexOf(String str, int fromIndex)
810 if (fromIndex >= count)
811 fromIndex = count - str.count;
812 for (;; --fromIndex)
814 if (fromIndex < 0)
815 return -1;
816 if (startsWith(str, fromIndex))
817 return fromIndex;
822 * Creates a substring of this String, starting at a specified index
823 * and ending at the end of this String.
825 * @param begin index to start substring (base 0)
826 * @return new String which is a substring of this String
827 * @throws IndexOutOfBoundsException if begin &lt; 0 || begin &gt; length()
828 * (while unspecified, this is a StringIndexOutOfBoundsException)
830 public String substring(int begin)
832 return substring(begin, count);
836 * Creates a substring of this String, starting at a specified index
837 * and ending at one character before a specified index.
839 * @param begin index to start substring (inclusive, base 0)
840 * @param end index to end at (exclusive)
841 * @return new String which is a substring of this String
842 * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
843 * || begin > end (while unspecified, this is a
844 * StringIndexOutOfBoundsException)
846 public native String substring(int beginIndex, int endIndex);
849 * Creates a substring of this String, starting at a specified index
850 * and ending at one character before a specified index. This behaves like
851 * <code>substring(beginIndex, endIndex)</code>.
853 * @param beginIndex index to start substring (inclusive, base 0)
854 * @param endIndex index to end at (exclusive)
855 * @return new String which is a substring of this String
856 * @throws IndexOutOfBoundsException if begin &lt; 0 || end &gt; length()
857 * || begin > end
858 * @since 1.4
860 public CharSequence subSequence(int beginIndex, int endIndex)
862 return substring(beginIndex, endIndex);
866 * Concatenates a String to this String. This results in a new string unless
867 * one of the two originals is "".
869 * @param str String to append to this String
870 * @return newly concatenated String
871 * @throws NullPointerException if str is null
873 public native String concat(String str);
876 * Replaces every instance of a character in this String with a new
877 * character. If no replacements occur, this is returned.
879 * @param oldChar the old character to replace
880 * @param newChar the new character
881 * @return new String with all instances of oldChar replaced with newChar
883 public native String replace(char oldChar, char newChar);
886 * Test if this String matches a regular expression. This is shorthand for
887 * <code>{@link Pattern}.matches(regex, this)</code>.
889 * @param regex the pattern to match
890 * @return true if the pattern matches
891 * @throws NullPointerException if regex is null
892 * @throws PatternSyntaxException if regex is invalid
893 * @see Pattern#matches(String, CharSequence)
894 * @since 1.4
896 public boolean matches(String regex)
898 return Pattern.matches(regex, this);
902 * Replaces the first substring match of the regular expression with a
903 * given replacement. This is shorthand for <code>{@link Pattern}
904 * .compile(regex).matcher(this).replaceFirst(replacement)</code>.
906 * @param regex the pattern to match
907 * @param replacement the replacement string
908 * @return the modified string
909 * @throws NullPointerException if regex or replacement is null
910 * @throws PatternSyntaxException if regex is invalid
911 * @see #replaceAll(String, String)
912 * @see Pattern#compile(String)
913 * @see Pattern#matcher(CharSequence)
914 * @see Matcher#replaceFirst(String)
915 * @since 1.4
917 public String replaceFirst(String regex, String replacement)
919 return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
923 * Replaces all matching substrings of the regular expression with a
924 * given replacement. This is shorthand for <code>{@link Pattern}
925 * .compile(regex).matcher(this).replaceAll(replacement)</code>.
927 * @param regex the pattern to match
928 * @param replacement the replacement string
929 * @return the modified string
930 * @throws NullPointerException if regex or replacement is null
931 * @throws PatternSyntaxException if regex is invalid
932 * @see #replaceFirst(String, String)
933 * @see Pattern#compile(String)
934 * @see Pattern#matcher(CharSequence)
935 * @see Matcher#replaceAll(String)
936 * @since 1.4
938 public String replaceAll(String regex, String replacement)
940 return Pattern.compile(regex).matcher(this).replaceAll(replacement);
944 * Split this string around the matches of a regular expression. Each
945 * element of the returned array is the largest block of characters not
946 * terminated by the regular expression, in the order the matches are found.
948 * <p>The limit affects the length of the array. If it is positive, the
949 * array will contain at most n elements (n - 1 pattern matches). If
950 * negative, the array length is unlimited, but there can be trailing empty
951 * entries. if 0, the array length is unlimited, and trailing empty entries
952 * are discarded.
954 * <p>For example, splitting "boo:and:foo" yields:<br>
955 * <table border=0>
956 * <th><td>Regex</td> <td>Limit</td> <td>Result</td></th>
957 * <tr><td>":"</td> <td>2</td> <td>{ "boo", "and:foo" }</td></tr>
958 * <tr><td>":"</td> <td>t</td> <td>{ "boo", "and", "foo" }</td></tr>
959 * <tr><td>":"</td> <td>-2</td> <td>{ "boo", "and", "foo" }</td></tr>
960 * <tr><td>"o"</td> <td>5</td> <td>{ "b", "", ":and:f", "", "" }</td></tr>
961 * <tr><td>"o"</td> <td>-2</td> <td>{ "b", "", ":and:f", "", "" }</td></tr>
962 * <tr><td>"o"</td> <td>0</td> <td>{ "b", "", ":and:f" }</td></tr>
963 * </table>
965 * <p>This is shorthand for
966 * <code>{@link Pattern}.compile(regex).split(this, limit)</code>.
968 * @param regex the pattern to match
969 * @param limit the limit threshold
970 * @return the array of split strings
971 * @throws NullPointerException if regex or replacement is null
972 * @throws PatternSyntaxException if regex is invalid
973 * @see Pattern#compile(String)
974 * @see Pattern#split(CharSequence, int)
975 * @since 1.4
977 public String[] split(String regex, int limit)
979 return Pattern.compile(regex).split(this, limit);
983 * Split this string around the matches of a regular expression. Each
984 * element of the returned array is the largest block of characters not
985 * terminated by the regular expression, in the order the matches are found.
986 * The array length is unlimited, and trailing empty entries are discarded,
987 * as though calling <code>split(regex, 0)</code>.
989 * @param regex the pattern to match
990 * @return the array of split strings
991 * @throws NullPointerException if regex or replacement is null
992 * @throws PatternSyntaxException if regex is invalid
993 * @see #split(String, int)
994 * @see Pattern#compile(String)
995 * @see Pattern#split(CharSequence, int)
996 * @since 1.4
998 public String[] split(String regex)
1000 return Pattern.compile(regex).split(this, 0);
1004 * Lowercases this String according to a particular locale. This uses
1005 * Unicode's special case mappings, as applied to the given Locale, so the
1006 * resulting string may be a different length.
1008 * @param loc locale to use
1009 * @return new lowercased String, or this if no characters were lowercased
1010 * @throws NullPointerException if loc is null
1011 * @see #toUpperCase(Locale)
1012 * @since 1.1
1014 public native String toLowerCase(Locale locale);
1017 * Lowercases this String. This uses Unicode's special case mappings, as
1018 * applied to the platform's default Locale, so the resulting string may
1019 * be a different length.
1021 * @return new lowercased String, or this if no characters were lowercased
1022 * @see #toLowerCase(Locale)
1023 * @see #toUpperCase()
1025 public String toLowerCase()
1027 // The JDK is a bit confused about what to do here. If we pass in
1028 // the default Locale then special Locale handling might be
1029 // invoked. However, the docs also say that Character.toLowerCase
1030 // rules here. We go with the latter.
1031 return toLowerCase (null);
1035 * Uppercases this String according to a particular locale. This uses
1036 * Unicode's special case mappings, as applied to the given Locale, so the
1037 * resulting string may be a different length.
1039 * @param loc locale to use
1040 * @return new uppercased String, or this if no characters were uppercased
1041 * @throws NullPointerException if loc is null
1042 * @see #toLowerCase(Locale)
1043 * @since 1.1
1045 public native String toUpperCase(Locale locale);
1048 * Uppercases this String. This uses Unicode's special case mappings, as
1049 * applied to the platform's default Locale, so the resulting string may
1050 * be a different length.
1052 * @return new uppercased String, or this if no characters were uppercased
1053 * @see #toUpperCase(Locale)
1054 * @see #toLowerCase()
1056 public String toUpperCase()
1058 // The JDK is a bit confused about what to do here. If we pass in
1059 // the default Locale then special Locale handling might be
1060 // invoked. However, the docs also say that Character.toLowerCase
1061 // rules here. We go with the latter.
1062 return toUpperCase (null);
1066 * Trims all characters less than or equal to <code>'\u0020'</code>
1067 * (<code>' '</code>) from the beginning and end of this String. This
1068 * includes many, but not all, ASCII control characters, and all
1069 * {@link Character#whitespace(char)}.
1071 * @return new trimmed String, or this if nothing trimmed
1073 public native String trim();
1076 * Returns this, as it is already a String!
1078 * @return this
1080 public String toString()
1082 return this;
1086 * Copies the contents of this String into a character array. Subsequent
1087 * changes to the array do not affect the String.
1089 * @return character array copying the String
1091 public native char[] toCharArray();
1094 * Returns a String representation of an Object. This is "null" if the
1095 * object is null, otherwise it is <code>obj.toString()</code> (which
1096 * can be null).
1098 * @param obj the Object
1099 * @return the string conversion of obj
1101 public static String valueOf(Object obj)
1103 return obj == null ? "null" : obj.toString();
1107 * Returns a String representation of a character array. Subsequent
1108 * changes to the array do not affect the String.
1110 * @param data the character array
1111 * @return a String containing the same character sequence as data
1112 * @throws NullPointerException if data is null
1113 * @see #valueOf(char[], int, int)
1114 * @see #String(char[])
1116 public static String valueOf(char[] data)
1118 return valueOf (data, 0, data.length);
1122 * Returns a String representing the character sequence of the char array,
1123 * starting at the specified offset, and copying chars up to the specified
1124 * count. Subsequent changes to the array do not affect the String.
1126 * @param data character array
1127 * @param offset position (base 0) to start copying out of data
1128 * @param count the number of characters from data to copy
1129 * @return String containing the chars from data[offset..offset+count]
1130 * @throws NullPointerException if data is null
1131 * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1132 * || offset + count > data.length)
1133 * (while unspecified, this is a StringIndexOutOfBoundsException)
1134 * @see #String(char[], int, int)
1136 public static native String valueOf(char[] data, int offset, int count);
1139 * Returns a String representing the character sequence of the char array,
1140 * starting at the specified offset, and copying chars up to the specified
1141 * count. Subsequent changes to the array do not affect the String.
1143 * @param data character array
1144 * @param offset position (base 0) to start copying out of data
1145 * @param count the number of characters from data to copy
1146 * @return String containing the chars from data[offset..offset+count]
1147 * @throws NullPointerException if data is null
1148 * @throws IndexOutOfBoundsException if (offset &lt; 0 || count &lt; 0
1149 * || offset + count > data.length)
1150 * (while unspecified, this is a StringIndexOutOfBoundsException)
1151 * @see #String(char[], int, int)
1153 public static String copyValueOf(char[] data, int offset, int count)
1155 String r = new String ();
1156 r.init(data, offset, count, false);
1157 return r;
1161 * Returns a String representation of a character array. Subsequent
1162 * changes to the array do not affect the String.
1164 * @param data the character array
1165 * @return a String containing the same character sequence as data
1166 * @throws NullPointerException if data is null
1167 * @see #copyValueOf(char[], int, int)
1168 * @see #String(char[])
1170 public static String copyValueOf(char[] data)
1172 return copyValueOf (data, 0, data.length);
1176 * Returns a String representing a boolean.
1178 * @param b the boolean
1179 * @return "true" if b is true, else "false"
1181 public static String valueOf(boolean b)
1183 return b ? "true" : "false";
1187 * Returns a String representing a character.
1189 * @param c the character
1190 * @return String containing the single character c
1192 public static native String valueOf(char c);
1195 * Returns a String representing an integer.
1197 * @param i the integer
1198 * @return String containing the integer in base 10
1199 * @see Integer#toString(int)
1201 public static native String valueOf(int i);
1204 * Returns a String representing a long.
1206 * @param l the long
1207 * @return String containing the long in base 10
1208 * @see Long#toString(long)
1210 public static String valueOf(long l)
1212 return Long.toString(l);
1216 * Returns a String representing a float.
1218 * @param f the float
1219 * @return String containing the float
1220 * @see Float#toString(float)
1222 public static String valueOf(float f)
1224 return Float.toString(f);
1228 * Returns a String representing a double.
1230 * @param d the double
1231 * @return String containing the double
1232 * @see Double#toString(double)
1234 public static String valueOf(double d)
1236 return Double.toString(d);
1240 * Fetches this String from the intern hashtable. If two Strings are
1241 * considered equal, by the equals() method, then intern() will return the
1242 * same String instance. ie. if (s1.equals(s2)) then
1243 * (s1.intern() == s2.intern()). All string literals and string-valued
1244 * constant expressions are already interned.
1246 * @return the interned String
1248 public native String intern();
1251 private native void init(char[] chars, int offset, int count,
1252 boolean dont_copy);
1253 private native void init(byte[] chars, int hibyte, int offset, int count);
1254 private native void init(byte[] chars, int offset, int count, String enc)
1255 throws UnsupportedEncodingException;
1256 private native void init(gnu.gcj.runtime.StringBuffer buffer);
1257 private static native void rehash();