java.lang
Class String

java.lang.Object
  java.lang.String

public class String
extends Object

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 support mutable strings. Because String objects are immutable they can be shared. For example:

     String str = "abc";
 

is equivalent to:

     byte data[] = {(byte)'a', (byte)'b', (byte)'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".concat(cde));
 

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.

The Java language provides special support for the string concatentation 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.

Currently on JControl the class StringBuffer is not implemented.

Since:

JDK1.0

Version:

1.121, 10/06/99

Author:

Lee Boynton, Arthur van Hoff, Helge Böhme (JControl version)

Available on JControl Devices:

all

Constructor Summary

String()
Initializes a newly created String object so that it represents an empty character sequence.

String(byte[] bytes)
Construct a new String by converting the specified array of bytes using the platform's default character encoding.

String(byte[] bytes, int offset, int length)
Construct a new String by converting the specified subarray of bytes using the platform's default character encoding.

Method Summary

char	charAt(int index) Returns the character at the specified index.
String	concat(String str) Concatenates the specified string to the end of this string.
boolean	equals(Object anObject) Compares this string to the specified object.
byte[]	getBytes() Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array.
int	indexOf(String str, int fromIndex) Returns the index within this string of the first occurrence of the specified substring, starting at the specified index.
int	length() Returns the length of this string.
String	substring(int beginIndex, int endIndex) Returns a new string that is a substring of this string.
char[]	toCharArray() Converts this string to a new character array.
String	trim() Removes white space from both ends of this string.
static String	valueOf(int i) Returns the string representation of the int argument.

Methods inherited from class java.lang.Object

clone, notifyAll, wait

Constructor Detail

String

public String()

Initializes a newly created String object so that it represents an empty character sequence.

String

public String(byte[] bytes)

Construct a new String by converting the specified array of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array.

Parameters:

bytes - The bytes to be converted into characters

Since:

JDK1.1

String

public String(byte[] bytes,
              int offset,
              int length)

Construct a new String by converting the specified subarray of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray.

Parameters:

bytes - The bytes to be converted into characters

offset - Index of the first byte to convert

length - Number of bytes to convert

Since:

JDK1.1

Method Detail

charAt

public char charAt(int index)

Returns the character at the specified index. An index ranges from 0 to length() - 1. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing.

Parameters:

index - the index of the character.

Returns:

the character at the specified index of this string. The first character is at index 0.

Throws:

java.lang.IndexOutOfBoundsException - if the index argument is negative or not less than the length of this string.

concat

public String concat(String str)

Concatenates the specified string to the end of this string.

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"
 

Parameters:

str - the String that 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.

Throws:

java.lang.NullPointerException - if str is null.

equals

public boolean equals(Object anObject)

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.

Overrides:

equals in class Object

Parameters:

anObject - the object to compare this String against.

Returns:

true if the String are equal; false otherwise.

getBytes

public byte[] getBytes()

Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array.

Returns:

the resultant byte array.

Since:

JDK1.1

indexOf

public int indexOf(String str,
                   int fromIndex)

Returns the index within this string of the first occurrence of the specified substring, starting at the specified index. The integer returned is the smallest value k such that:

 this.startsWith(str, k) && (k >= fromIndex)
 

is true.

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.

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.

Throws:

java.lang.NullPointerException - if str is null

length

public int length()

Returns the length of this string. The length is equal to the number of 16-bit Unicode characters in the string.

Returns:

the length of the sequence of characters represented by this object.

substring

public String substring(int beginIndex,
                        int endIndex)

Returns 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. Thus the length of the substring is endIndex-beginIndex.

Examples:

 "hamburger".substring(4, 8) returns "urge"
 "smiles".substring(1, 5) returns "mile"
 

Parameters:

beginIndex - the beginning index, inclusive.

endIndex - the ending index, exclusive.

Returns:

the specified substring.

Throws:

java.lang.IndexOutOfBoundsException - if the beginIndex is negative, or endIndex is larger than the length of this String object, or beginIndex is larger than endIndex.

toCharArray

public char[] toCharArray()

Converts this string to a new character array.

Returns:

a newly allocated character array whose length is the length of this string and whose contents are initialized to contain the character sequence represented by this string.

trim

public String trim()

Removes white space from both ends of this string.

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 from the beginning and end of a string; in fact, it trims all ASCII control characters as well.

Returns:

this string, with white space removed from the front and end.

valueOf

public static String valueOf(int i)

Returns the string representation of the int argument.

The representation is exactly the one returned by the Integer.toString method of one argument.

Parameters:

i - an int.

Returns:

a newly allocated string containing a string representation of the int argument.

See Also:

Integer.toString(int)