ewe.util
Class SubString

java.lang.Object
  ewe.util.SubString

All Implemented Interfaces:

Comparable

public class SubString

extends Object

implements Comparable

This is a very specialized Utility class used for bulk processing of text strings, while minimizing overheads of new Object creation.

A SubString consists of a reference to a character array (which may be shared by other SubStrings), a start index within the array and a length value for the sub-string.

You can manipulate a SubString in many of the same ways as you do a String, but unlike a String, a SubString is mutable (since you have full access to its data and its start and length values).

Field Summary

static int	BACKWARDS An option for equals().
char[]	data
static int	IGNORE_CASE An option for equals().
int	length
int	start
static int	STARTS_WITH An option for equals().

Constructor Summary

SubString()
Create a new SubString - use one of the set() methods to setup the text for the SubString.

Method Summary

char	charAt(int idx) Return the character at a particular index.
static int	compare(char[] one, int oneStart, int oneLength, char[] two, int twoStart, int twoLength) This does a numeric char for char comparison.
int	compareTo(Object other) Compare this SubString with either another SubString or a String.
int	compareTo(Object other, int options) Compare this SubString with either another SubString or a String.
void	copyInto(byte[] dest, int offset, boolean ascii) Copy all the characters of this substring into a byte array.
void	copyInto(byte[] dest, int offset, int len, int startPoint, boolean ascii) Copy a subset of this SubStrings data into a byte array.
void	copyInto(char[] dest, int offset) Copy all the characters of this substring into a character array.
void	copyInto(char[] dest, int offset, int len, int startPoint) Copy a subset of this SubStrings data into a character array.
boolean	endsWith(String endWith) Check if the SubString endsWith a particular String.
static boolean	equals(char[] big, int bigStart, int bigLength, char[] small, int smallStart, int smallLength, int options) This compares the character sequence given by the "small" parameters to the character sequence given by the "big" parameters.
boolean	equals(Object other) Compare this SubString with either another SubString or a String.
SubString	getCopy(SubString destination, char[] copyDataInto) Get a copy of the SubString.
SubString	getNew() Get a new SubString().
int	hashCode() As specified in the hashCode() contract, this returns the same hashCode that a String with the same text would return.
static int	indexOf(char what, char[] str, int strStart, int strLength, int start, int options) Find the index of a character within an array of characters, looking either backwards or forwards.
boolean	isNull() Return if this SubString is null (i.e.
int	length() Get the length of the SubString.
void	replace(char[] what, char[] with)
SubString	set(char[] dt, int st, int len)
SubString	set(String string)
SubString	set(String string, int st, int len) Create a SubString based on a substring of the text in the provided String.
int	split(char separator, Vector destination) This will split this substring and place the results as a series of SubString objects in the destination list.
int	split(char separator, Vector destination, int destinationStart) This will split this substring and place the results as a series of SubString objects in the destination list.
static Vector	split(String what, char separator, Vector dest) Split a String into smaller sub Strings placed in an output Vector.
boolean	startsWith(String startWith) Check if the SubString startsWith a particular String.
String	substring(int start, int length) Get a new SubString that is a substring of this SubString.
SubString	substring(int start, int length, SubString destination) Get a new SubString that is a substring of this SubString.
SubString	substring(int start, int length, SubString destination, char[] copyDataInto) Get a new SubString that is a substring of this SubString, optionally copying the data out into a new array.
void	toLowerCase()
String	toString() Return a String representation of this SubString.
void	toUpperCase()
void	trim() Trim the SubString so there are no leading or trailing spaces or Tabs.

Methods inherited from class java.lang.Object

clone, finalize, getClass

Field Detail

data

public char[] data

start

public int start

length

public int length

IGNORE_CASE

public static final int IGNORE_CASE

An option for equals().

See Also:

Constant Field Values

STARTS_WITH

public static final int STARTS_WITH

An option for equals().

See Also:

Constant Field Values

BACKWARDS

public static final int BACKWARDS

An option for equals().

See Also:

Constant Field Values

Constructor Detail

SubString

public SubString()

Create a new SubString - use one of the set() methods to setup the text for the SubString.

Method Detail

toString

public String toString()

Return a String representation of this SubString.

Overrides:

toString in class Object

Returns:

a String representing this object.

isNull

public boolean isNull()

Return if this SubString is null (i.e. it's data is null).

length

public int length()

Get the length of the SubString.

charAt

public char charAt(int idx)

Return the character at a particular index.

copyInto

public void copyInto(char[] dest,
                     int offset)

Copy all the characters of this substring into a character array.

Parameters:

dest - The destination character array.

offset - The offset in the destination to start copying into.

copyInto

public void copyInto(char[] dest,
                     int offset,
                     int len,
                     int startPoint)

Copy a subset of this SubStrings data into a character array.

Parameters:

dest - The destination character array.

offset - The offset in the destination to start copying into.

len - The number of characters to copy.

startPoint - The first index in this substring to copy from.

copyInto

public void copyInto(byte[] dest,
                     int offset,
                     boolean ascii)

Copy all the characters of this substring into a byte array.

Parameters:

dest - The destination byte array.

offset - The offset in the destination to start copying into.

ascii - if this is true then only the low byte is copied into the destination. If you want to do Utf8 encoding, then see the encode method.

copyInto

public void copyInto(byte[] dest,
                     int offset,
                     int len,
                     int startPoint,
                     boolean ascii)

Copy a subset of this SubStrings data into a byte array.

Parameters:

dest - The destination byte array.

offset - The offset in the destination to start copying into.

len - The number of characters to copy.

startPoint - The first index in this substring to copy from.

ascii - if this is true then only the low byte is copied into the destination. If you want to do Utf8 encoding, then see the encode method.

set

public SubString set(char[] dt,
                     int st,
                     int len)

set

public SubString set(String string)

set

public SubString set(String string,
                     int st,
                     int len)

Create a SubString based on a substring of the text in the provided String. A copy of the String data is made for this SubString.

getNew

public SubString getNew()

Get a new SubString(). Objects which override SubString can return a different object.

split

public int split(char separator,
                 Vector destination)

This will split this substring and place the results as a series of SubString objects in the destination list. If the destination contains SubString objects already, then each will be used in sequence as a destination. If there are not enough SubStrings in the destination then more will be added. If there are too many SubStrings extra ones will NOT be removed. The return value is the number of substrings found.

Parameters:

separator - The separator character. A separator of ' ' (a space) will also use the TAB ('\t') as a separator. A space separator also has the property that a sequence of more than one space or TAB characters will be considered as just one separator. So a line like "hello there how are you" will be separated into the five words exactly.

destination - This is the destination vector (which must NOT be null) in which SubString objects representing each separated text is placed.

Returns:

The number of found SubStrings in the text.

split

public int split(char separator,
                 Vector destination,
                 int destinationStart)

This will split this substring and place the results as a series of SubString objects in the destination list. If the destination contains SubString objects already, then each will be used in sequence as a destination. If there are not enough SubStrings in the destination then more will be added. If there are too many SubStrings extra ones will NOT be removed. The return value is the number of substrings found.

Parameters:

separator - The separator character. A separator of ' ' (a space) will also use the TAB ('\t') as a separator. A space separator also has the property that a sequence of more than one space or TAB characters will be considered as just one separator. So a line like "hello there how are you" will be separated into the five words exactly.

destination - This is the destination vector (which must NOT be null) in which SubString objects representing each separated text is placed.

Returns:

The number of found SubStrings in the text.

split

public static Vector split(String what,
                           char separator,
                           Vector dest)

Split a String into smaller sub Strings placed in an output Vector.

Parameters:

what - The String to split.

separator - The separator character.

dest - A destination Vector (which may be null).

Returns:

A Vector containing the exact number of Strings found in the String.

equals

public static boolean equals(char[] big,
                             int bigStart,
                             int bigLength,
                             char[] small,
                             int smallStart,
                             int smallLength,
                             int options)

This compares the character sequence given by the "small" parameters to the character sequence given by the "big" parameters.

indexOf

public static int indexOf(char what,
                          char[] str,
                          int strStart,
                          int strLength,
                          int start,
                          int options)

Find the index of a character within an array of characters, looking either backwards or forwards.

Parameters:

what - The character to look for.

str - The array of characters to look in.

strStart - The start of the source characters in the array.

strLength - The number of source characters in the array.

start - The location in str to start looking from (which should be >= strStart and < strStart+strLength). This character is always included in the search whether going backwards or forwards.

options - This can be 0 or BACKWARDS to start searching backwards.

Returns:

The index of the character in the string, or -1 if it is not found.

compare

public static int compare(char[] one,
                          int oneStart,
                          int oneLength,
                          char[] two,
                          int twoStart,
                          int twoLength)

This does a numeric char for char comparison.

compareTo

public int compareTo(Object other)

Compare this SubString with either another SubString or a String.

Specified by:

compareTo in interface Comparable

Parameters:

other - Either another SubString or a String.

Returns:

greater than 1 if this SubString is considered greater than the Object, less than 1 if this SubString is considered less than the Object, and 0 if this SubString is considered equal to the Object.

compareTo

public int compareTo(Object other,
                     int options)

Compare this SubString with either another SubString or a String.

Parameters:

other - Either another SubString or a String.

options - This can be IGNORE_CASE or 0.

Returns:

greater than 1 if this SubString is considered greater than the Object, less than 1 if this SubString is considered less than the Object, and 0 if this SubString is considered equal to the Object.

equals

public boolean equals(Object other)

Compare this SubString with either another SubString or a String.

Overrides:

equals in class Object

Parameters:

other - Either another SubString or a String.

Returns:

true if the text represented by this SubString and the other are equal.

hashCode

public int hashCode()

As specified in the hashCode() contract, this returns the same hashCode that a String with the same text would return.

Overrides:

hashCode in class Object

substring

public SubString substring(int start,
                           int length,
                           SubString destination,
                           char[] copyDataInto)

Get a new SubString that is a substring of this SubString, optionally copying the data out into a new array.

Parameters:

start - The first index in this SubString.

length - The number of characters.

destination - The destination SubString. If this is null a new one will be created.

copyDataInto - If this is null then the new SubString will reference the original character array for its data. If it is not null then the characters will be copied into this array. if this array is not big enough, a new one will be created and that one will be used instead.

Returns:

A new SubString (or the provided destination) representing part or all of the original substring.

toUpperCase

public void toUpperCase()

toLowerCase

public void toLowerCase()

substring

public SubString substring(int start,
                           int length,
                           SubString destination)

Get a new SubString that is a substring of this SubString.

Parameters:

start - The first index in this SubString.

length - The number of characters.

destination - The destination SubString. If this is null a new one will be created.

Returns:

A new SubString (or the provided destination) representing part or all of the original substring.

substring

public String substring(int start,
                        int length)

Get a new SubString that is a substring of this SubString.

Parameters:

start - The first index in this SubString.

length - The number of characters.

Returns:

A new String representing part or all of the original substring.

getCopy

public SubString getCopy(SubString destination,
                         char[] copyDataInto)

Get a copy of the SubString.

Parameters:

destination - The destination SubString. If this is null a new one will be created.

copyDataInto - If this is null then the new SubString will reference the original character array for its data. If it is not null then the characters will be copied into this array. if this array is not big enough, a new one will be created and that one will be used instead.

Returns:

A new SubString (or the provided destination) representing part or all of the original substring.

startsWith

public boolean startsWith(String startWith)

Check if the SubString startsWith a particular String.

endsWith

public boolean endsWith(String endWith)

Check if the SubString endsWith a particular String.

trim

public void trim()

Trim the SubString so there are no leading or trailing spaces or Tabs.

replace

public void replace(char[] what,
                    char[] with)