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:
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 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.
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 be accessing 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).
- Version:
- 1.0.3
- Author:
- Wes Biggs
-
REG_ANCHORINDEX
- Execution flag.
-
REG_DOT_NEWLINE
- Compilation flag.
-
REG_ICASE
- Compilation flag.
-
REG_MULTILINE
- Compilation flag.
-
REG_NOTBOL
- Execution flag.
-
REG_NOTEOL
- Execution flag.
-
RE(Object)
- Constructs a regular expression pattern buffer without any compilation
flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).
-
RE(Object, int)
- Constructs a regular expression pattern buffer using the specified
compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).
-
RE(Object, int, RESyntax)
- Constructs a regular expression pattern buffer using the specified
compilation flags and regular expression syntax.
-
getAllMatches(Object)
- Returns an array of all matches found in the input.
-
getAllMatches(Object, int)
- Returns an array of all matches found in the input,
beginning at the specified index position.
-
getAllMatches(Object, int, int)
- Returns an array of all matches found in the input string,
beginning at the specified index position and using the specified
execution flags.
-
getMatch(Object)
- Returns the first match found in the input.
-
getMatch(Object, int)
- Returns the first match found in the input, beginning
the search at the specified index.
-
getMatch(Object, int, int)
- Returns the first match found in the input, beginning
the search at the specified index, and using the specified
execution flags.
-
getMatch(Object, int, int, StringBuffer)
- Returns the first match found in the input, beginning
the search at the specified index, and using the specified
execution flags.
-
getMatchEnumeration(Object)
- Returns an REMatchEnumeration that can be used to iterate over the
matches found in the input text.
-
getMatchEnumeration(Object, int)
- Returns an REMatchEnumeration that can be used to iterate over the
matches found in the input text.
-
getMatchEnumeration(Object, int, int)
- Returns an REMatchEnumeration that can be used to iterate over the
matches found in the input text.
-
getNumSubs()
- Returns the maximum number of subexpressions in this regular expression.
-
isMatch(Object)
- Checks if the input in its entirety is an exact match of
this regular expression.
-
isMatch(Object, int)
- Checks if the input string, starting from index, is an exact match of
this regular expression.
-
isMatch(Object, int, int)
- Checks if the input, starting from index and using the specified
execution flags, is an exact match of this regular expression.
-
substitute(Object, String)
- Substitutes the replacement text for the first match found in the input.
-
substitute(Object, String, int)
- Substitutes the replacement text for the first match found in the input
beginning at the specified index position.
-
substitute(Object, String, int, int)
- 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, String)
- Substitutes the replacement text for each non-overlapping match found
in the input text.
-
substituteAll(Object, String, int)
- Substitutes the replacement text for each non-overlapping match found
in the input text, starting at the specified index.
-
substituteAll(Object, String, int, int)
- 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.
-
version()
- Returns a string representing the version of the gnu.regexp package.
REG_ICASE
public static final int REG_ICASE
- Compilation flag. Do not differentiate case. Subsequent
searches using this RE will be case insensitive.
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.
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.
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 = "food"
// m1 = "fool"
// m2 = null
// m3 = null
// m4 = "fool"
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.
REG_ANCHORINDEX
public static final int REG_ANCHORINDEX
- Execution flag.
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.
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
or character array.
- Throws: REException
- The input pattern could not be parsed.
- Throws: IllegalArgumentException
- The pattern was not a String, StringBuffer or char[].
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
or character array.
- cflags - The logical OR of any combination of the compilation flags listed above.
- Throws: REException
- The input pattern could not be parsed.
- Throws: IllegalArgumentException
- The pattern was not a String or char[].
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
or character array.
- 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.
- Throws: IllegalArgumentException
- The pattern was not a String or char[].
version
public static final String version()
- Returns a string representing the version of the gnu.regexp package.
isMatch
public boolean isMatch(Object input)
- Checks if the input in its entirety is an exact match of
this regular expression.
- Parameters:
- input - The input text.
- Throws: IllegalArgumentException
- The input text was not a String, char[], or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
getAllMatches
public REMatch[] getAllMatches(Object input)
- Returns an array of all matches found in the input.
- Parameters:
- input - The input text.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
getAllMatches
public REMatch[] getAllMatches(Object input,
int index)
- Returns an array of all matches found in the input,
beginning at the specified index position.
- Parameters:
- input - The input text.
- index - The offset index at which the search should be begin.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- 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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
getMatch
public REMatch getMatch(Object input)
- Returns the first match found in the input.
- Parameters:
- input - The input text.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
getMatch
public REMatch getMatch(Object input,
int index)
- Returns the first match found in the input, beginning
the search at the specified index.
- Parameters:
- input - The input text.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
getMatch
public REMatch 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. 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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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).
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- 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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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).
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- 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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
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.
- Throws: IllegalArgumentException
- The input text was not a String, char[], StringBuffer or InputStream.
toString
public String toString()
- Return a human readable form of the compiled regular expression,
useful for debugging.
- Overrides:
- toString in class Object
All Packages Class Hierarchy This Package Previous Next Index