java.lang
Class String

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

public final class String
extends Object

A general class of objects to represent character Strings. Strings are constant, their values cannot be changed after creation. The compiler makes sure that each String constant actually results in a String object. Because String objects are immutable they can be shared. For example:

	String str = "abc";
 
is equivalent to:
	char data[] = {'a', 'b', 'c'};
	String str = new String(data);
 
Here are some more examples of how strings can be used:
 	System.out.println("abc");
 	String cde = "cde";
 	System.out.println("abc" + cde);
	String c = "abc".substring(2,3);
	String d = cde.substring(1, 2);
 

See Also:
StringBuffer

Constructor Summary
String()
          Constructs a new empty String.
String(byte[] ascii, int hibyte)
          Constructs a new String whose value is the specified array of bytes.
String(byte[] ascii, int hibyte, int offset, int count)
          Constructs a new String whose initial value is the specified subarray of bytes.
String(char[] value)
          Constructs a new String whose initial value is the specified array of characters.
String(char[] value, int offset, int count)
          Constructs a new String whose initial value is the specified sub array of characters.
String(String value)
          Constructs a new String that is a copy of the specified String.
String(StringBuffer buffer)
          Construct a new string whose value is the current contents of the given string buffer
 
Method Summary
 char charAt(int index)
          Returns the character at the specified index.
 int compareTo(String anotherString)
          Compares this String to another specified String.
 String concat(String str)
          Concatenates the specified string to the end of this String and returns a new String object representing the concatenation.
static String copyValueOf(char[] data)
          Returns a String that is equivalent to the specified character array.
static String copyValueOf(char[] data, int offset, int count)
          Returns a String that is equivalent to the specified character array.
 boolean endsWith(String suffix)
          Determines whether the String ends with some suffix.
 boolean equals(Object anObject)
          Compares this String to the specified object.
 boolean equalsIgnoreCase(String anotherString)
          Compares this String to another object.
 void getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)
          Copies characters from this String into the specified byte array.
 void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
          Copies characters from this String into the specified character array.
 int hashCode()
          Returns a hashcode for this String.
 int indexOf(int ch)
          Returns the index within this String of the first occurrence of the specified character.
 int indexOf(int ch, int fromIndex)
          Returns the index within this String of the first occurrence of the specified character, starting the search at fromIndex.
 int indexOf(String str)
          Returns the index within this String of the first occurrence of the specified substring.
 int indexOf(String str, int fromIndex)
          Returns the index within this String of the first occurrence of the specified substring.
 String intern()
          Returns a String that is equal to this String but which is guaranteed to be from the unique String pool.
 int lastIndexOf(int ch)
          Returns the index within this String of the last occurrence of the specified character.
 int lastIndexOf(int ch, int fromIndex)
          Returns the index within this String of the last occurrence of the specified character.
 int lastIndexOf(String str)
          Returns the index within this String of the rightmost occurrence of the specified substring.
 int lastIndexOf(String str, int fromIndex)
          Returns the index within this String of the last occurrence of the specified substring.
 int length()
          Returns the length of the String.
 boolean regionMatches(boolean ignoreCase, int toffset, String other, int ooffset, int len)
          Determines whether a region of this String matches the specified region of the specified String.
 boolean regionMatches(int toffset, String other, int ooffset, int len)
          Determines whether a region of this String matches the specified region of the specified String.
 String replace(char oldChar, char newChar)
          Converts this String by replacing all occurences of oldChar with newChar.
 boolean startsWith(String prefix)
          Determines whether this String starts with some prefix.
 boolean startsWith(String prefix, int toffset)
          Determines whether this String starts with some prefix.
 String substring(int beginIndex)
          Returns the substring of this String.
 String substring(int beginIndex, int endIndex)
          Returns the substring of a String.
 char[] toCharArray()
          Converts this String to a character array.
 String toLowerCase()
          Converts all of the characters in this String to lower case.
 String toString()
          Converts the object (in this case already a String) to a String.
 String toUpperCase()
          Converts all of the characters in this String to upper case.
 String trim()
          Trims leading and trailing whitespace from this String.
static String valueOf(boolean b)
          Returns a String object that represents the state of the specified boolean.
static String valueOf(char c)
          Returns a String object that contains a single character
static String valueOf(char[] data)
          Returns a String that is equivalent to the specified character array.
static String valueOf(char[] data, int offset, int count)
          Returns a String that is equivalent to the specified character array.
static String valueOf(double d)
          Returns a String object that represents the value of the specified double.
static String valueOf(float f)
          Returns a String object that represents the value of the specified float.
static String valueOf(int i)
          Returns a String object that represents the value of the specified integer.
static String valueOf(long l)
          Returns a String object that represents the value of the specified long.
static String valueOf(Object obj)
          Returns a String that represents the String value of the object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

String

public String()
Constructs a new empty String.


String

public String(String value)
Constructs a new String that is a copy of the specified String.

Parameters:
value - the initial value of the String

String

public String(char[] value)
Constructs a new String whose initial value is the specified array of characters.

Parameters:
value - the initial value of the String

String

public String(char[] value,
              int offset,
              int count)
Constructs a new String whose initial value is the specified sub array of characters. The length of the new string will be count characters starting at offset within the specified character array.

Parameters:
value - the initial value of the String, an array of characters
offset - the offset into the value of the String
count - the length of the value of the String
Throws:
StringIndexOutOfBoundsException - If the offset and count arguments are invalid.

String

public String(byte[] ascii,
              int hibyte,
              int offset,
              int count)
Constructs a new String whose initial value is the specified subarray of bytes. The high-byte of each character can be specified, it should usually be 0. The length of the new String will be count characters starting at offset within the specified character array.

Parameters:
ascii - the bytes that will be converted to characters
hibyte - the high byte of each Unicode character
offset - the offset into the ascii array
count - the length of the String
Throws:
StringIndexOutOfBoundsException - If the offset and count arguments are invalid.

String

public String(byte[] ascii,
              int hibyte)
Constructs a new String whose value is the specified array of bytes. The byte array is transformed into Unicode chars using hibyte as the upper byte of each character.

Parameters:
ascii - the byte that will be converted to characters
hibyte - the top 8 bits of each 16 bit Unicode character

String

public String(StringBuffer buffer)
Construct a new string whose value is the current contents of the given string buffer

Parameters:
buffer - the stringbuffer to be converted
Method Detail

length

public int length()
Returns the length of the String. The length of the String is equal to the number of 16 bit Unicode characters in the String.


charAt

public char charAt(int index)
Returns the character at the specified index. An index ranges from 0 to length() - 1.

Parameters:
index - the index of the desired character
Throws:
StringIndexOutOfBoundsException - If the index is not in the range 0 to length()-1.

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)
Copies characters from this String into the specified character array. The characters of the specified substring (determined by srcBegin and srcEnd) are copied into the character array, starting at the array's dstBegin location.

Parameters:
srcBegin - index of the first character in the string
srcEnd - end of the characters that are copied
dst - the destination array
dstBegin - the start offset in the destination array

getBytes

public void getBytes(int srcBegin,
                     int srcEnd,
                     byte[] dst,
                     int dstBegin)
Copies characters from this String into the specified byte array. Copies the characters of the specified substring (determined by srcBegin and srcEnd) into the byte array, starting at the array's dstBegin location.

Parameters:
srcBegin - index of the first character in the String
srcEnd - end of the characters that are copied
dst - the destination array
dstBegin - the start offset in the destination array

equals

public boolean equals(Object anObject)
Compares this String to the specified object. Returns true if the object is equal to this String; that is, has the same length and the same characters in the same sequence.

Overrides:
equals in class Object
Parameters:
anObject - the object to compare this String against
Returns:
true if the Strings are equal; false otherwise.
See Also:
Hashtable

equalsIgnoreCase

public boolean equalsIgnoreCase(String anotherString)
Compares this String to another object. Returns true if the object is equal to this String; that is, has the same length and the same characters in the same sequence. Upper case characters are folded to lower case before they are compared.

Parameters:
anotherString - the String to compare this String against
Returns:
true if the Strings are equal, ignoring case; false otherwise.

compareTo

public int compareTo(String anotherString)
Compares this String to another specified String. Returns an integer that is less than, equal to, or greater than zero. The integer's value depends on whether this String is less than, equal to, or greater than anotherString.

Parameters:
anotherString - the String to be compared

regionMatches

public boolean regionMatches(int toffset,
                             String other,
                             int ooffset,
                             int len)
Determines whether a region of this String matches the specified region of the specified String.

Parameters:
toffset - where to start looking in this String
other - the other String
ooffset - where to start looking in the other String
len - the number of characters to compare
Returns:
true if the region matches with the other; false otherwise.

regionMatches

public boolean regionMatches(boolean ignoreCase,
                             int toffset,
                             String other,
                             int ooffset,
                             int len)
Determines whether a region of this String matches the specified region of the specified String. If the boolean ignoreCase is true, upper case characters are considered equivalent to lower case letters.

Parameters:
ignoreCase - if true, case is ignored
toffset - where to start looking in this String
other - the other String
ooffset - where to start looking in the other String
len - the number of characters to compare
Returns:
true if the region matches with the other; false otherwise.

startsWith

public boolean startsWith(String prefix,
                          int toffset)
Determines whether this String starts with some prefix.

Parameters:
prefix - the prefix
toffset - where to begin looking in the the String
Returns:
true if the String starts with the specified prefix; false otherwise.

startsWith

public boolean startsWith(String prefix)
Determines whether this String starts with some prefix.

Parameters:
prefix - the prefix
Returns:
true if the String starts with the specified prefix; false otherwise.

endsWith

public boolean endsWith(String suffix)
Determines whether the String ends with some suffix.

Parameters:
suffix - the suffix
Returns:
true if the String ends with the specified suffix; false otherwise.

hashCode

public int hashCode()
Returns a hashcode for this String. This is a large number composed of the character values in the String.

Overrides:
hashCode in class Object
See Also:
Hashtable

indexOf

public int indexOf(int ch)
Returns the index within this String of the first occurrence of the specified character. This method returns -1 if the index is not found.

Parameters:
ch - the character to search for

indexOf

public int indexOf(int ch,
                   int fromIndex)
Returns the index within this String of the first occurrence of the specified character, starting the search at fromIndex. This method returns -1 if the index is not found.

Parameters:
ch - the character to search for
fromIndex - the index to start the search from

lastIndexOf

public int lastIndexOf(int ch)
Returns the index within this String of the last occurrence of the specified character. The String is searched backwards starting at the last character. This method returns -1 if the index is not found.

Parameters:
ch - the character to search for

lastIndexOf

public int lastIndexOf(int ch,
                       int fromIndex)
Returns the index within this String of the last occurrence of the specified character. The String is searched backwards starting at fromIndex. This method returns -1 if the index is not found.

Parameters:
ch - the character to search for
fromIndex - the index to start the search from

indexOf

public int indexOf(String str)
Returns the index within this String of the first occurrence of the specified substring. This method returns -1 if the index is not found.

Parameters:
str - the substring to search for

indexOf

public int indexOf(String str,
                   int fromIndex)
Returns the index within this String of the first occurrence of the specified substring. The search is started at fromIndex. This method returns -1 if the index is not found.

Parameters:
str - the substring to search for
fromIndex - the index to start the search from

lastIndexOf

public int lastIndexOf(String str)
Returns the index within this String of the rightmost occurrence of the specified substring. The rightmost empty string "" is considered to occur at the index value this.length(). This method returns -1 if the index is not found.

Parameters:
str - the substring to search for

lastIndexOf

public int lastIndexOf(String str,
                       int fromIndex)
Returns the index within this String of the last occurrence of the specified substring. The returned index indicates the start of the substring, and it must be equal to or less than fromIndex. This method returns -1 if the index is not found.

Parameters:
str - the substring to search for
fromIndex - the index to start the search from

substring

public String substring(int beginIndex)
Returns the substring of this String. The substring is specified by a beginIndex (inclusive) and the end of the string.

Parameters:
beginIndex - the beginning index, inclusive

substring

public String substring(int beginIndex,
                        int endIndex)
Returns the substring of a String. The substring is specified by a beginIndex (inclusive) and an endIndex (exclusive).

Parameters:
beginIndex - the beginning index, inclusive
endIndex - the ending index, exclusive
Throws:
StringIndexOutOfBoundsException - If the beginIndex or the endIndex is out of range.

concat

public String concat(String str)
Concatenates the specified string to the end of this String and returns a new String object representing the concatenation.

Parameters:
str - the String which is concatenated to the end of this String
Returns:
the concatenated String

replace

public String replace(char oldChar,
                      char newChar)
Converts this String by replacing all occurences of oldChar with newChar.

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

toLowerCase

public String toLowerCase()
Converts all of the characters in this String to lower case.

Returns:
the String, converted to lowercase.
See Also:
Character.toLowerCase(char), toUpperCase()

toUpperCase

public String toUpperCase()
Converts all of the characters in this String to upper case.

Returns:
the String, converted to uppercase.
See Also:
Character.toUpperCase(char), toLowerCase()

trim

public String trim()
Trims leading and trailing whitespace from this String.

Returns:
the String, with whitespace removed.

toString

public String toString()
Converts the object (in this case already a String) to a String. Otherwise this class would inherit class Object's version of tostring().

Overrides:
toString in class Object
Returns:
the String itself.

toCharArray

public char[] toCharArray()
Converts this String to a character array. This creates a new array.

Returns:
an array of characters.

valueOf

public static String valueOf(Object obj)
Returns a String that represents the String value of the object. The object may choose how to represent itself by implementing the toString() method.

Parameters:
obj - the object to be converted

valueOf

public static String valueOf(char[] data)
Returns a String that is equivalent to the specified character array. Uses the original array as the body of the String (ie. it does not copy it to a new array).

Parameters:
data - the character array

valueOf

public static String valueOf(char[] data,
                             int offset,
                             int count)
Returns a String that is equivalent to the specified character array.

Parameters:
data - the character array
offset - the offset into the value of the String
count - the length of the value of the String

copyValueOf

public static String copyValueOf(char[] data,
                                 int offset,
                                 int count)
Returns a String that is equivalent to the specified character array. It creates a new array and copies the characters into it.

Parameters:
data - the character array
offset - the offset into the value of the String
count - the length of the value of the String

copyValueOf

public static String copyValueOf(char[] data)
Returns a String that is equivalent to the specified character array. It creates a new array and copies the characters into it.

Parameters:
data - the character array

valueOf

public static String valueOf(boolean b)
Returns a String object that represents the state of the specified boolean.

Parameters:
b - the boolean

valueOf

public static String valueOf(char c)
Returns a String object that contains a single character

Parameters:
c - the character
Returns:
the resulting String.

valueOf

public static String valueOf(int i)
Returns a String object that represents the value of the specified integer.

Parameters:
i - the integer

valueOf

public static String valueOf(long l)
Returns a String object that represents the value of the specified long.

Parameters:
l - the long

valueOf

public static String valueOf(float f)
Returns a String object that represents the value of the specified float.

Parameters:
f - the float

valueOf

public static String valueOf(double d)
Returns a String object that represents the value of the specified double.

Parameters:
d - the double

intern

public String intern()
Returns a String that is equal to this String but which is guaranteed to be from the unique String pool. For example:
s1.intern() == s2.intern() <=> s1.equals(s2).