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 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).
All operations on a regular expression are performed in a thread-safe manner. @author Wes Biggs @version 1.1.3, 18 June 2001
| |