javolution.text

Class TextBuilder

java.lang.Object

javolution.text.TextBuilder

All Implemented Interfaces:

java.io.Serializable, java.lang.Appendable, java.lang.CharSequence, Realtime, Reusable

public class TextBuilder
extends java.lang.Object
implements java.lang.Appendable, java.lang.CharSequence, Reusable, Realtime, java.io.Serializable

This class represents an Appendable text whose capacity expands gently without incurring expensive resize/copy operations ever.

This class is not intended for large documents manipulations which should be performed with the Text class directly (O(Log(n)) insertion and deletion capabilities).

This implementation is not synchronized.

Version:

5.3, January 20, 2008

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
TextBuilder()	Creates a text builder of small initial capacity.
TextBuilder(int capacity)	Creates a text builder of specified initial capacity.
TextBuilder(java.lang.String str)	Creates a text builder holding the specified String (convenience method).

Method Summary

Modifier and Type	Method	Description
TextBuilder	append(boolean b)	Appends the textual representation of the specified boolean argument.
TextBuilder	append(char c)	Appends the specified character.
TextBuilder	append(char[] chars)	Appends the characters from the char array argument.
TextBuilder	append(char[] chars, int offset, int length)	Appends the characters from a subarray of the char array argument.
TextBuilder	append(java.lang.CharSequence csq)	Appends the specified character sequence.
TextBuilder	append(java.lang.CharSequence csq, int start, int end)	Appends a subsequence of the specified character sequence.
TextBuilder	append(double d)	Appends the textual representation of the specified double; the number of digits is 17 or 16 when the 16 digits representation can be parsed back to the same double (mimic the standard library formatting).
TextBuilder	append(double d, int digits, boolean scientific, boolean showZero)	Appends the textual representation of the specified double according to the specified formatting arguments.
TextBuilder	append(float f)	Appends the textual representation of the specified float.
TextBuilder	append(int i)	Appends the decimal representation of the specified int argument.
TextBuilder	append(int i, int radix)	Appends the radix representation of the specified int argument.
TextBuilder	append(long l)	Appends the decimal representation of the specified long argument.
TextBuilder	append(long l, int radix)	Appends the radix representation of the specified long argument.
TextBuilder	append(java.lang.Object obj)	Appends the textual representation of the specified object.
TextBuilder	append(java.lang.String str)	Appends the specified string to this text builder.
TextBuilder	append(java.lang.String str, int start, int end)	Appends a subsequence of the specified string.
TextBuilder	append(Text txt)	Appends the specified text to this text builder.
TextBuilder	append(Text txt, int start, int end)	Appends a subsequence of the specified text.
char	charAt(int index)	Returns the character at the specified index.
TextBuilder	clear()	Removes all the characters of this text builder (equivalent to this.delete(start, this.length())).
boolean	contentEquals(java.lang.CharSequence csq)	Indicates if this text builder has the same character content as the specified character sequence.
boolean	contentEquals(java.lang.String csq)	Equivalent to contentEquals(CharSequence) (for J2ME compability).
TextBuilder	delete(int start, int end)	Removes the characters between the specified indices.
boolean	equals(java.lang.Object obj)	Compares this text builder against the specified object for equality.
void	getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)	Copies the character from this text builder into the destination character array.
int	hashCode()	Returns the hash code for this text builder.
TextBuilder	insert(int index, java.lang.CharSequence csq)	Inserts the specified character sequence at the specified location.
int	length()	Returns the length (character count) of this text builder.
static TextBuilder	newInstance()	Returns a new, preallocated or recycled text builder (on the stack when executing in a StackContext).
void	print()	Prints out this text builder to System.out (UTF-8 encoding).
void	print(java.io.Writer writer)	Prints out this text builder to the specified writer.
void	println()	Prints out this text builder to System.out and then terminates the line.
void	println(java.io.Writer writer)	Prints out this text builder to the specified writer and then terminates the line.
static void	recycle(TextBuilder instance)	Recycles a text builder instance immediately (on the stack when executing in a StackContext).
void	reset()	Resets this text builder for reuse (equivalent to clear()).
TextBuilder	reverse()	Reverses this character sequence.
void	setCharAt(int index, char c)	Sets the character at the specified position.
void	setLength(int newLength)	Convenience method equivalent to setLength(newLength, '').
void	setLength(int newLength, char fillChar)	Sets the length of this character builder.
java.lang.CharSequence	subSequence(int start, int end)	Returns a CharSequence corresponding to the character sequence between the specified indexes.
CharArray	toCharArray()	Returns the CharArray representation of this TextBuilder.
java.lang.String	toString()	Returns the String representation of this TextBuilder.
Text	toText()	Returns the Text corresponding to this TextBuilder (allocated on the "stack" when executing in a StackContext).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints

Constructor Detail

TextBuilder

public TextBuilder()

Creates a text builder of small initial capacity.

TextBuilder

public TextBuilder(java.lang.String str)

Creates a text builder holding the specified String (convenience method).

Parameters:

str - the initial string content of this text builder.

TextBuilder

public TextBuilder(int capacity)

Creates a text builder of specified initial capacity. Unless the text length exceeds the specified capacity, operations on this text builder will not allocate memory.

Parameters:

capacity - the initial capacity.

Method Detail

newInstance

public static TextBuilder newInstance()

Returns a new, preallocated or recycled text builder (on the stack when executing in a StackContext).

Returns:

a new, preallocated or recycled text builder instance.

recycle

public static void recycle(TextBuilder instance)

Recycles a text builder instance immediately (on the stack when executing in a StackContext).

length

public final int length()

Returns the length (character count) of this text builder.

Specified by:

length in interface java.lang.CharSequence

Returns:

the number of characters (16-bits Unicode).

charAt

public final char charAt(int index)

Returns the character at the specified index.

Specified by:

charAt in interface java.lang.CharSequence

Parameters:

index - the index of the character.

Returns:

the character at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= this.length()).

getChars

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

Copies the character from this text builder into the destination character array.

Parameters:

srcBegin - this text start index.

srcEnd - this text end index (not included).

dst - the destination array to copy the data into.

dstBegin - the offset into the destination array.

Throws:

java.lang.IndexOutOfBoundsException - if (srcBegin < 0) || (dstBegin < 0) || (srcBegin > srcEnd) || (srcEnd > this.length()) || ((dstBegin + srcEnd - srcBegin) > dst.length)

setCharAt

public final void setCharAt(int index,
                            char c)

Sets the character at the specified position.

Parameters:

index - the index of the character to modify.

c - the new character.

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= this.length())

setLength

public final void setLength(int newLength)

Convenience method equivalent to setLength(newLength, '').

Parameters:

newLength - the new length of this builder.

Throws:

java.lang.IndexOutOfBoundsException - if (newLength < 0)

setLength

public final void setLength(int newLength,
                            char fillChar)

Sets the length of this character builder. If the length is greater than the current length; the specified character is inserted.

Parameters:

newLength - the new length of this builder.

fillChar - the character to be appended if required.

Throws:

java.lang.IndexOutOfBoundsException - if (newLength < 0)

subSequence

public final java.lang.CharSequence subSequence(int start,
                                                int end)

Returns a CharSequence corresponding to the character sequence between the specified indexes.

Specified by:

subSequence in interface java.lang.CharSequence

Parameters:

start - the index of the first character inclusive.

end - the index of the last character exclusive.

Returns:

a character sequence.

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length())

append

public final TextBuilder append(char c)

Appends the specified character.

Specified by:

append in interface java.lang.Appendable

Parameters:

c - the character to append.

Returns:

this

append

public final TextBuilder append(java.lang.Object obj)

Appends the textual representation of the specified object. This method is equivalent to append(Text.valueOf(obj))

Parameters:

obj - the object to represent or null.

Returns:

this

See Also:

Text.valueOf(Object)

append

public final TextBuilder append(java.lang.CharSequence csq)

Appends the specified character sequence. If the specified character sequence is null this method is equivalent to append("null").

Specified by:

append in interface java.lang.Appendable

Parameters:

csq - the character sequence to append or null.

Returns:

this

append

public final TextBuilder append(java.lang.CharSequence csq,
                                int start,
                                int end)

Appends a subsequence of the specified character sequence. If the specified character sequence is null this method is equivalent to append("null").

Specified by:

append in interface java.lang.Appendable

Parameters:

csq - the character sequence to append or null.

start - the index of the first character to append.

end - the index after the last character to append.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > csq.length())

append

public final TextBuilder append(java.lang.String str)

Appends the specified string to this text builder. If the specified string is null this method is equivalent to append("null").

Parameters:

str - the string to append or null.

Returns:

this

append

public final TextBuilder append(java.lang.String str,
                                int start,
                                int end)

Appends a subsequence of the specified string. If the specified character sequence is null this method is equivalent to append("null").

Parameters:

str - the string to append or null.

start - the index of the first character to append.

end - the index after the last character to append.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > str.length())

append

public final TextBuilder append(Text txt)

Appends the specified text to this text builder. If the specified text is null this method is equivalent to append("null").

Parameters:

txt - the text to append or null.

Returns:

this

append

public final TextBuilder append(Text txt,
                                int start,
                                int end)

Appends a subsequence of the specified text. If the specified character sequence is null this method is equivalent to append("null").

Parameters:

txt - the text to append or null.

start - the index of the first character to append.

end - the index after the last character to append.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > txt.length())

append

public final TextBuilder append(char[] chars)

Appends the characters from the char array argument.

Parameters:

chars - the character array source.

Returns:

this

append

public final TextBuilder append(char[] chars,
                                int offset,
                                int length)

Appends the characters from a subarray of the char array argument.

Parameters:

chars - the character array source.

offset - the index of the first character to append.

length - the number of character to append.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (offset < 0) || (length < 0) || ((offset + length) > chars.length)

append

public final TextBuilder append(boolean b)

Appends the textual representation of the specified boolean argument.

Parameters:

b - the boolean to format.

Returns:

this

See Also:

TypeFormat

append

public final TextBuilder append(int i)

Appends the decimal representation of the specified int argument.

Parameters:

i - the int to format.

Returns:

this

append

public final TextBuilder append(int i,
                                int radix)

Appends the radix representation of the specified int argument.

Parameters:

i - the int to format.

radix - the radix (e.g. 16 for hexadecimal).

Returns:

this

append

public final TextBuilder append(long l)

Appends the decimal representation of the specified long argument.

Parameters:

l - the long to format.

Returns:

this

append

public final TextBuilder append(long l,
                                int radix)

Appends the radix representation of the specified long argument.

Parameters:

l - the long to format.

radix - the radix (e.g. 16 for hexadecimal).

Returns:

this

append

public final TextBuilder append(float f)

Appends the textual representation of the specified float.

Parameters:

f - the float to format.

Returns:

append(f, 10, (abs(f) >= 1E7) || (abs(f) < 0.001), false)

append

public final TextBuilder append(double d)

Appends the textual representation of the specified double; the number of digits is 17 or 16 when the 16 digits representation can be parsed back to the same double (mimic the standard library formatting).

Parameters:

d - the double to format.

Returns:

append(d, -1, (MathLib.abs(d) >= 1E7) || (MathLib.abs(d) < 0.001), false)

append

public final TextBuilder append(double d,
                                int digits,
                                boolean scientific,
                                boolean showZero)

Appends the textual representation of the specified double according to the specified formatting arguments.

Parameters:

d - the double value.

digits - the number of significative digits (excludes exponent) or -1 to mimic the standard library (16 or 17 digits).

scientific - true to forces the use of the scientific notation (e.g. 1.23E3); false otherwise.

showZero - true if trailing fractional zeros are represented; false otherwise.

Returns:

TypeFormat.format(d, digits, scientific, showZero, this)

Throws:

java.lang.IllegalArgumentException - if (digits > 19))

insert

public final TextBuilder insert(int index,
                                java.lang.CharSequence csq)

Inserts the specified character sequence at the specified location.

Parameters:

index - the insertion position.

csq - the character sequence being inserted.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index > this.length())

clear

public final TextBuilder clear()

Removes all the characters of this text builder (equivalent to this.delete(start, this.length())).

Returns:

this.delete(0, this.length())

delete

public final TextBuilder delete(int start,
                                int end)

Removes the characters between the specified indices.

Parameters:

start - the beginning index, inclusive.

end - the ending index, exclusive.

Returns:

this

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length())

reverse

public final TextBuilder reverse()

Reverses this character sequence.

Returns:

this

toText

public final Text toText()

Returns the Text corresponding to this TextBuilder (allocated on the "stack" when executing in a StackContext).

Specified by:

toText in interface Realtime

Returns:

the corresponding Text instance.

toString

public final java.lang.String toString()

Returns the String representation of this TextBuilder.

Specified by:

toString in interface java.lang.CharSequence

Overrides:

toString in class java.lang.Object

Returns:

the java.lang.String for this text builder.

toCharArray

public final CharArray toCharArray()

Returns the CharArray representation of this TextBuilder.

Returns:

the corresponding CharArray instance.

reset

public final void reset()

Resets this text builder for reuse (equivalent to clear()).

Specified by:

reset in interface Reusable

hashCode

public final int hashCode()

Returns the hash code for this text builder.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value.

equals

public final boolean equals(java.lang.Object obj)

Compares this text builder against the specified object for equality. Returns true if the specified object is a text builder having the same character content.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with or null.

Returns:

true if that is a text builder with the same character content as this text; false otherwise.

print

public void print()

Prints out this text builder to System.out (UTF-8 encoding). This method is equivalent to:

     synchronized(OUT) {
         print(OUT);
         OUT.flush();
     }
     ...
     static final OUT = new UTF8StreamWriter().setOutput(System.out);
 

println

public void println()

Prints out this text builder to System.out and then terminates the line. This method is equivalent to:

     synchronized(OUT) {
         println(OUT);
         OUT.flush();
     }
     ...
     static final OUT = new UTF8StreamWriter().setOutput(System.out);
 

print

public void print(java.io.Writer writer)
           throws java.io.IOException

Prints out this text builder to the specified writer.

Parameters:

writer - the destination writer.

Throws:

java.io.IOException

println

public void println(java.io.Writer writer)
             throws java.io.IOException

Prints out this text builder to the specified writer and then terminates the line.

Parameters:

writer - the destination writer.

Throws:

java.io.IOException

contentEquals

public final boolean contentEquals(java.lang.CharSequence csq)

Indicates if this text builder has the same character content as the specified character sequence.

Parameters:

csq - the character sequence to compare with.

Returns:

true if the specified character sequence has the same character content as this text; false otherwise.

contentEquals

public final boolean contentEquals(java.lang.String csq)

Equivalent to contentEquals(CharSequence) (for J2ME compability).

Parameters:

csq - the string character sequence to compare with.

Returns:

true if the specified string has the same character content as this text; false otherwise.