public class TextStringBuilder extends Object implements CharSequence, Appendable, Serializable, Builder<String>
StringBuffer
and
StringBuilder
.
The main differences from StringBuffer/StringBuilder are:
The aim has been to provide an API that mimics very closely what StringBuffer provides, but with additional methods.
It should be noted that some edge cases, with invalid indices or null input, have been altered - see individual
methods. The biggest of these changes is that by default, null will not output the text 'null'. This can be
controlled by a property, setNullText(String)
.
This class is called TextStringBuilder
instead of StringBuilder
to avoid clashing with
StringBuilder
.
Constructor and Description |
---|
TextStringBuilder()
Constructs an empty builder with an initial capacity of 32 characters.
|
TextStringBuilder(CharSequence seq)
Constructs an instance from a character sequence, allocating 32 extra characters for growth.
|
TextStringBuilder(int initialCapacity)
Constructs an instance with the specified initial capacity.
|
TextStringBuilder(String str)
Constructs an instance from a string, allocating 32 extra characters for growth.
|
Modifier and Type | Method and Description |
---|---|
TextStringBuilder |
append(boolean value)
Appends a boolean value to the string builder.
|
TextStringBuilder |
append(char ch)
Appends a char value to the string builder.
|
TextStringBuilder |
append(char[] chars)
Appends a char array to the string builder.
|
TextStringBuilder |
append(char[] chars,
int startIndex,
int length)
Appends a char array to the string builder.
|
TextStringBuilder |
append(CharBuffer str)
Appends the contents of a char buffer to this string builder.
|
TextStringBuilder |
append(CharBuffer buf,
int startIndex,
int length)
Appends the contents of a char buffer to this string builder.
|
TextStringBuilder |
append(CharSequence seq)
Appends a CharSequence to this string builder.
|
TextStringBuilder |
append(CharSequence seq,
int startIndex,
int endIndex)
Appends part of a CharSequence to this string builder.
|
TextStringBuilder |
append(double value)
Appends a double value to the string builder using
String.valueOf . |
TextStringBuilder |
append(float value)
Appends a float value to the string builder using
String.valueOf . |
TextStringBuilder |
append(int value)
Appends an int value to the string builder using
String.valueOf . |
TextStringBuilder |
append(long value)
Appends a long value to the string builder using
String.valueOf . |
TextStringBuilder |
append(Object obj)
Appends an object to this string builder.
|
TextStringBuilder |
append(String str)
Appends a string to this string builder.
|
TextStringBuilder |
append(StringBuffer str)
Appends a string buffer to this string builder.
|
TextStringBuilder |
append(StringBuffer str,
int startIndex,
int length)
Appends part of a string buffer to this string builder.
|
TextStringBuilder |
append(StringBuilder str)
Appends a StringBuilder to this string builder.
|
TextStringBuilder |
append(StringBuilder str,
int startIndex,
int length)
Appends part of a StringBuilder to this string builder.
|
TextStringBuilder |
append(String str,
int startIndex,
int length)
Appends part of a string to this string builder.
|
TextStringBuilder |
append(String format,
Object... objs)
Calls
String.format(String, Object...) and appends the result. |
TextStringBuilder |
append(TextStringBuilder str)
Appends another string builder to this string builder.
|
TextStringBuilder |
append(TextStringBuilder str,
int startIndex,
int length)
Appends part of a string builder to this string builder.
|
TextStringBuilder |
appendAll(Iterable<?> iterable)
Appends each item in an iterable to the builder without any separators.
|
TextStringBuilder |
appendAll(Iterator<?> it)
Appends each item in an iterator to the builder without any separators.
|
<T> TextStringBuilder |
appendAll(T... array)
Appends each item in an array to the builder without any separators.
|
TextStringBuilder |
appendFixedWidthPadLeft(int value,
int width,
char padChar)
Appends an object to the builder padding on the left to a fixed width.
|
TextStringBuilder |
appendFixedWidthPadLeft(Object obj,
int width,
char padChar)
Appends an object to the builder padding on the left to a fixed width.
|
TextStringBuilder |
appendFixedWidthPadRight(int value,
int width,
char padChar)
Appends an object to the builder padding on the right to a fixed length.
|
TextStringBuilder |
appendFixedWidthPadRight(Object obj,
int width,
char padChar)
Appends an object to the builder padding on the right to a fixed length.
|
TextStringBuilder |
appendln(boolean value)
Appends a boolean value followed by a new line to the string builder.
|
TextStringBuilder |
appendln(char ch)
Appends a char value followed by a new line to the string builder.
|
TextStringBuilder |
appendln(char[] chars)
Appends a char array followed by a new line to the string builder.
|
TextStringBuilder |
appendln(char[] chars,
int startIndex,
int length)
Appends a char array followed by a new line to the string builder.
|
TextStringBuilder |
appendln(double value)
Appends a double value followed by a new line to the string builder using
String.valueOf . |
TextStringBuilder |
appendln(float value)
Appends a float value followed by a new line to the string builder using
String.valueOf . |
TextStringBuilder |
appendln(int value)
Appends an int value followed by a new line to the string builder using
String.valueOf . |
TextStringBuilder |
appendln(long value)
Appends a long value followed by a new line to the string builder using
String.valueOf . |
TextStringBuilder |
appendln(Object obj)
Appends an object followed by a new line to this string builder.
|
TextStringBuilder |
appendln(String str)
Appends a string followed by a new line to this string builder.
|
TextStringBuilder |
appendln(StringBuffer str)
Appends a string buffer followed by a new line to this string builder.
|
TextStringBuilder |
appendln(StringBuffer str,
int startIndex,
int length)
Appends part of a string buffer followed by a new line to this string builder.
|
TextStringBuilder |
appendln(StringBuilder str)
Appends a string builder followed by a new line to this string builder.
|
TextStringBuilder |
appendln(StringBuilder str,
int startIndex,
int length)
Appends part of a string builder followed by a new line to this string builder.
|
TextStringBuilder |
appendln(String str,
int startIndex,
int length)
Appends part of a string followed by a new line to this string builder.
|
TextStringBuilder |
appendln(String format,
Object... objs)
Calls
String.format(String, Object...) and appends the result. |
TextStringBuilder |
appendln(TextStringBuilder str)
Appends another string builder followed by a new line to this string builder.
|
TextStringBuilder |
appendln(TextStringBuilder str,
int startIndex,
int length)
Appends part of a string builder followed by a new line to this string builder.
|
TextStringBuilder |
appendNewLine()
Appends the new line string to this string builder.
|
TextStringBuilder |
appendNull()
Appends the text representing
null to this string builder. |
TextStringBuilder |
appendPadding(int length,
char padChar)
Appends the pad character to the builder the specified number of times.
|
TextStringBuilder |
appendSeparator(char separator)
Appends a separator if the builder is currently non-empty.
|
TextStringBuilder |
appendSeparator(char standard,
char defaultIfEmpty)
Appends one of both separators to the builder If the builder is currently empty it will append the
defaultIfEmpty-separator Otherwise it will append the standard-separator
The separator is appended using
append(char) . |
TextStringBuilder |
appendSeparator(char separator,
int loopIndex)
Appends a separator to the builder if the loop index is greater than zero.
|
TextStringBuilder |
appendSeparator(String separator)
Appends a separator if the builder is currently non-empty.
|
TextStringBuilder |
appendSeparator(String separator,
int loopIndex)
Appends a separator to the builder if the loop index is greater than zero.
|
TextStringBuilder |
appendSeparator(String standard,
String defaultIfEmpty)
Appends one of both separators to the StrBuilder.
|
void |
appendTo(Appendable appendable)
Appends current contents of this
StrBuilder to the provided Appendable . |
TextStringBuilder |
appendWithSeparators(Iterable<?> iterable,
String separator)
Appends an iterable placing separators between each value, but not before the first or after the last.
|
TextStringBuilder |
appendWithSeparators(Iterator<?> it,
String separator)
Appends an iterator placing separators between each value, but not before the first or after the last.
|
TextStringBuilder |
appendWithSeparators(Object[] array,
String separator)
Appends an array placing separators between each value, but not before the first or after the last.
|
Reader |
asReader()
Gets the contents of this builder as a Reader.
|
StringTokenizer |
asTokenizer()
Creates a tokenizer that can tokenize the contents of this builder.
|
Writer |
asWriter()
Gets this builder as a Writer that can be written to.
|
String |
build()
Implement the
Builder interface. |
int |
capacity()
Gets the current size of the internal character array buffer.
|
char |
charAt(int index)
Gets the character at the specified index.
|
TextStringBuilder |
clear()
Clears the string builder (convenience Collections API style method).
|
boolean |
contains(char ch)
Tests if the string builder contains the specified char.
|
boolean |
contains(String str)
Tests if the string builder contains the specified string.
|
boolean |
contains(StringMatcher matcher)
Tests if the string builder contains a string matched using the specified matcher.
|
TextStringBuilder |
delete(int startIndex,
int endIndex)
Deletes the characters between the two specified indices.
|
TextStringBuilder |
deleteAll(char ch)
Deletes the character wherever it occurs in the builder.
|
TextStringBuilder |
deleteAll(String str)
Deletes the string wherever it occurs in the builder.
|
TextStringBuilder |
deleteAll(StringMatcher matcher)
Deletes all parts of the builder that the matcher matches.
|
TextStringBuilder |
deleteCharAt(int index)
Deletes the character at the specified index.
|
TextStringBuilder |
deleteFirst(char ch)
Deletes the character wherever it occurs in the builder.
|
TextStringBuilder |
deleteFirst(String str)
Deletes the string wherever it occurs in the builder.
|
TextStringBuilder |
deleteFirst(StringMatcher matcher)
Deletes the first match within the builder using the specified matcher.
|
char |
drainChar(int index)
Gets the character at the specified index before deleting it.
|
int |
drainChars(int startIndex,
int endIndex,
char[] target,
int targetIndex)
Drains (copies, then deletes) this character sequence into the specified array.
|
boolean |
endsWith(String str)
Checks whether this builder ends with the specified string.
|
TextStringBuilder |
ensureCapacity(int capacity)
Tests the capacity and ensures that it is at least the size specified.
|
boolean |
equals(Object obj)
Tests the contents of this builder against another to see if they contain the same character content.
|
boolean |
equals(TextStringBuilder other)
Tests the contents of this builder against another to see if they contain the same character content.
|
boolean |
equalsIgnoreCase(TextStringBuilder other)
Tests the contents of this builder against another to see if they contain the same character content ignoring
case.
|
char[] |
getChars(char[] target)
Copies this character array into the specified array.
|
void |
getChars(int startIndex,
int endIndex,
char[] target,
int targetIndex)
Copies this character array into the specified array.
|
String |
getNewLineText()
Gets the text to be appended when a new line is added.
|
String |
getNullText()
Gets the text to be appended when null is added.
|
int |
hashCode()
Gets a suitable hash code for this builder.
|
int |
indexOf(char ch)
Searches the string builder to find the first reference to the specified char.
|
int |
indexOf(char ch,
int startIndex)
Searches the string builder to find the first reference to the specified char.
|
int |
indexOf(String str)
Searches the string builder to find the first reference to the specified string.
|
int |
indexOf(String str,
int startIndex)
Searches the string builder to find the first reference to the specified string starting searching from the given
index.
|
int |
indexOf(StringMatcher matcher)
Searches the string builder using the matcher to find the first match.
|
int |
indexOf(StringMatcher matcher,
int startIndex)
Searches the string builder using the matcher to find the first match searching from the given index.
|
TextStringBuilder |
insert(int index,
boolean value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
char value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
char[] chars)
Inserts the character array into this builder.
|
TextStringBuilder |
insert(int index,
char[] chars,
int offset,
int length)
Inserts part of the character array into this builder.
|
TextStringBuilder |
insert(int index,
double value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
float value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
int value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
long value)
Inserts the value into this builder.
|
TextStringBuilder |
insert(int index,
Object obj)
Inserts the string representation of an object into this builder.
|
TextStringBuilder |
insert(int index,
String str)
Inserts the string into this builder.
|
boolean |
isEmpty()
Checks is the string builder is empty (convenience Collections API style method).
|
boolean |
isNotEmpty()
Checks is the string builder is not empty.
|
boolean |
isReallocated()
Gets whether the internal buffer has been reallocated.
|
int |
lastIndexOf(char ch)
Searches the string builder to find the last reference to the specified char.
|
int |
lastIndexOf(char ch,
int startIndex)
Searches the string builder to find the last reference to the specified char.
|
int |
lastIndexOf(String str)
Searches the string builder to find the last reference to the specified string.
|
int |
lastIndexOf(String str,
int startIndex)
Searches the string builder to find the last reference to the specified string starting searching from the given
index.
|
int |
lastIndexOf(StringMatcher matcher)
Searches the string builder using the matcher to find the last match.
|
int |
lastIndexOf(StringMatcher matcher,
int startIndex)
Searches the string builder using the matcher to find the last match searching from the given index.
|
String |
leftString(int length)
Extracts the leftmost characters from the string builder without throwing an exception.
|
int |
length()
Gets the length of the string builder.
|
String |
midString(int index,
int length)
Extracts some characters from the middle of the string builder without throwing an exception.
|
TextStringBuilder |
minimizeCapacity()
Minimizes the capacity to the actual length of the string.
|
int |
readFrom(CharBuffer charBuffer)
If possible, reads chars from the provided
CharBuffer directly into underlying character buffer without
making extra copies. |
int |
readFrom(Readable readable)
If possible, reads all chars from the provided
Readable directly into underlying character buffer without
making extra copies. |
int |
readFrom(Reader reader)
If possible, reads all chars from the provided
Reader directly into underlying character buffer without
making extra copies. |
int |
readFrom(Reader reader,
int count)
If possible, reads
count chars from the provided Reader directly into underlying character buffer
without making extra copies. |
TextStringBuilder |
replace(int startIndex,
int endIndex,
String replaceStr)
Replaces a portion of the string builder with another string.
|
TextStringBuilder |
replace(StringMatcher matcher,
String replaceStr,
int startIndex,
int endIndex,
int replaceCount)
Advanced search and replaces within the builder using a matcher.
|
TextStringBuilder |
replaceAll(char search,
char replace)
Replaces the search character with the replace character throughout the builder.
|
TextStringBuilder |
replaceAll(StringMatcher matcher,
String replaceStr)
Replaces all matches within the builder with the replace string.
|
TextStringBuilder |
replaceAll(String searchStr,
String replaceStr)
Replaces the search string with the replace string throughout the builder.
|
TextStringBuilder |
replaceFirst(char search,
char replace)
Replaces the first instance of the search character with the replace character in the builder.
|
TextStringBuilder |
replaceFirst(StringMatcher matcher,
String replaceStr)
Replaces the first match within the builder with the replace string.
|
TextStringBuilder |
replaceFirst(String searchStr,
String replaceStr)
Replaces the first instance of the search string with the replace string.
|
TextStringBuilder |
reverse()
Reverses the string builder placing each character in the opposite index.
|
String |
rightString(int length)
Extracts the rightmost characters from the string builder without throwing an exception.
|
TextStringBuilder |
set(CharSequence str)
Clears and sets this builder to the given value.
|
TextStringBuilder |
setCharAt(int index,
char ch)
Sets the character at the specified index.
|
TextStringBuilder |
setLength(int length)
Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
|
TextStringBuilder |
setNewLineText(String newLine)
Sets the text to be appended when a new line is added.
|
TextStringBuilder |
setNullText(String nullText)
Sets the text to be appended when null is added.
|
int |
size()
Gets the length of the string builder.
|
boolean |
startsWith(String str)
Checks whether this builder starts with the specified string.
|
CharSequence |
subSequence(int startIndex,
int endIndex) |
String |
substring(int start)
Extracts a portion of this string builder as a string.
|
String |
substring(int startIndex,
int endIndex)
Extracts a portion of this string builder as a string.
|
char[] |
toCharArray()
Copies the builder's character array into a new character array.
|
char[] |
toCharArray(int startIndex,
int endIndex)
Copies part of the builder's character array into a new character array.
|
String |
toString()
Gets a String version of the string builder, creating a new instance each time the method is called.
|
StringBuffer |
toStringBuffer()
Gets a StringBuffer version of the string builder, creating a new instance each time the method is called.
|
StringBuilder |
toStringBuilder()
Gets a StringBuilder version of the string builder, creating a new instance each time the method is called.
|
TextStringBuilder |
trim()
Trims the builder by removing characters less than or equal to a space from the beginning and end.
|
protected void |
validateIndex(int index)
Validates that an index is in the range
0 <= index <= size . |
protected int |
validateRange(int startIndex,
int endIndex)
Validates parameters defining a range of the builder.
|
static TextStringBuilder |
wrap(char[] initialBuffer)
Constructs an instance from a reference to a character array.
|
static TextStringBuilder |
wrap(char[] initialBuffer,
int length)
Constructs an instance from a reference to a character array.
|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
chars, codePoints
public TextStringBuilder()
public TextStringBuilder(CharSequence seq)
seq
- the string to copy, null treated as blank stringpublic TextStringBuilder(int initialCapacity)
initialCapacity
- the initial capacity, zero or less will be converted to 32public TextStringBuilder(String str)
str
- the string to copy, null treated as blank stringpublic static TextStringBuilder wrap(char[] initialBuffer)
initialBuffer
- The initial array that will back the new builder.public static TextStringBuilder wrap(char[] initialBuffer, int length)
initialBuffer
- The initial array that will back the new builder.length
- The length of the subarray to be used; must be non-negative and no larger than
initialBuffer.length
. The new builder's size will be set to length
.public TextStringBuilder append(boolean value)
value
- the value to appendpublic TextStringBuilder append(char ch)
append
in interface Appendable
ch
- the value to appendpublic TextStringBuilder append(char[] chars)
appendNull()
.chars
- the char array to appendpublic TextStringBuilder append(char[] chars, int startIndex, int length)
appendNull()
.chars
- the char array to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validStringIndexOutOfBoundsException
- if startIndex
is not in the
range 0 <= startIndex <= chars.length
StringIndexOutOfBoundsException
- if length < 0
StringIndexOutOfBoundsException
- if startIndex + length > chars.length
public TextStringBuilder append(CharBuffer str)
appendNull()
.str
- the char buffer to appendpublic TextStringBuilder append(CharBuffer buf, int startIndex, int length)
appendNull()
.buf
- the char buffer to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder append(CharSequence seq)
appendNull()
.append
in interface Appendable
seq
- the CharSequence to appendpublic TextStringBuilder append(CharSequence seq, int startIndex, int endIndex)
appendNull()
.append
in interface Appendable
seq
- the CharSequence to appendstartIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be validpublic TextStringBuilder append(double value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder append(float value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder append(int value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder append(long value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder append(Object obj)
appendNull()
.obj
- the object to appendpublic TextStringBuilder append(String str)
appendNull()
.str
- the string to appendpublic TextStringBuilder append(String str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validStringIndexOutOfBoundsException
- if startIndex
is not in the
range 0 <= startIndex <= str.length()
StringIndexOutOfBoundsException
- if length < 0
StringIndexOutOfBoundsException
- if startIndex + length > str.length()
public TextStringBuilder append(String format, Object... objs)
String.format(String, Object...)
and appends the result.format
- the format stringobjs
- the objects to use in the format stringthis
to enable chainingString.format(String, Object...)
public TextStringBuilder append(StringBuffer str)
appendNull()
.str
- the string buffer to appendpublic TextStringBuilder append(StringBuffer str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder append(StringBuilder str)
appendNull()
.str
- the StringBuilder to appendpublic TextStringBuilder append(StringBuilder str, int startIndex, int length)
appendNull()
.str
- the StringBuilder to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder append(TextStringBuilder str)
appendNull()
.str
- the string builder to appendpublic TextStringBuilder append(TextStringBuilder str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendAll(Iterable<?> iterable)
append(Object)
.iterable
- the iterable to appendpublic TextStringBuilder appendAll(Iterator<?> it)
append(Object)
.it
- the iterator to appendpublic <T> TextStringBuilder appendAll(T... array)
append(Object)
.T
- the element typearray
- the array to appendpublic TextStringBuilder appendFixedWidthPadLeft(int value, int width, char padChar)
String.valueOf
of the
int
value is used. If the formatted value is larger than the length, the left hand side is lost.value
- the value to appendwidth
- the fixed field width, zero or negative has no effectpadChar
- the pad character to usepublic TextStringBuilder appendFixedWidthPadLeft(Object obj, int width, char padChar)
toString
of the object is
used. If the object is larger than the length, the left hand side is lost. If the object is null, the null text
value is used.obj
- the object to append, null uses null textwidth
- the fixed field width, zero or negative has no effectpadChar
- the pad character to usepublic TextStringBuilder appendFixedWidthPadRight(int value, int width, char padChar)
String.valueOf
of the
int
value is used. If the object is larger than the length, the right hand side is lost.value
- the value to appendwidth
- the fixed field width, zero or negative has no effectpadChar
- the pad character to usepublic TextStringBuilder appendFixedWidthPadRight(Object obj, int width, char padChar)
toString
of the object is
used. If the object is larger than the length, the right hand side is lost. If the object is null, null text
value is used.obj
- the object to append, null uses null textwidth
- the fixed field width, zero or negative has no effectpadChar
- the pad character to usepublic TextStringBuilder appendln(boolean value)
value
- the value to appendpublic TextStringBuilder appendln(char ch)
ch
- the value to appendpublic TextStringBuilder appendln(char[] chars)
appendNull()
.chars
- the char array to appendpublic TextStringBuilder appendln(char[] chars, int startIndex, int length)
appendNull()
.chars
- the char array to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendln(double value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder appendln(float value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder appendln(int value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder appendln(long value)
String.valueOf
.value
- the value to appendpublic TextStringBuilder appendln(Object obj)
appendNull()
.obj
- the object to appendpublic TextStringBuilder appendln(String str)
appendNull()
.str
- the string to appendpublic TextStringBuilder appendln(String str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendln(String format, Object... objs)
String.format(String, Object...)
and appends the result.format
- the format stringobjs
- the objects to use in the format stringthis
to enable chainingString.format(String, Object...)
public TextStringBuilder appendln(StringBuffer str)
appendNull()
.str
- the string buffer to appendpublic TextStringBuilder appendln(StringBuffer str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendln(StringBuilder str)
appendNull()
.str
- the string builder to appendpublic TextStringBuilder appendln(StringBuilder str, int startIndex, int length)
appendNull()
.str
- the string builder to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendln(TextStringBuilder str)
appendNull()
.str
- the string builder to appendpublic TextStringBuilder appendln(TextStringBuilder str, int startIndex, int length)
appendNull()
.str
- the string to appendstartIndex
- the start index, inclusive, must be validlength
- the length to append, must be validpublic TextStringBuilder appendNewLine()
The new line string can be altered using setNewLineText(String)
. This might be used to force the output
to always use Unix line endings even when on Windows.
public TextStringBuilder appendNull()
null
to this string builder.public TextStringBuilder appendPadding(int length, char padChar)
length
- the length to append, negative means no appendpadChar
- the character to appendpublic TextStringBuilder appendSeparator(char separator)
append(char)
.
This method is useful for adding a separator each time around the loop except the first.
for (Iterator it = list.iterator(); it.hasNext();) { appendSeparator(','); append(it.next()); }
Note that for this simple example, you should use appendWithSeparators(Iterable, String)
.
separator
- the separator to usepublic TextStringBuilder appendSeparator(char standard, char defaultIfEmpty)
append(char)
.standard
- the separator if builder is not emptydefaultIfEmpty
- the separator if builder is emptypublic TextStringBuilder appendSeparator(char separator, int loopIndex)
append(char)
.
This method is useful for adding a separator each time around the loop except the first.
for (int i = 0; i < list.size(); i++) { appendSeparator(",", i); append(list.get(i)); }
Note that for this simple example, you should use appendWithSeparators(Iterable, String)
.
separator
- the separator to useloopIndex
- the loop indexpublic TextStringBuilder appendSeparator(String separator)
append(String)
.
This method is useful for adding a separator each time around the loop except the first.
for (Iterator it = list.iterator(); it.hasNext();) { appendSeparator(","); append(it.next()); }
Note that for this simple example, you should use appendWithSeparators(Iterable, String)
.
separator
- the separator to use, null means no separatorpublic TextStringBuilder appendSeparator(String separator, int loopIndex)
append(String)
.
This method is useful for adding a separator each time around the loop except the first.
for (int i = 0; i < list.size(); i++) { appendSeparator(",", i); append(list.get(i)); }
Note that for this simple example, you should use appendWithSeparators(Iterable, String)
.
separator
- the separator to use, null means no separatorloopIndex
- the loop indexpublic TextStringBuilder appendSeparator(String standard, String defaultIfEmpty)
append(String)
.
This method is for example useful for constructing queries
StrBuilder whereClause = new StrBuilder(); if(searchCommand.getPriority() != null) { whereClause.appendSeparator(" and", " where"); whereClause.append(" priority = ?") } if(searchCommand.getComponent() != null) { whereClause.appendSeparator(" and", " where"); whereClause.append(" component = ?") } selectClause.append(whereClause)
standard
- the separator if builder is not empty, null means no separatordefaultIfEmpty
- the separator if builder is empty, null means no separatorpublic void appendTo(Appendable appendable) throws IOException
StrBuilder
to the provided Appendable
.
This method tries to avoid doing any extra copies of contents.
appendable
- the appendable to append data toIOException
- if an I/O error occurs.readFrom(Readable)
public TextStringBuilder appendWithSeparators(Iterable<?> iterable, String separator)
append(Object)
.iterable
- the iterable to appendseparator
- the separator to use, null means no separatorpublic TextStringBuilder appendWithSeparators(Iterator<?> it, String separator)
append(Object)
.it
- the iterator to appendseparator
- the separator to use, null means no separatorpublic TextStringBuilder appendWithSeparators(Object[] array, String separator)
append(Object)
.array
- the array to appendseparator
- the separator to use, null means no separatorpublic Reader asReader()
This method allows the contents of the builder to be read using any standard method that expects a Reader.
To use, simply create a StrBuilder
, populate it with data, call asReader
, and then read away.
The internal character array is shared between the builder and the reader. This allows you to append to the builder after creating the reader, and the changes will be picked up. Note however, that no synchronization occurs, so you must perform all operations with the builder and the reader in one thread.
The returned reader supports marking, and ignores the flush method.
public StringTokenizer asTokenizer()
This method allows the contents of this builder to be tokenized. The tokenizer will be setup by default to tokenize on space, tab, newline and form feed (as per StringTokenizer). These values can be changed on the tokenizer class, before retrieving the tokens.
The returned tokenizer is linked to this builder. You may intermix calls to the builder and tokenizer within
certain limits, however there is no synchronization. Once the tokenizer has been used once, it must be
reset
to pickup the latest changes in the builder. For example:
StrBuilder b = new StrBuilder(); b.append("a b "); StrTokenizer t = b.asTokenizer(); String[] tokens1 = t.getTokenArray(); // returns a,b b.append("c d "); String[] tokens2 = t.getTokenArray(); // returns a,b (c and d ignored) t.reset(); // reset causes builder changes to be picked up String[] tokens3 = t.getTokenArray(); // returns a,b,c,d
In addition to simply intermixing appends and tokenization, you can also call the set methods on the tokenizer to alter how it tokenizes. Just remember to call reset when you want to pickup builder changes.
Calling StringTokenizer.reset(String)
or StringTokenizer.reset(char[])
with a non-null value will
break the link with the builder.
public Writer asWriter()
This method allows you to populate the contents of the builder using any standard method that takes a Writer.
To use, simply create a StrBuilder
, call asWriter
, and populate away. The data is available at
any time using the methods of the StrBuilder
.
The internal character array is shared between the builder and the writer. This allows you to intermix calls that append to the builder and write using the writer and the changes will be occur correctly. Note however, that no synchronization occurs, so you must perform all operations with the builder and the writer in one thread.
The returned writer ignores the close and flush methods.
public String build()
Builder
interface.build
in interface Builder<String>
toString()
public int capacity()
public char charAt(int index)
charAt
in interface CharSequence
index
- the index to retrieve, must be validIndexOutOfBoundsException
- if the index is invalidsetCharAt(int, char)
,
deleteCharAt(int)
public TextStringBuilder clear()
This method does not reduce the size of the internal character buffer. To do that, call clear()
followed
by minimizeCapacity()
.
This method is the same as setLength(int)
called with zero and is provided to match the API of
Collections.
public boolean contains(char ch)
ch
- the character to findpublic boolean contains(String str)
str
- the string to findpublic boolean contains(StringMatcher matcher)
Matchers can be used to perform advanced searching behavior. For example you could write a matcher to search for the character 'a' followed by a number.
matcher
- the matcher to use, null returns -1public TextStringBuilder delete(int startIndex, int endIndex)
startIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder deleteAll(char ch)
ch
- the character to deletepublic TextStringBuilder deleteAll(String str)
str
- the string to delete, null causes no actionpublic TextStringBuilder deleteAll(StringMatcher matcher)
Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by a number.
matcher
- the matcher to use to find the deletion, null causes no actionpublic TextStringBuilder deleteCharAt(int index)
index
- the index to deleteIndexOutOfBoundsException
- if the index is invalidcharAt(int)
,
setCharAt(int, char)
public TextStringBuilder deleteFirst(char ch)
ch
- the character to deletepublic TextStringBuilder deleteFirst(String str)
str
- the string to delete, null causes no actionpublic TextStringBuilder deleteFirst(StringMatcher matcher)
Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where the character 'a' is followed by a number.
matcher
- the matcher to use to find the deletion, null causes no actionpublic char drainChar(int index)
index
- the index to retrieve, must be validIndexOutOfBoundsException
- if the index is invalidcharAt(int)
,
deleteCharAt(int)
public int drainChars(int startIndex, int endIndex, char[] target, int targetIndex)
startIndex
- first index to copy, inclusive.endIndex
- last index to copy, exclusive.target
- the target array, must not be null
.targetIndex
- the index to start copying in the target.0
.public boolean endsWith(String str)
Note that this method handles null input quietly, unlike String.
str
- the string to search for, null returns falsepublic TextStringBuilder ensureCapacity(int capacity)
capacity
- the capacity to ensurepublic boolean equals(Object obj)
public boolean equals(TextStringBuilder other)
other
- the object to check, null returns falsepublic boolean equalsIgnoreCase(TextStringBuilder other)
other
- the object to check, null returns falsepublic char[] getChars(char[] target)
target
- the target array, null will cause an array to be createdpublic void getChars(int startIndex, int endIndex, char[] target, int targetIndex)
startIndex
- first index to copy, inclusive, must be valid.endIndex
- last index to copy, exclusive, must be valid.target
- the target array, must not be null or too small.targetIndex
- the index to start copying in target.NullPointerException
- if the array is null.IndexOutOfBoundsException
- if any index is invalid.public String getNewLineText()
public String getNullText()
public int hashCode()
public int indexOf(char ch)
ch
- the character to findpublic int indexOf(char ch, int startIndex)
ch
- the character to findstartIndex
- the index to start at, invalid index rounded to edgepublic int indexOf(String str)
Note that a null input string will return -1, whereas the JDK throws an exception.
str
- the string to find, null returns -1public int indexOf(String str, int startIndex)
Note that a null input string will return -1, whereas the JDK throws an exception.
str
- the string to find, null returns -1startIndex
- the index to start at, invalid index rounded to edgepublic int indexOf(StringMatcher matcher)
Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.
matcher
- the matcher to use, null returns -1public int indexOf(StringMatcher matcher, int startIndex)
Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.
matcher
- the matcher to use, null returns -1startIndex
- the index to start at, invalid index rounded to edgepublic TextStringBuilder insert(int index, boolean value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, char value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, char[] chars)
index
- the index to add at, must be validchars
- the char array to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, char[] chars, int offset, int length)
index
- the index to add at, must be validchars
- the char array to insertoffset
- the offset into the character array to start at, must be validlength
- the length of the character array part to copy, must be positiveIndexOutOfBoundsException
- if any index is invalidpublic TextStringBuilder insert(int index, double value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, float value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, int value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, long value)
index
- the index to add at, must be validvalue
- the value to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, Object obj)
index
- the index to add at, must be validobj
- the object to insertIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder insert(int index, String str)
index
- the index to add at, must be validstr
- the string to insertIndexOutOfBoundsException
- if the index is invalidpublic boolean isEmpty()
This method is the same as checking length()
and is provided to match the API of Collections.
true
if the size is 0
.public boolean isNotEmpty()
This method is the same as checking length()
.
true
if the size is not 0
.public boolean isReallocated()
public int lastIndexOf(char ch)
ch
- the character to findpublic int lastIndexOf(char ch, int startIndex)
ch
- the character to findstartIndex
- the index to start at, invalid index rounded to edgepublic int lastIndexOf(String str)
Note that a null input string will return -1, whereas the JDK throws an exception.
str
- the string to find, null returns -1public int lastIndexOf(String str, int startIndex)
Note that a null input string will return -1, whereas the JDK throws an exception.
str
- the string to find, null returns -1startIndex
- the index to start at, invalid index rounded to edgepublic int lastIndexOf(StringMatcher matcher)
Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.
matcher
- the matcher to use, null returns -1public int lastIndexOf(StringMatcher matcher, int startIndex)
Matchers can be used to perform advanced searching behavior. For example you could write a matcher to find the character 'a' followed by a number.
matcher
- the matcher to use, null returns -1startIndex
- the index to start at, invalid index rounded to edgepublic String leftString(int length)
This method extracts the left length
characters from the builder. If this many characters are not
available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
length
- the number of characters to extract, negative returns empty stringpublic int length()
length
in interface CharSequence
public String midString(int index, int length)
This method extracts length
characters from the builder at the specified index. If the index is negative
it is treated as zero. If the index is greater than the builder size, it is treated as the builder size. If the
length is negative, the empty string is returned. If insufficient characters are available in the builder, as
much as possible is returned. Thus the returned string may be shorter than the length requested.
index
- the index to start at, negative means zerolength
- the number of characters to extract, negative returns empty stringpublic TextStringBuilder minimizeCapacity()
public int readFrom(CharBuffer charBuffer)
CharBuffer
directly into underlying character buffer without
making extra copies.charBuffer
- CharBuffer to read.appendTo(Appendable)
public int readFrom(Readable readable) throws IOException
Readable
directly into underlying character buffer without
making extra copies.readable
- object to read fromIOException
- if an I/O error occurs.appendTo(Appendable)
public int readFrom(Reader reader) throws IOException
Reader
directly into underlying character buffer without
making extra copies.reader
- Reader to read.IOException
- if an I/O error occurs.appendTo(Appendable)
public int readFrom(Reader reader, int count) throws IOException
count
chars from the provided Reader
directly into underlying character buffer
without making extra copies.reader
- Reader to read.count
- The maximum characters to read, a value <= 0 returns 0.count
, then we've reached the end-of-stream, or -1 if
we reached the end of stream.IOException
- if an I/O error occurs.appendTo(Appendable)
public TextStringBuilder replace(int startIndex, int endIndex, String replaceStr)
startIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringreplaceStr
- the string to replace with, null means delete rangeIndexOutOfBoundsException
- if the index is invalidpublic TextStringBuilder replace(StringMatcher matcher, String replaceStr, int startIndex, int endIndex, int replaceCount)
Matchers can be used to perform advanced behavior. For example you could write a matcher to delete all occurrences where the character 'a' is followed by a number.
matcher
- the matcher to use to find the deletion, null causes no actionreplaceStr
- the string to replace the match with, null is a deletestartIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringreplaceCount
- the number of times to replace, -1 for replace allIndexOutOfBoundsException
- if start index is invalidpublic TextStringBuilder replaceAll(char search, char replace)
search
- the search characterreplace
- the replace characterpublic TextStringBuilder replaceAll(String searchStr, String replaceStr)
searchStr
- the search string, null causes no action to occurreplaceStr
- the replace string, null is equivalent to an empty stringpublic TextStringBuilder replaceAll(StringMatcher matcher, String replaceStr)
Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace all occurrences where the character 'a' is followed by a number.
matcher
- the matcher to use to find the deletion, null causes no actionreplaceStr
- the replace string, null is equivalent to an empty stringpublic TextStringBuilder replaceFirst(char search, char replace)
search
- the search characterreplace
- the replace characterpublic TextStringBuilder replaceFirst(String searchStr, String replaceStr)
searchStr
- the search string, null causes no action to occurreplaceStr
- the replace string, null is equivalent to an empty stringpublic TextStringBuilder replaceFirst(StringMatcher matcher, String replaceStr)
Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where the character 'a' is followed by a number.
matcher
- the matcher to use to find the deletion, null causes no actionreplaceStr
- the replace string, null is equivalent to an empty stringpublic TextStringBuilder reverse()
public String rightString(int length)
This method extracts the right length
characters from the builder. If this many characters are not
available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
length
- the number of characters to extract, negative returns empty stringpublic TextStringBuilder set(CharSequence str)
str
- the new value.charAt(int)
,
deleteCharAt(int)
public TextStringBuilder setCharAt(int index, char ch)
index
- the index to setch
- the new characterIndexOutOfBoundsException
- if the index is invalidcharAt(int)
,
deleteCharAt(int)
public TextStringBuilder setLength(int length)
length
- the length to set to, must be zero or positiveIndexOutOfBoundsException
- if the length is negativepublic TextStringBuilder setNewLineText(String newLine)
newLine
- the new line text, null means use system defaultpublic TextStringBuilder setNullText(String nullText)
nullText
- the null text, null means no appendpublic int size()
This method is the same as length()
and is provided to match the API of Collections.
public boolean startsWith(String str)
Note that this method handles null input quietly, unlike String.
str
- the string to search for, null returns falsepublic CharSequence subSequence(int startIndex, int endIndex)
subSequence
in interface CharSequence
public String substring(int start)
start
- the start index, inclusive, must be validIndexOutOfBoundsException
- if the index is invalidpublic String substring(int startIndex, int endIndex)
Note: This method treats an endIndex greater than the length of the builder as equal to the length of the builder, and continues without error, unlike StringBuffer or String.
startIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringIndexOutOfBoundsException
- if the index is invalidpublic char[] toCharArray()
public char[] toCharArray(int startIndex, int endIndex)
startIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringIndexOutOfBoundsException
- if startIndex is invalid, or if endIndex is invalid (but endIndex greater than
size is valid)public String toString()
Note that unlike StringBuffer, the string version returned is independent of the string builder.
toString
in interface CharSequence
toString
in class Object
public StringBuffer toStringBuffer()
public StringBuilder toStringBuilder()
public TextStringBuilder trim()
protected void validateIndex(int index)
0 <= index <= size
.index
- the index to test.IndexOutOfBoundsException
- Thrown when the index is not the range 0 <= index <= size
.protected int validateRange(int startIndex, int endIndex)
startIndex
- the start index, inclusive, must be validendIndex
- the end index, exclusive, must be valid except that if too large it is treated as end of stringStringIndexOutOfBoundsException
- if the index is invalidCopyright © 2014–2022 The Apache Software Foundation. All rights reserved.