The Tor Browser / file revision

 /*

 **********************************************************************

 *   Copyright (C) 2002-2013, International Business Machines

 *   Corporation and others.  All Rights Reserved.

 **********************************************************************

 *   file name:  regex.h

 *   encoding:   US-ASCII

 *   indentation:4

 *

 *   created on: 2002oct22

 *   created by: Andy Heninger

 *

 *   ICU Regular Expressions, API for C++

 */

 #ifndef REGEX_H

 #define REGEX_H

 //#define REGEX_DEBUG

 /**

  * \file

  * \brief  C++ API:  Regular Expressions

  *

  * <h2>Regular Expression API</h2>

  *

  * <p>The ICU API for processing regular expressions consists of two classes,

  *  <code>RegexPattern</code> and <code>RegexMatcher</code>.

  *  <code>RegexPattern</code> objects represent a pre-processed, or compiled

  *  regular expression.  They are created from a regular expression pattern string,

  *  and can be used to create <code>RegexMatcher</code> objects for the pattern.</p>

  *

  * <p>Class <code>RegexMatcher</code> bundles together a regular expression

  *  pattern and a target string to which the search pattern will be applied.

  *  <code>RegexMatcher</code> includes API for doing plain find or search

  *  operations, for search and replace operations, and for obtaining detailed

  *  information about bounds of a match. </p>

  *

  * <p>Note that by constructing <code>RegexMatcher</code> objects directly from regular

  * expression pattern strings application code can be simplified and the explicit

  * need for <code>RegexPattern</code> objects can usually be eliminated.

  * </p>

  */

 #include "unicode/utypes.h"

 #if !UCONFIG_NO_REGULAR_EXPRESSIONS

 #include "unicode/uobject.h"

 #include "unicode/unistr.h"

 #include "unicode/utext.h"

 #include "unicode/parseerr.h"

 #include "unicode/uregex.h"

 // Forward Declarations

 U_NAMESPACE_BEGIN

 struct Regex8BitSet;

 class  RegexCImpl;

 class  RegexMatcher;

 class  RegexPattern;

 struct REStackFrame;

 class  RuleBasedBreakIterator;

 class  UnicodeSet;

 class  UVector;

 class  UVector32;

 class  UVector64;

 #ifndef U_HIDE_INTERNAL_API

 /**

  *   RBBIPatternDump   Debug function, displays the compiled form of a pattern.

  *   @internal

  */

 #ifdef REGEX_DEBUG

 U_INTERNAL void U_EXPORT2

     RegexPatternDump(const RegexPattern *pat);

 #else

     #undef RegexPatternDump

     #define RegexPatternDump(pat)

 #endif

 #endif  /* U_HIDE_INTERNAL_API */

 /**

   * Class <code>RegexPattern</code> represents a compiled regular expression.  It includes

   * factory methods for creating a RegexPattern object from the source (string) form

   * of a regular expression, methods for creating RegexMatchers that allow the pattern

   * to be applied to input text, and a few convenience methods for simple common

   * uses of regular expressions.

   *

   * <p>Class RegexPattern is not intended to be subclassed.</p>

   *

   * @stable ICU 2.4

   */

 class U_I18N_API RegexPattern: public UObject {

 public:

     /**

      * default constructor.  Create a RegexPattern object that refers to no actual

      *   pattern.  Not normally needed; RegexPattern objects are usually

      *   created using the factory method <code>compile()</code>.

      *

      * @stable ICU 2.4

      */

     RegexPattern();

     /**

      * Copy Constructor.  Create a new RegexPattern object that is equivalent

      *                    to the source object.

      * @param source the pattern object to be copied.

      * @stable ICU 2.4

      */

     RegexPattern(const RegexPattern &source);

     /**

      * Destructor.  Note that a RegexPattern object must persist so long as any

      *  RegexMatcher objects that were created from the RegexPattern are active.

      * @stable ICU 2.4

      */

     virtual ~RegexPattern();

     /**

      * Comparison operator.  Two RegexPattern objects are considered equal if they

      * were constructed from identical source patterns using the same match flag

      * settings.

      * @param that a RegexPattern object to compare with "this".

      * @return TRUE if the objects are equivalent.

      * @stable ICU 2.4

      */

     UBool           operator==(const RegexPattern& that) const;

     /**

      * Comparison operator.  Two RegexPattern objects are considered equal if they

      * were constructed from identical source patterns using the same match flag

      * settings.

      * @param that a RegexPattern object to compare with "this".

      * @return TRUE if the objects are different.

      * @stable ICU 2.4

      */

     inline UBool    operator!=(const RegexPattern& that) const {return ! operator ==(that);}

     /**

      * Assignment operator.  After assignment, this RegexPattern will behave identically

      *     to the source object.

      * @stable ICU 2.4

      */

     RegexPattern  &operator =(const RegexPattern &source);

     /**

      * Create an exact copy of this RegexPattern object.  Since RegexPattern is not

      * intended to be subclasses, <code>clone()</code> and the copy construction are

      * equivalent operations.

      * @return the copy of this RegexPattern

      * @stable ICU 2.4

      */

     virtual RegexPattern  *clone() const;

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object.  These compile methods, rather than the constructors, are the usual

     * way that RegexPattern objects are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>All pattern match mode flags are set to their default values.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string rather than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled.

     * @param pe    Receives the position (line and column nubers) of any error

     *              within the regular expression.)

     * @param status A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 2.4

     */

     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,

         UParseError          &pe,

         UErrorCode           &status);

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object.  These compile methods, rather than the constructors, are the usual

     * way that RegexPattern objects are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>All pattern match mode flags are set to their default values.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string rather than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled. Note, the text referred

     *              to by this UText must not be deleted during the lifetime of the

     *              RegexPattern object or any RegexMatcher object created from it.

     * @param pe    Receives the position (line and column nubers) of any error

     *              within the regular expression.)

     * @param status A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 4.6

     */

     static RegexPattern * U_EXPORT2 compile( UText *regex,

         UParseError          &pe,

         UErrorCode           &status);

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object using the specified match mode flags.  These compile methods,

     * rather than the constructors, are the usual way that RegexPattern objects

     * are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string instead of than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled.

     * @param flags The match mode flags to be used.

     * @param pe    Receives the position (line and column numbers) of any error

     *              within the regular expression.)

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 2.4

     */

     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,

         uint32_t             flags,

         UParseError          &pe,

         UErrorCode           &status);

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object using the specified match mode flags.  These compile methods,

     * rather than the constructors, are the usual way that RegexPattern objects

     * are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string instead of than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled. Note, the text referred

     *              to by this UText must not be deleted during the lifetime of the

     *              RegexPattern object or any RegexMatcher object created from it.

     * @param flags The match mode flags to be used.

     * @param pe    Receives the position (line and column numbers) of any error

     *              within the regular expression.)

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 4.6

     */

     static RegexPattern * U_EXPORT2 compile( UText *regex,

         uint32_t             flags,

         UParseError          &pe,

         UErrorCode           &status);

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object using the specified match mode flags.  These compile methods,

     * rather than the constructors, are the usual way that RegexPattern objects

     * are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string instead of than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled.

     * @param flags The match mode flags to be used.

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 2.6

     */

     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,

         uint32_t             flags,

         UErrorCode           &status);

    /**

     * Compiles the regular expression in string form into a RegexPattern

     * object using the specified match mode flags.  These compile methods,

     * rather than the constructors, are the usual way that RegexPattern objects

     * are created.

     *

     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher

     * objects created from the pattern are active.  RegexMatchers keep a pointer

     * back to their pattern, so premature deletion of the pattern is a

     * catastrophic error.</p>

     *

     * <p>Note that it is often more convenient to construct a RegexMatcher directly

     *    from a pattern string instead of than separately compiling the pattern and

     *    then creating a RegexMatcher object from the pattern.</p>

     *

     * @param regex The regular expression to be compiled. Note, the text referred

     *              to by this UText must not be deleted during the lifetime of the

     *              RegexPattern object or any RegexMatcher object created from it.

     * @param flags The match mode flags to be used.

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return      A regexPattern object for the compiled pattern.

     *

     * @stable ICU 4.6

     */

     static RegexPattern * U_EXPORT2 compile( UText *regex,

         uint32_t             flags,

         UErrorCode           &status);

    /**

     * Get the match mode flags that were used when compiling this pattern.

     * @return  the match mode flags

     * @stable ICU 2.4

     */

     virtual uint32_t flags() const;

    /**

     * Creates a RegexMatcher that will match the given input against this pattern.  The

     * RegexMatcher can then be used to perform match, find or replace operations

     * on the input.  Note that a RegexPattern object must not be deleted while

     * RegexMatchers created from it still exist and might possibly be used again.

     * <p>

     * The matcher will retain a reference to the supplied input string, and all regexp

     * pattern matching operations happen directly on this original string.  It is

     * critical that the string not be altered or deleted before use by the regular

     * expression operations is complete.

     *

     * @param input    The input string to which the regular expression will be applied.

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return         A RegexMatcher object for this pattern and input.

     *

     * @stable ICU 2.4

     */

     virtual RegexMatcher *matcher(const UnicodeString &input,

         UErrorCode          &status) const;

 private:

     /**

      * Cause a compilation error if an application accidentally attempts to

      *   create a matcher with a (UChar *) string as input rather than

      *   a UnicodeString.  Avoids a dangling reference to a temporary string.

      * <p>

      * To efficiently work with UChar *strings, wrap the data in a UnicodeString

      * using one of the aliasing constructors, such as

      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>

      * or in a UText, using

      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>

      *

      */

     RegexMatcher *matcher(const UChar *input,

         UErrorCode          &status) const;

 public:

    /**

     * Creates a RegexMatcher that will match against this pattern.  The

     * RegexMatcher can be used to perform match, find or replace operations.

     * Note that a RegexPattern object must not be deleted while

     * RegexMatchers created from it still exist and might possibly be used again.

     *

     * @param status   A reference to a UErrorCode to receive any errors.

     * @return      A RegexMatcher object for this pattern and input.

     *

     * @stable ICU 2.6

     */

     virtual RegexMatcher *matcher(UErrorCode  &status) const;

    /**

     * Test whether a string matches a regular expression.  This convenience function

     * both compiles the regular expression and applies it in a single operation.

     * Note that if the same pattern needs to be applied repeatedly, this method will be

     * less efficient than creating and reusing a RegexMatcher object.

     *

     * @param regex The regular expression

     * @param input The string data to be matched

     * @param pe Receives the position of any syntax errors within the regular expression

     * @param status A reference to a UErrorCode to receive any errors.

     * @return True if the regular expression exactly matches the full input string.

     *

     * @stable ICU 2.4

     */

     static UBool U_EXPORT2 matches(const UnicodeString   &regex,

         const UnicodeString   &input,

               UParseError     &pe,

               UErrorCode      &status);

    /**

     * Test whether a string matches a regular expression.  This convenience function

     * both compiles the regular expression and applies it in a single operation.

     * Note that if the same pattern needs to be applied repeatedly, this method will be

     * less efficient than creating and reusing a RegexMatcher object.

     *

     * @param regex The regular expression

     * @param input The string data to be matched

     * @param pe Receives the position of any syntax errors within the regular expression

     * @param status A reference to a UErrorCode to receive any errors.

     * @return True if the regular expression exactly matches the full input string.

     *

     * @stable ICU 4.6

     */

     static UBool U_EXPORT2 matches(UText *regex,

         UText           *input,

         UParseError     &pe,

         UErrorCode      &status);

    /**

     * Returns the regular expression from which this pattern was compiled. This method will work

     * even if the pattern was compiled from a UText.

     *

     * Note: If the pattern was originally compiled from a UText, and that UText was modified,

     * the returned string may no longer reflect the RegexPattern object.

     * @stable ICU 2.4

     */

     virtual UnicodeString pattern() const;

    /**

     * Returns the regular expression from which this pattern was compiled. This method will work

     * even if the pattern was compiled from a UnicodeString.

     *

     * Note: This is the original input, not a clone. If the pattern was originally compiled from a

     * UText, and that UText was modified, the returned UText may no longer reflect the RegexPattern

     * object.

     *

     * @stable ICU 4.6

     */

     virtual UText *patternText(UErrorCode      &status) const;

     /**

      * Split a string into fields.  Somewhat like split() from Perl or Java.

      * Pattern matches identify delimiters that separate the input

      * into fields.  The input data between the delimiters becomes the

      * fields themselves.

      *

      * If the delimiter pattern includes capture groups, the captured text will

      * also appear in the destination array of output strings, interspersed

      * with the fields.  This is similar to Perl, but differs from Java, 

      * which ignores the presence of capture groups in the pattern.

      * 

      * Trailing empty fields will always be returned, assuming sufficient

      * destination capacity.  This differs from the default behavior for Java

      * and Perl where trailing empty fields are not returned.

      *

      * The number of strings produced by the split operation is returned.

      * This count includes the strings from capture groups in the delimiter pattern.

      * This behavior differs from Java, which ignores capture groups.

      *

      * For the best performance on split() operations,

      * <code>RegexMatcher::split</code> is preferable to this function

      *

      * @param input   The string to be split into fields.  The field delimiters

      *                match the pattern (in the "this" object)

      * @param dest    An array of UnicodeStrings to receive the results of the split.

      *                This is an array of actual UnicodeString objects, not an

      *                array of pointers to strings.  Local (stack based) arrays can

      *                work well here.

      * @param destCapacity  The number of elements in the destination array.

      *                If the number of fields found is less than destCapacity, the

      *                extra strings in the destination array are not altered.

      *                If the number of destination strings is less than the number

      *                of fields, the trailing part of the input string, including any

      *                field delimiters, is placed in the last destination string.

      * @param status  A reference to a UErrorCode to receive any errors.

      * @return        The number of fields into which the input string was split.

      * @stable ICU 2.4

      */

     virtual int32_t  split(const UnicodeString &input,

         UnicodeString    dest[],

         int32_t          destCapacity,

         UErrorCode       &status) const;

     /**

      * Split a string into fields.  Somewhat like split() from Perl or Java.

      * Pattern matches identify delimiters that separate the input

      * into fields.  The input data between the delimiters becomes the

      * fields themselves.

      *

      * If the delimiter pattern includes capture groups, the captured text will

      * also appear in the destination array of output strings, interspersed

      * with the fields.  This is similar to Perl, but differs from Java, 

      * which ignores the presence of capture groups in the pattern.

      * 

      * Trailing empty fields will always be returned, assuming sufficient

      * destination capacity.  This differs from the default behavior for Java

      * and Perl where trailing empty fields are not returned.

      *

      * The number of strings produced by the split operation is returned.

      * This count includes the strings from capture groups in the delimiter pattern.

      * This behavior differs from Java, which ignores capture groups.

      *

      *  For the best performance on split() operations,

      *  <code>RegexMatcher::split</code> is preferable to this function

      *

      * @param input   The string to be split into fields.  The field delimiters

      *                match the pattern (in the "this" object)

      * @param dest    An array of mutable UText structs to receive the results of the split.

      *                If a field is NULL, a new UText is allocated to contain the results for

      *                that field. This new UText is not guaranteed to be mutable.

      * @param destCapacity  The number of elements in the destination array.

      *                If the number of fields found is less than destCapacity, the

      *                extra strings in the destination array are not altered.

      *                If the number of destination strings is less than the number

      *                of fields, the trailing part of the input string, including any

      *                field delimiters, is placed in the last destination string.

      * @param status  A reference to a UErrorCode to receive any errors.

      * @return        The number of destination strings used.  

      *

      * @stable ICU 4.6

      */

     virtual int32_t  split(UText *input,

         UText            *dest[],

         int32_t          destCapacity,

         UErrorCode       &status) const;

     /**

      * ICU "poor man's RTTI", returns a UClassID for the actual class.

      *

      * @stable ICU 2.4

      */

     virtual UClassID getDynamicClassID() const;

     /**

      * ICU "poor man's RTTI", returns a UClassID for this class.

      *

      * @stable ICU 2.4

      */

     static UClassID U_EXPORT2 getStaticClassID();

 private:

     //

     //  Implementation Data

     //

     UText          *fPattern;      // The original pattern string.

     UnicodeString  *fPatternString; // The original pattern UncodeString if relevant

     uint32_t        fFlags;        // The flags used when compiling the pattern.

                                    //

     UVector64       *fCompiledPat; // The compiled pattern p-code.

     UnicodeString   fLiteralText;  // Any literal string data from the pattern,

                                    //   after un-escaping, for use during the match.

     UVector         *fSets;        // Any UnicodeSets referenced from the pattern.

     Regex8BitSet    *fSets8;       //      (and fast sets for latin-1 range.)

     UErrorCode      fDeferredStatus; // status if some prior error has left this

                                    //  RegexPattern in an unusable state.

     int32_t         fMinMatchLen;  // Minimum Match Length.  All matches will have length

                                    //   >= this value.  For some patterns, this calculated

                                    //   value may be less than the true shortest

                                    //   possible match.

     int32_t         fFrameSize;    // Size of a state stack frame in the

                                    //   execution engine.

     int32_t         fDataSize;     // The size of the data needed by the pattern that

                                    //   does not go on the state stack, but has just

                                    //   a single copy per matcher.

     UVector32       *fGroupMap;    // Map from capture group number to position of

                                    //   the group's variables in the matcher stack frame.

     int32_t         fMaxCaptureDigits;

     UnicodeSet     **fStaticSets;  // Ptr to static (shared) sets for predefined

                                    //   regex character classes, e.g. Word.

     Regex8BitSet   *fStaticSets8;  // Ptr to the static (shared) latin-1 only

                                    //  sets for predefined regex classes.

     int32_t         fStartType;    // Info on how a match must start.

     int32_t         fInitialStringIdx;     //

     int32_t         fInitialStringLen;

     UnicodeSet     *fInitialChars;

     UChar32         fInitialChar;

     Regex8BitSet   *fInitialChars8;

     UBool           fNeedsAltInput;

     friend class RegexCompile;

     friend class RegexMatcher;

     friend class RegexCImpl;

     //

     //  Implementation Methods

     //

     void        init();            // Common initialization, for use by constructors.

     void        zap();             // Common cleanup

 #ifdef REGEX_DEBUG

     void        dumpOp(int32_t index) const;

     friend     void U_EXPORT2 RegexPatternDump(const RegexPattern *);

 #endif

 };

 /**

  *  class RegexMatcher bundles together a regular expression pattern and

  *  input text to which the expression can be applied.  It includes methods

  *  for testing for matches, and for find and replace operations.

  *

  * <p>Class RegexMatcher is not intended to be subclassed.</p>

  *

  * @stable ICU 2.4

  */

 class U_I18N_API RegexMatcher: public UObject {

 public:

     /**

       * Construct a RegexMatcher for a regular expression.

       * This is a convenience method that avoids the need to explicitly create

       * a RegexPattern object.  Note that if several RegexMatchers need to be

       * created for the same expression, it will be more efficient to

       * separately create and cache a RegexPattern object, and use

       * its matcher() method to create the RegexMatcher objects.

       *

       *  @param regexp The Regular Expression to be compiled.

       *  @param flags  Regular expression options, such as case insensitive matching.

       *                @see UREGEX_CASE_INSENSITIVE

       *  @param status Any errors are reported by setting this UErrorCode variable.

       *  @stable ICU 2.6

       */

     RegexMatcher(const UnicodeString &regexp, uint32_t flags, UErrorCode &status);

     /**

       * Construct a RegexMatcher for a regular expression.

       * This is a convenience method that avoids the need to explicitly create

       * a RegexPattern object.  Note that if several RegexMatchers need to be

       * created for the same expression, it will be more efficient to

       * separately create and cache a RegexPattern object, and use

       * its matcher() method to create the RegexMatcher objects.

       *

       *  @param regexp The regular expression to be compiled.

       *  @param flags  Regular expression options, such as case insensitive matching.

       *                @see UREGEX_CASE_INSENSITIVE

       *  @param status Any errors are reported by setting this UErrorCode variable.

       *

       *  @stable ICU 4.6

       */

     RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);

     /**

       * Construct a RegexMatcher for a regular expression.

       * This is a convenience method that avoids the need to explicitly create

       * a RegexPattern object.  Note that if several RegexMatchers need to be

       * created for the same expression, it will be more efficient to

       * separately create and cache a RegexPattern object, and use

       * its matcher() method to create the RegexMatcher objects.

       * <p>

       * The matcher will retain a reference to the supplied input string, and all regexp

       * pattern matching operations happen directly on the original string.  It is

       * critical that the string not be altered or deleted before use by the regular

       * expression operations is complete.

       *

       *  @param regexp The Regular Expression to be compiled.

       *  @param input  The string to match.  The matcher retains a reference to the

       *                caller's string; mo copy is made.

       *  @param flags  Regular expression options, such as case insensitive matching.

       *                @see UREGEX_CASE_INSENSITIVE

       *  @param status Any errors are reported by setting this UErrorCode variable.

       *  @stable ICU 2.6

       */

     RegexMatcher(const UnicodeString &regexp, const UnicodeString &input,

         uint32_t flags, UErrorCode &status);

     /**

       * Construct a RegexMatcher for a regular expression.

       * This is a convenience method that avoids the need to explicitly create

       * a RegexPattern object.  Note that if several RegexMatchers need to be

       * created for the same expression, it will be more efficient to

       * separately create and cache a RegexPattern object, and use

       * its matcher() method to create the RegexMatcher objects.

       * <p>

       * The matcher will make a shallow clone of the supplied input text, and all regexp

       * pattern matching operations happen on this clone.  While read-only operations on

       * the supplied text are permitted, it is critical that the underlying string not be

       * altered or deleted before use by the regular expression operations is complete.

       *

       *  @param regexp The Regular Expression to be compiled.

       *  @param input  The string to match.  The matcher retains a shallow clone of the text.

       *  @param flags  Regular expression options, such as case insensitive matching.

       *                @see UREGEX_CASE_INSENSITIVE

       *  @param status Any errors are reported by setting this UErrorCode variable.

       *

       *  @stable ICU 4.6

       */

     RegexMatcher(UText *regexp, UText *input,

         uint32_t flags, UErrorCode &status);

 private:

     /**

      * Cause a compilation error if an application accidentally attempts to

      *   create a matcher with a (UChar *) string as input rather than

      *   a UnicodeString.    Avoids a dangling reference to a temporary string.

      * <p>

      * To efficiently work with UChar *strings, wrap the data in a UnicodeString

      * using one of the aliasing constructors, such as

      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>

      * or in a UText, using

      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>

      *

      */

     RegexMatcher(const UnicodeString &regexp, const UChar *input,

         uint32_t flags, UErrorCode &status);

 public:

    /**

     *   Destructor.

     *

     *  @stable ICU 2.4

     */

     virtual ~RegexMatcher();

    /**

     *   Attempts to match the entire input region against the pattern.

     *    @param   status     A reference to a UErrorCode to receive any errors.

     *    @return TRUE if there is a match

     *    @stable ICU 2.4

     */

     virtual UBool matches(UErrorCode &status);

    /**

     *   Resets the matcher, then attempts to match the input beginning 

     *   at the specified startIndex, and extending to the end of the input.

     *   The input region is reset to include the entire input string.

     *   A successful match must extend to the end of the input.

     *    @param   startIndex The input string (native) index at which to begin matching.

     *    @param   status     A reference to a UErrorCode to receive any errors.

     *    @return TRUE if there is a match

     *    @stable ICU 2.8

     */

     virtual UBool matches(int64_t startIndex, UErrorCode &status);

    /**

     *   Attempts to match the input string, starting from the beginning of the region,

     *   against the pattern.  Like the matches() method, this function 

     *   always starts at the beginning of the input region;

     *   unlike that function, it does not require that the entire region be matched.

     *

     *   <p>If the match succeeds then more information can be obtained via the <code>start()</code>,

     *     <code>end()</code>, and <code>group()</code> functions.</p>

     *

     *    @param   status     A reference to a UErrorCode to receive any errors.

     *    @return  TRUE if there is a match at the start of the input string.

     *    @stable ICU 2.4

     */

     virtual UBool lookingAt(UErrorCode &status);

   /**

     *   Attempts to match the input string, starting from the specified index, against the pattern.

     *   The match may be of any length, and is not required to extend to the end

     *   of the input string.  Contrast with match().

     *

     *   <p>If the match succeeds then more information can be obtained via the <code>start()</code>,

     *     <code>end()</code>, and <code>group()</code> functions.</p>

     *

     *    @param   startIndex The input string (native) index at which to begin matching.

     *    @param   status     A reference to a UErrorCode to receive any errors.

     *    @return  TRUE if there is a match.

     *    @stable ICU 2.8

     */

     virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);

    /**

     *  Find the next pattern match in the input string.

     *  The find begins searching the input at the location following the end of

     *  the previous match, or at the start of the string if there is no previous match.

     *  If a match is found, <code>start(), end()</code> and <code>group()</code>

     *  will provide more information regarding the match.

     *  <p>Note that if the input string is changed by the application,

     *     use find(startPos, status) instead of find(), because the saved starting

     *     position may not be valid with the altered input string.</p>

     *  @return  TRUE if a match is found.

     *  @stable ICU 2.4

     */

     virtual UBool find();

    /**

     *   Resets this RegexMatcher and then attempts to find the next substring of the

     *   input string that matches the pattern, starting at the specified index.

     *

     *   @param   start     The (native) index in the input string to begin the search.

     *   @param   status    A reference to a UErrorCode to receive any errors.

     *   @return  TRUE if a match is found.

     *   @stable ICU 2.4

     */

     virtual UBool find(int64_t start, UErrorCode &status);

    /**

     *   Returns a string containing the text matched by the previous match.

     *   If the pattern can match an empty string, an empty string may be returned.

     *   @param   status      A reference to a UErrorCode to receive any errors.

     *                        Possible errors are  U_REGEX_INVALID_STATE if no match

     *                        has been attempted or the last match failed.

     *   @return  a string containing the matched input text.

     *   @stable ICU 2.4

     */

     virtual UnicodeString group(UErrorCode &status) const;

    /**

     *    Returns a string containing the text captured by the given group

     *    during the previous match operation.  Group(0) is the entire match.

     *

     *    @param groupNum the capture group number

     *    @param   status     A reference to a UErrorCode to receive any errors.

     *                        Possible errors are  U_REGEX_INVALID_STATE if no match

     *                        has been attempted or the last match failed and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.

     *    @return the captured text

     *    @stable ICU 2.4

     */

     virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;

    /**

     *   Returns the number of capturing groups in this matcher's pattern.

     *   @return the number of capture groups

     *   @stable ICU 2.4

     */

     virtual int32_t groupCount() const;

    /**

     *   Returns a shallow clone of the entire live input string with the UText current native index

     *   set to the beginning of the requested group.

     *

     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText

     *   @param   group_len   A reference to receive the length of the desired capture group

     *   @param   status      A reference to a UErrorCode to receive any errors.

     *                        Possible errors are  U_REGEX_INVALID_STATE if no match

     *                        has been attempted or the last match failed and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.

     *   @return dest if non-NULL, a shallow copy of the input text otherwise

     *

     *   @stable ICU 4.6

     */

     virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const; 

    /**

     *   Returns a shallow clone of the entire live input string with the UText current native index

     *   set to the beginning of the requested group.

     *

     *   @param   groupNum   The capture group number.

     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText.

     *   @param   group_len   A reference to receive the length of the desired capture group

     *   @param   status      A reference to a UErrorCode to receive any errors.

     *                        Possible errors are  U_REGEX_INVALID_STATE if no match

     *                        has been attempted or the last match failed and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.

     *   @return dest if non-NULL, a shallow copy of the input text otherwise

     *

     *   @stable ICU 4.6

     */

     virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;

    /**

     *   Returns a string containing the text captured by the given group

     *   during the previous match operation.  Group(0) is the entire match.

     *

     *   @param   groupNum    the capture group number

     *   @param   dest        A mutable UText in which the matching text is placed.

     *                        If NULL, a new UText will be created (which may not be mutable).

     *   @param   status      A reference to a UErrorCode to receive any errors.

     *                        Possible errors are  U_REGEX_INVALID_STATE if no match

     *                        has been attempted or the last match failed.

     *   @return  A string containing the matched input text. If a pre-allocated UText

     *            was provided, it will always be used and returned.

     *

     *   @internal ICU 4.4 technology preview

     */

     virtual UText *group(int32_t groupNum, UText *dest, UErrorCode &status) const;

    /**

     *   Returns the index in the input string of the start of the text matched

     *   during the previous match operation.

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              The (native) position in the input string of the start of the last match.

     *    @stable ICU 2.4

     */

     virtual int32_t start(UErrorCode &status) const;

    /**

     *   Returns the index in the input string of the start of the text matched

     *   during the previous match operation.

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              The (native) position in the input string of the start of the last match.

     *   @stable ICU 4.6

     */

     virtual int64_t start64(UErrorCode &status) const;

    /**

     *   Returns the index in the input string of the start of the text matched by the

     *    specified capture group during the previous match operation.  Return -1 if

     *    the capture group exists in the pattern, but was not part of the last match.

     *

     *    @param  group       the capture group number

     *    @param  status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed, and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number

     *    @return the (native) start position of substring matched by the specified group.

     *    @stable ICU 2.4

     */

     virtual int32_t start(int32_t group, UErrorCode &status) const;

    /**

     *   Returns the index in the input string of the start of the text matched by the

     *    specified capture group during the previous match operation.  Return -1 if

     *    the capture group exists in the pattern, but was not part of the last match.

     *

     *    @param  group       the capture group number.

     *    @param  status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed, and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.

     *    @return the (native) start position of substring matched by the specified group.

     *    @stable ICU 4.6

     */

     virtual int64_t start64(int32_t group, UErrorCode &status) const;

    /**

     *    Returns the index in the input string of the first character following the

     *    text matched during the previous match operation.

     *

     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed.

     *    @return the index of the last character matched, plus one.

     *                        The index value returned is a native index, corresponding to

     *                        code units for the underlying encoding type, for example,

     *                        a byte index for UTF-8.

     *   @stable ICU 2.4

     */

     virtual int32_t end(UErrorCode &status) const;

    /**

     *    Returns the index in the input string of the first character following the

     *    text matched during the previous match operation.

     *

     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed.

     *    @return the index of the last character matched, plus one.

     *                        The index value returned is a native index, corresponding to

     *                        code units for the underlying encoding type, for example,

     *                        a byte index for UTF-8.

     *   @stable ICU 4.6

     */

     virtual int64_t end64(UErrorCode &status) const;

    /**

     *    Returns the index in the input string of the character following the

     *    text matched by the specified capture group during the previous match operation.

     *

     *    @param group  the capture group number

     *    @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number

     *    @return  the index of the first character following the text

     *              captured by the specified group during the previous match operation.

     *              Return -1 if the capture group exists in the pattern but was not part of the match.

     *              The index value returned is a native index, corresponding to

     *              code units for the underlying encoding type, for example,

     *              a byte index for UTF8.

     *    @stable ICU 2.4

     */

     virtual int32_t end(int32_t group, UErrorCode &status) const;

    /**

     *    Returns the index in the input string of the character following the

     *    text matched by the specified capture group during the previous match operation.

     *

     *    @param group  the capture group number

     *    @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed and

     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number

     *    @return  the index of the first character following the text

     *              captured by the specified group during the previous match operation.

     *              Return -1 if the capture group exists in the pattern but was not part of the match.

     *              The index value returned is a native index, corresponding to

     *              code units for the underlying encoding type, for example,

     *              a byte index for UTF8.

     *   @stable ICU 4.6

     */

     virtual int64_t end64(int32_t group, UErrorCode &status) const;

    /**

     *   Resets this matcher.  The effect is to remove any memory of previous matches,

     *       and to cause subsequent find() operations to begin at the beginning of

     *       the input string.

     *

     *   @return this RegexMatcher.

     *   @stable ICU 2.4

     */

     virtual RegexMatcher &reset();

    /**

     *   Resets this matcher, and set the current input position.

     *   The effect is to remove any memory of previous matches,

     *       and to cause subsequent find() operations to begin at

     *       the specified (native) position in the input string.

     * <p>

     *   The matcher's region is reset to its default, which is the entire

     *   input string.

     * <p>

     *   An alternative to this function is to set a match region

     *   beginning at the desired index.

     *

     *   @return this RegexMatcher.

     *   @stable ICU 2.8

     */

     virtual RegexMatcher &reset(int64_t index, UErrorCode &status);

    /**

     *   Resets this matcher with a new input string.  This allows instances of RegexMatcher

     *     to be reused, which is more efficient than creating a new RegexMatcher for

     *     each input string to be processed.

     *   @param input The new string on which subsequent pattern matches will operate.

     *                The matcher retains a reference to the callers string, and operates

     *                directly on that.  Ownership of the string remains with the caller.

     *                Because no copy of the string is made, it is essential that the

     *                caller not delete the string until after regexp operations on it

     *                are done.

     *                Note that while a reset on the matcher with an input string that is then

     *                modified across/during matcher operations may be supported currently for UnicodeString,

     *                this was not originally intended behavior, and support for this is not guaranteed

     *                in upcoming versions of ICU.

     *   @return this RegexMatcher.

     *   @stable ICU 2.4

     */

     virtual RegexMatcher &reset(const UnicodeString &input);

    /**

     *   Resets this matcher with a new input string.  This allows instances of RegexMatcher

     *     to be reused, which is more efficient than creating a new RegexMatcher for

     *     each input string to be processed.

     *   @param input The new string on which subsequent pattern matches will operate.

     *                The matcher makes a shallow clone of the given text; ownership of the

     *                original string remains with the caller. Because no deep copy of the

     *                text is made, it is essential that the caller not modify the string

     *                until after regexp operations on it are done.

     *   @return this RegexMatcher.

     *

     *   @stable ICU 4.6

     */

     virtual RegexMatcher &reset(UText *input);

   /**

     *  Set the subject text string upon which the regular expression is looking for matches

     *  without changing any other aspect of the matching state.

     *  The new and previous text strings must have the same content.

     *

     *  This function is intended for use in environments where ICU is operating on 

     *  strings that may move around in memory.  It provides a mechanism for notifying

     *  ICU that the string has been relocated, and providing a new UText to access the

     *  string in its new position.

     *

     *  Note that the regular expression implementation never copies the underlying text

     *  of a string being matched, but always operates directly on the original text 

     *  provided by the user. Refreshing simply drops the references to the old text 

     *  and replaces them with references to the new.

     *

     *  Caution:  this function is normally used only by very specialized,

     *  system-level code.  One example use case is with garbage collection that moves

     *  the text in memory.

     *

     * @param input      The new (moved) text string.

     * @param status     Receives errors detected by this function.

     *

     * @stable ICU 4.8 

     */

     virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);

 private:

     /**

      * Cause a compilation error if an application accidentally attempts to

      *   reset a matcher with a (UChar *) string as input rather than

      *   a UnicodeString.    Avoids a dangling reference to a temporary string.

      * <p>

      * To efficiently work with UChar *strings, wrap the data in a UnicodeString

      * using one of the aliasing constructors, such as

      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>

      * or in a UText, using

      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>

      *

      */

     RegexMatcher &reset(const UChar *input);

 public:

    /**

     *   Returns the input string being matched.  Ownership of the string belongs to

     *   the matcher; it should not be altered or deleted. This method will work even if the input

     *   was originally supplied as a UText.

     *   @return the input string

     *   @stable ICU 2.4

     */

     virtual const UnicodeString &input() const;

    /**

     *   Returns the input string being matched.  This is the live input text; it should not be

     *   altered or deleted. This method will work even if the input was originally supplied as

     *   a UnicodeString.

     *   @return the input text

     *

     *   @stable ICU 4.6

     */

     virtual UText *inputText() const;

    /**

     *   Returns the input string being matched, either by copying it into the provided

     *   UText parameter or by returning a shallow clone of the live input. Note that copying

     *   the entire input may cause significant performance and memory issues.

     *   @param dest The UText into which the input should be copied, or NULL to create a new UText

     *   @param status error code

     *   @return dest if non-NULL, a shallow copy of the input text otherwise

     *

     *   @stable ICU 4.6

     */

     virtual UText *getInput(UText *dest, UErrorCode &status) const;

    /** Sets the limits of this matcher's region.

      * The region is the part of the input string that will be searched to find a match.

      * Invoking this method resets the matcher, and then sets the region to start

      * at the index specified by the start parameter and end at the index specified

      * by the end parameter.

      *

      * Depending on the transparency and anchoring being used (see useTransparentBounds

      * and useAnchoringBounds), certain constructs such as anchors may behave differently

      * at or around the boundaries of the region

      *

      * The function will fail if start is greater than limit, or if either index

      *  is less than zero or greater than the length of the string being matched.

      *

      * @param start  The (native) index to begin searches at.

      * @param limit  The index to end searches at (exclusive).

      * @param status A reference to a UErrorCode to receive any errors.

      * @stable ICU 4.0

      */

      virtual RegexMatcher &region(int64_t start, int64_t limit, UErrorCode &status);

    /** 

      * Identical to region(start, limit, status) but also allows a start position without

      *  resetting the region state.

      * @param regionStart The region start

      * @param regionLimit the limit of the region

      * @param startIndex  The (native) index within the region bounds at which to begin searches.

      * @param status A reference to a UErrorCode to receive any errors.

      *                If startIndex is not within the specified region bounds, 

      *                U_INDEX_OUTOFBOUNDS_ERROR is returned.

      * @stable ICU 4.6

      */

      virtual RegexMatcher &region(int64_t regionStart, int64_t regionLimit, int64_t startIndex, UErrorCode &status);

    /**

      * Reports the start index of this matcher's region. The searches this matcher

      * conducts are limited to finding matches within regionStart (inclusive) and

      * regionEnd (exclusive).

      *

      * @return The starting (native) index of this matcher's region.

      * @stable ICU 4.0

      */

      virtual int32_t regionStart() const;

    /**

      * Reports the start index of this matcher's region. The searches this matcher

      * conducts are limited to finding matches within regionStart (inclusive) and

      * regionEnd (exclusive).

      *

      * @return The starting (native) index of this matcher's region.

      * @stable ICU 4.6

      */

      virtual int64_t regionStart64() const;

     /**

       * Reports the end (limit) index (exclusive) of this matcher's region. The searches

       * this matcher conducts are limited to finding matches within regionStart

       * (inclusive) and regionEnd (exclusive).

       *

       * @return The ending point (native) of this matcher's region.

       * @stable ICU 4.0

       */

       virtual int32_t regionEnd() const;

    /**

      * Reports the end (limit) index (exclusive) of this matcher's region. The searches

      * this matcher conducts are limited to finding matches within regionStart

      * (inclusive) and regionEnd (exclusive).

      *

      * @return The ending point (native) of this matcher's region.

      * @stable ICU 4.6

      */

       virtual int64_t regionEnd64() const;

     /**

       * Queries the transparency of region bounds for this matcher.

       * See useTransparentBounds for a description of transparent and opaque bounds.

       * By default, a matcher uses opaque region boundaries.

       *

       * @return TRUE if this matcher is using opaque bounds, false if it is not.

       * @stable ICU 4.0

       */

       virtual UBool hasTransparentBounds() const;

     /**

       * Sets the transparency of region bounds for this matcher.

       * Invoking this function with an argument of true will set this matcher to use transparent bounds.

       * If the boolean argument is false, then opaque bounds will be used.

       *

       * Using transparent bounds, the boundaries of this matcher's region are transparent

       * to lookahead, lookbehind, and boundary matching constructs. Those constructs can

       * see text beyond the boundaries of the region while checking for a match.

       *

       * With opaque bounds, no text outside of the matcher's region is visible to lookahead,

       * lookbehind, and boundary matching constructs.

       *

       * By default, a matcher uses opaque bounds.

       *

       * @param   b TRUE for transparent bounds; FALSE for opaque bounds

       * @return  This Matcher;

       * @stable ICU 4.0

       **/

       virtual RegexMatcher &useTransparentBounds(UBool b);

     /**

       * Return true if this matcher is using anchoring bounds.

       * By default, matchers use anchoring region bounds.

       *

       * @return TRUE if this matcher is using anchoring bounds.

       * @stable ICU 4.0

       */    

       virtual UBool hasAnchoringBounds() const;

     /**

       * Set whether this matcher is using Anchoring Bounds for its region.

       * With anchoring bounds, pattern anchors such as ^ and $ will match at the start

       * and end of the region.  Without Anchoring Bounds, anchors will only match at

       * the positions they would in the complete text.

       *

       * Anchoring Bounds are the default for regions.

       *

       * @param b TRUE if to enable anchoring bounds; FALSE to disable them.

       * @return  This Matcher

       * @stable ICU 4.0

       */

       virtual RegexMatcher &useAnchoringBounds(UBool b);

     /**

       * Return TRUE if the most recent matching operation attempted to access

       *  additional input beyond the available input text.

       *  In this case, additional input text could change the results of the match.

       *

       *  hitEnd() is defined for both successful and unsuccessful matches.

       *  In either case hitEnd() will return TRUE if if the end of the text was

       *  reached at any point during the matching process.

       *

       *  @return  TRUE if the most recent match hit the end of input

       *  @stable ICU 4.0

       */

       virtual UBool hitEnd() const;

     /**

       * Return TRUE the most recent match succeeded and additional input could cause

       * it to fail. If this method returns false and a match was found, then more input

       * might change the match but the match won't be lost. If a match was not found,

       * then requireEnd has no meaning.

       *

       * @return TRUE if more input could cause the most recent match to no longer match.

       * @stable ICU 4.0

       */

       virtual UBool requireEnd() const;

    /**

     *    Returns the pattern that is interpreted by this matcher.

     *    @return  the RegexPattern for this RegexMatcher

     *    @stable ICU 2.4

     */

     virtual const RegexPattern &pattern() const;

    /**

     *    Replaces every substring of the input that matches the pattern

     *    with the given replacement string.  This is a convenience function that

     *    provides a complete find-and-replace-all operation.

     *

     *    This method first resets this matcher. It then scans the input string

     *    looking for matches of the pattern. Input that is not part of any

     *    match is left unchanged; each match is replaced in the result by the

     *    replacement string. The replacement string may contain references to

     *    capture groups.

     *

     *    @param   replacement a string containing the replacement text.

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              a string containing the results of the find and replace.

     *    @stable ICU 2.4

     */

     virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);

    /**

     *    Replaces every substring of the input that matches the pattern

     *    with the given replacement string.  This is a convenience function that

     *    provides a complete find-and-replace-all operation.

     *

     *    This method first resets this matcher. It then scans the input string

     *    looking for matches of the pattern. Input that is not part of any

     *    match is left unchanged; each match is replaced in the result by the

     *    replacement string. The replacement string may contain references to

     *    capture groups.

     *

     *    @param   replacement a string containing the replacement text.

     *    @param   dest        a mutable UText in which the results are placed.

     *                          If NULL, a new UText will be created (which may not be mutable).

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              a string containing the results of the find and replace.

     *                          If a pre-allocated UText was provided, it will always be used and returned.

     *

     *    @stable ICU 4.6

     */

     virtual UText *replaceAll(UText *replacement, UText *dest, UErrorCode &status);

    /**

     * Replaces the first substring of the input that matches

     * the pattern with the replacement string.   This is a convenience

     * function that provides a complete find-and-replace operation.

     *

     * <p>This function first resets this RegexMatcher. It then scans the input string

     * looking for a match of the pattern. Input that is not part

     * of the match is appended directly to the result string; the match is replaced

     * in the result by the replacement string. The replacement string may contain

     * references to captured groups.</p>

     *

     * <p>The state of the matcher (the position at which a subsequent find()

     *    would begin) after completing a replaceFirst() is not specified.  The

     *    RegexMatcher should be reset before doing additional find() operations.</p>

     *

     *    @param   replacement a string containing the replacement text.

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              a string containing the results of the find and replace.

     *    @stable ICU 2.4

     */

     virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status);

    /**

     * Replaces the first substring of the input that matches

     * the pattern with the replacement string.   This is a convenience

     * function that provides a complete find-and-replace operation.

     *

     * <p>This function first resets this RegexMatcher. It then scans the input string

     * looking for a match of the pattern. Input that is not part

     * of the match is appended directly to the result string; the match is replaced

     * in the result by the replacement string. The replacement string may contain

     * references to captured groups.</p>

     *

     * <p>The state of the matcher (the position at which a subsequent find()

     *    would begin) after completing a replaceFirst() is not specified.  The

     *    RegexMatcher should be reset before doing additional find() operations.</p>

     *

     *    @param   replacement a string containing the replacement text.

     *    @param   dest        a mutable UText in which the results are placed.

     *                          If NULL, a new UText will be created (which may not be mutable).

     *    @param   status      a reference to a UErrorCode to receive any errors.

     *    @return              a string containing the results of the find and replace.

     *                          If a pre-allocated UText was provided, it will always be used and returned.

     *

     *    @stable ICU 4.6

     */

     virtual UText *replaceFirst(UText *replacement, UText *dest, UErrorCode &status);

    /**

     *   Implements a replace operation intended to be used as part of an

     *   incremental find-and-replace.

     *

     *   <p>The input string, starting from the end of the previous replacement and ending at

     *   the start of the current match, is appended to the destination string.  Then the

     *   replacement string is appended to the output string,

     *   including handling any substitutions of captured text.</p>

     *

     *   <p>For simple, prepackaged, non-incremental find-and-replace

     *   operations, see replaceFirst() or replaceAll().</p>

     *

     *   @param   dest        A UnicodeString to which the results of the find-and-replace are appended.

     *   @param   replacement A UnicodeString that provides the text to be substituted for

     *                        the input text that matched the regexp pattern.  The replacement

     *                        text may contain references to captured text from the

     *                        input.

     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR

     *                        if the replacement text specifies a capture group that

     *                        does not exist in the pattern.

     *

     *   @return  this  RegexMatcher

     *   @stable ICU 2.4

     *

     */

     virtual RegexMatcher &appendReplacement(UnicodeString &dest,

         const UnicodeString &replacement, UErrorCode &status);

    /**

     *   Implements a replace operation intended to be used as part of an

     *   incremental find-and-replace.

     *

     *   <p>The input string, starting from the end of the previous replacement and ending at

     *   the start of the current match, is appended to the destination string.  Then the

     *   replacement string is appended to the output string,

     *   including handling any substitutions of captured text.</p>

     *

     *   <p>For simple, prepackaged, non-incremental find-and-replace

     *   operations, see replaceFirst() or replaceAll().</p>

     *

     *   @param   dest        A mutable UText to which the results of the find-and-replace are appended.

     *                         Must not be NULL.

     *   @param   replacement A UText that provides the text to be substituted for

     *                        the input text that matched the regexp pattern.  The replacement

     *                        text may contain references to captured text from the input.

     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible

     *                        errors are  U_REGEX_INVALID_STATE if no match has been

     *                        attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR

     *                        if the replacement text specifies a capture group that

     *                        does not exist in the pattern.

     *

     *   @return  this  RegexMatcher

     *

     *   @stable ICU 4.6

     */

     virtual RegexMatcher &appendReplacement(UText *dest,

         UText *replacement, UErrorCode &status);

    /**

     * As the final step in a find-and-replace operation, append the remainder

     * of the input string, starting at the position following the last appendReplacement(),

     * to the destination string. <code>appendTail()</code> is intended to be invoked after one

     * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.

     *

     *  @param dest A UnicodeString to which the results of the find-and-replace are appended.

     *  @return  the destination string.

     *  @stable ICU 2.4

     */

     virtual UnicodeString &appendTail(UnicodeString &dest);

    /**

     * As the final step in a find-and-replace operation, append the remainder

     * of the input string, starting at the position following the last appendReplacement(),

     * to the destination string. <code>appendTail()</code> is intended to be invoked after one

     * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.

     *

     *  @param dest A mutable UText to which the results of the find-and-replace are appended.

     *               Must not be NULL.

     *  @param status error cod

     *  @return  the destination string.

     *

     *  @stable ICU 4.6

     */

     virtual UText *appendTail(UText *dest, UErrorCode &status);

     /**

      * Split a string into fields.  Somewhat like split() from Perl.

      * The pattern matches identify delimiters that separate the input

      *  into fields.  The input data between the matches becomes the

      *  fields themselves.

      *

      * @param input   The string to be split into fields.  The field delimiters

      *                match the pattern (in the "this" object).  This matcher

      *                will be reset to this input string.

      * @param dest    An array of UnicodeStrings to receive the results of the split.

      *                This is an array of actual UnicodeString objects, not an

      *                array of pointers to strings.  Local (stack based) arrays can

      *                work well here.

      * @param destCapacity  The number of elements in the destination array.

      *                If the number of fields found is less than destCapacity, the

      *                extra strings in the destination array are not altered.

      *                If the number of destination strings is less than the number

      *                of fields, the trailing part of the input string, including any

      *                field delimiters, is placed in the last destination string.

      * @param status  A reference to a UErrorCode to receive any errors.

      * @return        The number of fields into which the input string was split.

      * @stable ICU 2.6

      */

     virtual int32_t  split(const UnicodeString &input,

         UnicodeString    dest[],

         int32_t          destCapacity,

         UErrorCode       &status);

     /**

      * Split a string into fields.  Somewhat like split() from Perl.

      * The pattern matches identify delimiters that separate the input

      *  into fields.  The input data between the matches becomes the

      *  fields themselves.

      *

      * @param input   The string to be split into fields.  The field delimiters

      *                match the pattern (in the "this" object).  This matcher

      *                will be reset to this input string.

      * @param dest    An array of mutable UText structs to receive the results of the split.

      *                If a field is NULL, a new UText is allocated to contain the results for

      *                that field. This new UText is not guaranteed to be mutable.

      * @param destCapacity  The number of elements in the destination array.

      *                If the number of fields found is less than destCapacity, the

      *                extra strings in the destination array are not altered.

      *                If the number of destination strings is less than the number

      *                of fields, the trailing part of the input string, including any

      *                field delimiters, is placed in the last destination string.

      * @param status  A reference to a UErrorCode to receive any errors.

      * @return        The number of fields into which the input string was split.

      *

      * @stable ICU 4.6

      */

     virtual int32_t  split(UText *input,

         UText           *dest[],

         int32_t          destCapacity,

         UErrorCode       &status);

   /**

     *   Set a processing time limit for match operations with this Matcher.

     *  

     *   Some patterns, when matching certain strings, can run in exponential time.

     *   For practical purposes, the match operation may appear to be in an

     *   infinite loop.

     *   When a limit is set a match operation will fail with an error if the

     *   limit is exceeded.

     *   <p>

     *   The units of the limit are steps of the match engine.

     *   Correspondence with actual processor time will depend on the speed

     *   of the processor and the details of the specific pattern, but will

     *   typically be on the order of milliseconds.

     *   <p>

     *   By default, the matching time is not limited.

     *   <p>

     *

     *   @param   limit       The limit value, or 0 for no limit.

     *   @param   status      A reference to a UErrorCode to receive any errors.

     *   @stable ICU 4.0

     */

     virtual void setTimeLimit(int32_t limit, UErrorCode &status);

   /**

     * Get the time limit, if any, for match operations made with this Matcher.

     *

     *   @return the maximum allowed time for a match, in units of processing steps.

     *   @stable ICU 4.0

     */

     virtual int32_t getTimeLimit() const;

   /**

     *  Set the amount of heap storage available for use by the match backtracking stack.

     *  The matcher is also reset, discarding any results from previous matches.

     *  <p>

     *  ICU uses a backtracking regular expression engine, with the backtrack stack

     *  maintained on the heap.  This function sets the limit to the amount of memory

     *  that can be used  for this purpose.  A backtracking stack overflow will

     *  result in an error from the match operation that caused it.

     *  <p>

     *  A limit is desirable because a malicious or poorly designed pattern can use

     *  excessive memory, potentially crashing the process.  A limit is enabled

     *  by default.

     *  <p>

     *  @param limit  The maximum size, in bytes, of the matching backtrack stack.

     *                A value of zero means no limit.

     *                The limit must be greater or equal to zero.

     *

     *  @param status   A reference to a UErrorCode to receive any errors.

     *

     *  @stable ICU 4.0

     */

     virtual void setStackLimit(int32_t  limit, UErrorCode &status);

   /**

     *  Get the size of the heap storage available for use by the back tracking stack.

     *

     *  @return  the maximum backtracking stack size, in bytes, or zero if the

     *           stack size is unlimited.

     *  @stable ICU 4.0

     */

     virtual int32_t  getStackLimit() const;

   /**

     * Set a callback function for use with this Matcher.

     * During matching operations the function will be called periodically,

     * giving the application the opportunity to terminate a long-running

     * match.

     *

     *    @param   callback    A pointer to the user-supplied callback function.

     *    @param   context     User context pointer.  The value supplied at the

     *                         time the callback function is set will be saved

     *                         and passed to the callback each time that it is called.

     *    @param   status      A reference to a UErrorCode to receive any errors.

     *  @stable ICU 4.0

     */

     virtual void setMatchCallback(URegexMatchCallback     *callback,

                                   const void              *context,

                                   UErrorCode              &status);

   /**

     *  Get the callback function for this URegularExpression.

     *

     *    @param   callback    Out parameter, receives a pointer to the user-supplied 

     *                         callback function.

     *    @param   context     Out parameter, receives the user context pointer that

     *                         was set when uregex_setMatchCallback() was called.

     *    @param   status      A reference to a UErrorCode to receive any errors.

     *    @stable ICU 4.0

     */

     virtual void getMatchCallback(URegexMatchCallback     *&callback,

                                   const void              *&context,

                                   UErrorCode              &status);

   /**

     * Set a progress callback function for use with find operations on this Matcher.

     * During find operations, the callback will be invoked after each return from a

     * match attempt, giving the application the opportunity to terminate a long-running

     * find operation.

     *

     *    @param   callback    A pointer to the user-supplied callback function.

     *    @param   context     User context pointer.  The value supplied at the

     *                         time the callback function is set will be saved

     *                         and passed to the callback each time that it is called.

     *    @param   status      A reference to a UErrorCode to receive any errors.

     *    @stable ICU 4.6

     */

     virtual void setFindProgressCallback(URegexFindProgressCallback      *callback,

                                               const void                              *context,

                                               UErrorCode                              &status);

   /**

     *  Get the find progress callback function for this URegularExpression.

     *

     *    @param   callback    Out parameter, receives a pointer to the user-supplied 

     *                         callback function.

     *    @param   context     Out parameter, receives the user context pointer that

     *                         was set when uregex_setFindProgressCallback() was called.

     *    @param   status      A reference to a UErrorCode to receive any errors.

     *    @stable ICU 4.6

     */

     virtual void getFindProgressCallback(URegexFindProgressCallback      *&callback,

                                               const void                      *&context,

                                               UErrorCode                      &status);

 #ifndef U_HIDE_INTERNAL_API

    /**

      *   setTrace   Debug function, enable/disable tracing of the matching engine.

      *              For internal ICU development use only.  DO NO USE!!!!

      *   @internal

      */

     void setTrace(UBool state);

 #endif  /* U_HIDE_INTERNAL_API */

     /**

     * ICU "poor man's RTTI", returns a UClassID for this class.

     *

     * @stable ICU 2.2

     */

     static UClassID U_EXPORT2 getStaticClassID();

     /**

      * ICU "poor man's RTTI", returns a UClassID for the actual class.

      *

      * @stable ICU 2.2

      */

     virtual UClassID getDynamicClassID() const;

 private:

     // Constructors and other object boilerplate are private.

     // Instances of RegexMatcher can not be assigned, copied, cloned, etc.

     RegexMatcher();                  // default constructor not implemented

     RegexMatcher(const RegexPattern *pat);

     RegexMatcher(const RegexMatcher &other);

     RegexMatcher &operator =(const RegexMatcher &rhs);

     void init(UErrorCode &status);                      // Common initialization

     void init2(UText *t, UErrorCode &e);  // Common initialization, part 2.

     friend class RegexPattern;

     friend class RegexCImpl;

 public:

 #ifndef U_HIDE_INTERNAL_API

     /** @internal  */

     void resetPreserveRegion();  // Reset matcher state, but preserve any region.

 #endif  /* U_HIDE_INTERNAL_API */

 private:

     //

     //  MatchAt   This is the internal interface to the match engine itself.

     //            Match status comes back in matcher member variables.

     //

     void                 MatchAt(int64_t startIdx, UBool toEnd, UErrorCode &status);

     inline void          backTrack(int64_t &inputIdx, int32_t &patIdx);

     UBool                isWordBoundary(int64_t pos);         // perform Perl-like  \b test

     UBool                isUWordBoundary(int64_t pos);        // perform RBBI based \b test

     REStackFrame        *resetStack();

     inline REStackFrame *StateSave(REStackFrame *fp, int64_t savePatIdx, UErrorCode &status);

     void                 IncrementTime(UErrorCode &status);

     UBool                ReportFindProgress(int64_t matchIndex, UErrorCode &status);

     int64_t              appendGroup(int32_t groupNum, UText *dest, UErrorCode &status) const;

     UBool                findUsingChunk();

     void                 MatchChunkAt(int32_t startIdx, UBool toEnd, UErrorCode &status);

     UBool                isChunkWordBoundary(int32_t pos);

     const RegexPattern  *fPattern;

     RegexPattern        *fPatternOwned;    // Non-NULL if this matcher owns the pattern, and

                                            //   should delete it when through.

     const UnicodeString *fInput;           // The string being matched. Only used for input()

     UText               *fInputText;       // The text being matched. Is never NULL.

     UText               *fAltInputText;    // A shallow copy of the text being matched.

                                            //   Only created if the pattern contains backreferences.

     int64_t              fInputLength;     // Full length of the input text.

     int32_t              fFrameSize;       // The size of a frame in the backtrack stack.

     int64_t              fRegionStart;     // Start of the input region, default = 0.

     int64_t              fRegionLimit;     // End of input region, default to input.length.

     int64_t              fAnchorStart;     // Region bounds for anchoring operations (^ or $).

     int64_t              fAnchorLimit;     //   See useAnchoringBounds

     int64_t              fLookStart;       // Region bounds for look-ahead/behind and

     int64_t              fLookLimit;       //   and other boundary tests.  See

                                            //   useTransparentBounds

     int64_t              fActiveStart;     // Currently active bounds for matching.

     int64_t              fActiveLimit;     //   Usually is the same as region, but

                                            //   is changed to fLookStart/Limit when

                                            //   entering look around regions.

     UBool                fTransparentBounds;  // True if using transparent bounds.

     UBool                fAnchoringBounds; // True if using anchoring bounds.

     UBool                fMatch;           // True if the last attempted match was successful.

     int64_t              fMatchStart;      // Position of the start of the most recent match

     int64_t              fMatchEnd;        // First position after the end of the most recent match

                                            //   Zero if no previous match, even when a region

                                            //   is active.

     int64_t              fLastMatchEnd;    // First position after the end of the previous match,

                                            //   or -1 if there was no previous match.

     int64_t              fAppendPosition;  // First position after the end of the previous

                                            //   appendReplacement().  As described by the

                                            //   JavaDoc for Java Matcher, where it is called 

                                            //   "append position"

     UBool                fHitEnd;          // True if the last match touched the end of input.

     UBool                fRequireEnd;      // True if the last match required end-of-input

                                            //    (matched $ or Z)

     UVector64           *fStack;

     REStackFrame        *fFrame;           // After finding a match, the last active stack frame,

                                            //   which will contain the capture group results.

                                            //   NOT valid while match engine is running.

     int64_t             *fData;            // Data area for use by the compiled pattern.

     int64_t             fSmallData[8];     //   Use this for data if it's enough.

     int32_t             fTimeLimit;        // Max time (in arbitrary steps) to let the

                                            //   match engine run.  Zero for unlimited.

     int32_t             fTime;             // Match time, accumulates while matching.

     int32_t             fTickCounter;      // Low bits counter for time.  Counts down StateSaves.

                                            //   Kept separately from fTime to keep as much

                                            //   code as possible out of the inline

                                            //   StateSave function.

     int32_t             fStackLimit;       // Maximum memory size to use for the backtrack

                                            //   stack, in bytes.  Zero for unlimited.

     URegexMatchCallback *fCallbackFn;       // Pointer to match progress callback funct.

                                            //   NULL if there is no callback.

     const void         *fCallbackContext;  // User Context ptr for callback function.

     URegexFindProgressCallback  *fFindProgressCallbackFn;  // Pointer to match progress callback funct.

                                                            //   NULL if there is no callback.

     const void         *fFindProgressCallbackContext;      // User Context ptr for callback function.

     UBool               fInputUniStrMaybeMutable;  // Set when fInputText wraps a UnicodeString that may be mutable - compatibility.

     UBool               fTraceDebug;       // Set true for debug tracing of match engine.

     UErrorCode          fDeferredStatus;   // Save error state that cannot be immediately

                                            //   reported, or that permanently disables this matcher.

     RuleBasedBreakIterator  *fWordBreakItr;

 };

 U_NAMESPACE_END

 #endif  // UCONFIG_NO_REGULAR_EXPRESSIONS

 #endif