THE PACKAGE JAVA.LANG

java.lang.StringBuffer

20.13

public StringBuffer insert(int offset, char c)

throws IndexOutOfBoundsException;

public StringBuffer insert(int offset, int i)

throws IndexOutOfBoundsException;

public StringBuffer insert(int offset, long l)

throws IndexOutOfBoundsException;

public StringBuffer insert(int offset, float f)

throws IndexOutOfBoundsException;

public StringBuffer insert(int offset, double d)

throws IndexOutOfBoundsException;

public StringBuffer reverse();

}

A 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.

String buffers are safe for use by multiple threads. The methods are synchro 

nized 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 con 

catenation 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 representa 

tion 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)

.

549