org.apache.regexp

## Class RE

- java.lang.Object
- - org.apache.regexp.RE

- All Implemented Interfaces:
    java.io.Serializable

      public class RE
      extends java.lang.Object
      implements java.io.Serializable

  RE is an efficient, lightweight regular expression evaluator/matcher class. Regular expressions are pattern descriptions which enable sophisticated matching of strings. In addition to being able to match a string against a pattern, you can also extract parts of the match. This is especially useful in text parsing! Details on the syntax of regular expression patterns are given below.

  To compile a regular expression (RE), you can simply construct an RE matcher object from the string specification of the pattern, like this:

        RE r = new RE("a*b");

  Once you have done this, you can call either of the RE.match methods to perform matching on a String. For example:

        boolean matched = r.match("aaaab");

  will cause the boolean matched to be set to true because the pattern "a*b" matches the string "aaaab".

  If you were interested in the number of a's which matched the first part of our example expression, you could change the expression to "(a*)b". Then when you compiled the expression and matched it against something like "xaaaab", you would get results like this:

        RE r = new RE("(a*)b");                  // Compile expression
        boolean matched = r.match("xaaaab");     // Match against "xaaaab"

        String wholeExpr = r.getParen(0);        // wholeExpr will be 'aaaab'
        String insideParens = r.getParen(1);     // insideParens will be 'aaaa'

        int startWholeExpr = r.getParenStart(0); // startWholeExpr will be index 1
        int endWholeExpr = r.getParenEnd(0);     // endWholeExpr will be index 6
        int lenWholeExpr = r.getParenLength(0);  // lenWholeExpr will be 5

        int startInside = r.getParenStart(1);    // startInside will be index 1
        int endInside = r.getParenEnd(1);        // endInside will be index 5
        int lenInside = r.getParenLength(1);     // lenInside will be 4

  You can also refer to the contents of a parenthesized expression within a regular expression itself. This is called a 'backreference'. The first backreference in a regular expression is denoted by \1, the second by \2 and so on. So the expression:

        ([0-9]+)=\1

  will match any string of the form n=n (like 0=0 or 2=2).

  The full regular expression syntax accepted by RE is described here:

        Characters

          unicodeChar   Matches any identical unicode character
          \                    Used to quote a meta-character (like '*')
          \\                   Matches a single '\' character
          \0nnn                Matches a given octal character
          \xhh                 Matches a given 8-bit hexadecimal character
          \\uhhhh              Matches a given 16-bit hexadecimal character
          \t                   Matches an ASCII tab character
          \n                   Matches an ASCII newline character
          \r                   Matches an ASCII return character
          \f                   Matches an ASCII form feed character

        Character Classes

          [abc]                Simple character class
          [a-zA-Z]             Character class with ranges
          [^abc]               Negated character class

  NOTE: Incomplete ranges will be interpreted as "starts from zero" or "ends with last character".
  I.e. [-a] is the same as [\\u0000-a], and [a-] is the same as [a-\\uFFFF], [-] means "all characters".

        Standard POSIX Character Classes

          [:alnum:]            Alphanumeric characters.
          [:alpha:]            Alphabetic characters.
          [:blank:]            Space and tab characters.
          [:cntrl:]            Control characters.
          [:digit:]            Numeric characters.
          [:graph:]            Characters that are printable and are also visible.
                               (A space is printable, but not visible, while an
                               `a' is both.)
          [:lower:]            Lower-case alphabetic characters.
          [:print:]            Printable characters (characters that are not
                               control characters.)
          [:punct:]            Punctuation characters (characters that are not letter,
                               digits, control characters, or space characters).
          [:space:]            Space characters (such as space, tab, and formfeed,
                               to name a few).
          [:upper:]            Upper-case alphabetic characters.
          [:xdigit:]           Characters that are hexadecimal digits.

        Non-standard POSIX-style Character Classes

          [:javastart:]        Start of a Java identifier
          [:javapart:]         Part of a Java identifier

        Predefined Classes

          .         Matches any character other than newline
          \w        Matches a "word" character (alphanumeric plus "_")
          \W        Matches a non-word character
          \s        Matches a whitespace character
          \S        Matches a non-whitespace character
          \d        Matches a digit character
          \D        Matches a non-digit character

        Boundary Matchers

          ^         Matches only at the beginning of a line
          $         Matches only at the end of a line
          \b        Matches only at a word boundary
          \B        Matches only at a non-word boundary

        Greedy Closures

          A*        Matches A 0 or more times (greedy)
          A+        Matches A 1 or more times (greedy)
          A?        Matches A 1 or 0 times (greedy)
          A{n}      Matches A exactly n times (greedy)
          A{n,}     Matches A at least n times (greedy)
          A{n,m}    Matches A at least n but not more than m times (greedy)

        Reluctant Closures

          A*?       Matches A 0 or more times (reluctant)
          A+?       Matches A 1 or more times (reluctant)
          A??       Matches A 0 or 1 times (reluctant)

        Logical Operators

          AB        Matches A followed by B
          A|B       Matches either A or B
          (A)       Used for subexpression grouping
         (?:A)      Used for subexpression clustering (just like grouping but
                    no backrefs)

        Backreferences

          \1    Backreference to 1st parenthesized subexpression
          \2    Backreference to 2nd parenthesized subexpression
          \3    Backreference to 3rd parenthesized subexpression
          \4    Backreference to 4th parenthesized subexpression
          \5    Backreference to 5th parenthesized subexpression
          \6    Backreference to 6th parenthesized subexpression
          \7    Backreference to 7th parenthesized subexpression
          \8    Backreference to 8th parenthesized subexpression
          \9    Backreference to 9th parenthesized subexpression

  All closure operators (+, *, ?, {m,n}) are greedy by default, meaning that they match as many elements of the string as possible without causing the overall match to fail. If you want a closure to be reluctant (non-greedy), you can simply follow it with a '?'. A reluctant closure will match as few elements of the string as possible when finding matches. {m,n} closures don't currently support reluctancy.

  Line terminators
  A line terminator is a one- or two-character sequence that marks the end of a line of the input character sequence. The following are recognized as line terminators:

  - A newline (line feed) character ('\n'),
  - A carriage-return character followed immediately by a newline character ("\r\n"),
  - A standalone carriage-return character ('\r'),
  - A next-line character ('?'),
  - A line-separator character ('?'), or
  - A paragraph-separator character ('?).

  RE runs programs compiled by the RECompiler class. But the RE matcher class does not include the actual regular expression compiler for reasons of efficiency. In fact, if you want to pre-compile one or more regular expressions, the 'recompile' class can be invoked from the command line to produce compiled output like this:

          // Pre-compiled regular expression "a*b"
          char[] re1Instructions =
          {
              0x007c, 0x0000, 0x001a, 0x007c, 0x0000, 0x000d, 0x0041,
              0x0001, 0x0004, 0x0061, 0x007c, 0x0000, 0x0003, 0x0047,
              0x0000, 0xfff6, 0x007c, 0x0000, 0x0003, 0x004e, 0x0000,
              0x0003, 0x0041, 0x0001, 0x0004, 0x0062, 0x0045, 0x0000,
              0x0000,
          };

          REProgram re1 = new REProgram(re1Instructions);

  You can then construct a regular expression matcher (RE) object from the pre-compiled expression re1 and thus avoid the overhead of compiling the expression at runtime. If you require more dynamic regular expressions, you can construct a single RECompiler object and re-use it to compile each expression. Similarly, you can change the program run by a given matcher object at any time. However, RE and RECompiler are not threadsafe (for efficiency reasons, and because requiring thread safety in this class is deemed to be a rare requirement), so you will need to construct a separate compiler or matcher object for each thread (unless you do thread synchronization yourself). Once expression compiled into the REProgram object, REProgram can be safely shared across multiple threads and RE objects.

  ISSUES:

  - com.weusours.util.re is not currently compatible with all standard POSIX regcomp flags
  - com.weusours.util.re does not support POSIX equivalence classes ([=foo=] syntax) (I18N/locale issue)
  - com.weusours.util.re does not support nested POSIX character classes (definitely should, but not completely trivial)
  - com.weusours.util.re Does not support POSIX character collation concepts ([.foo.] syntax) (I18N/locale issue)
  - Should there be different matching styles (simple, POSIX, Perl etc?)
  - Should RE support character iterators (for backwards RE matching!)?
  - Should RE support reluctant {m,n} closures (does anyone care)?
  - Not *all* possibilities are considered for greediness when backreferences are involved (as POSIX suggests should be the case). The POSIX RE "(ac*)c*d[ac]*\1", when matched against "acdacaa" should yield a match of acdacaa where \1 is "a". This is not the case in this RE package, and actually Perl doesn't go to this extent either! Until someone actually complains about this, I'm not sure it's worth "fixing". If it ever is fixed, test #137 in RETest.txt should be updated.
  Version:
    $Id: RE.java 518156 2007-03-14 14:31:26Z vgritsenko $
  Author:
    Jonathan Locke, Tobias Schäfer
  See Also:
    `recompile`, `RECompiler`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static char` | `E_ALNUM`
    `(package private) static char` | `E_BOUND`
    `(package private) static char` | `E_DIGIT`
    `(package private) static char` | `E_NALNUM`
    `(package private) static char` | `E_NBOUND`
    `(package private) static char` | `E_NDIGIT`
    `(package private) static char` | `E_NSPACE`
    `(package private) static char` | `E_SPACE`
    `(package private) int` | `end0`
    `(package private) int` | `end1`
    `(package private) int` | `end2`
    `(package private) int[]` | `endBackref`
    `(package private) int[]` | `endn`
    `static int` | `MATCH_CASEINDEPENDENT` Flag to indicate that matching should be case-independent (folded)
    `static int` | `MATCH_MULTILINE` Newlines should match as BOL/EOL (^ and $)
    `static int` | `MATCH_NORMAL` Specifies normal, case-sensitive matching behaviour.
    `static int` | `MATCH_SINGLELINE` Consider all input a single body of text - newlines are matched by .
    `(package private) int` | `matchFlags`
    `(package private) static int` | `MAX_PAREN`
    `(package private) static int` | `maxNode`
    `(package private) int` | `maxParen`
    `(package private) static int` | `nodeSize`
    `(package private) static int` | `offsetNext`
    `(package private) static int` | `offsetOpcode`
    `(package private) static int` | `offsetOpdata`
    `(package private) static char` | `OP_ANY`
    `(package private) static char` | `OP_ANYOF`
    `(package private) static char` | `OP_ATOM`
    `(package private) static char` | `OP_BACKREF`
    `(package private) static char` | `OP_BOL`
    `(package private) static char` | `OP_BRANCH`
    `(package private) static char` | `OP_CLOSE`
    `(package private) static char` | `OP_CLOSE_CLUSTER`
    `(package private) static char` | `OP_CONTINUE`
    `(package private) static char` | `OP_END` * The format of a node in a program is: * * [ OPCODE ] [ OPDATA ] [ OPNEXT ] [ OPERAND ] * * char OPCODE - instruction * char OPDATA - modifying data * char OPNEXT - next node (relative offset) * *
    `(package private) static char` | `OP_EOL`
    `(package private) static char` | `OP_ESCAPE`
    `(package private) static char` | `OP_GOTO`
    `(package private) static char` | `OP_MAYBE`
    `(package private) static char` | `OP_NOTHING`
    `(package private) static char` | `OP_OPEN`
    `(package private) static char` | `OP_OPEN_CLUSTER`
    `(package private) static char` | `OP_PLUS`
    `(package private) static char` | `OP_POSIXCLASS`
    `(package private) static char` | `OP_RELUCTANTMAYBE`
    `(package private) static char` | `OP_RELUCTANTPLUS`
    `(package private) static char` | `OP_RELUCTANTSTAR`
    `(package private) static char` | `OP_STAR`
    `(package private) int` | `parenCount`
    `(package private) static char` | `POSIX_CLASS_ALNUM`
    `(package private) static char` | `POSIX_CLASS_ALPHA`
    `(package private) static char` | `POSIX_CLASS_BLANK`
    `(package private) static char` | `POSIX_CLASS_CNTRL`
    `(package private) static char` | `POSIX_CLASS_DIGIT`
    `(package private) static char` | `POSIX_CLASS_GRAPH`
    `(package private) static char` | `POSIX_CLASS_JPART`
    `(package private) static char` | `POSIX_CLASS_JSTART`
    `(package private) static char` | `POSIX_CLASS_LOWER`
    `(package private) static char` | `POSIX_CLASS_PRINT`
    `(package private) static char` | `POSIX_CLASS_PUNCT`
    `(package private) static char` | `POSIX_CLASS_SPACE`
    `(package private) static char` | `POSIX_CLASS_UPPER`
    `(package private) static char` | `POSIX_CLASS_XDIGIT`
    `(package private) REProgram` | `program`
    `static int` | `REPLACE_ALL` Flag bit that indicates that subst should replace all occurrences of this regular expression.
    `static int` | `REPLACE_BACKREFERENCES` Flag bit that indicates that subst should replace backreferences
    `static int` | `REPLACE_FIRSTONLY` Flag bit that indicates that subst should only replace the first occurrence of this regular expression.
    `(package private) CharacterIterator` | `search`
    `(package private) int` | `start0`
    `(package private) int` | `start1`
    `(package private) int` | `start2`
    `(package private) int[]` | `startBackref`
    `(package private) int[]` | `startn`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RE()` Constructs a regular expression matcher with no initial program.
    `RE(REProgram program)` Construct a matcher for a pre-compiled regular expression from program (bytecode) data.
    `RE(REProgram program, int matchFlags)` Construct a matcher for a pre-compiled regular expression from program (bytecode) data.
    `RE(java.lang.String pattern)` Constructs a regular expression matcher from a String by compiling it using a new instance of RECompiler.
    `RE(java.lang.String pattern, int matchFlags)` Constructs a regular expression matcher from a String by compiling it using a new instance of RECompiler.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `allocParens()` Performs lazy allocation of subexpression arrays
    `private int` | `compareChars(char c1, char c2, boolean caseIndependent)` Compares two characters.
    `int` | `getMatchFlags()` Returns the current match behaviour flags.
    `java.lang.String` | `getParen(int which)` Gets the contents of a parenthesized subexpression after a successful match.
    `int` | `getParenCount()` Returns the number of parenthesized subexpressions available after a successful match.
    `int` | `getParenEnd(int which)` Returns the end index of a given paren level.
    `int` | `getParenLength(int which)` Returns the length of a given paren level.
    `int` | `getParenStart(int which)` Returns the start index of a given paren level.
    `REProgram` | `getProgram()` Returns the current regular expression program in use by this matcher object.
    `java.lang.String[]` | `grep(java.lang.Object[] search)` Returns an array of Strings, whose toString representation matches a regular expression.
    `protected void` | `internalError(java.lang.String s)` Throws an Error representing an internal error condition probably resulting from a bug in the regular expression compiler (or possibly data corruption).
    `private boolean` | `isNewline(int i)`
    `boolean` | `match(CharacterIterator search, int i)` Matches the current regular expression program against a character array, starting at a given index.
    `boolean` | `match(java.lang.String search)` Matches the current regular expression program against a String.
    `boolean` | `match(java.lang.String search, int i)` Matches the current regular expression program against a character array, starting at a given index.
    `protected boolean` | `matchAt(int i)` Match the current regular expression program against the current input string, starting at index i of the input string.
    `protected int` | `matchNodes(int firstNode, int lastNode, int idxStart)` Try to match a string against a subset of nodes in the program
    `void` | `setMatchFlags(int matchFlags)` Sets match behaviour flags which alter the way RE does matching.
    `protected void` | `setParenEnd(int which, int i)` Sets the end of a paren level
    `protected void` | `setParenStart(int which, int i)` Sets the start of a paren level
    `void` | `setProgram(REProgram program)` Sets the current regular expression program used by this matcher object.
    `static java.lang.String` | `simplePatternToFullRegularExpression(java.lang.String pattern)` Converts a 'simplified' regular expression to a full regular expression
    `java.lang.String[]` | `split(java.lang.String s)` Splits a string into an array of strings on regular expression boundaries.
    `java.lang.String` | `subst(java.lang.String substituteIn, java.lang.String substitution)` Substitutes a string for this regular expression in another string.
    `java.lang.String` | `subst(java.lang.String substituteIn, java.lang.String substitution, int flags)` Substitutes a string for this regular expression in another string.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### MATCH_NORMAL

          public static final int MATCH_NORMAL

      Specifies normal, case-sensitive matching behaviour.
      See Also:
        Constant Field Values

    - #### MATCH_CASEINDEPENDENT

          public static final int MATCH_CASEINDEPENDENT

      Flag to indicate that matching should be case-independent (folded)
      See Also:
        Constant Field Values

    - #### MATCH_MULTILINE

          public static final int MATCH_MULTILINE

      Newlines should match as BOL/EOL (^ and $)
      See Also:
        Constant Field Values

    - #### MATCH_SINGLELINE

          public static final int MATCH_SINGLELINE

      Consider all input a single body of text - newlines are matched by .
      See Also:
        Constant Field Values

    - #### OP_END

          static final char OP_END

      * The format of a node in a program is: * * [ OPCODE ] [ OPDATA ] [ OPNEXT ] [ OPERAND ] * * char OPCODE - instruction * char OPDATA - modifying data * char OPNEXT - next node (relative offset) * *
      See Also:
        Constant Field Values

    - #### OP_BOL

          static final char OP_BOL

      See Also:
        Constant Field Values

    - #### OP_EOL

          static final char OP_EOL

      See Also:
        Constant Field Values

    - #### OP_ANY

          static final char OP_ANY

      See Also:
        Constant Field Values

    - #### OP_ANYOF

          static final char OP_ANYOF

      See Also:
        Constant Field Values

    - #### OP_BRANCH

          static final char OP_BRANCH

      See Also:
        Constant Field Values

    - #### OP_ATOM

          static final char OP_ATOM

      See Also:
        Constant Field Values

    - #### OP_STAR

          static final char OP_STAR

      See Also:
        Constant Field Values

    - #### OP_PLUS

          static final char OP_PLUS

      See Also:
        Constant Field Values

    - #### OP_MAYBE

          static final char OP_MAYBE

      See Also:
        Constant Field Values

    - #### OP_ESCAPE

          static final char OP_ESCAPE

      See Also:
        Constant Field Values

    - #### OP_OPEN

          static final char OP_OPEN

      See Also:
        Constant Field Values

    - #### OP_OPEN_CLUSTER

          static final char OP_OPEN_CLUSTER

      See Also:
        Constant Field Values

    - #### OP_CLOSE

          static final char OP_CLOSE

      See Also:
        Constant Field Values

    - #### OP_CLOSE_CLUSTER

          static final char OP_CLOSE_CLUSTER

      See Also:
        Constant Field Values

    - #### OP_BACKREF

          static final char OP_BACKREF

      See Also:
        Constant Field Values

    - #### OP_GOTO

          static final char OP_GOTO

      See Also:
        Constant Field Values

    - #### OP_NOTHING

          static final char OP_NOTHING

      See Also:
        Constant Field Values

    - #### OP_CONTINUE

          static final char OP_CONTINUE

      See Also:
        Constant Field Values

    - #### OP_RELUCTANTSTAR

          static final char OP_RELUCTANTSTAR

      See Also:
        Constant Field Values

    - #### OP_RELUCTANTPLUS

          static final char OP_RELUCTANTPLUS

      See Also:
        Constant Field Values

    - #### OP_RELUCTANTMAYBE

          static final char OP_RELUCTANTMAYBE

      See Also:
        Constant Field Values

    - #### OP_POSIXCLASS

          static final char OP_POSIXCLASS

      See Also:
        Constant Field Values

    - #### E_ALNUM

          static final char E_ALNUM

      See Also:
        Constant Field Values

    - #### E_NALNUM

          static final char E_NALNUM

      See Also:
        Constant Field Values

    - #### E_BOUND

          static final char E_BOUND

      See Also:
        Constant Field Values

    - #### E_NBOUND

          static final char E_NBOUND

      See Also:
        Constant Field Values

    - #### E_SPACE

          static final char E_SPACE

      See Also:
        Constant Field Values

    - #### E_NSPACE

          static final char E_NSPACE

      See Also:
        Constant Field Values

    - #### E_DIGIT

          static final char E_DIGIT

      See Also:
        Constant Field Values

    - #### E_NDIGIT

          static final char E_NDIGIT

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_ALNUM

          static final char POSIX_CLASS_ALNUM

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_ALPHA

          static final char POSIX_CLASS_ALPHA

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_BLANK

          static final char POSIX_CLASS_BLANK

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_CNTRL

          static final char POSIX_CLASS_CNTRL

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_DIGIT

          static final char POSIX_CLASS_DIGIT

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_GRAPH

          static final char POSIX_CLASS_GRAPH

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_LOWER

          static final char POSIX_CLASS_LOWER

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_PRINT

          static final char POSIX_CLASS_PRINT

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_PUNCT

          static final char POSIX_CLASS_PUNCT

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_SPACE

          static final char POSIX_CLASS_SPACE

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_UPPER

          static final char POSIX_CLASS_UPPER

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_XDIGIT

          static final char POSIX_CLASS_XDIGIT

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_JSTART

          static final char POSIX_CLASS_JSTART

      See Also:
        Constant Field Values

    - #### POSIX_CLASS_JPART

          static final char POSIX_CLASS_JPART

      See Also:
        Constant Field Values

    - #### maxNode

          static final int maxNode

      See Also:
        Constant Field Values

    - #### MAX_PAREN

          static final int MAX_PAREN

      See Also:
        Constant Field Values

    - #### offsetOpcode

          static final int offsetOpcode

      See Also:
        Constant Field Values

    - #### offsetOpdata

          static final int offsetOpdata

      See Also:
        Constant Field Values

    - #### offsetNext

          static final int offsetNext

      See Also:
        Constant Field Values

    - #### nodeSize

          static final int nodeSize

      See Also:
        Constant Field Values

    - #### program

          REProgram program

    - #### search

          transient CharacterIterator search

    - #### matchFlags

          int matchFlags

    - #### maxParen

          int maxParen

    - #### parenCount

          transient int parenCount

    - #### start0

          transient int start0

    - #### end0

          transient int end0

    - #### start1

          transient int start1

    - #### end1

          transient int end1

    - #### start2

          transient int start2

    - #### end2

          transient int end2

    - #### startn

          transient int[] startn

    - #### endn

          transient int[] endn

    - #### startBackref

          transient int[] startBackref

    - #### endBackref

          transient int[] endBackref

    - #### REPLACE_ALL

          public static final int REPLACE_ALL

      Flag bit that indicates that subst should replace all occurrences of this regular expression.
      See Also:
        Constant Field Values

    - #### REPLACE_FIRSTONLY

          public static final int REPLACE_FIRSTONLY

      Flag bit that indicates that subst should only replace the first occurrence of this regular expression.
      See Also:
        Constant Field Values

    - #### REPLACE_BACKREFERENCES

          public static final int REPLACE_BACKREFERENCES

      Flag bit that indicates that subst should replace backreferences
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RE

          public RE(java.lang.String pattern)
             throws RESyntaxException

      Constructs a regular expression matcher from a String by compiling it using a new instance of RECompiler. If you will be compiling many expressions, you may prefer to use a single RECompiler object instead.
      Parameters:
        `pattern` - The regular expression pattern to compile.
      Throws:
        `RESyntaxException` - Thrown if the regular expression has invalid syntax.
      See Also:
        `RECompiler`, `recompile`

    - #### RE

          public RE(java.lang.String pattern,
            int matchFlags)
             throws RESyntaxException

      Constructs a regular expression matcher from a String by compiling it using a new instance of RECompiler. If you will be compiling many expressions, you may prefer to use a single RECompiler object instead.
      Parameters:
        `pattern` - The regular expression pattern to compile.
        `matchFlags` - The matching style
      Throws:
        `RESyntaxException` - Thrown if the regular expression has invalid syntax.
      See Also:
        `RECompiler`, `recompile`

    - #### RE

          public RE(REProgram program,
            int matchFlags)

      Construct a matcher for a pre-compiled regular expression from program (bytecode) data. Permits special flags to be passed in to modify matching behaviour.
      Parameters:
        `program` - Compiled regular expression program (see RECompiler and/or recompile)
        `matchFlags` - One or more of the RE match behaviour flags (RE.MATCH_*):

               MATCH_NORMAL              // Normal (case-sensitive) matching
               MATCH_CASEINDEPENDENT     // Case folded comparisons
               MATCH_MULTILINE           // Newline matches as BOL/EOL

      See Also:
        `RECompiler`, `REProgram`, `recompile`

    - #### RE

          public RE(REProgram program)

      Construct a matcher for a pre-compiled regular expression from program (bytecode) data.
      Parameters:
        `program` - Compiled regular expression program
      See Also:
        `RECompiler`, `recompile`

    - #### RE

          public RE()

      Constructs a regular expression matcher with no initial program. This is likely to be an uncommon practice, but is still supported.

  - ### Method Detail

    - #### simplePatternToFullRegularExpression

          public static java.lang.String simplePatternToFullRegularExpression(java.lang.String pattern)

      Converts a 'simplified' regular expression to a full regular expression
      Parameters:
        `pattern` - The pattern to convert
      Returns:
        The full regular expression

    - #### setMatchFlags

          public void setMatchFlags(int matchFlags)

      Sets match behaviour flags which alter the way RE does matching.
      Parameters:
        `matchFlags` - One or more of the RE match behaviour flags (RE.MATCH_*):

               MATCH_NORMAL              // Normal (case-sensitive) matching
               MATCH_CASEINDEPENDENT     // Case folded comparisons
               MATCH_MULTILINE           // Newline matches as BOL/EOL

    - #### getMatchFlags

          public int getMatchFlags()

      Returns the current match behaviour flags.
      Returns:
        Current match behaviour flags (RE.MATCH_*).

               MATCH_NORMAL              // Normal (case-sensitive) matching
               MATCH_CASEINDEPENDENT     // Case folded comparisons
               MATCH_MULTILINE           // Newline matches as BOL/EOL

      See Also:
        `setMatchFlags(int)`

    - #### setProgram

          public void setProgram(REProgram program)

      Sets the current regular expression program used by this matcher object.
      Parameters:
        `program` - Regular expression program compiled by RECompiler.
      See Also:
        `RECompiler`, `REProgram`, `recompile`

    - #### getProgram

          public REProgram getProgram()

      Returns the current regular expression program in use by this matcher object.
      Returns:
        Regular expression program
      See Also:
        `setProgram(org.apache.regexp.REProgram)`

    - #### getParenCount

          public int getParenCount()

      Returns the number of parenthesized subexpressions available after a successful match.
      Returns:
        Number of available parenthesized subexpressions

    - #### getParen

          public java.lang.String getParen(int which)

      Gets the contents of a parenthesized subexpression after a successful match.
      Parameters:
        `which` - Nesting level of subexpression
      Returns:
        String

    - #### getParenStart

          public final int getParenStart(int which)

      Returns the start index of a given paren level.
      Parameters:
        `which` - Nesting level of subexpression
      Returns:
        String index

    - #### getParenEnd

          public final int getParenEnd(int which)

      Returns the end index of a given paren level.
      Parameters:
        `which` - Nesting level of subexpression
      Returns:
        String index

    - #### getParenLength

          public final int getParenLength(int which)

      Returns the length of a given paren level.
      Parameters:
        `which` - Nesting level of subexpression
      Returns:
        Number of characters in the parenthesized subexpression

    - #### setParenStart

          protected final void setParenStart(int which,
                           int i)

      Sets the start of a paren level
      Parameters:
        `which` - Which paren level
        `i` - Index in input array

    - #### setParenEnd

          protected final void setParenEnd(int which,
                         int i)

      Sets the end of a paren level
      Parameters:
        `which` - Which paren level
        `i` - Index in input array

    - #### internalError

          protected void internalError(java.lang.String s)
                                throws java.lang.Error

      Throws an Error representing an internal error condition probably resulting from a bug in the regular expression compiler (or possibly data corruption). In practice, this should be very rare.
      Parameters:
        `s` - Error description
      Throws:
        `java.lang.Error`

    - #### allocParens

          private void allocParens()

      Performs lazy allocation of subexpression arrays

    - #### matchNodes

          protected int matchNodes(int firstNode,
                       int lastNode,
                       int idxStart)

      Try to match a string against a subset of nodes in the program
      Parameters:
        `firstNode` - Node to start at in program
        `lastNode` - Last valid node (used for matching a subexpression without matching the rest of the program as well).
        `idxStart` - Starting position in character array
      Returns:
        Final input array index if match succeeded. -1 if not.

    - #### matchAt

          protected boolean matchAt(int i)

      Match the current regular expression program against the current input string, starting at index i of the input string. This method is only meant for internal use.
      Parameters:
        `i` - The input string index to start matching at
      Returns:
        True if the input matched the expression

    - #### match

          public boolean match(java.lang.String search,
                      int i)

      Matches the current regular expression program against a character array, starting at a given index.
      Parameters:
        `search` - String to match against
        `i` - Index to start searching at
      Returns:
        True if string matched

    - #### match

          public boolean match(CharacterIterator search,
                      int i)

      Matches the current regular expression program against a character array, starting at a given index.
      Parameters:
        `search` - String to match against
        `i` - Index to start searching at
      Returns:
        True if string matched

    - #### match

          public boolean match(java.lang.String search)

      Matches the current regular expression program against a String.
      Parameters:
        `search` - String to match against
      Returns:
        True if string matched

    - #### split

          public java.lang.String[] split(java.lang.String s)

      Splits a string into an array of strings on regular expression boundaries. This function works the same way as the Perl function of the same name. Given a regular expression of "[ab]+" and a string to split of "xyzzyababbayyzabbbab123", the result would be the array of Strings "[xyzzy, yyz, 123]".

      Please note that the first string in the resulting array may be an empty string. This happens when the very first character of input string is matched by the pattern.

      Parameters:
        `s` - String to split on this regular exression
      Returns:
        Array of strings

    - #### subst

          public java.lang.String subst(java.lang.String substituteIn,
                               java.lang.String substitution)

      Substitutes a string for this regular expression in another string. This method works like the Perl function of the same name. Given a regular expression of "a*b", a String to substituteIn of "aaaabfooaaabgarplyaaabwackyb" and the substitution String "-", the resulting String returned by subst would be "-foo-garply-wacky-".
      Parameters:
        `substituteIn` - String to substitute within
        `substitution` - String to substitute for all matches of this regular expression.
      Returns:
        The string substituteIn with zero or more occurrences of the current regular expression replaced with the substitution String (if this regular expression object doesn't match at any position, the original String is returned unchanged).

    - #### subst

          public java.lang.String subst(java.lang.String substituteIn,
                               java.lang.String substitution,
                               int flags)

      Substitutes a string for this regular expression in another string. This method works like the Perl function of the same name. Given a regular expression of "a*b", a String to substituteIn of "aaaabfooaaabgarplyaaabwackyb" and the substitution String "-", the resulting String returned by subst would be "-foo-garply-wacky-".

      It is also possible to reference the contents of a parenthesized expression with $0, $1, ... $9. A regular expression of "http://[\\.\\w\\-\\?/~_@&=%]+", a String to substituteIn of "visit us: http://www.apache.org!" and the substitution String "<a href=\"$0\">$0</a>", the resulting String returned by subst would be "visit us: <a href=\"http://www.apache.org\">http://www.apache.org</a>!".

      Note: $0 represents the whole match.

      Parameters:
        `substituteIn` - String to substitute within
        `substitution` - String to substitute for matches of this regular expression
        `flags` - One or more bitwise flags from REPLACE_*. If the REPLACE_FIRSTONLY flag bit is set, only the first occurrence of this regular expression is replaced. If the bit is not set (REPLACE_ALL), all occurrences of this pattern will be replaced. If the flag REPLACE_BACKREFERENCES is set, all backreferences will be processed.
      Returns:
        The string substituteIn with zero or more occurrences of the current regular expression replaced with the substitution String (if this regular expression object doesn't match at any position, the original String is returned unchanged).

    - #### grep

          public java.lang.String[] grep(java.lang.Object[] search)

      Returns an array of Strings, whose toString representation matches a regular expression. This method works like the Perl function of the same name. Given a regular expression of "a*b" and an array of String objects of [foo, aab, zzz, aaaab], the array of Strings returned by grep would be [aab, aaaab].
      Parameters:
        `search` - Array of Objects to search
      Returns:
        Array of Strings whose toString() value matches this regular expression.

    - #### isNewline

          private boolean isNewline(int i)

      Returns:
        true if character at i-th position in the `search` string is a newline

    - #### compareChars

          private int compareChars(char c1,
                         char c2,
                         boolean caseIndependent)

      Compares two characters.
      Parameters:
        `c1` - first character to compare.
        `c2` - second character to compare.
        `caseIndependent` - whether comparision is case insensitive or not.
      Returns:
        negative, 0, or positive integer as the first character less than, equal to, or greater then the second.

Copyright © 2001-2007 Apache Software Foundation. All Rights Reserved.