![]() |
稳重的钥匙扣 · 互动交流 - 广东省退役军人事务厅网站· 1 年前 · |
![]() |
帅气的消防车 · 极道天使漫画免费 - 极道天使漫画 - ...· 1 年前 · |
![]() |
刚分手的肉夹馍 · 《刺客信条:奥德赛》古希腊摄影大赛即将开启 ...· 1 年前 · |
![]() |
干练的充电器 · 汪精卫刺杀摄政王始末:同盟会美女运炸弹(图) ...· 1 年前 · |
![]() |
沉稳的电梯 · 秘鲁寒流造成241人死亡· 2 年前 · |
public final class String extends Object implements Serializable, Comparable<String>, CharSequence
String
class represents character strings. All
string literals in Java programs, such as
"abc"
, are
implemented as instances of this class.
Strings are constant; their values cannot be changed after they
are created. String buffers support mutable strings.
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);
The class
String
includes methods for examining
individual characters of the sequence, for comparing strings, for
searching strings, for extracting substrings, and for creating a
copy of a string with all characters translated to uppercase or to
lowercase. Case mapping is based on the Unicode Standard version
specified by the
Character
class.
The Java language provides special support for the string
concatenation operator ( + ), and for conversion of
other objects to strings. For additional information on string
concatenation and conversion, see
The Java™ Language Specification
.
Unless otherwise noted, passing a
null
argument to a constructor
or method in this class will cause a
NullPointerException
to be
thrown.
A
String
represents a string in the UTF-16 format
in which
supplementary characters
are represented by
surrogate
pairs
(see the section
Unicode
Character Representations
in the
Character
class for
more information).
Index values refer to
char
code units, so a supplementary
character uses two positions in a
String
.
The
String
class provides methods for dealing with
Unicode code points (i.e., characters), in addition to those for
dealing with Unicode code units (i.e.,
char
values).
Unless otherwise noted, methods for comparing Strings do not take locale
into account. The
Collator
class provides methods for
finer-grain, locale-sensitive String comparison.
javac
compiler
may implement the operator with
StringBuffer
,
StringBuilder
,
or
java.lang.invoke.StringConcatFactory
depending on the JDK version. The
implementation of string conversion is typically through the method
toString
,
defined by
Object
and inherited by all classes in Java.
Object.toString()
,
StringBuffer
,
StringBuilder
,
Charset
,
Serialized Form
String
that contains characters from a subarray
of the
Unicode code point
array
argument.
String
(
String
original)
String
object so that it represents
the same sequence of characters as the argument; in other words, the
newly created string is a copy of the argument string.
String
(
StringBuffer
buffer)
String
(
StringBuilder
builder)
charAt
(int index)
char
value at the
specified index.
IntStream
chars
()
int
zero-extending the
char
values
from this sequence.
codePointAt
(int index)
codePointBefore
(int index)
codePointCount
(int beginIndex,
int endIndex)
String
.
IntStream
codePoints
()
compareTo
(
String
anotherString)
compareToIgnoreCase
(
String
str)
String
concat
(
String
str)
boolean
contains
(
CharSequence
s)
boolean
contentEquals
(
CharSequence
cs)
CharSequence
.
boolean
contentEquals
(
StringBuffer
sb)
StringBuffer
.
static
String
copyValueOf
(char[] data)
valueOf(char[])
.
static
String
copyValueOf
(char[] data,
int offset,
int count)
valueOf(char[], int, int)
.
boolean
endsWith
(
String
suffix)
boolean
equals
(
Object
anObject)
boolean
equalsIgnoreCase
(
String
anotherString)
String
to another
String
, ignoring case
considerations.
static
String
format
(
String
format,
Object
... args)
static
String
format
(
Locale
l,
String
format,
Object
... args)
byte[]
getBytes
()
String
into a sequence of bytes using the
platform's default charset, storing the result into a new byte array.
getBytes
(int srcBegin,
int srcEnd,
byte[] dst,
int dstBegin)
getBytes
(
String
charsetName)
String
into a sequence of bytes using the named
charset, storing the result into a new byte array.
byte[]
getBytes
(
Charset
charset)
String
into a sequence of bytes using the given
charset
, storing the result into a
new byte array.
getChars
(int srcBegin,
int srcEnd,
char[] dst,
int dstBegin)
hashCode
()
indexOf
(int ch)
indexOf
(int ch,
int fromIndex)
indexOf
(
String
str)
indexOf
(
String
str,
int fromIndex)
String
intern
()
boolean
isBlank
()
boolean
isEmpty
()
static
String
join
(
CharSequence
delimiter,
CharSequence
... elements)
CharSequence elements
joined together with a copy of
the specified
delimiter
.
static
String
join
(
CharSequence
delimiter,
Iterable
<? extends
CharSequence
> elements)
String
composed of copies of the
CharSequence elements
joined together with a copy of the
specified
delimiter
.
lastIndexOf
(int ch)
lastIndexOf
(int ch,
int fromIndex)
lastIndexOf
(
String
str)
lastIndexOf
(
String
str,
int fromIndex)
length
()
Stream
<
String
>
lines
()
boolean
matches
(
String
regex)
offsetByCodePoints
(int index,
int codePointOffset)
String
that is
offset from the given
index
by
codePointOffset
code points.
boolean
regionMatches
(boolean ignoreCase,
int toffset,
String
other,
int ooffset,
int len)
boolean
regionMatches
(int toffset,
String
other,
int ooffset,
int len)
String
repeat
(int count)
count
times.
String
replace
(char oldChar,
char newChar)
oldChar
in this string with
newChar
.
String
replace
(
CharSequence
target,
CharSequence
replacement)
String
replaceAll
(
String
regex,
String
replacement)
String
replaceFirst
(
String
regex,
String
replacement)
String
[]
split
(
String
regex)
String
[]
split
(
String
regex,
int limit)
boolean
startsWith
(
String
prefix)
boolean
startsWith
(
String
prefix,
int toffset)
String
strip
()
white space
removed.
String
stripLeading
()
white space
removed.
String
stripTrailing
()
white space
removed.
CharSequence
subSequence
(int beginIndex,
int endIndex)
String
substring
(int beginIndex)
String
substring
(int beginIndex,
int endIndex)
char[]
toCharArray
()
String
toLowerCase
()
String
to lower
case using the rules of the default locale.
String
toLowerCase
(
Locale
locale)
String
to lower
case using the rules of the given
Locale
.
String
toString
()
String
toUpperCase
()
String
to upper
case using the rules of the default locale.
String
toUpperCase
(
Locale
locale)
String
to upper
case using the rules of the given
Locale
.
String
trim
()
'U+0020'
(the space character).
static
String
valueOf
(boolean b)
boolean
argument.
static
String
valueOf
(char c)
char
argument.
static
String
valueOf
(char[] data)
char
array
argument.
static
String
valueOf
(char[] data,
int offset,
int count)
char
array argument.
static
String
valueOf
(double d)
double
argument.
static
String
valueOf
(float f)
float
argument.
static
String
valueOf
(int i)
int
argument.
static
String
valueOf
(long l)
long
argument.
static
String
valueOf
(
Object
obj)
Object
argument.
public static final Comparator<String> CASE_INSENSITIVE_ORDER
String
objects as by
compareToIgnoreCase
. This comparator is serializable.
Note that this Comparator does
not
take locale into account,
and will result in an unsatisfactory ordering for certain locales.
The
Collator
class provides locale-sensitive comparison.
Collator
public String()
String
object so that it represents
an empty character sequence. Note that use of this constructor is
unnecessary since Strings are immutable.
public String(String original)
String
object so that it represents
the same sequence of characters as the argument; in other words, the
newly created string is a copy of the argument string. Unless an
explicit copy of
original
is needed, use of this constructor is
unnecessary since Strings are immutable.
original
- A
String
public String(char[] value)
String
so that it represents the sequence of
characters currently contained in the character array argument. The
contents of the character array are copied; subsequent modification of
the character array does not affect the newly created string.
value
- The initial value of the string
String
that contains characters from a subarray
of the character array argument. The
offset
argument is the
index of the first character of the subarray and the
count
argument specifies the length of the subarray. The contents of the
subarray are copied; subsequent modification of the character array does
not affect the newly created string.
value
- Array that is the source of characters
offset
- The initial offset
count
- The length
IndexOutOfBoundsException
- If
offset
is negative,
count
is negative, or
offset
is greater than
value.length - count
String
that contains characters from a subarray
of the
Unicode code point
array
argument. The
offset
argument is the index of the first code
point of the subarray and the
count
argument specifies the
length of the subarray. The contents of the subarray are converted to
char
s; subsequent modification of the
int
array does not
affect the newly created string.
codePoints
- Array that is the source of Unicode code points
offset
- The initial offset
count
- The length
IllegalArgumentException
- If any invalid Unicode code point is found in
codePoints
IndexOutOfBoundsException
- If
offset
is negative,
count
is negative, or
offset
is greater than
codePoints.length - count
String
constructors that take a
Charset
, charset name, or that use the platform's
default charset.
String
constructed from a subarray of an array
of 8-bit integer values.
The
offset
argument is the index of the first byte of the
subarray, and the
count
argument specifies the length of the
subarray.
Each
byte
in the subarray is converted to a
char
as
specified in the
String(byte[],int)
constructor.
ascii
- The bytes to be converted to characters
hibyte
- The top 8 bits of each 16-bit Unicode code unit
offset
- The initial offset
count
- The length
IndexOutOfBoundsException
- If
offset
is negative,
count
is negative, or
offset
is greater than
ascii.length - count
String(byte[], int)
,
String(byte[], int, int, java.lang.String)
,
String(byte[], int, int, java.nio.charset.Charset)
,
String(byte[], int, int)
,
String(byte[], java.lang.String)
,
String(byte[], java.nio.charset.Charset)
,
String(byte[])
String
constructors that take a
Charset
, charset name, or that use the platform's
default charset.
String
containing characters constructed from
an array of 8-bit integer values. Each character
c
in the
resulting string is constructed from the corresponding component
b
in the byte array such that:
c
== (char)(((hibyte & 0xff) << 8)
| (
b
& 0xff))
ascii
- The bytes to be converted to characters
hibyte
- The top 8 bits of each 16-bit Unicode code unit
String(byte[], int, int, java.lang.String)
,
String(byte[], int, int, java.nio.charset.Charset)
,
String(byte[], int, int)
,
String(byte[], java.lang.String)
,
String(byte[], java.nio.charset.Charset)
,
String(byte[])
String
by decoding the specified subarray of
bytes using the specified charset. The length of the new
String
is a function of the charset, and hence may not be equal to the length
of the subarray.
The behavior of this constructor when the given bytes are not valid
in the given charset is unspecified. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
offset
- The index of the first byte to decode
length
- The number of bytes to decode
charsetName
- The name of a supported
charset
UnsupportedEncodingException
- If the named charset is not supported
IndexOutOfBoundsException
- If
offset
is negative,
length
is negative, or
offset
is greater than
bytes.length - length
String
by decoding the specified subarray of
bytes using the specified
charset
.
The length of the new
String
is a function of the charset, and
hence may not be equal to the length of the subarray.
This method always replaces malformed-input and unmappable-character
sequences with this charset's default replacement string. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
offset
- The index of the first byte to decode
length
- The number of bytes to decode
charset
- The
charset
to be used to
decode the
bytes
IndexOutOfBoundsException
- If
offset
is negative,
length
is negative, or
offset
is greater than
bytes.length - length
String
by decoding the specified array of bytes
using the specified
charset
. The
length of the new
String
is a function of the charset, and hence
may not be equal to the length of the byte array.
The behavior of this constructor when the given bytes are not valid
in the given charset is unspecified. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
charsetName
- The name of a supported
charset
UnsupportedEncodingException
- If the named charset is not supported
public String(byte[] bytes, Charset charset)
String
by decoding the specified array of
bytes using the specified
charset
.
The length of the new
String
is a function of the charset, and
hence may not be equal to the length of the byte array.
This method always replaces malformed-input and unmappable-character
sequences with this charset's default replacement string. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
charset
- The
charset
to be used to
decode the
bytes
String
by decoding the specified subarray of
bytes using the platform's default charset. The length of the new
String
is a function of the charset, and hence may not be equal
to the length of the subarray.
The behavior of this constructor when the given bytes are not valid
in the default charset is unspecified. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
offset
- The index of the first byte to decode
length
- The number of bytes to decode
IndexOutOfBoundsException
- If
offset
is negative,
length
is negative, or
offset
is greater than
bytes.length - length
public String(byte[] bytes)
String
by decoding the specified array of bytes
using the platform's default charset. The length of the new
String
is a function of the charset, and hence may not be equal to the
length of the byte array.
The behavior of this constructor when the given bytes are not valid
in the default charset is unspecified. The
CharsetDecoder
class should be used when more control
over the decoding process is required.
bytes
- The bytes to be decoded into characters
public String(StringBuffer buffer)
buffer
- A
StringBuffer
public String(StringBuilder builder)
This constructor is provided to ease migration to
StringBuilder
. Obtaining a string from a string builder via the
toString
method is likely to run faster and is generally preferred.
builder
- A
StringBuilder
public int length()
length
in interface
CharSequence
public char charAt(int index)
char
value at the
specified index. An index ranges from
0
to
length() - 1
. The first
char
value of the sequence
is at index
0
, the next at index
1
,
and so on, as for array indexing.
If the
char
value specified by the index is a
surrogate
, the surrogate
value is returned.
charAt
in interface
CharSequence
index
- the index of the
char
value.
char
value at the specified index of this string.
The first
char
value is at index
0
.
IndexOutOfBoundsException
- if the
index
argument is negative or not less than the length of this
string.
public int codePointAt(int index)
char
values
(Unicode code units) and ranges from
0
to
length()
- 1
.
If the
char
value specified at the given index
is in the high-surrogate range, the following index is less
than the length of this
String
, and the
char
value at the following index is in the
low-surrogate range, then the supplementary code point
corresponding to this surrogate pair is returned. Otherwise,
the
char
value at the given index is returned.
index
- the index to the
char
values
index
IndexOutOfBoundsException
- if the
index
argument is negative or not less than the length of this
string.
public int codePointBefore(int index)
char
values
(Unicode code units) and ranges from
1
to
length
.
If the
char
value at
(index - 1)
is in the low-surrogate range,
(index - 2)
is not
negative, and the
char
value at
(index -
2)
is in the high-surrogate range, then the
supplementary code point value of the surrogate pair is
returned. If the
char
value at
index -
1
is an unpaired low-surrogate or a high-surrogate, the
surrogate value is returned.
index
- the index following the code point that should be returned
IndexOutOfBoundsException
- if the
index
argument is less than 1 or greater than the length
of this string.
public int codePointCount(int beginIndex, int endIndex)
String
. The text range begins at the
specified
beginIndex
and extends to the
char
at index
endIndex - 1
. Thus the
length (in
char
s) of the text range is
endIndex-beginIndex
. Unpaired surrogates within
the text range count as one code point each.
beginIndex
- the index to the first
char
of
the text range.
endIndex
- the index after the last
char
of
the text range.
IndexOutOfBoundsException
- if the
beginIndex
is negative, or
endIndex
is larger than the length of this
String
, or
beginIndex
is larger than
endIndex
.
public int offsetByCodePoints(int index, int codePointOffset)
String
that is
offset from the given
index
by
codePointOffset
code points. Unpaired surrogates
within the text range given by
index
and
codePointOffset
count as one code point each.
index
- the index to be offset
codePointOffset
- the offset in code points
String
IndexOutOfBoundsException
- if
index
is negative or larger then the length of this
String
, or if
codePointOffset
is positive
and the substring starting with
index
has fewer
than
codePointOffset
code points,
or if
codePointOffset
is negative and the substring
before
index
has fewer than the absolute value
of
codePointOffset
code points.
srcBegin
;
the last character to be copied is at index
srcEnd-1
(thus the total number of characters to be copied is
srcEnd-srcBegin
). The characters are copied into the
subarray of
dst
starting at index
dstBegin
and ending at index:
dstBegin + (srcEnd-srcBegin) - 1
srcBegin
- index of the first character in the string
to copy.
srcEnd
- index after the last character in the string
to copy.
dst
- the destination array.
dstBegin
- the start offset in the destination array.
IndexOutOfBoundsException
- If any of the following
is true:
srcBegin
is negative.
srcBegin
is greater than
srcEnd
srcEnd
is greater than the length of this
string
dstBegin
is negative
dstBegin+(srcEnd-srcBegin)
is larger than
dst.length
getBytes()
method, which uses the platform's default charset.
The first character to be copied is at index
srcBegin
; the
last character to be copied is at index
srcEnd-1
. The total
number of characters to be copied is
srcEnd-srcBegin
. The
characters, converted to bytes, are copied into the subarray of
dst
starting at index
dstBegin
and ending at index:
dstBegin + (srcEnd-srcBegin) - 1
srcBegin
- Index of the first character in the string to copy
srcEnd
- Index after the last character in the string to copy
dst
- The destination array
dstBegin
- The start offset in the destination array
IndexOutOfBoundsException
- If any of the following is true:
srcBegin
is negative
srcBegin
is greater than
srcEnd
srcEnd
is greater than the length of this String
dstBegin
is negative
dstBegin+(srcEnd-srcBegin)
is larger than
dst.length
public byte[] getBytes(String charsetName) throws UnsupportedEncodingException
String
into a sequence of bytes using the named
charset, storing the result into a new byte array.
The behavior of this method when this string cannot be encoded in
the given charset is unspecified. The
CharsetEncoder
class should be used when more control
over the encoding process is required.
charsetName
- The name of a supported
charset
UnsupportedEncodingException
- If the named charset is not supported
public byte[] getBytes(Charset charset)
String
into a sequence of bytes using the given
charset
, storing the result into a
new byte array.
This method always replaces malformed-input and unmappable-character
sequences with this charset's default replacement byte array. The
CharsetEncoder
class should be used when more
control over the encoding process is required.
charset
- The
Charset
to be used to encode
the
String
public byte[] getBytes()
String
into a sequence of bytes using the
platform's default charset, storing the result into a new byte array.
The behavior of this method when this string cannot be encoded in
the default charset is unspecified. The
CharsetEncoder
class should be used when more control
over the encoding process is required.
public boolean equals(Object anObject)
true
if and only if the argument is not
null
and is a
String
object that represents the same sequence of characters as this
object.
For finer-grained String comparison, refer to
Collator
.
equals
in class
Object
anObject
- The object to compare this
String
against
true
if the given object represents a
String
equivalent to this string,
false
otherwise
compareTo(String)
,
equalsIgnoreCase(String)
public boolean contentEquals(StringBuffer sb)
StringBuffer
. The result
is
true
if and only if this
String
represents the same
sequence of characters as the specified
StringBuffer
. This method
synchronizes on the
StringBuffer
.
For finer-grained String comparison, refer to
Collator
.
sb
- The
StringBuffer
to compare this
String
against
true
if this
String
represents the same
sequence of characters as the specified
StringBuffer
,
false
otherwise
public boolean contentEquals(CharSequence cs)
CharSequence
. The
result is
true
if and only if this
String
represents the
same sequence of char values as the specified sequence. Note that if the
CharSequence
is a
StringBuffer
then the method
synchronizes on it.
For finer-grained String comparison, refer to
Collator
.
cs
- The sequence to compare this
String
against
true
if this
String
represents the same
sequence of char values as the specified sequence,
false
otherwise
public boolean equalsIgnoreCase(String anotherString)
String
to another
String
, ignoring case
considerations. Two strings are considered equal ignoring case if they
are of the same length and corresponding characters in the two strings
are equal ignoring case.
Two characters
c1
and
c2
are considered the same
ignoring case if at least one of the following is true:
==
operator)
Character.toLowerCase(Character.toUpperCase(char))
on each character produces the same result
Note that this method does
not
take locale into account, and
will result in unsatisfactory results for certain locales. The
Collator
class provides locale-sensitive comparison.
anotherString
- The
String
to compare this
String
against
true
if the argument is not
null
and it
represents an equivalent
String
ignoring case;
false
otherwise
equals(Object)
public int compareTo(String anotherString)
String
object is compared lexicographically to the
character sequence represented by the argument string. The result is
a negative integer if this
String
object
lexicographically precedes the argument string. The result is a
positive integer if this
String
object lexicographically
follows the argument string. The result is zero if the strings
are equal;
compareTo
returns
0
exactly when
the
equals(Object)
method would return
true
.
This is the definition of lexicographic ordering. If two strings are
different, then either they have different characters at some index
that is a valid index for both strings, or their lengths are different,
or both. If they have different characters at one or more index
positions, let
k
be the smallest such index; then the string
whose character at position
k
has the smaller value, as
determined by using the
<
operator, lexicographically precedes the
other string. In this case,
compareTo
returns the
difference of the two character values at position
k
in
the two string -- that is, the value:
this.charAt(k)-anotherString.charAt(k)
If there is no index position at which they differ, then the shorter
string lexicographically precedes the longer string. In this case,
compareTo
returns the difference of the lengths of the
strings -- that is, the value:
this.length()-anotherString.length()
For finer-grained String comparison, refer to
Collator
.
compareTo
in interface
Comparable
<
String
>
anotherString
- the
String
to be compared.
0
if the argument string is equal to
this string; a value less than
0
if this string
is lexicographically less than the string argument; and a
value greater than
0
if this string is
lexicographically greater than the string argument.
public int compareToIgnoreCase(String str)
compareTo
with normalized versions of the strings
where case differences have been eliminated by calling
Character.toLowerCase(Character.toUpperCase(character))
on
each character.
Note that this method does
not
take locale into account,
and will result in an unsatisfactory ordering for certain locales.
The
Collator
class provides locale-sensitive comparison.
str
- the
String
to be compared.
Collator
String
object is compared to a substring
of the argument other. The result is true if these substrings
represent identical character sequences. The substring of this
String
object to be compared begins at index
toffset
and has length
len
. The substring of other to be compared
begins at index
ooffset
and has length
len
. The
result is
false
if and only if at least one of the following
is true:
toffset
is negative.
ooffset
is negative.
toffset+len
is greater than the length of this
String
object.
ooffset+len
is greater than the length of the other
argument.
len
such that:
this.charAt(toffset +
k
) != other.charAt(ooffset +
Note that this method does
not
take locale into account. The
Collator
class provides locale-sensitive comparison.
toffset
- the starting offset of the subregion in this string.
other
- the string argument.
ooffset
- the starting offset of the subregion in the string
argument.
len
- the number of characters to compare.
true
if the specified subregion of this string
exactly matches the specified subregion of the string argument;
false
otherwise.
String
object is compared to a substring
of the argument
other
. The result is
true
if these
substrings represent character sequences that are the same, ignoring
case if and only if
ignoreCase
is true. The substring of
this
String
object to be compared begins at index
toffset
and has length
len
. The substring of
other
to be compared begins at index
ooffset
and
has length
len
. The result is
false
if and only if
at least one of the following is true:
toffset
is negative.
ooffset
is negative.
toffset+len
is greater than the length of this
String
object.
ooffset+len
is greater than the length of the other
argument.
ignoreCase
is
false
and there is some nonnegative
integer
k
less than
len
such that:
this.charAt(toffset+k) != other.charAt(ooffset+k)
ignoreCase
is
true
and there is some nonnegative
integer
k
less than
len
such that:
Character.toLowerCase(Character.toUpperCase(this.charAt(toffset+k))) !=
Character.toLowerCase(Character.toUpperCase(other.charAt(ooffset+k)))
Note that this method does
not
take locale into account,
and will result in unsatisfactory results for certain locales when
ignoreCase
is
true
. The
Collator
class
provides locale-sensitive comparison.
ignoreCase
- if
true
, ignore case when comparing
characters.
toffset
- the starting offset of the subregion in this
string.
other
- the string argument.
ooffset
- the starting offset of the subregion in the string
argument.
len
- the number of characters to compare.
true
if the specified subregion of this string
matches the specified subregion of the string argument;
false
otherwise. Whether the matching is exact
or case insensitive depends on the
ignoreCase
argument.
public boolean startsWith(String prefix, int toffset)
prefix
- the prefix.
toffset
- where to begin looking in this string.
true
if the character sequence represented by the
argument is a prefix of the substring of this object starting
at index
toffset
;
false
otherwise.
The result is
false
if
toffset
is
negative or greater than the length of this
String
object; otherwise the result is the same
as the result of the expression
this.substring(toffset).startsWith(prefix)
public boolean startsWith(String prefix)
prefix
- the prefix.
true
if the character sequence represented by the
argument is a prefix of the character sequence represented by
this string;
false
otherwise.
Note also that
true
will be returned if the
argument is an empty string or is equal to this
String
object as determined by the
equals(Object)
method.
public boolean endsWith(String suffix)
suffix
- the suffix.
true
if the character sequence represented by the
argument is a suffix of the character sequence represented by
this object;
false
otherwise. Note that the
result will be
true
if the argument is the
empty string or is equal to this
String
object
as determined by the
equals(Object)
method.
public int hashCode()
String
object is computed as
s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
using
int
arithmetic, where
s[i]
is the
i
th character of the string,
n
is the length of
the string, and
^
indicates exponentiation.
(The hash value of the empty string is zero.)
hashCode
in class
Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public int indexOf(int ch)
ch
occurs in the character sequence represented by
this
String
object, then the index (in Unicode
code units) of the first such occurrence is returned. For
values of
ch
in the range from 0 to 0xFFFF
(inclusive), this is the smallest value
k
such that:
this.charAt(
k
) == ch
is true. For other values of
ch
, it is the
smallest value
k
such that:
this.codePointAt(
k
) == ch
is true. In either case, if no such character occurs in this
string, then
-1
is returned.
ch
- a character (Unicode code point).
-1
if the character does not occur.
public int indexOf(int ch, int fromIndex)
ch
occurs in the
character sequence represented by this
String
object at an index no smaller than
fromIndex
, then
the index of the first such occurrence is returned. For values
of
ch
in the range from 0 to 0xFFFF (inclusive),
this is the smallest value
k
such that:
(this.charAt(
k
) == ch)
&&
(
k
>= fromIndex)
is true. For other values of
ch
, it is the
smallest value
k
such that:
(this.codePointAt(
k
) == ch)
&&
(
k
>= fromIndex)
is true. In either case, if no such character occurs in this
string at or after position
fromIndex
, then
-1
is returned.
There is no restriction on the value of
fromIndex
. If it
is negative, it has the same effect as if it were zero: this entire
string may be searched. If it is greater than the length of this
string, it has the same effect as if it were equal to the length of
this string:
-1
is returned.
All indices are specified in
char
values
(Unicode code units).
ch
- a character (Unicode code point).
fromIndex
- the index to start the search from.
fromIndex
, or
-1
if the character does not occur.
public int lastIndexOf(int ch)
ch
in the
range from 0 to 0xFFFF (inclusive), the index (in Unicode code
units) returned is the largest value
k
such that:
this.charAt(
k
) == ch
is true. For other values of
ch
, it is the
largest value
k
such that:
this.codePointAt(
k
) == ch
is true. In either case, if no such character occurs in this
string, then
-1
is returned. The
String
is searched backwards starting at the last
character.
ch
- a character (Unicode code point).
-1
if the character does not occur.
public int lastIndexOf(int ch, int fromIndex)
ch
in the range
from 0 to 0xFFFF (inclusive), the index returned is the largest
value
k
such that:
(this.charAt(
k
) == ch)
&&
(
k
<= fromIndex)
is true. For other values of
ch
, it is the
largest value
k
such that:
(this.codePointAt(
k
) == ch)
&&
(
k
<= fromIndex)
is true. In either case, if no such character occurs in this
string at or before position
fromIndex
, then
-1
is returned.
All indices are specified in
char
values
(Unicode code units).
ch
- a character (Unicode code point).
fromIndex
- the index to start the search from. There is no
restriction on the value of
fromIndex
. If it is
greater than or equal to the length of this string, it has
the same effect as if it were equal to one less than the
length of this string: this entire string may be searched.
If it is negative, it has the same effect as if it were -1:
-1 is returned.
fromIndex
, or
-1
if the character does not occur before that point.
public int indexOf(String str)
The returned index is the smallest value
k
for which:
this.startsWith(str, k)
If no such value of
k
exists, then
-1
is returned.
str
- the substring to search for.
-1
if there is no such occurrence.
public int indexOf(String str, int fromIndex)
The returned index is the smallest value
k
for which:
k >= Math.min(fromIndex, this.length()) &&
this.startsWith(str, k)
If no such value of
k
exists, then
-1
is returned.
str
- the substring to search for.
fromIndex
- the index from which to start the search.
-1
if there is no such occurrence.
public int lastIndexOf(String str)
this.length()
.
The returned index is the largest value
k
for which:
this.startsWith(str, k)
If no such value of
k
exists, then
-1
is returned.
str
- the substring to search for.
-1
if there is no such occurrence.
public int lastIndexOf(String str, int fromIndex)
The returned index is the largest value
k
for which:
k <= Math.min(fromIndex, this.length()) &&
this.startsWith(str, k)
If no such value of
k
exists, then
-1
is returned.
str
- the substring to search for.
fromIndex
- the index to start the search from.
-1
if there is no such occurrence.
public String substring(int beginIndex)
Examples: "unhappy".substring(2) returns "happy" "Harbison".substring(3) returns "bison" "emptiness".substring(9) returns "" (an empty string)
beginIndex
- the beginning index, inclusive.
IndexOutOfBoundsException
- if
beginIndex
is negative or larger than the
length of this
String
object.
public String substring(int beginIndex, int endIndex)
beginIndex
and
extends to the character at index
endIndex - 1
.
Thus the length of the substring is
endIndex-beginIndex
.
Examples:
"hamburger".substring(4, 8) returns "urge"
"smiles".substring(1, 5) returns "mile"
beginIndex
- the beginning index, inclusive.
endIndex
- the ending index, exclusive.
IndexOutOfBoundsException
- if the
beginIndex
is negative, or
endIndex
is larger than the length of
this
String
object, or
beginIndex
is larger than
endIndex
.
public CharSequence subSequence(int beginIndex, int endIndex)
An invocation of this method of the form str.subSequence(begin, end) behaves in exactly the same way as the invocation str.substring(begin, end)
subSequence
in interface
CharSequence
String
class can implement
the
CharSequence
interface.
beginIndex
- the begin index, inclusive.
endIndex
- the end index, exclusive.
IndexOutOfBoundsException
- if
beginIndex
or
endIndex
is negative,
if
endIndex
is greater than
length()
,
or if
beginIndex
is greater than
endIndex
public String concat(String str)
0
, then this
String
object is returned. Otherwise, a
String
object is returned that represents a character
sequence that is the concatenation of the character sequence
represented by this
String
object and the character
sequence represented by the argument string.
Examples: "cares".concat("s") returns "caress" "to".concat("get").concat("her") returns "together"
str
- the
String
that is concatenated to the end
of this
String
.
public String replace(char oldChar, char newChar)
oldChar
in this string with
newChar
.
If the character
oldChar
does not occur in the
character sequence represented by this
String
object,
then a reference to this
String
object is returned.
Otherwise, a
String
object is returned that
represents a character sequence identical to the character sequence
represented by this
String
object, except that every
occurrence of
oldChar
is replaced by an occurrence
of
newChar
.
Examples:
"mesquite in your cellar".replace('e', 'o')
returns "mosquito in your collar"
"the war of baronets".replace('r', 'y')
returns "the way of bayonets"
"sparring with a purple porpoise".replace('p', 't')
returns "starring with a turtle tortoise"
"JonL".replace('q', 'x') returns "JonL" (no change)
oldChar
- the old character.
newChar
- the new character.
oldChar
with
newChar
.
public boolean matches(String regex)
An invocation of this method of the form
str
.matches(
regex
)
yields exactly the
same result as the expression
Pattern
.
matches(
regex
,
str
)
regex
- the regular expression to which this string is to be matched
true
if, and only if, this string matches the
given regular expression
PatternSyntaxException
- if the regular expression's syntax is invalid
Pattern
public boolean contains(CharSequence s)
s
- the sequence to search for
s
, false otherwise
public String replaceFirst(String regex, String replacement)
An invocation of this method of the form
str
.replaceFirst(
regex
,
repl
)
yields exactly the same result as the expression
Pattern
.
compile
(
regex
).
matcher
(
str
).
replaceFirst
(
repl
)
Note that backslashes (
\
) and dollar signs (
$
) in the
replacement string may cause the results to be different than if it were
being treated as a literal replacement string; see
Matcher.replaceFirst(java.lang.String)
.
Use
Matcher.quoteReplacement(java.lang.String)
to suppress the special
meaning of these characters, if desired.
regex
- the regular expression to which this string is to be matched
replacement
- the string to be substituted for the first match
String
PatternSyntaxException
- if the regular expression's syntax is invalid
Pattern
public String replaceAll(String regex, String replacement)
An invocation of this method of the form
str
.replaceAll(
regex
,
repl
)
yields exactly the same result as the expression
Pattern
.
compile
(
regex
).
matcher
(
str
).
replaceAll
(
repl
)
Note that backslashes (
\
) and dollar signs (
$
) in the
replacement string may cause the results to be different than if it were
being treated as a literal replacement string; see
Matcher.replaceAll
.
Use
Matcher.quoteReplacement(java.lang.String)
to suppress the special
meaning of these characters, if desired.
regex
- the regular expression to which this string is to be matched
replacement
- the string to be substituted for each match
String
PatternSyntaxException
- if the regular expression's syntax is invalid
Pattern
public String replace(CharSequence target, CharSequence replacement)
target
- The sequence of char values to be replaced
replacement
- The replacement sequence of char values
public String[] split(String regex, int limit)
The array returned by this method contains each substring of this string that is terminated by another substring that matches the given expression or is terminated by the end of the string. The substrings in the array are in the order in which they occur in this string. If the expression does not match any part of the input then the resulting array has just one element, namely this string.
When there is a positive-width match at the beginning of this string then an empty leading substring is included at the beginning of the resulting array. A zero-width match at the beginning however never produces such empty leading substring.
The
limit
parameter controls the number of times the
pattern is applied and therefore affects the length of the resulting
array.
If the
limit
is positive then the pattern will be applied
at most
limit
- 1 times, the array's length will be
no greater than
limit
, and the array's last entry will contain
all input beyond the last matched delimiter.
If the limit is negative then the pattern will be applied as many times as possible and the array can have any length.
The string
"boo:and:foo"
, for example, yields the
following results with these parameters:
Split example showing regex, limit, and result
Regex
Limit
Result
{ "boo", "and:foo" }
{ "boo", "and", "foo" }
{ "boo", "and", "foo" }
{ "b", "", ":and:f", "", "" }
{ "b", "", ":and:f", "", "" }
{ "b", "", ":and:f" }
An invocation of this method of the form
str.
split(
regex
,
n
)
yields the same result as the expression
Pattern
.
compile
(
regex
).
split
(
str
,
n
)
regex
- the delimiting regular expression
limit
- the result threshold, as described above
PatternSyntaxException
- if the regular expression's syntax is invalid
Pattern
public String[] split(String regex)
This method works as if by invoking the two-argument
split
method with the given expression and a limit
argument of zero. Trailing empty strings are therefore not included in
the resulting array.
The string
"boo:and:foo"
, for example, yields the following
results with these expressions:
Split examples showing regex and result
Regex
Result
{ "boo", "and", "foo" }
{ "b", "", ":and:f" }
regex
- the delimiting regular expression
PatternSyntaxException
- if the regular expression's syntax is invalid
Pattern
public static String join(CharSequence delimiter, CharSequence... elements)
CharSequence elements
joined together with a copy of
the specified
delimiter
.
For example,
String message = String.join("-", "Java", "is", "cool");
// message returned is: "Java-is-cool"
Note that if an element is null, then
"null"
is added.
delimiter
- the delimiter that separates each element
elements
- the elements to join together.
String
that is composed of the
elements
separated by the
delimiter
NullPointerException
- If
delimiter
or
elements
is
null
StringJoiner
public static String join(CharSequence delimiter, Iterable<? extends CharSequence> elements)
String
composed of copies of the
CharSequence elements
joined together with a copy of the
specified
delimiter
.
For example, List<String> strings = List.of("Java", "is", "cool"); String message = String.join(" ", strings); //message returned is: "Java is cool" Set<String> strings = new LinkedHashSet<>(List.of("Java", "is", "very", "cool")); String message = String.join("-", strings); //message returned is: "Java-is-very-cool" Note that if an individual element isnull
, then"null"
is added.
delimiter
- a sequence of characters that is used to separate each
of the
elements
in the resulting
String
elements
- an
Iterable
that will have its
elements
joined together.
String
that is composed from the
elements
argument
NullPointerException
- If
delimiter
or
elements
is
null
join(CharSequence,CharSequence...)
,
StringJoiner
public String toLowerCase(Locale locale)
String
to lower
case using the rules of the given
Locale
. Case mapping is based
on the Unicode Standard version specified by the
Character
class. Since case mappings are not always 1:1 char mappings, the resulting
String
may be a different length than the original
String
.
Examples of lowercase mappings are in the following table:
Lowercase mapping examples showing language code of locale, upper case, lower case, and description
Language Code of Locale
Upper Case
Lower Case
Description
locale
- use the case transformation rules for this locale
String
, converted to lowercase.
toLowerCase()
,
toUpperCase()
,
toUpperCase(Locale)
public String toLowerCase()
String
to lower
case using the rules of the default locale. This is equivalent to calling
toLowerCase(Locale.getDefault())
.
Note:
This method is locale sensitive, and may produce unexpected
results if used for strings that are intended to be interpreted locale
independently.
Examples are programming language identifiers, protocol keys, and HTML
tags.
For instance,
"TITLE".toLowerCase()
in a Turkish locale
returns
"t\u0131tle"
, where '\u0131' is the
LATIN SMALL LETTER DOTLESS I character.
To obtain correct results for locale insensitive strings, use
toLowerCase(Locale.ROOT)
.
String
, converted to lowercase.
toLowerCase(Locale)
public String toUpperCase(Locale locale)
String
to upper
case using the rules of the given
Locale
. Case mapping is based
on the Unicode Standard version specified by the
Character
class. Since case mappings are not always 1:1 char mappings, the resulting
String
may be a different length than the original
String
.
Examples of locale-sensitive and 1:M case mappings are in the following table.
Examples of locale-sensitive and 1:M case mappings. Shows Language code of locale, lower case, upper case, and description.
Language Code of Locale
Lower Case
Upper Case
Description
locale
- use the case transformation rules for this locale
String
, converted to uppercase.
toUpperCase()
,
toLowerCase()
,
toLowerCase(Locale)
public String toUpperCase()
String
to upper
case using the rules of the default locale. This method is equivalent to
toUpperCase(Locale.getDefault())
.
Note:
This method is locale sensitive, and may produce unexpected
results if used for strings that are intended to be interpreted locale
independently.
Examples are programming language identifiers, protocol keys, and HTML
tags.
For instance,
"title".toUpperCase()
in a Turkish locale
returns
"T\u0130TLE"
, where '\u0130' is the
LATIN CAPITAL LETTER I WITH DOT ABOVE character.
To obtain correct results for locale insensitive strings, use
toUpperCase(Locale.ROOT)
.
String
, converted to uppercase.
toUpperCase(Locale)
public String trim()
'U+0020'
(the space character).
If this
String
object represents an empty character
sequence, or the first and last characters of character sequence
represented by this
String
object both have codes
that are not space (as defined above), then a
reference to this
String
object is returned.
Otherwise, if all characters in this string are space (as
defined above), then a
String
object representing an
empty string is returned.
Otherwise, let
k
be the index of the first character in the
string whose code is not a space (as defined above) and let
m
be the index of the last character in the string whose code
is not a space (as defined above). A
String
object is returned, representing the substring of this string that
begins with the character at index
k
and ends with the
character at index
m
-that is, the result of
this.substring(k, m + 1)
.
This method may be used to trim space (as defined above) from
the beginning and end of a string.
public String strip()
white space
removed.
If this
String
object represents an empty string,
or if all code points in this string are
white space
, then an empty string
is returned.
Otherwise, returns a substring of this string beginning with the first
code point that is not a
white space
up to and including the last code point that is not a
white space
.
This method may be used to strip
white space
from
the beginning and end of a string.
Character.isWhitespace(int)
public String stripLeading()
white space
removed.
If this
String
object represents an empty string,
or if all code points in this string are
white space
, then an empty string
is returned.
Otherwise, returns a substring of this string beginning with the first
code point that is not a
white space
up to to and including the last code point of this string.
This method may be used to trim
white space
from
the beginning of a string.
Character.isWhitespace(int)
public String stripTrailing()
white space
removed.
If this
String
object represents an empty string,
or if all characters in this string are
white space
, then an empty string
is returned.
Otherwise, returns a substring of this string beginning with the first
code point of this string up to and including the last code point
that is not a
white space
.
This method may be used to trim
white space
from
the end of a string.
Character.isWhitespace(int)
public boolean isBlank()
true
if the string is empty or contains only
white space
codepoints,
otherwise
false
Character.isWhitespace(int)
public Stream<String> lines()
"\n"
(U+000A),
a carriage return character
"\r"
(U+000D),
or a carriage return followed immediately by a line feed
"\r\n"
(U+000D U+000A).
A
line
is either a sequence of zero or more characters
followed by a line terminator, or it is a sequence of one or
more characters followed by the end of the string. A
line does not include the line terminator.
The stream returned by this method contains the lines from
this string in the order in which they occur.
public String toString()
toString
in interface
CharSequence
toString
in class
Object
public IntStream chars()
int
zero-extending the
char
values
from this sequence. Any char which maps to a
surrogate code
point
is passed through uninterpreted.
chars
in interface
CharSequence
public IntStream codePoints()
int
values which are then passed to the stream.
codePoints
in interface
CharSequence
public static String format(String format, Object... args)
The locale always used is the one returned by
Locale.getDefault(Locale.Category)
with
FORMAT
category specified.
format
- A
format string
args
- Arguments referenced by the format specifiers in the format
string. If there are more arguments than format specifiers, the
extra arguments are ignored. The number of arguments is
variable and may be zero. The maximum number of arguments is
limited by the maximum dimension of a Java array as defined by
The Java™ Virtual Machine Specification
.
The behaviour on a
null
argument depends on the
conversion
.
IllegalFormatException
- If a format string contains an illegal syntax, a format
specifier that is incompatible with the given arguments,
insufficient arguments given the format string, or other
illegal conditions. For specification of all possible
formatting errors, see the
Details
section of the
formatter class specification.
Formatter
l
- The
locale
to apply during
formatting. If
l
is
null
then no localization
is applied.
format
- A
format string
args
- Arguments referenced by the format specifiers in the format
string. If there are more arguments than format specifiers, the
extra arguments are ignored. The number of arguments is
variable and may be zero. The maximum number of arguments is
limited by the maximum dimension of a Java array as defined by
The Java™ Virtual Machine Specification
.
The behaviour on a
null
argument depends on the
conversion
.
IllegalFormatException
- If a format string contains an illegal syntax, a format
specifier that is incompatible with the given arguments,
insufficient arguments given the format string, or other
illegal conditions. For specification of all possible
formatting errors, see the
Details
section of the
formatter class specification
Formatter
public static String valueOf(Object obj)
Object
argument.
obj
- an
Object
.
null
, then a string equal to
"null"
; otherwise, the value of
obj.toString()
is returned.
Object.toString()
public static String valueOf(char[] data)
char
array
argument. The contents of the character array are copied; subsequent
modification of the character array does not affect the returned
string.
data
- the character array.
String
that contains the characters of the
character array.
char
array argument.
The
offset
argument is the index of the first
character of the subarray. The
count
argument
specifies the length of the subarray. The contents of the subarray
are copied; subsequent modification of the character array does not
affect the returned string.
data
- the character array.
offset
- initial offset of the subarray.
count
- length of the subarray.
String
that contains the characters of the
specified subarray of the character array.
IndexOutOfBoundsException
- if
offset
is
negative, or
count
is negative, or
offset+count
is larger than
data.length
.
data
- the character array.
offset
- initial offset of the subarray.
count
- length of the subarray.
String
that contains the characters of the
specified subarray of the character array.
IndexOutOfBoundsException
- if
offset
is
negative, or
count
is negative, or
offset+count
is larger than
data.length
.
public static String copyValueOf(char[] data)
valueOf(char[])
.
data
- the character array.
String
that contains the characters of the
character array.
public static String valueOf(boolean b)
boolean
argument.
b
- a
boolean
.
true
, a string equal to
"true"
is returned; otherwise, a string equal to
"false"
is returned.
public static String valueOf(char c)
char
argument.
c
- a
char
.
1
containing
as its single character the argument
c
.
public static String valueOf(int i)
int
argument.
The representation is exactly the one returned by the
Integer.toString
method of one argument.
i
- an
int
.
int
argument.
Integer.toString(int, int)
public static String valueOf(long l)
long
argument.
The representation is exactly the one returned by the
Long.toString
method of one argument.
l
- a
long
.
long
argument.
Long.toString(long)
public static String valueOf(float f)
float
argument.
The representation is exactly the one returned by the
Float.toString
method of one argument.
f
- a
float
.
float
argument.
Float.toString(float)
public static String valueOf(double d)
double
argument.
The representation is exactly the one returned by the
Double.toString
method of one argument.
d
- a
double
.
double
argument.
Double.toString(double)
String
.
When the intern method is invoked, if the pool already contains a
string equal to this
String
object as determined by
the
equals(Object)
method, then the string from the pool is
returned. Otherwise, this
String
object is added to the
pool and a reference to this
String
object is returned.
It follows that for any two strings
s
and
t
,
s.intern() == t.intern()
is
true
if and only if
s.equals(t)
is
true
.
All literal strings and string-valued constant expressions are
interned. String literals are defined in section 3.10.5 of the
The Java™ Language Specification
.
public String repeat(int count)
count
times.
If this string is empty or count is zero then the empty
string is returned.
count
- number of times to repeat
count
times or the empty string if this
string is empty or count is zero
IllegalArgumentException
- if the
count
is
negative.