java.lang.Object | |
↳ | java.lang.String |
An immutable sequence of characters/code units (char
s). A
String
is represented by array of UTF-16 values, such that
Unicode supplementary characters (code points) are stored/encoded as
surrogate pairs via Unicode code units (char
).
Backing Arrays
This class is implemented using a char[]. The length of the array may exceed
the length of the string. For example, the string "Hello" may be backed by
the array ['H', 'e', 'l', 'l', 'o', 'W'. 'o', 'r', 'l', 'd']
with
offset 0 and length 5.
Multiple strings can share the same char[] because strings are immutable.
The substring(int)
method always returns a string that
shares the backing array of its source string. Generally this is an
optimization: fewer character arrays need to be allocated, and less copying
is necessary. But this can also lead to unwanted heap retention. Taking a
short substring of long string means that the long shared char[] won't be
garbage until both strings are garbage. This typically happens when parsing
small substrings out of a large input. To avoid this where necessary, call
new String(longString.subString(...))
. The string copy constructor
always ensures that the backing array is no larger than necessary.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CASE_INSENSITIVE_ORDER | A comparator ignoring the case of the characters. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates an empty string.
| |||||||||||
Converts the byte array to a string using the system's
default charset . | |||||||||||
This constructor was deprecated
in API level 1.
Use
String(byte[]) or String(byte[], String) instead.
| |||||||||||
Converts a subsequence of the byte array to a string using the system's
default charset . | |||||||||||
This constructor was deprecated
in API level 1.
Use
String(byte[], int, int) instead.
| |||||||||||
Converts the byte array to a string using the named charset.
| |||||||||||
Converts the byte array to a string using the named charset.
| |||||||||||
Converts the byte array to a string using the given charset.
| |||||||||||
Converts the byte array to a String using the given charset.
| |||||||||||
Initializes this string to contain the characters in the specified
character array.
| |||||||||||
Initializes this string to contain the specified characters in the
character array.
| |||||||||||
Constructs a new string with the same sequence of characters as
toCopy . | |||||||||||
Creates a
String from the contents of the specified
StringBuffer . | |||||||||||
Creates a
String from the sub-array of Unicode code points. | |||||||||||
Creates a
String from the contents of the specified StringBuilder . |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns the character at
index . | |||||||||||
Returns the Unicode code point at the given
index . | |||||||||||
Returns the Unicode code point that precedes the given
index . | |||||||||||
Calculates the number of Unicode code points between
start
and end . | |||||||||||
Compares the specified string to this string using the Unicode values of
the characters.
| |||||||||||
Compares the specified string to this string using the Unicode values of
the characters, ignoring case differences.
| |||||||||||
Concatenates this string and the specified string.
| |||||||||||
Determines if this
String contains the sequence of characters in
the CharSequence passed. | |||||||||||
Compares a
CharSequence to this String to determine if
their contents are equal. | |||||||||||
Returns whether the characters in the StringBuffer
strbuf are the
same as those in this string. | |||||||||||
Creates a new string containing the specified characters in the character
array.
| |||||||||||
Creates a new string containing the characters in the specified character
array.
| |||||||||||
Compares the specified string to this string to determine if the
specified string is a suffix.
| |||||||||||
Compares the specified object to this string and returns true if they are
equal.
| |||||||||||
Compares the specified string to this string ignoring the case of the
characters and returns true if they are equal.
| |||||||||||
Returns a formatted string, using the supplied format and arguments,
localized to the given locale.
| |||||||||||
Returns a localized formatted string, using the supplied format and arguments,
using the user's default locale.
| |||||||||||
This method was deprecated
in API level 1.
Use
getBytes() or getBytes(String) instead.
| |||||||||||
Returns a new byte array containing the characters of this string encoded using the
named charset.
| |||||||||||
Returns a new byte array containing the characters of this string encoded using the
given charset.
| |||||||||||
Returns a new byte array containing the characters of this string encoded using the
system's
default charset . | |||||||||||
Copies the specified characters in this string to the character array
starting at the specified offset in the character array.
| |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Searches in this string for the first index of the specified character.
| |||||||||||
Searches in this string for the index of the specified character.
| |||||||||||
Searches in this string for the index of the specified string.
| |||||||||||
Searches in this string for the first index of the specified string.
| |||||||||||
Returns an interned string equal to this string.
| |||||||||||
Returns true if the length of this string is 0.
| |||||||||||
Searches in this string for the last index of the specified string.
| |||||||||||
Returns the last index of the code point
c , or -1. | |||||||||||
Returns the last index of the code point
c , or -1. | |||||||||||
Searches in this string for the index of the specified string.
| |||||||||||
Returns the number of characters in this string.
| |||||||||||
Tests whether this string matches the given
regularExpression . | |||||||||||
Returns the index within this object that is offset from
index by
codePointOffset code points. | |||||||||||
Compares the specified string to this string and compares the specified
range of characters to determine if they are the same.
| |||||||||||
Compares the specified string to this string and compares the specified
range of characters to determine if they are the same.
| |||||||||||
Copies this string replacing occurrences of the specified target sequence
with another sequence.
| |||||||||||
Copies this string replacing occurrences of the specified character with
another character.
| |||||||||||
Replaces all matches for
regularExpression within this string with the given
replacement . | |||||||||||
Replaces the first match for
regularExpression within this string with the given
replacement . | |||||||||||
Splits this string using the supplied
regularExpression . | |||||||||||
Splits this string using the supplied
regularExpression . | |||||||||||
Compares the specified string to this string to determine if the
specified string is a prefix.
| |||||||||||
Compares the specified string to this string, starting at the specified
offset, to determine if the specified string is a prefix.
| |||||||||||
Has the same result as the substring function, but is present so that
string may implement the CharSequence interface.
| |||||||||||
Returns a string containing a suffix of this string.
| |||||||||||
Returns a string containing a subsequence of characters from this string.
| |||||||||||
Returns a new
char array containing a copy of the characters in this string. | |||||||||||
Converts this string to lower case, using the rules of
locale . | |||||||||||
Converts this string to lower case, using the rules of the user's default locale.
| |||||||||||
Returns this string.
| |||||||||||
Converts this this string to upper case, using the rules of
locale . | |||||||||||
Converts this this string to upper case, using the rules of the user's default locale.
| |||||||||||
Copies this string removing white space characters from the beginning and
end of the string.
| |||||||||||
Converts the specified long to its string representation.
| |||||||||||
Converts the specified object to its string representation.
| |||||||||||
Creates a new string containing the characters in the specified character
array.
| |||||||||||
Converts the specified double to its string representation.
| |||||||||||
Converts the specified integer to its string representation.
| |||||||||||
Converts the specified float to its string representation.
| |||||||||||
Creates a new string containing the specified characters in the character
array.
| |||||||||||
Converts the specified boolean to its string representation.
| |||||||||||
Converts the specified character to its string representation.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
java.lang.CharSequence
| |||||||||||
From interface
java.lang.Comparable
|
A comparator ignoring the case of the characters.
Converts the byte array to a string using the system's
default charset
.
This constructor was deprecated
in API level 1.
Use String(byte[])
or String(byte[], String)
instead.
Converts the byte array to a string, setting the high byte of every character to the specified value.
data | the byte array to convert to a string. |
---|---|
high | the high byte to use. |
NullPointerException | if data == null . |
---|
Converts a subsequence of the byte array to a string using the system's
default charset
.
NullPointerException | if data == null . |
---|---|
IndexOutOfBoundsException | if byteCount < 0 || offset < 0 || offset + byteCount > data.length .
|
This constructor was deprecated
in API level 1.
Use String(byte[], int, int)
instead.
Converts the byte array to a string, setting the high byte of every
character to high
.
NullPointerException | if data == null . |
---|---|
IndexOutOfBoundsException | if byteCount < 0 || offset < 0 || offset + byteCount > data.length |
Converts the byte array to a string using the named charset.
The behavior when the bytes cannot be decoded by the named charset
is unspecified. Use CharsetDecoder
for more control.
NullPointerException | if data == null . |
---|---|
IndexOutOfBoundsException | if byteCount < 0 || offset < 0 || offset + byteCount > data.length . |
UnsupportedEncodingException | if the named charset is not supported. |
Converts the byte array to a string using the named charset.
The behavior when the bytes cannot be decoded by the named charset
is unspecified. Use CharsetDecoder
for more control.
NullPointerException | if data == null . |
---|---|
UnsupportedEncodingException | if charsetName is not supported.
|
Converts the byte array to a string using the given charset.
The behavior when the bytes cannot be decoded by the given charset
is to replace malformed input and unmappable characters with the charset's default
replacement string. Use CharsetDecoder
for more control.
IndexOutOfBoundsException | if byteCount < 0 || offset < 0 || offset + byteCount > data.length |
---|---|
NullPointerException | if data == null |
Converts the byte array to a String using the given charset.
NullPointerException | if data == null |
---|
Initializes this string to contain the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.
NullPointerException | if data == null
|
---|
Initializes this string to contain the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.
NullPointerException | if data == null . |
---|---|
IndexOutOfBoundsException | if charCount < 0 || offset < 0 || offset + charCount > data.length
|
Constructs a new string with the same sequence of characters as toCopy
. The returned string's backing array
is no larger than necessary.
Creates a String
from the contents of the specified
StringBuffer
.
Creates a String
from the sub-array of Unicode code points.
NullPointerException | if codePoints == null . |
---|---|
IllegalArgumentException | if any of the elements of codePoints are not valid
Unicode code points. |
IndexOutOfBoundsException | if offset or count are not within the bounds
of codePoints . |
Creates a String
from the contents of the specified StringBuilder
.
NullPointerException | if stringBuilder == null . |
---|
Returns the character at index
.
IndexOutOfBoundsException | if index < 0 or index >= length() .
|
---|
Returns the Unicode code point at the given index
.
IndexOutOfBoundsException | if index < 0 || index >= length() |
---|
Returns the Unicode code point that precedes the given index
.
IndexOutOfBoundsException | if index < 1 || index > length() |
---|
Calculates the number of Unicode code points between start
and end
.
start | the inclusive beginning index of the subsequence. |
---|---|
end | the exclusive end index of the subsequence. |
IndexOutOfBoundsException | if start < 0 || end > length() || start > end |
---|
Compares the specified string to this string using the Unicode values of the characters. Returns 0 if the strings contain the same characters in the same order. Returns a negative integer if the first non-equal character in this string has a Unicode value which is less than the Unicode value of the character at the same position in the specified string, or if this string is a prefix of the specified string. Returns a positive integer if the first non-equal character in this string has a Unicode value which is greater than the Unicode value of the character at the same position in the specified string, or if the specified string is a prefix of this string.
string | the string to compare. |
---|
NullPointerException | if string is null .
|
---|
Compares the specified string to this string using the Unicode values of the characters, ignoring case differences. Returns 0 if the strings contain the same characters in the same order. Returns a negative integer if the first non-equal character in this string has a Unicode value which is less than the Unicode value of the character at the same position in the specified string, or if this string is a prefix of the specified string. Returns a positive integer if the first non-equal character in this string has a Unicode value which is greater than the Unicode value of the character at the same position in the specified string, or if the specified string is a prefix of this string.
string | the string to compare. |
---|
NullPointerException | if string is null .
|
---|
Concatenates this string and the specified string.
string | the string to concatenate |
---|
Determines if this String
contains the sequence of characters in
the CharSequence
passed.
cs | the character sequence to search for. |
---|
true
if the sequence of characters are contained in this
string, otherwise false
.Compares a CharSequence
to this String
to determine if
their contents are equal.
cs | the character sequence to compare to. |
---|
true
if equal, otherwise false
Returns whether the characters in the StringBuffer strbuf
are the
same as those in this string.
strbuf | the StringBuffer to compare this string to. |
---|
true
if the characters in strbuf
are identical to
those in this string. If they are not, false
will be
returned.NullPointerException | if strbuf is null . |
---|
Creates a new string containing the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.
data | the array of characters. |
---|---|
start | the starting offset in the character array. |
length | the number of characters to use. |
NullPointerException | if data is null . |
---|---|
IndexOutOfBoundsException | if length < 0, start < 0 or start + length >
data.length .
|
Creates a new string containing the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.
data | the array of characters. |
---|
NullPointerException | if data is null .
|
---|
Compares the specified string to this string to determine if the specified string is a suffix.
suffix | the suffix to look for. |
---|
true
if the specified string is a suffix of this string,
false
otherwise.NullPointerException | if suffix is null .
|
---|
Compares the specified object to this string and returns true if they are equal. The object must be an instance of string with the same characters in the same order.
other | the object to compare. |
---|
true
if the specified object is equal to this string,
false
otherwise.Compares the specified string to this string ignoring the case of the characters and returns true if they are equal.
string | the string to compare. |
---|
true
if the specified string is equal to this string,
false
otherwise.
Returns a formatted string, using the supplied format and arguments, localized to the given locale.
locale | the locale to apply; null value means no localization. |
---|---|
format | the format string (see format(String, Object...) ) |
args | the list of arguments passed to the formatter. If there are
more arguments than required by format ,
additional arguments are ignored. |
NullPointerException | if format == null |
---|---|
IllegalFormatException | if the format is invalid. |
Returns a localized formatted string, using the supplied format and arguments, using the user's default locale.
If you're formatting a string other than for human
consumption, you should use the format(Locale, String, Object...)
overload and supply Locale.US
. See
"Be wary of the default locale".
format | the format string (see format(String, Object...) ) |
---|---|
args | the list of arguments passed to the formatter. If there are
more arguments than required by format ,
additional arguments are ignored. |
NullPointerException | if format == null |
---|---|
IllegalFormatException | if the format is invalid. |
This method was deprecated
in API level 1.
Use getBytes()
or getBytes(String)
instead.
Mangles this string into a byte array by stripping the high order bits from
each character. Use getBytes()
or getBytes(String)
instead.
start | the starting offset of characters to copy. |
---|---|
end | the ending offset of characters to copy. |
data | the destination byte array. |
index | the starting offset in the destination byte array. |
NullPointerException | if data is null . |
---|---|
IndexOutOfBoundsException | if start < 0 , end > length() , index <
0 or end - start > data.length - index . |
Returns a new byte array containing the characters of this string encoded using the named charset.
The behavior when this string cannot be represented in the named charset
is unspecified. Use CharsetEncoder
for more control.
UnsupportedEncodingException | if the charset is not supported |
---|
Returns a new byte array containing the characters of this string encoded using the given charset.
The behavior when this string cannot be represented in the given charset
is to replace malformed input and unmappable characters with the charset's default
replacement byte array. Use CharsetEncoder
for more control.
Returns a new byte array containing the characters of this string encoded using the
system's default charset
.
The behavior when this string cannot be represented in the system's default charset is unspecified. In practice, when the default charset is UTF-8 (as it is on Android), all strings can be encoded.
Copies the specified characters in this string to the character array starting at the specified offset in the character array.
start | the starting offset of characters to copy. |
---|---|
end | the ending offset of characters to copy. |
buffer | the destination character array. |
index | the starting offset in the character array. |
NullPointerException | if buffer is null . |
---|---|
IndexOutOfBoundsException | if start < 0 , end > length() , start >
end , index < 0 , end - start > buffer.length -
index
|
Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
method.
Searches in this string for the first index of the specified character. The search for the character starts at the beginning and moves towards the end of this string.
c | the character to find. |
---|
Searches in this string for the index of the specified character. The search for the character starts at the specified offset and moves towards the end of this string.
c | the character to find. |
---|---|
start | the starting offset. |
Searches in this string for the index of the specified string. The search for the string starts at the specified offset and moves towards the end of this string.
subString | the string to find. |
---|---|
start | the starting offset. |
NullPointerException | if subString is null .
|
---|
Searches in this string for the first index of the specified string. The search for the string starts at the beginning and moves towards the end of this string.
string | the string to find. |
---|
NullPointerException | if string is null .
|
---|
Returns an interned string equal to this string. The VM maintains an internal set of
unique strings. All string literals found in loaded classes'
constant pools are automatically interned. Manually-interned strings are only weakly
referenced, so calling intern
won't lead to unwanted retention.
Interning is typically used because it guarantees that for interned strings
a
and b
, a.equals(b)
can be simplified to
a == b
. (This is not true of non-interned strings.)
Many applications find it simpler and more convenient to use an explicit
HashMap
to implement their own pools.
Searches in this string for the last index of the specified string. The search for the string starts at the end and moves towards the beginning of this string.
string | the string to find. |
---|
NullPointerException | if string is null .
|
---|
Returns the last index of the code point c
, or -1.
The search for the character starts at offset start
and moves towards
the beginning of this string.
Returns the last index of the code point c
, or -1.
The search for the character starts at the end and moves towards the
beginning of this string.
Searches in this string for the index of the specified string. The search for the string starts at the specified offset and moves towards the beginning of this string.
subString | the string to find. |
---|---|
start | the starting offset. |
NullPointerException | if subString is null .
|
---|
Returns the number of characters in this string.
Tests whether this string matches the given regularExpression
. This method returns
true only if the regular expression matches the entire input string. A common mistake is
to assume that this method behaves like contains(CharSequence)
; if you want to match anywhere
within the input string, you need to add .*
to the beginning and end of your
regular expression. See matches(String, CharSequence)
.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
if the syntax of the supplied regular expression is not valid. | |
NullPointerException | if regularExpression == null |
Returns the index within this object that is offset from index
by
codePointOffset
code points.
index | the index within this object to calculate the offset from. |
---|---|
codePointOffset | the number of code points to count. |
IndexOutOfBoundsException | if index is negative or greater than length()
or if there aren't enough code points before or after index to match codePointOffset . |
---|
Compares the specified string to this string and compares the specified range of characters to determine if they are the same. When ignoreCase is true, the case of the characters is ignored during the comparison.
ignoreCase | specifies if case should be ignored. |
---|---|
thisStart | the starting offset in this string. |
string | the string to compare. |
start | the starting offset in the specified string. |
length | the number of characters to compare. |
true
if the ranges of characters are equal, false
otherwise.NullPointerException | if string is null .
|
---|
Compares the specified string to this string and compares the specified range of characters to determine if they are the same.
thisStart | the starting offset in this string. |
---|---|
string | the string to compare. |
start | the starting offset in the specified string. |
length | the number of characters to compare. |
true
if the ranges of characters are equal, false
otherwiseNullPointerException | if string is null .
|
---|
Copies this string replacing occurrences of the specified target sequence with another sequence. The string is processed from the beginning to the end.
target | the sequence to replace. |
---|---|
replacement | the replacement sequence. |
NullPointerException | if target or replacement is null .
|
---|
Copies this string replacing occurrences of the specified character with another character.
oldChar | the character to replace. |
---|---|
newChar | the replacement character. |
Replaces all matches for regularExpression
within this string with the given
replacement
.
See Pattern
for regular expression syntax.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
if the syntax of the supplied regular expression is not valid. | |
NullPointerException | if regularExpression == null |
Replaces the first match for regularExpression
within this string with the given
replacement
.
See Pattern
for regular expression syntax.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
if the syntax of the supplied regular expression is not valid. | |
NullPointerException | if regularExpression == null |
Splits this string using the supplied regularExpression
.
Equivalent to split(regularExpression, 0)
.
See split(CharSequence, int)
for an explanation of limit
.
See Pattern
for regular expression syntax.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
NullPointerException | if regularExpression == null |
---|---|
if the syntax of the supplied regular expression is not valid. |
Splits this string using the supplied regularExpression
.
See split(CharSequence, int)
for an explanation of limit
.
See Pattern
for regular expression syntax.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
NullPointerException | if regularExpression == null |
---|---|
if the syntax of the supplied regular expression is not valid. |
Compares the specified string to this string to determine if the specified string is a prefix.
prefix | the string to look for. |
---|
true
if the specified string is a prefix of this string,
false
otherwiseNullPointerException | if prefix is null .
|
---|
Compares the specified string to this string, starting at the specified offset, to determine if the specified string is a prefix.
prefix | the string to look for. |
---|---|
start | the starting offset. |
true
if the specified string occurs in this string at the
specified offset, false
otherwise.NullPointerException | if prefix is null .
|
---|
Has the same result as the substring function, but is present so that string may implement the CharSequence interface.
start | the offset the first character. |
---|---|
end | the offset of one past the last character to include. |
IndexOutOfBoundsException | if start < 0 , end < 0 , start > end or
end > length() . |
---|
Returns a string containing a suffix of this string. The returned string shares this string's backing array.
start | the offset of the first character. |
---|
IndexOutOfBoundsException | if start < 0 or start > length() .
|
---|
Returns a string containing a subsequence of characters from this string. The returned string shares this string's backing array.
start | the offset of the first character. |
---|---|
end | the offset one past the last character. |
IndexOutOfBoundsException | if start < 0 , start > end or end >
length() .
|
---|
Returns a new char
array containing a copy of the characters in this string.
This is expensive and rarely useful. If you just want to iterate over the characters in
the string, use charAt(int)
instead.
Converts this string to lower case, using the rules of locale
.
Most case mappings are unaffected by the language of a Locale
. Exceptions include
dotted and dotless I in Azeri and Turkish locales, and dotted and dotless I and J in
Lithuanian locales. On the other hand, it isn't necessary to provide a Greek locale to get
correct case mapping of Greek characters: any locale will do.
See http://www.unicode.org/Public/UNIDATA/SpecialCasing.txt for full details of context- and language-specific special cases.
this
if it's already all lower case.
Converts this string to lower case, using the rules of the user's default locale. See "Be wary of the default locale".
this
if it's already all lower case.
Returns this string.
Converts this this string to upper case, using the rules of locale
.
Most case mappings are unaffected by the language of a Locale
. Exceptions include
dotted and dotless I in Azeri and Turkish locales, and dotted and dotless I and J in
Lithuanian locales. On the other hand, it isn't necessary to provide a Greek locale to get
correct case mapping of Greek characters: any locale will do.
See http://www.unicode.org/Public/UNIDATA/SpecialCasing.txt for full details of context- and language-specific special cases.
this
if it's already all upper case.
Converts this this string to upper case, using the rules of the user's default locale. See "Be wary of the default locale".
this
if it's already all upper case.
Copies this string removing white space characters from the beginning and end of the string.
<= \\u0020
removed from
the beginning and the end.
Converts the specified long to its string representation.
value | the long. |
---|
Converts the specified object to its string representation. If the object
is null return the string "null"
, otherwise use toString()
to get the string representation.
value | the object. |
---|
"null"
.
Creates a new string containing the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.
data | the array of characters. |
---|
NullPointerException | if data is null .
|
---|
Converts the specified double to its string representation.
value | the double. |
---|
Converts the specified integer to its string representation.
value | the integer. |
---|
Converts the specified float to its string representation.
value | the float. |
---|
Creates a new string containing the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.
data | the array of characters. |
---|---|
start | the starting offset in the character array. |
length | the number of characters to use. |
IndexOutOfBoundsException | if length < 0 , start < 0 or start +
length > data.length |
---|---|
NullPointerException | if data is null .
|
Converts the specified boolean to its string representation. When the
boolean is true
return "true"
, otherwise return "false"
.
value | the boolean. |
---|
Converts the specified character to its string representation.
value | the character. |
---|