StringBuffer (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.lang
Class StringBuffer

    java.lang.Object
      |
      +--java.lang.StringBuffer

All Implemented Interfaces:
  CharSequence, Serializable

public final class StringBuffer
extends Object
implements Serializable, CharSequence

A string buffer implements a mutable sequence of characters. A string buffer is like a `String`, but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls.

String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved.

String buffers are used by the compiler to implement the binary string concatenation operator `+`. For example, the code:

>          x = "a" + 4 + "c"

is compiled to the equivalent of:

>          x = new StringBuffer().append("a").append(4).append("c")
>                                .toString()

which creates a new string buffer (initially empty), appends the string representation of each operand to the string buffer in turn, and then converts the contents of the string buffer to a string. Overall, this avoids creating many temporary strings.

The principal operations on a `StringBuffer` are the `append` and `insert` methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string buffer. The `append` method always adds these characters at the end of the buffer; the `insert` method adds the characters at a specified point.

For example, if `z` refers to a string buffer object whose current contents are "`start`", then the method call `z.append("le")` would cause the string buffer to contain "`startle`", whereas `z.insert(4, "le")` would alter the string buffer to contain "`starlet`".

In general, if sb refers to an instance of a `StringBuffer`, then `sb.append(x)` has the same effect as `sb.insert(sb.length(), x)`.

Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to allocate a new internal buffer array. If the internal buffer overflows, it is automatically made larger.

Since:
  JDK1.0
See Also:
  `ByteArrayOutputStream`, `String`, Serialized Form

Constructor Summary
`StringBuffer()` Constructs a string buffer with no characters in it and an initial capacity of 16 characters.
`StringBuffer(int length)` Constructs a string buffer with no characters in it and an initial capacity specified by the `length` argument.
`StringBuffer(String str)` Constructs a string buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string buffer is a copy of the argument string.

Method Summary
`StringBuffer` | `append(boolean b)` Appends the string representation of the `boolean` argument to the string buffer.
`StringBuffer` | `append(char c)` Appends the string representation of the `char` argument to this string buffer.
`StringBuffer` | `append(char[] str)` Appends the string representation of the `char` array argument to this string buffer.
`StringBuffer` | `append(char[] str, int offset, int len)` Appends the string representation of a subarray of the `char` array argument to this string buffer.
`StringBuffer` | `append(double d)` Appends the string representation of the `double` argument to this string buffer.
`StringBuffer` | `append(float f)` Appends the string representation of the `float` argument to this string buffer.
`StringBuffer` | `append(int i)` Appends the string representation of the `int` argument to this string buffer.
`StringBuffer` | `append(long l)` Appends the string representation of the `long` argument to this string buffer.
`StringBuffer` | `append(Object obj)` Appends the string representation of the `Object` argument to this string buffer.
`StringBuffer` | `append(String str)` Appends the string to this string buffer.
`StringBuffer` | `append(StringBuffer sb)` Appends the specified `StringBuffer` to this `StringBuffer`.
`int` | `capacity()` Returns the current capacity of the String buffer.
`char` | `charAt(int index)` The specified character of the sequence currently represented by the string buffer, as indicated by the `index` argument, is returned.
`StringBuffer` | `delete(int start, int end)` Removes the characters in a substring of this `StringBuffer`.
`StringBuffer` | `deleteCharAt(int index)` Removes the character at the specified position in this `StringBuffer` (shortening the `StringBuffer` by one character).
`void` | `ensureCapacity(int minimumCapacity)` Ensures that the capacity of the buffer is at least equal to the specified minimum.
`void` | `getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)` Characters are copied from this string buffer into the destination character array `dst`.
`int` | `indexOf(String str)` Returns the index within this string of the first occurrence of the specified substring.
`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.
`StringBuffer` | `insert(int offset, boolean b)` Inserts the string representation of the `boolean` argument into this string buffer.
`StringBuffer` | `insert(int offset, char c)` Inserts the string representation of the `char` argument into this string buffer.
`StringBuffer` | `insert(int offset, char[] str)` Inserts the string representation of the `char` array argument into this string buffer.
`StringBuffer` | `insert(int index, char[] str, int offset, int len)` Inserts the string representation of a subarray of the `str` array argument into this string buffer.
`StringBuffer` | `insert(int offset, double d)` Inserts the string representation of the `double` argument into this string buffer.
`StringBuffer` | `insert(int offset, float f)` Inserts the string representation of the `float` argument into this string buffer.
`StringBuffer` | `insert(int offset, int i)` Inserts the string representation of the second `int` argument into this string buffer.
`StringBuffer` | `insert(int offset, long l)` Inserts the string representation of the `long` argument into this string buffer.
`StringBuffer` | `insert(int offset, Object obj)` Inserts the string representation of the `Object` argument into this string buffer.
`StringBuffer` | `insert(int offset, String str)` Inserts the string into this string buffer.
`int` | `lastIndexOf(String str)` Returns the index within this string of the rightmost occurrence of the specified substring.
`int` | `lastIndexOf(String str, int fromIndex)` Returns the index within this string of the last occurrence of the specified substring.
`int` | `length()` Returns the length (character count) of this string buffer.
`StringBuffer` | `replace(int start, int end, String str)` Replaces the characters in a substring of this `StringBuffer` with characters in the specified `String`.
`StringBuffer` | `reverse()` The character sequence contained in this string buffer is replaced by the reverse of the sequence.
`void` | `setCharAt(int index, char ch)` The character at the specified index of this string buffer is set to `ch`.
`void` | `setLength(int newLength)` Sets the length of this String buffer.
`CharSequence` | `subSequence(int start, int end)` Returns a new character sequence that is a subsequence of this sequence.
`String` | `substring(int start)` Returns a new `String` that contains a subsequence of characters currently contained in this `StringBuffer`.The substring begins at the specified index and extends to the end of the `StringBuffer`.
`String` | `substring(int start, int end)` Returns a new `String` that contains a subsequence of characters currently contained in this `StringBuffer`.
`String` | `toString()` Converts to a string representing the data in this string buffer.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### StringBuffer

    public StringBuffer()

  Constructs a string buffer with no characters in it and an initial capacity of 16 characters.

### StringBuffer

    public StringBuffer(int length)

  Constructs a string buffer with no characters in it and an initial capacity specified by the `length` argument.

Parameters:
  `length` - the initial capacity.
Throws:
  `NegativeArraySizeException` - if the `length` argument is less than `0`.

### StringBuffer

    public StringBuffer(String str)

  Constructs a string buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is `16` plus the length of the string argument.

Parameters:
  `str` - the initial contents of the buffer.
Throws:
  `NullPointerException` - if `str` is `null`

Method Detail

### length

    public int length()

  Returns the length (character count) of this string buffer.

  Specified by:
    `length` in interface `CharSequence`
  Returns:
    the length of the sequence of characters currently represented by this string buffer.

### capacity

    public int capacity()

  Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur.

  Returns:
    the current capacity of this string buffer.

### ensureCapacity

    public void ensureCapacity(int minimumCapacity)

  Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of:
  - The `minimumCapacity` argument.
  - Twice the old capacity, plus `2`.
  If the `minimumCapacity` argument is nonpositive, this method takes no action and simply returns.

  Parameters:
    `minimumCapacity` - the minimum desired capacity.

### setLength

    public void setLength(int newLength)

  Sets the length of this String buffer. This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index k less than `newLength`, the character at index k in the new character sequence is the same as the character at index k in the old sequence if k is less than the length of the old character sequence; otherwise, it is the null character `'\u0000'`. In other words, if the `newLength` argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the `newLength` argument.

  If the `newLength` argument is greater than or equal to the current length, sufficient null characters (`'\u0000'`) are appended to the string buffer so that length becomes the `newLength` argument.

  The `newLength` argument must be greater than or equal to `0`.

  Parameters:
    `newLength` - the new length of the buffer.
  Throws:
    `IndexOutOfBoundsException` - if the `newLength` argument is negative.
  See Also:
    `length()`

### charAt

    public char charAt(int index)

  The specified character of the sequence currently represented by the string buffer, as indicated by the `index` argument, is returned. The first character of a string buffer is at index `0`, the next at index `1`, and so on, for array indexing.

  The index argument must be greater than or equal to `0`, and less than the length of this string buffer.

  Specified by:
    `charAt` in interface `CharSequence`
  Parameters:
    `index` - the index of the desired character.
  Returns:
    the character at the specified index of this string buffer.
  Throws:
    `IndexOutOfBoundsException` - if `index` is negative or greater than or equal to `length()`.
  See Also:
    `length()`

### getChars

    public void getChars(int srcBegin,
                         int srcEnd,
                         char[] dst,
                         int dstBegin)

  Characters are copied from this string buffer into the destination character array `dst`. 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 are copied into the subarray of `dst` starting at index `dstBegin` and ending at index:

  >      dstbegin + (srcEnd-srcBegin) - 1

  Parameters:
    `srcBegin` - start copying at this offset in the string buffer.
    `srcEnd` - stop copying at this offset in the string buffer.
    `dst` - the array to copy the data into.
    `dstBegin` - offset into `dst`.
  Throws:
    `NullPointerException` - if `dst` is `null`.
    `IndexOutOfBoundsException` - if any of the following is true:
    - `srcBegin` is negative
    - `dstBegin` is negative
    - the `srcBegin` argument is greater than the `srcEnd` argument.
    - `srcEnd` is greater than `this.length()`, the current length of this string buffer.
    - `dstBegin+srcEnd-srcBegin` is greater than `dst.length`

### setCharAt

    public void setCharAt(int index,
                          char ch)

  The character at the specified index of this string buffer is set to `ch`. The string buffer is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character `ch` at position `index`.

  The index argument must be greater than or equal to `0`, and less than the length of this string buffer.

  Parameters:
    `index` - the index of the character to modify.
    `ch` - the new character.
  Throws:
    `IndexOutOfBoundsException` - if `index` is negative or greater than or equal to `length()`.
  See Also:
    `length()`

### append

    public StringBuffer append(Object obj)

  Appends the string representation of the `Object` argument to this string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `obj` - an `Object`.
  Returns:
    a reference to this `StringBuffer` object.
  See Also:
    `String.valueOf(java.lang.Object)`, `append(java.lang.String)`

### append

    public StringBuffer append(String str)

  Appends the string to this string buffer.

  The characters of the `String` argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. If `str` is `null`, then the four characters `"null"` are appended to this string buffer.

  Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the `append` method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument `str`.

  Parameters:
    `str` - a string.
  Returns:
    a reference to this `StringBuffer`.

### append

    public StringBuffer append(StringBuffer sb)

  Appends the specified `StringBuffer` to this `StringBuffer`.

  The characters of the `StringBuffer` argument are appended, in order, to the contents of this `StringBuffer`, increasing the length of this `StringBuffer` by the length of the argument. If `sb` is `null`, then the four characters `"null"` are appended to this `StringBuffer`.

  Let n be the length of the old character sequence, the one contained in the `StringBuffer` just prior to execution of the `append` method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument `sb`.

  The method `ensureCapacity` is first called on this `StringBuffer` with the new buffer length as its argument. (This ensures that the storage of this `StringBuffer` is adequate to contain the additional characters being appended.)

  Parameters:
    `sb` - the `StringBuffer` to append.
  Returns:
    a reference to this `StringBuffer`.
  Since:
    1.4

### append

    public StringBuffer append(char[] str)

  Appends the string representation of the `char` array argument to this string buffer.

  The characters of the array argument are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the length of the argument.

  The overall effect is exactly as if the argument were converted to a string by the method `String.valueOf(char[])` and the characters of that string were then `appended` to this `StringBuffer` object.

  Parameters:
    `str` - the characters to be appended.
  Returns:
    a reference to this `StringBuffer` object.

### append

    public StringBuffer append(char[] str,
                               int offset,
                               int len)

  Appends the string representation of a subarray of the `char` array argument to this string buffer.

  Characters of the character array `str`, starting at index `offset`, are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of `len`.

  The overall effect is exactly as if the arguments were converted to a string by the method `String.valueOf(char[],int,int)` and the characters of that string were then `appended` to this `StringBuffer` object.

  Parameters:
    `str` - the characters to be appended.
    `offset` - the index of the first character to append.
    `len` - the number of characters to append.
  Returns:
    a reference to this `StringBuffer` object.

### append

    public StringBuffer append(boolean b)

  Appends the string representation of the `boolean` argument to the string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `b` - a `boolean`.
  Returns:
    a reference to this `StringBuffer`.
  See Also:
    `String.valueOf(boolean)`, `append(java.lang.String)`

### append

    public StringBuffer append(char c)

  Appends the string representation of the `char` argument to this string buffer.

  The argument is appended to the contents of this string buffer. The length of this string buffer increases by `1`.

  The overall effect is exactly as if the argument were converted to a string by the method `String.valueOf(char)` and the character in that string were then `appended` to this `StringBuffer` object.

  Parameters:
    `c` - a `char`.
  Returns:
    a reference to this `StringBuffer` object.

### append

    public StringBuffer append(int i)

  Appends the string representation of the `int` argument to this string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `i` - an `int`.
  Returns:
    a reference to this `StringBuffer` object.
  See Also:
    `String.valueOf(int)`, `append(java.lang.String)`

### append

    public StringBuffer append(long l)

  Appends the string representation of the `long` argument to this string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `l` - a `long`.
  Returns:
    a reference to this `StringBuffer` object.
  See Also:
    `String.valueOf(long)`, `append(java.lang.String)`

### append

    public StringBuffer append(float f)

  Appends the string representation of the `float` argument to this string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `f` - a `float`.
  Returns:
    a reference to this `StringBuffer` object.
  See Also:
    `String.valueOf(float)`, `append(java.lang.String)`

### append

    public StringBuffer append(double d)

  Appends the string representation of the `double` argument to this string buffer.

  The argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then appended to this string buffer.

  Parameters:
    `d` - a `double`.
  Returns:
    a reference to this `StringBuffer` object.
  See Also:
    `String.valueOf(double)`, `append(java.lang.String)`

### delete

    public StringBuffer delete(int start,
                               int end)

  Removes the characters in a substring of this `StringBuffer`. The substring begins at the specified `start` and extends to the character at index `end - 1` or to the end of the `StringBuffer` if no such character exists. If `start` is equal to `end`, no changes are made.

  Parameters:
    `start` - The beginning index, inclusive.
    `end` - The ending index, exclusive.
  Returns:
    This string buffer.
  Throws:
    `StringIndexOutOfBoundsException` - if `start` is negative, greater than `length()`, or greater than `end`.
  Since:
    1.2

### deleteCharAt

    public StringBuffer deleteCharAt(int index)

  Removes the character at the specified position in this `StringBuffer` (shortening the `StringBuffer` by one character).

  Parameters:
    `index` - Index of character to remove
  Returns:
    This string buffer.
  Throws:
    `StringIndexOutOfBoundsException` - if the `index` is negative or greater than or equal to `length()`.
  Since:
    1.2

### replace

    public StringBuffer replace(int start,
                                int end,
                                String str)

  Replaces the characters in a substring of this `StringBuffer` with characters in the specified `String`. The substring begins at the specified `start` and extends to the character at index `end - 1` or to the end of the `StringBuffer` if no such character exists. First the characters in the substring are removed and then the specified `String` is inserted at `start`. (The `StringBuffer` will be lengthened to accommodate the specified String if necessary.)

  Parameters:
    `start` - The beginning index, inclusive.
    `end` - The ending index, exclusive.
    `str` - String that will replace previous contents.
  Returns:
    This string buffer.
  Throws:
    `StringIndexOutOfBoundsException` - if `start` is negative, greater than `length()`, or greater than `end`.
  Since:
    1.2

### substring

    public String substring(int start)

  Returns a new `String` that contains a subsequence of characters currently contained in this `StringBuffer`.The substring begins at the specified index and extends to the end of the `StringBuffer`.

  Parameters:
    `start` - The beginning index, inclusive.
  Returns:
    The new string.
  Throws:
    `StringIndexOutOfBoundsException` - if `start` is less than zero, or greater than the length of this `StringBuffer`.
  Since:
    1.2

### subSequence

    public CharSequence subSequence(int start,
                                    int end)

  Returns a new character sequence that is a subsequence of this sequence.

  An invocation of this method of the form

  >      sb.subSequence(begin, end)

  behaves in exactly the same way as the invocation

  >      sb.substring(begin, end)

  This method is provided so that the `StringBuffer` class can implement the `CharSequence` interface.

  Specified by:
    `subSequence` in interface `CharSequence`
  Parameters:
    `start` - the start index, inclusive.
    `end` - the end index, exclusive.
  Returns:
    the specified subsequence.
  Throws:
    `IndexOutOfBoundsException` - if `start` or `end` are negative, if `end` is greater than `length()`, or if `start` is greater than `end`
  Since:
    1.4

### substring

    public String substring(int start,
                            int end)

  Returns a new `String` that contains a subsequence of characters currently contained in this `StringBuffer`. The substring begins at the specified `start` and extends to the character at index `end - 1`. An exception is thrown if

  Parameters:
    `start` - The beginning index, inclusive.
    `end` - The ending index, exclusive.
  Returns:
    The new string.
  Throws:
    `StringIndexOutOfBoundsException` - if `start` or `end` are negative or greater than `length()`, or `start` is greater than `end`.
  Since:
    1.2

### insert

    public StringBuffer insert(int index,
                               char[] str,
                               int offset,
                               int len)

  Inserts the string representation of a subarray of the `str` array argument into this string buffer. The subarray begins at the specified `offset` and extends `len` characters. The characters of the subarray are inserted into this string buffer at the position indicated by `index`. The length of this `StringBuffer` increases by `len` characters.

  Parameters:
    `index` - position at which to insert subarray.
    `str` - A character array.
    `offset` - the index of the first character in subarray to to be inserted.
    `len` - the number of characters in the subarray to to be inserted.
  Returns:
    This string buffer.
  Throws:
    `StringIndexOutOfBoundsException` - if `index` is negative or greater than `length()`, or `offset` or `len` are negative, or `(offset+len)` is greater than `str.length`.
  Since:
    1.2

### insert

    public StringBuffer insert(int offset,
                               Object obj)

  Inserts the string representation of the `Object` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the indicated offset.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `obj` - an `Object`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(java.lang.Object)`, `insert(int, java.lang.String)`, `length()`

### insert

    public StringBuffer insert(int offset,
                               String str)

  Inserts the string into this string buffer.

  The characters of the `String` argument are inserted, in order, into this string buffer at the indicated offset, moving up any characters originally above that position and increasing the length of this string buffer by the length of the argument. If `str` is `null`, then the four characters `"null"` are inserted into this string buffer.

  The character at index k in the new character sequence is equal to:

  - the character at index k in the old character sequence, if k is less than `offset`
  - the character at index k`-offset` in the argument `str`, if k is not less than `offset` but is less than `offset+str.length()`
  - the character at index k`-str.length()` in the old character sequence, if k is not less than `offset+str.length()`

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `str` - a string.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `length()`

### insert

    public StringBuffer insert(int offset,
                               char[] str)

  Inserts the string representation of the `char` array argument into this string buffer.

  The characters of the array argument are inserted into the contents of this string buffer at the position indicated by `offset`. The length of this string buffer increases by the length of the argument.

  The overall effect is exactly as if the argument were converted to a string by the method `String.valueOf(char[])` and the characters of that string were then `inserted` into this `StringBuffer` object at the position indicated by `offset`.

  Parameters:
    `offset` - the offset.
    `str` - a character array.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.

### insert

    public StringBuffer insert(int offset,
                               boolean b)

  Inserts the string representation of the `boolean` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the indicated offset.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `b` - a `boolean`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(boolean)`, `insert(int, java.lang.String)`, `length()`

### insert

    public StringBuffer insert(int offset,
                               char c)

  Inserts the string representation of the `char` argument into this string buffer.

  The second argument is inserted into the contents of this string buffer at the position indicated by `offset`. The length of this string buffer increases by one.

  The overall effect is exactly as if the argument were converted to a string by the method `String.valueOf(char)` and the character in that string were then `inserted` into this `StringBuffer` object at the position indicated by `offset`.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `c` - a `char`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `IndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `length()`

### insert

    public StringBuffer insert(int offset,
                               int i)

  Inserts the string representation of the second `int` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the indicated offset.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `i` - an `int`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(int)`, `insert(int, java.lang.String)`, `length()`

### insert

    public StringBuffer insert(int offset,
                               long l)

  Inserts the string representation of the `long` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the position indicated by `offset`.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `l` - a `long`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(long)`, `insert(int, java.lang.String)`, `length()`

### insert

    public StringBuffer insert(int offset,
                               float f)

  Inserts the string representation of the `float` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the indicated offset.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `f` - a `float`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(float)`, `insert(int, java.lang.String)`, `length()`

### insert

    public StringBuffer insert(int offset,
                               double d)

  Inserts the string representation of the `double` argument into this string buffer.

  The second argument is converted to a string as if by the method `String.valueOf`, and the characters of that string are then inserted into this string buffer at the indicated offset.

  The offset argument must be greater than or equal to `0`, and less than or equal to the length of this string buffer.

  Parameters:
    `offset` - the offset.
    `d` - a `double`.
  Returns:
    a reference to this `StringBuffer` object.
  Throws:
    `StringIndexOutOfBoundsException` - if the offset is invalid.
  See Also:
    `String.valueOf(double)`, `insert(int, java.lang.String)`, `length()`

### indexOf

    public int indexOf(String str)

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

  >      this.toString().startsWith(str, k)

  is `true`.

  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.
  Throws:
    `NullPointerException` - if `str` is `null`.
  Since:
    1.4

### 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` for which:

  >          k >= Math.min(fromIndex, str.length()) &&
  >                        this.toString().startsWith(str, k)

  If no such value of k exists, then -1 is returned.

  Parameters:
    `str` - the substring for which to search.
    `fromIndex` - the index from which to start the search.
  Returns:
    the index within this string of the first occurrence of the specified substring, starting at the specified index.
  Throws:
    `NullPointerException` - if `str` is `null`.
  Since:
    1.4

### lastIndexOf

    public int lastIndexOf(String str)

  Returns the index within this string of the rightmost occurrence of the specified substring. The rightmost empty string "" is considered to occur at the index value `this.length()`. The returned index is the largest value k such that

  >      this.toString().startsWith(str, k)

  is true.

  Parameters:
    `str` - the substring to search for.
  Returns:
    if the string argument occurs one or more times 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.
  Throws:
    `NullPointerException` - if `str` is `null`.
  Since:
    1.4

### lastIndexOf

    public int lastIndexOf(String str,
                           int fromIndex)

  Returns the index within this string of the last occurrence of the specified substring. The integer returned is the largest value k such that:

  >          k <= Math.min(fromIndex, str.length()) &&
  >                        this.toString().startsWith(str, k)

  If no such value of k exists, then -1 is returned.

  Parameters:
    `str` - the substring to search for.
    `fromIndex` - the index to start the search from.
  Returns:
    the index within this string of the last occurrence of the specified substring.
  Throws:
    `NullPointerException` - if `str` is `null`.
  Since:
    1.4

### reverse

    public StringBuffer reverse()

  The character sequence contained in this string buffer is replaced by the reverse of the sequence.

  Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the `reverse` method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence.

  Returns:
    a reference to this `StringBuffer` object.
  Since:
    JDK1.0.2

### toString

    public String toString()

  Converts to a string representing the data in this string buffer. A new `String` object is allocated and initialized to contain the character sequence currently represented by this string buffer. This `String` is then returned. Subsequent changes to the string buffer do not affect the contents of the `String`.

  Implementation advice: This method can be coded so as to create a new `String` object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string buffer. Any subsequent operation that alters the content or capacity of the string buffer must then make a copy of the internal buffer at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation when it is implemented using a string buffer.

  Specified by:
    `toString` in interface `CharSequence`
  Overrides:
    `toString` in class `Object`
  Returns:
    a string representation of the string buffer.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.