org.clapper.util.text

Class XStringBuffer

java.lang.Object

org.clapper.util.text.XStringBufBase

org.clapper.util.text.XStringBuffer

All Implemented Interfaces:

java.lang.Appendable, java.lang.CharSequence

public class XStringBuffer
extends XStringBufBase

An XStringBuffer objects wraps a standard Java StringBuffer object, providing a superset of StringBuffer's functionality. (XStringBuffer cannot actually subclass StringBuffer, since StringBuffer is final.) Among the additional methods that this class provides are:

• A set of XStringBufBase.split() methods, to split the contents of the buffer on a delimiter
• A delete() method that deletes the first occurrence of a substring. (StringBuffer only provides a delete() method that takes a starting and ending index.)
• A replace() method that replaces the first occurrence of a substring. (StringBuffer only provides a replace() method that takes a starting and ending index.)
• A replaceAll() method to replace all occurrences of a substring with something else
• Methods to encode and decode metacharacter sequences in place. (See XStringBufBase.encodeMetacharacters() and XStringBufBase.decodeMetacharacters().)

Because XStringBuffer wraps a StringBuffer, it is thread-safe, but it can also be slower than a StringBuilder. For applications or methods that don't have to worry about thread safety, consider using the XStringBuilder class, instead.

See Also:

StringBuffer, XStringBuilder

Field Summary

Fields inherited from class org.clapper.util.text.XStringBufBase

METACHAR_SEQUENCE_START

Constructor Summary

Constructors

Constructor and Description
XStringBuffer() Construct an empty XStringBuffer object with a default initial capacity (the same initial capacity as an empty StringBuffer object).
XStringBuffer(int length) Construct an empty XStringBuffer object with the specified initial capacity.
XStringBuffer(java.lang.String initialContents) Construct a XStringBuffer object so that it represents the same sequence of characters as the String argument.

Method Summary

Modifier and Type	Method and Description
int	capacity() Return the current capacity of the buffer (i.e., the number of characters left before truncation will occur).
XStringBuffer	deleteCharAt(int index) Remove the character at the specified position in this object, shortening this object by one character.
void	ensureCapacity(int minimumCapacity) Ensure that the capacity of the buffer is at least equal to the specified minimum.
void	getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin) Copy the some or all of the contents of the buffer into a character array.
void	reverse() Reverse the contents of the buffer.
void	setCharAt(int index, char ch) Set the character at a specified index.
void	setLength(int newLength) Set the length of this XStringBuffer.
java.lang.StringBuffer	toStringBuffer() Return a standard StringBuffer containing a copy of the contents of this buffer.

Methods inherited from class org.clapper.util.text.XStringBufBase

append, append, append, append, append, append, append, append, append, append, append, append, append, charAt, clear, decodeMetacharacters, decodeMetacharacters, delete, delete, encodeMetacharacters, encodeMetacharacters, indexOf, indexOf, indexOf, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, length, replace, replace, replace, replaceAll, replaceAll, replaceAll, reset, split, split, split, split, split, subSequence, substring, substring, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints

Constructor Detail

XStringBuffer

public XStringBuffer()

Construct an empty XStringBuffer object with a default initial capacity (the same initial capacity as an empty StringBuffer object).

XStringBuffer

public XStringBuffer(int length)

Construct an empty XStringBuffer object with the specified initial capacity.

Parameters:

length - The initial capacity

XStringBuffer

public XStringBuffer(java.lang.String initialContents)

Construct a XStringBuffer object so that it represents the same sequence of characters as the String argument. (The String contrents are copied into the XStringBuffer object.)

Parameters:

initialContents - The initial contents

Method Detail

capacity

public int capacity()

Return the current capacity of the buffer (i.e., the number of characters left before truncation will occur).

Returns:

The capacity. A 0 means no more room is left, and all further inserted or appended characters will cause truncation.

See Also:

XStringBufBase.length()

deleteCharAt

public XStringBuffer deleteCharAt(int index)
                           throws java.lang.StringIndexOutOfBoundsException

Remove the character at the specified position in this object, shortening this object by one character.

Parameters:

index - Index of the character to remove

Returns:

This object

Throws:

java.lang.StringIndexOutOfBoundsException - if index is negative, or greater than or equal to length().

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Ensure 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 non-positive, this method returns without doing anything.

Parameters:

minimumCapacity - The minimum desirec capacity

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)
              throws java.lang.IndexOutOfBoundsException

Copy the some or all of the contents of the buffer into a character array. 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).

Specified by:

getChars in class XStringBufBase

Parameters:

srcBegin - Start copy from this offset in the string buffer

srcEnd - Stop copy from this offset in the string buffer

dst - Where to copy the characters.

dstBegin - Offset into dst

Throws:

java.lang.IndexOutOfBoundsException - invalid index

reverse

public void reverse()

Reverse the contents of the buffer.

setCharAt

public void setCharAt(int index,
                      char ch)
               throws java.lang.StringIndexOutOfBoundsException

Set the character at a specified index. The index parameter must be greater than or equal to 0, and less than the length of this string buffer.

Parameters:

index - The index at which to set the value.

ch - The character to store

Throws:

java.lang.StringIndexOutOfBoundsException - index out of range

setLength

public void setLength(int newLength)
               throws java.lang.IndexOutOfBoundsException

Set the length of this XStringBuffer. This string buffer is altered to represent a new character sequence whose length is specified by the argument. 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 the current length of the string buffer, the buffer is padded with null characters out to the new length.

Parameters:

newLength - the new length of the buffer

Throws:

java.lang.IndexOutOfBoundsException - newLength is negative

toStringBuffer

public java.lang.StringBuffer toStringBuffer()

Return a standard StringBuffer containing a copy of the contents of this buffer.

Returns:

The string buffer