## calypso.util
Class StringBuf

    java.lang.Object
      |
      +--calypso.util.StringBuf

public final class StringBuf
extends java.lang.Object

This class is similar to java/lang/StringBuffer with the following changes:

- None of the methods are synchronized
- There is no sharing of the character array
- Converting to a String requires a copy of the character data
- Alloc and Recycle are provided to speed up allocation
- A bunch of useful operations are provided (comparisons, etc.)

Constructor Summary
`StringBuf()` Constructs an empty String buffer.
`StringBuf(char[] chars, int offset, int length)`
`StringBuf(int length)` Constructs an empty String buffer with the specified initial length.
`StringBuf(java.lang.String str)` Constructs a String buffer with the specified initial value.

Method Summary
`static StringBuf` | `Alloc()` Constructs an empty String buffer, reusing one from the recycler.
`StringBuf` | `append(boolean b)` Appends a boolean to the end of this buffer.
`StringBuf` | `append(char c)` Appends a character to the end of this buffer.
`StringBuf` | `append(char[] str)` Appends an array of characters to the end of this buffer.
`StringBuf` | `append(char[] str, int offset, int len)` Appends a part of an array of characters to the end of this buffer.
`StringBuf` | `append(double d)` Appends a double to the end of this buffer.
`StringBuf` | `append(float f)` Appends a float to the end of this buffer.
`StringBuf` | `append(int i)` Appends an integer to the end of this buffer.
`StringBuf` | `append(long l)` Appends a long to the end of this buffer.
`StringBuf` | `append(java.lang.Object obj)` Appends an object to the end of this buffer.
`StringBuf` | `append(java.lang.String str)` Appends a String to the end of this buffer.
`StringBuf` | `assign(char[] str)`
`StringBuf` | `assign(char[] str, int offset, int len)`
`StringBuf` | `assign(java.lang.String str)`
`int` | `capacity()` Returns the current capacity of the String buffer.
`char` | `charAt(int index)` Returns the character at the specified index.
`void` | `compressWhitespace(boolean aStripLeadingWhitespace)` Compress the whitespace present in the buffer.
`static void` | `EmptyRecycler()` Empty the recycler discarding any cached StringBuf objects
`void` | `ensureCapacity(int minimumCapacity)` Ensures that the capacity of the buffer is at least equal to the specified minimum.
`boolean` | `equals(java.lang.Object aObject)`
`boolean` | `equals(java.lang.String anotherString)` Compares this StringBuf to another String.
`boolean` | `equals(StringBuf anotherString)` Compares this StringBuf to another StringBuf.
`boolean` | `equalsIgnoreCase(int aStart, int aLength, java.lang.String anotherString)`
`boolean` | `equalsIgnoreCase(java.lang.String anotherString)` Compares this StringBuf to another String.
`boolean` | `equalsIgnoreCase(StringBuf anotherString)` Compares this StringBuf to another StringBuf.
`void` | `getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)` Copies the characters of the specified substring (determined by srcBegin and srcEnd) into the character array, starting at the array's dstBegin location.
`int` | `indexOf(int ch)`
`int` | `indexOf(int ch, int fromIndex)`
`StringBuf` | `insert(int offset, boolean b)` Inserts a boolean into the String buffer.
`StringBuf` | `insert(int offset, char c)` Inserts a character into the String buffer.
`StringBuf` | `insert(int offset, char[] str)` Inserts an array of characters into the String buffer.
`StringBuf` | `insert(int offset, double d)` Inserts a double into the String buffer.
`StringBuf` | `insert(int offset, float f)` Inserts a float into the String buffer.
`StringBuf` | `insert(int offset, int i)` Inserts an integer into the String buffer.
`StringBuf` | `insert(int offset, long l)` Inserts a long into the String buffer.
`StringBuf` | `insert(int offset, java.lang.Object obj)` Inserts an object into the String buffer.
`StringBuf` | `insert(int offset, java.lang.String str)` Inserts a String into the String buffer.
`boolean` | `isWhitespace()` Return true if the string buffer contains nothing but whitespace as defined by Character.isWhitespace()
`int` | `length()` Returns the length (character count) of the buffer.
`static void` | `Recycle(StringBuf aBuf)` Release a StringBuf to the recycler.
`void` | `remove(int fromIndex)`
`void` | `remove(int fromIndex, int toIndex)` Remove characters from the StringBuf starting at fromIndex and up to but not including toIndex.
`StringBuf` | `reverse()` Reverse the order of the characters in the String buffer.
`void` | `setCharAt(int index, char ch)` Changes the character at the specified index to be ch.
`void` | `setEmpty()` Clear the content for reuse.
`void` | `setLength(int newLength)` Sets the length of the String.
`char[]` | `toChars()`
`void` | `toLowerCase()`
`java.lang.String` | `toString()` Converts to a String representing the data in the buffer.
`void` | `toUpperCase()`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### StringBuf

    public StringBuf()

  Constructs an empty String buffer.

### StringBuf

    public StringBuf(int length)

  Constructs an empty String buffer with the specified initial length.
  Parameters:
    `length` - the initial length

### StringBuf

    public StringBuf(java.lang.String str)

  Constructs a String buffer with the specified initial value.
  Parameters:
    `str` - the initial value of the buffer

### StringBuf

    public StringBuf(char[] chars,
                     int offset,
                     int length)

Method Detail

### Alloc

    public static StringBuf Alloc()

  Constructs an empty String buffer, reusing one from the recycler.

### Recycle

    public static void Recycle(StringBuf aBuf)

  Release a StringBuf to the recycler. It is up to the caller to ensure that buffer is no longer being used otherwise unpredicatable program behavior will result.

### EmptyRecycler

    public static void EmptyRecycler()

  Empty the recycler discarding any cached StringBuf objects

### length

    public int length()

  Returns the length (character count) of the buffer.

### capacity

    public int capacity()

  Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur.

### ensureCapacity

    public void ensureCapacity(int minimumCapacity)

  Ensures that the capacity of the buffer is at least equal to the specified minimum.
  Parameters:
    `minimumCapacity` - the minimum desired capacity

### setLength

    public void setLength(int newLength)

  Sets the length of the String. If the length is reduced, characters are lost. If the length is extended, the values of the new characters are set to 0.
  Parameters:
    `newLength` - the new length of the buffer
  Throws:
    StringIndexOutOfBoundsException - If the length is invalid.

### setEmpty

    public void setEmpty()

  Clear the content for reuse. Farster than setLength(0).

### charAt

    public char charAt(int index)

  Returns the character at the specified index. An index ranges from 0..length()-1.
  Parameters:
    `index` - the index of the desired character
  Throws:
    StringIndexOutOfBoundsException - If the index is invalid.

### getChars

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

  Copies the characters of the specified substring (determined by srcBegin and srcEnd) into the character array, starting at the array's dstBegin location. Both srcBegin and srcEnd must be legal indexes into the buffer.
  Parameters:
    `srcBegin` - begin copy at this offset in the String
    `srcEnd` - stop copying at this offset in the String
    `dst` - the array to copy the data into
    `dstBegin` - offset into dst
  Throws:
    StringIndexOutOfBoundsException - If there is an invalid index into the buffer.

### setCharAt

    public void setCharAt(int index,
                          char ch)

  Changes the character at the specified index to be ch.
  Parameters:
    `index` - the index of the character
    `ch` - the new character
  Throws:
    StringIndexOutOfBoundsException - If the index is invalid.

### append

    public StringBuf append(java.lang.Object obj)

  Appends an object to the end of this buffer.
  Parameters:
    `obj` - the object to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(java.lang.String str)

  Appends a String to the end of this buffer.
  Parameters:
    `str` - the String to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(char[] str)

  Appends an array of characters to the end of this buffer.
  Parameters:
    `str` - the characters to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### assign

    public StringBuf assign(char[] str)

### assign

    public StringBuf assign(java.lang.String str)

### assign

    public StringBuf assign(char[] str,
                            int offset,
                            int len)

### append

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

  Appends a part of an array of characters to the end of this buffer.
  Parameters:
    `str` - the characters to be appended
    `offset` - where to start
    `len` - the number of characters to add
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(boolean b)

  Appends a boolean to the end of this buffer.
  Parameters:
    `b` - the boolean to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(char c)

  Appends a character to the end of this buffer.
  Parameters:
    `ch` - the character to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(int i)

  Appends an integer to the end of this buffer.
  Parameters:
    `i` - the integer to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(long l)

  Appends a long to the end of this buffer.
  Parameters:
    `l` - the long to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(float f)

  Appends a float to the end of this buffer.
  Parameters:
    `f` - the float to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### append

    public StringBuf append(double d)

  Appends a double to the end of this buffer.
  Parameters:
    `d` - the double to be appended
  Returns:
    the StringBuf itself, NOT a new one.

### insert

    public StringBuf insert(int offset,
                            java.lang.Object obj)

  Inserts an object into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `obj` - the object to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            java.lang.String str)

  Inserts a String into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `str` - the String to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            char[] str)

  Inserts an array of characters into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `str` - the characters to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            boolean b)

  Inserts a boolean into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `b` - the boolean to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            char c)

  Inserts a character into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `ch` - the character to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset invalid.

### insert

    public StringBuf insert(int offset,
                            int i)

  Inserts an integer into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `i` - the integer to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            long l)

  Inserts a long into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `l` - the long to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            float f)

  Inserts a float into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `f` - the float to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public StringBuf insert(int offset,
                            double d)

  Inserts a double into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `d` - the double to insert
  Returns:
    the StringBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### reverse

    public StringBuf reverse()

  Reverse the order of the characters in the String buffer.

### toUpperCase

    public void toUpperCase()

### toLowerCase

    public void toLowerCase()

### toString

    public java.lang.String toString()

  Converts to a String representing the data in the buffer.
  Overrides:
    toString in class java.lang.Object

### toChars

    public char[] toChars()

### compressWhitespace

    public void compressWhitespace(boolean aStripLeadingWhitespace)

  Compress the whitespace present in the buffer. XXX I suppose there are i18n issues with this after all a space is probably not a space...

### isWhitespace

    public boolean isWhitespace()

  Return true if the string buffer contains nothing but whitespace as defined by Character.isWhitespace()

### equalsIgnoreCase

    public boolean equalsIgnoreCase(java.lang.String anotherString)

  Compares this StringBuf to another String. Returns true if the String is equal to this StringBuf; that is, has the same length and the same characters in the same sequence. Upper case characters are folded to lower case before they are compared.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### equalsIgnoreCase

    public boolean equalsIgnoreCase(int aStart,
                                    int aLength,
                                    java.lang.String anotherString)

### equalsIgnoreCase

    public boolean equalsIgnoreCase(StringBuf anotherString)

  Compares this StringBuf to another StringBuf. Returns true if the other StringBuf is equal to this StringBuf; that is, has the same length and the same characters in the same sequence. Upper case characters are folded to lower case before they are compared.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### equals

    public boolean equals(java.lang.Object aObject)

  Overrides:
    equals in class java.lang.Object

### equals

    public boolean equals(StringBuf anotherString)

  Compares this StringBuf to another StringBuf. Returns true if the other StringBuf is equal to this StringBuf; that is, has the same length and the same characters in the same sequence.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### equals

    public boolean equals(java.lang.String anotherString)

  Compares this StringBuf to another String. Returns true if the other String is equal to this StringBuf; that is, has the same length and the same characters in the same sequence.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### indexOf

    public int indexOf(int ch)

### indexOf

    public int indexOf(int ch,
                       int fromIndex)

### remove

    public void remove(int fromIndex)

### remove

    public void remove(int fromIndex,
                       int toIndex)

  Remove characters from the StringBuf starting at fromIndex and up to but not including toIndex. If toIndex is beyond the length of the StringBuf then it is automatically clamped to the end of the StringBuf. If fromIndex is out of range a StringIndexOutOfBoundsException is thrown.