java.lang.StringBufferString (§20.12), 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.
public classA 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 create a new internal buffer array.StringBuffer{ publicStringBuffer(); publicStringBuffer(int length)
throws NegativeArraySizeException; publicStringBuffer(String str); public StringtoString(); public intlength(); public voidsetLength(int newLength) throwsIndexOutOfBoundsException; public intcapacity(); public voidensureCapacity(int minimumCapacity); public charcharAt(int index) throwsIndexOutOfBoundsException; public voidsetCharAt(int index, char ch) throwsIndexOutOfBoundsException; public voidgetChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
throws NullPointerException,IndexOutOfBoundsException; public StringBufferappend(Object obj); public StringBufferappend(String str); public StringBufferappend(char[] str) throws NullPointerException; public StringBufferappend(char[] str, int offset, int len) throws NullPointerException,IndexOutOfBoundsException; public StringBufferappend(boolean b); public StringBufferappend(char c); public StringBufferappend(int i); public StringBufferappend(long l); public StringBufferappend(float f); public StringBufferappend(double d); public StringBufferinsert(int offset, Object obj) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, String str) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, char[] str) throws NullPointerException,IndexOutOfBoundsException; public StringBufferinsert(int offset, boolean b) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, char c) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, int i) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, long l) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, float f) throwsIndexOutOfBoundsException; public StringBufferinsert(int offset, double d) throwsIndexOutOfBoundsException; public StringBufferreverse(); }
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 can be used by a compiler to implement the binary string concatenation operator + (§15.17.1). For example, suppose k has type int and a has type Object. Then the expression:
k + "/" + a
can be compiled as if it were the expression:
new StringBuffer().append(k).append("/").
append(a).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 adds the characters of that string to the contents of 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 the characters "start", then the method call z.append("le") would alter the string buffer to contain the characters "startle", but z.insert(4, "le") would alter the string buffer to contain the characters "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).
20.13.1 public
StringBuffer()
This constructor initializes a newly created StringBuffer object so that it initially
represents an empty character sequence and has capacity 16.
20.13.2 public
StringBuffer(int length)
throws NegativeArraySizeException
This constructor initializes a newly created StringBuffer object so that it initially
represents an empty character sequence, but has the capacity specified by
the argument.
If the argument is negative, a NegativeArraySizeException is thrown.
20.13.3 public
StringBuffer(String str)
This constructor initializes a newly created StringBuffer object so that it represents
the same sequence of characters as the 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 argument string.
20.13.4 public String
toString()
A new String object is created and initialized to contain the character sequence
currently represented by the string buffer; the new String is then returned. Any
subsequent changes to the string buffer do not affect the contents of the returned
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 (§15.17.1) when it is implemented using a string buffer.
Overrides the toString method of Object (§20.1.2).
20.13.5 public int
length()
This method returns the length of the sequence of characters currently represented
by this StringBuffer object.
20.13.6 public int
capacity()
The current capacity of this StringBuffer object is returned.
20.13.7 public void
ensureCapacity(int minimumCapacity)
If the current capacity of this StringBuffer object is less than the argument, then
a new internal buffer is created with greater capacity. The new capacity will be the
larger of:
minimumCapacity argument is nonpositive, this method takes no action and simply returns.20.13.8 public void
setLength(int newLength)
throws IndexOutOfBoundsException
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'. This method also calls the
ensureCapacity method (§20.13.7) with argument newLength.
If the argument is negative, an IndexOutOfBoundsException is thrown.
20.13.9 public char
charAt(int index)
throws IndexOutOfBoundsException
The specified character of the sequence currently represented by the string buffer,
as indicated by the index argument, is returned. The first character of the
sequence is at index 0, the next at index 1, and so on, as for array indexing.
If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.
20.13.10 public void
setCharAt(int index, char ch)
throws IndexOutOfBoundsException
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.
If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.
20.13.11 public void
getChars(int srcBegin, int srcEnd,
char[] dst, int dstBegin)
throws NullPointerException,
IndexOutOfBoundsException
Characters are copied from this StringBuffer object into the destination array
dst. 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.
If dst is null, then a NullPointerException is thrown.
Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:
srcBegin argument is negative.
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.
20.13.12 public StringBuffer
append(Object obj)
The argument is converted to a string as if by the method String.valueOf
(§20.12.38) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.13 public StringBuffer
append(String str)
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. The method ensureCapacity (§20.13.7) is first called with this new
string buffer length as its argument. A reference to this StringBuffer object is
returned.
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.
20.13.14 public StringBuffer
append(char[] str)
throws NullPointerException
The characters of the array 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.
The method ensureCapacity (§20.13.7) is first called with this new string
buffer length as its argument. A reference to this StringBuffer object is
returned.
The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.
20.13.15 public StringBuffer
append(char[] str,
int offset, int len)
throws NullPointerException,
IndexOutOfBoundsException
Characters of the character array str, starting at index offset, are appended, in
order, to the contents of this string buffer, increasing the length of this string
buffer by len. The method ensureCapacity (§20.13.7) is first called with this
new string buffer length as its argument. A reference to this StringBuffer object
is returned.
The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf of three arguments (§20.12.40) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.
20.13.16 public StringBuffer
append(boolean b)
The argument is converted to a string as if by the method String.valueOf
(§20.12.41) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.17 public StringBuffer
append(char c)
The argument is appended to the contents of this string buffer, increasing the
length of this string buffer by 1. The method ensureCapacity (§20.13.7) is first
called with this new string buffer length as its argument. A reference to this
StringBuffer object is returned.
The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then appended (§20.13.13) to this StringBuffer object.
20.13.18 public StringBuffer
append(int i)
The argument is converted to a string as if by the method String.valueOf
(§20.12.43) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.19 public StringBuffer
append(long l)
The argument is converted to a string as if by the method String.valueOf
(§20.12.44) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.20 public StringBuffer
append(float f)
The argument is converted to a string as if by the method String.valueOf
(§20.12.45) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.21 public StringBuffer
append(double d)
The argument is converted to a string as if by the method String.valueOf
(§20.12.46) and the characters of that string are then appended (§20.13.13) to this
StringBuffer object. A reference to this StringBuffer object is returned.
20.13.22 public StringBuffer
insert(int offset, Object obj)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.38) and the characters of that string are then inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.23 public StringBuffer
insert(int offset, String str)
throws IndexOutOfBoundsException
The characters of the String argument are inserted, in order, into the string buffer
at the position indicated by offset, moving up any characters originally above
that position and increasing the length of the string buffer by the length of the
argument. If str is null, then the four characters "null" are inserted into this
string buffer. The method ensureCapacity (§20.13.7) is first called with this new
string buffer length as its argument. A reference to this StringBuffer object is
returned.
The character at index k in the new character sequence is equal to:
offset
-offset in the argument str, if k is not less than offset but is less than offset+str.length()
-str.length() in the old character sequence, if k is not less than offset+str.length()
20.13.24 public StringBuffer
insert(int offset, char[] str)
throws NullPointerException,
IndexOutOfBoundsException
The characters of the array argument, taken in order, are inserted into this string
buffer, increasing the length of the string buffer by the length of the argument. The
method ensureCapacity (§20.13.7) is first called with this new string buffer
length as its argument. A reference to this StringBuffer object is returned.
The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.
Note that while the StringBuffer class provides an append method that takes an offset, a character array, and two other arguments (§20.13.15), it does not currently provide an insert method that takes an offset, a character array, and two other arguments.
20.13.25 public StringBuffer
insert(int offset, boolean b)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.41) and the characters of that string are then inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.26 public StringBuffer
insert(int offset, char c)
throws IndexOutOfBoundsException
The argument is inserted into the contents of this string buffer at the position indicated
by offset, increasing the length of this string buffer by 1. The method
ensureCapacity (§20.13.7) is first called with this new string buffer length as its
argument. A reference to this StringBuffer object is returned.
The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.
20.13.27 public StringBuffer
insert(int offset, int i)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.43) and the characters of that string are then inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.28 public StringBuffer
insert(int offset, long l)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.44) and the characters of that string are inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.29 public StringBuffer
insert(int offset, float f)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.45) and the characters of that string are then inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.30 public StringBuffer
insert(int offset, double d)
throws IndexOutOfBoundsException
The argument is converted to a string as if by the method String.valueOf
(§20.12.46) and the characters of that string are then inserted (§20.13.23) into this
StringBuffer object at the position indicated by offset. A reference to this
StringBuffer object is returned.
20.13.31 public StringBuffer
reverse()
The character sequence contained in this StringBuffer object is replaced by the
reverse of that sequence. A reference to this StringBuffer object is returned.
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.
Contents | Prev | Next | Index
Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc.
All rights reserved
Please send any comments or corrections to doug.kramer@sun.com