StringBuffer represents a changeable String.
* It provides the operations required to modify the
* StringBuffer including insert, replace, delete, append,
* and reverse.
*
*
* StringBuffers are variable-length in nature, so even if
* you initialize them to a certain size, they can still grow larger than
* that. Capacity indicates the number of characters the
* StringBuffer can have in it before it has to grow (growing
* the char array is an expensive operation involving new).
*
*
* Incidentally, the String operator "+" actually is turned into a
* StringBuffer operation:
*
* a + b
*
* is the same as
*
* new StringBuffer(a).append(b).toString().
*
* @implnote Classpath's StringBuffer is capable of sharing memory with
* Strings for efficiency. This will help in two instances:
* first, when a StringBuffer is created from a String but is
* never changed, and second, when a StringBuffer is converted
* to a String and the StringBuffer is not changed after that.
*
* @since JDK1.0
* @author Paul Fisher
* @author John Keiser
* @author Tom Tromey
* @see java.lang.String
*/
public final class StringBuffer implements Serializable, CharSequence
{
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param bool the boolean to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(boolean)
*/
public StringBuffer append (boolean bool)
{
return append (String.valueOf(bool));
}
/** Append the char to this StringBuffer.
* @param c the char to append.
* @return this StringBuffer.
*/
public synchronized StringBuffer append (char ch)
{
ensureCapacity_unsynchronized (count + 1);
value[count++] = ch;
return this;
}
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param inum the int to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(int)
*/
public native StringBuffer append (int inum);
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param lnum the long to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(long)
*/
public StringBuffer append (long lnum)
{
return append (String.valueOf(lnum));
}
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param fnum the float to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(float)
*/
public StringBuffer append (float fnum)
{
return append (String.valueOf(fnum));
}
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param dnum the double to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(double)
*/
public StringBuffer append (double dnum)
{
return append (String.valueOf(dnum));
}
/** Append the String value of the argument to this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param obj the Object to convert and append.
* @return this StringBuffer.
* @see java.lang.String#valueOf(java.lang.Object)
*/
public StringBuffer append (Object obj)
{
return append (String.valueOf(obj));
}
/** Append the String to this StringBuffer.
* @param str the String to append.
* @return this StringBuffer.
*/
public synchronized StringBuffer append (String str)
{
if (str == null)
str = "null";
int len = str.length();
ensureCapacity_unsynchronized (count + len);
str.getChars(0, len, value, count);
count += len;
return this;
}
/** Append the char array to this StringBuffer.
* @param data the char[] to append.
* @return this StringBuffer.
* @exception NullPointerException if str is null.
*/
public StringBuffer append (char[] data)
{
return append (data, 0, data.length);
}
/** Append the char array to this StringBuffer.
* @param data the char[] to append.
* @param offset the place to start grabbing characters from
* str.
* @param count the number of characters to get from str.
* @return this StringBuffer.
* @exception NullPointerException if str is null.
* @exception IndexOutOfBoundsException if offset or
* offset+len is out of range.
*/
public synchronized StringBuffer append (char[] data, int offset, int count)
{
ensureCapacity_unsynchronized (this.count + count);
System.arraycopy(data, offset, value, this.count, count);
this.count += count;
return this;
}
/** Get the total number of characters this StringBuffer
* can support before it must be grown. Not to be confused with
* length.
* @return the capacity of this StringBuffer
* @see #length()
* @see #ensureCapacity(int)
*/
public int capacity ()
{
return value.length;
}
/** Get the character at the specified index.
* @param index the index of the character to get, starting at 0.
* @return the character at the specified index.
* @exception IndexOutOfBoundsException if the desired character index
* is negative or greater then length() - 1.
*/
public synchronized char charAt (int index)
{
if (index >= count)
throw new StringIndexOutOfBoundsException (index);
return value[index];
}
/** Delete characters from this StringBuffer.
* delete(10, 12) will delete 10 and 11, but not 12.
* @param start the first character to delete.
* @param end the index after the last character to delete.
* @return this StringBuffer.
* @exception StringIndexOutOfBoundsException if start
* or end-1 are out of bounds, or if
* start > end.
*/
public synchronized StringBuffer delete (int start, int end)
{
if (start < 0 || start > count || start > end)
throw new StringIndexOutOfBoundsException (start);
if (end > count)
end = count;
// This will unshare if required.
ensureCapacity_unsynchronized (count);
if (count - end != 0)
System.arraycopy (value, end, value, start, count - end);
count -= (end - start);
return this;
}
/** Delete a character from this StringBuffer.
* @param index the index of the character to delete.
* @return this StringBuffer.
* @exception StringIndexOutOfBoundsException if index
* is out of bounds.
*/
public StringBuffer deleteCharAt(int index)
{
return delete (index, index + 1);
}
/** Increase the capacity of this StringBuffer.
* This will ensure that an expensive growing operation will not occur
* until minimumCapacity is reached.
* If the capacity is actually already greater than minimumCapacity
* @param minimumCapacity the new capacity.
* @see #capacity()
*/
public synchronized void ensureCapacity (int minimumCapacity)
{
if (shared || minimumCapacity > value.length)
{
// We don't want to make a larger vector when `shared' is
// set. If we do, then setLength becomes very inefficient
// when repeatedly reusing a StringBuffer in a loop.
int max = (minimumCapacity > value.length
? value.length*2+2
: value.length);
minimumCapacity = (minimumCapacity < max ? max : minimumCapacity);
char[] nb = new char[minimumCapacity];
System.arraycopy(value, 0, nb, 0, count);
value = nb;
shared = false;
}
}
// ensureCapacity is used by several synchronized methods in StringBuffer.
// There's no need to synchronize again.
private void ensureCapacity_unsynchronized (int minimumCapacity)
{
if (shared || minimumCapacity > value.length)
{
// We don't want to make a larger vector when `shared' is
// set. If we do, then setLength becomes very inefficient
// when repeatedly reusing a StringBuffer in a loop.
int max = (minimumCapacity > value.length
? value.length*2+2
: value.length);
minimumCapacity = (minimumCapacity < max ? max : minimumCapacity);
char[] nb = new char[minimumCapacity];
System.arraycopy(value, 0, nb, 0, count);
value = nb;
shared = false;
}
}
/** Get the specified array of characters.
* The characters will be copied into the array you pass in.
* @param srcOffset the index to start copying from in the
* StringBuffer.
* @param srcEnd the number of characters to copy.
* @param dst the array to copy into.
* @param dstOffset the index to start copying into dst.
* @exception NullPointerException if dst is null.
* @exception IndexOutOfBoundsException if any source or target
* indices are out of range.
* @see java.lang.System#arraycopy(java.lang.Object,int,java.lang.Object,int,int)
*/
public synchronized void getChars (int srcOffset, int srcEnd,
char[] dst, int dstOffset)
{
if (srcOffset < 0 || srcOffset > srcEnd)
throw new StringIndexOutOfBoundsException (srcOffset);
int todo = srcEnd - srcOffset;
if (srcEnd > count || dstOffset + todo > count)
throw new StringIndexOutOfBoundsException (srcEnd);
System.arraycopy(value, srcOffset, dst, dstOffset, todo);
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param bool the boolean to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(boolean)
*/
public StringBuffer insert (int offset, boolean bool)
{
return insert (offset, bool ? "true" : "false");
}
/** Insert the char argument into this StringBuffer.
* @param offset the place to insert.
* @param ch the char to insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
*/
public synchronized StringBuffer insert (int offset, char ch)
{
if (offset < 0 || offset > count)
throw new StringIndexOutOfBoundsException (offset);
ensureCapacity_unsynchronized (count+1);
System.arraycopy(value, offset, value, offset+1, count-offset);
value[offset] = ch;
count++;
return this;
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param inum the int to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(int)
*/
public StringBuffer insert (int offset, int inum)
{
return insert (offset, String.valueOf(inum));
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param lnum the long to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(long)
*/
public StringBuffer insert (int offset, long lnum)
{
return insert (offset, String.valueOf(lnum));
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param fnum the float to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(float)
*/
public StringBuffer insert (int offset, float fnum)
{
return insert (offset, String.valueOf(fnum));
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param dnum the double to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(double)
*/
public StringBuffer insert (int offset, double dnum)
{
return insert (offset, String.valueOf(dnum));
}
/** Insert the String value of the argument into this StringBuffer.
* Uses String.valueOf() to convert to
* String.
* @param offset the place to insert.
* @param obj the Object to convert and insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
* @see java.lang.String#valueOf(java.lang.Object)
*/
public StringBuffer insert (int offset, Object obj)
{
return insert (offset, String.valueOf(obj));
}
/** Insert the String argument into this StringBuffer.
* @param offset the place to insert.
* @param str the String to insert.
* @return this StringBuffer.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
*/
public synchronized StringBuffer insert (int offset, String str)
{
if (offset < 0 || offset > count)
throw new StringIndexOutOfBoundsException (offset);
// Note that using `null' is from JDK 1.2.
if (str == null)
str = "null";
int len = str.length();
ensureCapacity_unsynchronized (count+len);
System.arraycopy(value, offset, value, offset+len, count-offset);
str.getChars(0, len, value, offset);
count += len;
return this;
}
/** Insert the char[] argument into this
* StringBuffer.
* @param offset the place to insert.
* @param data the char[] to insert.
* @return this StringBuffer.
* @exception NullPointerException if data is
* null.
* @exception IndexOutOfBoundsException if offset is out
* of range for this StringBuffer.
*/
public StringBuffer insert (int offset, char[] data)
{
// One could check if offset is invalid here instead of making sure that
// data isn't null before dereferencing, but this works just as well.
return insert (offset, data, 0, data == null ? 0 : data.length);
}
/** Insert the char[] argument into this
* StringBuffer.
* @param offset the place to insert.
* @param str the char[] to insert.
* @param str_offset the index in str to start inserting
* from.
* @param len the number of characters to insert.
* @return this StringBuffer.
* @exception NullPointerException if str is null.
* @exception IndexOutOfBoundsException if offset is out
* of range, for this StringBuffer, or if
* str_offset or str_offset+len
* are out of range for str.
*/
public synchronized StringBuffer insert(int offset, char[] str,
int str_offset, int len)
{
if (offset < 0 || offset > count)
throw new StringIndexOutOfBoundsException (offset);
if (len < 0)
throw new StringIndexOutOfBoundsException (len);
if (str_offset < 0 || str_offset + len > str.length)
throw new StringIndexOutOfBoundsException (str_offset);
ensureCapacity_unsynchronized (count + len);
System.arraycopy(value, offset, value, offset + len, count - offset);
System.arraycopy(str, str_offset, value, offset, len);
count += len;
return this;
}
/** Get the length of the String this
* StringBuffer would create. Not to be confused with the
* capacity of the StringBuffer.
* @return the length of this StringBuffer.
* @see #capacity()
* @see #setLength(int)
*/
public int length ()
{
return count;
}
/** Replace characters between index start (inclusive) and
* end (exclusive) with str. If end
* is larger than the size of this StringBuffer, all characters after
* start are replaced.
* @param start the beginning index of characters to delete (inclusive).
* @param end the ending index of characters to delete (exclusive).
* @param str the new String to insert.
* @return this StringBuffer.
*/
public synchronized StringBuffer replace (int start, int end, String str)
{
if (start < 0 || start > count || start > end)
throw new StringIndexOutOfBoundsException (start);
int len = str.length();
// Calculate the difference in 'count' after the replace.
int delta = len - ((end > count ? count : end) - start);
ensureCapacity_unsynchronized (count + delta);
if (delta != 0 && end < count)
System.arraycopy(value, end, value, end + delta, count - end);
str.getChars (0, len, value, start);
count += delta;
return this;
}
/** Reverse the characters in this StringBuffer.
* @return this StringBuffer.
*/
public synchronized StringBuffer reverse ()
{
// Call ensureCapacity to enforce copy-on-write.
ensureCapacity_unsynchronized (count);
for (int i = 0; i < count / 2; ++i)
{
char c = value[i];
value[i] = value[count - i - 1];
value[count - i - 1] = c;
}
return this;
}
/** Set the character at the specified index.
* @param index the index of the character to set starting at 0.
* @param ch the value to set that character to.
* @exception IndexOutOfBoundsException if the specified character
* index is not between 0 and length() - 1 (inclusive).
*/
public synchronized void setCharAt (int index, char ch)
{
if (index < 0 || index >= count)
throw new StringIndexOutOfBoundsException (index);
// Call ensureCapacity to enforce copy-on-write.
ensureCapacity_unsynchronized (count);
value[index] = ch;
}
/** Set the length of this StringBuffer.
*
* If the new length is greater than the current length, all the new * characters are set to '\0'. *
* If the new length is less than the current length, the first
* newLength characters of the old array will be
* @param newLength the new length
* @exception IndexOutOfBoundsException if the new length is
* negative.
* @see #length()
*/
public synchronized void setLength (int newLength)
{
if (newLength < 0)
throw new StringIndexOutOfBoundsException (newLength);
ensureCapacity_unsynchronized (newLength);
for (int i = count; i < newLength; ++i)
value[i] = '\0';
count = newLength;
}
/** Create a new StringBuffer with default capacity 16.
* @see JLS 20.13.1
*/
public StringBuffer ()
{
this (DEFAULT_CAPACITY);
}
/** Create an empty StringBuffer with the specified initial capacity.
* @param capacity the initial capacity.
*/
public StringBuffer (int capacity)
{
count = 0;
value = new char[capacity];
shared = false;
}
/** Create a new StringBuffer with the characters in the specified String.
* Initial capacity will be the size of the String plus 16.
* @param str the String to make a StringBuffer out of.
* @XXX optimize for sharing.
*/
public StringBuffer (String str)
{
// The documentation is not clear, but experimentation with
// other implementations indicates that StringBuffer(null)
// should throw a NullPointerException.
count = str.length();
// JLS: The initial capacity of the string buffer is 16 plus the
// length of the argument string.
value = new char[count + DEFAULT_CAPACITY];
str.getChars(0, count, value, 0);
shared = false;
}
/**
* Creates a substring of this StringBuffer, starting at a specified index
* and ending at the end of this StringBuffer.
*
* @param beginIndex index to start substring (base 0)
*
* @return new String which is a substring of this StringBuffer
*
* @exception StringIndexOutOfBoundsException
* if (beginIndex < 0 || beginIndex > this.length())
*/
public String substring (int beginIndex)
{
return substring (beginIndex, count);
}
/**
* Creates a substring of this StringBuffer, starting at a specified index
* and ending at one character before a specified index.
*
* @param beginIndex index to start substring (base 0)
* @param endIndex index after the last character to be
* copied into the substring
*
* @return new String which is a substring of this StringBuffer
*
* @exception StringIndexOutOfBoundsException
* if (beginIndex < 0 || endIndex > this.length() || beginIndex > endIndex)
*/
public synchronized String substring (int beginIndex, int endIndex)
{
if (beginIndex < 0 || endIndex > count || beginIndex > endIndex)
throw new StringIndexOutOfBoundsException ();
// FIXME: for libgcj it would be possible, and more efficient, to
// enable sharing here.
return new String (value, beginIndex, endIndex - beginIndex);
}
/**
* Creates a substring of this StringBuffer, starting at a specified index
* and ending at one character before a specified index.
*
* To implement CharSequence.
* Calls substring(beginIndex, endIndex).
*
* @param beginIndex index to start substring (base 0)
* @param endIndex index after the last character to be
* copied into the substring
*
* @return new String which is a substring of this StringBuffer
*
* @exception StringIndexOutOfBoundsException
* if (beginIndex < 0 || endIndex > this.length() || beginIndex > endIndex)
*/
public CharSequence subSequence (int beginIndex, int endIndex)
{
return substring(beginIndex, endIndex);
}
/** Convert this StringBuffer to a String.
* @return the characters in this StringBuffer
*/
public String toString ()
{
// Note: in libgcj this causes the StringBuffer to be shared. In
// Classpath it does not.
return new String (this);
}
// Index of next available character. Note that this has
// permissions set this way so that String can get the value.
int count;
// The buffer. Note that this has permissions set this way so that
// String can get the value.
char[] value;
// True if we need to copy the buffer before writing to it again.
// FIXME: JDK 1.2 doesn't specify this. The new buffer-growing
// semantics make this less useful in that case, too. Note that
// this has permissions set this way so that String can get the
// value.
boolean shared;
static final long serialVersionUID = 3388685877147921107L;
private final static int DEFAULT_CAPACITY = 16; // JLS 20.13.1
}