java.lang

Class String

Implemented Interfaces:
CharSequence, Comparable, Serializable

public final class String
extends Object
implements Serializable, Comparable, CharSequence

Strings represent an immutable set of characters. All String literals are instances of this class, and two string literals with the same contents refer to the same String object.

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.

Since:
1.0

See Also:
Serialized Form

Field Summary

static Comparator
CASE_INSENSITIVE_ORDER
A Comparator that uses String.compareToIgnoreCase(String).

Constructor Summary

String()
Creates an empty String (length 0).
String(byte[] data)
Creates a new String using the byte array.
String(byte[] ascii, int hibyte)
Deprecated. use String(byte[],String) to perform correct encoding
String(byte[] data, int offset, int count)
Creates a new String using the portion of the byte array starting at the offset and ending at offset + count.
String(byte[] ascii, int hibyte, int offset, int count)
Deprecated. use String(byte[],int,int,String) to perform correct encoding
String(byte[] data, int offset, int count, String encoding)
Creates a new String using the portion of the byte array starting at the offset and ending at offset + count.
String(byte[] data, String encoding)
Creates a new String using the byte array.
String(char[] data)
Creates a new String using the character sequence of the char array.
String(char[] data, int offset, int count)
Creates a new String using the character sequence of a subarray of characters.
String(String str)
Copies the contents of a String to a new String.
String(StringBuffer buffer)
Creates a new String using the character sequence represented by the StringBuffer.
String(StringBuilder buffer)
Creates a new String using the character sequence represented by the StringBuilder.

Method Summary

char
charAt(int index)
Returns the character located at the specified index within this String.
int
compareTo(Object o)
Behaves like compareTo(java.lang.String) unless the Object is not a String.
int
compareTo(String anotherString)
Compares this String and another String (case sensitive, lexicographically).
int
compareToIgnoreCase(String str)
Compares this String and another String (case insensitive).
String
concat(String str)
Concatenates a String to this String.
boolean
contentEquals(StringBuffer buffer)
Compares the given StringBuffer to this String.
static String
copyValueOf(char[] data)
Returns a String representation of a character array.
static String
copyValueOf(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.
boolean
endsWith(String suffix)
Predicate which determines if this String ends with a given suffix.
boolean
equals(Object anObject)
Predicate which compares anObject to this.
boolean
equalsIgnoreCase(String anotherString)
Compares a String to this String, ignoring case.
byte[]
getBytes()
Converts the Unicode characters in this String to a byte array.
void
getBytes(int srcBegin, int srcEnd, dst[] , int dstBegin)
Deprecated. use getBytes(), which uses a char to byte encoder
byte[]
getBytes(String enc)
Converts the Unicode characters in this String to a byte array.
void
getChars(int srcBegin, int srcEnd, dst[] , int dstBegin)
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.
int
hashCode()
Computes the hashcode for this String.
int
indexOf(int ch)
Finds the first instance of a character in this String.
int
indexOf(int ch, int fromIndex)
Finds the first instance of a character in this String, starting at a given index.
int
indexOf(String str)
Finds the first instance of a String in this String.
int
indexOf(String str, int fromIndex)
Finds the first instance of a String in this String, starting at a given index.
String
intern()
If two Strings are considered equal, by the equals() method, then intern() will return the same String instance. ie.
int
lastIndexOf(int ch)
Finds the last instance of a character in this String.
int
lastIndexOf(int ch, int fromIndex)
Finds the last instance of a character in this String, starting at a given index.
int
lastIndexOf(String str)
Finds the last instance of a String in this String.
int
lastIndexOf(String str, int fromIndex)
Finds the last instance of a String in this String, starting at a given index.
int
length()
Returns the number of characters contained in this String.
boolean
matches(String regex)
Test if this String matches a regular expression.
boolean
regionMatches(boolean ignoreCase, 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.
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.
String
replace(char oldChar, char newChar)
Replaces every instance of a character in this String with a new character.
String
replaceAll(String regex, String replacement)
Replaces all matching substrings of the regular expression with a given replacement.
String
replaceFirst(String regex, String replacement)
Replaces the first substring match of the regular expression with a given replacement.
String[]
split(String regex)
Split this string around the matches of a regular expression.
String[]
split(String regex, int limit)
Split this string around the matches of a regular expression.
boolean
startsWith(String prefix)
Predicate which determines if this String starts with a given prefix.
boolean
startsWith(String prefix, int toffset)
Predicate which determines if this String contains the given prefix, beginning comparison at toffset.
CharSequence
subSequence(int begin, int end)
Creates a substring of this String, starting at a specified index and ending at one character before a specified index.
String
substring(int begin)
Creates a substring of this String, starting at a specified index and ending at the end of this String.
String
substring(int beginIndex, int endIndex)
Creates a substring of this String, starting at a specified index and ending at one character before a specified index.
char[]
toCharArray()
Copies the contents of this String into a character array.
String
toLowerCase()
Lowercases this String.
String
toLowerCase(Locale loc)
Lowercases this String according to a particular locale.
String
toString()
Returns this, as it is already a String!
String
toUpperCase()
Uppercases this String.
String
toUpperCase(Locale loc)
Uppercases this String according to a particular locale.
String
trim()
Trims all characters less than or equal to '\u0020' (' ') from the beginning and end of this String.
static String
valueOf(boolean b)
Returns a String representing a boolean.
static String
valueOf(char c)
Returns a String representing a character.
static String
valueOf(char[] data)
Returns a String representation of a character array.
static 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.
static String
valueOf(double d)
Returns a String representing a double.
static String
valueOf(float f)
Returns a String representing a float.
static String
valueOf(int i)
Returns a String representing an integer.
static String
valueOf(Object obj)
Returns a String representation of an Object.
static String
valueOf(long l)
Returns a String representing a long.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CASE_INSENSITIVE_ORDER

public static final Comparator CASE_INSENSITIVE_ORDER
A Comparator that uses String.compareToIgnoreCase(String). This comparator is Serializable. Note that it ignores Locale, for that, you want a Collator.

Since:
1.2

See Also:
Collator.compare(String,String)

Constructor Details

String

public String()
Creates an empty String (length 0). Unless you really need a new object, consider using "" instead.


String

public String(byte[] data)
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 CharsetDecoder. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Parameters:
data - byte array to copy

Throws:
NullPointerException - if data is null

Since:
1.1

See Also:
String(byte[],int,int), String(byte[],int,int,String)


String

public String(byte[] ascii,
              int hibyte)

Deprecated. use String(byte[],String) to perform correct encoding

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))
 

Parameters:
ascii - array of integer values
hibyte - top byte of each Unicode character

Throws:
NullPointerException - if ascii is null

See Also:
String(byte[]), String(byte[],String), String(byte[],int,int), String(byte[],int,int,String), String(byte[],int,int,int)


String

public String(byte[] data,
              int offset,
              int count)
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 CharsetDecoder. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Parameters:
data - byte array to copy
offset - the offset to start at
count - the number of bytes in the array to use

Throws:
NullPointerException - if data is null
IndexOutOfBoundsException - if offset or count is incorrect

Since:
1.1

See Also:
String(byte[],int,int,String)


String

public String(byte[] ascii,
              int hibyte,
              int offset,
              int count)

Deprecated. use String(byte[],int,int,String) to perform correct encoding

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))
 

Parameters:
ascii - array of integer values
hibyte - top byte of each Unicode character
offset - position (base 0) to start copying out of ascii
count - the number of characters from ascii to copy

Throws:
NullPointerException - if ascii is null
IndexOutOfBoundsException - if (offset < 0 || count < 0 || offset + count > ascii.length) (while unspecified, this is a StringIndexOutOfBoundsException)

See Also:
String(byte[]), String(byte[],String), String(byte[],int,int), String(byte[],int,int,String)


String

public String(byte[] data,
              int offset,
              int count,
              String encoding)
            throws UnsupportedEncodingException
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 CharsetDecoder, and for valid character sets, see Charset. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Parameters:
data - byte array to copy
offset - the offset to start at
count - the number of bytes in the array to use
encoding - the name of the encoding to use

Throws:
NullPointerException - if data or encoding is null
IndexOutOfBoundsException - if offset or count is incorrect (while unspecified, this is a StringIndexOutOfBoundsException)
UnsupportedEncodingException - if encoding is not found

Since:
1.1


String

public String(byte[] data,
              String encoding)
            throws UnsupportedEncodingException
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 CharsetDecoder, and for valid character sets, see Charset. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Parameters:
data - byte array to copy
encoding - the name of the encoding to use

Throws:
NullPointerException - if data or encoding is null
UnsupportedEncodingException - if encoding is not found

Since:
1.1

See Also:
String(byte[],int,int,String)


String

public String(char[] data)
Creates a new String using the character sequence of the char array. Subsequent changes to data do not affect the String.

Parameters:
data - char array to copy

Throws:
NullPointerException - if data is null


String

public String(char[] data,
              int offset,
              int count)
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.

Parameters:
data - char array to copy
offset - position (base 0) to start copying out of data
count - the number of characters from data to copy

Throws:
NullPointerException - if data is null
IndexOutOfBoundsException - if (offset < 0 || count < 0 || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)


String

public String(String str)
Copies the contents of a String to a new String. Since Strings are immutable, only a shallow copy is performed.

Parameters:
str - String to copy

Throws:
NullPointerException - if value is null


String

public String(StringBuffer buffer)
Creates a new String using the character sequence represented by the StringBuffer. Subsequent changes to buf do not affect the String.

Parameters:
buffer - StringBuffer to copy

Throws:
NullPointerException - if buffer is null


String

public String(StringBuilder buffer)
Creates a new String using the character sequence represented by the StringBuilder. Subsequent changes to buf do not affect the String.

Parameters:
buffer - StringBuilder to copy

Throws:
NullPointerException - if buffer is null

Method Details

charAt

public char charAt(int index)
Returns the character located at the specified index within this String.
Specified by:
charAt in interface CharSequence

Parameters:
index - position of character to return (base 0)

Returns:
character located at position index

Throws:
IndexOutOfBoundsException - if index < 0 || index >= length() (while unspecified, this is a StringIndexOutOfBoundsException)


compareTo

public int compareTo(Object o)
Behaves like compareTo(java.lang.String) unless the Object is not a String. Then it throws a ClassCastException.
Specified by:
compareTo in interface Comparable

Parameters:
o - the object to compare against

Returns:
the comparison

Throws:
NullPointerException - if o is null
ClassCastException - if o is not a String

Since:
1.2


compareTo

public int compareTo(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 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.

Parameters:
anotherString - the String to compare against

Returns:
the comparison

Throws:
NullPointerException - if anotherString is null


compareToIgnoreCase

public int compareToIgnoreCase(String str)
Compares this String and another String (case insensitive). This comparison is similar to equalsIgnoreCase, in that it ignores locale and multi-characater capitalization, and compares characters after performing Character.toLowerCase(Character.toUpperCase(c)) on each character of the string. This is unsatisfactory for locale-based comparison, in which case you should use Collator.

Parameters:
str - the string to compare against

Returns:
the comparison

Since:
1.2

See Also:
Collator.compare(String,String)


concat

public String concat(String str)
Concatenates a String to this String. This results in a new string unless one of the two originals is "".

Parameters:
str - String to append to this String

Returns:
newly concatenated String

Throws:
NullPointerException - if str is null


contentEquals

public boolean contentEquals(StringBuffer buffer)
Compares the given StringBuffer to this String. This is true if the StringBuffer has the same content as this String at this moment.

Parameters:
buffer - the StringBuffer to compare to

Returns:
true if StringBuffer has the same character sequence

Throws:
NullPointerException - if the given StringBuffer is null

Since:
1.4


copyValueOf

public static String copyValueOf(char[] data)
Returns a String representation of a character array. Subsequent changes to the array do not affect the String.

Parameters:
data - the character array

Returns:
a String containing the same character sequence as data

Throws:
NullPointerException - if data is null

See Also:
copyValueOf(char[],int,int), String(char[])


copyValueOf

public static String copyValueOf(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.

Parameters:
data - character array
offset - position (base 0) to start copying out of data
count - the number of characters from data to copy

Returns:
String containing the chars from data[offset..offset+count]

Throws:
NullPointerException - if data is null
IndexOutOfBoundsException - if (offset < 0 || count < 0 || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)

See Also:
String(char[],int,int)


endsWith

public boolean endsWith(String suffix)
Predicate which determines if this String ends with a given suffix. If the suffix is an empty String, true is returned.

Parameters:
suffix - String to compare

Returns:
true if this String ends with the suffix

Throws:
NullPointerException - if suffix is null

See Also:
regionMatches(boolean,int,String,int,int)


equals

public boolean equals(Object anObject)
Predicate which compares anObject to this. This is true only for Strings with the same character sequence.
Overrides:
equals in interface Object

Parameters:
anObject - the object to compare

Returns:
true if anObject is semantically equal to this

See Also:
compareTo(String), equalsIgnoreCase(String)


equalsIgnoreCase

public boolean equalsIgnoreCase(String anotherString)
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:
  • c1 == c2
  • Character.toUpperCase(c1) == Character.toUpperCase(c2)
  • Character.toLowerCase(c1) == Character.toLowerCase(c2)

Parameters:
anotherString - String to compare to this String

Returns:
true if anotherString is equal, ignoring case

See Also:
equals(Object), Character.toUpperCase(char), Character.toLowerCase(char)


getBytes

public byte[] getBytes()
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 CharsetEncoder. Unsupported characters get replaced by an encoding specific byte.

Returns:
the resulting byte array, or null on a problem

Since:
1.1


getBytes

public void getBytes(int srcBegin,
                     int srcEnd,
                     dst[] ,
                     int dstBegin)

Deprecated. use getBytes(), which uses a char to byte encoder

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.

Parameters:
srcBegin - index to being copying characters from this String
srcEnd - index after the last character to be copied from this String
dstBegin - index to start writing characters into dst

Throws:
NullPointerException - if dst is null and copy length is non-zero
IndexOutOfBoundsException - if any indices are out of bounds (while unspecified, source problems cause a StringIndexOutOfBoundsException, and dst problems cause an ArrayIndexOutOfBoundsException)

See Also:
getBytes(), getBytes(String)


getBytes

public byte[] getBytes(String enc)
            throws UnsupportedEncodingException
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 CharsetEncoder, and for valid character sets, see Charset. Unsupported characters get replaced by an encoding specific byte.

Parameters:
enc - encoding name

Returns:
the resulting byte array

Throws:
NullPointerException - if enc is null
UnsupportedEncodingException - if encoding is not supported

Since:
1.1


getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     dst[] ,
                     int dstBegin)
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.

Parameters:
srcBegin - index to begin copying characters from this String
srcEnd - index after the last character to be copied from this String
dstBegin - index to start writing characters into dst

Throws:
NullPointerException - if dst is null
IndexOutOfBoundsException - if any indices are out of bounds (while unspecified, source problems cause a StringIndexOutOfBoundsException, and dst problems cause an ArrayIndexOutOfBoundsException)


hashCode

public int hashCode()
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].
Overrides:
hashCode in interface Object

Returns:
hashcode value of this String


indexOf

public int indexOf(int ch)
Finds the first instance of a character in this String.

Parameters:
ch - character to find

Returns:
location (base 0) of the character, or -1 if not found


indexOf

public int indexOf(int ch,
                   int fromIndex)
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.

Parameters:
ch - character to find
fromIndex - index to start the search

Returns:
location (base 0) of the character, or -1 if not found


indexOf

public int indexOf(String str)
Finds the first instance of a String in this String.

Parameters:
str - String to find

Returns:
location (base 0) of the String, or -1 if not found

Throws:
NullPointerException - if str is null


indexOf

public int indexOf(String str,
                   int fromIndex)
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.

Parameters:
str - String to find
fromIndex - index to start the search

Returns:
location (base 0) of the String, or -1 if not found

Throws:
NullPointerException - if str is null


intern

public String intern()
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.

Returns:
the interned String


lastIndexOf

public int lastIndexOf(int ch)
Finds the last instance of a character in this String.

Parameters:
ch - character to find

Returns:
location (base 0) of the character, or -1 if not found


lastIndexOf

public int lastIndexOf(int ch,
                       int fromIndex)
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.

Parameters:
ch - character to find
fromIndex - index to start the search

Returns:
location (base 0) of the character, or -1 if not found


lastIndexOf

public int lastIndexOf(String str)
Finds the last instance of a String in this String.

Parameters:
str - String to find

Returns:
location (base 0) of the String, or -1 if not found

Throws:
NullPointerException - if str is null


lastIndexOf

public int lastIndexOf(String str,
                       int fromIndex)
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.

Parameters:
str - String to find
fromIndex - index to start the search

Returns:
location (base 0) of the String, or -1 if not found

Throws:
NullPointerException - if str is null


length

public int length()
Returns the number of characters contained in this String.
Specified by:
length in interface CharSequence

Returns:
the length of this String


matches

public boolean matches(String regex)
Test if this String matches a regular expression. This is shorthand for Pattern.matches(regex, this).

Parameters:
regex - the pattern to match

Returns:
true if the pattern matches

Throws:
NullPointerException - if regex is null
PatternSyntaxException - if regex is invalid

Since:
1.4

See Also:
Pattern.matches(String,CharSequence)


regionMatches

public boolean regionMatches(boolean ignoreCase,
                             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.

Parameters:
ignoreCase - true if case should be ignored in comparision
toffset - index to start comparison at for this String
other - String to compare region to this String
ooffset - index to start comparison at for other
len - number of characters to compare

Returns:
true if regions match, false otherwise

Throws:
NullPointerException - if other is null


regionMatches

public 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. Indices out of bounds are harmless, and give a false result.

Parameters:
toffset - index to start comparison at for this String
other - String to compare region to this String
ooffset - index to start comparison at for other
len - number of characters to compare

Returns:
true if regions match (case sensitive)

Throws:
NullPointerException - if other is null


replace

public String replace(char oldChar,
                      char newChar)
Replaces every instance of a character in this String with a new character. If no replacements occur, this is returned.

Parameters:
oldChar - the old character to replace
newChar - the new character

Returns:
new String with all instances of oldChar replaced with newChar


replaceAll

public String replaceAll(String regex,
                         String replacement)
Replaces all matching substrings of the regular expression with a given replacement. This is shorthand for Pattern .compile(regex).matcher(this).replaceAll(replacement).

Parameters:
regex - the pattern to match
replacement - the replacement string

Returns:
the modified string

Throws:
NullPointerException - if regex or replacement is null
PatternSyntaxException - if regex is invalid

Since:
1.4

See Also:
replaceFirst(String,String), Pattern.compile(String), Pattern.matcher(CharSequence), Matcher.replaceAll(String)


replaceFirst

public String replaceFirst(String regex,
                           String replacement)
Replaces the first substring match of the regular expression with a given replacement. This is shorthand for Pattern .compile(regex).matcher(this).replaceFirst(replacement).

Parameters:
regex - the pattern to match
replacement - the replacement string

Returns:
the modified string

Throws:
NullPointerException - if regex or replacement is null
PatternSyntaxException - if regex is invalid

Since:
1.4

See Also:
replaceAll(String,String), Pattern.compile(String), Pattern.matcher(CharSequence), Matcher.replaceFirst(String)


split

public String[] split(String regex)
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).

Parameters:
regex - the pattern to match

Returns:
the array of split strings

Throws:
NullPointerException - if regex or replacement is null
PatternSyntaxException - if regex is invalid

Since:
1.4

See Also:
split(String,int), Pattern.compile(String), Pattern.split(CharSequence,int)


split

public String[] split(String regex,
                      int 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 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:

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" }

This is shorthand for Pattern.compile(regex).split(this, limit).

Parameters:
regex - the pattern to match
limit - the limit threshold

Returns:
the array of split strings

Throws:
NullPointerException - if regex or replacement is null
PatternSyntaxException - if regex is invalid

Since:
1.4

See Also:
Pattern.compile(String), Pattern.split(CharSequence,int)


startsWith

public boolean startsWith(String prefix)
Predicate which determines if this String starts with a given prefix. If the prefix is an empty String, true is returned.

Parameters:
prefix - String to compare

Returns:
true if this String starts with the prefix

Throws:
NullPointerException - if prefix is null

See Also:
startsWith(String,int)


startsWith

public boolean startsWith(String prefix,
                          int toffset)
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).

Parameters:
prefix - String to compare
toffset - offset for this String where comparison starts

Returns:
true if this String starts with prefix

Throws:
NullPointerException - if prefix is null

See Also:
regionMatches(boolean,int,String,int,int)


subSequence

public CharSequence subSequence(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).
Specified by:
subSequence in interface CharSequence

Parameters:
begin - index to start substring (inclusive, base 0)
end - index to end at (exclusive)

Returns:
new String which is a substring of this String

Throws:
IndexOutOfBoundsException - if begin < 0 || end > length() || begin > end

Since:
1.4


substring

public String substring(int begin)
Creates a substring of this String, starting at a specified index and ending at the end of this String.

Parameters:
begin - index to start substring (base 0)

Returns:
new String which is a substring of this String

Throws:
IndexOutOfBoundsException - if begin < 0 || begin > length() (while unspecified, this is a StringIndexOutOfBoundsException)


substring

public String substring(int beginIndex,
                        int endIndex)
Creates a substring of this String, starting at a specified index and ending at one character before a specified index.

Parameters:
beginIndex - index to start substring (inclusive, base 0)
endIndex - index to end at (exclusive)

Returns:
new String which is a substring of this String

Throws:
IndexOutOfBoundsException - if begin < 0 || end > length() || begin > end (while unspecified, this is a StringIndexOutOfBoundsException)


toCharArray

public char[] toCharArray()
Copies the contents of this String into a character array. Subsequent changes to the array do not affect the String.

Returns:
character array copying the String


toLowerCase

public String toLowerCase()
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.

Returns:
new lowercased String, or this if no characters were lowercased

See Also:
toLowerCase(Locale), toUpperCase()


toLowerCase

public String toLowerCase(Locale loc)
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.

Parameters:
loc - locale to use

Returns:
new lowercased String, or this if no characters were lowercased

Throws:
NullPointerException - if loc is null

Since:
1.1

See Also:
toUpperCase(Locale)


toString

public String toString()
Returns this, as it is already a String!
Specified by:
toString in interface CharSequence
Overrides:
toString in interface Object

Returns:
this


toUpperCase

public String toUpperCase()
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.

Returns:
new uppercased String, or this if no characters were uppercased

See Also:
toUpperCase(Locale), toLowerCase()


toUpperCase

public String toUpperCase(Locale loc)
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.

Parameters:
loc - locale to use

Returns:
new uppercased String, or this if no characters were uppercased

Throws:
NullPointerException - if loc is null

Since:
1.1

See Also:
toLowerCase(Locale)


trim

public String trim()
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 Character.isWhitespace(char).

Returns:
new trimmed String, or this if nothing trimmed


valueOf

public static String valueOf(boolean b)
Returns a String representing a boolean.

Parameters:
b - the boolean

Returns:
"true" if b is true, else "false"


valueOf

public static String valueOf(char c)
Returns a String representing a character.

Parameters:
c - the character

Returns:
String containing the single character c


valueOf

public static String valueOf(char[] data)
Returns a String representation of a character array. Subsequent changes to the array do not affect the String.

Parameters:
data - the character array

Returns:
a String containing the same character sequence as data

Throws:
NullPointerException - if data is null

See Also:
valueOf(char[],int,int), String(char[])


valueOf

public static 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.

Parameters:
data - character array
offset - position (base 0) to start copying out of data
count - the number of characters from data to copy

Returns:
String containing the chars from data[offset..offset+count]

Throws:
NullPointerException - if data is null
IndexOutOfBoundsException - if (offset < 0 || count < 0 || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)

See Also:
String(char[],int,int)


valueOf

public static String valueOf(double d)
Returns a String representing a double.

Parameters:
d - the double

Returns:
String containing the double

See Also:
Double.toString(double)


valueOf

public static String valueOf(float f)
Returns a String representing a float.

Parameters:
f - the float

Returns:
String containing the float

See Also:
Float.toString(float)


valueOf

public static String valueOf(int i)
Returns a String representing an integer.

Parameters:
i - the integer

Returns:
String containing the integer in base 10

See Also:
Integer.toString(int)


valueOf

public static String valueOf(Object obj)
Returns a String representation of an Object. This is "null" if the object is null, otherwise it is obj.toString() (which can be null).

Parameters:
obj - the Object

Returns:
the string conversion of obj


valueOf

public static String valueOf(long l)
Returns a String representing a long.

Parameters:
l - the long

Returns:
String containing the long in base 10

See Also:
Long.toString(long)


String.java -- immutable character sequences; the object of string literals Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.