java.lang
Class String

java.lang.Object
  extended by java.lang.String
All Implemented Interfaces:
Comparable

public final class String
extends Object
implements Comparable

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

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(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).
 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 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.
 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 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.
 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.
 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 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()
          Lowercases this String.
 String toLowerCase(Locale locale)
          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 locale)
          Uppercases this String according to a particular locale.
 String trim()
          Trims all characters less than or equal to ' ' (' ') 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(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(long l)
          Returns a String representing a long.
static String valueOf(Object obj)
          Returns a String representation of an Object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

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

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[] 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 characters 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
See Also:
#String(byte[], int, int, String)

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
Error - if the decoding fails
Since:
1.1
See Also:
String(byte[], int, int), #String(byte[], int, int, String)

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 Detail

length

public int length()
Returns the number of characters contained in this String.

Returns:
the length of this String

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)

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)

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

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

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

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)

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

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

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

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)

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)

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)

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 class Object
Returns:
hashcode value of this String
See Also:
Object.equals(Object), System.identityHashCode(Object)

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

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

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

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

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 begin,
                        int end)
Creates a substring of this String, starting at a specified index and ending at one character before a specified index.

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 (while unspecified, this is a StringIndexOutOfBoundsException)

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

toLowerCase

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

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

toUpperCase

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

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

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

Returns:
new trimmed String, or this if nothing trimmed

toString

public String toString()
Returns this, as it is already a String!

Overrides:
toString in class Object
Returns:
this
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

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

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

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(double d)
Returns a String representing a double.

Parameters:
d - the double
Returns:
String containing the double
See Also:
Double.toString(double)