gnu.java.util.regex

Class RE

java.lang.Object
- gnu.java.util.regex.REToken
- - gnu.java.util.regex.RE

Implemented Interfaces:: Cloneable, Serializable

Known Direct Subclasses:: UncheckedRE

public class RE

extends gnu.java.util.regex.REToken

RE provides the user interface for compiling and matching regular expressions.

A regular expression object (class RE) is compiled by constructing it from a String, StringBuffer or character array, with optional compilation flags (below) and an optional syntax specification (see RESyntax; if not specified, RESyntax.RE_SYNTAX_PERL5 is used).

Once compiled, a regular expression object is reusable as well as threadsafe: multiple threads can use the RE instance simultaneously to match against different input text.

Various methods attempt to match input text against a compiled regular expression. These methods are:

isMatch: returns true if the input text in its entirety matches the regular expression pattern.

getMatch: returns the first match found in the input text, or null if no match is found.

getAllMatches: returns an array of all non-overlapping matches found in the input text. If no matches are found, the array is zero-length.

substitute: substitute the first occurence of the pattern in the input text with a replacement string (which may include metacharacters $0-$9, see REMatch.substituteInto).

substituteAll: same as above, but repeat for each match before returning.

getMatchEnumeration: returns an REMatchEnumeration object that allows iteration over the matches (see REMatchEnumeration for some reasons why you may want to do this instead of using getAllMatches.

These methods all have similar argument lists. The input can be a CharIndexed, String, a character array, a StringBuffer, or an InputStream of some sort. Note that when using an InputStream, the stream read position cannot be guaranteed after attempting a match (this is not a bug, but a consequence of the way regular expressions work). Using an REMatchEnumeration can eliminate most positioning problems. Although the input object can be of various types, it is recommended that it should be a CharIndexed because CharIndexed.getLastMatch() can show the last match found on this input, which helps the expression \G work as the end of the previous match.

The optional index argument specifies the offset from the beginning of the text at which the search should start (see the descriptions of some of the execution flags for how this can affect positional pattern operators). For an InputStream, this means an offset from the current read position, so subsequent calls with the same index argument on an InputStream will not necessarily access the same position on the stream, whereas repeated searches at a given index in a fixed string will return consistent results.

You can optionally affect the execution environment by using a combination of execution flags (constants listed below).

All operations on a regular expression are performed in a thread-safe manner.

See Also:: Serialized Form

Field Summary
`static int`	`REG_ANCHORINDEX` Execution flag.
`static int`	`REG_DOT_NEWLINE` Compilation flag.
`static int`	`REG_FIX_STARTING_POSITION` Execution flag.
`static int`	`REG_ICASE` Compilation flag.
`static int`	`REG_ICASE_USASCII` Compilation flag.
`static int`	`REG_MULTILINE` Compilation flag.
`static int`	`REG_NOTBOL` Execution flag.
`static int`	`REG_NOTEOL` Execution flag.
`static int`	`REG_NO_INTERPOLATE` Execution flag.
`static int`	`REG_REPLACE_USE_BACKSLASHESCAPE` Execution flag.
`static int`	`REG_TRY_ENTIRE_MATCH` Execution flag.
`static int`	`REG_X_COMMENTS` Compilation flag.

Fields inherited from class gnu.java.util.regex.REToken
`next`, `subIndex`, `uncle`, `unicodeAware`

Constructor Summary
`RE()` The basic constructor.
`RE(Object pattern)` Constructs a regular expression pattern buffer without any compilation flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).
`RE(Object pattern, int cflags)` Constructs a regular expression pattern buffer using the specified compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).
`RE(Object pattern, int cflags, RESyntax syntax)` Constructs a regular expression pattern buffer using the specified compilation flags and regular expression syntax.

Method Summary
`REMatch[]`	`getAllMatches(Object input)` Returns an array of all matches found in the input.
`REMatch[]`	`getAllMatches(Object input, int index)` Returns an array of all matches found in the input, beginning at the specified index position.
`REMatch[]`	`getAllMatches(Object input, int index, int eflags)` Returns an array of all matches found in the input string, beginning at the specified index position and using the specified execution flags.
`REMatch`	`getMatch(Object input)` Returns the first match found in the input.
`REMatch`	`getMatch(Object input, int index)` Returns the first match found in the input, beginning the search at the specified index.
`REMatch`	`getMatch(Object input, int index, int eflags)` Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.
`REMatch`	`getMatch(Object input, int index, int eflags, CPStringBuilder buffer)` Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.
`REMatchEnumeration`	`getMatchEnumeration(Object input)` Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
`REMatchEnumeration`	`getMatchEnumeration(Object input, int index)` Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
`REMatchEnumeration`	`getMatchEnumeration(Object input, int index, int eflags)` Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
`int`	`getMaximumLength()`
`int`	`getMinimumLength()` Returns the minimum number of characters that could possibly constitute a match of this regular expression.
`int`	`getNumSubs()` Returns the maximum number of subexpressions in this regular expression.
`static String`	`getReplacement(String replace, REMatch m, int eflags)`
`protected void`	`initialize(Object patternObj, int cflags, RESyntax syntax, int myIndex, int nextSub)`
`boolean`	`isMatch(Object input)` Checks if the regular expression matches the input in its entirety.
`boolean`	`isMatch(Object input, int index)` Checks if the input string, starting from index, is an exact match of this regular expression.
`boolean`	`isMatch(Object input, int index, int eflags)` Checks if the input, starting from index and using the specified execution flags, is an exact match of this regular expression.
`static CharIndexed`	`makeCharIndexed(Object input, int index)`
`String`	`substitute(Object input, String replace)` Substitutes the replacement text for the first match found in the input.
`String`	`substitute(Object input, String replace, int index)` Substitutes the replacement text for the first match found in the input beginning at the specified index position.
`String`	`substitute(Object input, String replace, int index, int eflags)` Substitutes the replacement text for the first match found in the input string, beginning at the specified index position and using the specified execution flags.
`String`	`substituteAll(Object input, String replace)` Substitutes the replacement text for each non-overlapping match found in the input text.
`String`	`substituteAll(Object input, String replace, int index)` Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index.
`String`	`substituteAll(Object input, String replace, int index, int eflags)` Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index and using the specified execution flags.
`String`	`toString()` Return a human readable form of the compiled regular expression, useful for debugging.
`static String`	`version()` Returns a string representing the version of the gnu.regexp package.

Methods inherited from class gnu.java.util.regex.REToken
`clone`, `next`, `toLowerCase`, `toString`, `toUpperCase`

Methods inherited from class java.lang.Object
`clone`, `equals`, `extends Object> getClass`, `finalize`, `hashCode`, `notify`, `notifyAll`, `toString`, `wait`, `wait`, `wait`

REG_ANCHORINDEX

public static final int REG_ANCHORINDEX

Execution flag. When a match method is invoked that starts matching at a non-zero index into the input, treat the input as if it begins at the index given. The effect of this flag is that the engine does not "see" any text in the input before the given index. This is useful so that the match-beginning operator (^) matches not at position 0 in the input string, but at the position the search started at (based on the index input given to the getMatch function). See the example under REG_NOTBOL. It also affects the use of the \< and \b operators.
Field Value:
64

REG_DOT_NEWLINE

public static final int REG_DOT_NEWLINE

Compilation flag. The match-any-character operator (dot) will match a newline character. When set this overrides the syntax bit RE_DOT_NEWLINE (see RESyntax for details). This is equivalent to the "/s" operator in Perl.
Field Value:
4

REG_FIX_STARTING_POSITION

public static final int REG_FIX_STARTING_POSITION

Execution flag. Do not move the position at which the search begins. If not set, the starting position will be moved until a match is found.
Field Value:
4096

REG_ICASE

public static final int REG_ICASE

Compilation flag. Do not differentiate case. Subsequent searches using this RE will be case insensitive.
Field Value:
2

REG_ICASE_USASCII

public static final int REG_ICASE_USASCII

Compilation flag. If set, REG_ICASE is effective only for US-ASCII.
Field Value:
2048

REG_MULTILINE

public static final int REG_MULTILINE

Compilation flag. Use multiline mode. In this mode, the ^ and $ anchors will match based on newlines within the input. This is equivalent to the "/m" operator in Perl.
Field Value:
8

REG_NOTBOL

public static final int REG_NOTBOL

Execution flag. The match-beginning operator (^) will not match at the beginning of the input string. Useful for matching on a substring when you know the context of the input is such that position zero of the input to the match test is not actually position zero of the text.
This example demonstrates the results of various ways of matching on a substring.
String s = "food bar fool"; RE exp = new RE("^foo."); REMatch m0 = exp.getMatch(s); REMatch m1 = exp.getMatch(s.substring(8)); REMatch m2 = exp.getMatch(s.substring(8),0,RE.REG_NOTBOL); REMatch m3 = exp.getMatch(s,8); REMatch m4 = exp.getMatch(s,8,RE.REG_ANCHORINDEX);
// Results: // m0.toString(): "food" // m1.toString(): "fool" // m2.toString(): null // m3.toString(): null // m4.toString(): "fool"
Field Value:
16

REG_NOTEOL

public static final int REG_NOTEOL

Execution flag. The match-end operator ($) does not match at the end of the input string. Useful for matching on substrings.
Field Value:
32

REG_NO_INTERPOLATE

public static final int REG_NO_INTERPOLATE

Execution flag. The substitute and substituteAll methods will not attempt to interpolate occurrences of $1-$9 in the replacement text with the corresponding subexpressions. For example, you may want to replace all matches of "one dollar" with "$1".
Field Value:
128

REG_REPLACE_USE_BACKSLASHESCAPE

public static final int REG_REPLACE_USE_BACKSLASHESCAPE

Execution flag. The substitute and substituteAll methods will treat the character '\' in the replacement as an escape to a literal character. In this case "\n", "\$", "\\", "\x40" and "\012" will become "n", "$", "\", "x40" and "012" respectively. This flag has no effect if REG_NO_INTERPOLATE is set on.
Field Value:
512

REG_TRY_ENTIRE_MATCH

public static final int REG_TRY_ENTIRE_MATCH

Execution flag. Try to match the whole input string. An implicit match-end operator is added to this regexp.
Field Value:
256

REG_X_COMMENTS

public static final int REG_X_COMMENTS

Compilation flag. Allow whitespace and comments in pattern. This is equivalent to the "/x" operator in Perl.
Field Value:
1024

RE

protected RE()

The basic constructor. Object is special, because it has no superclass, so there is no call to super().

RE

public RE(Object pattern)
            throws REException

Constructs a regular expression pattern buffer without any compilation flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).
Parameters:
pattern - A regular expression pattern, in the form of a String, StringBuffer or char[]. Other input types will be converted to strings using the toString() method.
Throws:
REException - The input pattern could not be parsed.
NullPointerException - The pattern was null.

RE

public RE(Object pattern,
          int cflags)
            throws REException

Constructs a regular expression pattern buffer using the specified compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).
Parameters:
pattern - A regular expression pattern, in the form of a String, StringBuffer, or char[]. Other input types will be converted to strings using the toString() method.
cflags - The logical OR of any combination of the compilation flags listed above.
Throws:
REException - The input pattern could not be parsed.
NullPointerException - The pattern was null.

RE

public RE(Object pattern,
          int cflags,
          RESyntax syntax)
            throws REException

Constructs a regular expression pattern buffer using the specified compilation flags and regular expression syntax.
Parameters:
pattern - A regular expression pattern, in the form of a String, StringBuffer, or char[]. Other input types will be converted to strings using the toString() method.
cflags - The logical OR of any combination of the compilation flags listed above.
syntax - The type of regular expression syntax to use.
Throws:
REException - The input pattern could not be parsed.
NullPointerException - The pattern was null.

getAllMatches

public REMatch[] getAllMatches(Object input)

Returns an array of all matches found in the input. If the regular expression allows the empty string to match, it will substitute matches at all positions except the end of the input.
Parameters:
input - The input text.
Returns:
a non-null (but possibly zero-length) array of matches

getAllMatches

public REMatch[] getAllMatches(Object input,
                               int index)

Returns an array of all matches found in the input, beginning at the specified index position. If the regular expression allows the empty string to match, it will substitute matches at all positions except the end of the input.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
Returns:
a non-null (but possibly zero-length) array of matches

getAllMatches

public REMatch[] getAllMatches(Object input,
                               int index,
                               int eflags)

Returns an array of all matches found in the input string, beginning at the specified index position and using the specified execution flags. If the regular expression allows the empty string to match, it will substitute matches at all positions except the end of the input.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
Returns:
a non-null (but possibly zero-length) array of matches

getMatch

public REMatch getMatch(Object input)

Returns the first match found in the input. If no match is found, null is returned.
Parameters:
input - The input text.
Returns:
An REMatch instance referencing the match, or null if none.

getMatch

public REMatch getMatch(Object input,
                        int index)

Returns the first match found in the input, beginning the search at the specified index. If no match is found, returns null.
Parameters:
input - The input text.
index - The offset within the text to begin looking for a match.
Returns:
An REMatch instance referencing the match, or null if none.

getMatch

public REMatch getMatch(Object input,
                        int index,
                        int eflags)

Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags. If no match is found, returns null.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
Returns:
An REMatch instance referencing the match, or null if none.

getMatch

public REMatch getMatch(Object input,
                        int index,
                        int eflags,
                        CPStringBuilder buffer)

Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags. If no match is found, returns null. If a StringBuffer is provided and is non-null, the contents of the input text from the index to the beginning of the match (or to the end of the input, if there is no match) are appended to the StringBuffer.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
buffer - The StringBuffer to save pre-match text in.
Returns:
An REMatch instance referencing the match, or null if none.

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
Parameters:
input - The input text.
Returns:
A non-null REMatchEnumeration instance.

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input,
                                              int index)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
Returns:
A non-null REMatchEnumeration instance, with its input cursor set to the index position specified.

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input,
                                              int index,
                                              int eflags)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
Returns:
A non-null REMatchEnumeration instance, with its input cursor set to the index position specified.

getMaximumLength

public int getMaximumLength()

getMinimumLength

public int getMinimumLength()

Returns the minimum number of characters that could possibly constitute a match of this regular expression.

getNumSubs

public int getNumSubs()

Returns the maximum number of subexpressions in this regular expression. If the expression contains branches, the value returned will be the maximum subexpressions in any of the branches.

getReplacement

public static String getReplacement(String replace,
                                    REMatch m,
                                    int eflags)

initialize

protected void initialize(Object patternObj,
                          int cflags,
                          RESyntax syntax,
                          int myIndex,
                          int nextSub)
            throws REException

isMatch

public boolean isMatch(Object input)

Checks if the regular expression matches the input in its entirety.
Parameters:
input - The input text.

isMatch

public boolean isMatch(Object input,
                       int index)

Checks if the input string, starting from index, is an exact match of this regular expression.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.

isMatch

public boolean isMatch(Object input,
                       int index,
                       int eflags)

Checks if the input, starting from index and using the specified execution flags, is an exact match of this regular expression.
Parameters:
input - The input text.
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.

makeCharIndexed

public static CharIndexed makeCharIndexed(Object input,
                                          int index)

substitute

public String substitute(Object input,
                         String replace)

Substitutes the replacement text for the first match found in the input.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
Returns:
A String interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

substitute

public String substitute(Object input,
                         String replace,
                         int index)

Substitutes the replacement text for the first match found in the input beginning at the specified index position. Specifying an index effectively causes the regular expression engine to throw away the specified number of characters.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
index - The offset index at which the search should be begin.
Returns:
A String containing the substring of the input, starting at the index position, and interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

substitute

public String substitute(Object input,
                         String replace,
                         int index,
                         int eflags)

Substitutes the replacement text for the first match found in the input string, beginning at the specified index position and using the specified execution flags.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
Returns:
A String containing the substring of the input, starting at the index position, and interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

substituteAll

public String substituteAll(Object input,
                            String replace)

Substitutes the replacement text for each non-overlapping match found in the input text.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
Returns:
A String interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

substituteAll

public String substituteAll(Object input,
                            String replace,
                            int index)

Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index. If the regular expression allows the empty string to match, it will substitute matches at all positions except the end of the input.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
index - The offset index at which the search should be begin.
Returns:
A String containing the substring of the input, starting at the index position, and interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

substituteAll

public String substituteAll(Object input,
                            String replace,
                            int index,
                            int eflags)

Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index and using the specified execution flags.
Parameters:
input - The input text.
replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).
index - The offset index at which the search should be begin.
eflags - The logical OR of any execution flags above.
Returns:
A String containing the substring of the input, starting at the index position, and interpolating the substituted text.
See Also:
REMatch.substituteInto(String)

toString

public String toString()

Return a human readable form of the compiled regular expression, useful for debugging.
Overrides:
toString in interface gnu.java.util.regex.REToken

version

public static final String version()

Returns a string representing the version of the gnu.regexp package.

gnu/regexp/RE.java Copyright (C) 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About
Prev Class \| Next Class		Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr

gnu.java.util.regex

Class RE

Field Summary

Fields inherited from class gnu.java.util.regex.REToken

Constructor Summary

Method Summary

Methods inherited from class gnu.java.util.regex.REToken

Methods inherited from class java.lang.Object

Field Details

REG_ANCHORINDEX

REG_DOT_NEWLINE

REG_FIX_STARTING_POSITION

REG_ICASE

REG_ICASE_USASCII

REG_MULTILINE

REG_NOTBOL

REG_NOTEOL

REG_NO_INTERPOLATE

REG_REPLACE_USE_BACKSLASHESCAPE

REG_TRY_ENTIRE_MATCH

REG_X_COMMENTS

Constructor Details

RE

RE

RE

RE

Method Details

getAllMatches

getAllMatches

getAllMatches

getMatch

getMatch

getMatch

getMatch

getMatchEnumeration

getMatchEnumeration

getMatchEnumeration

getMaximumLength

getMinimumLength

getNumSubs

getReplacement

initialize

isMatch

isMatch

isMatch

makeCharIndexed

substitute

substitute

substitute

substituteAll

substituteAll

substituteAll

toString

version