Java Language Reference

Previous Chapter 10
The java.lang Package
Next
 

StringBuffer

Name

StringBuffer

Synopsis

Class Name:

java.lang.StringBuffer

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

java.io.Serializable

Availability:

JDK 1.0 or later

Description

The StringBuffer class represents a variable-length sequence of characters. StringBuffer objects are used in computations that involve creating new String objects. The StringBuffer class provides a number of utility methods for working with StringBuffer objects, including append() and insert() methods that add characters to a StringBuffer and methods that fetch the contents of StringBuffer objects.

When a StringBuffer object is created, the constructor determines the initial contents and capacity of the StringBuffer. The capacity of a StringBuffer is the number of characters that its internal data structure can hold. This is distinct from the length of the contents of a StringBuffer, which is the number of characters that are actually stored in the StringBuffer object. The capacity of a StringBuffer can vary. When a StringBuffer object is asked to hold more characters than its current capacity allows, the StringBuffer enlarges its internal data structure. However, it is more costly in terms of execution time and memory when a StringBuffer has to repeatedly increase its capacity than when a StringBuffer object is created with sufficient capacity.

Because the intended use of StringBuffer objects involves modifying their contents, all methods of the StringBuffer class that modify StringBuffer objects are synchronized. This means that is it safe for multiple threads to try to modify a StringBuffer object at the same time.

StringBuffer objects are used implicitly by the string concatenation operator. Consider the following code:

String s, s1, s2;
s = s1 + s2;

To compute the string concatenation, the Java compiler generates code like:

s = new StringBuffer().append(s1).append(s2).toString();

Class Summary

public class java.lang.StringBuffer extends java.lang.Object {
    // Constructors
    public StringBuffer();
    public StringBuffer(int length);
    public StringBuffer(String str);
    // Instance Methods
    public StringBuffer append(boolean b);
    public synchronized StringBuffer append(char c);
    public synchronized StringBuffer append(char[] str);
    public synchronized StringBuffer append(char[] str, int offset, int len);
    public StringBuffer append(double d);
    public StringBuffer append(float f);
    public StringBuffer append(int i);
    public StringBuffer append(long l);
    public synchronized StringBuffer append(Object obj);
    public synchronized StringBuffer append(String str);
    public int capacity();
    public synchronized char charAt(int index);
    public synchronized void ensureCapacity(int minimumCapacity);
    public synchronized void getChars(int srcBegin, int srcEnd, 
                             char[] dst, int dstBegin);
    public StringBuffer insert(int offset, boolean b);
    public synchronized StringBuffer insert(int offset, char c);
    public synchronized StringBuffer insert(int offset, char[] str);
    public StringBuffer insert(int offset, double d);
    public StringBuffer insert(int offset, float f);
    public StringBuffer insert(int offset, int i);
    public StringBuffer insert(int offset, long l);
    public synchronized StringBuffer insert(int offset, Object obj);
    public synchronized StringBuffer insert(int offset, String str);
    public int length();
    public synchronized StringBuffer reverse();
    public synchronized void setCharAt(int index, char ch);
    public synchronized void setLength(int newLength);
    public String toString();
}

Constructors

StringBuffer

public StringBuffer()

Description

Creates a StringBuffer object that does not contain any characters and has a capacity of 16 characters.

public StringBuffer(int capacity)

Parameters

capacity

The initial capacity of this StringBufffer object.

Throws

NegativeArraySizeException

If capacity is negative.

Description

Creates a StringBuffer object that does not contain any characters and has the specified capacity.

public StringBuffer(String str)

Parameters

str

A String object.

Description

Creates a StringBuffer object that contains the same sequence of characters as the given String object and has a capacity 16 greater than the length of the String.

Instance Methods

append

public StringBuffer append(boolean b)

Parameters

b

A boolean value.

Returns

This StringBuffer object.

Description

This method appends either "true" or "false" to the end of the sequence of characters stored in ths StringBuffer object, depending on the value of b.

public synchronized StringBuffer append(char c)

Parameters

c

A char value.

Returns

This StringBuffer object.

Description

This method appends the given character to the end of the sequence of characters stored in this StringBuffer object.

public synchronized StringBuffer append(char str[])

Parameters

str

An array of char values.

Returns

This StringBuffer object.

Description

This method appends the characters in the given array to the end of the sequence of characters stored in this StringBuffer object.

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

Parameters

str

An array of char values.

offset

An offset into the array.

len

The number of characters from the array to be appended.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset or len are out of range.

Description

This method appends the specified portion of the given array to the end of the character sequence stored in this StringBuffer object. The portion of the array that is appended starts offset elements from the beginning of the array and is len elements long.

public StringBuffer append(double d)

Parameters

d

A double value.

Returns

This StringBuffer object.

Description

This method converts the given double value to a string using Double.toString(d) and appends the resulting string to the end of the sequence of characters stored in this StringBuffer object.

public StringBuffer append(float f)

Parameters

f

A float value.

Returns

This StringBuffer object.

Description

This method converts the given float value to a string using Float.toString(f) and appends the resulting string to the end of the sequence of characters stored in this StringBuffer object.

public StringBuffer append(int i)

Parameters

i

An int value.

Returns

This StringBuffer object.

Description

This method converts the given int value to a string using Integer.toString(i) and appends the resulting string to the end of the sequence of characters stored in this StringBuffer object.

public StringBuffer append(long l)

Parameters

l

A long value.

Returns

This StringBuffer object.

Description

This method converts the given long value to a string using Long.toString(l) and appends the resulting string to the end of the sequence of characters stored in this StringBuffer object.

public synchronized StringBuffer append(Object obj)

Parameters

obj

A reference to an object.

Returns

This StringBuffer object.

Description

This method gets the string representation of the given object by calling String.valueOf(obj) and appends the resulting string to the end of the character sequence stored in this StringBuffer object.

public synchronized StringBuffer append(String str)

Parameters

str

A String object.

Returns

This StringBuffer object.

Description

This method appends the sequence of characters represented by the given String to the characters in this StringBuffer object. If str is null, the string "null" is appended.

capacity

public int capacity()

Returns

The capacity of this StringBuffer object.

Description

This method returns the current capacity of this object. The capacity of a StringBuffer object is the number of characters that its internal data structure can hold. A StringBuffer object automatically increases its capacity when it is asked to hold more characters than its current capacity allows.

charAt

public synchronized char charAt(int index)

Parameters

index

An index into the StringBuffer.

Returns

The character stored at the specified position in this StringBuffer object.

Throws

StringIndexOutOfBoundsException

If index is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method returns the character at the specified position in the StringBuffer object. The first character in the StringBuffer is at index 0.

ensureCapacity

public synchronized void ensureCapacity(int minimumCapacity)

Parameters

minimumCapacity

The minimum desired capacity.

Description

This method ensures that the capacity of this StringBuffer object is at least the specified number of characters. If necessary, the capacity of this object is increased to the greater of minimumCapacity or double its current capacity plus two.

It is more efficient to ensure that the capacity of a StringBuffer object is sufficient to hold all of the additions that will be made to its contents, rather than let the StringBuffer increase its capacity in multiple increments.

getChars

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

Parameters

srcBegin

The index of the first character to be copied.

srcEnd

The index after the last character to be copied.

dst

The destination char array.

dstBegin

An offset into the destination array.

Throws

StringIndexOutOfBoundsException

If srcBegin, srcEnd, or dstBegin is out of range.

Description

This method copies each character in the specified range of this StringBuffer object to the given array of char values. More specifically, the first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1.

These characters are copied into dst, starting at index dstBegin and ending at index:

dstBegin + (srcEnd-srcBegin) - 1

insert

public StringBuffer insert(int offset, boolean b)

Parameters

offset

An offset into the StringBuffer.

b

A boolean value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is out of range.

Description

This method inserts either "true" or "false" into the sequence of characters stored in this StringBuffer object, depending on the value of b. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public synchronized StringBuffer insert(int offset, char c)

Parameters

offset

An offset into the StringBuffer.

c

A char value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method inserts the given character into the sequence of characters stored in this StringBuffer object. The character is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the character is inserted before the first character in the StringBuffer.

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

Parameters

offset

An offset into the StringBuffer.

str

An array of char values.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method inserts the characters in the given array into the sequence of characters stored in this StringBuffer object. The characters are inserted at a position offset characters from the beginning of the sequence. If offset is 0, the characters are inserted before the first character in the StringBuffer.

public StringBuffer insert(int offset, double d)

Parameters

offset

An offset into the StringBuffer.

d

A double value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method converts the given double value to a string using Double.toString(d) and inserts the resulting string into the sequence of characters stored in this StringBuffer object. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public StringBuffer insert(int offset, float f)

Parameters

offset

An offset into the StringBuffer.

f

A float value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method converts the given float value to a string using Float.toString(f) and inserts the resulting string into the sequence of characters stored in this StringBuffer object. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public StringBuffer insert(int offset, int i)

Parameters

offset

An offset into the StringBuffer.

i

An int value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method converts the given int value to a string using Integer.toString(i) and inserts the resulting string into the sequence of characters stored in this StringBuffer object. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public StringBuffer insert(int offset, long l)

Parameters

offset

An offset into the StringBuffer.

l

A long value.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method converts the given long value to a string using Long.toString(l) and inserts the resulting string into the sequence of characters stored in this StringBuffer object. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public synchronized StringBuffer insert(int offset, Object obj)

Parameters

offset

An offset into the StringBuffer.

obj

A reference to an object.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method gets the string representation of the given object by calling String.valueOf(obj) and inserts the resulting string into the sequence of characters stored in this StringBuffer object. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

public synchronized StringBuffer insert(int offset, String str)

Parameters

offset

An offset into the StringBuffer.

str

A String object.

Returns

This StringBuffer object.

Throws

StringIndexOutOfBoundsException

If offset is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method inserts the sequence of characters represented by the given String into the sequence of characters stored in this StringBuffer object. If str is null, the string "null" is inserted. The string is inserted at a position offset characters from the beginning of the sequence. If offset is 0, the string is inserted before the first character in the StringBuffer.

length

public int length()

Returns

The number of characters stored in this StringBuffer object.

Description

This method returns the number of characters stored in this StringBuffer object. The length is distinct from the capacity of a StringBuffer, which is the number of characters that its internal data structure can hold.

reverse

public synchronized StringBuffer reverse()

Returns

This StringBuffer object.

Description

This method reverses the sequence of characters stored in this StringBuffer object.

setCharAt

public synchronized void setCharAt(int index, char ch)

Parameters

index

The index of the character to be set.

ch

A char value.

Throws

StringIndexOutOfBoundsException

If index is less than zero or greater than or equal to the length of the StringBuffer object.

Description

This method modifies the character located index characters from the beginning of the sequence of characters stored in this StringBuffer object. The current character at this position is replaced by the character ch.

setLength

public synchronized void setLength(int newLength)

Parameters

newLength

The new length for this StringBuffer.

Throws

StringIndexOutOfBoundsException

If index is less than zero.

Description

This method sets the length of the sequence of characters stored in this StringBuffer object. If the length is set to be less than the current length, characters are lost from the end of the character sequence. If the length is set to be more than the current length, NUL characters (\u0000) are added to the end of the character sequence.

toString

public String toString()

Returns

A new String object that represents the same sequence of characters as the sequence of characters stored in this StringBuffer object.

Overrides

Object.toString()

Description

This method returns a new String object that represents the same sequence of characters as the sequence of characters stored in this StringBuffer object. Note that any subsequent changes to the contents of this StringBuffer object do not affect the contents of the String object created by this method.

Inherited Methods

Method

Inherited From

Method

Inherited From

clone()

Object

equals(Object)

Object

finalize()

Object

getClass()

Object

hashCode()

Object

notify()

Object

notifyAll()

Object

wait()

Object

wait(long)

Object

wait(long, int)

Object

See Also

Character; Double; Exceptions; Float; Integer; Long; Object; String; String Concatenation Operator +


Previous Home Next
String Book Index System

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java