Packages  This Package  Prev  Next  Index  

§1.16 Class String

public  final  class  java.lang.String
    extends  java.lang.Object  (I-§1.12)
{
        // Constructors
    public String();	§1.16.1
    public String(byte  ascii[], int  hibyte);	§1.16.2
    public String(byte  ascii[], int  hibyte, 	§1.16.3
                          int  offset, int  count);
    public String(char  value[]);	§1.16.4
    public String(char  value[], int  offset, int  count);	§1.16.5 
    public String(String  value);	§1.16.6
    public String(StringBuffer  buffer);	§1.16.7

        // Methods
    public char charAt(int  index);	§1.16.8
    public int compareTo(String  anotherString);	§1.16.9
    public String concat(String  str);	§1.16.10
    public static String copyValueOf(char  data[]);	§1.16.11
    public static String	§1.16.12
        copyValueOf(char  data[], int  offset, int count);
    public boolean endsWith(String  suffix);	§1.16.13
    public boolean equals(Object  anObject);	§1.16.14
    public boolean equalsIgnoreCase(String  anotherString);	§1.16.15
    public void getBytes(int  srcBegin, int  srcEnd,	§1.16.16
                                            byte  dst[], int  dstBegin);
    public void getChars(int  srcBegin, int  srcEnd,	§1.16.17
                                          char  dst[], int  dstBegin);
    public int hashCode();	§1.16.18
    public int indexOf(int  ch);	§1.16.19
    public int indexOf(int  ch, int  fromIndex);	§1.16.20
    public int indexOf(String  str);	§1.16.21
    public int indexOf(String  str, int  fromIndex);	§1.16.22
    public String intern();	§1.16.23
    public int lastIndexOf(int  ch);	§1.16.24
    public int lastIndexOf(int  ch, int  fromIndex);	§1.16.25
    public int lastIndexOf(String  str);	§1.16.26
    public int lastIndexOf(String  str, int  fromIndex);	§1.16.27
                       
    public int length();	§1.16.28
    public boolean regionMatches(boolean  ignoreCase,	§1.16.29
             int  toffset, String  other, int  ooffset, int  len);
    public boolean regionMatches(int  toffset, String  other,	§1.16.30  
                int  ooffset, int  len);
    public String replace(char  oldChar, 	§1.16.31
                      char  newChar);
    public boolean startsWith(String  prefix);	§1.16.32
    public boolean startsWith(String  prefix, int toffset);	§1.16.33
    public String substring(int  beginIndex);	§1.16.34
    public String substring(int  beginIndex, int endIndex);	§1.16.35
    public char[] toCharArray();	§1.16.36
    public String toLowerCase();	§1.16.37
    public String toString();	§1.16.38
    public String toUpperCase();	§1.16.39
    public String trim();	§1.16.40
    public static String valueOf(boolean  b);	§1.16.41
    public static String valueOf(char  c);	§1.16.42
    public static String valueOf(char  data[]);	§1.16.43
    public static String 	§1.16.44
        valueOf(char  data[], int  offset, int  count);
    public static String valueOf(double  d);	§1.16.45
    public static String valueOf(float  f);	§1.16.46
    public static String valueOf(int  i);	§1.16.47
    public static String valueOf(long  l);	§1.16.48
    public static String valueOf(Object  obj);	§1.16.49
}
The 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 (I-§1.17) support mutable strings.

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.


Constructors

String

public String()
Allocates a new String containing no characters.

String

public String(byte ascii[], int hibyte)
Allocates a new String containg 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))
Parameters:
ascii - the bytes to be converted to characters
hibyte - the top 8 bits of each 16-bit Unicode character

String

public String(byte ascii[], int hibyte, int offset,
int count)
Allocates a new 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 (I-§1.16.2).

Parameters:
ascii - the bytes to be converted to characters
hibyte -
the top 8 bits of each 16-bit Unicode character -
offset - the initial offset
count - the length
Throws
StringIndexOutOfBoundsException (I-§1.44)
If the offset or count argument is invalid.

String

public String(char value[])
Allocates a new String so that it represents the sequence of characters currently contained in the character array argument.
Parameters:
value - the initial value of the string

String

public String(char value[], int offset, int count)
Allocates a new 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.
Parameters:
value - array that is the source of characters
offset - the initial offset
count - the length
Throws
StringIndexOutOfBoundsException (I-§1.44)
If the offset and count arguments index characters outside the bounds of the value array.

String

public String(String value)
Allocates a new string that contains the same sequence of characters as the string argument.
Parameters:
value - a String.

String

public String(StringBuffer buffer)
Allocates a new string that contains the sequence of characters currently contained in the string buffer argument.
Parameters:
buffer - a StringBuffer.

Methods

charAt

public char charAt(int index)
Returns:
The character at the specified index of this string. The first character is at index 0.
Parameters:
index - the index of the desired character
Throws
StringIndexOutOfBoundsException (I-§1.44)
If the index is out of range.

compareTo

public int compareTo(String anotherString)
Compares two strings lexicographically.
Parameters:
anotherString - the String to be compared
Returns:
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.

concat

public String concat(String str)
Concatenates the string argument to the end of this string.
If the length of the argument string is zero, then this object is returned.
Parameters:
str - the String which is concatenated to the end of this String
Returns:
A string that represents the concatenation of this object's characters followed by the string argument's characters.

copyValueOf

public static String copyValueOf(char data[])
Returns:
a String that contains the characters of the character array.
Parameters:
data - the character array

copyValueOf

public static String
copyValueOf(char data[], int offset, int count)
Parameters:
data - the character array
offset - initial offset of the subarray
count - length of the subarray
Returns:
a String that contains the characters of the specified subarray of the character array.

endsWith

public boolean endsWith(String suffix)
Parameters:
suffix - the suffix
Returns:
true if the character sequence represented by the argument is a suffix of the character sequence represented by this object; false otherwise.

equals

public boolean equals(Object anObject)
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.
Parameters:
anObject - the object to compare this String against
Returns:
true if the String's are equal; false otherwise.
Overrides:
equals in class Object (I-§1.12.3).
See Also:
equalsIgnoreCase (I-§1.16.15)
compareTo (I-§1.16.9).

equalsIgnoreCase

public boolean equalsIgnoreCase(String anotherString)
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, where case is ignored.
Two characters are considered the same, ignoring case, if at least one of the following is true:
Two sequence of characters are the same, ignoring case, if the sequences have the same length and corresponding characters are the same, ignoring case.
Parameters:
anotherString - the String to compare this String against
Returns:
true if the String's are equal, ignoring case; false otherwise.

getBytes

public void getBytes(int srcBegin, int srcEnd,
byte dst[], int dstBegin)
Copies characters from this string into the destination byte array. Each byte receives the 8 low-order bits of the corresponding character.
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
Parameters:
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

getChars

public void getChars(int srcBegin, int srcEnd,
char dst[], int dstBegin)
Copies characters from this string into the destination character array.
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
Parameters:
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

hashCode

public int hashCode()
Returns:
a hash code value for this object.
Overrides:
hashCode in class Object (I-§1.12.6).

indexOf

public int indexOf(int ch)
Parameters:
ch - a character
Returns:
the index of the first occurrence of the character in the character sequence represented by this object, or -1 if the character does not occur.

indexOf

public int indexOf(int ch, int fromIndex)
Parameters:
ch - a character
fromIndex - the index to start the search from
Returns:
the index of the first occurrence of the character in the character sequence represented by this object that is greater than or equal to fromIndex, or -1 if the character does not occur.

indexOf

public int indexOf(String str)
Parameters:
str - any string
Returns:
if the string argument occurs as a substring within this object, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.

indexOf

public int indexOf(String str, int fromIndex)
Parameters:
str - the substring to search for
fromIndex - the index to start the search from
Returns:
If the string argument occurs as a substring within this object at a starting index no smaller than fromIndex then the index of the first character of the first such substring is returned. If it does not occur as a substring starting at fromIndex or beyond, -1 is returned.

intern

public String intern()
Creates a canonical representation for the string object.
If s and t are strings such that s.equals(t), it is guaranteed that
s.intern() == t.intern().
Returns:
a string that has the same contents as this string, but is guaranteed to be from a pool of unique strings.

lastIndexOf

public int lastIndexOf(int ch)
Parameters:
ch - a character.
Returns:
the index of the last occurrence of the character in the character sequence represented by this object, or -1 if the character does not occur.

lastIndexOf

public int lastIndexOf(int ch, int fromIndex)
Parameters:
ch - a character
fromIndex - the index to start the search from
Returns:
the index of the last occurrence of the character in the character sequence represented by this object that is less than or equal to from-Index, or -1 if the character does not occur before that point.

lastIndexOf

public int lastIndexOf(String str)
Parameters:
str - the substring to search for
Returns:
If the string argument occurs as a substring within this object, then the index of the first character of the last such substring is returned. If it does not occur as a substring, -1 is returned.

lastIndexOf

public int lastIndexOf(String str, int fromIndex)
Parameters:
str - the substring to search for
fromIndex - the index to start the search from
Returns:
If the string argument occurs as a substring within this object at a starting index no greater than fromIndex then the index of the first character of the lastsuch substring is returned. If it does not occur as a substring starting at fromIndex or earlier, -1 is returned.

length

public int length()
Returns:
the length of the sequence of characters represented by this object is returned.

regionMatches

public boolean
regionMatches(boolean ignoreCase, int toffset,
String other, int ooffset, int len)
Determines if two string regions are equal.
If toffset or ooffset is negative, or if toffset+length is greater than the length of this string, or if ooffset+length is greater than the length of the string argument, then this
method returns false.
Parameters:
ignoreCase - if true, ignore case when comparing characters
toffset - starting offset of the subregion in this string
other - string argument
ooffset - starting offset of the subregion in the string argument
len - the number of characters to compare
Returns:
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.

regionMatches

public boolean
regionMatches(int toffset, String other,
int ooffset, int len)
Determines if two string regions are equal.
If toffset or ooffset is negative, or if toffset+length is greater than the length of this string, or if ooffset+length is greater than the length of the string argument, then this method returns false.
Parameters:
toffset - starting offset of the subregion in this string
other - string argument
ooffset - starting offset of the subregion in the string argument
len - the number of characters to compare
Returns:
true if the specified subregion of this string exactly matches the specified subregion of the string argument; false otherwise.

replace

public String replace(char oldChar, char newChar)
Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar.
If the character oldChar does not occur in the character sequence represented by this object, then this string is returned.
Parameters:
oldChar - the old character
newChar - the new character
Returns:
a string derived from this string by replacing every occurrence of oldChar with newChar.

startsWith

public boolean startsWith(String prefix)
Parameters:
prefix - the prefix
Returns:
true if the character sequence represented by the argument is a prefix of the character sequence represented by this string; false otherwise

startsWith

public boolean startsWith(String prefix, int toffset)
Parameters:
prefix - the prefix
toffset - where to begin looking in the the String
Returns:
true if the character sequence represented by the argument is a prefix of the substring of this object starting at index toffset; false otherwise

substring

public String substring(int beginIndex)
Creates a new string that is a substring of this string. The substring begins at the specified index and extends to the end of this string.
Parameters:
beginIndex - the beginning index, inclusive
Returns:
the specified substring.
Throws
StringIndexOutOfBoundsException (I-§1.44)
If the beginIndex is out of range.

substring

public String substring(int beginIndex, int endIndex)
Creates a new string that is a substring of this string. The substring begins at the specified beginIndex and extends to the character at index endIndex - 1.
Parameters:
beginIndex - the beginning index, inclusive
endIndex - the ending index, exclusive
Returns:
the specified substring.
Throws
StringIndexOutOfBoundsException (I-§1.44)
If the beginIndex or the endIndex is out of range.

toCharArray

public char[] toCharArray()
Returns:
A newly allocated character array whose length is the length of this string and whose contents is initialized to contain the character sequence represented by this string.

toLowerCase

public String toLowerCase()
Converts a string to lowercase.
If no character in this string has a different lowercase version (I-§1.2.21), then this string is returned.


Otherwise, a new string is allocated, whose length is identical to this string, and such that each character which has a difference lowercase version is mapped to this lower case equivalent.
Returns:
the string, converted to lowercase.

toString

public String toString()
This object (which is already a string!) is itself returned.
Returns:
the string itself.
Overrides:
toString in class Object (I-§1.12.9).

toUpperCase

public String toUpperCase()
Converts a string to uppercase.
If no character in this string has a different uppercase version (I-§1.2.24), then this string is returned.


Otherwise, a new string is allocated, whose length is identical to this string, and such that each character which has a difference uppercase version is mapped to this uppercase equivalent.
Returns:
the string, converted to uppercase.

trim

public String trim()
Removes white space from both ends of a string.
All characters that have codes less than or equal to '\u0020' (the space character) are considered to be white space.
Returns:
this string, with whitespace removed from the front and end

valueOf

public static String valueOf(boolean b)
Creates the string representation of the boolean argument.
Parameters:
b - a boolean
Returns:
if the argument is true, a string equal to "true" is returned; otherwise, a string equal to "false" is returned.

valueOf

public static String valueOf(char c)
Creates the string representation of the char argument.
Parameters:
c - a char
Returns:
a newly allocated string of length one containing as its single characer the argument c.

valueOf

public static String valueOf(char data[])
Creates the string representation of the char array argument.
Parameters:
data - a char array
Returns:
a newly allocated string representing the same sequence of characters contained in the character array argument.

valueOf

public static String
valueOf(char data[], int offset, int count)
Creates the string representation of a specific subarray of the 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.
Parameters:
data - the character array
offset - the initial offset into the value of the String
count - the length of the value of the String
Returns:
a newly allocated string representing the sequence of characters contained in the subarray of the character array argument.

valueOf

public static String valueOf(double d)
Creates the string representation of the double argument.
The representation is exactly the one returned by the Double-.toString method of one argument (I-§1.6.21).

Parameters:
d - a double
Returns:
a newly allocated string containing a string representation of the double argument.

valueOf

public static String valueOf(float f)
Creates the string representation of the float argument.
The representation is exactly the one returned by the Float.toString method of one argument (I-§1.7.22).

Parameters:
f - a float
Returns:
a newly allocated string containing a string representation of the float argument.

valueOf

public static String valueOf(int i)
Creates the string representation of the int argument.
The representation is exactly the one returned by the Integer.toString method of one argument (I-§1.8.20).

Parameters:
i - an int
Returns:
a newly allocated string containing a string representation of the int argument.

valueOf

public static String valueOf(long l)
Creates the string representation of a the long argument.
The representation is exactly the one returned by the Long.toString method of one argument (I-§1.9.20).

Parameters:
l - a long
Returns:
a newly allocated string containing a string representation of the long argument.

valueOf

public static String valueOf(Object obj)
Creates the string representation of the Object argument.
Parameters:
obj - an Object.
Returns:
If the argument is null, then a string equal to "null"; otherwise the value of obj.toString() is returned.
See Also:
toString in class Object (I-§1.12.9).

Packages  This Package  Prev  Next  Index
Java API Document (HTML generated by dkramer on April 22, 1996)
Copyright © 1996 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to doug.kramer@sun.com