StrBuilder (Commons Lang 2.6 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.lang.text
Class StrBuilder

java.lang.Object
  org.apache.commons.lang.text.StrBuilder

All Implemented Interfaces:: Cloneable

public class StrBuilder
extends Object
implements Cloneable
extends Object
implements Cloneable

Builds a string from constituent parts providing a more flexible and powerful API than StringBuffer.

The main differences from StringBuffer/StringBuilder are:

Not synchronized
Not final
Subclasses have direct access to character array
Additional methods
- appendWithSeparators - adds an array of values, with a separator
- appendPadding - adds a length padding characters
- appendFixedLength - adds a fixed width field to the builder
- toCharArray/getChars - simpler ways to get a range of the character array
- delete - delete char or string
- replace - search and replace for a char or string
- leftString/rightString/midString - substring without exceptions
- contains - whether the builder contains a char or string
- size/clear/isEmpty - collections style API methods

Views

asTokenizer - uses the internal buffer as the source of a StrTokenizer
asReader - uses the internal buffer as the source of a Reader
asWriter - allows a Writer to write directly to the internal buffer

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).

Prior to 3.0, this class implemented Cloneable but did not implement the clone method so could not be used. From 3.0 onwards it no longer implements the interface.

Since:: 2.2
Version:: $Id: StrBuilder.java 1057349 2011-01-10 20:40:49Z niallp $
Author:: Apache Software Foundation

Field Summary
`protected char[]`	`buffer` Internal data storage.
`protected int`	`size` Current size of the buffer.

Constructor Summary
`StrBuilder()` Constructor that creates an empty builder initial capacity 32 characters.
`StrBuilder(int initialCapacity)` Constructor that creates an empty builder the specified initial capacity.
`StrBuilder(String str)` Constructor that creates a builder from the string, allocating 32 extra characters for growth.

Method Summary
`StrBuilder`	`append(boolean value)` Appends a boolean value to the string builder.
`StrBuilder`	`append(char ch)` Appends a char value to the string builder.
`StrBuilder`	`append(char[] chars)` Appends a char array to the string builder.
`StrBuilder`	`append(char[] chars, int startIndex, int length)` Appends a char array to the string builder.
`StrBuilder`	`append(double value)` Appends a double value to the string builder using `String.valueOf`.
`StrBuilder`	`append(float value)` Appends a float value to the string builder using `String.valueOf`.
`StrBuilder`	`append(int value)` Appends an int value to the string builder using `String.valueOf`.
`StrBuilder`	`append(long value)` Appends a long value to the string builder using `String.valueOf`.
`StrBuilder`	`append(Object obj)` Appends an object to this string builder.
`StrBuilder`	`append(StrBuilder str)` Appends another string builder to this string builder.
`StrBuilder`	`append(StrBuilder str, int startIndex, int length)` Appends part of a string builder to this string builder.
`StrBuilder`	`append(String str)` Appends a string to this string builder.
`StrBuilder`	`append(StringBuffer str)` Appends a string buffer to this string builder.
`StrBuilder`	`append(StringBuffer str, int startIndex, int length)` Appends part of a string buffer to this string builder.
`StrBuilder`	`append(String str, int startIndex, int length)` Appends part of a string to this string builder.
`StrBuilder`	`appendAll(Collection coll)` Appends each item in a collection to the builder without any separators.
`StrBuilder`	`appendAll(Iterator it)` Appends each item in an iterator to the builder without any separators.
`StrBuilder`	`appendAll(Object[] array)` Appends each item in an array to the builder without any separators.
`StrBuilder`	`appendFixedWidthPadLeft(int value, int width, char padChar)` Appends an object to the builder padding on the left to a fixed width.
`StrBuilder`	`appendFixedWidthPadLeft(Object obj, int width, char padChar)` Appends an object to the builder padding on the left to a fixed width.
`StrBuilder`	`appendFixedWidthPadRight(int value, int width, char padChar)` Appends an object to the builder padding on the right to a fixed length.
`StrBuilder`	`appendFixedWidthPadRight(Object obj, int width, char padChar)` Appends an object to the builder padding on the right to a fixed length.
`StrBuilder`	`appendln(boolean value)` Appends a boolean value followed by a new line to the string builder.
`StrBuilder`	`appendln(char ch)` Appends a char value followed by a new line to the string builder.
`StrBuilder`	`appendln(char[] chars)` Appends a char array followed by a new line to the string builder.
`StrBuilder`	`appendln(char[] chars, int startIndex, int length)` Appends a char array followed by a new line to the string builder.
`StrBuilder`	`appendln(double value)` Appends a double value followed by a new line to the string builder using `String.valueOf`.
`StrBuilder`	`appendln(float value)` Appends a float value followed by a new line to the string builder using `String.valueOf`.
`StrBuilder`	`appendln(int value)` Appends an int value followed by a new line to the string builder using `String.valueOf`.
`StrBuilder`	`appendln(long value)` Appends a long value followed by a new line to the string builder using `String.valueOf`.
`StrBuilder`	`appendln(Object obj)` Appends an object followed by a new line to this string builder.
`StrBuilder`	`appendln(StrBuilder str)` Appends another string builder followed by a new line to this string builder.
`StrBuilder`	`appendln(StrBuilder str, int startIndex, int length)` Appends part of a string builder followed by a new line to this string builder.
`StrBuilder`	`appendln(String str)` Appends a string followed by a new line to this string builder.
`StrBuilder`	`appendln(StringBuffer str)` Appends a string buffer followed by a new line to this string builder.
`StrBuilder`	`appendln(StringBuffer str, int startIndex, int length)` Appends part of a string buffer followed by a new line to this string builder.
`StrBuilder`	`appendln(String str, int startIndex, int length)` Appends part of a string followed by a new line to this string builder.
`StrBuilder`	`appendNewLine()` Appends the new line string to this string builder.
`StrBuilder`	`appendNull()` Appends the text representing `null` to this string builder.
`StrBuilder`	`appendPadding(int length, char padChar)` Appends the pad character to the builder the specified number of times.
`StrBuilder`	`appendSeparator(char separator)` Appends a separator if the builder is currently non-empty.
`StrBuilder`	`appendSeparator(char standard, char defaultIfEmpty)` Append 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)`.
`StrBuilder`	`appendSeparator(char separator, int loopIndex)` Appends a separator to the builder if the loop index is greater than zero.
`StrBuilder`	`appendSeparator(String separator)` Appends a separator if the builder is currently non-empty.
`StrBuilder`	`appendSeparator(String separator, int loopIndex)` Appends a separator to the builder if the loop index is greater than zero.
`StrBuilder`	`appendSeparator(String standard, String defaultIfEmpty)` Appends one of both separators to the StrBuilder.
`StrBuilder`	`appendWithSeparators(Collection coll, String separator)` Appends a collection placing separators between each value, but not before the first or after the last.
`StrBuilder`	`appendWithSeparators(Iterator it, String separator)` Appends an iterator placing separators between each value, but not before the first or after the last.
`StrBuilder`	`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.
`StrTokenizer`	`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.
`int`	`capacity()` Gets the current size of the internal character array buffer.
`char`	`charAt(int index)` Gets the character at the specified index.
`StrBuilder`	`clear()` Clears the string builder (convenience Collections API style method).
`Object`	`clone()` Clone this object.
`boolean`	`contains(char ch)` Checks if the string builder contains the specified char.
`boolean`	`contains(String str)` Checks if the string builder contains the specified string.
`boolean`	`contains(StrMatcher matcher)` Checks if the string builder contains a string matched using the specified matcher.
`StrBuilder`	`delete(int startIndex, int endIndex)` Deletes the characters between the two specified indices.
`StrBuilder`	`deleteAll(char ch)` Deletes the character wherever it occurs in the builder.
`StrBuilder`	`deleteAll(String str)` Deletes the string wherever it occurs in the builder.
`StrBuilder`	`deleteAll(StrMatcher matcher)` Deletes all parts of the builder that the matcher matches.
`StrBuilder`	`deleteCharAt(int index)` Deletes the character at the specified index.
`StrBuilder`	`deleteFirst(char ch)` Deletes the character wherever it occurs in the builder.
`StrBuilder`	`deleteFirst(String str)` Deletes the string wherever it occurs in the builder.
`StrBuilder`	`deleteFirst(StrMatcher matcher)` Deletes the first match within the builder using the specified matcher.
`boolean`	`endsWith(String str)` Checks whether this builder ends with the specified string.
`StrBuilder`	`ensureCapacity(int capacity)` Checks the capacity and ensures that it is at least the size specified.
`boolean`	`equals(Object obj)` Checks the contents of this builder against another to see if they contain the same character content.
`boolean`	`equals(StrBuilder other)` Checks the contents of this builder against another to see if they contain the same character content.
`boolean`	`equalsIgnoreCase(StrBuilder other)` Checks the contents of this builder against another to see if they contain the same character content ignoring case.
`char[]`	`getChars(char[] destination)` Copies the character array into the specified array.
`void`	`getChars(int startIndex, int endIndex, char[] destination, int destinationIndex)` Copies the 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(StrMatcher matcher)` Searches the string builder using the matcher to find the first match.
`int`	`indexOf(StrMatcher matcher, int startIndex)` Searches the string builder using the matcher to find the first match searching from the given index.
`StrBuilder`	`insert(int index, boolean value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, char value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, char[] chars)` Inserts the character array into this builder.
`StrBuilder`	`insert(int index, char[] chars, int offset, int length)` Inserts part of the character array into this builder.
`StrBuilder`	`insert(int index, double value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, float value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, int value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, long value)` Inserts the value into this builder.
`StrBuilder`	`insert(int index, Object obj)` Inserts the string representation of an object into this builder.
`StrBuilder`	`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).
`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(StrMatcher matcher)` Searches the string builder using the matcher to find the last match.
`int`	`lastIndexOf(StrMatcher 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.
`StrBuilder`	`minimizeCapacity()` Minimizes the capacity to the actual length of the string.
`StrBuilder`	`replace(int startIndex, int endIndex, String replaceStr)` Replaces a portion of the string builder with another string.
`StrBuilder`	`replace(StrMatcher matcher, String replaceStr, int startIndex, int endIndex, int replaceCount)` Advanced search and replaces within the builder using a matcher.
`StrBuilder`	`replaceAll(char search, char replace)` Replaces the search character with the replace character throughout the builder.
`StrBuilder`	`replaceAll(String searchStr, String replaceStr)` Replaces the search string with the replace string throughout the builder.
`StrBuilder`	`replaceAll(StrMatcher matcher, String replaceStr)` Replaces all matches within the builder with the replace string.
`StrBuilder`	`replaceFirst(char search, char replace)` Replaces the first instance of the search character with the replace character in the builder.
`StrBuilder`	`replaceFirst(String searchStr, String replaceStr)` Replaces the first instance of the search string with the replace string.
`StrBuilder`	`replaceFirst(StrMatcher matcher, String replaceStr)` Replaces the first match within the builder with the replace string.
`StrBuilder`	`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.
`StrBuilder`	`setCharAt(int index, char ch)` Sets the character at the specified index.
`StrBuilder`	`setLength(int length)` Updates the length of the builder by either dropping the last characters or adding filler of unicode zero.
`StrBuilder`	`setNewLineText(String newLine)` Sets the text to be appended when a new line is added.
`StrBuilder`	`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.
`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.
`StrBuilder`	`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 parameters defining a single index in the builder.
`protected int`	`validateRange(int startIndex, int endIndex)` Validates parameters defining a range of the builder.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

buffer

protected char[] buffer

Internal data storage.

size

protected int size

Current size of the buffer.

Constructor Detail

StrBuilder

public StrBuilder()

Constructor that creates an empty builder initial capacity 32 characters.

StrBuilder

public StrBuilder(int initialCapacity)

Constructor that creates an empty builder the specified initial capacity.

Parameters:: initialCapacity - the initial capacity, zero or less will be converted to 32

StrBuilder

public StrBuilder(String str)

Constructor that creates a builder from the string, allocating 32 extra characters for growth.

Parameters:: str - the string to copy, null treated as blank string

Method Detail

getNewLineText

public String getNewLineText()

Gets the text to be appended when a new line is added.

Returns:: the new line text, null means use system default

setNewLineText

public StrBuilder setNewLineText(String newLine)

Sets the text to be appended when a new line is added.

Parameters:: newLine - the new line text, null means use system default
Returns:: this, to enable chaining

getNullText

public String getNullText()

Gets the text to be appended when null is added.

Returns:: the null text, null means no append

setNullText

public StrBuilder setNullText(String nullText)

Sets the text to be appended when null is added.

Parameters:: nullText - the null text, null means no append
Returns:: this, to enable chaining

length

public int length()

Gets the length of the string builder.

Returns:: the length

setLength

public StrBuilder setLength(int length)

Updates the length of the builder by either dropping the last characters or adding filler of unicode zero.

Parameters:: length - the length to set to, must be zero or positive
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the length is negative

capacity

public int capacity()

Gets the current size of the internal character array buffer.

Returns:: the capacity

ensureCapacity

public StrBuilder ensureCapacity(int capacity)

Checks the capacity and ensures that it is at least the size specified.

Parameters:: capacity - the capacity to ensure
Returns:: this, to enable chaining

minimizeCapacity

public StrBuilder minimizeCapacity()

Minimizes the capacity to the actual length of the string.

Returns:: this, to enable chaining

size

public int size()

Gets the length of the string builder.

This method is the same as length() and is provided to match the API of Collections.

Returns:: the length

isEmpty

public boolean isEmpty()

Checks is the string builder is empty (convenience Collections API style method).

This method is the same as checking length() and is provided to match the API of Collections.

Returns:: true if the size is 0.

clear

public StrBuilder clear()

Clears the string builder (convenience Collections API style method).

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.

Returns:: this, to enable chaining

charAt

public char charAt(int index)

Gets the character at the specified index.

Parameters:: index - the index to retrieve, must be valid
Returns:: the character at the index
Throws:: IndexOutOfBoundsException - if the index is invalid
See Also:: setCharAt(int, char), deleteCharAt(int)

setCharAt

public StrBuilder setCharAt(int index,
                            char ch)

Sets the character at the specified index.

Parameters:: index - the index to set; ch - the new character
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the index is invalid
See Also:: charAt(int), deleteCharAt(int)

deleteCharAt

public StrBuilder deleteCharAt(int index)

Deletes the character at the specified index.

Parameters:: index - the index to delete
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the index is invalid
See Also:: charAt(int), setCharAt(int, char)

toCharArray

public char[] toCharArray()

Copies the builder's character array into a new character array.

Returns:: a new array that represents the contents of the builder

toCharArray

public char[] toCharArray(int startIndex,
                          int endIndex)

Copies part of the builder's character array into a new character array.

Parameters:: startIndex - the start index, inclusive, must be valid; endIndex - the end index, exclusive, must be valid except that if too large it is treated as end of string
Returns:: a new array that holds part of the contents of the builder
Throws:: IndexOutOfBoundsException - if startIndex is invalid, or if endIndex is invalid (but endIndex greater than size is valid)

getChars

public char[] getChars(char[] destination)

Copies the character array into the specified array.

Parameters:: destination - the destination array, null will cause an array to be created
Returns:: the input array, unless that was null or too small

getChars

public void getChars(int startIndex,
                     int endIndex,
                     char[] destination,
                     int destinationIndex)

Copies the character array into the specified array.

Parameters:: startIndex - first index to copy, inclusive, must be valid; endIndex - last index, exclusive, must be valid; destination - the destination array, must not be null or too small; destinationIndex - the index to start copying in destination
Throws:: NullPointerException - if the array is null; IndexOutOfBoundsException - if any index is invalid

appendNewLine

public StrBuilder appendNewLine()

Appends the new line string to this string builder.

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.

Returns:: this, to enable chaining

appendNull

public StrBuilder appendNull()

Appends the text representing null to this string builder.

Returns:: this, to enable chaining

append

public StrBuilder append(Object obj)

Appends an object to this string builder. Appending null will call appendNull().

Parameters:: obj - the object to append
Returns:: this, to enable chaining

append

public StrBuilder append(String str)

Appends a string to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append
Returns:: this, to enable chaining

append

public StrBuilder append(String str,
                         int startIndex,
                         int length)

Appends part of a string to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining

append

public StrBuilder append(StringBuffer str)

Appends a string buffer to this string builder. Appending null will call appendNull().

Parameters:: str - the string buffer to append
Returns:: this, to enable chaining

append

public StrBuilder append(StringBuffer str,
                         int startIndex,
                         int length)

Appends part of a string buffer to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining

append

public StrBuilder append(StrBuilder str)

Appends another string builder to this string builder. Appending null will call appendNull().

Parameters:: str - the string builder to append
Returns:: this, to enable chaining

append

public StrBuilder append(StrBuilder str,
                         int startIndex,
                         int length)

Appends part of a string builder to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining

append

public StrBuilder append(char[] chars)

Appends a char array to the string builder. Appending null will call appendNull().

Parameters:: chars - the char array to append
Returns:: this, to enable chaining

append

public StrBuilder append(char[] chars,
                         int startIndex,
                         int length)

Appends a char array to the string builder. Appending null will call appendNull().

Parameters:: chars - the char array to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining

append

public StrBuilder append(boolean value)

Appends a boolean value to the string builder.

Parameters:: value - the value to append
Returns:: this, to enable chaining

append

public StrBuilder append(char ch)

Appends a char value to the string builder.

Parameters:: ch - the value to append
Returns:: this, to enable chaining

append

public StrBuilder append(int value)

Appends an int value to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining

append

public StrBuilder append(long value)

Appends a long value to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining

append

public StrBuilder append(float value)

Appends a float value to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining

append

public StrBuilder append(double value)

Appends a double value to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining

appendln

public StrBuilder appendln(Object obj)

Appends an object followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: obj - the object to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(String str)

Appends a string followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(String str,
                           int startIndex,
                           int length)

Appends part of a string followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(StringBuffer str)

Appends a string buffer followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string buffer to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(StringBuffer str,
                           int startIndex,
                           int length)

Appends part of a string buffer followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(StrBuilder str)

Appends another string builder followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string builder to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(StrBuilder str,
                           int startIndex,
                           int length)

Appends part of a string builder followed by a new line to this string builder. Appending null will call appendNull().

Parameters:: str - the string to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(char[] chars)

Appends a char array followed by a new line to the string builder. Appending null will call appendNull().

Parameters:: chars - the char array to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(char[] chars,
                           int startIndex,
                           int length)

Appends a char array followed by a new line to the string builder. Appending null will call appendNull().

Parameters:: chars - the char array to append; startIndex - the start index, inclusive, must be valid; length - the length to append, must be valid
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(boolean value)

Appends a boolean value followed by a new line to the string builder.

Parameters:: value - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(char ch)

Appends a char value followed by a new line to the string builder.

Parameters:: ch - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(int value)

Appends an int value followed by a new line to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(long value)

Appends a long value followed by a new line to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(float value)

Appends a float value followed by a new line to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendln

public StrBuilder appendln(double value)

Appends a double value followed by a new line to the string builder using String.valueOf.

Parameters:: value - the value to append
Returns:: this, to enable chaining
Since:: 2.3

appendAll

public StrBuilder appendAll(Object[] array)

Appends each item in an array to the builder without any separators. Appending a null array will have no effect. Each object is appended using append(Object).

Parameters:: array - the array to append
Returns:: this, to enable chaining
Since:: 2.3

appendAll

public StrBuilder appendAll(Collection coll)

Appends each item in a collection to the builder without any separators. Appending a null collection will have no effect. Each object is appended using append(Object).

Parameters:: coll - the collection to append
Returns:: this, to enable chaining
Since:: 2.3

appendAll

public StrBuilder appendAll(Iterator it)

Appends each item in an iterator to the builder without any separators. Appending a null iterator will have no effect. Each object is appended using append(Object).

Parameters:: it - the iterator to append
Returns:: this, to enable chaining
Since:: 2.3

appendWithSeparators

public StrBuilder appendWithSeparators(Object[] array,
                                       String separator)

Appends an array placing separators between each value, but not before the first or after the last. Appending a null array will have no effect. Each object is appended using append(Object).

Parameters:: array - the array to append; separator - the separator to use, null means no separator
Returns:: this, to enable chaining

appendWithSeparators

public StrBuilder appendWithSeparators(Collection coll,
                                       String separator)

Appends a collection placing separators between each value, but not before the first or after the last. Appending a null collection will have no effect. Each object is appended using append(Object).

Parameters:: coll - the collection to append; separator - the separator to use, null means no separator
Returns:: this, to enable chaining

appendWithSeparators

public StrBuilder appendWithSeparators(Iterator it,
                                       String separator)

Appends an iterator placing separators between each value, but not before the first or after the last. Appending a null iterator will have no effect. Each object is appended using append(Object).

Parameters:: it - the iterator to append; separator - the separator to use, null means no separator
Returns:: this, to enable chaining

appendSeparator

public StrBuilder appendSeparator(String separator)

Appends a separator if the builder is currently non-empty. Appending a null separator will have no effect. The separator is appended using 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(Collection, String).

Parameters:: separator - the separator to use, null means no separator
Returns:: this, to enable chaining
Since:: 2.3

appendSeparator

public StrBuilder appendSeparator(String standard,
                                  String defaultIfEmpty)

Appends one of both separators to the StrBuilder. If the builder is currently empty it will append the defaultIfEmpty-separator Otherwise it will append the standard-separator Appending a null separator will have no effect. The separator is appended using 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)

Parameters:: standard - the separator if builder is not empty, null means no separator; defaultIfEmpty - the separator if builder is empty, null means no separator
Returns:: this, to enable chaining
Since:: 2.5

appendSeparator

public StrBuilder appendSeparator(char separator)

Appends a separator if the builder is currently non-empty. The separator is appended using 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(Collection, String).

Parameters:: separator - the separator to use
Returns:: this, to enable chaining
Since:: 2.3

appendSeparator

public StrBuilder appendSeparator(char standard,
                                  char defaultIfEmpty)

Append 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).

Parameters:: standard - the separator if builder is not empty; defaultIfEmpty - the separator if builder is empty
Returns:: this, to enable chaining
Since:: 2.5

appendSeparator

public StrBuilder appendSeparator(String separator,
                                  int loopIndex)

Appends a separator to the builder if the loop index is greater than zero. Appending a null separator will have no effect. The separator is appended using 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(Collection, String).

Parameters:: separator - the separator to use, null means no separator; loopIndex - the loop index
Returns:: this, to enable chaining
Since:: 2.3

appendSeparator

public StrBuilder appendSeparator(char separator,
                                  int loopIndex)

Appends a separator to the builder if the loop index is greater than zero. The separator is appended using 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(Collection, String).

Parameters:: separator - the separator to use; loopIndex - the loop index
Returns:: this, to enable chaining
Since:: 2.3

appendPadding

public StrBuilder appendPadding(int length,
                                char padChar)

Appends the pad character to the builder the specified number of times.

Parameters:: length - the length to append, negative means no append; padChar - the character to append
Returns:: this, to enable chaining

appendFixedWidthPadLeft

public StrBuilder appendFixedWidthPadLeft(Object obj,
                                          int width,
                                          char padChar)

Appends an object to the builder padding on the left to a fixed width. The 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.

Parameters:: obj - the object to append, null uses null text; width - the fixed field width, zero or negative has no effect; padChar - the pad character to use
Returns:: this, to enable chaining

appendFixedWidthPadLeft

public StrBuilder appendFixedWidthPadLeft(int value,
                                          int width,
                                          char padChar)

Appends an object to the builder padding on the left to a fixed width. The String.valueOf of the int value is used. If the formatted value is larger than the length, the left hand side is lost.

Parameters:: value - the value to append; width - the fixed field width, zero or negative has no effect; padChar - the pad character to use
Returns:: this, to enable chaining

appendFixedWidthPadRight

public StrBuilder appendFixedWidthPadRight(Object obj,
                                           int width,
                                           char padChar)

Appends an object to the builder padding on the right to a fixed length. The 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.

Parameters:: obj - the object to append, null uses null text; width - the fixed field width, zero or negative has no effect; padChar - the pad character to use
Returns:: this, to enable chaining

appendFixedWidthPadRight

public StrBuilder appendFixedWidthPadRight(int value,
                                           int width,
                                           char padChar)

Appends an object to the builder padding on the right to a fixed length. The String.valueOf of the int value is used. If the object is larger than the length, the right hand side is lost.

Parameters:: value - the value to append; width - the fixed field width, zero or negative has no effect; padChar - the pad character to use
Returns:: this, to enable chaining

insert

public StrBuilder insert(int index,
                         Object obj)

Inserts the string representation of an object into this builder. Inserting null will use the stored null text value.

Parameters:: index - the index to add at, must be valid; obj - the object to insert
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the index is invalid

insert

public StrBuilder insert(int index,
                         String str)

Inserts the string into this builder. Inserting null will use the stored null text value.

Parameters:: index - the index to add at, must be valid; str - the string to insert
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the index is invalid

insert

public StrBuilder insert(int index,
                         char[] chars)

Inserts the character array into this builder. Inserting null will use the stored null text value.

Parameters:: index - the index to add at, must be valid; chars - the char array to insert
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if the index is invalid

insert

public StrBuilder insert(int index,
                         char[] chars,
                         int offset,
                         int length)

Inserts part of the character array into this builder. Inserting null will use the stored null text value.

Parameters:: index - the index to add at, must be valid; chars - the char array to insert; offset - the offset into the character array to start at, must be valid; length - the length of the character array part to copy, must be positive
Returns:: this, to enable chaining
Throws:: IndexOutOfBoundsException - if any index is invalid