• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 **********************************************************************
5 *   Copyright (C) 2002-2016, International Business Machines
6 *   Corporation and others.  All Rights Reserved.
7 **********************************************************************
8 *   file name:  regex.h
9 *   encoding:   US-ASCII
10 *   indentation:4
11 *
12 *   created on: 2002oct22
13 *   created by: Andy Heninger
14 *
15 *   ICU Regular Expressions, API for C++
16 */
17 
18 #ifndef REGEX_H
19 #define REGEX_H
20 
21 //#define REGEX_DEBUG
22 
23 /**
24  * \file
25  * \brief  C++ API:  Regular Expressions
26  *
27  * <h2>Regular Expression API</h2>
28  *
29  * <p>The ICU API for processing regular expressions consists of two classes,
30  *  <code>RegexPattern</code> and <code>RegexMatcher</code>.
31  *  <code>RegexPattern</code> objects represent a pre-processed, or compiled
32  *  regular expression.  They are created from a regular expression pattern string,
33  *  and can be used to create <code>RegexMatcher</code> objects for the pattern.</p>
34  *
35  * <p>Class <code>RegexMatcher</code> bundles together a regular expression
36  *  pattern and a target string to which the search pattern will be applied.
37  *  <code>RegexMatcher</code> includes API for doing plain find or search
38  *  operations, for search and replace operations, and for obtaining detailed
39  *  information about bounds of a match. </p>
40  *
41  * <p>Note that by constructing <code>RegexMatcher</code> objects directly from regular
42  * expression pattern strings application code can be simplified and the explicit
43  * need for <code>RegexPattern</code> objects can usually be eliminated.
44  * </p>
45  */
46 
47 #include "unicode/utypes.h"
48 
49 #if !UCONFIG_NO_REGULAR_EXPRESSIONS
50 
51 #include "unicode/uobject.h"
52 #include "unicode/unistr.h"
53 #include "unicode/utext.h"
54 #include "unicode/parseerr.h"
55 
56 #include "unicode/uregex.h"
57 
58 // Forward Declarations
59 
60 struct UHashtable;
61 
62 U_NAMESPACE_BEGIN
63 
64 struct Regex8BitSet;
65 class  RegexCImpl;
66 class  RegexMatcher;
67 class  RegexPattern;
68 struct REStackFrame;
69 class  RuleBasedBreakIterator;
70 class  UnicodeSet;
71 class  UVector;
72 class  UVector32;
73 class  UVector64;
74 
75 
76 /**
77   * Class <code>RegexPattern</code> represents a compiled regular expression.  It includes
78   * factory methods for creating a RegexPattern object from the source (string) form
79   * of a regular expression, methods for creating RegexMatchers that allow the pattern
80   * to be applied to input text, and a few convenience methods for simple common
81   * uses of regular expressions.
82   *
83   * <p>Class RegexPattern is not intended to be subclassed.</p>
84   *
85   * @stable ICU 2.4
86   */
87 class U_I18N_API RegexPattern U_FINAL : public UObject {
88 public:
89 
90     /**
91      * default constructor.  Create a RegexPattern object that refers to no actual
92      *   pattern.  Not normally needed; RegexPattern objects are usually
93      *   created using the factory method <code>compile()</code>.
94      *
95      * @stable ICU 2.4
96      */
97     RegexPattern();
98 
99     /**
100      * Copy Constructor.  Create a new RegexPattern object that is equivalent
101      *                    to the source object.
102      * @param source the pattern object to be copied.
103      * @stable ICU 2.4
104      */
105     RegexPattern(const RegexPattern &source);
106 
107     /**
108      * Destructor.  Note that a RegexPattern object must persist so long as any
109      *  RegexMatcher objects that were created from the RegexPattern are active.
110      * @stable ICU 2.4
111      */
112     virtual ~RegexPattern();
113 
114     /**
115      * Comparison operator.  Two RegexPattern objects are considered equal if they
116      * were constructed from identical source patterns using the same match flag
117      * settings.
118      * @param that a RegexPattern object to compare with "this".
119      * @return TRUE if the objects are equivalent.
120      * @stable ICU 2.4
121      */
122     UBool           operator==(const RegexPattern& that) const;
123 
124     /**
125      * Comparison operator.  Two RegexPattern objects are considered equal if they
126      * were constructed from identical source patterns using the same match flag
127      * settings.
128      * @param that a RegexPattern object to compare with "this".
129      * @return TRUE if the objects are different.
130      * @stable ICU 2.4
131      */
132     inline UBool    operator!=(const RegexPattern& that) const {return ! operator ==(that);}
133 
134     /**
135      * Assignment operator.  After assignment, this RegexPattern will behave identically
136      *     to the source object.
137      * @stable ICU 2.4
138      */
139     RegexPattern  &operator =(const RegexPattern &source);
140 
141     /**
142      * Create an exact copy of this RegexPattern object.  Since RegexPattern is not
143      * intended to be subclassed, <code>clone()</code> and the copy construction are
144      * equivalent operations.
145      * @return the copy of this RegexPattern
146      * @stable ICU 2.4
147      */
148     virtual RegexPattern  *clone() const;
149 
150 
151    /**
152     * Compiles the regular expression in string form into a RegexPattern
153     * object.  These compile methods, rather than the constructors, are the usual
154     * way that RegexPattern objects are created.
155     *
156     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
157     * objects created from the pattern are active.  RegexMatchers keep a pointer
158     * back to their pattern, so premature deletion of the pattern is a
159     * catastrophic error.</p>
160     *
161     * <p>All pattern match mode flags are set to their default values.</p>
162     *
163     * <p>Note that it is often more convenient to construct a RegexMatcher directly
164     *    from a pattern string rather than separately compiling the pattern and
165     *    then creating a RegexMatcher object from the pattern.</p>
166     *
167     * @param regex The regular expression to be compiled.
168     * @param pe    Receives the position (line and column nubers) of any error
169     *              within the regular expression.)
170     * @param status A reference to a UErrorCode to receive any errors.
171     * @return      A regexPattern object for the compiled pattern.
172     *
173     * @stable ICU 2.4
174     */
175     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
176         UParseError          &pe,
177         UErrorCode           &status);
178 
179    /**
180     * Compiles the regular expression in string form into a RegexPattern
181     * object.  These compile methods, rather than the constructors, are the usual
182     * way that RegexPattern objects are created.
183     *
184     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
185     * objects created from the pattern are active.  RegexMatchers keep a pointer
186     * back to their pattern, so premature deletion of the pattern is a
187     * catastrophic error.</p>
188     *
189     * <p>All pattern match mode flags are set to their default values.</p>
190     *
191     * <p>Note that it is often more convenient to construct a RegexMatcher directly
192     *    from a pattern string rather than separately compiling the pattern and
193     *    then creating a RegexMatcher object from the pattern.</p>
194     *
195     * @param regex The regular expression to be compiled. Note, the text referred
196     *              to by this UText must not be deleted during the lifetime of the
197     *              RegexPattern object or any RegexMatcher object created from it.
198     * @param pe    Receives the position (line and column nubers) of any error
199     *              within the regular expression.)
200     * @param status A reference to a UErrorCode to receive any errors.
201     * @return      A regexPattern object for the compiled pattern.
202     *
203     * @stable ICU 4.6
204     */
205     static RegexPattern * U_EXPORT2 compile( UText *regex,
206         UParseError          &pe,
207         UErrorCode           &status);
208 
209    /**
210     * Compiles the regular expression in string form into a RegexPattern
211     * object using the specified match mode flags.  These compile methods,
212     * rather than the constructors, are the usual way that RegexPattern objects
213     * are created.
214     *
215     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
216     * objects created from the pattern are active.  RegexMatchers keep a pointer
217     * back to their pattern, so premature deletion of the pattern is a
218     * catastrophic error.</p>
219     *
220     * <p>Note that it is often more convenient to construct a RegexMatcher directly
221     *    from a pattern string instead of than separately compiling the pattern and
222     *    then creating a RegexMatcher object from the pattern.</p>
223     *
224     * @param regex The regular expression to be compiled.
225     * @param flags The match mode flags to be used.
226     * @param pe    Receives the position (line and column numbers) of any error
227     *              within the regular expression.)
228     * @param status   A reference to a UErrorCode to receive any errors.
229     * @return      A regexPattern object for the compiled pattern.
230     *
231     * @stable ICU 2.4
232     */
233     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
234         uint32_t             flags,
235         UParseError          &pe,
236         UErrorCode           &status);
237 
238    /**
239     * Compiles the regular expression in string form into a RegexPattern
240     * object using the specified match mode flags.  These compile methods,
241     * rather than the constructors, are the usual way that RegexPattern objects
242     * are created.
243     *
244     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
245     * objects created from the pattern are active.  RegexMatchers keep a pointer
246     * back to their pattern, so premature deletion of the pattern is a
247     * catastrophic error.</p>
248     *
249     * <p>Note that it is often more convenient to construct a RegexMatcher directly
250     *    from a pattern string instead of than separately compiling the pattern and
251     *    then creating a RegexMatcher object from the pattern.</p>
252     *
253     * @param regex The regular expression to be compiled. Note, the text referred
254     *              to by this UText must not be deleted during the lifetime of the
255     *              RegexPattern object or any RegexMatcher object created from it.
256     * @param flags The match mode flags to be used.
257     * @param pe    Receives the position (line and column numbers) of any error
258     *              within the regular expression.)
259     * @param status   A reference to a UErrorCode to receive any errors.
260     * @return      A regexPattern object for the compiled pattern.
261     *
262     * @stable ICU 4.6
263     */
264     static RegexPattern * U_EXPORT2 compile( UText *regex,
265         uint32_t             flags,
266         UParseError          &pe,
267         UErrorCode           &status);
268 
269    /**
270     * Compiles the regular expression in string form into a RegexPattern
271     * object using the specified match mode flags.  These compile methods,
272     * rather than the constructors, are the usual way that RegexPattern objects
273     * are created.
274     *
275     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
276     * objects created from the pattern are active.  RegexMatchers keep a pointer
277     * back to their pattern, so premature deletion of the pattern is a
278     * catastrophic error.</p>
279     *
280     * <p>Note that it is often more convenient to construct a RegexMatcher directly
281     *    from a pattern string instead of than separately compiling the pattern and
282     *    then creating a RegexMatcher object from the pattern.</p>
283     *
284     * @param regex The regular expression to be compiled.
285     * @param flags The match mode flags to be used.
286     * @param status   A reference to a UErrorCode to receive any errors.
287     * @return      A regexPattern object for the compiled pattern.
288     *
289     * @stable ICU 2.6
290     */
291     static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
292         uint32_t             flags,
293         UErrorCode           &status);
294 
295    /**
296     * Compiles the regular expression in string form into a RegexPattern
297     * object using the specified match mode flags.  These compile methods,
298     * rather than the constructors, are the usual way that RegexPattern objects
299     * are created.
300     *
301     * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
302     * objects created from the pattern are active.  RegexMatchers keep a pointer
303     * back to their pattern, so premature deletion of the pattern is a
304     * catastrophic error.</p>
305     *
306     * <p>Note that it is often more convenient to construct a RegexMatcher directly
307     *    from a pattern string instead of than separately compiling the pattern and
308     *    then creating a RegexMatcher object from the pattern.</p>
309     *
310     * @param regex The regular expression to be compiled. Note, the text referred
311     *              to by this UText must not be deleted during the lifetime of the
312     *              RegexPattern object or any RegexMatcher object created from it.
313     * @param flags The match mode flags to be used.
314     * @param status   A reference to a UErrorCode to receive any errors.
315     * @return      A regexPattern object for the compiled pattern.
316     *
317     * @stable ICU 4.6
318     */
319     static RegexPattern * U_EXPORT2 compile( UText *regex,
320         uint32_t             flags,
321         UErrorCode           &status);
322 
323    /**
324     * Get the match mode flags that were used when compiling this pattern.
325     * @return  the match mode flags
326     * @stable ICU 2.4
327     */
328     virtual uint32_t flags() const;
329 
330    /**
331     * Creates a RegexMatcher that will match the given input against this pattern.  The
332     * RegexMatcher can then be used to perform match, find or replace operations
333     * on the input.  Note that a RegexPattern object must not be deleted while
334     * RegexMatchers created from it still exist and might possibly be used again.
335     * <p>
336     * The matcher will retain a reference to the supplied input string, and all regexp
337     * pattern matching operations happen directly on this original string.  It is
338     * critical that the string not be altered or deleted before use by the regular
339     * expression operations is complete.
340     *
341     * @param input    The input string to which the regular expression will be applied.
342     * @param status   A reference to a UErrorCode to receive any errors.
343     * @return         A RegexMatcher object for this pattern and input.
344     *
345     * @stable ICU 2.4
346     */
347     virtual RegexMatcher *matcher(const UnicodeString &input,
348         UErrorCode          &status) const;
349 
350 private:
351     /**
352      * Cause a compilation error if an application accidentally attempts to
353      *   create a matcher with a (UChar *) string as input rather than
354      *   a UnicodeString.  Avoids a dangling reference to a temporary string.
355      * <p>
356      * To efficiently work with UChar *strings, wrap the data in a UnicodeString
357      * using one of the aliasing constructors, such as
358      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
359      * or in a UText, using
360      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
361      *
362      */
363     RegexMatcher *matcher(const UChar *input,
364         UErrorCode          &status) const;
365 public:
366 
367 
368    /**
369     * Creates a RegexMatcher that will match against this pattern.  The
370     * RegexMatcher can be used to perform match, find or replace operations.
371     * Note that a RegexPattern object must not be deleted while
372     * RegexMatchers created from it still exist and might possibly be used again.
373     *
374     * @param status   A reference to a UErrorCode to receive any errors.
375     * @return      A RegexMatcher object for this pattern and input.
376     *
377     * @stable ICU 2.6
378     */
379     virtual RegexMatcher *matcher(UErrorCode  &status) const;
380 
381 
382    /**
383     * Test whether a string matches a regular expression.  This convenience function
384     * both compiles the regular expression and applies it in a single operation.
385     * Note that if the same pattern needs to be applied repeatedly, this method will be
386     * less efficient than creating and reusing a RegexMatcher object.
387     *
388     * @param regex The regular expression
389     * @param input The string data to be matched
390     * @param pe Receives the position of any syntax errors within the regular expression
391     * @param status A reference to a UErrorCode to receive any errors.
392     * @return True if the regular expression exactly matches the full input string.
393     *
394     * @stable ICU 2.4
395     */
396     static UBool U_EXPORT2 matches(const UnicodeString   &regex,
397         const UnicodeString   &input,
398               UParseError     &pe,
399               UErrorCode      &status);
400 
401    /**
402     * Test whether a string matches a regular expression.  This convenience function
403     * both compiles the regular expression and applies it in a single operation.
404     * Note that if the same pattern needs to be applied repeatedly, this method will be
405     * less efficient than creating and reusing a RegexMatcher object.
406     *
407     * @param regex The regular expression
408     * @param input The string data to be matched
409     * @param pe Receives the position of any syntax errors within the regular expression
410     * @param status A reference to a UErrorCode to receive any errors.
411     * @return True if the regular expression exactly matches the full input string.
412     *
413     * @stable ICU 4.6
414     */
415     static UBool U_EXPORT2 matches(UText *regex,
416         UText           *input,
417         UParseError     &pe,
418         UErrorCode      &status);
419 
420    /**
421     * Returns the regular expression from which this pattern was compiled. This method will work
422     * even if the pattern was compiled from a UText.
423     *
424     * Note: If the pattern was originally compiled from a UText, and that UText was modified,
425     * the returned string may no longer reflect the RegexPattern object.
426     * @stable ICU 2.4
427     */
428     virtual UnicodeString pattern() const;
429 
430 
431    /**
432     * Returns the regular expression from which this pattern was compiled. This method will work
433     * even if the pattern was compiled from a UnicodeString.
434     *
435     * Note: This is the original input, not a clone. If the pattern was originally compiled from a
436     * UText, and that UText was modified, the returned UText may no longer reflect the RegexPattern
437     * object.
438     *
439     * @stable ICU 4.6
440     */
441     virtual UText *patternText(UErrorCode      &status) const;
442 
443 
444     /**
445      * Get the group number corresponding to a named capture group.
446      * The returned number can be used with any function that access
447      * capture groups by number.
448      *
449      * The function returns an error status if the specified name does not
450      * appear in the pattern.
451      *
452      * @param  groupName   The capture group name.
453      * @param  status      A UErrorCode to receive any errors.
454      *
455      * @stable ICU 55
456      */
457     virtual int32_t groupNumberFromName(const UnicodeString &groupName, UErrorCode &status) const;
458 
459 
460     /**
461      * Get the group number corresponding to a named capture group.
462      * The returned number can be used with any function that access
463      * capture groups by number.
464      *
465      * The function returns an error status if the specified name does not
466      * appear in the pattern.
467      *
468      * @param  groupName   The capture group name,
469      *                     platform invariant characters only.
470      * @param  nameLength  The length of the name, or -1 if the name is
471      *                     nul-terminated.
472      * @param  status      A UErrorCode to receive any errors.
473      *
474      * @stable ICU 55
475      */
476     virtual int32_t groupNumberFromName(const char *groupName, int32_t nameLength, UErrorCode &status) const;
477 
478 
479     /**
480      * Split a string into fields.  Somewhat like split() from Perl or Java.
481      * Pattern matches identify delimiters that separate the input
482      * into fields.  The input data between the delimiters becomes the
483      * fields themselves.
484      *
485      * If the delimiter pattern includes capture groups, the captured text will
486      * also appear in the destination array of output strings, interspersed
487      * with the fields.  This is similar to Perl, but differs from Java,
488      * which ignores the presence of capture groups in the pattern.
489      *
490      * Trailing empty fields will always be returned, assuming sufficient
491      * destination capacity.  This differs from the default behavior for Java
492      * and Perl where trailing empty fields are not returned.
493      *
494      * The number of strings produced by the split operation is returned.
495      * This count includes the strings from capture groups in the delimiter pattern.
496      * This behavior differs from Java, which ignores capture groups.
497      *
498      * For the best performance on split() operations,
499      * <code>RegexMatcher::split</code> is preferable to this function
500      *
501      * @param input   The string to be split into fields.  The field delimiters
502      *                match the pattern (in the "this" object)
503      * @param dest    An array of UnicodeStrings to receive the results of the split.
504      *                This is an array of actual UnicodeString objects, not an
505      *                array of pointers to strings.  Local (stack based) arrays can
506      *                work well here.
507      * @param destCapacity  The number of elements in the destination array.
508      *                If the number of fields found is less than destCapacity, the
509      *                extra strings in the destination array are not altered.
510      *                If the number of destination strings is less than the number
511      *                of fields, the trailing part of the input string, including any
512      *                field delimiters, is placed in the last destination string.
513      * @param status  A reference to a UErrorCode to receive any errors.
514      * @return        The number of fields into which the input string was split.
515      * @stable ICU 2.4
516      */
517     virtual int32_t  split(const UnicodeString &input,
518         UnicodeString    dest[],
519         int32_t          destCapacity,
520         UErrorCode       &status) const;
521 
522 
523     /**
524      * Split a string into fields.  Somewhat like split() from Perl or Java.
525      * Pattern matches identify delimiters that separate the input
526      * into fields.  The input data between the delimiters becomes the
527      * fields themselves.
528      *
529      * If the delimiter pattern includes capture groups, the captured text will
530      * also appear in the destination array of output strings, interspersed
531      * with the fields.  This is similar to Perl, but differs from Java,
532      * which ignores the presence of capture groups in the pattern.
533      *
534      * Trailing empty fields will always be returned, assuming sufficient
535      * destination capacity.  This differs from the default behavior for Java
536      * and Perl where trailing empty fields are not returned.
537      *
538      * The number of strings produced by the split operation is returned.
539      * This count includes the strings from capture groups in the delimiter pattern.
540      * This behavior differs from Java, which ignores capture groups.
541      *
542      *  For the best performance on split() operations,
543      *  <code>RegexMatcher::split</code> is preferable to this function
544      *
545      * @param input   The string to be split into fields.  The field delimiters
546      *                match the pattern (in the "this" object)
547      * @param dest    An array of mutable UText structs to receive the results of the split.
548      *                If a field is NULL, a new UText is allocated to contain the results for
549      *                that field. This new UText is not guaranteed to be mutable.
550      * @param destCapacity  The number of elements in the destination array.
551      *                If the number of fields found is less than destCapacity, the
552      *                extra strings in the destination array are not altered.
553      *                If the number of destination strings is less than the number
554      *                of fields, the trailing part of the input string, including any
555      *                field delimiters, is placed in the last destination string.
556      * @param status  A reference to a UErrorCode to receive any errors.
557      * @return        The number of destination strings used.
558      *
559      * @stable ICU 4.6
560      */
561     virtual int32_t  split(UText *input,
562         UText            *dest[],
563         int32_t          destCapacity,
564         UErrorCode       &status) const;
565 
566 
567     /**
568      * ICU "poor man's RTTI", returns a UClassID for the actual class.
569      *
570      * @stable ICU 2.4
571      */
572     virtual UClassID getDynamicClassID() const;
573 
574     /**
575      * ICU "poor man's RTTI", returns a UClassID for this class.
576      *
577      * @stable ICU 2.4
578      */
579     static UClassID U_EXPORT2 getStaticClassID();
580 
581 private:
582     //
583     //  Implementation Data
584     //
585     UText          *fPattern;      // The original pattern string.
586     UnicodeString  *fPatternString; // The original pattern UncodeString if relevant
587     uint32_t        fFlags;        // The flags used when compiling the pattern.
588                                    //
589     UVector64       *fCompiledPat; // The compiled pattern p-code.
590     UnicodeString   fLiteralText;  // Any literal string data from the pattern,
591                                    //   after un-escaping, for use during the match.
592 
593     UVector         *fSets;        // Any UnicodeSets referenced from the pattern.
594     Regex8BitSet    *fSets8;       //      (and fast sets for latin-1 range.)
595 
596 
597     UErrorCode      fDeferredStatus; // status if some prior error has left this
598                                    //  RegexPattern in an unusable state.
599 
600     int32_t         fMinMatchLen;  // Minimum Match Length.  All matches will have length
601                                    //   >= this value.  For some patterns, this calculated
602                                    //   value may be less than the true shortest
603                                    //   possible match.
604 
605     int32_t         fFrameSize;    // Size of a state stack frame in the
606                                    //   execution engine.
607 
608     int32_t         fDataSize;     // The size of the data needed by the pattern that
609                                    //   does not go on the state stack, but has just
610                                    //   a single copy per matcher.
611 
612     UVector32       *fGroupMap;    // Map from capture group number to position of
613                                    //   the group's variables in the matcher stack frame.
614 
615     UnicodeSet     **fStaticSets;  // Ptr to static (shared) sets for predefined
616                                    //   regex character classes, e.g. Word.
617 
618     Regex8BitSet   *fStaticSets8;  // Ptr to the static (shared) latin-1 only
619                                    //  sets for predefined regex classes.
620 
621     int32_t         fStartType;    // Info on how a match must start.
622     int32_t         fInitialStringIdx;     //
623     int32_t         fInitialStringLen;
624     UnicodeSet     *fInitialChars;
625     UChar32         fInitialChar;
626     Regex8BitSet   *fInitialChars8;
627     UBool           fNeedsAltInput;
628 
629     UHashtable     *fNamedCaptureMap;  // Map from capture group names to numbers.
630 
631     friend class RegexCompile;
632     friend class RegexMatcher;
633     friend class RegexCImpl;
634 
635     //
636     //  Implementation Methods
637     //
638     void        init();            // Common initialization, for use by constructors.
639     void        zap();             // Common cleanup
640 
641     void        dumpOp(int32_t index) const;
642 
643   public:
644 #ifndef U_HIDE_INTERNAL_API
645     /**
646       * Dump a compiled pattern. Internal debug function.
647       * @internal
648       */
649     void        dumpPattern() const;
650 #endif  /* U_HIDE_INTERNAL_API */
651 };
652 
653 
654 
655 /**
656  *  class RegexMatcher bundles together a regular expression pattern and
657  *  input text to which the expression can be applied.  It includes methods
658  *  for testing for matches, and for find and replace operations.
659  *
660  * <p>Class RegexMatcher is not intended to be subclassed.</p>
661  *
662  * @stable ICU 2.4
663  */
664 class U_I18N_API RegexMatcher U_FINAL : public UObject {
665 public:
666 
667     /**
668       * Construct a RegexMatcher for a regular expression.
669       * This is a convenience method that avoids the need to explicitly create
670       * a RegexPattern object.  Note that if several RegexMatchers need to be
671       * created for the same expression, it will be more efficient to
672       * separately create and cache a RegexPattern object, and use
673       * its matcher() method to create the RegexMatcher objects.
674       *
675       *  @param regexp The Regular Expression to be compiled.
676       *  @param flags  Regular expression options, such as case insensitive matching.
677       *                @see UREGEX_CASE_INSENSITIVE
678       *  @param status Any errors are reported by setting this UErrorCode variable.
679       *  @stable ICU 2.6
680       */
681     RegexMatcher(const UnicodeString &regexp, uint32_t flags, UErrorCode &status);
682 
683     /**
684       * Construct a RegexMatcher for a regular expression.
685       * This is a convenience method that avoids the need to explicitly create
686       * a RegexPattern object.  Note that if several RegexMatchers need to be
687       * created for the same expression, it will be more efficient to
688       * separately create and cache a RegexPattern object, and use
689       * its matcher() method to create the RegexMatcher objects.
690       *
691       *  @param regexp The regular expression to be compiled.
692       *  @param flags  Regular expression options, such as case insensitive matching.
693       *                @see UREGEX_CASE_INSENSITIVE
694       *  @param status Any errors are reported by setting this UErrorCode variable.
695       *
696       *  @stable ICU 4.6
697       */
698     RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);
699 
700     /**
701       * Construct a RegexMatcher for a regular expression.
702       * This is a convenience method that avoids the need to explicitly create
703       * a RegexPattern object.  Note that if several RegexMatchers need to be
704       * created for the same expression, it will be more efficient to
705       * separately create and cache a RegexPattern object, and use
706       * its matcher() method to create the RegexMatcher objects.
707       * <p>
708       * The matcher will retain a reference to the supplied input string, and all regexp
709       * pattern matching operations happen directly on the original string.  It is
710       * critical that the string not be altered or deleted before use by the regular
711       * expression operations is complete.
712       *
713       *  @param regexp The Regular Expression to be compiled.
714       *  @param input  The string to match.  The matcher retains a reference to the
715       *                caller's string; mo copy is made.
716       *  @param flags  Regular expression options, such as case insensitive matching.
717       *                @see UREGEX_CASE_INSENSITIVE
718       *  @param status Any errors are reported by setting this UErrorCode variable.
719       *  @stable ICU 2.6
720       */
721     RegexMatcher(const UnicodeString &regexp, const UnicodeString &input,
722         uint32_t flags, UErrorCode &status);
723 
724     /**
725       * Construct a RegexMatcher for a regular expression.
726       * This is a convenience method that avoids the need to explicitly create
727       * a RegexPattern object.  Note that if several RegexMatchers need to be
728       * created for the same expression, it will be more efficient to
729       * separately create and cache a RegexPattern object, and use
730       * its matcher() method to create the RegexMatcher objects.
731       * <p>
732       * The matcher will make a shallow clone of the supplied input text, and all regexp
733       * pattern matching operations happen on this clone.  While read-only operations on
734       * the supplied text are permitted, it is critical that the underlying string not be
735       * altered or deleted before use by the regular expression operations is complete.
736       *
737       *  @param regexp The Regular Expression to be compiled.
738       *  @param input  The string to match.  The matcher retains a shallow clone of the text.
739       *  @param flags  Regular expression options, such as case insensitive matching.
740       *                @see UREGEX_CASE_INSENSITIVE
741       *  @param status Any errors are reported by setting this UErrorCode variable.
742       *
743       *  @stable ICU 4.6
744       */
745     RegexMatcher(UText *regexp, UText *input,
746         uint32_t flags, UErrorCode &status);
747 
748 private:
749     /**
750      * Cause a compilation error if an application accidentally attempts to
751      *   create a matcher with a (UChar *) string as input rather than
752      *   a UnicodeString.    Avoids a dangling reference to a temporary string.
753      * <p>
754      * To efficiently work with UChar *strings, wrap the data in a UnicodeString
755      * using one of the aliasing constructors, such as
756      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
757      * or in a UText, using
758      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
759      *
760      */
761     RegexMatcher(const UnicodeString &regexp, const UChar *input,
762         uint32_t flags, UErrorCode &status);
763 public:
764 
765 
766    /**
767     *   Destructor.
768     *
769     *  @stable ICU 2.4
770     */
771     virtual ~RegexMatcher();
772 
773 
774    /**
775     *   Attempts to match the entire input region against the pattern.
776     *    @param   status     A reference to a UErrorCode to receive any errors.
777     *    @return TRUE if there is a match
778     *    @stable ICU 2.4
779     */
780     virtual UBool matches(UErrorCode &status);
781 
782 
783    /**
784     *   Resets the matcher, then attempts to match the input beginning
785     *   at the specified startIndex, and extending to the end of the input.
786     *   The input region is reset to include the entire input string.
787     *   A successful match must extend to the end of the input.
788     *    @param   startIndex The input string (native) index at which to begin matching.
789     *    @param   status     A reference to a UErrorCode to receive any errors.
790     *    @return TRUE if there is a match
791     *    @stable ICU 2.8
792     */
793     virtual UBool matches(int64_t startIndex, UErrorCode &status);
794 
795 
796    /**
797     *   Attempts to match the input string, starting from the beginning of the region,
798     *   against the pattern.  Like the matches() method, this function
799     *   always starts at the beginning of the input region;
800     *   unlike that function, it does not require that the entire region be matched.
801     *
802     *   <p>If the match succeeds then more information can be obtained via the <code>start()</code>,
803     *     <code>end()</code>, and <code>group()</code> functions.</p>
804     *
805     *    @param   status     A reference to a UErrorCode to receive any errors.
806     *    @return  TRUE if there is a match at the start of the input string.
807     *    @stable ICU 2.4
808     */
809     virtual UBool lookingAt(UErrorCode &status);
810 
811 
812   /**
813     *   Attempts to match the input string, starting from the specified index, against the pattern.
814     *   The match may be of any length, and is not required to extend to the end
815     *   of the input string.  Contrast with match().
816     *
817     *   <p>If the match succeeds then more information can be obtained via the <code>start()</code>,
818     *     <code>end()</code>, and <code>group()</code> functions.</p>
819     *
820     *    @param   startIndex The input string (native) index at which to begin matching.
821     *    @param   status     A reference to a UErrorCode to receive any errors.
822     *    @return  TRUE if there is a match.
823     *    @stable ICU 2.8
824     */
825     virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);
826 
827 
828    /**
829     *  Find the next pattern match in the input string.
830     *  The find begins searching the input at the location following the end of
831     *  the previous match, or at the start of the string if there is no previous match.
832     *  If a match is found, <code>start(), end()</code> and <code>group()</code>
833     *  will provide more information regarding the match.
834     *  <p>Note that if the input string is changed by the application,
835     *     use find(startPos, status) instead of find(), because the saved starting
836     *     position may not be valid with the altered input string.</p>
837     *  @return  TRUE if a match is found.
838     *  @stable ICU 2.4
839     */
840     virtual UBool find();
841 
842 
843    /**
844     *  Find the next pattern match in the input string.
845     *  The find begins searching the input at the location following the end of
846     *  the previous match, or at the start of the string if there is no previous match.
847     *  If a match is found, <code>start(), end()</code> and <code>group()</code>
848     *  will provide more information regarding the match.
849     *  <p>Note that if the input string is changed by the application,
850     *     use find(startPos, status) instead of find(), because the saved starting
851     *     position may not be valid with the altered input string.</p>
852     *  @param   status  A reference to a UErrorCode to receive any errors.
853     *  @return  TRUE if a match is found.
854     * @stable ICU 55
855     */
856     virtual UBool find(UErrorCode &status);
857 
858    /**
859     *   Resets this RegexMatcher and then attempts to find the next substring of the
860     *   input string that matches the pattern, starting at the specified index.
861     *
862     *   @param   start     The (native) index in the input string to begin the search.
863     *   @param   status    A reference to a UErrorCode to receive any errors.
864     *   @return  TRUE if a match is found.
865     *   @stable ICU 2.4
866     */
867     virtual UBool find(int64_t start, UErrorCode &status);
868 
869 
870    /**
871     *   Returns a string containing the text matched by the previous match.
872     *   If the pattern can match an empty string, an empty string may be returned.
873     *   @param   status      A reference to a UErrorCode to receive any errors.
874     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
875     *                        has been attempted or the last match failed.
876     *   @return  a string containing the matched input text.
877     *   @stable ICU 2.4
878     */
879     virtual UnicodeString group(UErrorCode &status) const;
880 
881 
882    /**
883     *    Returns a string containing the text captured by the given group
884     *    during the previous match operation.  Group(0) is the entire match.
885     *
886     *    A zero length string is returned both for capture groups that did not
887     *    participate in the match and for actual zero length matches.
888     *    To distinguish between these two cases use the function start(),
889     *    which returns -1 for non-participating groups.
890     *
891     *    @param groupNum the capture group number
892     *    @param   status     A reference to a UErrorCode to receive any errors.
893     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
894     *                        has been attempted or the last match failed and
895     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
896     *    @return the captured text
897     *    @stable ICU 2.4
898     */
899     virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;
900 
901    /**
902     *   Returns the number of capturing groups in this matcher's pattern.
903     *   @return the number of capture groups
904     *   @stable ICU 2.4
905     */
906     virtual int32_t groupCount() const;
907 
908 
909    /**
910     *   Returns a shallow clone of the entire live input string with the UText current native index
911     *   set to the beginning of the requested group.
912     *
913     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText
914     *   @param   group_len   A reference to receive the length of the desired capture group
915     *   @param   status      A reference to a UErrorCode to receive any errors.
916     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
917     *                        has been attempted or the last match failed and
918     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
919     *   @return dest if non-NULL, a shallow copy of the input text otherwise
920     *
921     *   @stable ICU 4.6
922     */
923     virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const;
924 
925    /**
926     *   Returns a shallow clone of the entire live input string with the UText current native index
927     *   set to the beginning of the requested group.
928     *
929     *   A group length of zero is returned both for capture groups that did not
930     *   participate in the match and for actual zero length matches.
931     *   To distinguish between these two cases use the function start(),
932     *   which returns -1 for non-participating groups.
933     *
934     *   @param   groupNum   The capture group number.
935     *   @param   dest        The UText into which the input should be cloned, or NULL to create a new UText.
936     *   @param   group_len   A reference to receive the length of the desired capture group
937     *   @param   status      A reference to a UErrorCode to receive any errors.
938     *                        Possible errors are  U_REGEX_INVALID_STATE if no match
939     *                        has been attempted or the last match failed and
940     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
941     *   @return dest if non-NULL, a shallow copy of the input text otherwise
942     *
943     *   @stable ICU 4.6
944     */
945     virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;
946 
947    /**
948     *   Returns the index in the input string of the start of the text matched
949     *   during the previous match operation.
950     *    @param   status      a reference to a UErrorCode to receive any errors.
951     *    @return              The (native) position in the input string of the start of the last match.
952     *    @stable ICU 2.4
953     */
954     virtual int32_t start(UErrorCode &status) const;
955 
956    /**
957     *   Returns the index in the input string of the start of the text matched
958     *   during the previous match operation.
959     *    @param   status      a reference to a UErrorCode to receive any errors.
960     *    @return              The (native) position in the input string of the start of the last match.
961     *   @stable ICU 4.6
962     */
963     virtual int64_t start64(UErrorCode &status) const;
964 
965 
966    /**
967     *   Returns the index in the input string of the start of the text matched by the
968     *    specified capture group during the previous match operation.  Return -1 if
969     *    the capture group exists in the pattern, but was not part of the last match.
970     *
971     *    @param  group       the capture group number
972     *    @param  status      A reference to a UErrorCode to receive any errors.  Possible
973     *                        errors are  U_REGEX_INVALID_STATE if no match has been
974     *                        attempted or the last match failed, and
975     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
976     *    @return the (native) start position of substring matched by the specified group.
977     *    @stable ICU 2.4
978     */
979     virtual int32_t start(int32_t group, UErrorCode &status) const;
980 
981    /**
982     *   Returns the index in the input string of the start of the text matched by the
983     *    specified capture group during the previous match operation.  Return -1 if
984     *    the capture group exists in the pattern, but was not part of the last match.
985     *
986     *    @param  group       the capture group number.
987     *    @param  status      A reference to a UErrorCode to receive any errors.  Possible
988     *                        errors are  U_REGEX_INVALID_STATE if no match has been
989     *                        attempted or the last match failed, and
990     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
991     *    @return the (native) start position of substring matched by the specified group.
992     *    @stable ICU 4.6
993     */
994     virtual int64_t start64(int32_t group, UErrorCode &status) const;
995 
996    /**
997     *    Returns the index in the input string of the first character following the
998     *    text matched during the previous match operation.
999     *
1000     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible
1001     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1002     *                        attempted or the last match failed.
1003     *    @return the index of the last character matched, plus one.
1004     *                        The index value returned is a native index, corresponding to
1005     *                        code units for the underlying encoding type, for example,
1006     *                        a byte index for UTF-8.
1007     *   @stable ICU 2.4
1008     */
1009     virtual int32_t end(UErrorCode &status) const;
1010 
1011    /**
1012     *    Returns the index in the input string of the first character following the
1013     *    text matched during the previous match operation.
1014     *
1015     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible
1016     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1017     *                        attempted or the last match failed.
1018     *    @return the index of the last character matched, plus one.
1019     *                        The index value returned is a native index, corresponding to
1020     *                        code units for the underlying encoding type, for example,
1021     *                        a byte index for UTF-8.
1022     *   @stable ICU 4.6
1023     */
1024     virtual int64_t end64(UErrorCode &status) const;
1025 
1026 
1027    /**
1028     *    Returns the index in the input string of the character following the
1029     *    text matched by the specified capture group during the previous match operation.
1030     *
1031     *    @param group  the capture group number
1032     *    @param   status      A reference to a UErrorCode to receive any errors.  Possible
1033     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1034     *                        attempted or the last match failed and
1035     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1036     *    @return  the index of the first character following the text
1037     *              captured by the specified group during the previous match operation.
1038     *              Return -1 if the capture group exists in the pattern but was not part of the match.
1039     *              The index value returned is a native index, corresponding to
1040     *              code units for the underlying encoding type, for example,
1041     *              a byte index for UTF8.
1042     *    @stable ICU 2.4
1043     */
1044     virtual int32_t end(int32_t group, UErrorCode &status) const;
1045 
1046    /**
1047     *    Returns the index in the input string of the character following the
1048     *    text matched by the specified capture group during the previous match operation.
1049     *
1050     *    @param group  the capture group number
1051     *    @param   status      A reference to a UErrorCode to receive any errors.  Possible
1052     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1053     *                        attempted or the last match failed and
1054     *                        U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1055     *    @return  the index of the first character following the text
1056     *              captured by the specified group during the previous match operation.
1057     *              Return -1 if the capture group exists in the pattern but was not part of the match.
1058     *              The index value returned is a native index, corresponding to
1059     *              code units for the underlying encoding type, for example,
1060     *              a byte index for UTF8.
1061     *   @stable ICU 4.6
1062     */
1063     virtual int64_t end64(int32_t group, UErrorCode &status) const;
1064 
1065    /**
1066     *   Resets this matcher.  The effect is to remove any memory of previous matches,
1067     *       and to cause subsequent find() operations to begin at the beginning of
1068     *       the input string.
1069     *
1070     *   @return this RegexMatcher.
1071     *   @stable ICU 2.4
1072     */
1073     virtual RegexMatcher &reset();
1074 
1075 
1076    /**
1077     *   Resets this matcher, and set the current input position.
1078     *   The effect is to remove any memory of previous matches,
1079     *       and to cause subsequent find() operations to begin at
1080     *       the specified (native) position in the input string.
1081     * <p>
1082     *   The matcher's region is reset to its default, which is the entire
1083     *   input string.
1084     * <p>
1085     *   An alternative to this function is to set a match region
1086     *   beginning at the desired index.
1087     *
1088     *   @return this RegexMatcher.
1089     *   @stable ICU 2.8
1090     */
1091     virtual RegexMatcher &reset(int64_t index, UErrorCode &status);
1092 
1093 
1094    /**
1095     *   Resets this matcher with a new input string.  This allows instances of RegexMatcher
1096     *     to be reused, which is more efficient than creating a new RegexMatcher for
1097     *     each input string to be processed.
1098     *   @param input The new string on which subsequent pattern matches will operate.
1099     *                The matcher retains a reference to the callers string, and operates
1100     *                directly on that.  Ownership of the string remains with the caller.
1101     *                Because no copy of the string is made, it is essential that the
1102     *                caller not delete the string until after regexp operations on it
1103     *                are done.
1104     *                Note that while a reset on the matcher with an input string that is then
1105     *                modified across/during matcher operations may be supported currently for UnicodeString,
1106     *                this was not originally intended behavior, and support for this is not guaranteed
1107     *                in upcoming versions of ICU.
1108     *   @return this RegexMatcher.
1109     *   @stable ICU 2.4
1110     */
1111     virtual RegexMatcher &reset(const UnicodeString &input);
1112 
1113 
1114    /**
1115     *   Resets this matcher with a new input string.  This allows instances of RegexMatcher
1116     *     to be reused, which is more efficient than creating a new RegexMatcher for
1117     *     each input string to be processed.
1118     *   @param input The new string on which subsequent pattern matches will operate.
1119     *                The matcher makes a shallow clone of the given text; ownership of the
1120     *                original string remains with the caller. Because no deep copy of the
1121     *                text is made, it is essential that the caller not modify the string
1122     *                until after regexp operations on it are done.
1123     *   @return this RegexMatcher.
1124     *
1125     *   @stable ICU 4.6
1126     */
1127     virtual RegexMatcher &reset(UText *input);
1128 
1129 
1130   /**
1131     *  Set the subject text string upon which the regular expression is looking for matches
1132     *  without changing any other aspect of the matching state.
1133     *  The new and previous text strings must have the same content.
1134     *
1135     *  This function is intended for use in environments where ICU is operating on
1136     *  strings that may move around in memory.  It provides a mechanism for notifying
1137     *  ICU that the string has been relocated, and providing a new UText to access the
1138     *  string in its new position.
1139     *
1140     *  Note that the regular expression implementation never copies the underlying text
1141     *  of a string being matched, but always operates directly on the original text
1142     *  provided by the user. Refreshing simply drops the references to the old text
1143     *  and replaces them with references to the new.
1144     *
1145     *  Caution:  this function is normally used only by very specialized,
1146     *  system-level code.  One example use case is with garbage collection that moves
1147     *  the text in memory.
1148     *
1149     * @param input      The new (moved) text string.
1150     * @param status     Receives errors detected by this function.
1151     *
1152     * @stable ICU 4.8
1153     */
1154     virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);
1155 
1156 private:
1157     /**
1158      * Cause a compilation error if an application accidentally attempts to
1159      *   reset a matcher with a (UChar *) string as input rather than
1160      *   a UnicodeString.    Avoids a dangling reference to a temporary string.
1161      * <p>
1162      * To efficiently work with UChar *strings, wrap the data in a UnicodeString
1163      * using one of the aliasing constructors, such as
1164      * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
1165      * or in a UText, using
1166      * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
1167      *
1168      */
1169     RegexMatcher &reset(const UChar *input);
1170 public:
1171 
1172    /**
1173     *   Returns the input string being matched.  Ownership of the string belongs to
1174     *   the matcher; it should not be altered or deleted. This method will work even if the input
1175     *   was originally supplied as a UText.
1176     *   @return the input string
1177     *   @stable ICU 2.4
1178     */
1179     virtual const UnicodeString &input() const;
1180 
1181    /**
1182     *   Returns the input string being matched.  This is the live input text; it should not be
1183     *   altered or deleted. This method will work even if the input was originally supplied as
1184     *   a UnicodeString.
1185     *   @return the input text
1186     *
1187     *   @stable ICU 4.6
1188     */
1189     virtual UText *inputText() const;
1190 
1191    /**
1192     *   Returns the input string being matched, either by copying it into the provided
1193     *   UText parameter or by returning a shallow clone of the live input. Note that copying
1194     *   the entire input may cause significant performance and memory issues.
1195     *   @param dest The UText into which the input should be copied, or NULL to create a new UText
1196     *   @param status error code
1197     *   @return dest if non-NULL, a shallow copy of the input text otherwise
1198     *
1199     *   @stable ICU 4.6
1200     */
1201     virtual UText *getInput(UText *dest, UErrorCode &status) const;
1202 
1203 
1204    /** Sets the limits of this matcher's region.
1205      * The region is the part of the input string that will be searched to find a match.
1206      * Invoking this method resets the matcher, and then sets the region to start
1207      * at the index specified by the start parameter and end at the index specified
1208      * by the end parameter.
1209      *
1210      * Depending on the transparency and anchoring being used (see useTransparentBounds
1211      * and useAnchoringBounds), certain constructs such as anchors may behave differently
1212      * at or around the boundaries of the region
1213      *
1214      * The function will fail if start is greater than limit, or if either index
1215      *  is less than zero or greater than the length of the string being matched.
1216      *
1217      * @param start  The (native) index to begin searches at.
1218      * @param limit  The index to end searches at (exclusive).
1219      * @param status A reference to a UErrorCode to receive any errors.
1220      * @stable ICU 4.0
1221      */
1222      virtual RegexMatcher &region(int64_t start, int64_t limit, UErrorCode &status);
1223 
1224    /**
1225      * Identical to region(start, limit, status) but also allows a start position without
1226      *  resetting the region state.
1227      * @param regionStart The region start
1228      * @param regionLimit the limit of the region
1229      * @param startIndex  The (native) index within the region bounds at which to begin searches.
1230      * @param status A reference to a UErrorCode to receive any errors.
1231      *                If startIndex is not within the specified region bounds,
1232      *                U_INDEX_OUTOFBOUNDS_ERROR is returned.
1233      * @stable ICU 4.6
1234      */
1235      virtual RegexMatcher &region(int64_t regionStart, int64_t regionLimit, int64_t startIndex, UErrorCode &status);
1236 
1237    /**
1238      * Reports the start index of this matcher's region. The searches this matcher
1239      * conducts are limited to finding matches within regionStart (inclusive) and
1240      * regionEnd (exclusive).
1241      *
1242      * @return The starting (native) index of this matcher's region.
1243      * @stable ICU 4.0
1244      */
1245      virtual int32_t regionStart() const;
1246 
1247    /**
1248      * Reports the start index of this matcher's region. The searches this matcher
1249      * conducts are limited to finding matches within regionStart (inclusive) and
1250      * regionEnd (exclusive).
1251      *
1252      * @return The starting (native) index of this matcher's region.
1253      * @stable ICU 4.6
1254      */
1255      virtual int64_t regionStart64() const;
1256 
1257 
1258     /**
1259       * Reports the end (limit) index (exclusive) of this matcher's region. The searches
1260       * this matcher conducts are limited to finding matches within regionStart
1261       * (inclusive) and regionEnd (exclusive).
1262       *
1263       * @return The ending point (native) of this matcher's region.
1264       * @stable ICU 4.0
1265       */
1266       virtual int32_t regionEnd() const;
1267 
1268    /**
1269      * Reports the end (limit) index (exclusive) of this matcher's region. The searches
1270      * this matcher conducts are limited to finding matches within regionStart
1271      * (inclusive) and regionEnd (exclusive).
1272      *
1273      * @return The ending point (native) of this matcher's region.
1274      * @stable ICU 4.6
1275      */
1276       virtual int64_t regionEnd64() const;
1277 
1278     /**
1279       * Queries the transparency of region bounds for this matcher.
1280       * See useTransparentBounds for a description of transparent and opaque bounds.
1281       * By default, a matcher uses opaque region boundaries.
1282       *
1283       * @return TRUE if this matcher is using opaque bounds, false if it is not.
1284       * @stable ICU 4.0
1285       */
1286       virtual UBool hasTransparentBounds() const;
1287 
1288     /**
1289       * Sets the transparency of region bounds for this matcher.
1290       * Invoking this function with an argument of true will set this matcher to use transparent bounds.
1291       * If the boolean argument is false, then opaque bounds will be used.
1292       *
1293       * Using transparent bounds, the boundaries of this matcher's region are transparent
1294       * to lookahead, lookbehind, and boundary matching constructs. Those constructs can
1295       * see text beyond the boundaries of the region while checking for a match.
1296       *
1297       * With opaque bounds, no text outside of the matcher's region is visible to lookahead,
1298       * lookbehind, and boundary matching constructs.
1299       *
1300       * By default, a matcher uses opaque bounds.
1301       *
1302       * @param   b TRUE for transparent bounds; FALSE for opaque bounds
1303       * @return  This Matcher;
1304       * @stable ICU 4.0
1305       **/
1306       virtual RegexMatcher &useTransparentBounds(UBool b);
1307 
1308 
1309     /**
1310       * Return true if this matcher is using anchoring bounds.
1311       * By default, matchers use anchoring region bounds.
1312       *
1313       * @return TRUE if this matcher is using anchoring bounds.
1314       * @stable ICU 4.0
1315       */
1316       virtual UBool hasAnchoringBounds() const;
1317 
1318 
1319     /**
1320       * Set whether this matcher is using Anchoring Bounds for its region.
1321       * With anchoring bounds, pattern anchors such as ^ and $ will match at the start
1322       * and end of the region.  Without Anchoring Bounds, anchors will only match at
1323       * the positions they would in the complete text.
1324       *
1325       * Anchoring Bounds are the default for regions.
1326       *
1327       * @param b TRUE if to enable anchoring bounds; FALSE to disable them.
1328       * @return  This Matcher
1329       * @stable ICU 4.0
1330       */
1331       virtual RegexMatcher &useAnchoringBounds(UBool b);
1332 
1333 
1334     /**
1335       * Return TRUE if the most recent matching operation attempted to access
1336       *  additional input beyond the available input text.
1337       *  In this case, additional input text could change the results of the match.
1338       *
1339       *  hitEnd() is defined for both successful and unsuccessful matches.
1340       *  In either case hitEnd() will return TRUE if if the end of the text was
1341       *  reached at any point during the matching process.
1342       *
1343       *  @return  TRUE if the most recent match hit the end of input
1344       *  @stable ICU 4.0
1345       */
1346       virtual UBool hitEnd() const;
1347 
1348     /**
1349       * Return TRUE the most recent match succeeded and additional input could cause
1350       * it to fail. If this method returns false and a match was found, then more input
1351       * might change the match but the match won't be lost. If a match was not found,
1352       * then requireEnd has no meaning.
1353       *
1354       * @return TRUE if more input could cause the most recent match to no longer match.
1355       * @stable ICU 4.0
1356       */
1357       virtual UBool requireEnd() const;
1358 
1359 
1360    /**
1361     *    Returns the pattern that is interpreted by this matcher.
1362     *    @return  the RegexPattern for this RegexMatcher
1363     *    @stable ICU 2.4
1364     */
1365     virtual const RegexPattern &pattern() const;
1366 
1367 
1368    /**
1369     *    Replaces every substring of the input that matches the pattern
1370     *    with the given replacement string.  This is a convenience function that
1371     *    provides a complete find-and-replace-all operation.
1372     *
1373     *    This method first resets this matcher. It then scans the input string
1374     *    looking for matches of the pattern. Input that is not part of any
1375     *    match is left unchanged; each match is replaced in the result by the
1376     *    replacement string. The replacement string may contain references to
1377     *    capture groups.
1378     *
1379     *    @param   replacement a string containing the replacement text.
1380     *    @param   status      a reference to a UErrorCode to receive any errors.
1381     *    @return              a string containing the results of the find and replace.
1382     *    @stable ICU 2.4
1383     */
1384     virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);
1385 
1386 
1387    /**
1388     *    Replaces every substring of the input that matches the pattern
1389     *    with the given replacement string.  This is a convenience function that
1390     *    provides a complete find-and-replace-all operation.
1391     *
1392     *    This method first resets this matcher. It then scans the input string
1393     *    looking for matches of the pattern. Input that is not part of any
1394     *    match is left unchanged; each match is replaced in the result by the
1395     *    replacement string. The replacement string may contain references to
1396     *    capture groups.
1397     *
1398     *    @param   replacement a string containing the replacement text.
1399     *    @param   dest        a mutable UText in which the results are placed.
1400     *                          If NULL, a new UText will be created (which may not be mutable).
1401     *    @param   status      a reference to a UErrorCode to receive any errors.
1402     *    @return              a string containing the results of the find and replace.
1403     *                          If a pre-allocated UText was provided, it will always be used and returned.
1404     *
1405     *    @stable ICU 4.6
1406     */
1407     virtual UText *replaceAll(UText *replacement, UText *dest, UErrorCode &status);
1408 
1409 
1410    /**
1411     * Replaces the first substring of the input that matches
1412     * the pattern with the replacement string.   This is a convenience
1413     * function that provides a complete find-and-replace operation.
1414     *
1415     * <p>This function first resets this RegexMatcher. It then scans the input string
1416     * looking for a match of the pattern. Input that is not part
1417     * of the match is appended directly to the result string; the match is replaced
1418     * in the result by the replacement string. The replacement string may contain
1419     * references to captured groups.</p>
1420     *
1421     * <p>The state of the matcher (the position at which a subsequent find()
1422     *    would begin) after completing a replaceFirst() is not specified.  The
1423     *    RegexMatcher should be reset before doing additional find() operations.</p>
1424     *
1425     *    @param   replacement a string containing the replacement text.
1426     *    @param   status      a reference to a UErrorCode to receive any errors.
1427     *    @return              a string containing the results of the find and replace.
1428     *    @stable ICU 2.4
1429     */
1430     virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status);
1431 
1432 
1433    /**
1434     * Replaces the first substring of the input that matches
1435     * the pattern with the replacement string.   This is a convenience
1436     * function that provides a complete find-and-replace operation.
1437     *
1438     * <p>This function first resets this RegexMatcher. It then scans the input string
1439     * looking for a match of the pattern. Input that is not part
1440     * of the match is appended directly to the result string; the match is replaced
1441     * in the result by the replacement string. The replacement string may contain
1442     * references to captured groups.</p>
1443     *
1444     * <p>The state of the matcher (the position at which a subsequent find()
1445     *    would begin) after completing a replaceFirst() is not specified.  The
1446     *    RegexMatcher should be reset before doing additional find() operations.</p>
1447     *
1448     *    @param   replacement a string containing the replacement text.
1449     *    @param   dest        a mutable UText in which the results are placed.
1450     *                          If NULL, a new UText will be created (which may not be mutable).
1451     *    @param   status      a reference to a UErrorCode to receive any errors.
1452     *    @return              a string containing the results of the find and replace.
1453     *                          If a pre-allocated UText was provided, it will always be used and returned.
1454     *
1455     *    @stable ICU 4.6
1456     */
1457     virtual UText *replaceFirst(UText *replacement, UText *dest, UErrorCode &status);
1458 
1459 
1460    /**
1461     *   Implements a replace operation intended to be used as part of an
1462     *   incremental find-and-replace.
1463     *
1464     *   <p>The input string, starting from the end of the previous replacement and ending at
1465     *   the start of the current match, is appended to the destination string.  Then the
1466     *   replacement string is appended to the output string,
1467     *   including handling any substitutions of captured text.</p>
1468     *
1469     *   <p>For simple, prepackaged, non-incremental find-and-replace
1470     *   operations, see replaceFirst() or replaceAll().</p>
1471     *
1472     *   @param   dest        A UnicodeString to which the results of the find-and-replace are appended.
1473     *   @param   replacement A UnicodeString that provides the text to be substituted for
1474     *                        the input text that matched the regexp pattern.  The replacement
1475     *                        text may contain references to captured text from the
1476     *                        input.
1477     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible
1478     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1479     *                        attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR
1480     *                        if the replacement text specifies a capture group that
1481     *                        does not exist in the pattern.
1482     *
1483     *   @return  this  RegexMatcher
1484     *   @stable ICU 2.4
1485     *
1486     */
1487     virtual RegexMatcher &appendReplacement(UnicodeString &dest,
1488         const UnicodeString &replacement, UErrorCode &status);
1489 
1490 
1491    /**
1492     *   Implements a replace operation intended to be used as part of an
1493     *   incremental find-and-replace.
1494     *
1495     *   <p>The input string, starting from the end of the previous replacement and ending at
1496     *   the start of the current match, is appended to the destination string.  Then the
1497     *   replacement string is appended to the output string,
1498     *   including handling any substitutions of captured text.</p>
1499     *
1500     *   <p>For simple, prepackaged, non-incremental find-and-replace
1501     *   operations, see replaceFirst() or replaceAll().</p>
1502     *
1503     *   @param   dest        A mutable UText to which the results of the find-and-replace are appended.
1504     *                         Must not be NULL.
1505     *   @param   replacement A UText that provides the text to be substituted for
1506     *                        the input text that matched the regexp pattern.  The replacement
1507     *                        text may contain references to captured text from the input.
1508     *   @param   status      A reference to a UErrorCode to receive any errors.  Possible
1509     *                        errors are  U_REGEX_INVALID_STATE if no match has been
1510     *                        attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR
1511     *                        if the replacement text specifies a capture group that
1512     *                        does not exist in the pattern.
1513     *
1514     *   @return  this  RegexMatcher
1515     *
1516     *   @stable ICU 4.6
1517     */
1518     virtual RegexMatcher &appendReplacement(UText *dest,
1519         UText *replacement, UErrorCode &status);
1520 
1521 
1522    /**
1523     * As the final step in a find-and-replace operation, append the remainder
1524     * of the input string, starting at the position following the last appendReplacement(),
1525     * to the destination string. <code>appendTail()</code> is intended to be invoked after one
1526     * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.
1527     *
1528     *  @param dest A UnicodeString to which the results of the find-and-replace are appended.
1529     *  @return  the destination string.
1530     *  @stable ICU 2.4
1531     */
1532     virtual UnicodeString &appendTail(UnicodeString &dest);
1533 
1534 
1535    /**
1536     * As the final step in a find-and-replace operation, append the remainder
1537     * of the input string, starting at the position following the last appendReplacement(),
1538     * to the destination string. <code>appendTail()</code> is intended to be invoked after one
1539     * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.
1540     *
1541     *  @param dest A mutable UText to which the results of the find-and-replace are appended.
1542     *               Must not be NULL.
1543     *  @param status error cod
1544     *  @return  the destination string.
1545     *
1546     *  @stable ICU 4.6
1547     */
1548     virtual UText *appendTail(UText *dest, UErrorCode &status);
1549 
1550 
1551     /**
1552      * Split a string into fields.  Somewhat like split() from Perl.
1553      * The pattern matches identify delimiters that separate the input
1554      *  into fields.  The input data between the matches becomes the
1555      *  fields themselves.
1556      *
1557      * @param input   The string to be split into fields.  The field delimiters
1558      *                match the pattern (in the "this" object).  This matcher
1559      *                will be reset to this input string.
1560      * @param dest    An array of UnicodeStrings to receive the results of the split.
1561      *                This is an array of actual UnicodeString objects, not an
1562      *                array of pointers to strings.  Local (stack based) arrays can
1563      *                work well here.
1564      * @param destCapacity  The number of elements in the destination array.
1565      *                If the number of fields found is less than destCapacity, the
1566      *                extra strings in the destination array are not altered.
1567      *                If the number of destination strings is less than the number
1568      *                of fields, the trailing part of the input string, including any
1569      *                field delimiters, is placed in the last destination string.
1570      * @param status  A reference to a UErrorCode to receive any errors.
1571      * @return        The number of fields into which the input string was split.
1572      * @stable ICU 2.6
1573      */
1574     virtual int32_t  split(const UnicodeString &input,
1575         UnicodeString    dest[],
1576         int32_t          destCapacity,
1577         UErrorCode       &status);
1578 
1579 
1580     /**
1581      * Split a string into fields.  Somewhat like split() from Perl.
1582      * The pattern matches identify delimiters that separate the input
1583      *  into fields.  The input data between the matches becomes the
1584      *  fields themselves.
1585      *
1586      * @param input   The string to be split into fields.  The field delimiters
1587      *                match the pattern (in the "this" object).  This matcher
1588      *                will be reset to this input string.
1589      * @param dest    An array of mutable UText structs to receive the results of the split.
1590      *                If a field is NULL, a new UText is allocated to contain the results for
1591      *                that field. This new UText is not guaranteed to be mutable.
1592      * @param destCapacity  The number of elements in the destination array.
1593      *                If the number of fields found is less than destCapacity, the
1594      *                extra strings in the destination array are not altered.
1595      *                If the number of destination strings is less than the number
1596      *                of fields, the trailing part of the input string, including any
1597      *                field delimiters, is placed in the last destination string.
1598      * @param status  A reference to a UErrorCode to receive any errors.
1599      * @return        The number of fields into which the input string was split.
1600      *
1601      * @stable ICU 4.6
1602      */
1603     virtual int32_t  split(UText *input,
1604         UText           *dest[],
1605         int32_t          destCapacity,
1606         UErrorCode       &status);
1607 
1608   /**
1609     *   Set a processing time limit for match operations with this Matcher.
1610     *
1611     *   Some patterns, when matching certain strings, can run in exponential time.
1612     *   For practical purposes, the match operation may appear to be in an
1613     *   infinite loop.
1614     *   When a limit is set a match operation will fail with an error if the
1615     *   limit is exceeded.
1616     *   <p>
1617     *   The units of the limit are steps of the match engine.
1618     *   Correspondence with actual processor time will depend on the speed
1619     *   of the processor and the details of the specific pattern, but will
1620     *   typically be on the order of milliseconds.
1621     *   <p>
1622     *   By default, the matching time is not limited.
1623     *   <p>
1624     *
1625     *   @param   limit       The limit value, or 0 for no limit.
1626     *   @param   status      A reference to a UErrorCode to receive any errors.
1627     *   @stable ICU 4.0
1628     */
1629     virtual void setTimeLimit(int32_t limit, UErrorCode &status);
1630 
1631   /**
1632     * Get the time limit, if any, for match operations made with this Matcher.
1633     *
1634     *   @return the maximum allowed time for a match, in units of processing steps.
1635     *   @stable ICU 4.0
1636     */
1637     virtual int32_t getTimeLimit() const;
1638 
1639   /**
1640     *  Set the amount of heap storage available for use by the match backtracking stack.
1641     *  The matcher is also reset, discarding any results from previous matches.
1642     *  <p>
1643     *  ICU uses a backtracking regular expression engine, with the backtrack stack
1644     *  maintained on the heap.  This function sets the limit to the amount of memory
1645     *  that can be used  for this purpose.  A backtracking stack overflow will
1646     *  result in an error from the match operation that caused it.
1647     *  <p>
1648     *  A limit is desirable because a malicious or poorly designed pattern can use
1649     *  excessive memory, potentially crashing the process.  A limit is enabled
1650     *  by default.
1651     *  <p>
1652     *  @param limit  The maximum size, in bytes, of the matching backtrack stack.
1653     *                A value of zero means no limit.
1654     *                The limit must be greater or equal to zero.
1655     *
1656     *  @param status   A reference to a UErrorCode to receive any errors.
1657     *
1658     *  @stable ICU 4.0
1659     */
1660     virtual void setStackLimit(int32_t  limit, UErrorCode &status);
1661 
1662   /**
1663     *  Get the size of the heap storage available for use by the back tracking stack.
1664     *
1665     *  @return  the maximum backtracking stack size, in bytes, or zero if the
1666     *           stack size is unlimited.
1667     *  @stable ICU 4.0
1668     */
1669     virtual int32_t  getStackLimit() const;
1670 
1671 
1672   /**
1673     * Set a callback function for use with this Matcher.
1674     * During matching operations the function will be called periodically,
1675     * giving the application the opportunity to terminate a long-running
1676     * match.
1677     *
1678     *    @param   callback    A pointer to the user-supplied callback function.
1679     *    @param   context     User context pointer.  The value supplied at the
1680     *                         time the callback function is set will be saved
1681     *                         and passed to the callback each time that it is called.
1682     *    @param   status      A reference to a UErrorCode to receive any errors.
1683     *  @stable ICU 4.0
1684     */
1685     virtual void setMatchCallback(URegexMatchCallback     *callback,
1686                                   const void              *context,
1687                                   UErrorCode              &status);
1688 
1689 
1690   /**
1691     *  Get the callback function for this URegularExpression.
1692     *
1693     *    @param   callback    Out parameter, receives a pointer to the user-supplied
1694     *                         callback function.
1695     *    @param   context     Out parameter, receives the user context pointer that
1696     *                         was set when uregex_setMatchCallback() was called.
1697     *    @param   status      A reference to a UErrorCode to receive any errors.
1698     *    @stable ICU 4.0
1699     */
1700     virtual void getMatchCallback(URegexMatchCallback     *&callback,
1701                                   const void              *&context,
1702                                   UErrorCode              &status);
1703 
1704 
1705   /**
1706     * Set a progress callback function for use with find operations on this Matcher.
1707     * During find operations, the callback will be invoked after each return from a
1708     * match attempt, giving the application the opportunity to terminate a long-running
1709     * find operation.
1710     *
1711     *    @param   callback    A pointer to the user-supplied callback function.
1712     *    @param   context     User context pointer.  The value supplied at the
1713     *                         time the callback function is set will be saved
1714     *                         and passed to the callback each time that it is called.
1715     *    @param   status      A reference to a UErrorCode to receive any errors.
1716     *    @stable ICU 4.6
1717     */
1718     virtual void setFindProgressCallback(URegexFindProgressCallback      *callback,
1719                                               const void                              *context,
1720                                               UErrorCode                              &status);
1721 
1722 
1723   /**
1724     *  Get the find progress callback function for this URegularExpression.
1725     *
1726     *    @param   callback    Out parameter, receives a pointer to the user-supplied
1727     *                         callback function.
1728     *    @param   context     Out parameter, receives the user context pointer that
1729     *                         was set when uregex_setFindProgressCallback() was called.
1730     *    @param   status      A reference to a UErrorCode to receive any errors.
1731     *    @stable ICU 4.6
1732     */
1733     virtual void getFindProgressCallback(URegexFindProgressCallback      *&callback,
1734                                               const void                      *&context,
1735                                               UErrorCode                      &status);
1736 
1737 #ifndef U_HIDE_INTERNAL_API
1738    /**
1739      *   setTrace   Debug function, enable/disable tracing of the matching engine.
1740      *              For internal ICU development use only.  DO NO USE!!!!
1741      *   @internal
1742      */
1743     void setTrace(UBool state);
1744 #endif  /* U_HIDE_INTERNAL_API */
1745 
1746     /**
1747     * ICU "poor man's RTTI", returns a UClassID for this class.
1748     *
1749     * @stable ICU 2.2
1750     */
1751     static UClassID U_EXPORT2 getStaticClassID();
1752 
1753     /**
1754      * ICU "poor man's RTTI", returns a UClassID for the actual class.
1755      *
1756      * @stable ICU 2.2
1757      */
1758     virtual UClassID getDynamicClassID() const;
1759 
1760 private:
1761     // Constructors and other object boilerplate are private.
1762     // Instances of RegexMatcher can not be assigned, copied, cloned, etc.
1763     RegexMatcher();                  // default constructor not implemented
1764     RegexMatcher(const RegexPattern *pat);
1765     RegexMatcher(const RegexMatcher &other);
1766     RegexMatcher &operator =(const RegexMatcher &rhs);
1767     void init(UErrorCode &status);                      // Common initialization
1768     void init2(UText *t, UErrorCode &e);  // Common initialization, part 2.
1769 
1770     friend class RegexPattern;
1771     friend class RegexCImpl;
1772 public:
1773 #ifndef U_HIDE_INTERNAL_API
1774     /** @internal  */
1775     void resetPreserveRegion();  // Reset matcher state, but preserve any region.
1776 #endif  /* U_HIDE_INTERNAL_API */
1777 private:
1778 
1779     //
1780     //  MatchAt   This is the internal interface to the match engine itself.
1781     //            Match status comes back in matcher member variables.
1782     //
1783     void                 MatchAt(int64_t startIdx, UBool toEnd, UErrorCode &status);
1784     inline void          backTrack(int64_t &inputIdx, int32_t &patIdx);
1785     UBool                isWordBoundary(int64_t pos);         // perform Perl-like  \b test
1786     UBool                isUWordBoundary(int64_t pos);        // perform RBBI based \b test
1787     REStackFrame        *resetStack();
1788     inline REStackFrame *StateSave(REStackFrame *fp, int64_t savePatIdx, UErrorCode &status);
1789     void                 IncrementTime(UErrorCode &status);
1790 
1791     // Call user find callback function, if set. Return TRUE if operation should be interrupted.
1792     inline UBool         findProgressInterrupt(int64_t matchIndex, UErrorCode &status);
1793 
1794     int64_t              appendGroup(int32_t groupNum, UText *dest, UErrorCode &status) const;
1795 
1796     UBool                findUsingChunk(UErrorCode &status);
1797     void                 MatchChunkAt(int32_t startIdx, UBool toEnd, UErrorCode &status);
1798     UBool                isChunkWordBoundary(int32_t pos);
1799 
1800     const RegexPattern  *fPattern;
1801     RegexPattern        *fPatternOwned;    // Non-NULL if this matcher owns the pattern, and
1802                                            //   should delete it when through.
1803 
1804     const UnicodeString *fInput;           // The string being matched. Only used for input()
1805     UText               *fInputText;       // The text being matched. Is never NULL.
1806     UText               *fAltInputText;    // A shallow copy of the text being matched.
1807                                            //   Only created if the pattern contains backreferences.
1808     int64_t              fInputLength;     // Full length of the input text.
1809     int32_t              fFrameSize;       // The size of a frame in the backtrack stack.
1810 
1811     int64_t              fRegionStart;     // Start of the input region, default = 0.
1812     int64_t              fRegionLimit;     // End of input region, default to input.length.
1813 
1814     int64_t              fAnchorStart;     // Region bounds for anchoring operations (^ or $).
1815     int64_t              fAnchorLimit;     //   See useAnchoringBounds
1816 
1817     int64_t              fLookStart;       // Region bounds for look-ahead/behind and
1818     int64_t              fLookLimit;       //   and other boundary tests.  See
1819                                            //   useTransparentBounds
1820 
1821     int64_t              fActiveStart;     // Currently active bounds for matching.
1822     int64_t              fActiveLimit;     //   Usually is the same as region, but
1823                                            //   is changed to fLookStart/Limit when
1824                                            //   entering look around regions.
1825 
1826     UBool                fTransparentBounds;  // True if using transparent bounds.
1827     UBool                fAnchoringBounds; // True if using anchoring bounds.
1828 
1829     UBool                fMatch;           // True if the last attempted match was successful.
1830     int64_t              fMatchStart;      // Position of the start of the most recent match
1831     int64_t              fMatchEnd;        // First position after the end of the most recent match
1832                                            //   Zero if no previous match, even when a region
1833                                            //   is active.
1834     int64_t              fLastMatchEnd;    // First position after the end of the previous match,
1835                                            //   or -1 if there was no previous match.
1836     int64_t              fAppendPosition;  // First position after the end of the previous
1837                                            //   appendReplacement().  As described by the
1838                                            //   JavaDoc for Java Matcher, where it is called
1839                                            //   "append position"
1840     UBool                fHitEnd;          // True if the last match touched the end of input.
1841     UBool                fRequireEnd;      // True if the last match required end-of-input
1842                                            //    (matched $ or Z)
1843 
1844     UVector64           *fStack;
1845     REStackFrame        *fFrame;           // After finding a match, the last active stack frame,
1846                                            //   which will contain the capture group results.
1847                                            //   NOT valid while match engine is running.
1848 
1849     int64_t             *fData;            // Data area for use by the compiled pattern.
1850     int64_t             fSmallData[8];     //   Use this for data if it's enough.
1851 
1852     int32_t             fTimeLimit;        // Max time (in arbitrary steps) to let the
1853                                            //   match engine run.  Zero for unlimited.
1854 
1855     int32_t             fTime;             // Match time, accumulates while matching.
1856     int32_t             fTickCounter;      // Low bits counter for time.  Counts down StateSaves.
1857                                            //   Kept separately from fTime to keep as much
1858                                            //   code as possible out of the inline
1859                                            //   StateSave function.
1860 
1861     int32_t             fStackLimit;       // Maximum memory size to use for the backtrack
1862                                            //   stack, in bytes.  Zero for unlimited.
1863 
1864     URegexMatchCallback *fCallbackFn;       // Pointer to match progress callback funct.
1865                                            //   NULL if there is no callback.
1866     const void         *fCallbackContext;  // User Context ptr for callback function.
1867 
1868     URegexFindProgressCallback  *fFindProgressCallbackFn;  // Pointer to match progress callback funct.
1869                                                            //   NULL if there is no callback.
1870     const void         *fFindProgressCallbackContext;      // User Context ptr for callback function.
1871 
1872 
1873     UBool               fInputUniStrMaybeMutable;  // Set when fInputText wraps a UnicodeString that may be mutable - compatibility.
1874 
1875     UBool               fTraceDebug;       // Set true for debug tracing of match engine.
1876 
1877     UErrorCode          fDeferredStatus;   // Save error state that cannot be immediately
1878                                            //   reported, or that permanently disables this matcher.
1879 
1880     RuleBasedBreakIterator  *fWordBreakItr;
1881 };
1882 
1883 U_NAMESPACE_END
1884 #endif  // UCONFIG_NO_REGULAR_EXPRESSIONS
1885 #endif
1886