Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.lang

Class String

java.lang.Object
|
+--java.lang.String

All Implemented Interfaces:

Serializable, Comparable, CharSequence


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:Authors:

Field Summary

static java.util.ComparatorCASE_INSENSITIVE_ORDER

A Comparator that uses String.compareToIgnoreCase(String).

Constructor Summary

String()

Creates an empty String (length 0).
String(java.lang.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, java.lang.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, java.lang.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(java.lang.StringBuffer buffer)

Creates a new String using the character sequence represented by the StringBuffer.

Method Summary

charcharAt(int index)

Returns the character located at the specified index within this String.
intcompareTo(java.lang.String anotherString)

Compares this String and another String (case sensitive, lexicographically).
intcompareTo(java.lang.Object o)

Behaves like compareTo(java.lang.String) unless the Object is not a String.
intcompareToIgnoreCase(java.lang.String s)

Compares this String and another String (case insensitive).
java.lang.Stringconcat(java.lang.String str)

Concatenates a String to this String.
booleancontentEquals(java.lang.StringBuffer buffer)

Compares the given StringBuffer to this String.
static java.lang.StringcopyValueOf(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 java.lang.StringcopyValueOf(char[] data)

Returns a String representation of a character array.
booleanendsWith(java.lang.String suffix)

Predicate which determines if this String ends with a given suffix.
booleanequals(java.lang.Object anObject)

Predicate which compares anObject to this.
booleanequalsIgnoreCase(java.lang.String anotherString)

Compares a String to this String, ignoring case.
voidgetBytes(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(java.lang.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.
voidgetChars(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.
inthashCode()

Computes the hashcode for this String.
intindexOf(int ch)

Finds the first instance of a character in this String.
intindexOf(int ch, int fromIndex)

Finds the first instance of a character in this String, starting at a given index.
intindexOf(java.lang.String str)

Finds the first instance of a String in this String.
intindexOf(java.lang.String str, int fromIndex)

Finds the first instance of a String in this String, starting at a given index.
java.lang.Stringintern()

Fetches this String from the intern hashtable.
intlastIndexOf(int ch)

Finds the last instance of a character in this String.
intlastIndexOf(int ch, int fromIndex)

Finds the last instance of a character in this String, starting at a given index.
intlastIndexOf(java.lang.String str)

Finds the last instance of a String in this String.
intlastIndexOf(java.lang.String str, int fromIndex)

Finds the last instance of a String in this String, starting at a given index.
intlength()

Returns the number of characters contained in this String.
booleanmatches(java.lang.String regex)

Test if this String matches a regular expression.
booleanregionMatches(int toffset, java.lang.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.
booleanregionMatches(boolean ignoreCase, int toffset, java.lang.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.
java.lang.Stringreplace(char oldChar, char newChar)

Replaces every instance of a character in this String with a new character.
java.lang.StringreplaceAll(java.lang.String regex, java.lang.String replacement)

Replaces all matching substrings of the regular expression with a given replacement.
java.lang.StringreplaceFirst(java.lang.String regex, java.lang.String replacement)

Replaces the first substring match of the regular expression with a given replacement.
java.lang.String[]split(java.lang.String regex, int limit)

Split this string around the matches of a regular expression.
java.lang.String[]split(java.lang.String regex)

Split this string around the matches of a regular expression.
booleanstartsWith(java.lang.String prefix, int toffset)

Predicate which determines if this String contains the given prefix, beginning comparison at toffset.
booleanstartsWith(java.lang.String prefix)

Predicate which determines if this String starts with a given prefix.
java.lang.CharSequencesubSequence(int beginIndex, int endIndex)

Creates a substring of this String, starting at a specified index and ending at one character before a specified index.
java.lang.Stringsubstring(int begin)

Creates a substring of this String, starting at a specified index and ending at the end of this String.
java.lang.Stringsubstring(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.
java.lang.StringtoLowerCase(java.util.Locale loc)

Lowercases this String according to a particular locale.
java.lang.StringtoLowerCase()

Lowercases this String.
java.lang.StringtoString()

Returns this, as it is already a String!
java.lang.StringtoUpperCase(java.util.Locale loc)

Uppercases this String according to a particular locale.
java.lang.StringtoUpperCase()

Uppercases this String.
java.lang.Stringtrim()

Trims all characters less than or equal to '\u0020' (' ') from the beginning and end of this String.
static java.lang.StringvalueOf(java.lang.Object obj)

Returns a String representation of an Object.
static java.lang.StringvalueOf(char[] data)

Returns a String representation of a character array.
static java.lang.StringvalueOf(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 java.lang.StringvalueOf(boolean b)

Returns a String representing a boolean.
static java.lang.StringvalueOf(char c)

Returns a String representing a character.
static java.lang.StringvalueOf(int i)

Returns a String representing an integer.
static java.lang.StringvalueOf(long l)

Returns a String representing a long.
static java.lang.StringvalueOf(float f)

Returns a String representing a float.
static java.lang.StringvalueOf(double d)

Returns a String representing a double.

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:See Also:


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 java.nio.charset.CharsetDecoder. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Since:Parameters:

Throws:

See Also:


String

public String(byte[] ascii, int hibyte)

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:

Throws:

See Also:


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 java.nio.charset.CharsetDecoder. The behavior is not specified if the decoder encounters invalid characters; this implementation throws an Error.

Since:Parameters:

Throws:

See Also:


String

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

Throws:

See Also:


String

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

Since:Parameters:

Throws:


String

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

Since:Parameters:

Throws:

See Also:


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:

Throws:


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:

Throws:


String

public String(java.lang.String str)

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

Parameters:

Throws:


String

public String(java.lang.StringBuffer buffer)

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

Parameters:

Throws:


Method Details

charAt

public char charAt(int index)

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

Parameters:

Returns:

Throws:


compareTo

public int compareTo(java.lang.Object o)

Behaves like compareTo(java.lang.String) unless the Object is not a String. Then it throws a ClassCastException.

Since:Parameters:

Returns:

Throws:


compareTo

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

Returns:

Throws:


compareToIgnoreCase

public int compareToIgnoreCase(java.lang.String s)

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 java.text.Collator.

Since:Parameters:

Returns:

See Also:


concat

public String concat(java.lang.String str)

Concatenates a String to this String. This results in a new string unless one of the two originals is "".

Parameters:

Returns:

Throws:


contentEquals

public boolean contentEquals(java.lang.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.

Since:Parameters:

Returns:

Throws:


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:

Returns:

Throws:

See Also:


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:

Returns:

Throws:

See Also:


endsWith

public boolean endsWith(java.lang.String suffix)

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

Parameters:

Returns:

Throws:

See Also:


equals

public boolean equals(java.lang.Object anObject)

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

Parameters:

Returns:

See Also:


equalsIgnoreCase

public boolean equalsIgnoreCase(java.lang.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:

Parameters:

Returns:

See Also:


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 java.nio.charset.CharsetEncoder. The behavior is not specified if the encoder encounters a problem; this implementation returns null.

Since:Returns:


getBytes

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

Parameters:

Throws:

See Also:


getBytes

public byte[] getBytes(java.lang.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 java.nio.charset.CharsetEncoder, and for valid character sets, see java.nio.charset.Charset. The behavior is not specified if the encoder encounters a problem; this implementation returns null.

Since:Parameters:

Returns:

Throws:


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:

Throws:


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:


indexOf

public int indexOf(int ch)

Finds the first instance of a character in this String.

Parameters:

Returns:


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:

Returns:


indexOf

public int indexOf(java.lang.String str)

Finds the first instance of a String in this String.

Parameters:

Returns:

Throws:


indexOf

public int indexOf(java.lang.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:

Returns:

Throws:


intern

public String intern()

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.

Returns:


lastIndexOf

public int lastIndexOf(int ch)

Finds the last instance of a character in this String.

Parameters:

Returns:


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:

Returns:


lastIndexOf

public int lastIndexOf(java.lang.String str)

Finds the last instance of a String in this String.

Parameters:

Returns:

Throws:


lastIndexOf

public int lastIndexOf(java.lang.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:

Returns:

Throws:


length

public int length()

Returns the number of characters contained in this String.

Returns:


matches

public boolean matches(java.lang.String regex)

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

Since:Parameters:

Returns:

Throws:

See Also:


regionMatches

public boolean regionMatches(boolean ignoreCase, int toffset, java.lang.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:

Returns:

Throws:


regionMatches

public boolean regionMatches(int toffset, java.lang.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:

Returns:

Throws:


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:

Returns:


replaceAll

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

Since:Parameters:

Returns:

Throws:

See Also:


replaceFirst

public String replaceFirst(java.lang.String regex, java.lang.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).

Since:Parameters:

Returns:

Throws:

See Also:


split

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

Since:Parameters:

Returns:

Throws:

See Also:


split

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

Since:Parameters:

Returns:

Throws:

See Also:


startsWith

public boolean startsWith(java.lang.String prefix)

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

Parameters:

Returns:

Throws:

See Also:


startsWith

public boolean startsWith(java.lang.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:

Returns:

Throws:

See Also:


subSequence

public CharSequence subSequence(int beginIndex, int endIndex)

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

Since:Parameters:

Returns:

Throws:


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:

Returns:

Throws:


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:

Returns:

Throws:


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:


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:

See Also:


toLowerCase

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

Since:Parameters:

Returns:

Throws:

See Also:


toString

public String toString()

Returns this, as it is already a String!

Returns:


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:

See Also:


toUpperCase

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

Since:Parameters:

Returns:

Throws:

See Also:


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#whitespace(char).

Returns:


valueOf

public static String valueOf(boolean b)

Returns a String representing a boolean.

Parameters:

Returns:


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:

Returns:

Throws:

See Also:


valueOf

public static String valueOf(char c)

Returns a String representing a character.

Parameters:

Returns:


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:

Returns:

Throws:

See Also:


valueOf

public static String valueOf(double d)

Returns a String representing a double.

Parameters:

Returns:

See Also:


valueOf

public static String valueOf(float f)

Returns a String representing a float.

Parameters:

Returns:

See Also:


valueOf

public static String valueOf(int i)

Returns a String representing an integer.

Parameters:

Returns:

See Also:


valueOf

public static String valueOf(java.lang.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:

Returns:


valueOf

public static String valueOf(long l)

Returns a String representing a long.

Parameters:

Returns:

See Also: