javolution37.javolution.lang

Class Text

java.lang.Object

javolution37.javolution.realtime.RealtimeObject

javolution37.javolution.lang.Text

All Implemented Interfaces:

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

public abstract class Text
extends RealtimeObject
implements java.lang.CharSequence, java.lang.Comparable, java.io.Serializable, Immutable

This class represents an immutable character sequence with extremely fast concatenation, insertion and deletion capabilities (O[Log(n)]) instead of O[n] for StringBuffer/StringBuilder).

Instances of this class have the following advantages over String:

• No need for an intermediate StringBuffer in order to manipulate textual documents. Text methods are much faster (especially for large documents).
• Bug free. They are not plagued by the String.substring(int) memory leak bug (when small substrings prevent memory from larger string from being garbage collected).
• More flexible as they allows for search and comparison with any java.lang.String or CharSequence.
• Easy formatting using the TextBuilder class (no need to specify the buffer capacity as it gently increases without incurring expensive resize/copy operations).
• Real-time compliant (instances allocated on the "stack" when executing in a PoolContext).

As for any CharSequence, parsing of primitive types can be achieved using the TypeFormat utility class.

Text literals should be explicitely interned. Unlike strings literals and strings-value constant expressions, interning is not implicit. For example:

         final static Text TRUE = Text.intern("true");
         final static Text FALSE = Text.intern("false");
     

Interned texts are always allocated in ImmortalMemory (RTSJ VMs).

Implementation Note: To avoid expensive copy operations , Text instances are broken down into smaller immutable sequences (they form a minimal-depth binary tree). Internal copies are then performed in O[Log(n)] instead of O[n]).

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javolution37.javolution.realtime.RealtimeObject

RealtimeObject.Factory<T extends RealtimeObject>

Nested classes/interfaces inherited from interface javolution37.javolution.realtime.Realtime

Realtime.ObjectSpace

Field Summary

Fields

Modifier and Type	Field and Description
static Text	EMPTY Holds an empty character sequence.
static Text	NULL Holds the "null" character sequence.

Method Summary

Modifier and Type	Method and Description
abstract char	charAt(int index) Returns the character at the specified index.
int	compareTo(java.lang.Object csq) Compares this text to another character sequence or string lexicographically.
Text	concat(Text that) Concatenates the specified text to the end of this text.
boolean	contentEquals(java.lang.CharSequence csq) Indicates if this text has the same character content as the specified character sequence.
boolean	contentEqualsIgnoreCase(java.lang.CharSequence csq) Indicates if this text has the same character contend as the specified character sequence ignoring case considerations.
Text	copy() Returns a compact copy of this text allocated on the stack when executing in a PoolContext.
Text	delete(int start, int end) Returns the text without the characters between the specified indexes.
abstract int	depth() Returns the depth of the internal tree used to represent this text.
boolean	endsWith(java.lang.CharSequence suffix) Indicates if this text ends with the specified suffix.
boolean	equals(java.lang.Object obj) Compares this text against the specified object for equality.
abstract void	getChars(int start, int end, char[] dest, int destPos) Copies the characters from this text into the destination character array.
int	hashCode() Returns the hash code for this text.
abstract int	indexOf(char c, int fromIndex) Returns the index within this text of the first occurrence of the specified character, starting the search at the specified index.
int	indexOf(java.lang.CharSequence csq) Returns the index within this text of the first occurrence of the specified character sequence searching forward.
int	indexOf(java.lang.CharSequence csq, int fromIndex) Returns the index within this text of the first occurrence of the specified characters sequence searching forward from the specified index.
int	indexOfAny(CharSet charSet) Returns the index within this text of the first occurrence of any character in the specified character set.
int	indexOfAny(CharSet charSet, int start) Returns the index within a region of this text of the first occurrence of any character in the specified character set.
int	indexOfAny(CharSet charSet, int start, int length) Returns the index within a region of this text of the first occurrence of any character in the specified character set.
Text	insert(int index, Text txt) Returns the text having the specified text inserted at the specified location.
static Text	intern(java.lang.CharSequence csq) Returns a text equals to the specified character sequence from a pool of unique text instances in ImmortalMemory.
static Text	intern(java.lang.String str) Returns a text equals to the specified string from a pool of unique text instances in ImmortalMemory.
boolean	isBlank() Indicates if all characters of this text are whitespaces (no characters greater than the space character).
boolean	isBlank(int start, int length) Indicates if the specified sub-range of characters of this text are whitespaces (no characters greater than the space character).
abstract int	lastIndexOf(char c, int fromIndex) Returns the index within this text of the first occurrence of the specified character, searching backward and starting at the specified index.
int	lastIndexOf(java.lang.CharSequence csq) Returns the index within this text of the last occurrence of the specified characters sequence searching backward.
int	lastIndexOf(java.lang.CharSequence csq, int fromIndex) Returns the index within this text of the last occurrence of the specified character sequence searching backward from the specified index.
int	lastIndexOfAny(CharSet charSet) Returns the index within this text of the last occurrence of any character in the specified character set.
int	lastIndexOfAny(CharSet charSet, int start) Returns the index within a region of this text of the last occurrence of any character in the specified character set.
int	lastIndexOfAny(CharSet charSet, int start, int length) Returns the index within a region of this text of the last occurrence of any character in the specified character set.
int	length() Returns the length of this text.
Text	padLeft(int len) Pads this text on the left with spaces to make the minimum total length as specified.
Text	padLeft(int len, char c) Pads this text on the left to make the minimum total length as specified.
Text	padRight(int len) Pads this text on the right with spaces to make the minimum total length as specified.
Text	padRight(int len, char c) Pads this text on the right to make the minimum total length as specified.
Text	plus(java.lang.Object obj) Returns the concatenation of this text and the textual representation of the specified object.
Text	replace(Text target, Text replacement) Replaces each character sequence of this text that matches the specified target sequence with the specified replacement sequence.
boolean	startsWith(java.lang.CharSequence prefix) Indicates if this text starts with the specified prefix.
boolean	startsWith(java.lang.CharSequence prefix, int index) Indicates if this text starts with the specified prefix at the specified index.
abstract java.lang.String	stringValue() Returns the String value corresponding to this text.
java.lang.CharSequence	subSequence(int start, int end) Returns subtext(start, end).
Text	subtext(int start) Returns a portion of this text.
abstract Text	subtext(int start, int end) Returns a portion of this text.
abstract Text	toLowerCase() Converts the characters of this text to lower case.
Text	toText() Returns this (implements Realtime interface).
abstract Text	toUpperCase() Converts the characters of this text to upper case.
Text	trim() Returns a copy of this text, with leading and trailing whitespace omitted.
Text	trimEnd() Returns a copy of this text, with trailing whitespace omitted.
Text	trimStart() Returns a copy of this text, with leading whitespace omitted.
static Text	valueOf(boolean b) Returns the text representation of the boolean argument.
static Text	valueOf(char c) Returns the unique text instance corresponding to the specified character.
static Text	valueOf(char[] chars) Returns the text that contains the characters from the specified array.
static Text	valueOf(char[] chars, int offset, int length) Returns the text that contains the characters from the specified subarray of characters.
static Text	valueOf(char c, int length) Returns the text that contains a specific length sequence of the character specified.
static Text	valueOf(java.lang.CharSequence csq, int start, int end) Returns the text that contains the specified subsequence of characters.
static Text	valueOf(double d) Returns the textual representation of the specified double argument.
static Text	valueOf(double value, int digits, boolean scientific, boolean showZero) Returns the textual representation of the specified double value according to the specified formatting arguments.
static Text	valueOf(float f) Returns the textual representation of the specified float instance.
static Text	valueOf(int i) Returns the decimal representation of the specified int argument.
static Text	valueOf(int i, int radix) Returns the radix representation of the specified int argument.
static Text	valueOf(long l) Returns the decimal representation of the specified long argument.
static Text	valueOf(long l, int radix) Returns the radix representation of the specified long argument.
static Text	valueOf(java.lang.Object obj) Returns the text representing the specified object.

Methods inherited from class javolution37.javolution.realtime.RealtimeObject

export, move, moveHeap, preserve, toString, unpreserve

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints, toString

Field Detail

EMPTY

public static final Text EMPTY

Holds an empty character sequence.

NULL

public static final Text NULL

Holds the "null" character sequence.

Method Detail

valueOf

public static Text valueOf(java.lang.Object obj)

Returns the text representing the specified object. If the specified object is null this method returns NULL.

Parameters:

obj - the object to represent as text.

Returns:

the textual representation of the specified object.

See Also:

Realtime.toText()

valueOf

public static Text valueOf(java.lang.CharSequence csq,
                           int start,
                           int end)

Returns the text that contains the specified subsequence of characters.

Parameters:

csq - the character sequence source.

start - the index of the first character.

end - the index after the last character.

Returns:

the corresponding text instance.

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > csq.length())

valueOf

public static Text valueOf(char[] chars)

Returns the text that contains the characters from the specified array.

Parameters:

chars - the array source of the characters.

Returns:

the corresponding instance.

valueOf

public static Text valueOf(char[] chars,
                           int offset,
                           int length)

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

Parameters:

chars - the source of the characters.

offset - the index of the first character in the data soure.

length - the length of the text returned.

Returns:

the corresponding instance.

Throws:

java.lang.IndexOutOfBoundsException - if (offset < 0) || (length < 0) || ((offset + length) > chars.length)

valueOf

public static Text valueOf(boolean b)

Returns the text representation of the boolean argument.

Parameters:

b - a boolean.

Returns:

if the argument is true, the text "true" is returned; otherwise, the text "false" is returned.

valueOf

public static Text valueOf(char c)

Returns the unique text instance corresponding to the specified character.

Parameters:

c - a character.

Returns:

a text of length 1 containing 'c'.

valueOf

public static Text valueOf(int i)

Returns the decimal representation of the specified int argument.

Parameters:

i - the int to format.

Returns:

the corresponding text instance.

valueOf

public static Text valueOf(int i,
                           int radix)

Returns the radix representation of the specified int argument.

Parameters:

i - the int to format.

radix - the radix (e.g. 16 for hexadecimal).

Returns:

the corresponding text instance.

valueOf

public static Text valueOf(long l)

Returns the decimal representation of the specified long argument.

Parameters:

l - the long to format.

Returns:

the corresponding text instance.

valueOf

public static Text valueOf(long l,
                           int radix)

Returns the radix representation of the specified long argument.

Parameters:

l - the long to format.

radix - the radix (e.g. 16 for hexadecimal).

Returns:

the corresponding text instance.

valueOf

public static Text valueOf(float f)

Returns the textual representation of the specified float instance.

Parameters:

f - the float to format.

Returns:

the corresponding text instance. /

valueOf

public static Text valueOf(double d)

Returns the textual representation of the specified double argument.

Parameters:

d - the double to format.

Returns:

the corresponding text instance. /

valueOf

public static Text valueOf(double value,
                           int digits,
                           boolean scientific,
                           boolean showZero)

Returns the textual representation of the specified double value according to the specified formatting arguments.

Parameters:

value - the double value.

digits - the number of significative digits (excludes exponent).

scientific - true to forces the use of the scientific notation (e.g. 1.23E3); false otherwise.

showZero - true if trailing fractional zeros are represented; false otherwise.

Returns:

the corresponding text instance.

Throws:

java.lang.IllegalArgumentException - if ((digits > 19) || (digits <= 0))) /

length

public final int length()

Returns the length of this text.

Specified by:

length in interface java.lang.CharSequence

Returns:

the number of characters (16-bits Unicode) composing this text.

plus

public final Text plus(java.lang.Object obj)

Returns the concatenation of this text and the textual representation of the specified object.

Parameters:

obj - the object whose textual representation is appended.

Returns:

this.concat(Text.valueOf(obj))

concat

public final Text concat(Text that)

Concatenates the specified text to the end of this text. This method is extremely fast (faster even than StringBuffer.append(String)) and still returns a text instance with an internal binary tree of minimal depth!

Parameters:

that - the text that is concatenated.

Returns:

this + that

subtext

public final Text subtext(int start)

Returns a portion of this text.

Parameters:

start - the index of the first character inclusive.

Returns:

the sub-text starting at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (start > this.length())

insert

public final Text insert(int index,
                         Text txt)

Returns the text having the specified text inserted at the specified location.

Parameters:

index - the insertion position.

txt - the text being inserted.

Returns:

subtext(0, index).concat(txt).concat(subtext(index))

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index > this.length())

delete

public final Text delete(int start,
                         int end)

Returns the text without the characters between the specified indexes.

Parameters:

start - the beginning index, inclusive.

end - the ending index, exclusive.

Returns:

subtext(0, start).concat(subtext(end))

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length()

replace

public final Text replace(Text target,
                          Text replacement)

Replaces each character sequence of this text that matches the specified target sequence with the specified replacement sequence.

Parameters:

target - the text to be replaced.

replacement - the replacement text.

Returns:

the resulting text.

subSequence

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

Returns subtext(start, end).

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:

this.subtext(start, end)

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length())

indexOf

public final int indexOf(java.lang.CharSequence csq)

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

Parameters:

csq - 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 final int indexOf(java.lang.CharSequence csq,
                         int fromIndex)

Returns the index within this text of the first occurrence of the specified characters sequence searching forward from the specified index.

Parameters:

csq - a character sequence.

fromIndex - the index to start the search from.

Returns:

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

lastIndexOf

public final int lastIndexOf(java.lang.CharSequence csq)

Returns the index within this text of the last occurrence of the specified characters sequence searching backward.

Parameters:

csq - 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 final int lastIndexOf(java.lang.CharSequence csq,
                             int fromIndex)

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

Parameters:

csq - 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 final boolean startsWith(java.lang.CharSequence prefix)

Indicates if this text 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 text; false otherwise.

endsWith

public final boolean endsWith(java.lang.CharSequence suffix)

Indicates if this text 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 text; false otherwise.

startsWith

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

Indicates if this text 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)

trim

public final Text trim()

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

Returns:

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

intern

public static Text intern(java.lang.CharSequence csq)

Returns a text equals to the specified character sequence from a pool of unique text instances in ImmortalMemory.

Returns:

an unique text instance allocated in ImmortalMemory.

intern

public static Text intern(java.lang.String str)

Returns a text equals to the specified string from a pool of unique text instances in ImmortalMemory.

Returns:

an unique text instance allocated in ImmortalMemory.

contentEquals

public final boolean contentEquals(java.lang.CharSequence csq)

Indicates if this text has the same character content as the specified character sequence.

Parameters:

csq - the character sequence to compare with.

Returns:

true if the specified character sequence has the same character content as this text; false otherwise.

contentEqualsIgnoreCase

public final boolean contentEqualsIgnoreCase(java.lang.CharSequence csq)

Indicates if this text has the same character contend as the specified character sequence ignoring case considerations.

Parameters:

csq - the CharSequence to compare this text against.

Returns:

true if the argument and this text are equal, ignoring case; false otherwise.

equals

public final boolean equals(java.lang.Object obj)

Compares this text against the specified object for equality. Returns true if the specified object is a text having the same character sequence as this text. For generic comparaison with any character sequence the contentEquals(CharSequence) should be used.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with or null.

Returns:

true if that is a text with the same character sequence as this text; false otherwise.

hashCode

public final int hashCode()

Returns the hash code for this text.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value.

compareTo

public final int compareTo(java.lang.Object csq)

Compares this text to another character sequence or string lexicographically.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

csq - the character sequence to be compared.

Returns:

TypeFormat.LEXICAL_COMPARATOR.compare(this, csq)

Throws:

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

toText

public final Text toText()

Returns this (implements Realtime interface).

Specified by:

toText in interface Realtime

Overrides:

toText in class RealtimeObject

Returns:

this

copy

public final Text copy()

Returns a compact copy of this text allocated on the stack when executing in a PoolContext.

Returns:

a local compact copy of this text.

depth

public abstract int depth()

Returns the depth of the internal tree used to represent this text.

Returns:

the maximum depth of the text internal binary tree.

charAt

public abstract 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.

Returns:

the character at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= this.length())

indexOf

public abstract int indexOf(char c,
                            int fromIndex)

Returns the index within this text of the first occurrence of the specified character, starting the search at the specified index.

Parameters:

c - the character to search for.

fromIndex - the index to start the search from.

Returns:

the index of the first occurrence of the character in this text that is greater than or equal to fromIndex, or -1 if the character does not occur.

lastIndexOf

public abstract int lastIndexOf(char c,
                                int fromIndex)

Returns the index within this text of the first occurrence of the specified character, searching backward and starting at the specified index.

Parameters:

c - the character to search for.

fromIndex - the index to start the search backward from.

Returns:

the index of the first occurrence of the character in this text that is less than or equal to fromIndex, or -1 if the character does not occur.

subtext

public abstract Text subtext(int start,
                             int end)

Returns a portion of this text.

Parameters:

start - the index of the first character inclusive.

end - the index of the last character exclusive.

Returns:

the sub-text starting at the specified start position and ending just before the specified end position.

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length())

getChars

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

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

Parameters:

start - the index of the first character to copy.

end - the index after the last character to copy.

dest - the destination array.

destPos - the start offset in the destination array.

Throws:

java.lang.IndexOutOfBoundsException - if (start < 0) || (end < 0) || (start > end) || (end > this.length())

toLowerCase

public abstract Text toLowerCase()

Converts the characters of this text to lower case.

Returns:

the text in lower case.

See Also:

Character.toLowerCase(char)

toUpperCase

public abstract Text toUpperCase()

Converts the characters of this text to upper case.

Returns:

the text in lower case.

See Also:

Character.toUpperCase(char)

stringValue

public abstract java.lang.String stringValue()

Returns the String value corresponding to this text.

Returns:

the java.lang.String for this text.

valueOf

public static Text valueOf(char c,
                           int length)

Returns the text that contains a specific length sequence of the character specified.

Parameters:

c - the character to fill this text with.

length - the length of the text returned.

Returns:

the corresponding instance.

Throws:

java.lang.IndexOutOfBoundsException - if (length < 0)

isBlank

public final boolean isBlank()

Indicates if all characters of this text are whitespaces (no characters greater than the space character).

Returns:

true if this text contains only whitespace.

isBlank

public final boolean isBlank(int start,
                             int length)

Indicates if the specified sub-range of characters of this text are whitespaces (no characters greater than the space character).

Parameters:

start - the start index.

length - the number of characters to inspect.

trimStart

public final Text trimStart()

Returns a copy of this text, with leading whitespace omitted.

Returns:

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

trimEnd

public final Text trimEnd()

Returns a copy of this text, with trailing whitespace omitted.

Returns:

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

padLeft

public final Text padLeft(int len)

Pads this text on the left with spaces to make the minimum total length as specified. The new length of the new text is equal to the original length plus (length()-len) spaces.

Parameters:

len - the total number of characters to make this text equal to.

Returns:

a new text or the same text if no padding required.

Throws:

an - IllegalArgumentException if the (len<0).

padLeft

public final Text padLeft(int len,
                          char c)

Pads this text on the left to make the minimum total length as specified. Spaces or the given Unicode character are used to pad with.
The new length of the new text is equal to the original length plus (length()-len) pad characters.

Parameters:

len - the total number of characters to make this text equal to.

c - the character to pad using.

Returns:

a new text or the same text if no padding required.

Throws:

an - IllegalArgumentException if the (len<0).

padRight

public final Text padRight(int len)

Pads this text on the right with spaces to make the minimum total length as specified. The new length of the new text is equal to the original length plus (length()-len) spaces.

Parameters:

len - the total number of characters to make this text equal to.

Returns:

a new text or the same text if no padding required.

Throws:

an - IllegalArgumentException if the (len<0).

padRight

public final Text padRight(int len,
                           char c)

Pads this text on the right to make the minimum total length as specified. Spaces or the given Unicode character are used to pad with.
The new length of the new text is equal to the original length plus (length()-len) pad characters.

Parameters:

len - the total number of characters to make this text equal to.

c - the character to pad using.

Returns:

a new text or the same text if no padding required.

Throws:

an - IllegalArgumentException if the (len<0).

indexOfAny

public final int indexOfAny(CharSet charSet)

Returns the index within this text of the first occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

Returns:

the index of the first character that matches one of the characters in the supplied set; or -1 if none.

indexOfAny

public final int indexOfAny(CharSet charSet,
                            int start)

Returns the index within a region of this text of the first occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

start - the index of the start of the search region in this text.

Returns:

the index of the first character that matches one of the characters in the supplied set; or -1 if none.

indexOfAny

public final int indexOfAny(CharSet charSet,
                            int start,
                            int length)

Returns the index within a region of this text of the first occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

start - the index of the start of the search region in this text.

length - the length of the region to search.

Returns:

the index of the first character that matches one of the characters in the supplied array; or -1 if none.

lastIndexOfAny

public final int lastIndexOfAny(CharSet charSet)

Returns the index within this text of the last occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

Returns:

the index of the last character that matches one of the characters in the supplied array; or -1 if none.

lastIndexOfAny

public final int lastIndexOfAny(CharSet charSet,
                                int start)

Returns the index within a region of this text of the last occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

start - the index of the start of the search region in this text.

Returns:

the index of the last character that matches one of the characters in the supplied array; or -1 if none.

lastIndexOfAny

public final int lastIndexOfAny(CharSet charSet,
                                int start,
                                int length)

Returns the index within a region of this text of the last occurrence of any character in the specified character set.

Parameters:

charSet - the character set.

start - the index of the start of the search region in this text.

length - the length of the region to search.

Returns:

the index of the last character that matches one of the characters in the supplied array; or -1 if none.