java.lang
Class String
java.lang.Object
|
+--java.lang.String
All Implemented Interfaces:
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:- Paul N. Fisher
- Eric Blake <ebb9@email.byu.edu>
String()
|
String(java.lang.String str)
|
String(char[] data)
|
String(char[] data, int offset, int count)
|
String(byte[] ascii, int hibyte, int offset, int count)
|
String(byte[] ascii, int hibyte)
|
String(byte[] data, int offset, int count, java.lang.String encoding)
|
String(byte[] data, java.lang.String encoding)
|
String(byte[] data, int offset, int count)
|
String(byte[] data)
|
String(java.lang.StringBuffer buffer)
|
char | charAt(int index)
|
int | compareTo(java.lang.String anotherString)
|
int | compareTo(java.lang.Object o)
|
int | compareToIgnoreCase(java.lang.String s)
|
java.lang.String | concat(java.lang.String str)
|
boolean | contentEquals(java.lang.StringBuffer buffer)
|
static java.lang.String | copyValueOf(char[] data, int offset, int count)
|
static java.lang.String | copyValueOf(char[] data)
|
boolean | endsWith(java.lang.String suffix)
|
boolean | equals(java.lang.Object anObject)
|
boolean | equalsIgnoreCase(java.lang.String anotherString)
|
void | getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)
|
byte[] | getBytes(java.lang.String enc)
|
byte[] | getBytes()
|
void | getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
|
int | hashCode()
|
int | indexOf(int ch)
|
int | indexOf(int ch, int fromIndex)
|
int | indexOf(java.lang.String str)
|
int | indexOf(java.lang.String str, int fromIndex)
|
java.lang.String | intern()
|
int | lastIndexOf(int ch)
|
int | lastIndexOf(int ch, int fromIndex)
|
int | lastIndexOf(java.lang.String str)
|
int | lastIndexOf(java.lang.String str, int fromIndex)
|
int | length()
|
boolean | matches(java.lang.String regex)
|
boolean | regionMatches(int toffset, java.lang.String other, int ooffset, int len)
|
boolean | regionMatches(boolean ignoreCase, int toffset, java.lang.String other, int ooffset, int len)
|
java.lang.String | replace(char oldChar, char newChar)
|
java.lang.String | replaceAll(java.lang.String regex, java.lang.String replacement)
|
java.lang.String | replaceFirst(java.lang.String regex, java.lang.String replacement)
|
java.lang.String[] | split(java.lang.String regex, int limit)
|
java.lang.String[] | split(java.lang.String regex)
|
boolean | startsWith(java.lang.String prefix, int toffset)
|
boolean | startsWith(java.lang.String prefix)
|
java.lang.CharSequence | subSequence(int beginIndex, int endIndex)
|
java.lang.String | substring(int begin)
|
java.lang.String | substring(int beginIndex, int endIndex)
|
char[] | toCharArray()
|
java.lang.String | toLowerCase(java.util.Locale loc)
|
java.lang.String | toLowerCase()
|
java.lang.String | toString()
|
java.lang.String | toUpperCase(java.util.Locale loc)
|
java.lang.String | toUpperCase()
|
java.lang.String | trim()
|
static java.lang.String | valueOf(java.lang.Object obj)
|
static java.lang.String | valueOf(char[] data)
|
static java.lang.String | valueOf(char[] data, int offset, int count)
|
static java.lang.String | valueOf(boolean b)
|
static java.lang.String | valueOf(char c)
|
static java.lang.String | valueOf(int i)
|
static java.lang.String | valueOf(long l)
|
static java.lang.String | valueOf(float f)
|
static java.lang.String | valueOf(double d)
|
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:
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:
charAt
public char charAt(int index)
Returns the character located at the specified index within this String.
Parameters:
Returns:
- character located at position index
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:
- newly concatenated String
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:
- true if StringBuffer has the same character sequence
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:
- a String containing the same character sequence as data
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:
- String containing the chars from data[offset..offset+count]
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:
- true if this String ends with the suffix
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:
- true if anObject is semantically equal to this
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:
c1 == c2
Character.toUpperCase(c1)
== Character.toUpperCase(c2)
Character.toLowerCase(c1)
== Character.toLowerCase(c2)
Parameters:
Returns:
- true if anotherString is equal, ignoring case
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:
- the resulting byte array, or null on a problem
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:
NullPointerException
- if dst is null and copy length is non-zeroIndexOutOfBoundsException
- if any indices are out of bounds
(while unspecified, source problems cause a
StringIndexOutOfBoundsException, and dst problems cause an
ArrayIndexOutOfBoundsException)
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:
- the resulting byte array, or null on a problem
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:
NullPointerException
- if dst is nullIndexOutOfBoundsException
- 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:
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:
Returns:
- location (base 0) of the character, or -1 if not found
indexOf
public int indexOf(java.lang.String str)
Finds the first instance of a String in this String.
Parameters:
Returns:
- location (base 0) of the String, or -1 if not found
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:
- location (base 0) of the String, or -1 if not found
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:
- 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:
Returns:
- location (base 0) of the character, or -1 if not found
lastIndexOf
public int lastIndexOf(java.lang.String str)
Finds the last instance of a String in this String.
Parameters:
Returns:
- location (base 0) of the String, or -1 if not found
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:
- location (base 0) of the String, or -1 if not found
Throws:
length
public int length()
Returns the number of characters contained in this String.
Returns:
- the length of this String
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:
- true if the pattern matches
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:
- true if regions match, false otherwise
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:
- true if regions match (case sensitive)
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:
- new String with all instances of oldChar replaced with newChar
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:
- the array of split strings
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:
- the array of split strings
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:
- true if this String starts with the prefix
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:
- true if this String starts with prefix
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:
- new String which is a substring of this String
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:
- new String which is a substring of this String
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:
- new String which is a substring of this String
Throws:
IndexOutOfBoundsException
- if begin < 0 || end > length()
|| begin > end (while unspecified, this is a
StringIndexOutOfBoundsException)
toCharArray
public char[] toCharArray()
Copies the contents of this String into a character array. Subsequent
changes to the array do not affect the String.
Returns:
- character array copying the String
toLowerCase
public String toLowerCase()
Lowercases this String. This uses Unicode's special case mappings, as
applied to the platform's default Locale, so the resulting string may
be a different length.
Returns:
- new lowercased String, or this if no characters were lowercased
See Also:
toLowerCase
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:
- new lowercased String, or this if no characters were lowercased
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:
- new uppercased String, or this if no characters were uppercased
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:
- new uppercased String, or this if no characters were uppercased
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:
- new trimmed String, or this if nothing trimmed
valueOf
public static String valueOf(boolean b)
Returns a String representing a boolean.
Parameters:
Returns:
- "true" if b is true, else "false"
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:
- a String containing the same character sequence as data
Throws:
See Also:
valueOf
public static String valueOf(char c)
Returns a String representing a character.
Parameters:
Returns:
- String containing the single character c
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:
- String containing the chars from data[offset..offset+count]
Throws:
See Also:
valueOf
public static String valueOf(double d)
Returns a String representing a double.
Parameters:
Returns:
- String containing the double
See Also:
valueOf
public static String valueOf(float f)
Returns a String representing a float.
Parameters:
Returns:
- String containing the float
See Also:
valueOf
public static String valueOf(int i)
Returns a String representing an integer.
Parameters:
Returns:
- String containing the integer in base 10
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:
- the string conversion of obj
valueOf
public static String valueOf(long l)
Returns a String representing a long.
Parameters:
Returns:
- String containing the long in base 10
See Also:
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.