Class RE
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
UncheckedRE
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).
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 String, a character array, a StringBuffer, a Reader or an InputStream of some sort. Note that when using a Reader or 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.
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 a Reader or InputStream, this means an offset from the current read position, so subsequent calls with the same index argument on a Reader or 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.
- Version:
- 1.1.4-dev, to be released
- Author:
- Wes Biggs
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Execution flag.static final int
Compilation flag.static final int
Compilation flag.static final int
Compilation flag.static final int
Execution flag.static final int
Execution flag.static final int
Execution flag. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
RE()
Constructs a regular expression pattern buffer without any compilation flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).Constructs a regular expression pattern buffer using the specified compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).Constructs a regular expression pattern buffer using the specified compilation flags and regular expression syntax. -
Method Summary
Modifier and TypeMethodDescription(package private) boolean
(package private) void
dump
(StringBuffer os) 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.(package private) static final String
Returns the first match found in the input.Returns the first match found in the input, beginning the search at the specified index.Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.getMatch
(Object input, int index, int eflags, StringBuffer buffer) Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.getMatchEnumeration
(Object input) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.getMatchEnumeration
(Object input, int index) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.getMatchEnumeration
(Object input, int index, int eflags) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.(package private) REMatch
getMatchImpl
(CharIndexed input, int anchor, int eflags, StringBuffer buffer) int
Returns the minimum number of characters that could possibly constitute a match of this regular expression.int
Returns the maximum number of subexpressions in this regular expression.protected void
initialize
(Object patternObj, int cflags, RESyntax syntax, int myIndex, int nextSub) boolean
Checks if the regular expression matches the input in its entirety.boolean
Checks if the input string, starting from index, is an exact match of this regular expression.boolean
Checks if the input, starting from index and using the specified execution flags, is an exact match of this regular expression.(package private) boolean
match
(CharIndexed input, REMatch mymatch) Returns true if the match succeeded, false if it failed.(package private) void
substitute
(Object input, String replace) Substitutes the replacement text for the first match found in the input.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.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.substituteAll
(Object input, String replace) Substitutes the replacement text for each non-overlapping match found in the input text.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.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.toString()
Return a human readable form of the compiled regular expression, useful for debugging.static final String
version()
Returns a string representing the version of the gnu.regexp package.
-
Field Details
-
REG_ICASE
public static final int REG_ICASECompilation flag. Do not differentiate case. Subsequent searches using this RE will be case insensitive.- See Also:
-
REG_DOT_NEWLINE
public static final int REG_DOT_NEWLINECompilation 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.- See Also:
-
REG_MULTILINE
public static final int REG_MULTILINECompilation 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.- See Also:
-
REG_NOTBOL
public static final int REG_NOTBOLExecution 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 = "food"
// m1 = "fool"
// m2 = null
// m3 = null
// m4 = "fool"
- See Also:
-
REG_NOTEOL
public static final int REG_NOTEOLExecution flag. The match-end operator ($) does not match at the end of the input string. Useful for matching on substrings.- See Also:
-
REG_ANCHORINDEX
public static final int REG_ANCHORINDEXExecution 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.- See Also:
-
REG_NO_INTERPOLATE
public static final int REG_NO_INTERPOLATEExecution 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".- See Also:
-
-
Constructor Details
-
RE
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
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
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.
-
RE
protected RE()
-
-
Method Details
-
version
Returns a string representing the version of the gnu.regexp package. -
getLocalizedMessage
-
initialize
protected void initialize(Object patternObj, int cflags, RESyntax syntax, int myIndex, int nextSub) throws REException - Throws:
REException
-
isMatch
Checks if the regular expression matches the input in its entirety.- Parameters:
input
- The input text.
-
isMatch
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
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.
-
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. -
setUncle
-
chain
-
getMinimumLength
public int getMinimumLength()Returns the minimum number of characters that could possibly constitute a match of this regular expression.- Overrides:
getMinimumLength
in classREToken
-
getAllMatches
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
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
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
-
match
Description copied from class:REToken
Returns true if the match succeeded, false if it failed. -
getMatch
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
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
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
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.
-
getMatchImpl
-
getMatchEnumeration
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
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
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.
-
substitute
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:
-
substitute
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:
-
substitute
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:
-
substituteAll
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:
-
substituteAll
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:
-
substituteAll
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:
-
toString
Return a human readable form of the compiled regular expression, useful for debugging. -
dump
-