org.clapper.util.text

Class XStringBuilder

java.lang.Object

org.clapper.util.text.XStringBufBase

org.clapper.util.text.XStringBuilder

All Implemented Interfaces:

java.lang.Appendable, java.lang.CharSequence

public class XStringBuilder
extends XStringBufBase

An XStringBuilder objects wraps a standard Java StringBuilder object, providing a superset of StringBuilder's functionality. (XStringBuilder cannot actually subclass StringBuilder, since StringBuilder 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. (StringBuilder only provides a delete() method that takes a starting and ending index.)
• A replace() method that replaces the first occurrence of a substring. (StringBuilder 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 XStringBuilder wraps a StringBuilder, it is not thread-safe; but, it is likely to be faster than a StringBuffer or an XStringBuffer. For applications or methods that must to worry about multiple threads modifying the buffer concurrently, consider using the XStringBuffer class, instead.

See Also:

StringBuilder, XStringBuffer

Field Summary

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

METACHAR_SEQUENCE_START

Constructor Summary

Constructors

Constructor and Description
XStringBuilder() Construct an empty XStringBuilder object with a default initial capacity (the same initial capacity as an empty StringBuilder object).
XStringBuilder(int length) Construct an empty XStringBuilder object with the specified initial capacity.
XStringBuilder(java.lang.String initialContents) Construct a XStringBuilder 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).
XStringBuilder	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 XStringBuilder.
void	trimToSize() Attempts to reduce storage used for the character sequence.

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

XStringBuilder

public XStringBuilder()

Construct an empty XStringBuilder object with a default initial capacity (the same initial capacity as an empty StringBuilder object).

XStringBuilder

public XStringBuilder(int length)

Construct an empty XStringBuilder object with the specified initial capacity.

Parameters:

length - The initial capacity

XStringBuilder

public XStringBuilder(java.lang.String initialContents)

Construct a XStringBuilder object so that it represents the same sequence of characters as the String argument. (The String contrents are copied into the XStringBuilder 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 XStringBuilder 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 XStringBuilder. 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

trimToSize

public void trimToSize()

Attempts to reduce storage used for the character sequence. If the buffer is larger than necessary to hold its current sequence of characters, then it may be resized to become more space efficient. Calling this method may, but is not required to, affect the value returned by a subsequent call to the capacity() method.