FileDocCategorySizeDatePackage
StringBuilder.javaAPI DocAndroid 1.5 API24731Wed May 06 22:41:04 BST 2009java.lang

StringBuilder

public final class StringBuilder extends AbstractStringBuilder implements Serializable, Appendable, CharSequence
A modifiable {@link CharSequence sequence of characters} for use in creating and modifying Strings. This class is intended as a direct replacement of {@link StringBuffer} for non-concurrent use; unlike {@code StringBuffer} this class is not synchronized for thread safety.

The majority of the modification methods on this class return {@code StringBuilder}, so that, like {@code StringBuffer}s, they can be used in chaining method calls together. For example, {@code new StringBuilder("One should ").append("always strive ").append("to achieve Harmony")}.

see
CharSequence
see
Appendable
see
StringBuffer
see
String
since
Android 1.0

Fields Summary
private static final long
serialVersionUID
Constructors Summary
public StringBuilder()
Constructs an instance with an initial capacity of {@code 16}.

see
#capacity()
since
Android 1.0


                         
      
        super();
    
public StringBuilder(int capacity)
Constructs an instance with the specified capacity.

param
capacity the initial capacity to use.
throws
NegativeArraySizeException if the specified {@code capacity} is negative.
see
#capacity()
since
Android 1.0

        super(capacity);
    
public StringBuilder(CharSequence seq)
Constructs an instance that's initialized with the contents of the specified {@code CharSequence}. The capacity of the new builder will be the length of the {@code CharSequence} plus 16.

param
seq the {@code CharSequence} to copy into the builder.
since
Android 1.0

        super(seq.toString());
    
public StringBuilder(String str)
Constructs an instance that's initialized with the contents of the specified {@code String}. The capacity of the new builder will be the length of the {@code String} plus 16.

param
str the {@code String} to copy into the builder.
since
Android 1.0

        super(str);
    
Methods Summary
public java.lang.StringBuilderappend(double d)
Appends the string representation of the specified {@code double} value. The {@code double} value is converted to a string according to the rule defined by {@link String#valueOf(double)}.

param
d the {@code double} value to append.
return
this builder.
see
String#valueOf(double)
since
Android 1.0

        append0(Double.toString(d));
        return this;
    
public java.lang.StringBuilderappend(java.lang.Object obj)
Appends the string representation of the specified {@code Object}. The {@code Object} value is converted to a string according to the rule defined by {@link String#valueOf(Object)}.

param
obj the {@code Object} to append.
return
this builder.
see
String#valueOf(Object)
since
Android 1.0

        if (obj == null) {
            appendNull();
        } else {
            append0(obj.toString());
        }
        return this;
    
public java.lang.StringBuilderappend(java.lang.String str)
Appends the contents of the specified string. If the string is {@code null}, then the string {@code "null"} is appended.

param
str the string to append.
return
this builder.
since
Android 1.0

        append0(str);
        return this;
    
public java.lang.StringBuilderappend(java.lang.StringBuffer sb)
Appends the contents of the specified {@code StringBuffer}. If the StringBuffer is {@code null}, then the string {@code "null"} is appended.

param
sb the {@code StringBuffer} to append.
return
this builder.
since
Android 1.0

        if (sb == null) {
            appendNull();
        } else {
            append0(sb.getValue(), 0, sb.length());
        }
        return this;
    
public java.lang.StringBuilderappend(char[] ch)
Appends the string representation of the specified {@code char[]}. The {@code char[]} is converted to a string according to the rule defined by {@link String#valueOf(char[])}.

param
ch the {@code char[]} to append..
return
this builder.
see
String#valueOf(char[])
since
Android 1.0

        append0(ch);
        return this;
    
public java.lang.StringBuilderappend(char[] str, int offset, int len)
Appends the string representation of the specified subset of the {@code char[]}. The {@code char[]} value is converted to a String according to the rule defined by {@link String#valueOf(char[],int,int)}.

param
str the {@code char[]} to append.
param
offset the inclusive offset index.
param
len the number of characters.
return
this builder.
throws
ArrayIndexOutOfBoundsException if {@code offset} and {@code len} do not specify a valid subsequence.
see
String#valueOf(char[],int,int)
since
Android 1.0

        append0(str, offset, len);
        return this;
    
public java.lang.StringBuilderappend(java.lang.CharSequence csq)
Appends the string representation of the specified {@code CharSequence}. If the {@code CharSequence} is {@code null}, then the string {@code "null"} is appended.

param
csq the {@code CharSequence} to append.
return
this builder.
since
Android 1.0

        if (csq == null) {
            appendNull();
        } else {
            append0(csq.toString());
        }
        return this;
    
public java.lang.StringBuilderappend(java.lang.CharSequence csq, int start, int end)
Appends the string representation of the specified subsequence of the {@code CharSequence}. If the {@code CharSequence} is {@code null}, then the string {@code "null"} is used to extract the subsequence from.

param
csq the {@code CharSequence} to append.
param
start the beginning index.
param
end the ending index.
return
this builder.
throws
IndexOutOfBoundsException if {@code start} or {@code end} are negative, {@code start} is greater than {@code end} or {@code end} is greater than the length of {@code csq}.
since
Android 1.0

        append0(csq, start, end);
        return this;
    
public java.lang.StringBuilderappend(boolean b)
Appends the string representation of the specified {@code boolean} value. The {@code boolean} value is converted to a String according to the rule defined by {@link String#valueOf(boolean)}.

param
b the {@code boolean} value to append.
return
this builder.
see
String#valueOf(boolean)
since
Android 1.0

        append0(b ? "true" : "false"); //$NON-NLS-1$ //$NON-NLS-2$
        return this;
    
public java.lang.StringBuilderappend(char c)
Appends the string representation of the specified {@code char} value. The {@code char} value is converted to a string according to the rule defined by {@link String#valueOf(char)}.

param
c the {@code char} value to append.
return
this builder.
see
String#valueOf(char)
since
Android 1.0

        append0(c);
        return this;
    
public java.lang.StringBuilderappend(int i)
Appends the string representation of the specified {@code int} value. The {@code int} value is converted to a string according to the rule defined by {@link String#valueOf(int)}.

param
i the {@code int} value to append.
return
this builder.
see
String#valueOf(int)
since
Android 1.0

        append0(Integer.toString(i));
        return this;
    
public java.lang.StringBuilderappend(long lng)
Appends the string representation of the specified {@code long} value. The {@code long} value is converted to a string according to the rule defined by {@link String#valueOf(long)}.

param
lng the {@code long} value.
return
this builder.
see
String#valueOf(long)
since
Android 1.0

        append0(Long.toString(lng));
        return this;
    
public java.lang.StringBuilderappend(float f)
Appends the string representation of the specified {@code float} value. The {@code float} value is converted to a string according to the rule defined by {@link String#valueOf(float)}.

param
f the {@code float} value to append.
return
this builder.
see
String#valueOf(float)
since
Android 1.0

        append0(Float.toString(f));
        return this;
    
public java.lang.StringBuilderappendCodePoint(int codePoint)
Appends the encoded Unicode code point. The code point is converted to a {@code char[]} as defined by {@link Character#toChars(int)}.

param
codePoint the Unicode code point to encode and append.
return
this builder.
see
Character#toChars(int)
since
Android 1.0

        append0(Character.toChars(codePoint));
        return this;
    
public java.lang.StringBuilderdelete(int start, int end)
Deletes a sequence of characters specified by {@code start} and {@code end}. Shifts any remaining characters to the left.

param
start the inclusive start index.
param
end the exclusive end index.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code start} is less than zero, greater than the current length or greater than {@code end}.
since
Android 1.0

        delete0(start, end);
        return this;
    
public java.lang.StringBuilderdeleteCharAt(int index)
Deletes the character at the specified index. shifts any remaining characters to the left.

param
index the index of the character to delete.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code index} is less than zero or is greater than or equal to the current length.
since
Android 1.0

        deleteCharAt0(index);
        return this;
    
public java.lang.StringBuilderinsert(int offset, boolean b)
Inserts the string representation of the specified {@code boolean} value at the specified {@code offset}. The {@code boolean} value is converted to a string according to the rule defined by {@link String#valueOf(boolean)}.

param
offset the index to insert at.
param
b the {@code boolean} value to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length}.
see
String#valueOf(boolean)
since
Android 1.0

        insert0(offset, b ? "true" : "false"); //$NON-NLS-1$ //$NON-NLS-2$
        return this;
    
public java.lang.StringBuilderinsert(int offset, char c)
Inserts the string representation of the specified {@code char} value at the specified {@code offset}. The {@code char} value is converted to a string according to the rule defined by {@link String#valueOf(char)}.

param
offset the index to insert at.
param
c the {@code char} value to insert.
return
this builder.
throws
IndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(char)
since
Android 1.0

        insert0(offset, c);
        return this;
    
public java.lang.StringBuilderinsert(int offset, int i)
Inserts the string representation of the specified {@code int} value at the specified {@code offset}. The {@code int} value is converted to a String according to the rule defined by {@link String#valueOf(int)}.

param
offset the index to insert at.
param
i the {@code int} value to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(int)
since
Android 1.0

        insert0(offset, Integer.toString(i));
        return this;
    
public java.lang.StringBuilderinsert(int offset, long l)
Inserts the string representation of the specified {@code long} value at the specified {@code offset}. The {@code long} value is converted to a String according to the rule defined by {@link String#valueOf(long)}.

param
offset the index to insert at.
param
l the {@code long} value to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {code length()}.
see
String#valueOf(long)
since
Android 1.0

        insert0(offset, Long.toString(l));
        return this;
    
public java.lang.StringBuilderinsert(int offset, float f)
Inserts the string representation of the specified {@code float} value at the specified {@code offset}. The {@code float} value is converted to a string according to the rule defined by {@link String#valueOf(float)}.

param
offset the index to insert at.
param
f the {@code float} value to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(float)
since
Android 1.0

        insert0(offset, Float.toString(f));
        return this;
    
public java.lang.StringBuilderinsert(int offset, double d)
Inserts the string representation of the specified {@code double} value at the specified {@code offset}. The {@code double} value is converted to a String according to the rule defined by {@link String#valueOf(double)}.

param
offset the index to insert at.
param
d the {@code double} value to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(double)
since
Android 1.0

        insert0(offset, Double.toString(d));
        return this;
    
public java.lang.StringBuilderinsert(int offset, java.lang.Object obj)
Inserts the string representation of the specified {@code Object} at the specified {@code offset}. The {@code Object} value is converted to a String according to the rule defined by {@link String#valueOf(Object)}.

param
offset the index to insert at.
param
obj the {@code Object} to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(Object)
since
Android 1.0

        insert0(offset, obj == null ? "null" : obj.toString()); //$NON-NLS-1$
        return this;
    
public java.lang.StringBuilderinsert(int offset, java.lang.String str)
Inserts the specified string at the specified {@code offset}. If the specified string is null, then the String {@code "null"} is inserted.

param
offset the index to insert at.
param
str the {@code String} to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
since
Android 1.0

        insert0(offset, str);
        return this;
    
public java.lang.StringBuilderinsert(int offset, char[] ch)
Inserts the string representation of the specified {@code char[]} at the specified {@code offset}. The {@code char[]} value is converted to a String according to the rule defined by {@link String#valueOf(char[])}.

param
offset the index to insert at.
param
ch the {@code char[]} to insert.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
String#valueOf(char[])
since
Android 1.0

        insert0(offset, ch);
        return this;
    
public java.lang.StringBuilderinsert(int offset, char[] str, int strOffset, int strLen)
Inserts the string representation of the specified subsequence of the {@code char[]} at the specified {@code offset}. The {@code char[]} value is converted to a String according to the rule defined by {@link String#valueOf(char[],int,int)}.

param
offset the index to insert at.
param
str the {@code char[]} to insert.
param
strOffset the inclusive index.
param
strLen the number of characters.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}, or {@code strOffset} and {@code strLen} do not specify a valid subsequence.
see
String#valueOf(char[],int,int)
since
Android 1.0

        insert0(offset, str, strOffset, strLen);
        return this;
    
public java.lang.StringBuilderinsert(int offset, java.lang.CharSequence s)
Inserts the string representation of the specified {@code CharSequence} at the specified {@code offset}. The {@code CharSequence} is converted to a String as defined by {@link CharSequence#toString()}. If {@code s} is {@code null}, then the String {@code "null"} is inserted.

param
offset the index to insert at.
param
s the {@code CharSequence} to insert.
return
this builder.
throws
IndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}.
see
CharSequence#toString()
since
Android 1.0

        insert0(offset, s == null ? "null" : s.toString()); //$NON-NLS-1$
        return this;
    
public java.lang.StringBuilderinsert(int offset, java.lang.CharSequence s, int start, int end)
Inserts the string representation of the specified subsequence of the {@code CharSequence} at the specified {@code offset}. The {@code CharSequence} is converted to a String as defined by {@link CharSequence#subSequence(int, int)}. If the {@code CharSequence} is {@code null}, then the string {@code "null"} is used to determine the subsequence.

param
offset the index to insert at.
param
s the {@code CharSequence} to insert.
param
start the start of the subsequence of the character sequence.
param
end the end of the subsequence of the character sequence.
return
this builder.
throws
IndexOutOfBoundsException if {@code offset} is negative or greater than the current {@code length()}, or {@code start} and {@code end} do not specify a valid subsequence.
see
CharSequence#subSequence(int, int)
since
Android 1.0

        insert0(offset, s, start, end);
        return this;
    
private voidreadObject(java.io.ObjectInputStream in)
Reads the state of a {@code StringBuilder} from the passed stream and restores it to this instance.

param
in the stream to read the state from.
throws
IOException if the stream throws it during the read.
throws
ClassNotFoundException if the stream throws it during the read.

        in.defaultReadObject();
        int count = in.readInt();
        char[] value = (char[]) in.readObject();
        set(value, count);
    
public java.lang.StringBuilderreplace(int start, int end, java.lang.String str)
Replaces the specified subsequence in this builder with the specified string.

param
start the inclusive begin index.
param
end the exclusive end index.
param
str the replacement string.
return
this builder.
throws
StringIndexOutOfBoundsException if {@code start} is negative, greater than the current {@code length()} or greater than {@code end}.
since
Android 1.0

        replace0(start, end, str);
        return this;
    
public java.lang.StringBuilderreverse()
Reverses the order of characters in this builder.

return
this buffer.
since
Android 1.0

        reverse0();
        return this;
    
public java.lang.StringtoString()
Returns the contents of this builder.

return
the string representation of the data in this builder.
since
Android 1.0

        /* Note: This method is required to workaround a compiler bug
         * in the RI javac (at least in 1.5.0_06) that will generate a
         * reference to the non-public AbstractStringBuilder if we don't
         * override it here.
         */
        return super.toString();
    
private voidwriteObject(java.io.ObjectOutputStream out)
Writes the state of this object to the stream passed.

param
out the stream to write the state to.
throws
IOException if the stream throws it during the write.
serialData
{@code int} - the length of this object. {@code char[]} - the buffer from this object, which may be larger than the length field.

        out.defaultWriteObject();
        out.writeInt(length());
        out.writeObject(getValue());