All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.roguewave.tools.v2-0.RegExp

java.lang.Object
   |
   +----com.roguewave.tools.v2-0.RegExp

public class RegExp
extends Object
implements RegExpConstants, Cloneable, Serializable

Class RegExp represents a regular expression. The constructor "compiles" the expression into a form that can be used more efficiently. The results can then be used for string searches.

The regular expression (RE) is constructed as follows:

First, the rules for one-character REs that match a single character:

Any character that is not a special character (to be defined) matches itself.
A backslash (\) followed by any special character matches the literal character itself. I.e., this "escapes" the special character.
The "special characters" are:
```
+	*	?	.	[	]	^	$
```
The period (.) matches any character except the newline. E.g., ".umpty" matches either "Humpty" or "Dumpty".
A set of characters enclosed in brackets ([]) is a one- character RE that matches any of the characters in that set. E.g., "[akm]" matches either an "a", "k", or "m". A range of characters can be indicated with a dash. E.g., "[a-z]" matches any lower-case letter. However, if the first character of the set is the caret (^), then the RE matches any character except those in the set. It does not match the empty string. Example: [^akm] matches any character except "a", "k", or "m". The caret loses its special meaning if it is not the first character of the set.

Next, here are the rules for building a multicharacter RE:

A one-character RE followed by an asterisk (*) matches zero or more occurences of the RE. Hence, [a-z]* matches zero or more lower-case characters.
A one-character RE followed by a plus (+) matches one or more occurrences of the RE. Hence, [a-z]+ matches one or more lower- case characters.
A question mark (?) is an optional element. The preceeding RE can occur zero or once in the string -- no more. E.g. xy?z matches either xyz or xz.
The concatenation of REs is an RE that matches the corresponding concatenation of strings. E.g., [A-Z][a-z]* matches any capitalized word.

Finally, the entire regular expression can be anchored to match only the beginning or end of a line:

If the caret (^) is at the beginning of the RE, then the matched string must be at the beginning of a line.
If the dollar sign ($) is at the end of the RE, then the matched string must be at the end of the line.

The following escape codes can be used to match control characters:

 	\b		backspace
 	\f		formfeed
 	\n		newline
 	\r		carriage return
 	\s		space
 	\t		tab 
 	\e		ESC (escape)
 	\ddd		the literal oct number 0ddd
 	\xddd		the literal hex number 0xddd
 	\^C		Control code.  E.g.  \^D is "control-D"

ILLEGAL: Status representing an invalid regular expression
OK: Status representing a valid regular expression
TOOLONG: Status representing a regular expression whose compiled representation is too long for the buffer allocated to hold it.

RegExp(String): Creates a regular expression from the given string.
RegExp(StringBuffer): Creates a regular expression from the given string.

clone(): Creates a regular expression equal to self.
find(String): Finds a match for this RE within a given String.
find(String, int): Finds a match for this RE within a given String beginning at a given index.
find(StringBuffer): Finds a match for this RE within a given StringBuffer.
find(StringBuffer, int): Finds a match for this RE within a given StringBuffer beginning at a given index.
index(String): Gets the position and length of the portion of a given String that matches this RE.
index(String, int): Gets the position and length of the portion of a given String, beginning at a given index, that matches this RE.
index(StringBuffer): Gets the position and length of the portion of a given StringBuffer that matches this RE.
index(StringBuffer, int): Gets the position and length of the portion of a given StringBuffer, beginning at a given index, that matches this RE.
indexBegin(String): Does the same work as index, but returns only the index of the beginning of the matched pattern.
indexBegin(String, int): Does the same work as index, but returns only the index of the beginning of the matched pattern.
indexBegin(StringBuffer): Does the same work as index, but returns only the index of the beginning of the matched pattern.
indexBegin(StringBuffer, int): Does the same work as index, but returns only the index of the beginning of the matched pattern.
indexLength(String): Does the same work as index, but returns only the length of the matched pattern.
indexLength(String, int): Does the same work as index, but returns only the length of the matched pattern.
indexLength(StringBuffer): Does the same work as index, but returns only the length of the matched pattern.
indexLength(StringBuffer, int): Does the same work as index, but returns only the length of the matched pattern.
replace(String, int, String): Creates a new string by replacing that portion of a given target string that matches self with a given replacement string.
replace(StringBuffer, int, String): Replaces that portion of a given StringBuffer that matches self with a given replacement string.
status(): Returns the status of the regular expression.
toString(): Returns a String containing the source text for the regular expression

 public static final int OK

Status representing a valid regular expression

ILLEGAL

 public static final int ILLEGAL

Status representing an invalid regular expression

TOOLONG

 public static final int TOOLONG

Status representing a regular expression whose compiled representation is too long for the buffer allocated to hold it.

RegExp

 public RegExp(String str)

Creates a regular expression from the given string. The status of the regular expression after construction should be checked via the status() member function.

Parameters:: str - The string containing the regular expression text

RegExp

 public RegExp(StringBuffer str)

Creates a regular expression from the given string. The status of the regular expression after construction should be checked via the status() member function.

Parameters:: str - The StringBuffer containing the regular expression text

clone

 public Object clone()

Creates a regular expression equal to self.

Overrides:: clone in class Object

status

 public int status()

Returns the status of the regular expression.

Returns:: RegExp.OK if the pattern is good, or one of RegExp.ILLEGAL or RegExp.TOOLONG if the pattern is bad

toString

 public String toString()

Returns a String containing the source text for the regular expression

Returns:: The source text of the regular expression.
Overrides:: toString in class Object

replace

 public String replace(String target,
                       int start,
                       String replStr)

Creates a new string by replacing that portion of a given target string that matches self with a given replacement string. The function builds a new String by replacing the first instance of this regular expression found in target with replStr. Search begins at index start.

Note the different return type and behavior from the replace function that takes a StringBuffer as the target.

Parameters:: target - Base string, which will have that portion which matches this RE replaced by replStr; start - Index into target where search should begin; replStr - String to replace matched portion of target
Returns:: The new string created by replacing the matched substring or null if no match was found
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

replace

 public boolean replace(StringBuffer target,
                        int start,
                        String replStr)

Replaces that portion of a given StringBuffer that matches self with a given replacement string. The function replaces the first instance of this regular expression found in target with replStr. Search begins at index start.

If a match is found, the target StringBuffer itself is modified. Note the different return type and behavior from the replace function which takes a String.

Parameters:: target - StringBuffer in which the portion that matches this RE will be replaced by replStr; start - Index into target where search should begin; replStr - String to replace matched portion of target
Returns:: true if pattern is found and replacement is made, false otherwise
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

find

 public String find(String target,
                    int start)

Finds a match for this RE within a given String beginning at a given index. Searches target beginning at index start for the first instance matching self, and returns the matching substring or null if none is found.

Parameters:: target - The string to search; start - Index into target where search is to begin
Returns:: The matching substring or null if none is found
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

find

 public String find(String target)

Finds a match for this RE within a given String. Searches target for the first instance matching self, and returns the matching substring or null if none is found.

Parameters:: target - The string to search
Returns:: The matching substring or null if none is found
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

find

 public String find(StringBuffer target,
                    int start)

Finds a match for this RE within a given StringBuffer beginning at a given index. Searches target beginning at index start for a substring matching self and returns the matching substring or null is none is found.

Parameters:: target - The string to search; start - Index into target where search is to begin
Returns:: The matching substring or null if none is found
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

find

 public String find(StringBuffer target)

Finds a match for this RE within a given StringBuffer. Searches target for a substring matching self and returns the matching substring or null is none is found.

Parameters:: target - The string to search
Returns:: The matching substring or null if none is found
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

index

 public int[] index(String str,
                    int start)

Gets the position and length of the portion of a given String, beginning at a given index, that matches this RE. Searches the string str for an instance of the regular expression. Search begins at index start.

Parameters:: str - The string to search; start - The index into str where the search begins
Returns:: int array of length 2. First element is the index of the matched substring, second element is the length. Both are -1 if no match is found.
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

index

 public int[] index(String str)

Gets the position and length of the portion of a given String that matches this RE. Searches the string str for an instance of the regular expression.

Parameters:: str - The string to search
Returns:: int array of length 2. First element is the index of the matched substring, second element is the length. Both are -1 if no match is found.
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

index

 public int[] index(StringBuffer str,
                    int start)

Gets the position and length of the portion of a given StringBuffer, beginning at a given index, that matches this RE. Searches the string str for an instance of the regular expression. Search begins at index start.

Parameters:: str - The string to search; start - The index into str where the search starts
Returns:: int array of length 2. First element is the index of the matched substring, second element is the length. Both are -1 if no match is found.
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

index

 public int[] index(StringBuffer str)

Gets the position and length of the portion of a given StringBuffer that matches this RE. Searches the string str for an instance of the regular expression.

Parameters:: str - The string to search
Returns:: int array of length 2. First element is the index of the matched substring, second element is the length. Both are -1 if no match is found.
Throws: BadRegularExpressionException: Thrown if the status of the regular expression is other than RegExp.OK

indexBegin

 public int indexBegin(String str,
                       int start)

Does the same work as index, but returns only the index of the beginning of the matched pattern.

Parameters:: str - String to be searched for matching pattern; start - Index into str where search begins
Returns:: Returns the index of the matched substring

indexBegin

 public int indexBegin(String str)

Does the same work as index, but returns only the index of the beginning of the matched pattern.

Parameters:: str - String to be searched for matching pattern
Returns:: Returns the index of the matched substring

indexLength

 public int indexLength(String str,
                        int start)

Does the same work as index, but returns only the length of the matched pattern.

Parameters:: str - String to be searched for matching pattern; start - Index into str where search begins
Returns:: Returns the length of the matched substring

indexLength

 public int indexLength(String str)

Does the same work as index, but returns only the length of the matched pattern.

Parameters:: str - String to be searched for matching pattern
Returns:: Returns the length of the matched substring

indexBegin

 public int indexBegin(StringBuffer str,
                       int start)

Does the same work as index, but returns only the index of the beginning of the matched pattern.

Parameters:: str - String to be searched for matching pattern; start - Index into str where search begins
Returns:: Returns the index of the matched substring

indexBegin

 public int indexBegin(StringBuffer str)

Does the same work as index, but returns only the index of the beginning of the matched pattern.

Parameters:: str - String to be searched for matching pattern
Returns:: Returns the index of the matched substring

indexLength

 public int indexLength(StringBuffer str,
                        int start)

Does the same work as index, but returns only the length of the matched pattern.

Parameters:: str - String to be searched for matching pattern; start - Index into str where search begins
Returns:: Returns the length of the matched substring

indexLength

 public int indexLength(StringBuffer str)

Does the same work as index, but returns only the length of the matched pattern.

Parameters:: str - String to be searched for matching pattern
Returns:: Returns the length of the matched substring

All Packages  Class Hierarchy  This Package  Previous  Next  Index