public final class String extends Object implements Serializable, Comparable<String>, CharSequence
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
).
['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.
StringBuffer
,
StringBuilder
,
Charset
,
Serialized FormModifier and Type | Field and Description |
---|---|
static Comparator<String> |
CASE_INSENSITIVE_ORDER
A comparator ignoring the case of the characters.
|
Constructor and Description |
---|
String()
Creates an empty string.
|
String(byte[] data)
Converts the byte array to a string using the system's
default charset . |
String(byte[] data,
Charset charset)
Converts the byte array to a String using the given charset.
|
String(byte[] data,
int high)
Deprecated.
Use
String(byte[]) or String(byte[], String) instead. |
String(byte[] data,
int offset,
int byteCount)
Converts a subsequence of the byte array to a string using the system's
default charset . |
String(byte[] data,
int offset,
int byteCount,
Charset charset)
Converts the byte array to a string using the given charset.
|
String(byte[] data,
int high,
int offset,
int byteCount)
Deprecated.
Use
String(byte[], int, int) instead. |
String(byte[] data,
int offset,
int byteCount,
String charsetName)
Converts the byte array to a string using the named charset.
|
String(byte[] data,
String charsetName)
Converts the byte array to a string using the named charset.
|
String(char[] data)
Initializes this string to contain the characters in the specified
character array.
|
String(char[] data,
int offset,
int charCount)
Initializes this string to contain the specified characters in the
character array.
|
String(int[] codePoints,
int offset,
int count)
Creates a
String from the sub-array of Unicode code points. |
String(String toCopy)
Constructs a new string with the same sequence of characters as
toCopy . |
String(StringBuffer stringBuffer)
Creates a
String from the contents of the specified
StringBuffer . |
String(StringBuilder stringBuilder)
Creates a
String from the contents of the specified StringBuilder . |
Modifier and Type | Method and Description |
---|---|
char |
charAt(int index)
Returns the character at the specified offset in this string.
|
int |
codePointAt(int index)
Returns the Unicode code point at the given
index . |
int |
codePointBefore(int index)
Returns the Unicode code point that precedes the given
index . |
int |
codePointCount(int start,
int end)
Calculates the number of Unicode code points between
start
and end . |
int |
compareTo(String string)
Compares the specified string to this string using the Unicode values of
the characters.
|
int |
compareToIgnoreCase(String string)
Compares the specified string to this string using the Unicode values of
the characters, ignoring case differences.
|
String |
concat(String string)
Concatenates this string and the specified string.
|
boolean |
contains(CharSequence cs)
Determines if this
String contains the sequence of characters in
the CharSequence passed. |
boolean |
contentEquals(CharSequence cs)
Compares a
CharSequence to this String to determine if
their contents are equal. |
boolean |
contentEquals(StringBuffer strbuf)
Returns whether the characters in the StringBuffer
strbuf are the
same as those in this string. |
static String |
copyValueOf(char[] data)
Creates a new string containing the characters in the specified character
array.
|
static String |
copyValueOf(char[] data,
int start,
int length)
Creates a new string containing the specified characters in the character
array.
|
boolean |
endsWith(String suffix)
Compares the specified string to this string to determine if the
specified string is a suffix.
|
boolean |
equals(Object object)
Compares the specified object to this string and returns true if they are
equal.
|
boolean |
equalsIgnoreCase(String string)
Compares the specified string to this string ignoring the case of the
characters and returns true if they are equal.
|
static String |
format(Locale locale,
String format,
Object... args)
Returns a formatted string, using the supplied format and arguments,
localized to the given locale.
|
static String |
format(String format,
Object... args)
Returns a localized formatted string, using the supplied format and arguments,
using the user's default locale.
|
byte[] |
getBytes()
Returns a new byte array containing the characters of this string encoded using the
system's
default charset . |
byte[] |
getBytes(Charset charset)
Returns a new byte array containing the characters of this string encoded using the
given charset.
|
void |
getBytes(int start,
int end,
byte[] data,
int index)
Deprecated.
Use
getBytes() or getBytes(String) |
byte[] |
getBytes(String charsetName)
Returns a new byte array containing the characters of this string encoded using the
named charset.
|
void |
getChars(int start,
int end,
char[] buffer,
int index)
Copies the specified characters in this string to the character array
starting at the specified offset in the character array.
|
int |
hashCode()
Returns an integer hash code for this object.
|
int |
indexOf(int c)
Searches in this string for the first index of the specified character.
|
int |
indexOf(int c,
int start)
Searches in this string for the index of the specified character.
|
int |
indexOf(String string)
Searches in this string for the first index of the specified string.
|
int |
indexOf(String subString,
int start)
Searches in this string for the index of the specified string.
|
String |
intern()
Returns an interned string equal to this string.
|
boolean |
isEmpty()
Returns true if the length of this string is 0.
|
int |
lastIndexOf(int c)
Returns the last index of the code point
c , or -1. |
int |
lastIndexOf(int c,
int start)
Returns the last index of the code point
c , or -1. |
int |
lastIndexOf(String string)
Searches in this string for the last index of the specified string.
|
int |
lastIndexOf(String subString,
int start)
Searches in this string for the index of the specified string.
|
int |
length()
Returns the size of this string.
|
boolean |
matches(String regularExpression)
Tests whether this string matches the given
regularExpression . |
int |
offsetByCodePoints(int index,
int codePointOffset)
Returns the index within this object that is offset from
index by
codePointOffset code points. |
boolean |
regionMatches(boolean ignoreCase,
int thisStart,
String string,
int start,
int length)
Compares the specified string to this string and compares the specified
range of characters to determine if they are the same.
|
boolean |
regionMatches(int thisStart,
String string,
int start,
int length)
Compares the specified string to this string and compares the specified
range of characters to determine if they are the same.
|
String |
replace(char oldChar,
char newChar)
Copies this string replacing occurrences of the specified character with
another character.
|
String |
replace(CharSequence target,
CharSequence replacement)
Copies this string replacing occurrences of the specified target sequence
with another sequence.
|
String |
replaceAll(String regularExpression,
String replacement)
Replaces all matches for
regularExpression within this string with the given
replacement . |
String |
replaceFirst(String regularExpression,
String replacement)
Replaces the first match for
regularExpression within this string with the given
replacement . |
String[] |
split(String regularExpression)
Splits this string using the supplied
regularExpression . |
String[] |
split(String regularExpression,
int limit)
Splits this string using the supplied
regularExpression . |
boolean |
startsWith(String prefix)
Compares the specified string to this string to determine if the
specified string is a prefix.
|
boolean |
startsWith(String prefix,
int start)
Compares the specified string to this string, starting at the specified
offset, to determine if the specified string is a prefix.
|
CharSequence |
subSequence(int start,
int end)
Has the same result as the substring function, but is present so that
string may implement the CharSequence interface.
|
String |
substring(int start)
Returns a string containing a suffix of this string.
|
String |
substring(int start,
int end)
Returns a string containing a subsequence of characters from this string.
|
char[] |
toCharArray()
Copies the characters in this string to a character array.
|
String |
toLowerCase()
Converts this string to lower case, using the rules of the user's default locale.
|
String |
toLowerCase(Locale locale)
Converts this string to lower case, using the rules of
locale . |
String |
toString()
Returns this string.
|
String |
toUpperCase()
Converts this this string to upper case, using the rules of the user's default locale.
|
String |
toUpperCase(Locale locale)
Converts this this string to upper case, using the rules of
locale . |
String |
trim()
Copies this string removing white space characters from the beginning and
end of the string.
|
static String |
valueOf(boolean value)
Converts the specified boolean to its string representation.
|
static String |
valueOf(char value)
Converts the specified character to its string representation.
|
static String |
valueOf(char[] data)
Creates a new string containing the characters in the specified character
array.
|
static String |
valueOf(char[] data,
int start,
int length)
Creates a new string containing the specified characters in the character
array.
|
static String |
valueOf(double value)
Converts the specified double to its string representation.
|
static String |
valueOf(float value)
Converts the specified float to its string representation.
|
static String |
valueOf(int value)
Converts the specified integer to its string representation.
|
static String |
valueOf(long value)
Converts the specified long to its string representation.
|
static String |
valueOf(Object value)
Converts the specified object to its string representation.
|
public static final Comparator<String> CASE_INSENSITIVE_ORDER
public String()
public String(byte[] data)
default charset
.@Deprecated public String(byte[] data, int high)
data
- the byte array to convert to a string.high
- the high byte to use.NullPointerException
- if data == null
.public String(byte[] data, int offset, int byteCount)
default charset
.NullPointerException
- if data == null
.IndexOutOfBoundsException
- if byteCount < 0 || offset < 0 || offset + byteCount > data.length
.@Deprecated public String(byte[] data, int high, int offset, int byteCount)
String(byte[], int, int)
instead.high
.NullPointerException
- if data == null
.IndexOutOfBoundsException
- if byteCount < 0 || offset < 0 || offset + byteCount > data.length
public String(byte[] data, int offset, int byteCount, String charsetName) throws UnsupportedEncodingException
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.public String(byte[] data, String charsetName) throws UnsupportedEncodingException
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.public String(byte[] data, int offset, int byteCount, Charset 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
public String(byte[] data, Charset charset)
NullPointerException
- if data == null
public String(char[] data)
NullPointerException
- if data == null
public String(char[] data, int offset, int charCount)
NullPointerException
- if data == null
.IndexOutOfBoundsException
- if charCount < 0 || offset < 0 || offset + charCount > data.length
public String(String toCopy)
toCopy
. The returned string's backing array
is no larger than necessary.public String(StringBuffer stringBuffer)
String
from the contents of the specified
StringBuffer
.public String(int[] codePoints, int offset, int count)
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
.public String(StringBuilder stringBuilder)
String
from the contents of the specified StringBuilder
.NullPointerException
- if stringBuilder == null
.public char charAt(int index)
charAt
in interface CharSequence
index
- the zero-based index in this string.IndexOutOfBoundsException
- if index < 0
or index >= length()
.public int compareTo(String string)
compareTo
in interface Comparable<String>
string
- the string to compare.NullPointerException
- if string
is null
.public int compareToIgnoreCase(String string)
string
- the string to compare.NullPointerException
- if string
is null
.public String concat(String string)
string
- the string to concatenatepublic static String copyValueOf(char[] data)
data
- the array of characters.NullPointerException
- if data
is null
.public static String copyValueOf(char[] data, int start, int length)
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
.public boolean endsWith(String 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
.public boolean equals(Object object)
public boolean equalsIgnoreCase(String string)
string
- the string to compare.true
if the specified string is equal to this string,
false
otherwise.@Deprecated public void getBytes(int start, int end, byte[] data, int index)
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
.public byte[] getBytes()
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.
public byte[] getBytes(String charsetName) throws UnsupportedEncodingException
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 supportedpublic byte[] getBytes(Charset 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.
public void getChars(int start, int end, char[] buffer, int index)
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
public int hashCode()
Object
Object.equals(java.lang.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.
hashCode
in class Object
Object.equals(java.lang.Object)
public int indexOf(int c)
c
- the character to find.public int indexOf(int c, int start)
c
- the character to find.start
- the starting offset.public int indexOf(String string)
string
- the string to find.NullPointerException
- if string
is null
.public int indexOf(String subString, int start)
subString
- the string to find.start
- the starting offset.NullPointerException
- if subString
is null
.public String intern()
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.
public boolean isEmpty()
public int lastIndexOf(int c)
c
, or -1.
The search for the character starts at the end and moves towards the
beginning of this string.public int lastIndexOf(int c, int start)
c
, or -1.
The search for the character starts at offset start
and moves towards
the beginning of this string.public int lastIndexOf(String string)
string
- the string to find.NullPointerException
- if string
is null
.public int lastIndexOf(String subString, int start)
subString
- the string to find.start
- the starting offset.NullPointerException
- if subString
is null
.public int length()
length
in interface CharSequence
public boolean regionMatches(int thisStart, String string, int start, int length)
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
.public boolean regionMatches(boolean ignoreCase, int thisStart, String string, int start, int length)
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
.public String replace(char oldChar, char newChar)
oldChar
- the character to replace.newChar
- the replacement character.public String replace(CharSequence target, CharSequence replacement)
target
- the sequence to replace.replacement
- the replacement sequence.NullPointerException
- if target
or replacement
is null
.public boolean startsWith(String prefix)
prefix
- the string to look for.true
if the specified string is a prefix of this string,
false
otherwiseNullPointerException
- if prefix
is null
.public boolean startsWith(String prefix, int start)
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
.public String substring(int start)
start
- the offset of the first character.IndexOutOfBoundsException
- if start < 0
or start > length()
.public String substring(int start, int end)
start
- the offset of the first character.end
- the offset one past the last character.IndexOutOfBoundsException
- if start < 0
, start > end
or end >
length()
.public char[] toCharArray()
public String toLowerCase()
this
if it's already all lower case.public String toLowerCase(Locale locale)
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.public String toString()
toString
in interface CharSequence
toString
in class Object
public String toUpperCase()
this
if it's already all upper case.public String toUpperCase(Locale locale)
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.public String trim()
<= \\u0020
removed from
the beginning and the end.public static String valueOf(char[] data)
data
- the array of characters.NullPointerException
- if data
is null
.public static String valueOf(char[] data, int start, int length)
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
.public static String valueOf(char value)
value
- the character.public static String valueOf(double value)
value
- the double.public static String valueOf(float value)
value
- the float.public static String valueOf(int value)
value
- the integer.public static String valueOf(long value)
value
- the long.public static String valueOf(Object value)
"null"
, otherwise use toString()
to get the string representation.value
- the object."null"
.public static String valueOf(boolean value)
true
return "true"
, otherwise return "false"
.value
- the boolean.public boolean contentEquals(StringBuffer strbuf)
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
.public boolean contentEquals(CharSequence cs)
CharSequence
to this String
to determine if
their contents are equal.cs
- the character sequence to compare to.true
if equal, otherwise false
public boolean matches(String regularExpression)
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(java.lang.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 Pattern.matches(java.lang.String, java.lang.CharSequence)
.
If the same regular expression is to be used for multiple operations, it may be more
efficient to reuse a compiled Pattern
.
PatternSyntaxException
- if the syntax of the supplied regular expression is not
valid.NullPointerException
- if regularExpression == null
public String replaceAll(String regularExpression, String replacement)
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
.
PatternSyntaxException
- if the syntax of the supplied regular expression is not
valid.NullPointerException
- if regularExpression == null
Pattern
public String replaceFirst(String regularExpression, String replacement)
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
.
PatternSyntaxException
- if the syntax of the supplied regular expression is not
valid.NullPointerException
- if regularExpression == null
Pattern
public String[] split(String regularExpression)
regularExpression
.
Equivalent to split(regularExpression, 0)
.
See Pattern.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
PatternSyntaxException
- if the syntax of the supplied regular expression is not
valid.Pattern
public String[] split(String regularExpression, int limit)
regularExpression
.
See Pattern.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
PatternSyntaxException
- if the syntax of the supplied regular expression is not
valid.public CharSequence subSequence(int start, int end)
subSequence
in interface CharSequence
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()
.CharSequence.subSequence(int, int)
public int codePointAt(int index)
index
.IndexOutOfBoundsException
- if index < 0 || index >= length()
Character.codePointAt(char[], int, int)
public int codePointBefore(int index)
index
.IndexOutOfBoundsException
- if index < 1 || index > length()
Character.codePointBefore(char[], int, int)
public int codePointCount(int start, int end)
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
Character.codePointCount(CharSequence, int, int)
public boolean contains(CharSequence cs)
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
.public int offsetByCodePoints(int index, int codePointOffset)
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
.public static String format(String format, Object... args)
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 Formatter.format(java.lang.String, java.lang.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.public static String format(Locale locale, String format, Object... args)
locale
- the locale to apply; null
value means no localization.format
- the format string (see Formatter.format(java.lang.String, java.lang.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.