java.lang.StringBuffer Class Reference

Public Member Functions
	StringBuffer ()
	StringBuffer (int capacity)
	StringBuffer (String string)
StringBuffer	append (boolean b)
synchronized StringBuffer	append (char ch)
StringBuffer	append (double d)
StringBuffer	append (float f)
StringBuffer	append (int i)
StringBuffer	append (long l)
synchronized StringBuffer	append (Object obj)
synchronized StringBuffer	append (String string)
synchronized StringBuffer	append (StringBuffer sb)
synchronized StringBuffer	append (char[] chars)
synchronized StringBuffer	append (char[] chars, int start, int length)
int	capacity ()
char	charAt (int index)
synchronized StringBuffer	delete (int start, int end)
synchronized StringBuffer	deleteCharAt (int location)
synchronized void	ensureCapacity (int min)
synchronized void	getChars (int start, int end, char[] buffer, int idx)
synchronized int	indexOf (String subString, int start)
synchronized StringBuffer	insert (int index, char ch)
StringBuffer	insert (int index, boolean b)
StringBuffer	insert (int index, int i)
StringBuffer	insert (int index, long l)
StringBuffer	insert (int index, double d)
StringBuffer	insert (int index, float f)
StringBuffer	insert (int index, Object obj)
synchronized StringBuffer	insert (int index, String string)
synchronized StringBuffer	insert (int index, char[] chars)
synchronized StringBuffer	insert (int index, char[] chars, int start, int length)
int	lastIndexOf (String string)
synchronized int	lastIndexOf (String subString, int start)
int	length ()
synchronized StringBuffer	replace (int start, int end, String string)
synchronized StringBuffer	reverse ()
synchronized void	setCharAt (int index, char ch)
synchronized void	setLength (int length)
synchronized String	substring (int start)
synchronized String	substring (int start, int end)
synchronized String	toString ()

Detailed Description

A modifiable sequence of characters for use in creating strings, where all accesses are synchronized. This class has mostly been replaced by StringBuilder because this synchronization is rarely useful. This class is mainly used to interact with legacy APIs that expose it.

For particularly complex string-building needs, consider java.util.Formatter.

The majority of the modification methods on this class return

this 

so that method calls can be chained together. For example:

new StringBuffer("a").append("b").append("c").toString() 

.

See also

CharSequence

Appendable

StringBuilder

String

String::format

Since

1.0

Constructor & Destructor Documentation

StringBuffer() [1/3]

java.lang.StringBuffer.StringBuffer ( )

inline

Constructs a new StringBuffer using the default capacity which is 16.

StringBuffer() [2/3]

java.lang.StringBuffer.StringBuffer ( int  capacity )

inline

Constructs a new StringBuffer using the specified capacity.

Parameters

capacity

the initial capacity.

StringBuffer() [3/3]

java.lang.StringBuffer.StringBuffer ( String  string )

inline

Constructs a new StringBuffer containing the characters in the specified string. The capacity of the new buffer will be the length of the

String 

plus the default capacity.

Parameters

string

the string content with which to initialize the new instance.

Exceptions

NullPointerException

if string is null .

Member Function Documentation

append() [1/11]

StringBuffer java.lang.StringBuffer.append ( boolean  b )

inline

Adds the string representation of the specified boolean to the end of this StringBuffer.

If the argument is

true 

the string

"true" 

is appended, otherwise the string

"false" 

is appended.

Parameters

b	the boolean to append.

Returns

this StringBuffer.

See also

String::valueOf(boolean)

append() [2/11]

synchronized StringBuffer java.lang.StringBuffer.append ( char  ch )

inline

Adds the specified character to the end of this buffer.

Parameters

ch	the character to append.

Returns

this StringBuffer.

See also

String::valueOf(char)

append() [3/11]

StringBuffer java.lang.StringBuffer.append ( double  d )

inline

Adds the string representation of the specified double to the end of this StringBuffer.

Parameters

d	the double to append.

Returns

this StringBuffer.

See also

String::valueOf(double)

append() [4/11]

StringBuffer java.lang.StringBuffer.append ( float  f )

inline

Adds the string representation of the specified float to the end of this StringBuffer.

Parameters

f	the float to append.

Returns

this StringBuffer.

See also

String::valueOf(float)

append() [5/11]

StringBuffer java.lang.StringBuffer.append ( int  i )

inline

Adds the string representation of the specified integer to the end of this StringBuffer.

Parameters

i	the integer to append.

Returns

this StringBuffer.

See also

String::valueOf(int)

append() [6/11]

StringBuffer java.lang.StringBuffer.append ( long  l )

inline

Adds the string representation of the specified long to the end of this StringBuffer.

Parameters

l	the long to append.

Returns

this StringBuffer.

See also

String::valueOf(long)

append() [7/11]

synchronized StringBuffer java.lang.StringBuffer.append ( Object  obj )

inline

Adds the string representation of the specified object to the end of this StringBuffer.

If the specified object is

null 

the string

"null" 

is appended, otherwise the objects

toString 

is used to get its string representation.

Parameters

obj	the object to append (may be null).

Returns

this StringBuffer.

See also

String::valueOf(Object)

append() [8/11]

synchronized StringBuffer java.lang.StringBuffer.append ( String  string )

inline

Adds the specified string to the end of this buffer.

If the specified string is

null 

the string

"null" 

is appended, otherwise the contents of the specified string is appended.

Parameters

string

the string to append (may be null).

Returns

this StringBuffer.

append() [9/11]

synchronized StringBuffer java.lang.StringBuffer.append ( StringBuffer  sb )

inline

Adds the specified StringBuffer to the end of this buffer.

If the specified StringBuffer is

null 

the string

"null" 

is appended, otherwise the contents of the specified StringBuffer is appended.

Parameters

sb	the StringBuffer to append (may be null).

Returns

this StringBuffer.

Since

1.4

append() [10/11]

synchronized StringBuffer java.lang.StringBuffer.append ( char []  chars )

inline

Adds the character array to the end of this buffer.

Parameters

chars

the character array to append.

Returns

this StringBuffer.

Exceptions

NullPointerException

if chars is null .

append() [11/11]

synchronized StringBuffer java.lang.StringBuffer.append ( char []  chars, int  start, int  length  )

inline

Adds the specified sequence of characters to the end of this buffer.

Parameters

chars	the character array to append.
start	the starting offset.
length	the number of characters.

Returns

this StringBuffer.

Exceptions

ArrayIndexOutOfBoundsException	if length < 0 , start < 0 or start + length > chars.length .
NullPointerException	if chars is null .

capacity()

int java.lang.StringBuffer.capacity ( )

inline

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.

charAt()

char java.lang.StringBuffer.charAt ( int  index )

inline

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.

Parameters

index

the index of the desired character.

Returns

the character at the specified index of this string buffer.

Exceptions

IndexOutOfBoundsException

if index is negative or greater than or equal to length().

See also

java.lang.StringBuffer::length()

delete()

synchronized StringBuffer java.lang.StringBuffer.delete ( int  start, int  end  )

inline

Deletes a range of characters.

Parameters

start	the offset of the first character.
end	the offset one past the last character.

Returns

this StringBuffer.

Exceptions

StringIndexOutOfBoundsException

if start < 0 , start > end or end > length() .

deleteCharAt()

synchronized StringBuffer java.lang.StringBuffer.deleteCharAt ( int  location )

inline

Deletes the character at the specified offset.

Parameters

location

the offset of the character to delete.

Returns

this StringBuffer.

Exceptions

StringIndexOutOfBoundsException

if location < 0 or location >= length()

ensureCapacity()

synchronized void java.lang.StringBuffer.ensureCapacity ( int  min )

inline

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.

getChars()

synchronized void java.lang.StringBuffer.getChars ( int  start, int  end, char []  buffer, int  idx  )

inline

Copies the requested sequence of characters to the

char[] 

passed starting at

idx 

.

Parameters

start	the starting offset of characters to copy.
end	the ending offset of characters to copy.
buffer	the destination character array.
idx	the starting offset in the character array.

Exceptions

IndexOutOfBoundsException

if start < 0 , end > length() , start > end , index < 0 , end - start > buffer.length - index

indexOf()

synchronized int java.lang.StringBuffer.indexOf ( String  subString, int  start  )

inline

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.

Exceptions

java.lang.NullPointerException

if str is null.

Since

1.4

insert() [1/10]

synchronized StringBuffer java.lang.StringBuffer.insert ( int  index, char  ch  )

inline

Inserts the character into this buffer at the specified offset.

Parameters

index	the index at which to insert.
ch	the character to insert.

Returns

this buffer.

Exceptions

ArrayIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [2/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, boolean  b  )

inline

Inserts the string representation of the specified boolean into this buffer at the specified offset.

Parameters

index	the index at which to insert.
b	the boolean to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [3/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, int  i  )

inline

Inserts the string representation of the specified integer into this buffer at the specified offset.

Parameters

index	the index at which to insert.
i	the integer to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [4/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, long  l  )

inline

Inserts the string representation of the specified long into this buffer at the specified offset.

Parameters

index	the index at which to insert.
l	the long to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [5/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, double  d  )

inline

Inserts the string representation of the specified into this buffer double at the specified offset.

Parameters

index	the index at which to insert.
d	the double to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [6/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, float  f  )

inline

Inserts the string representation of the specified float into this buffer at the specified offset.

Parameters

index	the index at which to insert.
f	the float to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [7/10]

StringBuffer java.lang.StringBuffer.insert ( int  index, Object  obj  )

inline

Inserts the string representation of the specified object into this buffer at the specified offset.

If the specified object is

null 

, the string

"null" 

is inserted, otherwise the objects

toString 

method is used to get its string representation.

Parameters

index	the index at which to insert.
obj	the object to insert (may be null).

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [8/10]

synchronized StringBuffer java.lang.StringBuffer.insert ( int  index, String  string  )

inline

Inserts the string into this buffer at the specified offset.

If the specified string is

null 

, the string

"null" 

is inserted, otherwise the contents of the string is inserted.

Parameters

index	the index at which to insert.
string	the string to insert (may be null).

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if index < 0 or index > length() .

insert() [9/10]

synchronized StringBuffer java.lang.StringBuffer.insert ( int  index, char []  chars  )

inline

Inserts the character array into this buffer at the specified offset.

Parameters

index	the index at which to insert.
chars	the character array to insert.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException	if index < 0 or index > length() .
NullPointerException	if chars is null .

insert() [10/10]

synchronized StringBuffer java.lang.StringBuffer.insert ( int  index, char []  chars, int  start, int  length  )

inline

Inserts the specified subsequence of characters into this buffer at the specified index.

Parameters

index	the index at which to insert.
chars	the character array to insert.
start	the starting offset.
length	the number of characters.

Returns

this buffer.

Exceptions

NullPointerException	if chars is null .
StringIndexOutOfBoundsException	if length < 0 , start < 0 , start + length > chars.length , index < 0 or index > length()

lastIndexOf() [1/2]

int java.lang.StringBuffer.lastIndexOf ( String  string )

inline

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.

Exceptions

java.lang.NullPointerException

if str is null.

Since

1.4

lastIndexOf() [2/2]

synchronized int java.lang.StringBuffer.lastIndexOf ( String  subString, int  start  )

inline

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.

Exceptions

java.lang.NullPointerException

if str is null.

Since

1.4

length()

int java.lang.StringBuffer.length ( )

inline

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.

replace()

synchronized StringBuffer java.lang.StringBuffer.replace ( int  start, int  end, String  string  )

inline

Replaces the characters in the specified range with the contents of the specified string.

Parameters

start	the inclusive begin index.
end	the exclusive end index.
string	the string that will replace the contents in the range.

Returns

this buffer.

Exceptions

StringIndexOutOfBoundsException

if start or end are negative, start is greater than end or end is greater than the length of s .

reverse()

synchronized StringBuffer java.lang.StringBuffer.reverse ( )

inline

Reverses the order of characters in this buffer.

Returns

this buffer.

setCharAt()

synchronized void java.lang.StringBuffer.setCharAt ( int  index, char  ch  )

inline

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.

Parameters

index

the index of the desired character.

Returns

the character at the specified index of this string buffer.

Exceptions

IndexOutOfBoundsException

if index is negative or greater than or equal to length().

See also

java.lang.StringBuffer::length()

setLength()

synchronized void java.lang.StringBuffer.setLength ( int  length )

inline

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

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.

Exceptions

StringIndexOutOfBoundsException

if the newLength argument is negative.

See also

java.lang.StringBuffer::length()

substring() [1/2]

synchronized String java.lang.StringBuffer.substring ( int  start )

inline

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.

Exceptions

StringIndexOutOfBoundsException

if start is less than zero, or greater than the length of this StringBuffer.

Since

1.2

substring() [2/2]

synchronized String java.lang.StringBuffer.substring ( int  start, int  end  )

inline

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.

Exceptions

StringIndexOutOfBoundsException

if start or end are negative or greater than length(), or start is greater than end.

Since

1.2

toString()

synchronized String java.lang.StringBuffer.toString ( )

inline

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.

Returns

a string representation of the string buffer.

---

The documentation for this class was generated from the following file:

• src/java/lang/StringBuffer.java