Overview | Package | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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)`

Overview | Package | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD