com.dautelle.util
Class FastString

java.lang.Object
  com.dautelle.realtime.RealtimeObject
      com.dautelle.util.FastString

All Implemented Interfaces:

java.lang.CharSequence, java.lang.Comparable, Realtime, java.io.Serializable

public final class FastString

extends RealtimeObject

implements java.lang.CharSequence, java.lang.Comparable

This class represents a Real-Time String.

This class is very much like java.lang.String; but a lot faster (e.g. string concatenation is as fast as with java.lang.StringBuffer) and more flexible as it allows for search, concatenation and comparison with any CharSequence such as itself, java.lang.String or java.lang.StringBuffer.

Instances of this class are immutable (but like any real-time object, instances allocated in a pool context must be exported if referenced after exiting the pool context).

In case of successive concatenations, it may be advantageous to start with a FastString whose character buffer is capable of holding the final concatenated string (ref. newInstance(int capacity)), this to avoid unnecessary character buffer allocation. Then FastString can advantageously be used in place of java.lang.StringBuffer(capacity) (as fast, but immutable). For example:

         // Constructs an immutable fullName.
         FastString fullName = FastString.newInstance(64). 
             concat(firstName).concat(" ").concat(lastName);

Finally, as for any CharSequence, parsing to primitive types can be achieved using the TypeFormat utility class.

Version:

6.0, January 18, 2004

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

static class

FastString.Value This inner class represents a mutable image of an immutable FastString.

Nested classes inherited from class com.dautelle.realtime.RealtimeObject

RealtimeObject.Factory

Field Summary

static FastString

EMPTY Holds the empty string.

Constructor Summary

FastString(java.lang.CharSequence chars)
Creates a constant FastString always allocated on the heap, corresponding to the specified character sequence.

Method Summary

char	charAt(int index) Returns the character at the specified index.
int	compareTo(java.lang.CharSequence chars) Compares this FastString with the specified character sequence lexicographically.
int	compareTo(java.lang.Object that) Compares this FastString to another object.
FastString	concat(java.lang.CharSequence chars) Concatenates the specified character sequence to the end of this FastString.
boolean	endsWith(java.lang.CharSequence suffix) Indicates if this FastString ends with the specified suffix.
boolean	equals(java.lang.Object that) Compares this FastString against the specified object.
boolean	equalsIgnoreCase(java.lang.CharSequence chars) Compares this FastString to the specified character sequence ignoring case considerations.
java.lang.Object	export() Exports this object out of the current pool context.
void	getChars(int start, int end, char[] dest, int destPos) Copies the characters from this FastString into the destination character array.
int	hashCode() Returns the hash code for this real-time string.
int	indexOf(java.lang.CharSequence chars) Returns the index within this FastString of the first occurrence of the specified character sequence searching forward.
int	indexOf(java.lang.CharSequence chars, int fromIndex) Returns the index within this FastString of the first occurrence of the specified character sequence searching forward from the specified index.
int	lastIndexOf(java.lang.CharSequence chars) Returns the index within this FastString of the last occurrence of the specified character sequence searching backward.
int	lastIndexOf(java.lang.CharSequence chars, int fromIndex) Returns the index within this FastString of the last occurrence of the specified character sequence searching backward from the specified index.
int	length() Returns the length of this FastString.
static FastString	newInstance(int capacity) Returns an empty FastString having an internal data array of specified capacity.
FastString	replace(char oldChar, char newChar) Returns a FastString where all occurrences of oldChar have been replaced with newChar.
boolean	startsWith(java.lang.CharSequence prefix) Indicates if this FastString starts with the specified prefix.
boolean	startsWith(java.lang.CharSequence prefix, int index) Indicates if this FastString starts with the specified prefix at the specified index.
java.lang.CharSequence	subSequence(int start, int end) Returns a new character sequence that is a subsequence of this sequence.
FastString	substring(int start) Returns a sub-string of this FastString.
FastString	substring(int start, int end) Returns a sub-string of this FastString.
java.lang.Object	toHeap() Moves this object to the heap.
java.lang.String	toString() Returns the text representation of this FastString.
FastString	trim() Returns a copy of this FastString, with leading and trailing whitespace omitted.
static FastString	valueOf(boolean b) Returns the FastString representing the boolean argument.
static FastString	valueOf(char c) Returns the FastString representing the char argument.
static FastString	valueOf(char[] data, int first, int length) Returns the FastString that contains the characters from the specified subarray of characters.
static FastString	valueOf(java.lang.CharSequence chars) Returns the FastString representing the specified character sequence.
static FastString	valueOf(double d) Returns the FastString representing the specified double argument.
static FastString	valueOf(int i) Returns the FastString representing the specified int argument (decimal representation).
static FastString	valueOf(long l) Returns the FastString representing the specified long argument (decimal representation).

Methods inherited from class com.dautelle.realtime.RealtimeObject

clone, isLocalObject, isPoolObject, recycle

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY

public static final FastString EMPTY

Holds the empty string.

Constructor Detail

FastString

public FastString(java.lang.CharSequence chars)

Creates a constant FastString always allocated on the heap, corresponding to the specified character sequence. This method is typically used to define static FastString constants.

Parameters:

chars - the CharSequence source.

Method Detail

newInstance

public static FastString newInstance(int capacity)

Returns an empty FastString having an internal data array of specified capacity.

Note: Despite of their immutability, strings may share the same data array (e.g. substring(int)). In case of successive concatenations, it may be advantageous to start with a FastString capable of holding the final concatenated string. Then all intermediate strings share the same data array (they are substrings) and no additional data array need to be allocated. Doing so, FastString behave very much like StringBuffer (as fast) but still maintain their immutability requirement.

Parameters:

capacity - the maximum number of characters during concatenation; beyond which new allocations of internal data arrays may occur.

Returns:

an empty real-time string of specified capacity.

valueOf

public static FastString valueOf(char[] data,
                                 int first,
                                 int length)

Returns the FastString that contains the characters from the specified subarray of characters.

Parameters:

data - the source of the characters.

first - the index of the first character.

length - the length of the subarray.

Returns:

the corresponding real-time string.

valueOf

public static FastString valueOf(java.lang.CharSequence chars)

Returns the FastString representing the specified character sequence.

Parameters:

chars - the CharSequence source.

Returns:

the corresponding real-time string.

valueOf

public static FastString valueOf(boolean b)

Returns the FastString representing the boolean argument.

Parameters:

b - a boolean.

Returns:

if the argument is true, a string equal to "true" is returned; otherwise, a string equal to "false" is returned.

See Also:

TypeFormat.parseBoolean(java.lang.CharSequence)

valueOf

public static FastString valueOf(char c)

Returns the FastString representing the char argument.

Parameters:

c - a char.

Returns:

a string of length 1 containing as its single character the argument c.

valueOf

public static FastString valueOf(int i)

Returns the FastString representing the specified int argument (decimal representation).

Parameters:

i - the int number.

Returns:

the decimal representation of the int argument.

See Also:

TypeFormat.parseInt(java.lang.CharSequence)

valueOf

public static FastString valueOf(long l)

Returns the FastString representing the specified long argument (decimal representation).

Parameters:

l - the long number.

Returns:

the decimal representation of the long argument.

See Also:

TypeFormat.parseLong(java.lang.CharSequence)

valueOf

public static FastString valueOf(double d)

Returns the FastString representing the specified double argument. The error is assumed to be the intrinsic double error (64 bits IEEE 754 format).

Parameters:

d - the double number.

Returns:

valueOf(d, 0)

See Also:

TypeFormat.parseDouble(java.lang.CharSequence)

length

public int length()

Returns the length of this FastString.

Specified by:

length in interface java.lang.CharSequence

Returns:

the number of characters (16-bits Unicode) composing this real-time string.

charAt

public char charAt(int index)

Returns the character at the specified index.

Specified by:

charAt in interface java.lang.CharSequence

Parameters:

index - the index of the character starting at 0.

Returns:

the character at the specified index of this real-time string.

Throws:

java.lang.IndexOutOfBoundsException - if the index is not in the [0, length() - 1] range.

substring

public FastString substring(int start)

Returns a sub-string of this FastString.

Note: For performance reason, the sub-string being returned references this FastString character array. If this FastString is short-lived and the sub-string is long-lived, it is recommended to perform a copy of the sub-string to avoid that small sub-strings takes up a lot of memory space which cannot be garbage collected.

Parameters:

start - the index of the first character inclusive.

Returns:

the substring starting at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - if the start index is not in the [0, length()] range.

substring

public FastString substring(int start,
                            int end)

Returns a sub-string of this FastString.

Note: For performance reason, the sub-string being returned references this FastString character array. If this FastString is short-lived and the sub-string is long-lived, it is recommended to perform a copy of the sub-string to avoid that small sub-strings takes up a lot of memory space which cannot be garbage collected.

Parameters:

start - the index of the first character inclusive.

end - the index of the last character exclusive.

Returns:

the substring starting at the specified start position and ending just before the specified end position.

Throws:

java.lang.IndexOutOfBoundsException - if the start index is not in the [0, length()] range.

java.lang.IndexOutOfBoundsException - if the end index is not in the [start, length()] range.

subSequence

public java.lang.CharSequence subSequence(int start,
                                          int end)

Returns a new character sequence that is a subsequence of this sequence. Equivalent to substring(int, int)

Specified by:

subSequence in interface java.lang.CharSequence

Parameters:

start - the index of the first character inclusive.

end - the index of the last character exclusive.

Returns:

the character sequence starting at the specified start position and ending just before the specified end position.

Throws:

java.lang.IndexOutOfBoundsException - if the start index is not in the [0, length()] range.

java.lang.IndexOutOfBoundsException - if the end index is not in the [start, length()] range.

getChars

public void getChars(int start,
                     int end,
                     char[] dest,
                     int destPos)

Copies the characters from this FastString into the destination character array.

Parameters:

start - the index of the first character in the string to copy.

end - the index after the last character in the string to copy.

dest - the destination array.

destPos - the start offset in the destination array.

Throws:

java.lang.StringIndexOutOfBoundsException - if the start index is not in the [0, length()] range.

java.lang.StringIndexOutOfBoundsException - if the end index is not in the [start, length()] range.

indexOf

public int indexOf(java.lang.CharSequence chars)

Returns the index within this FastString of the first occurrence of the specified character sequence searching forward.

Parameters:

chars - a character sequence.

Returns:

the index of the first character of the character sequence found; or -1 if the character sequence is not found.

indexOf

public int indexOf(java.lang.CharSequence chars,
                   int fromIndex)

Returns the index within this FastString of the first occurrence of the specified character sequence searching forward from the specified index.

Parameters:

chars - a character sequence.

fromIndex - the index to start the search from.

Returns:

the index in the range [fromIndex, length()-chars.length()] or -1 if the character sequence is not found.

lastIndexOf

public int lastIndexOf(java.lang.CharSequence chars)

Returns the index within this FastString of the last occurrence of the specified character sequence searching backward.

Parameters:

chars - a character sequence.

Returns:

the index of the first character of the character sequence found; or -1 if the character sequence is not found.

lastIndexOf

public int lastIndexOf(java.lang.CharSequence chars,
                       int fromIndex)

Returns the index within this FastString of the last occurrence of the specified character sequence searching backward from the specified index.

Parameters:

chars - a character sequence.

fromIndex - the index to start the backward search from.

Returns:

the index in the range [0, fromIndex] or -1 if the character sequence is not found.

startsWith

public boolean startsWith(java.lang.CharSequence prefix)

Indicates if this FastString starts with the specified prefix.

Parameters:

prefix - the prefix.

Returns:

true if the character sequence represented by the argument is a prefix of the character sequence represented by this string; false otherwise.

endsWith

public boolean endsWith(java.lang.CharSequence suffix)

Indicates if this FastString ends with the specified suffix.

Parameters:

suffix - the suffix.

Returns:

true if the character sequence represented by the argument is a suffix of the character sequence represented by this string; false otherwise.

startsWith

public boolean startsWith(java.lang.CharSequence prefix,
                          int index)

Indicates if this FastString starts with the specified prefix at the specified index.

Parameters:

prefix - the prefix.

index - the index of the prefix location in this string.

Returns:

this.substring(index).startsWith(prefix)

concat

public FastString concat(java.lang.CharSequence chars)

Concatenates the specified character sequence to the end of this FastString.

Parameters:

chars - the character sequence that is concatenated.

Returns:

a real-time string that represents the concatenation of this string's characters followed by the specified sequence of character.

replace

public FastString replace(char oldChar,
                          char newChar)

Returns a FastString where all occurrences of oldChar have been replaced with newChar.

Parameters:

oldChar - the old character.

newChar - the new character.

Returns:

this FastString if it does not contain any occurence of the specifed oldChar or a string derived from this string by replacing every occurrence of oldChar with newChar.

trim

public FastString trim()

Returns a copy of this FastString, with leading and trailing whitespace omitted.

Returns:

a copy of this string with leading and trailing white space removed, or this string if it has no leading or trailing white space.

toString

public java.lang.String toString()

Returns the text representation of this FastString. The String returned is always allocated on the heap and can safely be referenced elsewhere.

Specified by:

toString in interface java.lang.CharSequence

Returns:

the java.lang.String for this FastString.

equals

public boolean equals(java.lang.Object that)

Compares this FastString against the specified object.

Note: Unfortunately, due to the current (JDK 1.4.1) implementation of java.lang.String and java.lang.StringBuffer, this method is not symmetric.

Parameters:

that - the object to compare with.

Returns:

true if both objects are CharSequence and they represent the same sequence; false otherwise.

equalsIgnoreCase

public boolean equalsIgnoreCase(java.lang.CharSequence chars)

Compares this FastString to the specified character sequence ignoring case considerations. The two character sequence are considered equal ignoring case if they are of the same length, and corresponding characters in the two strings are equal ignoring case.

Parameters:

chars - the CharSequence to compare this FastString against.

Returns:

true if the argument is not null and the character sequences are equal, ignoring case; false otherwise.

See Also:

equals(Object)

hashCode

public int hashCode()

Returns the hash code for this real-time string.

Note: Returns the same hashCode as java.lang.String (consistent with equals(java.lang.Object))

Returns:

the hash code value.

compareTo

public int compareTo(java.lang.Object that)

Compares this FastString to another object. If the object is a CharSequence this function behaves like compareTo(CharSequence). Otherwise, it throws a ClassCastException.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

that - the object to be compared.

Returns:

compareTo((CharSequence) that)

Throws:

java.lang.ClassCastException - if the specifed object is not a CharSequence.

compareTo

public int compareTo(java.lang.CharSequence chars)

Compares this FastString with the specified character sequence lexicographically.

Parameters:

chars - the character sequence to be compared with.

Returns:

the value 0 if the argument character sequence is equal to this string; a value less than 0 if this string is lexicographically less than the character sequence argument; and a value greater than 0 if this string is lexicographically greater than the character sequence argument.

Throws:

java.lang.ClassCastException - if the specifed object is not a CharSequence.

export

public java.lang.Object export()

Description copied from interface: Realtime

Exports this object out of the current pool context. Realtime members are exported as well (recursion). This method affects only objects belonging to the current pool context. To avoid pool depletion, a "free" object from the outer pool is moved to replace the object being exported.

Specified by:

export in interface Realtime

Overrides:

export in class RealtimeObject

toHeap

public java.lang.Object toHeap()

Description copied from interface: Realtime

Moves this object to the heap. Realtime members are moved to the heap as well (recursion). This method affects only objects belonging to a pool context (current or not).

Specified by:

toHeap in interface Realtime

Overrides:

toHeap in class RealtimeObject