com.jcorporate.expresso.kernel.util
Class FastStringBuffer

java.lang.Object
  com.jcorporate.expresso.kernel.util.FastStringBuffer

All Implemented Interfaces:

Serializable

public final class FastStringBuffer

extends Object

implements Serializable

A fast string buffer implements a mutable sequence of characters.

Fast string buffers are unsafe for use by multiple threads.

Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to allocate a new internal buffer array. If the internal buffer overflows, it is automatically made larger.

There are several performance improvements that make it worthwhile to use this class over the standard JDK StringBuffer

• Method calls are unsynchronized. Calls to synchronized methods are automatically at least four times slower than unsynchronized methods
• Pooling. By using the pooling mechanism, you basically remove all string allocation overhead and the fast string buffer is most likely pre-allocated to a size you'll use
• Non-zeroing out. StringBuffer zero's out it's character array, even though it's not necessary. FastStringBuffer doesn't perform any memory zeroing
• Parameter Checks removed. FastStringBuffer doesn't perform any out of bounds checks against incoming strings and parameters. This automatically saves overhead at the expense of you potentially getting less descriptive error messages
• Reuse. By calling the clear() method you can reuse a FastStringBuffer thus saving yourself a lot of memory allocations

Since:

Expresso 4.0, Pooling Mechanism since Expreso 5.0

See Also:

ByteArrayOutputStream, StringBuffer, Serialized Form

Constructor Summary

FastStringBuffer()
Constructs a string buffer with no characters in it and an initial capacity of 16 characters.

FastStringBuffer(int length)
Constructs a string buffer with no characters in it and an initial capacity specified by the length argument.

FastStringBuffer(String str)
Constructs a string buffer so that it represents the same sequence of characters as the string argument.

Method Summary

FastStringBuffer	append(boolean b) Appends the string representation of the boolean argument to the string buffer.
FastStringBuffer	append(char c) Appends the string representation of the char argument to this string buffer.
FastStringBuffer	append(char[] str) Appends the string representation of the char array argument to this string buffer.
FastStringBuffer	append(char[] str, int offset, int len) Appends the string representation of a subarray of the char array argument to this string buffer.
FastStringBuffer	append(double d) Appends the string representation of the double argument to this string buffer.
FastStringBuffer	append(FastStringBuffer str) Appends one FastStringBuffer to another so they can be merged with no unnecessary allocations
FastStringBuffer	append(float f) Appends the string representation of the float argument to this string buffer.
FastStringBuffer	append(int i) Appends the string representation of the int argument to this string buffer.
FastStringBuffer	append(long l) Appends the string representation of the long argument to this string buffer.
FastStringBuffer	append(Object obj) Appends the string representation of the Object argument to this string buffer.
FastStringBuffer	append(String str) Appends the string to this string buffer.
int	capacity() Returns the current capacity of the String buffer.
char	charAt(int index) Returns the character at a specific index in this string buffer.
void	clear() Clears the buffer and prepares it for reuse.
void	ensureCapacity(int minimumCapacity) Ensures that the capacity of the buffer is at least equal to the specified minimum.
void	getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin) Characters are copied from this string buffer into the destination character array dst.
static FastStringBuffer	getInstance() Retrieve an instance of FastString buffer from the object pool.
int	length() Returns the length (character count) of this string buffer.
void	release() Sends the FastStringBuffer back to the object pool.
FastStringBuffer	reverse() The character sequence contained in this string buffer is replaced by the reverse of the sequence.
void	setCharAt(int index, char ch) The character at the specified index of this string buffer is set to ch.
void	setLength(int newLength) Sets the length of this String buffer.
String	toString() Converts to a string representing the data in this string buffer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FastStringBuffer

public FastStringBuffer()

Constructs a string buffer with no characters in it and an initial capacity of 16 characters.

FastStringBuffer

public FastStringBuffer(int length)

Constructs a string buffer with no characters in it and an initial capacity specified by the length argument.

Parameters:

length - the initial capacity.

Throws:

NegativeArraySizeException - if the length argument is less than 0.

FastStringBuffer

public FastStringBuffer(String str)

Constructs a string buffer so that it represents the same sequence of characters as the string argument. The initial capacity of the string buffer is 16 plus the length of the string argument.

Parameters:

str - the initial contents of the buffer.

Method Detail

length

public int length()

Returns the length (character count) of this string buffer.

Returns:

the number of characters in this string 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.

Returns:

the current capacity of this string buffer.

clear

public void clear()

Clears the buffer and prepares it for reuse.

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of:

• The minimumCapacity argument.
• Twice the old capacity, plus 2.

If the minimumCapacity argument is nonpositive, this method takes no action and simply returns.

Parameters:

minimumCapacity - the minimum desired capacity.

setLength

public void setLength(int newLength)

Sets the length of this String buffer. If the newLength argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the newLength argument.

If the newLength argument is greater than or equal to the current length, sufficient null characters ('\u0000') are appended to the string buffer so that length becomes the newLength argument.

The newLength argument must be greater than or equal to 0.

Parameters:

newLength - the new length of the buffer.

See Also:

StringBuffer.length()

charAt

public char charAt(int index)

Returns the character at a specific index in this string buffer.

The first character of a string buffer is at index 0, the next at index 1, and so on, for array indexing.

The index argument must be greater than or equal to 0, and less than the length of this string buffer.

Parameters:

index - the index of the desired character.

Returns:

the character at the specified index of this string buffer.

See Also:

StringBuffer.length()

getChars

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

Characters are copied from this string buffer into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index:

     dstbegin + (srcEnd-srcBegin) - 1
 

Parameters:

srcBegin - start copying at this offset in the string buffer.

srcEnd - stop copying at this offset in the string buffer.

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)

The character at the specified index of this string buffer is set to ch.

The offset argument must be greater than or equal to 0, and less than the length of this string buffer.

Parameters:

index - the index of the character to modify.

ch - the new character.

Throws:

StringIndexOutOfBoundsException - if the index is invalid.

See Also:

StringBuffer.length()

append

public FastStringBuffer append(Object obj)

Appends the string representation of the Object argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

obj - an Object.

Returns:

this string buffer.

See Also:

String.valueOf(java.lang.Object), StringBuffer.append(java.lang.String)

append

public FastStringBuffer append(String str)

Appends the string to this string buffer.

The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument.

Parameters:

str - a string.

Returns:

this string buffer.

append

public FastStringBuffer append(char[] str)

Appends the string representation of the char array argument to this string buffer.

The characters of the array argument are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the length of the argument.

Parameters:

str - the characters to be appended.

Returns:

this string buffer.

append

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

Appends the string representation of a subarray of the char array argument to this string buffer.

Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of len.

Parameters:

str - the characters to be appended.

offset - the index of the first character to append.

len - the number of characters to append.

Returns:

this string buffer.

append

public FastStringBuffer append(FastStringBuffer str)

Appends one FastStringBuffer to another so they can be merged with no unnecessary allocations

Parameters:

str - The string buffer to append to.

Returns:

this string buffer

append

public FastStringBuffer append(boolean b)

Appends the string representation of the boolean argument to the string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

b - a boolean.

Returns:

this string buffer.

See Also:

String.valueOf(boolean), StringBuffer.append(java.lang.String)

append

public FastStringBuffer append(char c)

Appends the string representation of the char argument to this string buffer.

The argument is appended to the contents of this string buffer. The length of this string buffer increases by 1.

Parameters:

c - a char.

Returns:

this string buffer.

append

public FastStringBuffer append(int i)

Appends the string representation of the int argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

i - an int.

Returns:

this string buffer.

See Also:

String.valueOf(int), StringBuffer.append(java.lang.String)

append

public FastStringBuffer append(long l)

Appends the string representation of the long argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

l - a long.

Returns:

this string buffer.

See Also:

String.valueOf(long), StringBuffer.append(java.lang.String)

append

public FastStringBuffer append(float f)

Appends the string representation of the float argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

f - a float.

Returns:

this string buffer.

See Also:

String.valueOf(float), StringBuffer.append(java.lang.String)

append

public FastStringBuffer append(double d)

Appends the string representation of the double argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

Parameters:

d - a double.

Returns:

this string buffer.

See Also:

String.valueOf(double), StringBuffer.append(java.lang.String)

reverse

public FastStringBuffer reverse()

The character sequence contained in this string buffer is replaced by the reverse of the sequence.

Returns:

this string buffer.

toString

public String toString()

Converts to a string representing the data in this string buffer. A new String object is allocated and initialized to contain the character sequence currently represented by this string buffer. This String is then returned. Subsequent changes to the string buffer do not affect the contents of the String.

Returns:

a string representation of the string buffer.

getInstance

public static FastStringBuffer getInstance()

Retrieve an instance of FastString buffer from the object pool. The object is often preallocated to a 1024 byte size from a pool of objects. This can drastically reduce small memory allocations and increate performance.

Returns:

an instantiaged FastStringBuffer instance.

release

public void release()

Sends the FastStringBuffer back to the object pool. Use this if you have obtained the FastStringBuffer instance through FastStringBuffer.getInstance()