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.

Version:

$Revision: 6735 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

StringBuilder, XStringBuffer

Field Summary

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

METACHAR_SEQUENCE_START

Constructor Summary

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

int	capacity() Return the current capacity of the buffer (i.e., the number of characters left before truncation will occur).
protected void	deleteCharacters(int start, int end) Remove the characters in a substring of this XStringBuilder.
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.
protected java.lang.Appendable	getBufferAsAppendable() Get the underlying buffer (e.g., StringBuilder, StringBuilder) as an Appender object.
protected java.lang.CharSequence	getBufferAsCharSequence() Get the underlying buffer (e.g., StringBuilder, StringBuilder) as a CharSequence object.
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.
protected void	insertCharacter(int index, char ch) Insert a single character into the buffer at a specified position.
protected void	insertCharacters(int index, char[] chars, int offset, int len) Insert characters from a character array into the buffer at a specified position.
protected java.lang.CharSequence	newBufferAsCharSequence() Get a new instance of the underlying buffer type (e.g., StringBuilder, StringBuilder) as a CharSequence object.
protected void	replaceString(int start, int end, java.lang.String str) Replace the characters in a substring of this buffer with characters in the specified String.
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

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

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.

getBufferAsAppendable

protected java.lang.Appendable getBufferAsAppendable()

Get the underlying buffer (e.g., StringBuilder, StringBuilder) as an Appender object.

Specified by:

getBufferAsAppendable in class XStringBufBase

Returns:

the Appender

newBufferAsCharSequence

protected java.lang.CharSequence newBufferAsCharSequence()

Get a new instance of the underlying buffer type (e.g., StringBuilder, StringBuilder) as a CharSequence object.

Specified by:

newBufferAsCharSequence in class XStringBufBase

Returns:

the Appendable

getBufferAsCharSequence

protected java.lang.CharSequence getBufferAsCharSequence()

Get the underlying buffer (e.g., StringBuilder, StringBuilder) as a CharSequence object.

Specified by:

getBufferAsCharSequence in class XStringBufBase

Returns:

the Appendable

deleteCharacters

protected void deleteCharacters(int start,
                                int end)
                         throws java.lang.IndexOutOfBoundsException

Remove the characters in a substring of this XStringBuilder. The substring begins at the specified start and extends to the character at index end - 1, or to the end of the string, if no such character exists. If start is equal to end, no changes are made.

Specified by:

deleteCharacters in class XStringBufBase

Parameters:

start - The beginning index, inclusive

end - The ending index, exclusive

Throws:

java.lang.IndexOutOfBoundsException - if start is negative, greater than length(), or greater than end

insertCharacter

protected void insertCharacter(int index,
                               char ch)

Insert a single character into the buffer at a specified position. Note that an insertion operation may push characters off the end of the buffer.

Specified by:

insertCharacter in class XStringBufBase

Parameters:

index - Where to start inserting in the string buffer

ch - The character to insert

insertCharacters

protected void insertCharacters(int index,
                                char[] chars,
                                int offset,
                                int len)

Insert characters from a character array into the buffer at a specified position. Note that an insertion operation may push characters off the end of the buffer.

Specified by:

insertCharacters in class XStringBufBase

Parameters:

index - Where to start inserting in the string buffer

chars - The character(s) to insert

offset - The starting position in the chars array

len - The number of characters to insert

replaceString

protected void replaceString(int start,
                             int end,
                             java.lang.String str)
                      throws java.lang.IndexOutOfBoundsException

Replace the characters in a substring of this buffer with characters in the specified String. The substring begins at the specified start and extends to the character at index end - 1, or to the end of the XStringBuilder if no such character exists. First the characters in the substring are removed and then the specified String is inserted at start. (The XStringBuilder will be lengthened to accommodate the specified String if necessary.)

Specified by:

replaceString in class XStringBufBase

Parameters:

start - The beginning index, inclusive

end - The ending index, exclusive

str - The string that will replace the previous contents

Throws:

java.lang.IndexOutOfBoundsException - if start is negative, or greater than length(), or greater than end