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
-}