Java Doc for StrBuilder.java in  » Library » Apache-common-lang » org » apache » commons » lang » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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, StrBuilder.setNullText(String) .
author:
   Stephen Colebourne
since:
   2.2
version:
   $Id: StrBuilder.java 492371 2007-01-04 00:42:05Z scolebourne $

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 formfeed (as per StringTokenizer).

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.

This method extracts the left length characters from the builder.

This method extracts the right length characters from the builder.

The new line string can be altered using StrBuilder.setNewLineText(String) . This might be used to force the output to always use Unix line endings even when on Windows. this, to enable chaining

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());
 }
 

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());
 }
 

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));
 }
 

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));
 }
 

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. a reader that reads from this builder

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 formfeed (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 buider and tokenizer within certain limits, however there is no synchronization. Once the tokenizer has been used once, it must be StrTokenizer.reset 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
 

Calling StrTokenizer.reset(String) or StrTokenizer.reset(char[]) with a non-null value will break the link with the builder. a tokenizer that is linked to this builder

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. a writer that populates this builder

This method does not reduce the size of the internal character buffer. To do that, call clear() followed by StrBuilder.minimizeCapacity() .

This method is the same as StrBuilder.setLength(int) called with zero and is provided to match the API of Collections. this, to enable chaining

Matchers can be used to perform advanced searching behaviour. For example you could write a matcher to search for the character 'a' followed by a number.
Parameters:
  matcher - the matcher to use, null returns -1 true if the matcher finds a match in the builder

Matchers can be used to perform advanced deletion behaviour. For example you could write a matcher to delete all occurances where the character 'a' is followed by a number.
Parameters:
  matcher - the matcher to use to find the deletion, null causes no action this, to enable chaining

Matchers can be used to perform advanced deletion behaviour. For example you could write a matcher to delete where the character 'a' is followed by a number.
Parameters:
  matcher - the matcher to use to find the deletion, null causes no action this, to enable chaining

Note that this method handles null input quietly, unlike String.
Parameters:
  str - the string to search for, null returns false true if the builder ends with the string

Note that a null input string will return -1, whereas the JDK throws an exception.
Parameters:
  str - the string to find, null returns -1 the first index of the string, or -1 if not found

Note that a null input string will return -1, whereas the JDK throws an exception.
Parameters:
  str - the string to find, null returns -1
Parameters:
  startIndex - the index to start at, invalid index rounded to edge the first index of the string, or -1 if not found

Matchers can be used to perform advanced searching behaviour. For example you could write a matcher to find the character 'a' followed by a number.
Parameters:
  matcher - the matcher to use, null returns -1 the first index matched, or -1 if not found

Matchers can be used to perform advanced searching behaviour. For example you could write a matcher to find the character 'a' followed by a number.
Parameters:
  matcher - the matcher to use, null returns -1
Parameters:
  startIndex - the index to start at, invalid index rounded to edge the first index matched, or -1 if not found

This method is the same as checking StrBuilder.length() and is provided to match the API of Collections. true if the size is 0.

Note that a null input string will return -1, whereas the JDK throws an exception.
Parameters:
  str - the string to find, null returns -1 the last index of the string, or -1 if not found

Note that a null input string will return -1, whereas the JDK throws an exception.
Parameters:
  str - the string to find, null returns -1
Parameters:
  startIndex - the index to start at, invalid index rounded to edge the last index of the string, or -1 if not found

Matchers can be used to perform advanced searching behaviour. For example you could write a matcher to find the character 'a' followed by a number.
Parameters:
  matcher - the matcher to use, null returns -1 the last index matched, or -1 if not found

Matchers can be used to perform advanced searching behaviour. For example you could write a matcher to find the character 'a' followed by a number.
Parameters:
  matcher - the matcher to use, null returns -1
Parameters:
  startIndex - the index to start at, invalid index rounded to edge the last index matched, or -1 if not found

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.
Parameters:
  length - the number of characters to extract, negative returns empty string the new string

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.
Parameters:
  index - the index to start at, negative means zero
Parameters:
  length - the number of characters to extract, negative returns empty string the new string

Matchers can be used to perform advanced behaviour. For example you could write a matcher to delete all occurances where the character 'a' is followed by a number.
Parameters:
  matcher - the matcher to use to find the deletion, null causes no action
Parameters:
  replaceStr - the string to replace the match with, null is a delete
Parameters:
  startIndex - the start index, inclusive, must be valid
Parameters:
  endIndex - the end index, exclusive, must be valid exceptthat if too large it is treated as end of string
Parameters:
  replaceCount - the number of times to replace, -1 for replace all this, to enable chaining
throws:
  IndexOutOfBoundsException - if start index is invalid

Matchers can be used to perform advanced replace behaviour. For example you could write a matcher to replace all occurances where the character 'a' is followed by a number.
Parameters:
  matcher - the matcher to use to find the deletion, null causes no action
Parameters:
  replaceStr - the replace string, null is equivalent to an empty string this, to enable chaining

Matchers can be used to perform advanced replace behaviour. For example you could write a matcher to replace where the character 'a' is followed by a number.
Parameters:
  matcher - the matcher to use to find the deletion, null causes no action
Parameters:
  replaceStr - the replace string, null is equivalent to an empty string this, to enable chaining

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.
Parameters:
  length - the number of characters to extract, negative returns empty string the new string

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

Note that this method handles null input quietly, unlike String.
Parameters:
  str - the string to search for, null returns false true if the builder starts with the string

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.
Parameters:
  startIndex - the start index, inclusive, must be valid
Parameters:
  endIndex - the end index, exclusive, must be valid exceptthat if too large it is treated as end of string the new string
throws:
  IndexOutOfBoundsException - if the index is invalid

Note that unlike StringBuffer, the string version returned is independent of the string builder. the builder as a String