FileDocCategorySizeDatePackage
StringBuilder.javaAPI DocJava SE 6 API14091Tue Jun 10 00:25:36 BST 2008java.lang

StringBuilder

public final class StringBuilder extends AbstractStringBuilder implements CharSequence, Serializable
A mutable sequence of characters. This class provides an API compatible with StringBuffer, but with no guarantee of synchronization. This class is designed for use as a drop-in replacement for StringBuffer in places where the string buffer was being used by a single thread (as is generally the case). Where possible, it is recommended that this class be used in preference to StringBuffer as it will be faster under most implementations.

The principal operations on a StringBuilder 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 builder. The append method always adds these characters at the end of the builder; the insert method adds the characters at a specified point.

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

In general, if sb refers to an instance of a StringBuilder, then sb.append(x) has the same effect as sb.insert(sb.length(), x). Every string builder has a capacity. As long as the length of the character sequence contained in the string builder does not exceed the capacity, it is not necessary to allocate a new internal buffer. If the internal buffer overflows, it is automatically made larger.

Instances of StringBuilder are not safe for use by multiple threads. If such synchronization is required then it is recommended that {@link java.lang.StringBuffer} be used.

author
Michael McCloskey
version
1.11, 11/17/05
see
java.lang.StringBuffer
see
java.lang.String
since
1.5

Fields Summary
static final long
serialVersionUID
use serialVersionUID for interoperability
Constructors Summary
public StringBuilder()
Constructs a string builder with no characters in it and an initial capacity of 16 characters.


                           
      
	super(16);
public StringBuilder(int capacity)
Constructs a string builder with no characters in it and an initial capacity specified by the capacity argument.

param
capacity the initial capacity.
throws
NegativeArraySizeException if the capacity argument is less than 0.

	super(capacity);
public StringBuilder(String str)
Constructs a string builder initialized to the contents of the specified string. The initial capacity of the string builder is 16 plus the length of the string argument.

param
str the initial contents of the buffer.
throws
NullPointerException if str is null

	super(str.length() + 16);
	append(str);
public StringBuilder(CharSequence seq)
Constructs a string builder that contains the same characters as the specified CharSequence. The initial capacity of the string builder is 16 plus the length of the CharSequence argument.

param
seq the sequence to copy.
throws
NullPointerException if seq is null

        this(seq.length() + 16);
        append(seq);
Methods Summary
public java.lang.StringBuilderappend(java.lang.CharSequence s, int start, int end)

throws
IndexOutOfBoundsException {@inheritDoc}

        super.append(s, start, end);
        return this;
public java.lang.StringBuilderappend(char[] str)

 
	super.append(str);
        return this;
public java.lang.StringBuilderappend(char[] str, int offset, int len)

        super.append(str, offset, len);
        return this;
public java.lang.StringBuilderappend(boolean b)

see
java.lang.String#valueOf(boolean)
see
#append(java.lang.String)

        super.append(b);
        return this;
public java.lang.StringBuilderappend(char c)

        super.append(c);
        return this;
public java.lang.StringBuilderappend(int i)

see
java.lang.String#valueOf(int)
see
#append(java.lang.String)

	super.append(i);
        return this;
public java.lang.StringBuilderappend(long lng)

see
java.lang.String#valueOf(long)
see
#append(java.lang.String)

        super.append(lng);
        return this;
public java.lang.StringBuilderappend(float f)

see
java.lang.String#valueOf(float)
see
#append(java.lang.String)

	super.append(f);
        return this;
public java.lang.StringBuilderappend(double d)

see
java.lang.String#valueOf(double)
see
#append(java.lang.String)

	super.append(d);
        return this;
public java.lang.StringBuilderappend(java.lang.Object obj)

see
java.lang.String#valueOf(java.lang.Object)
see
#append(java.lang.String)

	return append(String.valueOf(obj));
public java.lang.StringBuilderappend(java.lang.String str)

	super.append(str);
        return this;
private java.lang.StringBuilderappend(java.lang.StringBuilder sb)

	if (sb == null)
            return append("null");
	int len = sb.length();
	int newcount = count + len;
	if (newcount > value.length)
	    expandCapacity(newcount);
	sb.getChars(0, len, value, count);
	count = newcount;
        return this;
public java.lang.StringBuilderappend(java.lang.StringBuffer sb)
Appends the specified StringBuffer to this sequence.

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

Let n be the length of this character sequence 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.

param
sb the StringBuffer to append.
return
a reference to this object.

        super.append(sb);
        return this;
public java.lang.StringBuilderappend(java.lang.CharSequence s)

throws
IndexOutOfBoundsException {@inheritDoc}

        if (s == null)
            s = "null";
        if (s instanceof String)
            return this.append((String)s);
        if (s instanceof StringBuffer)
            return this.append((StringBuffer)s);
        if (s instanceof StringBuilder)
            return this.append((StringBuilder)s);
        return this.append(s, 0, s.length());
public java.lang.StringBuilderappendCodePoint(int codePoint)

since
1.5

	super.appendCodePoint(codePoint);
	return this;
public java.lang.StringBuilderdelete(int start, int end)

throws
StringIndexOutOfBoundsException {@inheritDoc}

	super.delete(start, end);
        return this;
public java.lang.StringBuilderdeleteCharAt(int index)

throws
StringIndexOutOfBoundsException {@inheritDoc}

        super.deleteCharAt(index);
        return this;
public intindexOf(java.lang.String str)

throws
NullPointerException {@inheritDoc}

	return indexOf(str, 0);
public intindexOf(java.lang.String str, int fromIndex)

throws
NullPointerException {@inheritDoc}

        return String.indexOf(value, 0, count,
                              str.toCharArray(), 0, str.length(), fromIndex);
public java.lang.StringBuilderinsert(int index, char[] str, int offset, int len)

throws
StringIndexOutOfBoundsException {@inheritDoc}

        super.insert(index, str, offset, len);
	return this;
public java.lang.StringBuilderinsert(int offset, java.lang.Object obj)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(java.lang.Object)
see
#insert(int, java.lang.String)
see
#length()

	return insert(offset, String.valueOf(obj));
public java.lang.StringBuilderinsert(int offset, java.lang.String str)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
#length()

	super.insert(offset, str);
        return this;
public java.lang.StringBuilderinsert(int offset, char[] str)

throws
StringIndexOutOfBoundsException {@inheritDoc}

	super.insert(offset, str);
        return this;
public java.lang.StringBuilderinsert(int dstOffset, java.lang.CharSequence s)

throws
IndexOutOfBoundsException {@inheritDoc}

        if (s == null)
            s = "null";
        if (s instanceof String)
            return this.insert(dstOffset, (String)s);
        return this.insert(dstOffset, s, 0, s.length());
public java.lang.StringBuilderinsert(int dstOffset, java.lang.CharSequence s, int start, int end)

throws
IndexOutOfBoundsException {@inheritDoc}

        super.insert(dstOffset, s, start, end);
        return this;
public java.lang.StringBuilderinsert(int offset, boolean b)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(boolean)
see
#insert(int, java.lang.String)
see
#length()

	super.insert(offset, b);
        return this;
public java.lang.StringBuilderinsert(int offset, char c)

throws
IndexOutOfBoundsException {@inheritDoc}
see
#length()

        super.insert(offset, c);
	return this;
public java.lang.StringBuilderinsert(int offset, int i)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(int)
see
#insert(int, java.lang.String)
see
#length()

	return insert(offset, String.valueOf(i));
public java.lang.StringBuilderinsert(int offset, long l)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(long)
see
#insert(int, java.lang.String)
see
#length()

	return insert(offset, String.valueOf(l));
public java.lang.StringBuilderinsert(int offset, float f)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(float)
see
#insert(int, java.lang.String)
see
#length()

	return insert(offset, String.valueOf(f));
public java.lang.StringBuilderinsert(int offset, double d)

throws
StringIndexOutOfBoundsException {@inheritDoc}
see
java.lang.String#valueOf(double)
see
#insert(int, java.lang.String)
see
#length()

	return insert(offset, String.valueOf(d));
public intlastIndexOf(java.lang.String str)

throws
NullPointerException {@inheritDoc}

        return lastIndexOf(str, count);
public intlastIndexOf(java.lang.String str, int fromIndex)

throws
NullPointerException {@inheritDoc}

        return String.lastIndexOf(value, 0, count,
                              str.toCharArray(), 0, str.length(), fromIndex);
private voidreadObject(java.io.ObjectInputStream s)
readObject is called to restore the state of the StringBuffer from a stream.

        s.defaultReadObject();
        count = s.readInt();
        value = (char[]) s.readObject();
public java.lang.StringBuilderreplace(int start, int end, java.lang.String str)

throws
StringIndexOutOfBoundsException {@inheritDoc}

        super.replace(start, end, str);
        return this;
public java.lang.StringBuilderreverse()

	super.reverse();
	return this;
public java.lang.StringtoString()

        // Create a copy, don't share the array
	return new String(value, 0, count);
private voidwriteObject(java.io.ObjectOutputStream s)
Save the state of the StringBuilder instance to a stream (that is, serialize it).

serialData
the number of characters currently stored in the string builder (int), followed by the characters in the string builder (char[]). The length of the char array may be greater than the number of characters currently stored in the string builder, in which case extra characters are ignored.

        s.defaultWriteObject();
        s.writeInt(count);
        s.writeObject(value);