public RE() 
{
        this((REProgram) null, MATCH_NORMAL);
}

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

 public RE(String pattern) throws RESyntaxException 
{
        this(pattern, MATCH_NORMAL);
}

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.

Also see:

RECompiler
recompile
exception: RESyntaxException - Thrown if the regular expression has invalid syntax.

 public RE(REProgram program) 
{
        this(program, MATCH_NORMAL);
}

Construct a matcher for a pre-compiled regular expression from program (bytecode) data.

Parameters:

program - Compiled regular expression program

Also see:

RECompiler
recompile

 public RE(String pattern,
    int matchFlags) throws RESyntaxException 
{
        this(new RECompiler().compile(pattern), matchFlags);
}

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.

Also see:

RECompiler
recompile
exception: RESyntaxException - Thrown if the regular expression has invalid syntax.

 public RE(REProgram program,
    int matchFlags) 
{
        setProgram(program);
        setMatchFlags(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


Also see:

RECompiler
REProgram
recompile

 public int getMatchFlags() 
{
        return matchFlags;
}

Returns the current match behaviour flags.

 public String getParen(int which) 
{
        int start;
        if (which <  parenCount && (start = getParenStart(which))  >= 0)
        {
            return search.substring(start, getParenEnd(which));
        }
        return null;
}

Gets the contents of a parenthesized subexpression after a successful match.

 public int getParenCount() 
{
        return parenCount;
}

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

 public final int getParenEnd(int which) 
{
        if (which <  parenCount)
        {
            switch (which)
            {
                case 0:
                    return end0;
                case 1:
                    return end1;
                case 2:
                    return end2;
                default:
                    if (endn == null)
                    {
                        allocParens();
                    }
                    return endn[which];
            }
        }
        return -1;
}

Returns the end index of a given paren level.

 public final int getParenLength(int which) 
{
        if (which <  parenCount)
        {
            return getParenEnd(which) - getParenStart(which);
        }
        return -1;
}

Returns the length of a given paren level.

 public final int getParenStart(int which) 
{
        if (which <  parenCount)
        {
            switch (which)
            {
                case 0:
                    return start0;
                case 1:
                    return start1;
                case 2:
                    return start2;
                default:
                    if (startn == null)
                    {
                        allocParens();
                    }
                    return startn[which];
            }
        }
        return -1;
}

Returns the start index of a given paren level.

 public REProgram getProgram() 
{
        return program;
}

Returns the current regular expression program in use by this matcher object.

 public String[] grep(Object[] search) 
{
        // Create new vector to hold return items
        Vector v = new Vector();
        // Traverse array of objects
        for (int i = 0; i <  search.length; i++)
        {
            // Get next object as a string
            String s = search[i].toString();
            // If it matches this regexp, add it to the list
            if (match(s))
            {
                v.addElement(s);
            }
        }
        // Return vector as an array of strings
        String[] ret = new String[v.size()];
        v.copyInto(ret);
        return ret;
}

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].

 protected  void internalError(String s) throws Error 
{
        throw new Error("RE internal error: " + s);
}

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.

 public boolean match(String search) 
{
        return match(search, 0);
}

Matches the current regular expression program against a String.

 public boolean match(String search,
    int i) 
{
        return match(new StringCharacterIterator(search), i);
}

Matches the current regular expression program against a character array, starting at a given index.

 public boolean match(CharacterIterator search,
    int i) 
{
        // There is no compiled program to search with!
        if (program == null)
        {
            // This should be uncommon enough to be an error case rather
            // than an exception (which would have to be handled everywhere)
            internalError("No RE program to run!");
        }
        // Save string to search
        this.search = search;
        // Can we optimize the search by looking for new lines?
        if ((program.flags & REProgram.OPT_HASBOL) == REProgram.OPT_HASBOL)
        {
            // Non multi-line matching with BOL: Must match at '0' index
            if ((matchFlags & MATCH_MULTILINE) == 0)
            {
                return i == 0 && matchAt(i);
            }
            // Multi-line matching with BOL: Seek to next line
            for ( ;! search.isEnd(i); i++)
            {
                // Skip if we are at the beginning of the line
                if (isNewline(i))
                {
                    continue;
                }
                // Match at the beginning of the line
                if (matchAt(i))
                {
                    return true;
                }
                // Skip to the end of line
                for ( ;! search.isEnd(i); i++)
                {
                    if (isNewline(i))
                    {
                        break;
                    }
                }
            }
            return false;
        }
        // Can we optimize the search by looking for a prefix string?
        if (program.prefix == null)
        {
            // Unprefixed matching must try for a match at each character
            for ( ;! search.isEnd(i - 1); i++)
            {
                // Try a match at index i
                if (matchAt(i))
                {
                    return true;
                }
            }
            return false;
        }
        else
        {
            // Prefix-anchored matching is possible
            boolean caseIndependent = (matchFlags & MATCH_CASEINDEPENDENT) != 0;
            char[] prefix = program.prefix;
            for ( ; !search.isEnd(i + prefix.length - 1); i++)
            {
                int j = i;
                int k = 0;
                boolean match;
                do {
                    // If there's a mismatch of any character in the prefix, give up
                    match = (compareChars(search.charAt(j++), prefix[k++], caseIndependent) == 0);
                } while (match && k <  prefix.length);
                // See if the whole prefix string matched
                if (k == prefix.length)
                {
                    // We matched the full prefix at firstChar, so try it
                    if (matchAt(i))
                    {
                        return true;
                    }
                }
            }
            return false;
        }
}

Matches the current regular expression program against a character array, starting at a given index.

 protected boolean matchAt(int i) 
{
        // Initialize start pointer, paren cache and paren count
        start0 = -1;
        end0   = -1;
        start1 = -1;
        end1   = -1;
        start2 = -1;
        end2   = -1;
        startn = null;
        endn   = null;
        parenCount = 1;
        setParenStart(0, i);
        // Allocate backref arrays (unless optimizations indicate otherwise)
        if ((program.flags & REProgram.OPT_HASBACKREFS) != 0)
        {
            startBackref = new int[maxParen];
            endBackref = new int[maxParen];
        }
        // Match against string
        int idx;
        if ((idx = matchNodes(0, maxNode, i)) != -1)
        {
            setParenEnd(0, idx);
            return true;
        }
        // Didn't match
        parenCount = 0;
        return false;
}

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.

 protected int matchNodes(int firstNode,
    int lastNode,
    int idxStart) 
{
        // Our current place in the string
        int idx = idxStart;
        // Loop while node is valid
        int next, opcode, opdata;
        int idxNew;
        char[] instruction = program.instruction;
        for (int node = firstNode; node <  lastNode; )
        {
            opcode = instruction[node /* + offsetOpcode */];
            next   = node + (short) instruction[node + offsetNext];
            opdata = instruction[node + offsetOpdata];
            switch (opcode)
            {
                case OP_MAYBE:
                case OP_STAR:
                    {
                        // Try to match the following subexpr. If it matches:
                        //   MAYBE:  Continues matching rest of the expression
                        //    STAR:  Points back here to repeat subexpr matching
                        if ((idxNew = matchNodes(node + nodeSize, maxNode, idx)) != -1)
                        {
                            return idxNew;
                        }
                        // If failed, just continue with the rest of expression
                        break;
                    }
                case OP_PLUS:
                    {
                        // Try to match the subexpr again (and again (and ...
                        if ((idxNew = matchNodes(next, maxNode, idx)) != -1)
                        {
                            return idxNew;
                        }
                        // If failed, just continue with the rest of expression
                        // Rest is located at the next pointer of the next instruction
                        // (which must be OP_CONTINUE)
                        node = next + (short) instruction[next + offsetNext];
                        continue;
                    }
                case OP_RELUCTANTMAYBE:
                case OP_RELUCTANTSTAR:
                    {
                        // Try to match the rest without using the reluctant subexpr
                        if ((idxNew = matchNodes(next, maxNode, idx)) != -1)
                        {
                            return idxNew;
                        }
                        // Try reluctant subexpr. If it matches:
                        //   RELUCTANTMAYBE: Continues matching rest of the expression
                        //    RELUCTANTSTAR: Points back here to repeat reluctant star matching
                        return matchNodes(node + nodeSize, next, idx);
                    }
                case OP_RELUCTANTPLUS:
                    {
                        // Continue matching the rest without using the reluctant subexpr
                        if ((idxNew = matchNodes(next + (short) instruction[next + offsetNext], maxNode, idx)) != -1)
                        {
                            return idxNew;
                        }
                        // Try to match subexpression again
                        break;
                    }
                case OP_OPEN:
                    // Match subexpression
                    if ((program.flags & REProgram.OPT_HASBACKREFS) != 0)
                    {
                        startBackref[opdata] = idx;
                    }
                    if ((idxNew = matchNodes(next, maxNode, idx)) != -1)
                    {
                        // Increase valid paren count
                        if (opdata  >= parenCount)
                        {
                            parenCount = opdata + 1;
                        }
                        // Don't set paren if already set later on
                        if (getParenStart(opdata) == -1)
                        {
                            setParenStart(opdata, idx);
                        }
                    }
                    return idxNew;
                case OP_CLOSE:
                    // Done matching subexpression
                    if ((program.flags & REProgram.OPT_HASBACKREFS) != 0)
                    {
                        endBackref[opdata] = idx;
                    }
                    if ((idxNew = matchNodes(next, maxNode, idx)) != -1)
                    {
                        // Increase valid paren count
                        if (opdata   >= parenCount)
                        {
                            parenCount = opdata + 1;
                        }
                        // Don't set paren if already set later on
                        if (getParenEnd(opdata) == -1)
                        {
                            setParenEnd(opdata, idx);
                        }
                    }
                    return idxNew;
                case OP_BACKREF:
                    {
                        // Get the start and end of the backref
                        int s = startBackref[opdata];
                        int e = endBackref[opdata];
                        // We don't know the backref yet
                        if (s == -1 || e == -1)
                        {
                            return -1;
                        }
                        // The backref is empty size
                        if (s == e)
                        {
                            break;
                        }
                        // Get the length of the backref
                        int l = e - s;
                        // If there's not enough input left, give up.
                        if (search.isEnd(idx + l - 1))
                        {
                            return -1;
                        }
                        // Case fold the backref?
                        final boolean caseFold =
                            ((matchFlags & MATCH_CASEINDEPENDENT) != 0);
                        // Compare backref to input
                        for (int i = 0; i <  l; i++)
                        {
                            if (compareChars(search.charAt(idx++), search.charAt(s + i), caseFold) != 0)
                            {
                                return -1;
                            }
                        }
                    }
                    break;
                case OP_BOL:
                    // Fail if we're not at the start of the string
                    if (idx != 0)
                    {
                        // If we're multiline matching, we could still be at the start of a line
                        if ((matchFlags & MATCH_MULTILINE) == MATCH_MULTILINE)
                        {
                            // Continue if at the start of a line
                            if (isNewline(idx - 1))
                            {
                                break;
                            }
                        }
                        return -1;
                    }
                    break;
                case OP_EOL:
                    // If we're not at the end of string
                    if (!search.isEnd(0) && !search.isEnd(idx))
                    {
                        // If we're multi-line matching
                        if ((matchFlags & MATCH_MULTILINE) == MATCH_MULTILINE)
                        {
                            // Continue if we're at the end of a line
                            if (isNewline(idx))
                            {
                                break;
                            }
                        }
                        return -1;
                    }
                    break;
                case OP_ESCAPE:
                    // Which escape?
                    switch (opdata)
                    {
                        // Word boundary match
                        case E_NBOUND:
                        case E_BOUND:
                            {
                                char cLast = ((idx == 0) ? '\n' : search.charAt(idx - 1));
                                char cNext = ((search.isEnd(idx)) ? '\n' : search.charAt(idx));
                                if ((Character.isLetterOrDigit(cLast) == Character.isLetterOrDigit(cNext)) == (opdata == E_BOUND))
                                {
                                    return -1;
                                }
                            }
                            break;
                        // Alpha-numeric, digit, space, javaLetter, javaLetterOrDigit
                        case E_ALNUM:
                        case E_NALNUM:
                        case E_DIGIT:
                        case E_NDIGIT:
                        case E_SPACE:
                        case E_NSPACE:
                            // Give up if out of input
                            if (search.isEnd(idx))
                            {
                                return -1;
                            }
                            char c = search.charAt(idx);
                            // Switch on escape
                            switch (opdata)
                            {
                                case E_ALNUM:
                                case E_NALNUM:
                                    if (!((Character.isLetterOrDigit(c) || c == '_') == (opdata == E_ALNUM)))
                                    {
                                        return -1;
                                    }
                                    break;
                                case E_DIGIT:
                                case E_NDIGIT:
                                    if (!(Character.isDigit(c) == (opdata == E_DIGIT)))
                                    {
                                        return -1;
                                    }
                                    break;
                                case E_SPACE:
                                case E_NSPACE:
                                    if (!(Character.isWhitespace(c) == (opdata == E_SPACE)))
                                    {
                                        return -1;
                                    }
                                    break;
                            }
                            idx++;
                            break;
                        default:
                            internalError("Unrecognized escape '" + opdata + "'");
                    }
                    break;
                case OP_ANY:
                    if ((matchFlags & MATCH_SINGLELINE) == MATCH_SINGLELINE) {
                        // Match anything
                        if (search.isEnd(idx))
                        {
                            return -1;
                        }
                    }
                    else
                    {
                        // Match anything but a newline
                        if (search.isEnd(idx) || isNewline(idx))
                        {
                            return -1;
                        }
                    }
                    idx++;
                    break;
                case OP_ATOM:
                    {
                        // Match an atom value
                        if (search.isEnd(idx))
                        {
                            return -1;
                        }
                        // Get length of atom and starting index
                        // int lenAtom = opdata;
                        int startAtom = node + nodeSize;
                        // Give up if not enough input remains to have a match
                        if (search.isEnd(opdata + idx - 1))
                        {
                            return -1;
                        }
                        // Match atom differently depending on casefolding flag
                        final boolean caseFold =
                            ((matchFlags & MATCH_CASEINDEPENDENT) != 0);
                        for (int i = 0; i <  opdata; i++)
                        {
                            if (compareChars(search.charAt(idx++), instruction[startAtom + i], caseFold) != 0)
                            {
                                return -1;
                            }
                        }
                    }
                    break;
                case OP_POSIXCLASS:
                    {
                        // Out of input?
                        if (search.isEnd(idx))
                        {
                            return -1;
                        }
                        switch (opdata)
                        {
                            case POSIX_CLASS_ALNUM:
                                if (!Character.isLetterOrDigit(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_ALPHA:
                                if (!Character.isLetter(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_DIGIT:
                                if (!Character.isDigit(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_BLANK: // JWL - bugbug: is this right??
                                if (!Character.isSpaceChar(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_SPACE:
                                if (!Character.isWhitespace(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_CNTRL:
                                if (Character.getType(search.charAt(idx)) != Character.CONTROL)
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_GRAPH: // JWL - bugbug???
                                switch (Character.getType(search.charAt(idx)))
                                {
                                    case Character.MATH_SYMBOL:
                                    case Character.CURRENCY_SYMBOL:
                                    case Character.MODIFIER_SYMBOL:
                                    case Character.OTHER_SYMBOL:
                                        break;
                                    default:
                                        return -1;
                                }
                                break;
                            case POSIX_CLASS_LOWER:
                                if (Character.getType(search.charAt(idx)) != Character.LOWERCASE_LETTER)
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_UPPER:
                                if (Character.getType(search.charAt(idx)) != Character.UPPERCASE_LETTER)
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_PRINT:
                                if (Character.getType(search.charAt(idx)) == Character.CONTROL)
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_PUNCT:
                            {
                                int type = Character.getType(search.charAt(idx));
                                switch(type)
                                {
                                    case Character.DASH_PUNCTUATION:
                                    case Character.START_PUNCTUATION:
                                    case Character.END_PUNCTUATION:
                                    case Character.CONNECTOR_PUNCTUATION:
                                    case Character.OTHER_PUNCTUATION:
                                        break;
                                    default:
                                        return -1;
                                }
                            }
                            break;
                            case POSIX_CLASS_XDIGIT: // JWL - bugbug??
                            {
                                boolean isXDigit = ((search.charAt(idx)  >= '0' && search.charAt(idx) < = '9') ||
                                                    (search.charAt(idx)  >= 'a' && search.charAt(idx) < = 'f') ||
                                                    (search.charAt(idx)  >= 'A' && search.charAt(idx) < = 'F'));
                                if (!isXDigit)
                                {
                                    return -1;
                                }
                            }
                            break;
                            case POSIX_CLASS_JSTART:
                                if (!Character.isJavaIdentifierStart(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            case POSIX_CLASS_JPART:
                                if (!Character.isJavaIdentifierPart(search.charAt(idx)))
                                {
                                    return -1;
                                }
                                break;
                            default:
                                internalError("Bad posix class");
                                break;
                        }
                        // Matched.
                        idx++;
                    }
                    break;
                case OP_ANYOF:
                    {
                        // Out of input?
                        if (search.isEnd(idx))
                        {
                            return -1;
                        }
                        // Get character to match against character class and maybe casefold
                        char c = search.charAt(idx);
                        boolean caseFold = (matchFlags & MATCH_CASEINDEPENDENT) != 0;
                        // Loop through character class checking our match character
                        int idxRange = node + nodeSize;
                        int idxEnd = idxRange + (opdata * 2);
                        boolean match = false;
                        for (int i = idxRange; !match && i <  idxEnd; )
                        {
                            // Get start, end and match characters
                            char s = instruction[i++];
                            char e = instruction[i++];
                            match = ((compareChars(c, s, caseFold)  >= 0)
                                     && (compareChars(c, e, caseFold) < = 0));
                        }
                        // Fail if we didn't match the character class
                        if (!match)
                        {
                            return -1;
                        }
                        idx++;
                    }
                    break;
                case OP_BRANCH:
                {
                    // Check for choices
                    // FIXME Dead code - only reason to keep is backward compat with pre-compiled exprs. Remove?
                    if (instruction[next /* + offsetOpcode */] != OP_BRANCH)
                    {
                        // If there aren't any other choices, just evaluate this branch.
                        node += nodeSize;
                        continue;
                    }
                    // Try all available branches
                    int nextBranch;
                    do
                    {
                        // Try matching the branch against the string
                        if ((idxNew = matchNodes(node + nodeSize, maxNode, idx)) != -1)
                        {
                            return idxNew;
                        }
                        // Go to next branch (if any)
                        nextBranch = (short) instruction[node + offsetNext];
                        node += nextBranch;
                    }
                    while (nextBranch != 0 && (instruction[node /* + offsetOpcode */] == OP_BRANCH));
                    // Failed to match any branch!
                    return -1;
                }
                case OP_OPEN_CLUSTER:
                case OP_CLOSE_CLUSTER:
                    // starting or ending the matching of a subexpression which has no backref.
                case OP_NOTHING:
                case OP_GOTO:
                    // Just advance to the next node without doing anything
                    break;
                case OP_CONTINUE:
                    // Advance to the following node
                    node += nodeSize;
                    continue;
                case OP_END:
                    // Match has succeeded!
                    setParenEnd(0, idx);
                    return idx;
                default:
                    // Corrupt program
                    internalError("Invalid opcode '" + opcode + "'");
            }
            // Advance to the next node in the program
            node = next;
        }
        // We "should" never end up here
        internalError("Corrupt program");
        return -1;
}

Try to match a string against a subset of nodes in the program

 public  void setMatchFlags(int matchFlags) 
{
        this.matchFlags = matchFlags;
}

Sets match behaviour flags which alter the way RE does matching.

 protected final  void setParenEnd(int which,
    int i) 
{
        if (which <  parenCount)
        {
            switch (which)
            {
                case 0:
                    end0 = i;
                    break;
                case 1:
                    end1 = i;
                    break;
                case 2:
                    end2 = i;
                    break;
                default:
                    if (endn == null)
                    {
                        allocParens();
                    }
                    endn[which] = i;
                    break;
            }
        }
}

Sets the end of a paren level

 protected final  void setParenStart(int which,
    int i) 
{
        if (which <  parenCount)
        {
            switch (which)
            {
                case 0:
                    start0 = i;
                    break;
                case 1:
                    start1 = i;
                    break;
                case 2:
                    start2 = i;
                    break;
                default:
                    if (startn == null)
                    {
                        allocParens();
                    }
                    startn[which] = i;
                    break;
            }
        }
}

Sets the start of a paren level

 public  void setProgram(REProgram program) 
{
        this.program = program;
        if (program != null && program.maxParens != -1) {
            this.maxParen = program.maxParens;
        } else {
            this.maxParen = MAX_PAREN;
        }
}

Sets the current regular expression program used by this matcher object.

 public static String simplePatternToFullRegularExpression(String pattern) 
{
        StringBuffer buf = new StringBuffer();
        for (int i = 0; i <  pattern.length(); i++)
        {
            char c = pattern.charAt(i);
            switch (c)
            {
                case '*':
                    buf.append(".*");
                    break;
                case '.':
                case '[':
                case ']':
                case '\\':
                case '+':
                case '?':
                case '{':
                case '}':
                case '$':
                case '^':
                case '|':
                case '(':
                case ')':
                    buf.append('\\');
                default:
                    buf.append(c);
                    break;
            }
        }
        return buf.toString();
}

Converts a 'simplified' regular expression to a full regular expression

 public String[] split(String s) 
{
        // Create new vector
        Vector v = new Vector();
        // Start at position 0 and search the whole string
        int pos = 0;
        int len = s.length();
        // Try a match at each position
        while (pos <  len && match(s, pos))
        {
            // Get start of match
            int start = getParenStart(0);
            // Get end of match
            int newpos = getParenEnd(0);
            // Check if no progress was made
            if (newpos == pos)
            {
                v.addElement(s.substring(pos, start + 1));
                newpos++;
            }
            else
            {
                v.addElement(s.substring(pos, start));
            }
            // Move to new position
            pos = newpos;
        }
        // Push remainder if it's not empty
        String remainder = s.substring(pos);
        if (remainder.length() != 0)
        {
            v.addElement(remainder);
        }
        // Return vector as an array of strings
        String[] ret = new String[v.size()];
        v.copyInto(ret);
        return ret;
}

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.

 public String subst(String substituteIn,
    String substitution) 
{
        return subst(substituteIn, substitution, REPLACE_ALL);
}

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-".

 public String subst(String substituteIn,
    String substitution,
    int flags) 
{
        // String to return
        StringBuffer ret = new StringBuffer();
        // Start at position 0 and search the whole string
        int pos = 0;
        int len = substituteIn.length();
        // Try a match at each position
        while (pos <  len && match(substituteIn, pos))
        {
            // Append string before match
            ret.append(substituteIn.substring(pos, getParenStart(0)));
            if ((flags & REPLACE_BACKREFERENCES) != 0)
            {
                // Process backreferences
                int lCurrentPosition = 0;
                int lLastPosition = -2;
                int lLength = substitution.length();
                while ((lCurrentPosition = substitution.indexOf("$", lCurrentPosition))  >= 0)
                {
                    if ((lCurrentPosition == 0 || substitution.charAt(lCurrentPosition - 1) != '\\')
                        && lCurrentPosition + 1 <  lLength)
                    {
                        char c = substitution.charAt(lCurrentPosition + 1);
                        if (c  >= '0' && c < = '9')
                        {
                            // Append everything between the last and the current $ sign
                            ret.append(substitution.substring(lLastPosition + 2, lCurrentPosition));
                            // Append the parenthesized expression, if present
                            String val = getParen(c - '0');
                            if (val != null) {
                                ret.append(val);
                            }
                            lLastPosition = lCurrentPosition;
                        }
                    }
                    // Move forward, skipping past match
                    lCurrentPosition++;
                }
                // Append everything after the last $ sign
                ret.append(substitution.substring(lLastPosition + 2, lLength));
            }
            else
            {
                // Append substitution without processing backreferences
                ret.append(substitution);
            }
            // Move forward, skipping past match
            int newpos = getParenEnd(0);
            // We always want to make progress!
            if (newpos == pos)
            {
                newpos++;
            }
            // Try new position
            pos = newpos;
            // Break out if we're only supposed to replace one occurrence
            if ((flags & REPLACE_FIRSTONLY) != 0)
            {
                break;
            }
        }
        // If there's remaining input, append it
        if (pos <  len)
        {
            ret.append(substituteIn.substring(pos));
        }
        // Return string buffer as string
        return ret.toString();
}

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.