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.

Version:

1.21

Author:

Bradford Castalia, UA/PIRL

See Also:

StringBuffer

Field Summary

static String	ID
static String	NL
static char	QUESTIONABLE_CHARACTER

Constructor Summary

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

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:

&#XN;

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