java.lang

Class String

public final class String extends Object implements Serializable, Comparable<String>, 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

UNKNOWN: updated to 1.4; but could use better data sharing via offset field

Field Summary
static Comparator<String>	CASE_INSENSITIVE_ORDER A Comparator that uses `String.compareToIgnoreCase(String)`.

Constructor Summary
	String() Creates an empty String (length 0).
	String(String str) Copies the contents of a String to a new String.
	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(byte[] ascii, int hibyte, int offset, int count) Creates a new String using an 8-bit array of integer values, starting at an offset, and copying up to the count.
	String(byte[] ascii, int hibyte) Creates a new String using an 8-bit array of integer values.
	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(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[] data) Creates a new String using the byte array.
	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.
	String(int[] codePoints, int offset, int count) Creates a new String containing the characters represented in the given subarray of Unicode code points.

Method Summary
char	charAt(int index) Returns the character located at the specified index within this String.
int	codePointAt(int index) Get the code point at the specified index.
int	codePointBefore(int index) Get the code point before the specified index.
int	codePointCount(int start, int end) Return the number of code points between two indices in the `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	contains(CharSequence s) Returns true iff this String contains the sequence of Characters described in s.
boolean	contentEquals(StringBuffer buffer) Compares the given StringBuffer to this String.
boolean	contentEquals(CharSequence seq) Compares the given CharSequence to this String.
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.
static String	copyValueOf(char[] data) Returns a String representation of a character array.
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.
static String	format(Locale locale, String format, Object... args)
static String	format(String format, Object... args)
void	getBytes(int srcBegin, int srcEnd, byte[] 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.
byte[]	getBytes(String enc) Converts the Unicode characters in this String to a byte array.
byte[]	getBytes() Converts the Unicode characters in this String to a byte array.
void	getChars(int srcBegin, int srcEnd, char[] 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. if (s1.equals(s2)) then (s1.intern() == s2.intern()).
boolean	isEmpty() Returns true if, and only if, {@link #length()} is `0`.
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.
int	offsetByCodePoints(int index, int codePointOffset) Return the index into this String that is offset from the given index by `codePointOffset` code points.
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.
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.
String	replace(char oldChar, char newChar) Replaces every instance of a character in this String with a new character.
String	replace(CharSequence target, CharSequence replacement) Returns a string that is this string with all instances of the sequence represented by `target` replaced by the sequence in `replacement`.
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, int limit) Split this string around the matches of a regular expression.
String[]	split(String regex) Split this string around the matches of a regular expression.
boolean	startsWith(String prefix, int toffset) Predicate which determines if this String contains the given prefix, beginning comparison at toffset.
boolean	startsWith(String prefix) Predicate which determines if this String starts with a given prefix.
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.
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.
char[]	toCharArray() Copies the contents of this String into a character array.
String	toLowerCase(Locale loc) Lowercases this String according to a particular locale.
String	toLowerCase() Lowercases this String.
String	toString() Returns this, as it is already a String!
String	toUpperCase(Locale loc) Uppercases this String according to a particular locale.
String	toUpperCase() Uppercases this String.
String	trim() Trims all characters less than or equal to `' '` (`' '`) from the beginning and end of this String.
static String	valueOf(Object obj) Returns a String representation of an Object.
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(boolean b) Returns a String representing a boolean.
static String	valueOf(char c) Returns a String representing a character.
static String	valueOf(int i) Returns a String representing an integer.
static String	valueOf(long l) Returns a String representing a long.
static String	valueOf(float f) Returns a String representing a float.
static String	valueOf(double d) Returns a String representing a double.

Field Detail

CASE_INSENSITIVE_ORDER

public static final Comparator<String> CASE_INSENSITIVE_ORDER

A Comparator that uses String.compareToIgnoreCase(String). This comparator is {@link Serializable}. Note that it ignores Locale, for that, you want a Collator.

Since: 1.2

Constructor Detail

String

public String()

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

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(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 < 0 (overflow) || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)

String

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

Deprecated: use {@link #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 < 0 (overflow) || offset + count > ascii.length) (while unspecified, this is a StringIndexOutOfBoundsException)

String

public String(byte[] ascii, int hibyte)

Deprecated: use {@link #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

String

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

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 Error if the decoding fails

Since: 1.1

String

public String(byte[] data, String 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.

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 Error if the decoding fails

Since: 1.1

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 {@link java.nio.charset.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 Error if the decoding fails

Since: 1.1

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 {@link java.nio.charset.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 Error if the decoding fails

Since: 1.1

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

String

public String(int[] codePoints, int offset, int count)

Creates a new String containing the characters represented in the given subarray of Unicode code points.

Parameters: codePoints the entire array of code points offset the start of the subarray count the length of the subarray

Throws: IllegalArgumentException if an invalid code point is found in the codePoints array IndexOutOfBoundsException if offset is negative or offset + count is greater than the length of the array.

Method Detail

charAt

public char charAt(int index)

Returns the character located at the specified index within this String.

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)

codePointAt

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

Parameters: index the index of the codepoint to get, starting at 0

Returns: the codepoint at the specified index

Throws: IndexOutOfBoundsException if index is negative or >= length()

Since: 1.5

codePointBefore

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

Parameters: index the index just past the codepoint to get, starting at 0

Returns: the codepoint at the specified index

Throws: IndexOutOfBoundsException if index is negative or >= length() (while unspecified, this is a StringIndexOutOfBoundsException)

Since: 1.5

codePointCount

public int codePointCount(int start, int end)

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.

Parameters: start the starting index end one past the ending index

Returns: the number of code points

Since: 1.5

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 {@link java.text.Collator}.

Parameters: str the string to compare against

Returns: the comparison

Since: 1.2

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

contains

public boolean contains(CharSequence s)

Returns true iff this String contains the sequence of Characters described in s.

Parameters: s the CharSequence

Returns: true iff this String contains s

Since: 1.5

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

contentEquals

public boolean contentEquals(CharSequence seq)

Compares the given CharSequence to this String. This is true if the CharSequence has the same content as this String at this moment.

Parameters: seq the CharSequence to compare to

Returns: true if CharSequence has the same character sequence

Throws: NullPointerException if the given CharSequence is null

Since: 1.5

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 < 0 (overflow) || offset + count < 0 (overflow) || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)

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: (char[], int, int) (char[])

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

equals

public boolean equals(Object anObject)

Predicate which compares anObject to this. This is true only for Strings with the same character sequence.

Parameters: anObject the object to compare

Returns: true if anObject is semantically equal to this

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

format

public static String format(Locale locale, String format, Object... args)

Since: 1.5

format

public static String format(String format, Object... args)

Since: 1.5

getBytes

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

Deprecated: use {@link #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 dst byte array which each low byte of this String is copied into 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)

getBytes

public byte[] getBytes(String enc)

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

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 {@link java.nio.charset.CharsetEncoder}. Unsupported characters get replaced by an encoding specific byte.

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

Since: 1.1

getChars

public void getChars(int srcBegin, int srcEnd, char[] 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 dst character array which this String is copied into 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].

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

isEmpty

public boolean isEmpty()

Returns true if, and only if, {@link #length()} is 0.

Returns: true if the length of the string is zero.

Since: 1.6

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.

Returns: the length of this String

matches

public boolean matches(String regex)

Test if this String matches a regular expression. This is shorthand for {@link 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

offsetByCodePoints

public int offsetByCodePoints(int index, int codePointOffset)

Return the index into this String that is offset from the given index by codePointOffset code points.

Parameters: index the index at which to start codePointOffset the number of code points to offset

Returns: 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. IndexOutOfBoundsException if codePointOffset is positive and the substring starting with index has fewer than codePointOffset code points. IndexOutOfBoundsException if codePointOffset is negative and the substring ending with index has fewer than (-codePointOffset) code points.

Since: 1.5

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

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

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

replace

public String replace(CharSequence target, CharSequence replacement)

Returns a string that is this string with all instances of the sequence represented by target replaced by the sequence in replacement.

Parameters: target the sequence to be replaced replacement the sequence used as the replacement

Returns: the string constructed as above

replaceAll

public String replaceAll(String regex, String 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)

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: String compile matcher replaceAll

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

{@link 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

split

public String[] split(String regex, int limit)

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 {@link 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

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

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

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

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)

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

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

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

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

toString

public String toString()

Returns this, as it is already a String!

Returns: this

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

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

trim

public String trim()

Trims all characters less than or equal to ' ' (' ') from the beginning and end of this String. This includes many, but not all, ASCII control characters, and all {@link Character#isWhitespace(char)}.

Returns: new trimmed String, or this if nothing trimmed

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(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: (char[], int, int) (char[])

valueOf

public static String valueOf(char[] data, int offset, int count)

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)