PIRL.Strings

## Class String_Buffer

- java.lang.Object
- - PIRL.Strings.String_Buffer

Direct Known Subclasses:
  String_Buffer_Reader

    public class String_Buffer
    extends Object

A String_Buffer is a wrapper for the StringBuffer class.

The StringBuffer class is declared final so it can not be extended. The String_Buffer class implements all of the StringBuffer methods (by simply calling the corresponding method) plus numerous methods that provide extended and convenient capabilities along the usual lines of String manipulation. The wrapped methods all function identically to their StringBuffer counterparts, of course, except when a reference to this StringBuffer object is returned it is a reference to this String_Buffer object.

See Also:
  `StringBuffer`

### Field Summary

Fields
`static String` `ID`
`static String` `NL`
`static char` `QUESTIONABLE_CHARACTER`

### Constructor Summary

Constructors
Constructor and Description
`String_Buffer()` Constructs a String_Buffer with no characters in it and an initial capacity of 16 characters.
`String_Buffer(int length)` Constructs a String_Buffer with no characters in it and an initial capacity specified by the length argument.
`String_Buffer(String string)` Constructs a String_Buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the String_Buffer is a copy of the argument string.

### Method Summary

Methods
`String_Buffer` `append(boolean b)`
`String_Buffer` `append(byte b)` Append a byte as a character.
`String_Buffer` `append(byte[] bytes)` Append a byte array as characters.
`String_Buffer` `append(byte[] bytes, int offset, int length)` Append a set of bytes as characters.
`String_Buffer` `append(char c)`
`String_Buffer` `append(char[] s)`
`String_Buffer` `append(char[] s, int offset, int length)`
`String_Buffer` `append(double d)`
`String_Buffer` `append(float f)`
`String_Buffer` `append(int i)`
`String_Buffer` `append(long l)`
`String_Buffer` `append(Object o)`
`String_Buffer` `append(String s)`
`int` `capacity()`
`char` `charAt(int index)`
`String_Buffer` `clean(char character)` Clean all unescaped occurances of a character from a String.
`String_Buffer` `clear()` Empties the buffer of all characters.
`String_Buffer` `delete(int start, int end)`
`String_Buffer` `deleteCharAt(int index)`
`void` `ensureCapacity(int minimumCapacity)`
`boolean` `equals_ignore_case(int index, String pattern)` Tests if the pattern String is equal regardless of case to the substring of the same length starting at the index.
`boolean` `equals(int index, String pattern)` Tests if the pattern String is equal to the substring of the same length starting at the index.
`boolean` `equalsIgnoreCase(int index, String pattern)`
`String_Buffer` `escape_to_special()` Substitutes escape sequences with special characters.
`static String` `escape_to_special(String string)` Substitutes escape sequences with special characters.
`String_Buffer` `from_character_references()` Substitutes numeric character references with characters.
`static String` `from_character_references(String string)` Substitutes numeric character references with characters.
`void` `getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)`
`int` `index_of(int index, char character)` Gets the index of the next character matching the specified character, starting with the specified index.
`int` `index_of(int index, String pattern)` Gets the index of the next occurance of the substring matching the pattern String, starting with the specified index.
`int` `indexOf(int index, char character)`
`int` `indexOf(int index, String pattern)`
`String_Buffer` `insert(int index, boolean b)`
`String_Buffer` `insert(int index, char c)`
`String_Buffer` `insert(int index, char[] s)`
`String_Buffer` `insert(int index, char[] s, int offset, int length)`
`String_Buffer` `insert(int index, double d)`
`String_Buffer` `insert(int index, float f)`
`String_Buffer` `insert(int index, int i)`
`String_Buffer` `insert(int index, long l)`
`String_Buffer` `insert(int index, Object o)`
`String_Buffer` `insert(int index, String s)`
`int` `length()`
`String_Buffer` `replace_span(int index, String span, String substitute)` Replaces all sequences of any and all characters from the span String with the substitute String, starting at the specified index.
`String_Buffer` `replace(int start, int end, String string)`
`String_Buffer` `replace(int index, String old_string, String new_string)` Replaces all occurances of the old_string with the new_string, starting at the specified index.
`String_Buffer` `replaceSpan(int index, String span, String substitute)`
`String_Buffer` `reverse()`
`void` `setCharAt(int index, char c)`
`void` `setLength(int length)`
`int` `skip_back_over(int index, String skip)` Skips back over any and all characters in the skip String, starting with the character at the specified index.
`int` `skip_back_until(int index, String find)` Skips back until a character also in the find String is found, starting with the character at the specified index.
`int` `skip_over(int index, String skip)` Skips over any and all characters in the skip String, starting with the character at the specified index.
`int` `skip_until(int index, String find)` Skips until a character also in the find String is found, starting with the character at the specified index.
`int` `skipBackOver(int index, String skip)`
`int` `skipBackUntil(int index, String find)`
`int` `skipOver(int index, String skip)`
`int` `skipUntil(int index, String find)`
`String_Buffer` `special_to_escape()` Substitutes special characters with escape sequences.
`static String` `special_to_escape(String string)` Substitutes special characters with escape sequences.
`String` `substring(int index)`
`String` `substring(int start, int end)`
`String_Buffer` `to_character_references()` Substitutes non-printable characters with numeric character references.
`static String` `to_character_references(String string)` Substitutes non-printable characters with numeric character references.
`String_Buffer` `to_printable_ASCII()` Substitute all non-ASCII and unprintable characters with a question mark.
`static String` `to_printable_ASCII(String string)` Substitute all non-ASCII and unprintable characters with a question mark.
`String` `toString()`
`String_Buffer` `trim_all(char character)` Trims a sequence of the same character from both ends of a string.
`String_Buffer` `trim_beginning()` Trims whitespace from the beginning of the String_Buffer.
`String_Buffer` `trim_end()` Trims whitespace from the end of the String_Buffer.
`String_Buffer` `trim()` Trims whitespace from both ends of the String_Buffer.
`String_Buffer` `trim(char character)` Trims a character from both ends of a string.
`String_Buffer` `trim(int start, int end)` Trims whitespace from both ends of a substring of the String_Buffer, starting at the start index and ending before the end index.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### ID

    public static final String ID

See Also:
  Constant Field Values

#### NL

    public static final String NL

#### QUESTIONABLE_CHARACTER

    public static final char QUESTIONABLE_CHARACTER

See Also:
  Constant Field Values

### Constructor Detail

#### String_Buffer

    public String_Buffer()

Constructs a String_Buffer with no characters in it and an initial capacity of 16 characters.

#### String_Buffer

    public String_Buffer(int length)

Constructs a String_Buffer with no characters in it and an initial capacity specified by the length argument.

Parameters:
  `length` - The initial capacity.
Throws:
  `NegativeArraySizeException` - If the length argument is less than 0.

#### String_Buffer

    public String_Buffer(String string)

Constructs a String_Buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the String_Buffer is a copy of the argument string. The initial capacity of the String_Buffer is 16 plus the length of the string argument.

Parameters:
  `string` - The initial contents of the buffer.

### Method Detail

#### append

    public String_Buffer append(boolean b)

See Also:
  `StringBuffer.append(boolean)`

#### append

    public String_Buffer append(char c)

See Also:
  `StringBuffer.append(char)`

#### append

    public String_Buffer append(byte b)

Append a byte as a character.

Parameters:
  `b` - The byte to be appended.

#### append

    public String_Buffer append(char[] s)

See Also:
  `StringBuffer.append(char[])`

#### append

    public String_Buffer append(byte[] bytes)

Append a byte array as characters.

Equivalent to append (bytes, 0, bytes.length);

Parameters:
  `bytes` - An array of bytes.

#### append

    public String_Buffer append(char[] s,
                       int offset,
                       int length)

See Also:
  `StringBuffer.append(char[], int, int)`

#### append

    public String_Buffer append(byte[] bytes,
                       int offset,
                       int length)
                         throws IndexOutOfBoundsException

Append a set of bytes as characters.

A convenience method for append (new String (bytes, offset, length));

Parameters:
  `bytes` - An array of bytes.
  `offset` - The byte array offset of the first byte to be appended.
  `length` - The number of bytes to be appended.
Throws:
  `IndexOutOfBoundsException` - If the offset and/or length index bytes outside array bounds.

#### append

    public String_Buffer append(double d)

See Also:
  `StringBuffer.append(double)`

#### append

    public String_Buffer append(float f)

See Also:
  `StringBuffer.append(float)`

#### append

    public String_Buffer append(int i)

See Also:
  `StringBuffer.append(int)`

#### append

    public String_Buffer append(long l)

See Also:
  `StringBuffer.append(long)`

#### append

    public String_Buffer append(Object o)

See Also:
  `StringBuffer.append(Object)`

#### append

    public String_Buffer append(String s)

See Also:
  `StringBuffer.append(String)`

#### capacity

    public int capacity()

See Also:
  `StringBuffer.capacity()`

#### charAt

    public char charAt(int index)

See Also:
  `StringBuffer.charAt(int)`

#### delete

    public String_Buffer delete(int start,
                       int end)

See Also:
  `StringBuffer.delete(int, int)`

#### deleteCharAt

    public String_Buffer deleteCharAt(int index)

See Also:
  `StringBuffer.deleteCharAt(int)`

#### ensureCapacity

    public void ensureCapacity(int minimumCapacity)

See Also:
  `StringBuffer.ensureCapacity(int)`

#### getChars

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

See Also:
  `StringBuffer.getChars(int, int, char[], int)`

#### insert

    public String_Buffer insert(int index,
                       boolean b)

See Also:
  `StringBuffer.insert(int, boolean)`

#### insert

    public String_Buffer insert(int index,
                       char c)

See Also:
  `StringBuffer.insert(int, char)`

#### insert

    public String_Buffer insert(int index,
                       char[] s)

See Also:
  `StringBuffer.insert(int, char[])`

#### insert

    public String_Buffer insert(int index,
                       char[] s,
                       int offset,
                       int length)

See Also:
  `StringBuffer.insert(int, char[], int, int)`

#### insert

    public String_Buffer insert(int index,
                       double d)

See Also:
  `StringBuffer.insert(int, double)`

#### insert

    public String_Buffer insert(int index,
                       float f)

See Also:
  `StringBuffer.insert(int, float)`

#### insert

    public String_Buffer insert(int index,
                       int i)

See Also:
  `StringBuffer.insert(int, int)`

#### insert

    public String_Buffer insert(int index,
                       long l)

See Also:
  `StringBuffer.insert(int, long)`

#### insert

    public String_Buffer insert(int index,
                       Object o)

See Also:
  `StringBuffer.insert(int, Object)`

#### insert

    public String_Buffer insert(int index,
                       String s)

See Also:
  `StringBuffer.insert(int, String)`

#### length

    public int length()

See Also:
  `StringBuffer.length()`

#### replace

    public String_Buffer replace(int start,
                        int end,
                        String string)

See Also:
  `StringBuffer.replace(int, int, String)`

#### reverse

    public String_Buffer reverse()

See Also:
  `StringBuffer.reverse()`

#### setCharAt

    public void setCharAt(int index,
                 char c)

See Also:
  `StringBuffer.setCharAt(int, char)`

#### setLength

    public void setLength(int length)

See Also:
  `StringBuffer.setLength(int)`

#### substring

    public String substring(int index)

See Also:
  `StringBuffer.substring(int)`

#### substring

    public String substring(int start,
                   int end)

See Also:
  `StringBuffer.substring(int, int)`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`
See Also:
  `StringBuffer.toString()`

#### skip_over

    public int skip_over(int index,
                String skip)

Skips over any and all characters in the skip String, starting with the character at the specified index.

Parameters:
  `index` - The index of the first character to test.
  `skip` - The set of characters to be skipped.
Returns:
  The index of the character at or beyond the starting index that is not in the skip String, or the end (`length`) index if all remaining characters from the starting index are in the skip String.
See Also:
  `String.indexOf(int)`, `charAt(int)`

#### skipOver

    public int skipOver(int index,
               String skip)

See Also:
  `skip_over(int, String)`

#### skip_back_over

    public int skip_back_over(int index,
                     String skip)

Skips back over any and all characters in the skip String, starting with the character at the specified index.

Parameters:
  `index` - The index of the first character to test.
  `skip` - The set of characters to be skipped.
Returns:
  The index of the last character at or before the starting index that is not in the skip String, or -1 if all characters up to and including the starting index are in the skip String.
See Also:
  `String.indexOf(int)`, `charAt(int)`

#### skipBackOver

    public int skipBackOver(int index,
                   String skip)

See Also:
  `skip_back_over(int, String)`

#### skip_until

    public int skip_until(int index,
                 String find)

Skips until a character also in the find String is found, starting with the character at the specified index.

Parameters:
  `index` - The index of the first character to test.
  `find` - The set of potential characters to find.
Returns:
  The index of the character at or beyond the starting index that is in the find String, or -1 if all remaining characters from the starting index are not in the find String.
See Also:
  `String.indexOf(int)`, `charAt(int)`

#### skipUntil

    public int skipUntil(int index,
                String find)

See Also:
  `skip_until(int, String)`

#### skip_back_until

    public int skip_back_until(int index,
                      String find)

Skips back until a character also in the find String is found, starting with the character at the specified index.

Parameters:
  `index` - The index of the first character to test.
  `find` - The set of potential characters to find.
Returns:
  The index of the last character at or before the starting index that is in the find String, or -1 if all characters up to and including the starting index are not in the find String.
See Also:
  `String.indexOf(int)`, `charAt(int)`

#### skipBackUntil

    public int skipBackUntil(int index,
                    String find)

See Also:
  `skip_back_until(int, String)`

#### index_of

    public int index_of(int index,
               char character)

Gets the index of the next character matching the specified character, starting with the specified index.

Parameters:
  `index` - The index of the first character to test.
  `character` - The character to match.
Returns:
  The index of the next character at or beyond the starting index that matches the specified character, or -1 if all remaining characters do not match the specified character.
See Also:
  `String.indexOf(int, int)`

#### indexOf

    public int indexOf(int index,
              char character)

See Also:
  `index_of(int, char)`

#### index_of

    public int index_of(int index,
               String pattern)

Gets the index of the next occurance of the substring matching the pattern String, starting with the specified index.

Parameters:
  `index` - The starting index from which to search for the pattern String.
  `pattern` - The pattern String to match.
Returns:
  The index of the next substring at or beyond the starting index that matches the pattern String, or -1 if the pattern is not found.
See Also:
  `String.indexOf(String, int)`

#### indexOf

    public int indexOf(int index,
              String pattern)

See Also:
  `index_of(int, String)`

#### equals

    public boolean equals(int index,
                 String pattern)

Tests if the pattern String is equal to the substring of the same length starting at the index.

Parameters:
  `index` - The starting index from which to test for the pattern String.
  `pattern` - The pattern String to match.
Returns:
  true if they are equal; false otherwise.
See Also:
  `String.startsWith(String, int)`

#### equals_ignore_case

    public boolean equals_ignore_case(int index,
                             String pattern)

Tests if the pattern String is equal regardless of case to the substring of the same length starting at the index.

Parameters:
  `index` - The starting index from which to test for the pattern String.
  `pattern` - The pattern String to match.
Returns:
  true if they are equal while ignoring case; false otherwise.
See Also:
  `String.regionMatches(boolean, int, String, int, int)`

#### equalsIgnoreCase

    public boolean equalsIgnoreCase(int index,
                           String pattern)

See Also:
  `equals_ignore_case(int, String)`

#### replace

    public String_Buffer replace(int index,
                        String old_string,
                        String new_string)

Replaces all occurances of the old_string with the new_string, starting at the specified index.

Recursive replacements are avoided: If the new_string contains the old_string, the new old_string remains in its location within the new_string; the search for an old_string continues at the location after where the new_string has been inserted.

Parameters:
  `index` - The starting index from which to test for the old_string.
  `old_string` - The substring to find.
  `new_string` - The String to replace the old_string.
Returns:
  This, possibly modified, String_Buffer.
See Also:
  `index_of(int, String)`, `StringBuffer.replace(int, int, String)`

#### replace_span

    public String_Buffer replace_span(int index,
                             String span,
                             String substitute)

Replaces all sequences of any and all characters from the span String with the substitute String, starting at the specified index.

Each replacement occurs on the longest sequence of characters all from the span String set.

Recursive replacements are avoided: If the substitute contains any characters from the span the substitute remains unaffected; the search for another span continues at the location after where the substitute has been inserted.

Parameters:
  `index` - The starting index from which to test for span characters.
  `span` - The set of potential characters for replacement.
  `substitute` - The String to replace each span sequence.
Returns:
  This, possibly modified, String_Buffer.
See Also:
  `skip_until(int, String)`, `skip_over(int, String)`, `StringBuffer.replace(int, int, String)`

#### replaceSpan

    public String_Buffer replaceSpan(int index,
                            String span,
                            String substitute)

See Also:
  `replace_span(int, String, String)`

#### trim

    public String_Buffer trim(int start,
                     int end)

Trims whitespace from both ends of a substring of the String_Buffer, starting at the start index and ending before the end index.

Parameters:
  `start` - The index of the starting character of the substring.
  `end` - The index of the end (last + 1) character of the substring.
Returns:
  This, possibly modified, String_Buffer.
See Also:
  `StringBuffer.substring(int, int)`, `String.trim()`, `StringBuffer.replace(int, int, String)`

#### trim

    public String_Buffer trim()

Trims whitespace from both ends of the String_Buffer.

Returns:
  This, possibly modified, String_Buffer.
See Also:
  `trim(int, int)`

#### trim_beginning

    public String_Buffer trim_beginning()

Trims whitespace from the beginning of the String_Buffer.

Returns:
  This, possibly modified, String_Buffer.
See Also:
  `Character.isWhitespace(char)`, `delete(int, int)`

#### trim_end

    public String_Buffer trim_end()

Trims whitespace from the end of the String_Buffer.

Returns:
  This, possibly modified, String_Buffer.
See Also:
  `Character.isWhitespace(char)`, `delete(int, int)`

#### trim

    public String_Buffer trim(char character)

Trims a character from both ends of a string.

Parameters:
  `character` - The character to be trimmed off the ends.
Returns:
  This, possibly modified, String_Buffer.

#### trim_all

    public String_Buffer trim_all(char character)

Trims a sequence of the same character from both ends of a string.

Parameters:
  `character` - The character to be trimmed off the ends.
Returns:
  This, possibly modified, String_Buffer.

#### clear

    public String_Buffer clear()

Empties the buffer of all characters.

Returns:
  This String_Buffer.

#### clean

    public String_Buffer clean(char character)

Clean all unescaped occurances of a character from a String.

Escaped characters, which are preceded by a backslash ('\') character, are always ignored. All other characters that match the character to be cleaned are removed from the String.

The backslash character can be cleaned from the String. Escaped backslash characters will result in a single backslash character. Thus a String might be first cleaned of a non-backslash character and then cleaned of backslash characters to remove any escape characters remaining from the previous cleaning.

Parameters:
  `character` - The char to be cleaned from the String.
Returns:
  This, possibly modified, String_Buffer.
See Also:
  `escape_to_special()`

#### escape_to_special

    public String_Buffer escape_to_special()

Substitutes escape sequences with special characters.

The following escape sequences, and their corresponding special characters, are recognized:

> \b - Backspace (BS)
> \t - Horizontal tab (HT)
> \n - Newline (NL)
> \f - Form feed (FF)
> \r - Carriage return (CR)
> \X - The character X
> \0nnn - The character having the octal value nnn (0 <= nnn <= 177777)

The escape sequences will be substituted for their corresponding special characters, which will shorten the length of the String_Buffer. All backslash characters, except those that are themselves escaped, will be removed from the String_Buffer.

N.B.: If an octal valued escape sequence is immediately followed by an octal digit (0-7) the latter will be mistaken for part of the escape sequence unless the maximum 6 digit limit has been reached. Because of this it may be preferable to encode non-printable characters using standard `character references`.

Returns:
  This String_Buffer. The conversion is done in-place.
See Also:
  `special_to_escape()`

#### escape_to_special

    public static String escape_to_special(String string)

Substitutes escape sequences with special characters.

Parameters:
  `string` - The String to be filtered. If null, null is returned.
Returns:
  The filtered String.
See Also:
  `escape_to_special()`

#### special_to_escape

    public String_Buffer special_to_escape()

Substitutes special characters with escape sequences.

All control characters - less than ' ' (32) or greater than '~' (126) - will be substituted with escape sequences:

> \b - for backspace (BS, 8)
> \t - for horizontal tab (HT, 9)
> \n - for newline (NL, 10)
> \f - for form feed (FF, 12)
> \r - for carriage return (CR, 13)
> \0nnn - for all other special characters where nnn is the octal value of the character (1-6 digits).

The escape sequences will substitute for their corresponding special characters, which will increase the length of the String_Buffer.

N.B.: If an octal valued escape sequence is immediately followed by an octal digit (0-7) the latter will be mistaken for part of the escape sequence unless the maximum 6 digit limit has been reached. Because of this it may be preferable to encode non-printable characters using standard `character references`.

Returns:
  This String_Buffer. The conversion is done in-place.
See Also:
  `escape_to_special()`

#### special_to_escape

    public static String special_to_escape(String string)

Substitutes special characters with escape sequences.

Parameters:
  `string` - The String to be filtered. If null, null is returned.
Returns:
  The filtered String.
See Also:
  `special_to_escape()`

#### from_character_references

    public String_Buffer from_character_references()

Substitutes numeric character references with characters.

All numeric character references will be replaced with their single character value. A numeric character references has the form:

> &#[X]N;

Where N is the text representation of the character value. If the 'X' (case insensitive) is present the value is in hexadecimal representation, otherwise it is decimal. N.B.: The semicolon terminating the numerical character reference must be present as well as the &# prefix that signals the presence of the reference.

Returns:
  This String_Buffer. The conversion is done in-place.
See Also:
  `to_character_references()`

#### from_character_references

    public static String from_character_references(String string)

Substitutes numeric character references with characters.

Parameters:
  `string` - The String to be filtered. If null, null is returned.
Returns:
  The filtered String.
See Also:
  `from_character_references()`

#### to_character_references

    public String_Buffer to_character_references()

Substitutes non-printable characters with numeric character references.

All non-printable characters - less than ' ' (32) or greater than '~' (126) - will be substituted with hexadecimal numeric character references. A hexadecimal numeric character references has the form:

> &#X N;

Where N is the hexadecimal (uppercase) representation of the character value.

Returns:
  This String_Buffer. The conversion is done in-place.
See Also:
  `from_character_references()`, `special_to_escape()`

#### to_character_references

    public static String to_character_references(String string)

Substitutes non-printable characters with numeric character references.

Parameters:
  `string` - The String to be filtered. If null, null is returned.
Returns:
  The filtered String.
See Also:
  `to_character_references()`

#### to_printable_ASCII

    public String_Buffer to_printable_ASCII()

Substitute all non-ASCII and unprintable characters with a question mark.

All non-printable characters - less than ' ' (32) or greater than '~' (126) - will be substituted with the `question mark` ('?') character.

Returns:
  This String_Buffer. The conversion is done in-place.

#### to_printable_ASCII

    public static String to_printable_ASCII(String string)

Substitute all non-ASCII and unprintable characters with a question mark.

Parameters:
  `string` - The string to be filtered. If null, null is returned.
Returns:
  The filtered String.
See Also:
  `to_printable_ASCII()`