edu.utexas.its.eis.tools.qwicap.util
Class Characters

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.util.Characters

All Implemented Interfaces:

CharSequence

public final class Characters
extends Object
implements CharSequence

The Characters class transparently represents either a String, or a subsection of a character array. Conversions from String to character array, and vice versa, are avoided wherever possible, and if a conversion must be performed to satisfy a caller, the conversion is performed only once, and the result is cached. This means that modifications to a character array passed to the constructor, or returned by the getArray() method, have the potential to invalidate the cache. So do NOT modify those arrays.

Convenience methods such as write, println and append are provided so that those common operations can be performed without the caller having to be aware of the presence/absence of char[] or String forms in any instance of this class, and in order to avoid conversions between those forms unless absolutely necessary.

Author:

Chris W. Johnson

Constructor Summary

Characters(char[] C)
Creates a Characters object that represents an entire char array.

Characters(char[] C, int COffset, int CLength)
Creates a Characters object that represents a subsection of a char array.

Characters(String S)
Creates a Characters object that represents a String.

Characters(StringBuffer SB)
Creates a Characters object that represents the String supplied by the specified StringBuffer object.

Characters(StringBuilder SB)
Creates a Characters object that represents the String supplied by the specified StringBuffer object.

Method Summary

Characters	append(Characters Other) Creates a new Characters object representing the concatenation of first this object, and then the specified Characters object.
void	append(StringBuffer Buff) Appends the characters represented by this object to the specified StringBuffer.
void	append(StringBuilder Buff) Appends the characters represented by this object to the specified StringBuilder.
char	charAt(int Index) Returns the char value at the specified index.
boolean	equals(char[] OtherChars, int OtherOffset, int OtherLength) Compares the characters in this object to the specified subsection of a char array.
boolean	equals(Object OtherObj) Compares this object to another object.
char[]	getArray() Returns the charactes of this object represented as an array of characters.
int	getArrayOffset() Returms the offset of the first character represented by this object in the char array returned by the getArray method.
boolean	hasArray() Returns true if this object already contains a char array representation of its characters, or false if such a representation has not yet been created.
int	hashCode() Return the hash code for these characters.
boolean	hasString() Returns true if this object already contains a String representation of its characters, or false if such a representation has not yet been created.
int	indexOf(int Char) Returns the index of the first occurrence of the specified character, or -1 if the character was not found.
int	indexOf(int Char, int Offset) Returns the index of the first occurrence of the specified character, or -1 if the character was not found.
int	length() Returns the length of this character sequence.
void	print(PrintStream Out) Prints the characters of this object to the specified PrintStream.
void	print(PrintWriter Out) Prints the characters of this object to the specified PrintWriter.
void	println(PrintStream Out) Uses the specified PrintStream object's println method to print the characters of this object.
void	println(PrintWriter Out) Uses the specified PrintWriter object's println method to print the characters of this object.
boolean	startsWith(Characters Other) Compares the initial characters of this object with all the characters of another Characters object.
CharSequence	subSequence(int FirstCharOffset, int LastCharOffset) Returns a Characters instance representing a subsequence of this object's characters.
String	substring(int FirstCharOffset) Retrieves a substring of this object's characters, beginning with the character at the specified offset, and including all of the characters that follow it.
String	substring(int FirstCharOffset, int LastCharOffset) Retrieves a substring of this object's characters.
String	toString() Returns the String representation of the characters represented by this Characters object.
void	write(Writer Out) Writes the characters of this object to the specified Writer.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Characters

public Characters(String S)

Creates a Characters object that represents a String.

Parameters:

S - The String to be represented by this Characters object.

Characters

public Characters(StringBuffer SB)

Creates a Characters object that represents the String supplied by the specified StringBuffer object.

Parameters:

SB - The StringBuffer object containing the String to be represented by this Characters object.

Characters

public Characters(StringBuilder SB)

Creates a Characters object that represents the String supplied by the specified StringBuffer object.

Parameters:

SB - The StringBuilder object containing the String to be represented by this Characters object.

Characters

public Characters(char[] C)

Creates a Characters object that represents an entire char array.

Parameters:

C - The char array to be represented by this Characters object.

Characters

public Characters(char[] C,
                  int COffset,
                  int CLength)

Creates a Characters object that represents a subsection of a char array.

Parameters:

C - The char array to be represented by this Characters object.

COffset - Index of the first character in the C array to be represented by this object.

CLength - Number of characters, beginning at COffset, to be represented by this object.

Method Detail

length

public int length()

Returns the length of this character sequence. The length is the number of 16-bit chars in the sequence.

Specified by:

length in interface CharSequence

Returns:

The length of this character sequence. The length is the number of 16-bit chars in the sequence.

getArray

public char[] getArray()

Returns the charactes of this object represented as an array of characters. If only a String representation of the characters exists, a char array is created and cached for future use.

For efficiency, the array returned is not a clone or copy of the character array used within this object, it is that actual array. Consequently, alterations to the contents of the array are possible, but strongly discouraged. Among other things, alterations to the array will leave the array out of synch with the String representation of these same characters that may also exist. If so, callers treating this Characters object as a source for an array of chars will get different results from those treating this Characters object as a source for a String. All kinds of bad things might come from this. If this class is needed in a context where programmers can't be depended upon to respect this limitation, a subclass should be created which overrides this method to return a copy of the array (and overrides getArrayOffset to always return 0).

Returns:

The array containing the characters in this object. The contents of this array should not be altered.

getArrayOffset

public int getArrayOffset()

Returms the offset of the first character represented by this object in the char array returned by the getArray method.

Returns:

Offset of the first character represented by this object in the char array returned by getArray.

equals

public boolean equals(Object OtherObj)

Compares this object to another object. Useful comparisons may be performed only if the other object is a String or another Characters object. In all other cases, this method returns false.

Overrides:

equals in class Object

Parameters:

OtherObj - Another object to compare with this one.

Returns:

true if this object represents a sequence of characters equivalent to the supplied object, false otherwise.

equals

public boolean equals(char[] OtherChars,
                      int OtherOffset,
                      int OtherLength)

Compares the characters in this object to the specified subsection of a char array. The comparison is case-sensitive.

Parameters:

OtherChars - The array of characters to be compared to the characters in this object.

OtherOffset - The index into OtherChars at which comparison is to begin.

OtherLength - The number of characters in OtherChars, starting at OtherOffset, to be compared.

Returns:

true if the characters match, false otherwise.

hashCode

public int hashCode()

Return the hash code for these characters. For the any given set of characters, the hash code is identical whether the characters were supplied as a String object, or as an array of characters.

Overrides:

hashCode in class Object

Returns:

The hash code for the characters represented by this object.

startsWith

public boolean startsWith(Characters Other)

Compares the initial characters of this object with all the characters of another Characters object. The comparison is case-sensitive.

Parameters:

Other - The Characters object to be compared with the start of this one.

Returns:

true if this object begins with the characters of the Other object, false otherwise.

substring

public String substring(int FirstCharOffset)

Retrieves a substring of this object's characters, beginning with the character at the specified offset, and including all of the characters that follow it.

Parameters:

FirstCharOffset - Offset of the first character, inclusive.

Returns:

The requested substring.

substring

public String substring(int FirstCharOffset,
                        int LastCharOffset)

Retrieves a substring of this object's characters.

Parameters:

FirstCharOffset - Offset of the first character, inclusive.

LastCharOffset - Offset of the final character, exclusive.

Returns:

The requested substring.

subSequence

public CharSequence subSequence(int FirstCharOffset,
                                int LastCharOffset)

Returns a Characters instance representing a subsequence of this object's characters.

Specified by:

subSequence in interface CharSequence

Parameters:

FirstCharOffset - Offset of the first character, inclusive.

LastCharOffset - Offset of the final character, exclusive.

Returns:

The requested subsequence, represented by an instance of Characters.

charAt

public char charAt(int Index)
            throws IndexOutOfBoundsException

Returns the char value at the specified index. An index ranges from zero to length() - 1. The first char value of the sequence is at index zero, the next at index one, and so on, as for array indexing.

If the char value specified by the index is a surrogate, the surrogate value is returned.

Specified by:

charAt in interface CharSequence

Parameters:

Index - The index of the character to be returned.

Returns:

The char at the specified index.

Throws:

IndexOutOfBoundsException - If the index is invalid.

indexOf

public int indexOf(int Char)

Returns the index of the first occurrence of the specified character, or -1 if the character was not found.

Parameters:

Char - Character to be searched for.

Returns:

Index of the first occurrence of Char, or -1 if it was not found.

indexOf

public int indexOf(int Char,
                   int Offset)

Returns the index of the first occurrence of the specified character, or -1 if the character was not found.

Parameters:

Char - Character to be searched for.

Offset - The offset at which to begin the search.

Returns:

Index of the first occurrence of Char, or -1 if it was not found.

toString

public String toString()

Returns the String representation of the characters represented by this Characters object. This method always returns the same String object for efficiency. If only a character array representation of the characters exists, a new String object is created and cached for future use.

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

Returns:

The characters of this object represented as a String.

hasString

public boolean hasString()

Returns true if this object already contains a String representation of its characters, or false if such a representation has not yet been created.

Returns:

true if a String representation of this object has already exists, false otherwise.

hasArray

public boolean hasArray()

Returns true if this object already contains a char array representation of its characters, or false if such a representation has not yet been created.

Returns:

true if a char array representation of this object has already exists, false otherwise.

append

public Characters append(Characters Other)

Creates a new Characters object representing the concatenation of first this object, and then the specified Characters object.

Parameters:

Other - The characters to be appended to this object.

Returns:

A new Characters object representing this + Other.

append

public void append(StringBuffer Buff)

Appends the characters represented by this object to the specified StringBuffer.

Parameters:

Buff - The StringBuffer to which this object's characters should be appended.

append

public void append(StringBuilder Buff)

Appends the characters represented by this object to the specified StringBuilder.

Parameters:

Buff - The StringBuilder to which this object's characters should be appended.

print

public void print(PrintStream Out)

Prints the characters of this object to the specified PrintStream.

Parameters:

Out - PrintStream to which this object's characters should be printed.

println

public void println(PrintStream Out)

Uses the specified PrintStream object's println method to print the characters of this object.

Parameters:

Out - PrintStream to which this object's characters should be printed.

print

public void print(PrintWriter Out)
           throws IOException

Prints the characters of this object to the specified PrintWriter.

Parameters:

Out - PrintWriter to which this object's characters should be printed.

Throws:

IOException - If thers's a problem printing to the PrintWriter.

println

public void println(PrintWriter Out)
             throws IOException

Uses the specified PrintWriter object's println method to print the characters of this object.

Parameters:

Out - PrintWriter to which this object's characters should be printed.

Throws:

IOException - If thers's a problem printing to the PrintWriter.

write

public void write(Writer Out)
           throws IOException

Writes the characters of this object to the specified Writer.

Parameters:

Out - Writer to which this object's characters should be written.

Throws:

IOException - If thers's a problem writing to the Writer.