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.

Version:

$Revision: 6735 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

StringBuffer, XStringBuilder

Field Summary

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

METACHAR_SEQUENCE_START

Constructor Summary

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

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 XStringBuffer.
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.
protected java.lang.Appendable	getBufferAsAppendable() Get the underlying buffer (e.g., StringBuffer, StringBuilder) as an Appender object.
protected java.lang.CharSequence	getBufferAsCharSequence() Get the underlying buffer (e.g., StringBuffer, 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., StringBuffer, 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 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

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

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

getBufferAsAppendable

protected java.lang.Appendable getBufferAsAppendable()

Get the underlying buffer (e.g., StringBuffer, 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., StringBuffer, 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., StringBuffer, 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 XStringBuffer. 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 XStringBuffer if no such character exists. First the characters in the substring are removed and then the specified String is inserted at start. (The XStringBuffer 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