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. String concatenation is implemented
through the StringBuilder(or StringBuffer)
class and its append method.
String conversions are implemented through the method
toString, defined by Object and
inherited by all classes in Java. For additional information on
string concatenation and conversion, see Gosling, Joy, and Steele,
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).
String object so that it
represents an empty character sequence. Note that use of this
constructor is unnecessary since Strings are immutable.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.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.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.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 chars; subsequent
modification of the int array does not affect the
newly created string.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 method above.
String containing characters
constructed from an array of 8-bit integer values. Each character
cin the resulting string is constructed from the
corresponding component b in the byte array such that:
c == (char)(((hibyte & 0xff) << 8)
| (b & 0xff))
The behavior of this constructor when the given bytes are not valid in the given charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required.
The behavior of this constructor when the given bytes are not valid in the given charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required.
The behavior of this constructor when the given bytes are not valid in the default charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required.
The behavior of this constructor when the given bytes are not valid in the default charset is unspecified. The java.nio.charset.CharsetDecoder class should be used when more control over the decoding process is required.
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.
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 java.text package provides Collators to allow locale-sensitive ordering.
char value at the specified index. An index ranges from zero
to length() - 1. The first char value of the sequence is at
index zero, the next at index one, and so on, as for array
indexing.
If the char value specified by the index is a
surrogate, the surrogate
value is returned.
char values
(Unicode code units) and ranges from 0 to
- 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.
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.
String. The text range begins at the
specified beginIndex and extends to the
char at index endIndex - 1. Thus the
length (in chars) of the text range is
endIndex-beginIndex. Unpaired surrogates within
the text range count as one code point each.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
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:
If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case,this.charAt(k)-anotherString.charAt(k)
compareTo returns the difference of the lengths of the
strings -- that is, the value:
this.length()-anotherString.length()
In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of -1, 0, or 1 according to whether the value of expression is negative, zero or positive. The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)
The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.
Finally, the implementer must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.
It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."
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 java.text package provides collators to allow locale-sensitive ordering.
If the length of the argument string is 0, then this
String object is returned. Otherwise, a new
String object is created, representing 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"
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.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:
The locale always used is the one returned by Locale.getDefault() .
The behavior of this method when this string cannot be encoded in the default charset is unspecified. The java.nio.charset.CharsetEncoder class should be used when more control over the encoding process is required.
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
The behavior of this method when this string cannot be encoded in the given charset is unspecified. The java.nio.charset.CharsetEncoder class should be used when more control over the encoding process is required.
The first character to be copied is at index 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
String object is computed as
usings[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
int arithmetic, where s[i] is the
ith character of the string, n is the length of
the string, and ^ indicates exponentiation.
(The hash value of the empty string is zero.)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:
is true. For other values ofthis.charAt(k) == ch
ch, it is the
smallest value k such that:
is true. In either case, if no such character occurs in this string, thenthis.codePointAt(k) == ch
-1 is returned.
If a character with value 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:
is true. For other values of(this.charAt(k) == ch) && (k >= fromIndex)
ch, it is the
smallest value k such that:
is true. In either case, if no such character occurs in this string at or after position(this.codePointAt(k) == ch) && (k >= fromIndex)
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).
isthis.startsWith(str, k)
true.
k >= Math.min(fromIndex, str.length()) && this.startsWith(str, k)
A pool of strings, initially empty, is maintained privately by the
class String.
When the intern method is invoked, if the pool already contains a
string equal to this String object as determined by
the
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 §3.10.5 of the Java Language Specification
ch in the
range from 0 to 0xFFFF (inclusive), the index (in Unicode code
units) returned is the largest value k such that:
is true. For other values ofthis.charAt(k) == ch
ch, it is the
largest value k such that:
is true. In either case, if no such character occurs in this string, thenthis.codePointAt(k) == ch
-1 is returned. The
String is searched backwards starting at the last
character.ch in the range
from 0 to 0xFFFF (inclusive), the index returned is the largest
value k such that:
is true. For other values of(this.charAt(k) == ch) && (k <= fromIndex)
ch, it is the
largest value k such that:
is true. In either case, if no such character occurs in this string at or before position(this.codePointAt(k) == ch) && (k <= fromIndex)
fromIndex, then
-1 is returned.
All indices are specified in char values
(Unicode code units).
this.length().
The returned index is the largest value k such that
is true.this.startsWith(str, k)
k <= Math.min(fromIndex, str.length()) && this.startsWith(str, k)
chars in the sequence.An invocation of this method of the form str.matches(regex) yields exactly the same result as the expression
java.util.regex.Pattern .matches (regex, str)
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
- By executing a synchronized instance method of that object.
- By executing the body of a
synchronizedstatement that synchronizes on the object. - For objects of type
Class,by executing a synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
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.A substring of this 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:
and:Character.toLowerCase(this.charAt(toffset+k)) != Character.toLowerCase(other.charAt(ooffset+k))Character.toUpperCase(this.charAt(toffset+k)) != Character.toUpperCase(other.charAt(ooffset+k))
A substring of this 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.
- There is some nonnegative integer k less than len such that: this.charAt(toffset+k) != other.charAt(ooffset+k)
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 new String object is created 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)
An invocation of this method of the form str.replaceAll(regex, repl) yields exactly the same result as the expression
java.util.regex.Pattern .compile (regex).matcher (str).replaceAll (repl)
An invocation of this method of the form str.replaceFirst(regex, repl) yields exactly the same result as the expression
java.util.regex.Pattern .compile (regex).matcher (str).replaceFirst (repl)
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:
Regex Result : { "boo", "and", "foo" } o { "b", "", ":and:f" }
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.
The limit parameter controls the number of times the pattern is applied and therefore affects the length of the resulting array. If the limit n is greater than zero then the pattern will be applied at most n - 1 times, the array's length will be no greater than n, and the array's last entry will contain all input beyond the last matched delimiter. If n is non-positive then the pattern will be applied as many times as possible and the array can have any length. If n is zero then the pattern will be applied as many times as possible, the array can have any length, and trailing empty strings will be discarded.
The string "boo:and:foo", for example, yields the following results with these parameters:
Regex Limit Result : 2 { "boo", "and:foo" } : 5 { "boo", "and", "foo" } : -2 { "boo", "and", "foo" } o 5 { "b", "", ":and:f", "", "" } o -2 { "b", "", ":and:f", "", "" } o 0 { "b", "", ":and:f" }
An invocation of this method of the form str.split(regex, n) yields the same result as the expression
java.util.regex.Pattern .compile (regex).split (str, n)
CharSequence that is a subsequence of this sequence.
The subsequence starts with the char value at the specified index and
ends with the char value at index end - 1. The length
(in chars) of the
returned sequence is end - start, so if start == end
then an empty sequence is returned. Examples:
"unhappy".substring(2) returns "happy" "Harbison".substring(3) returns "bison" "emptiness".substring(9) returns "" (an empty string)
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"
String to lower
case using the rules of the default locale. This is equivalent to calling
toLowerCase(Locale.getDefault()).
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:
| Language Code of Locale | Upper Case | Lower Case | Description |
|---|---|---|---|
| tr (Turkish) | \u0130 | \u0069 | capital letter I with dot above -> small letter i |
| tr (Turkish) | \u0049 | \u0131 | capital letter I -> small letter dotless i |
| (all) | French Fries | french fries | lowercased all chars in String |
| (all) |  
 
 |
 
 
 |
lowercased all chars in String |
String to upper
case using the rules of the default locale. This method is equivalent to
toUpperCase(Locale.getDefault()).
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.
| Language Code of Locale | Lower Case | Upper Case | Description |
|---|---|---|---|
| tr (Turkish) | \u0069 | \u0130 | small letter i -> capital letter I with dot above |
| tr (Turkish) | \u0131 | \u0049 | small letter dotless i -> capital letter I |
| (all) | \u00df | \u0053 \u0053 | small letter sharp s -> two letters: SS |
| (all) | Fahrvergnügen | FAHRVERGNÜGEN |
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
greater than '\u0020' (the space character), then a
reference to this String object is returned.
Otherwise, if there is no character with a code greater than
'\u0020' in the string, then a new
String object representing an empty string is created
and returned.
Otherwise, let k be the index of the first character in the
string whose code is greater than '\u0020', and let
m be the index of the last character in the string whose code
is greater than '\u0020'. A new String
object is created, 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 whitespace (as defined above) from the beginning and end of a string.
boolean argument.char
argument.char array
argument. The contents of the character array are copied; subsequent
modification of the character array does not affect the newly
created string.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 newly created string.
double argument.
The representation is exactly the one returned by the
Double.toString method of one argument.
float argument.
The representation is exactly the one returned by the
Float.toString method of one argument.
int argument.
The representation is exactly the one returned by the
Integer.toString method of one argument.
long argument.
The representation is exactly the one returned by the
Long.toString method of one argument.
Object argument.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
- Some other thread invokes the notify method for this object and thread T happens to be arbitrarily chosen as the thread to be awakened.
- Some other thread invokes the notifyAll method for this object.
- Some other thread interrupts thread T.
- The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified.
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
- Another thread notifies threads waiting on this object's monitor
to wake up either through a call to the
notifymethod or thenotifyAllmethod. - The timeout period, specified by
timeoutmilliseconds plusnanosnanoseconds arguments, has elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.