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.
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.
