This class also includes a number of methods for manipulating the * contents of strings (of course, creating a new object if there are any * changes, as String is immutable). Case mapping relies on Unicode 3.0.0 * standards, where some character sequences have a different number of * characters in the uppercase version than the lower case. * *
Strings are special, in that they are the only object with an overloaded * operator. When you use '+' with at least one String argument, both * arguments have String conversion performed on them, and another String (not * guaranteed to be unique) results. * *
String is special-cased when doing data serialization - rather than
* listing the fields of this class, a String object is converted to a string
* literal in the object stream.
*
* @author Paul N. Fisher
* @author Eric Blake (ebb9@email.byu.edu)
* @author Per Bothner (bothner@cygnus.com)
* @author Tom Tromey (tromey@redhat.com)
* @author Andrew John Hughes (gnu_andrew@member.fsf.org)
* @since 1.0
* @status updated to 1.4
*/
public final class String
implements Serializable, Comparable The limit affects the length of the array. If it is positive, the
* array will contain at most n elements (n - 1 pattern matches). If
* negative, the array length is unlimited, but there can be trailing empty
* entries. if 0, the array length is unlimited, and trailing empty entries
* are discarded.
*
* For example, splitting "boo:and:foo" yields: This is shorthand for
* String.compareToIgnoreCase(String).
*
* @param o1 the first string
* @param o2 the second string
* @return < 0, 0, or > 0 depending on the case-insensitive
* comparison of the two strings.
* @throws NullPointerException if either argument is null
* @throws ClassCastException if either argument is not a String
* @see #compareToIgnoreCase(String)
*/
public int compare(String o1, String o2)
{
return o1.compareToIgnoreCase(o2);
}
} // class CaseInsensitiveComparator
/**
* A Comparator that uses String.compareToIgnoreCase(String).
* This comparator is {@link Serializable}. Note that it ignores Locale,
* for that, you want a Collator.
*
* @see Collator#compare(String, String)
* @since 1.2
*/
public static final Comparator"" instead.
*/
public String()
{
data = "".data;
boffset = 0;
count = 0;
}
/**
* Copies the contents of a String to a new String. Since Strings are
* immutable, only a shallow copy is performed.
*
* @param str String to copy
* @throws NullPointerException if value is null
*/
public String(String str)
{
data = str.data;
boffset = str.boffset;
count = str.count;
cachedHashCode = str.cachedHashCode;
}
/**
* Creates a new String using the character sequence of the char array.
* Subsequent changes to data do not affect the String.
*
* @param data char array to copy
* @throws NullPointerException if data is null
*/
public String(char[] data)
{
init(data, 0, data.length, false);
}
/**
* Creates a new String using the character sequence of a subarray of
* characters. The string starts at offset, and copies count chars.
* Subsequent changes to data do not affect the String.
*
* @param data char array to copy
* @param offset position (base 0) to start copying out of data
* @param count the number of characters from data to copy
* @throws NullPointerException if data is null
* @throws IndexOutOfBoundsException if (offset < 0 || count < 0
* || offset + count < 0 (overflow)
* || offset + count > data.length)
* (while unspecified, this is a StringIndexOutOfBoundsException)
*/
public String(char[] data, int offset, int count)
{
init(data, offset, count, false);
}
/**
* Creates a new String using an 8-bit array of integer values, starting at
* an offset, and copying up to the count. Each character c, using
* corresponding byte b, is created in the new String as if by performing:
*
*
* c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
*
*
* @param ascii array of integer values
* @param hibyte top byte of each Unicode character
* @param offset position (base 0) to start copying out of ascii
* @param count the number of characters from ascii to copy
* @throws NullPointerException if ascii is null
* @throws IndexOutOfBoundsException if (offset < 0 || count < 0
* || offset + count < 0 (overflow)
* || offset + count > ascii.length)
* (while unspecified, this is a StringIndexOutOfBoundsException)
* @see #String(byte[])
* @see #String(byte[], String)
* @see #String(byte[], int, int)
* @see #String(byte[], int, int, String)
* @deprecated use {@link #String(byte[], int, int, String)} to perform
* correct encoding
*/
public String(byte[] ascii, int hibyte, int offset, int count)
{
init(ascii, hibyte, offset, count);
}
/**
* Creates a new String using an 8-bit array of integer values. Each
* character c, using corresponding byte b, is created in the new String
* as if by performing:
*
*
* c = (char) (((hibyte & 0xff) << 8) | (b & 0xff))
*
*
* @param ascii array of integer values
* @param hibyte top byte of each Unicode character
* @throws NullPointerException if ascii is null
* @see #String(byte[])
* @see #String(byte[], String)
* @see #String(byte[], int, int)
* @see #String(byte[], int, int, String)
* @see #String(byte[], int, int, int)
* @deprecated use {@link #String(byte[], String)} to perform
* correct encoding
*/
public String(byte[] ascii, int hibyte)
{
init(ascii, hibyte, 0, ascii.length);
}
/**
* Creates a new String using the portion of the byte array starting at the
* offset and ending at offset + count. Uses the specified encoding type
* to decode the byte array, so the resulting string may be longer or
* shorter than the byte array. For more decoding control, use
* {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
* see {@link java.nio.charset.Charset}. The behavior is not specified if
* the decoder encounters invalid characters; this implementation throws
* an Error.
*
* @param data byte array to copy
* @param offset the offset to start at
* @param count the number of bytes in the array to use
* @param encoding the name of the encoding to use
* @throws NullPointerException if data or encoding is null
* @throws IndexOutOfBoundsException if offset or count is incorrect
* (while unspecified, this is a StringIndexOutOfBoundsException)
* @throws UnsupportedEncodingException if encoding is not found
* @throws Error if the decoding fails
* @since 1.1
*/
public String(byte[] data, int offset, int count, String encoding)
throws UnsupportedEncodingException
{
init (data, offset, count, encoding);
}
/**
* Creates a new String using the byte array. Uses the specified encoding
* type to decode the byte array, so the resulting string may be longer or
* shorter than the byte array. For more decoding control, use
* {@link java.nio.charset.CharsetDecoder}, and for valid character sets,
* see {@link java.nio.charset.Charset}. The behavior is not specified if
* the decoder encounters invalid characters; this implementation throws
* an Error.
*
* @param data byte array to copy
* @param encoding the name of the encoding to use
* @throws NullPointerException if data or encoding is null
* @throws UnsupportedEncodingException if encoding is not found
* @throws Error if the decoding fails
* @see #String(byte[], int, int, String)
* @since 1.1
*/
public String(byte[] data, String encoding)
throws UnsupportedEncodingException
{
this(data, 0, data.length, encoding);
}
/**
* Creates a new String using the portion of the byte array starting at the
* offset and ending at offset + count. Uses the encoding of the platform's
* default charset, so the resulting string may be longer or shorter than
* the byte array. For more decoding control, use
* {@link java.nio.charset.CharsetDecoder}. The behavior is not specified
* if the decoder encounters invalid characters; this implementation throws
* an Error.
*
* @param data byte array to copy
* @param offset the offset to start at
* @param count the number of bytes in the array to use
* @throws NullPointerException if data is null
* @throws IndexOutOfBoundsException if offset or count is incorrect
* @throws Error if the decoding fails
* @see #String(byte[], int, int, String)
* @since 1.1
*/
public String(byte[] data, int offset, int count)
{
try
{
init (data, offset, count,
System.getProperty("file.encoding", "8859_1"));
}
catch (UnsupportedEncodingException x1)
{
// Maybe the default encoding is bad.
try
{
init (data, offset, count, "8859_1");
}
catch (UnsupportedEncodingException x2)
{
// We know this can't happen.
}
}
}
/**
* Creates a new String using the byte array. Uses the encoding of the
* platform's default charset, so the resulting string may be longer or
* shorter than the byte array. For more decoding control, use
* {@link java.nio.charset.CharsetDecoder}. The behavior is not specified
* if the decoder encounters invalid characters; this implementation throws
* an Error.
*
* @param data byte array to copy
* @throws NullPointerException if data is null
* @throws Error if the decoding fails
* @see #String(byte[], int, int)
* @see #String(byte[], int, int, String)
* @since 1.1
*/
public String(byte[] data)
{
this(data, 0, data.length);
}
/**
* Creates a new String using the character sequence represented by
* the StringBuffer. Subsequent changes to buf do not affect the String.
*
* @param buffer StringBuffer to copy
* @throws NullPointerException if buffer is null
*/
public String(StringBuffer buffer)
{
synchronized (buffer)
{
// Share unless buffer is 3/4 empty.
boolean should_copy = ((buffer.count << 2) < buffer.value.length);
if (! should_copy)
buffer.shared = true;
init (buffer.value, 0, buffer.count, ! should_copy);
}
}
/**
* Creates a new String using the character sequence represented by
* the StringBuilder. Subsequent changes to buf do not affect the String.
*
* @param buffer StringBuilder to copy
* @throws NullPointerException if buffer is null
*/
public String(StringBuilder buffer)
{
this(buffer.value, 0, buffer.count);
}
/**
* Special constructor which can share an array when safe to do so.
*
* @param data the characters to copy
* @param offset the location to start from
* @param count the number of characters to use
* @param dont_copy true if the array is trusted, and need not be copied
* @throws NullPointerException if chars is null
* @throws StringIndexOutOfBoundsException if bounds check fails
*/
String(char[] data, int offset, int count, boolean dont_copy)
{
init(data, offset, count, dont_copy);
}
// This is used by gnu.gcj.runtime.StringBuffer, so it must have
// package-private protection. It is accessed via CNI and so avoids
// ordinary protection mechanisms.
String(gnu.gcj.runtime.StringBuffer buffer)
{
// No need to synchronize or mark the buffer, since we know it is
// only used once.
init (buffer);
}
/**
* Returns the number of characters contained in this String.
*
* @return the length of this String
*/
public int length()
{
return count;
}
/**
* Returns the character located at the specified index within this String.
*
* @param index position of character to return (base 0)
* @return character located at position index
* @throws IndexOutOfBoundsException if index < 0 || index >= length()
* (while unspecified, this is a StringIndexOutOfBoundsException)
*/
public native char charAt(int index);
/**
* Get the code point at the specified index. This is like #charAt(int),
* but if the character is the start of a surrogate pair, and the
* following character completes the pair, then the corresponding
* supplementary code point is returned.
* @param index the index of the codepoint to get, starting at 0
* @return the codepoint at the specified index
* @throws IndexOutOfBoundsException if index is negative or >= length()
* @since 1.5
*/
public synchronized int codePointAt(int index)
{
// Use the CharSequence overload as we get better range checking
// this way.
return Character.codePointAt(this, index);
}
/**
* Get the code point before the specified index. This is like
* #codePointAt(int), but checks the characters at index-1 and
* index-2 to see if they form a supplementary code point.
* @param index the index just past the codepoint to get, starting at 0
* @return the codepoint at the specified index
* @throws IndexOutOfBoundsException if index is negative or >= length()
* (while unspecified, this is a StringIndexOutOfBoundsException)
* @since 1.5
*/
public synchronized int codePointBefore(int index)
{
// Use the CharSequence overload as we get better range checking
// this way.
return Character.codePointBefore(this, index);
}
/**
* Copies characters from this String starting at a specified start index,
* ending at a specified stop index, to a character array starting at
* a specified destination begin index.
*
* @param srcBegin index to begin copying characters from this String
* @param srcEnd index after the last character to be copied from this String
* @param dst character array which this String is copied into
* @param dstBegin index to start writing characters into dst
* @throws NullPointerException if dst is null
* @throws IndexOutOfBoundsException if any indices are out of bounds
* (while unspecified, source problems cause a
* StringIndexOutOfBoundsException, and dst problems cause an
* ArrayIndexOutOfBoundsException)
*/
public native void getChars(int srcBegin, int srcEnd,
char[] dst, int dstBegin);
/**
* Copies the low byte of each character from this String starting at a
* specified start index, ending at a specified stop index, to a byte array
* starting at a specified destination begin index.
*
* @param srcBegin index to being copying characters from this String
* @param srcEnd index after the last character to be copied from this String
* @param dst byte array which each low byte of this String is copied into
* @param dstBegin index to start writing characters into dst
* @throws NullPointerException if dst is null and copy length is non-zero
* @throws IndexOutOfBoundsException if any indices are out of bounds
* (while unspecified, source problems cause a
* StringIndexOutOfBoundsException, and dst problems cause an
* ArrayIndexOutOfBoundsException)
* @see #getBytes()
* @see #getBytes(String)
* @deprecated use {@link #getBytes()}, which uses a char to byte encoder
*/
public native void getBytes(int srcBegin, int srcEnd,
byte[] dst, int dstBegin);
/**
* Converts the Unicode characters in this String to a byte array. Uses the
* specified encoding method, so the result may be longer or shorter than
* the String. For more encoding control, use
* {@link java.nio.charset.CharsetEncoder}, and for valid character sets,
* see {@link java.nio.charset.Charset}. The behavior is not specified if
* the encoder encounters a problem; this implementation returns null.
*
* @param enc encoding name
* @return the resulting byte array, or null on a problem
* @throws NullPointerException if enc is null
* @throws UnsupportedEncodingException if encoding is not supported
* @since 1.1
*/
public native byte[] getBytes(String enc)
throws UnsupportedEncodingException;
/**
* Converts the Unicode characters in this String to a byte array. Uses the
* encoding of the platform's default charset, so the result may be longer
* or shorter than the String. For more encoding control, use
* {@link java.nio.charset.CharsetEncoder}. The behavior is not specified if
* the encoder encounters a problem; this implementation returns null.
*
* @return the resulting byte array, or null on a problem
* @since 1.1
*/
public byte[] getBytes()
{
try
{
return getBytes (System.getProperty("file.encoding", "8859_1"));
}
catch (UnsupportedEncodingException x)
{
// This probably shouldn't happen, but could if file.encoding
// is somehow changed to a value we don't understand.
try
{
return getBytes ("8859_1");
}
catch (UnsupportedEncodingException x2)
{
// This really shouldn't happen, because the 8859_1
// encoding should always be available.
throw new InternalError ("couldn't find 8859_1 encoder");
}
}
}
/**
* Predicate which compares anObject to this. This is true only for Strings
* with the same character sequence.
*
* @param anObject the object to compare
* @return true if anObject is semantically equal to this
* @see #compareTo(String)
* @see #equalsIgnoreCase(String)
*/
public native boolean equals(Object anObject);
/**
* Compares the given StringBuffer to this String. This is true if the
* StringBuffer has the same content as this String at this moment.
*
* @param buffer the StringBuffer to compare to
* @return true if StringBuffer has the same character sequence
* @throws NullPointerException if the given StringBuffer is null
* @since 1.4
*/
public native boolean contentEquals(StringBuffer buffer);
/**
* Compares the given CharSequence to this String. This is true if
* the CharSequence has the same content as this String at this
* moment.
*
* @param seq the CharSequence to compare to
* @return true if CharSequence has the same character sequence
* @throws NullPointerException if the given CharSequence is null
* @since 1.5
*/
public native boolean contentEquals(CharSequence seq);
/**
* Compares a String to this String, ignoring case. This does not handle
* multi-character capitalization exceptions; instead the comparison is
* made on a character-by-character basis, and is true if:
*
*
* @param anotherString String to compare to this String
* @return true if anotherString is equal, ignoring case
* @see #equals(Object)
* @see Character#toUpperCase(char)
* @see Character#toLowerCase(char)
*/
public native boolean equalsIgnoreCase(String anotherString);
/**
* Compares this String and another String (case sensitive,
* lexicographically). The result is less than 0 if this string sorts
* before the other, 0 if they are equal, and greater than 0 otherwise.
* After any common starting sequence is skipped, the result is
* c1 == c2Character.toUpperCase(c1)
* == Character.toUpperCase(c2)Character.toLowerCase(c1)
* == Character.toLowerCase(c2)this.charAt(k) - anotherString.charAt(k) if both strings
* have characters remaining, or
* this.length() - anotherString.length() if one string is
* a subsequence of the other.
*
* @param anotherString the String to compare against
* @return the comparison
* @throws NullPointerException if anotherString is null
*/
public int compareTo(String anotherString)
{
return nativeCompareTo(anotherString);
}
/**
* The native implementation of compareTo(). Must be named different
* since cni doesn't understand the bridge method generated from
* the compareTo() method because of the ComparableCharacter.toLowerCase(Character.toUpperCase(c)) on each
* character of the string. This is unsatisfactory for locale-based
* comparison, in which case you should use {@link java.text.Collator}.
*
* @param str the string to compare against
* @return the comparison
* @see Collator#compare(String, String)
* @since 1.2
*/
public int compareToIgnoreCase(String str)
{
return this.toUpperCase().toLowerCase().compareTo(
str.toUpperCase().toLowerCase());
}
/**
* Predicate which determines if this String matches another String
* starting at a specified offset for each String and continuing
* for a specified length. Indices out of bounds are harmless, and give
* a false result.
*
* @param toffset index to start comparison at for this String
* @param other String to compare region to this String
* @param ooffset index to start comparison at for other
* @param len number of characters to compare
* @return true if regions match (case sensitive)
* @throws NullPointerException if other is null
*/
public native boolean regionMatches(int toffset,
String other, int ooffset, int len);
/**
* Predicate which determines if this String matches another String
* starting at a specified offset for each String and continuing
* for a specified length, optionally ignoring case. Indices out of bounds
* are harmless, and give a false result. Case comparisons are based on
* Character.toLowerCase() and
* Character.toUpperCase(), not on multi-character
* capitalization expansions.
*
* @param ignoreCase true if case should be ignored in comparision
* @param toffset index to start comparison at for this String
* @param other String to compare region to this String
* @param ooffset index to start comparison at for other
* @param len number of characters to compare
* @return true if regions match, false otherwise
* @throws NullPointerException if other is null
*/
public native boolean regionMatches(boolean ignoreCase, int toffset,
String other, int ooffset, int len);
/**
* Predicate which determines if this String contains the given prefix,
* beginning comparison at toffset. The result is false if toffset is
* negative or greater than this.length(), otherwise it is the same as
* this.substring(toffset).startsWith(prefix).
*
* @param prefix String to compare
* @param toffset offset for this String where comparison starts
* @return true if this String starts with prefix
* @throws NullPointerException if prefix is null
* @see #regionMatches(boolean, int, String, int, int)
*/
public native boolean startsWith(String prefix, int toffset);
/**
* Predicate which determines if this String starts with a given prefix.
* If the prefix is an empty String, true is returned.
*
* @param prefix String to compare
* @return true if this String starts with the prefix
* @throws NullPointerException if prefix is null
* @see #startsWith(String, int)
*/
public boolean startsWith(String prefix)
{
return startsWith (prefix, 0);
}
/**
* Predicate which determines if this String ends with a given suffix.
* If the suffix is an empty String, true is returned.
*
* @param suffix String to compare
* @return true if this String ends with the suffix
* @throws NullPointerException if suffix is null
* @see #regionMatches(boolean, int, String, int, int)
*/
public boolean endsWith(String suffix)
{
return regionMatches (this.count - suffix.count, suffix, 0, suffix.count);
}
/**
* Computes the hashcode for this String. This is done with int arithmetic,
* where ** represents exponentiation, by this formula:
* s[0]*31**(n-1) + s[1]*31**(n-2) + ... + s[n-1].
*
* @return hashcode value of this String
*/
public native int hashCode();
/**
* Finds the first instance of a character in this String.
*
* @param ch character to find
* @return location (base 0) of the character, or -1 if not found
*/
public int indexOf(int ch)
{
return indexOf(ch, 0);
}
/**
* Finds the first instance of a character in this String, starting at
* a given index. If starting index is less than 0, the search
* starts at the beginning of this String. If the starting index
* is greater than the length of this String, -1 is returned.
*
* @param ch character to find
* @param fromIndex index to start the search
* @return location (base 0) of the character, or -1 if not found
*/
public native int indexOf(int ch, int fromIndex);
/**
* Finds the last instance of a character in this String.
*
* @param ch character to find
* @return location (base 0) of the character, or -1 if not found
*/
public int lastIndexOf(int ch)
{
return lastIndexOf(ch, count - 1);
}
/**
* Finds the last instance of a character in this String, starting at
* a given index. If starting index is greater than the maximum valid
* index, then the search begins at the end of this String. If the
* starting index is less than zero, -1 is returned.
*
* @param ch character to find
* @param fromIndex index to start the search
* @return location (base 0) of the character, or -1 if not found
*/
public native int lastIndexOf(int ch, int fromIndex);
/**
* Finds the first instance of a String in this String.
*
* @param str String to find
* @return location (base 0) of the String, or -1 if not found
* @throws NullPointerException if str is null
*/
public int indexOf(String str)
{
return indexOf(str, 0);
}
/**
* Finds the first instance of a String in this String, starting at
* a given index. If starting index is less than 0, the search
* starts at the beginning of this String. If the starting index
* is greater than the length of this String, -1 is returned.
*
* @param str String to find
* @param fromIndex index to start the search
* @return location (base 0) of the String, or -1 if not found
* @throws NullPointerException if str is null
*/
public native int indexOf(String str, int fromIndex);
/**
* Finds the last instance of a String in this String.
*
* @param str String to find
* @return location (base 0) of the String, or -1 if not found
* @throws NullPointerException if str is null
*/
public int lastIndexOf(String str)
{
return lastIndexOf(str, count - str.count);
}
/**
* Finds the last instance of a String in this String, starting at
* a given index. If starting index is greater than the maximum valid
* index, then the search begins at the end of this String. If the
* starting index is less than zero, -1 is returned.
*
* @param str String to find
* @param fromIndex index to start the search
* @return location (base 0) of the String, or -1 if not found
* @throws NullPointerException if str is null
*/
public int lastIndexOf(String str, int fromIndex)
{
if (fromIndex >= count)
fromIndex = count - str.count;
for (;; --fromIndex)
{
if (fromIndex < 0)
return -1;
if (startsWith(str, fromIndex))
return fromIndex;
}
}
/**
* Creates a substring of this String, starting at a specified index
* and ending at the end of this String.
*
* @param begin index to start substring (base 0)
* @return new String which is a substring of this String
* @throws IndexOutOfBoundsException if begin < 0 || begin > length()
* (while unspecified, this is a StringIndexOutOfBoundsException)
*/
public String substring(int begin)
{
return substring(begin, count);
}
/**
* Creates a substring of this String, starting at a specified index
* and ending at one character before a specified index.
*
* @param begin index to start substring (inclusive, base 0)
* @param end index to end at (exclusive)
* @return new String which is a substring of this String
* @throws IndexOutOfBoundsException if begin < 0 || end > length()
* || begin > end (while unspecified, this is a
* StringIndexOutOfBoundsException)
*/
public native String substring(int begin, int end);
/**
* Creates a substring of this String, starting at a specified index
* and ending at one character before a specified index. This behaves like
* substring(begin, end).
*
* @param begin index to start substring (inclusive, base 0)
* @param end index to end at (exclusive)
* @return new String which is a substring of this String
* @throws IndexOutOfBoundsException if begin < 0 || end > length()
* || begin > end
* @since 1.4
*/
public CharSequence subSequence(int begin, int end)
{
return substring(begin, end);
}
/**
* Concatenates a String to this String. This results in a new string unless
* one of the two originals is "".
*
* @param str String to append to this String
* @return newly concatenated String
* @throws NullPointerException if str is null
*/
public native String concat(String str);
/**
* Replaces every instance of a character in this String with a new
* character. If no replacements occur, this is returned.
*
* @param oldChar the old character to replace
* @param newChar the new character
* @return new String with all instances of oldChar replaced with newChar
*/
public native String replace(char oldChar, char newChar);
/**
* Test if this String matches a regular expression. This is shorthand for
* {@link Pattern}.matches(regex, this).
*
* @param regex the pattern to match
* @return true if the pattern matches
* @throws NullPointerException if regex is null
* @throws PatternSyntaxException if regex is invalid
* @see Pattern#matches(String, CharSequence)
* @since 1.4
*/
public boolean matches(String regex)
{
return Pattern.matches(regex, this);
}
/**
* Replaces the first substring match of the regular expression with a
* given replacement. This is shorthand for {@link Pattern}
* .compile(regex).matcher(this).replaceFirst(replacement).
*
* @param regex the pattern to match
* @param replacement the replacement string
* @return the modified string
* @throws NullPointerException if regex or replacement is null
* @throws PatternSyntaxException if regex is invalid
* @see #replaceAll(String, String)
* @see Pattern#compile(String)
* @see Pattern#matcher(CharSequence)
* @see Matcher#replaceFirst(String)
* @since 1.4
*/
public String replaceFirst(String regex, String replacement)
{
return Pattern.compile(regex).matcher(this).replaceFirst(replacement);
}
/**
* Replaces all matching substrings of the regular expression with a
* given replacement. This is shorthand for {@link Pattern}
* .compile(regex).matcher(this).replaceAll(replacement).
*
* @param regex the pattern to match
* @param replacement the replacement string
* @return the modified string
* @throws NullPointerException if regex or replacement is null
* @throws PatternSyntaxException if regex is invalid
* @see #replaceFirst(String, String)
* @see Pattern#compile(String)
* @see Pattern#matcher(CharSequence)
* @see Matcher#replaceAll(String)
* @since 1.4
*/
public String replaceAll(String regex, String replacement)
{
return Pattern.compile(regex).matcher(this).replaceAll(replacement);
}
/**
* Split this string around the matches of a regular expression. Each
* element of the returned array is the largest block of characters not
* terminated by the regular expression, in the order the matches are found.
*
*
*
*
*
* Regex Limit Result
* ":" 2 { "boo", "and:foo" } ":" t { "boo", "and", "foo" } ":" -2 { "boo", "and", "foo" } "o" 5 { "b", "", ":and:f", "", "" } "o" -2 { "b", "", ":and:f", "", "" } "o" 0 { "b", "", ":and:f" } {@link Pattern}.compile(regex).split(this, limit).
*
* @param regex the pattern to match
* @param limit the limit threshold
* @return the array of split strings
* @throws NullPointerException if regex or replacement is null
* @throws PatternSyntaxException if regex is invalid
* @see Pattern#compile(String)
* @see Pattern#split(CharSequence, int)
* @since 1.4
*/
public String[] split(String regex, int limit)
{
return Pattern.compile(regex).split(this, limit);
}
/**
* Split this string around the matches of a regular expression. Each
* element of the returned array is the largest block of characters not
* terminated by the regular expression, in the order the matches are found.
* The array length is unlimited, and trailing empty entries are discarded,
* as though calling split(regex, 0).
*
* @param regex the pattern to match
* @return the array of split strings
* @throws NullPointerException if regex or replacement is null
* @throws PatternSyntaxException if regex is invalid
* @see #split(String, int)
* @see Pattern#compile(String)
* @see Pattern#split(CharSequence, int)
* @since 1.4
*/
public String[] split(String regex)
{
return Pattern.compile(regex).split(this, 0);
}
/**
* Lowercases this String according to a particular locale. This uses
* Unicode's special case mappings, as applied to the given Locale, so the
* resulting string may be a different length.
*
* @param loc locale to use
* @return new lowercased String, or this if no characters were lowercased
* @throws NullPointerException if loc is null
* @see #toUpperCase(Locale)
* @since 1.1
*/
public native String toLowerCase(Locale locale);
/**
* Lowercases this String. This uses Unicode's special case mappings, as
* applied to the platform's default Locale, so the resulting string may
* be a different length.
*
* @return new lowercased String, or this if no characters were lowercased
* @see #toLowerCase(Locale)
* @see #toUpperCase()
*/
public String toLowerCase()
{
// The JDK is a bit confused about what to do here. If we pass in
// the default Locale then special Locale handling might be
// invoked. However, the docs also say that Character.toLowerCase
// rules here. We go with the latter.
return toLowerCase (null);
}
/**
* Uppercases this String according to a particular locale. This uses
* Unicode's special case mappings, as applied to the given Locale, so the
* resulting string may be a different length.
*
* @param loc locale to use
* @return new uppercased String, or this if no characters were uppercased
* @throws NullPointerException if loc is null
* @see #toLowerCase(Locale)
* @since 1.1
*/
public native String toUpperCase(Locale locale);
/**
* Uppercases this String. This uses Unicode's special case mappings, as
* applied to the platform's default Locale, so the resulting string may
* be a different length.
*
* @return new uppercased String, or this if no characters were uppercased
* @see #toUpperCase(Locale)
* @see #toLowerCase()
*/
public String toUpperCase()
{
// The JDK is a bit confused about what to do here. If we pass in
// the default Locale then special Locale handling might be
// invoked. However, the docs also say that Character.toLowerCase
// rules here. We go with the latter.
return toUpperCase (null);
}
/**
* Trims all characters less than or equal to '\u0020'
* (' ') from the beginning and end of this String. This
* includes many, but not all, ASCII control characters, and all
* {@link Character#isWhitespace(char)}.
*
* @return new trimmed String, or this if nothing trimmed
*/
public native String trim();
/**
* Returns this, as it is already a String!
*
* @return this
*/
public String toString()
{
return this;
}
/**
* Copies the contents of this String into a character array. Subsequent
* changes to the array do not affect the String.
*
* @return character array copying the String
*/
public native char[] toCharArray();
/**
* Returns a String representation of an Object. This is "null" if the
* object is null, otherwise it is obj.toString() (which
* can be null).
*
* @param obj the Object
* @return the string conversion of obj
*/
public static String valueOf(Object obj)
{
return obj == null ? "null" : obj.toString();
}
/**
* Returns a String representation of a character array. Subsequent
* changes to the array do not affect the String.
*
* @param data the character array
* @return a String containing the same character sequence as data
* @throws NullPointerException if data is null
* @see #valueOf(char[], int, int)
* @see #String(char[])
*/
public static String valueOf(char[] data)
{
return valueOf (data, 0, data.length);
}
/**
* Returns a String representing the character sequence of the char array,
* starting at the specified offset, and copying chars up to the specified
* count. Subsequent changes to the array do not affect the String.
*
* @param data character array
* @param offset position (base 0) to start copying out of data
* @param count the number of characters from data to copy
* @return String containing the chars from data[offset..offset+count]
* @throws NullPointerException if data is null
* @throws IndexOutOfBoundsException if (offset < 0 || count < 0
* || offset + count > data.length)
* (while unspecified, this is a StringIndexOutOfBoundsException)
* @see #String(char[], int, int)
*/
public static native String valueOf(char[] data, int offset, int count);
/**
* Returns a String representing the character sequence of the char array,
* starting at the specified offset, and copying chars up to the specified
* count. Subsequent changes to the array do not affect the String.
*
* @param data character array
* @param offset position (base 0) to start copying out of data
* @param count the number of characters from data to copy
* @return String containing the chars from data[offset..offset+count]
* @throws NullPointerException if data is null
* @throws IndexOutOfBoundsException if (offset < 0 || count < 0
* || offset + count < 0 (overflow)
* || offset + count > data.length)
* (while unspecified, this is a StringIndexOutOfBoundsException)
* @see #String(char[], int, int)
*/
public static String copyValueOf(char[] data, int offset, int count)
{
String r = new String ();
r.init(data, offset, count, false);
return r;
}
/**
* Returns a String representation of a character array. Subsequent
* changes to the array do not affect the String.
*
* @param data the character array
* @return a String containing the same character sequence as data
* @throws NullPointerException if data is null
* @see #copyValueOf(char[], int, int)
* @see #String(char[])
*/
public static String copyValueOf(char[] data)
{
return copyValueOf (data, 0, data.length);
}
/**
* Returns a String representing a boolean.
*
* @param b the boolean
* @return "true" if b is true, else "false"
*/
public static String valueOf(boolean b)
{
return b ? "true" : "false";
}
/**
* Returns a String representing a character.
*
* @param c the character
* @return String containing the single character c
*/
public static native String valueOf(char c);
/**
* Returns a String representing an integer.
*
* @param i the integer
* @return String containing the integer in base 10
* @see Integer#toString(int)
*/
public static native String valueOf(int i);
/**
* Returns a String representing a long.
*
* @param l the long
* @return String containing the long in base 10
* @see Long#toString(long)
*/
public static String valueOf(long l)
{
return Long.toString(l);
}
/**
* Returns a String representing a float.
*
* @param f the float
* @return String containing the float
* @see Float#toString(float)
*/
public static String valueOf(float f)
{
return Float.toString(f);
}
/**
* Returns a String representing a double.
*
* @param d the double
* @return String containing the double
* @see Double#toString(double)
*/
public static String valueOf(double d)
{
return Double.toString(d);
}
/** @since 1.5 */
public static String format(Locale locale, String format, Object... args)
{
Formatter f = new Formatter(locale);
return f.format(format, args).toString();
}
/** @since 1.5 */
public static String format(String format, Object... args)
{
return format(Locale.getDefault(), format, args);
}
/**
* Fetches this String from the intern hashtable.
* If two Strings are considered equal, by the equals() method,
* then intern() will return the same String instance. ie.
* if (s1.equals(s2)) then (s1.intern() == s2.intern()).
* All string literals and string-valued constant expressions
* are already interned.
*
* @return the interned String
*/
public native String intern();
/**
* Return the number of code points between two indices in the
* String. An unpaired surrogate counts as a
* code point for this purpose. Characters outside the indicated
* range are not examined, even if the range ends in the middle of a
* surrogate pair.
*
* @param start the starting index
* @param end one past the ending index
* @return the number of code points
* @since 1.5
*/
public synchronized int codePointCount(int start, int end)
{
if (start < 0 || end > count || start > end)
throw new StringIndexOutOfBoundsException();
int count = 0;
while (start < end)
{
char base = charAt(start);
if (base < Character.MIN_HIGH_SURROGATE
|| base > Character.MAX_HIGH_SURROGATE
|| start == end
|| start == count
|| charAt(start + 1) < Character.MIN_LOW_SURROGATE
|| charAt(start + 1) > Character.MAX_LOW_SURROGATE)
{
// Nothing.
}
else
{
// Surrogate pair.
++start;
}
++start;
++count;
}
return count;
}
/**
* Returns true iff this String contains the sequence of Characters
* described in s.
* @param s the CharSequence
* @return true iff this String contains s
*
* @since 1.5
*/
public boolean contains (CharSequence s)
{
return this.indexOf(s.toString()) != -1;
}
/**
* Returns a string that is this string with all instances of the sequence
* represented by target replaced by the sequence in
* replacement.
* @param target the sequence to be replaced
* @param replacement the sequence used as the replacement
* @return the string constructed as above
*/
public String replace (CharSequence target, CharSequence replacement)
{
String targetString = target.toString();
String replaceString = replacement.toString();
int targetLength = target.length();
int replaceLength = replacement.length();
int startPos = this.indexOf(targetString);
StringBuilder result = new StringBuilder(this);
while (startPos != -1)
{
// Replace the target with the replacement
result.replace(startPos, startPos + targetLength, replaceString);
// Search for a new occurrence of the target
startPos = result.indexOf(targetString, startPos + replaceLength);
}
return result.toString();
}
/**
* Return the index into this String that is offset from the given index by
* codePointOffset code points.
* @param index the index at which to start
* @param codePointOffset the number of code points to offset
* @return the index into this String that is codePointOffset
* code points offset from index.
*
* @throws IndexOutOfBoundsException if index is negative or larger than the
* length of this string.
* @throws IndexOutOfBoundsException if codePointOffset is positive and the
* substring starting with index has fewer than codePointOffset code points.
* @throws IndexOutOfBoundsException if codePointOffset is negative and the
* substring ending with index has fewer than (-codePointOffset) code points.
* @since 1.5
*/
public int offsetByCodePoints(int index, int codePointOffset)
{
if (index < 0 || index > count)
throw new IndexOutOfBoundsException();
return Character.offsetByCodePoints(this, index, codePointOffset);
}
/**
* Returns true if, and only if, {@link #length()}
* is 0.
*
* @return true if the length of the string is zero.
* @since 1.6
*/
public boolean isEmpty()
{
return count == 0;
}
// Generate a String that shares the value array: subsequent changes
// to this array will affect the String. A private internal method
// that is called from CPStringBuilder by compiler-generated code.
private static String toString(char[] value, int startIndex, int count)
{
return new String(value, startIndex, count, true);
}
private native void init(char[] chars, int offset, int count,
boolean dont_copy);
private native void init(byte[] chars, int hibyte, int offset, int count);
private native void init(byte[] chars, int offset, int count, String enc)
throws UnsupportedEncodingException;
private native void init(gnu.gcj.runtime.StringBuffer buffer);
}