The String class
represents a read-only string of characters. A
String object is created by the Java compiler
whenever it encounters a string in double quotes; this method of
creation is typically simpler than using a constructor. The static
valueOf( ) factory methods create new
String objects that hold the textual
representation of various Java primitive types. There are also
valueOf( ) methods, copyValueOf(
) methods and String( ) constructors for
creating a String object that holds a copy of the
text contained in another String,
StringBuffer, StringBuilder, or
a char or int array. You can
also use the String( ) constructor to create a
String object from an array of bytes. If you do
this, you may explicitly specify the name of the charset (or
character encoding) to be used to decode the bytes into characters,
or you can rely on the default charset for your platform. (See
java.nio.charset.Charset for more on charset
names.)
In Java
5.0, the
static format( ) methods provide another useful
way to create String objects that hold formatted
text. These utility methods create and use a new
java.util.Formatter object and behave like the
sprintf( ) function in the C programming language.
length( ) returns the
number of characters in a string. charAt( )
extracts a character from a string. You can use these two methods to
iterate through the characters of a string. You can obtain a
char array that holds the characters of a string
with toCharArray( ), or use getChars(
) to copy just a selected region of the string into an
existing array. Use getBytes( ) if you want to
obtain an array of bytes that contains the encoded form of the
characters in a string, using either the platform's
default encoding or a named encoding.
This class
defines many methods for comparing strings and substrings.
equals( ) returns TRue if two
String objects contain the same text, and
equalsIgnoreCase( ) returns
true if two strings are equal when uppercase and
lowercase differences are ignored. As of Java 1.4, the
contentEquals( ) method compares a string to a
specified StringBuffer object, returning
true if they contain the same text.
startsWith( ) and endsWith( )
return true if a string starts with the specified
prefix string or ends with the specified suffix string. A
two-argument version of startsWith( ) allows you
to specify a position within this string at which the prefix
comparison is to be done. The regionMatches(
) method is a generalized version of
this startsWith( ) method. It returns
TRue if the specified region of the specified
string matches the characters that begin at a specified position
within this string. The five-argument version of this method allows
you to perform this comparison ignoring the case of the characters
being compared. The final string comparison method is
matches( ), which, as described below, compares a
string to a regular expression pattern.
compareTo( ) is another
string comparison method, but it is used for comparing the order of
two strings, rather than simply comparing them for equality.
compareTo( ) implements the
Comparable interface and enables sorting of lists
and arrays of String objects. See
Comparable for more information.
compareToIgnoreCase( ) is like compareTo(
) but ignores the case of the two strings when doing the
comparison. The CASE_INSENSITIVE_ORDER constant is
a Comparator for sorting strings in a way that
ignores the case of their characters. (The
java.util.Comparator interface is similar to the
Comparable interface but allows the definition of
object orderings that are different from the default ordering defined
by Comparable.) The compareTo(
) and compareToIgnoreCase( ) methods and
the CASE_INSENSITIVE_ORDER
Comparator object order strings based only on the
numeric ordering of the Unicode encoding of their characters. This is
not always the preferred "alphabetical
ordering" in some languages. See
java.text.Collator for a more general technique
for collating strings.
indexOf( ) and
lastIndexOf( ) search forward and backward in a
string for a specified character or substring. They return the
position of the match, or -1 if there is no match. The one argument
versions of these methods start at the beginning or end of the
string, and the two-argument versions start searching from a
specified character position.
Java 5.0 adds new comparison methods that work with any
CharSequence. A new version of
contentEquals( ) enables the comparison of a
string with any CharSequence, including
StringBuilder objects. The contains(
) method returns true if the string
contains any sequence of characters equal to the specified
CharSequence.
substring( ) returns a
string that consists of the characters from (and including) the
specified start position to (but not including) the specified end
position. A one-argument version returns all characters from (and
including) the specified start position to the end of the string. As
of Java 1.4, the String class implements the
CharSequence interface and defines the
subSequence( ) method, which works just like the
two-argument version of substring( ) but returns
the specified characters as a CharSequence rather
than as a String.
Several methods return new strings that
contain modified versions of the text held by the original string
(the original string remains unchanged). replace(
) creates a new string with all occurrences of one
character replaced by another. Java 5.0 adds a generalized version of
replace( ) that replaces all occurrences of one
CharSequence with another. More general methods,
replaceAll( ) and replaceFirst(
), use regular expression pattern matching; they are
described later in this section.
toUpperCase( ) and
toLowerCase( ) return a new string in which all
characters are converted to upper- or lowercase respectively. These
case-conversion methods take an optional Locale
argument to perform locale-specific case conversion. trim(
)
is a utility method that returns a new string in which all leading
and trailing whitespace has been removed. concat(
) returns the new string formed by
concatenating or appending the specified string to this string.
String concatenation is more commonly done, however, with the
+ operator.
Note that String objects are immutable; there is
no setCharAt( ) method to change the contents. The
methods that return a String do not modify the
string they are invoked on but instead return a new
String object that holds a modified copy of the
text of the original. Use a StringBuffer if you
want to manipulate the contents of a string or call
toCharArray( ) or getChars(
)
to convert a string to an array
of char values.
Java 1.4 introduced support for pattern matching with
regular expressions.
matches( ) returns true if this string exactly
matches the pattern specified by the regular expression argument.
replaceAll( ) and replaceFirst( )
create a new string in which all occurrences or the first occurrence
of a substring that matches the specified regular expression is
replaced with the specified replacement string. The split(
) methods return an array of substrings
of this string, formed by splitting this string at positions that
match the specified regular expression. These regular expression
methods are all convenience methods that simply call methods of the
same name in the java.util.regex package. See the
Pattern and Matcher classes in
that package for further details.
Many
programs use strings as commonly as they use Java primitive values.
Because the String type is an object rather than a
primitive value, however, you cannot in general use
the = = operator to compare
two strings for equality. Instead, even though strings are immutable,
you must use the more expensive equals( ) method.
For programs that perform a lot of string comparison, the
intern( ) provides a way to speed up those
comparisons. The String class maintains a set of
String objects that includes all double-quoted
string literals and all compile-time constant strings defined in a
Java program. The set is guaranteed not to contain duplicates, and
the set is used to ensure that duplicate String
objects are not created unnecessarily. The intern(
) method looks up a string in or adds a new string to this
set of unique strings. It searches the set for a string that contains
exactly the same characters as the string you invoked the method on.
If such a string is found, intern( ) returns it.
If no matching string is found, the string you invoked
intern( ) on is itself stored in the set
("interned") and becomes the return
value of the method. What this means is that you can safely compare
any strings returned by the intern( ) method using
the = = and != operators
instead of equals( ). You can also successfully
compare any string returned by intern( ) to any
string constant with = = and
!=.
In
Java 5.0,
Unicode supplementary characters may
be represented as a single int codepoint value or
as a sequence of two char values known as a
"surrogate pair." See
Character for more on supplementary characters and
methods for working with them. String methods for
working with supplementary characters, such as codePointAt(
)
,
codePointCount( ), and
offsetByCodePoints( ), are similar to those
defined by Character.
Figure 10-58. java.lang.String
public final class
String implements Serializable, Comparable<String>, CharSequence {
// Public Constructors
public
String ( );
5.0 public
String (StringBuilder
builder );
public
String (StringBuffer
buffer );
public
String (char[ ]
value );
public
String (String
original );
1.1 public
String (byte[ ]
bytes );
1.1 public
String (byte[ ]
bytes , String
charsetName )
throws java.io.UnsupportedEncodingException;
# public
String (byte[ ]
ascii , int
hibyte );
public
String (char[ ]
value , int
offset , int
count );
1.1 public
String (byte[ ]
bytes , int
offset , int
length );
5.0 public
String (int[ ]
codePoints , int
offset , int
count );
# public
String (byte[ ]
ascii , int
hibyte , int
offset , int
count );
1.1 public
String (byte[ ]
bytes , int
offset , int
length , String
charsetName )
throws java.io.UnsupportedEncodingException;
// Public Constants
1.2 public static final java.util.Comparator<String>
CASE_INSENSITIVE_ORDER ;
// Public Class Methods
public static String
copyValueOf (char[ ]
data );
public static String
copyValueOf (char[ ]
data , int
offset , int
count );
5.0 public static String
format (String
format , Object...
args );
5.0 public static String
format (java.util.Locale
l , String
format , Object...
args );
public static String
valueOf (float
f );
public static String
valueOf (long
l );
public static String
valueOf (Object
obj );
public static String
valueOf (double
d );
public static String
valueOf (boolean
b );
public static String
valueOf (char[ ]
data );
public static String
valueOf (int
i );
public static String
valueOf (char
c );
public static String
valueOf (char[ ]
data , int
offset , int
count );
// Public Instance Methods
public char
charAt (int
index ); Implements:CharSequence
5.0 public int
codePointAt (int
index );
5.0 public int
codePointBefore (int
index );
5.0 public int
codePointCount (int
beginIndex , int
endIndex );
public int
compareTo (String
anotherString ); Implements:Comparable
1.2 public int
compareToIgnoreCase (String
str );
public String
concat (String
str );
5.0 public boolean
contains (CharSequence
s );
1.4 public boolean
contentEquals (StringBuffer
sb );
5.0 public boolean
contentEquals (CharSequence
cs );
public boolean
endsWith (String
suffix );
public boolean
equalsIgnoreCase (String
anotherString );
1.1 public byte[ ]
getBytes ( );
1.1 public byte[ ]
getBytes (String
charsetName ) throws java.io.
UnsupportedEncodingException;
public void
getChars (int
srcBegin , int
srcEnd , char[ ]
dst , int
dstBegin );
public int
indexOf (int
ch );
public int
indexOf (String
str );
public int
indexOf (int
ch , int
fromIndex );
public int
indexOf (String
str , int
fromIndex );
public String
intern ( ); native
public int
lastIndexOf (String
str );
public int
lastIndexOf (int
ch );
public int
lastIndexOf (String
str , int
fromIndex );
public int
lastIndexOf (int
ch , int
fromIndex );
public int
length ( ); Implements:CharSequence
1.4 public boolean
matches (String
regex );
5.0 public int
offsetByCodePoints (int
index , int
codePointOffset );
public boolean
regionMatches (int
toffset , String
other , int
ooffset , int
len );
public boolean
regionMatches (boolean
ignoreCase , int
toffset , String
other , int
ooffset , int
len );
public String
replace (char
oldChar , char
newChar );
5.0 public String
replace (CharSequence
target , CharSequence
replacement );
1.4 public String
replaceAll (String
regex , String
replacement );
1.4 public String
replaceFirst (String
regex , String
replacement );
1.4 public String[ ]
split (String
regex );
1.4 public String[ ]
split (String
regex , int
limit );
public boolean
startsWith (String
prefix );
public boolean
startsWith (String
prefix , int
toffset );
public String
substring (int
beginIndex );
public String
substring (int
beginIndex , int
endIndex );
public char[ ]
toCharArray ( );
public String
toLowerCase ( );
1.1 public String
toLowerCase (java.util.Locale
locale );
public String
toString ( ); Implements:CharSequence
public String
toUpperCase ( );
1.1 public String
toUpperCase (java.util.Locale
locale );
public String
trim ( );
// Methods Implementing CharSequence
public char
charAt (int
index );
public int
length ( );
1.4 public CharSequence
subSequence (int
beginIndex , int
endIndex );
public String
toString ( );
// Methods Implementing Comparable
public int
compareTo (String
anotherString );
// Public Methods Overriding Object
public boolean
equals (Object
anObject );
public int
hashCode ( );
// Deprecated Public Methods
# public void
getBytes (int
srcBegin , int
srcEnd , byte[ ]
dst , int
dstBegin );
}
Too many methods to list.
Too many methods to list.
Too many fields to list.