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 relies heavily on the information provided
* by the Unicode Consortium's Unicode 3.0 specification. The
* specification's UnicodeData.txt and SpecialCasing.txt files are
* used extensively to provide case mapping.
*
* 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 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.
*
* @author Lee Boynton
* @author Arthur van Hoff
* @version 1.152, 02/01/03
* @see java.lang.Object#toString()
* @see java.lang.StringBuffer
* @see java.lang.StringBuffer#append(boolean)
* @see java.lang.StringBuffer#append(char)
* @see java.lang.StringBuffer#append(char[])
* @see java.lang.StringBuffer#append(char[], int, int)
* @see java.lang.StringBuffer#append(double)
* @see java.lang.StringBuffer#append(float)
* @see java.lang.StringBuffer#append(int)
* @see java.lang.StringBuffer#append(long)
* @see java.lang.StringBuffer#append(java.lang.Object)
* @see java.lang.StringBuffer#append(java.lang.String)
* @see java.nio.charset.Charset
* @since JDK1.0
*/
public final class String
implements java.io.Serializable, Comparable, CharSequence
{
/**
* Compares this string to the specified object.
* The result is 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.
*
* @param anObject the object to compare this String
* against.
* @return true if the String are equal;
* false otherwise.
* @see java.lang.String#compareTo(java.lang.String)
* @see java.lang.String#equalsIgnoreCase(java.lang.String)
*/
public boolean equals(Object anObject) {
if (this == anObject) {
return true;
}
if (anObject instanceof String) {
String anotherString = (String)anObject;
int n = count;
if (n == anotherString.count) {
char v1[] = value;
char v2[] = anotherString.value;
int i = offset;
int j = anotherString.offset;
while (n-- != 0) {
if (v1[i++] != v2[j++])
return false;
}
return true;
}
}
return false;
}
/**
* Compares two strings lexicographically.
* The comparison is based on the Unicode value of each character in
* the strings. The character sequence represented by this
* 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 {@link #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)
* compareTo returns the difference of the lengths of the
* strings -- that is, the value:
*
* this.length()-anotherString.length()
* String to be compared.
* @return the value 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.
* @exception java.lang.NullPointerException if anotherString
* is null.
*/
public int compareTo(String anotherString) {
int len1 = count;
int len2 = anotherString.count;
int n = Math.min(len1, len2);
char v1[] = value;
char v2[] = anotherString.value;
int i = offset;
int j = anotherString.offset;
if (i == j) {
int k = i;
int lim = n + i;
while (k < lim) {
char c1 = v1[k];
char c2 = v2[k];
if (c1 != c2) {
return c1 - c2;
}
k++;
}
} else {
while (n-- != 0) {
char c1 = v1[i++];
char c2 = v2[j++];
if (c1 != c2) {
return c1 - c2;
}
}
}
return len1 - len2;
}
/**
* Compares this String to another Object. If the Object is a String,
* this function behaves like compareTo(String). Otherwise,
* it throws a ClassCastException (as Strings are comparable
* only to other Strings).
*
* @param o the Object to be compared.
* @return the value 0 if the argument is a string
* lexicographically equal to this string; a value less than
* 0 if the argument is a string lexicographically
* greater than this string; and a value greater than
* 0 if the argument is a string lexicographically
* less than this string.
* @exception ClassCastException if the argument is not a
* String.
* @see java.lang.Comparable
* @since 1.2
*/
public int compareTo(Object o) {
return compareTo((String)o);
}
/**
* Returns a hash code for this string. The hash code for a
* String object is computed as
*
* s[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.)
*
* @return a hash code value for this object.
*/
public int hashCode() {
int h = hash;
if (h == 0) {
int off = offset;
char val[] = value;
int len = count;
for (int i = 0; i < len; i++) {
h = 31*h + val[off++];
}
hash = h;
}
return h;
}
}