PIRL

PIRL.Strings
Class String_Buffer

java.lang.Object
  extended by 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()

PIRL

Copyright (C) \ 2003-2009 Bradford Castalia, University of Arizona