| /* |
| ********************************************************************** |
| * Copyright (C) 2002-2008, International Business Machines |
| * Corporation and others. All Rights Reserved. |
| ********************************************************************** |
| * file name: regex.h |
| * encoding: US-ASCII |
| * indentation:4 |
| * |
| * created on: 2002oct22 |
| * created by: Andy Heninger |
| * |
| * ICU Regular Expressions, API for C++ |
| */ |
| |
| #ifndef REGEX_H |
| #define REGEX_H |
| |
| //#define REGEX_DEBUG |
| |
| /** |
| * \file |
| * \brief C++ API: Regular Expressions |
| * |
| * <h2>Regular Expression API</h2> |
| * |
| * <p>The ICU API for processing regular expressions consists of two classes, |
| * <code>RegexPattern</code> and <code>RegexMatcher</code>. |
| * <code>RegexPattern</code> objects represent a pre-processed, or compiled |
| * regular expression. They are created from a regular expression pattern string, |
| * and can be used to create <code>RegexMatcher</code> objects for the pattern.</p> |
| * |
| * <p>Class <code>RegexMatcher</code> bundles together a regular expression |
| * pattern and a target string to which the search pattern will be applied. |
| * <code>RegexMatcher</code> includes API for doing plain find or search |
| * operations, for search and replace operations, and for obtaining detailed |
| * information about bounds of a match. </p> |
| * |
| * <p>Note that by constructing <code>RegexMatcher</code> objects directly from regular |
| * expression pattern strings application code can be simplified and the explicit |
| * need for <code>RegexPattern</code> objects can usually be eliminated. |
| * </p> |
| */ |
| |
| #include "unicode/utypes.h" |
| |
| #if !UCONFIG_NO_REGULAR_EXPRESSIONS |
| |
| #include "unicode/uobject.h" |
| #include "unicode/unistr.h" |
| #include "unicode/parseerr.h" |
| |
| #include "unicode/uregex.h" |
| |
| U_NAMESPACE_BEGIN |
| |
| |
| // Forward Declarations... |
| |
| class RegexMatcher; |
| class RegexPattern; |
| class UVector; |
| class UVector32; |
| class UnicodeSet; |
| struct REStackFrame; |
| struct Regex8BitSet; |
| class RuleBasedBreakIterator; |
| class RegexCImpl; |
| |
| |
| |
| |
| /** |
| * RBBIPatternDump Debug function, displays the compiled form of a pattern. |
| * @internal |
| */ |
| #ifdef REGEX_DEBUG |
| U_INTERNAL void U_EXPORT2 |
| RegexPatternDump(const RegexPattern *pat); |
| #else |
| #define RegexPatternDump(pat) |
| #endif |
| |
| |
| |
| /** |
| * Class <code>RegexPattern</code> represents a compiled regular expression. It includes |
| * factory methods for creating a RegexPattern object from the source (string) form |
| * of a regular expression, methods for creating RegexMatchers that allow the pattern |
| * to be applied to input text, and a few convenience methods for simple common |
| * uses of regular expressions. |
| * |
| * <p>Class RegexPattern is not intended to be subclassed.</p> |
| * |
| * @stable ICU 2.4 |
| */ |
| class U_I18N_API RegexPattern: public UObject { |
| public: |
| |
| /** |
| * default constructor. Create a RegexPattern object that refers to no actual |
| * pattern. Not normally needed; RegexPattern objects are usually |
| * created using the factory method <code>compile()</code>. |
| * |
| * @stable ICU 2.4 |
| */ |
| RegexPattern(); |
| |
| /** |
| * Copy Constructor. Create a new RegexPattern object that is equivalent |
| * to the source object. |
| * @param source the pattern object to be copied. |
| * @stable ICU 2.4 |
| */ |
| RegexPattern(const RegexPattern &source); |
| |
| /** |
| * Destructor. Note that a RegexPattern object must persist so long as any |
| * RegexMatcher objects that were created from the RegexPattern are active. |
| * @stable ICU 2.4 |
| */ |
| virtual ~RegexPattern(); |
| |
| /** |
| * Comparison operator. Two RegexPattern objects are considered equal if they |
| * were constructed from identical source patterns using the same match flag |
| * settings. |
| * @param that a RegexPattern object to compare with "this". |
| * @return TRUE if the objects are equivalent. |
| * @stable ICU 2.4 |
| */ |
| UBool operator==(const RegexPattern& that) const; |
| |
| /** |
| * Comparison operator. Two RegexPattern objects are considered equal if they |
| * were constructed from identical source patterns using the same match flag |
| * settings. |
| * @param that a RegexPattern object to compare with "this". |
| * @return TRUE if the objects are different. |
| * @stable ICU 2.4 |
| */ |
| inline UBool operator!=(const RegexPattern& that) const {return ! operator ==(that);}; |
| |
| /** |
| * Assignment operator. After assignment, this RegexPattern will behave identically |
| * to the source object. |
| * @stable ICU 2.4 |
| */ |
| RegexPattern &operator =(const RegexPattern &source); |
| |
| /** |
| * Create an exact copy of this RegexPattern object. Since RegexPattern is not |
| * intended to be subclasses, <code>clone()</code> and the copy construction are |
| * equivalent operations. |
| * @return the copy of this RegexPattern |
| * @stable ICU 2.4 |
| */ |
| virtual RegexPattern *clone() const; |
| |
| |
| /** |
| * Compiles the regular expression in string form into a RegexPattern |
| * object. These compile methods, rather than the constructors, are the usual |
| * way that RegexPattern objects are created. |
| * |
| * <p>Note that RegexPattern objects must not be deleted while RegexMatcher |
| * objects created from the pattern are active. RegexMatchers keep a pointer |
| * back to their pattern, so premature deletion of the pattern is a |
| * catastrophic error.</p> |
| * |
| * <p>All pattern match mode flags are set to their default values.</p> |
| * |
| * <p>Note that it is often more convenient to construct a RegexMatcher directly |
| * from a pattern string rather than separately compiling the pattern and |
| * then creating a RegexMatcher object from the pattern.</p> |
| * |
| * @param regex The regular expression to be compiled. |
| * @param pe Receives the position (line and column nubers) of any error |
| * within the regular expression.) |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return A regexPattern object for the compiled pattern. |
| * |
| * @stable ICU 2.4 |
| */ |
| static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex, |
| UParseError &pe, |
| UErrorCode &status); |
| |
| /** |
| * Compiles the regular expression in string form into a RegexPattern |
| * object using the specified match mode flags. These compile methods, |
| * rather than the constructors, are the usual way that RegexPattern objects |
| * are created. |
| * |
| * <p>Note that RegexPattern objects must not be deleted while RegexMatcher |
| * objects created from the pattern are active. RegexMatchers keep a pointer |
| * back to their pattern, so premature deletion of the pattern is a |
| * catastrophic error.</p> |
| * |
| * <p>Note that it is often more convenient to construct a RegexMatcher directly |
| * from a pattern string instead of than separately compiling the pattern and |
| * then creating a RegexMatcher object from the pattern.</p> |
| * |
| * @param regex The regular expression to be compiled. |
| * @param flags The match mode flags to be used. |
| * @param pe Receives the position (line and column nubers) of any error |
| * within the regular expression.) |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return A regexPattern object for the compiled pattern. |
| * |
| * @stable ICU 2.4 |
| */ |
| static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex, |
| uint32_t flags, |
| UParseError &pe, |
| UErrorCode &status); |
| |
| |
| /** |
| * Compiles the regular expression in string form into a RegexPattern |
| * object using the specified match mode flags. These compile methods, |
| * rather than the constructors, are the usual way that RegexPattern objects |
| * are created. |
| * |
| * <p>Note that RegexPattern objects must not be deleted while RegexMatcher |
| * objects created from the pattern are active. RegexMatchers keep a pointer |
| * back to their pattern, so premature deletion of the pattern is a |
| * catastrophic error.</p> |
| * |
| * <p>Note that it is often more convenient to construct a RegexMatcher directly |
| * from a pattern string instead of than separately compiling the pattern and |
| * then creating a RegexMatcher object from the pattern.</p> |
| * |
| * @param regex The regular expression to be compiled. |
| * @param flags The match mode flags to be used. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return A regexPattern object for the compiled pattern. |
| * |
| * @stable ICU 2.6 |
| */ |
| static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex, |
| uint32_t flags, |
| UErrorCode &status); |
| |
| |
| /** |
| * Get the match mode flags that were used when compiling this pattern. |
| * @return the match mode flags |
| * @stable ICU 2.4 |
| */ |
| virtual uint32_t flags() const; |
| |
| /** |
| * Creates a RegexMatcher that will match the given input against this pattern. The |
| * RegexMatcher can then be used to perform match, find or replace operations |
| * on the input. Note that a RegexPattern object must not be deleted while |
| * RegexMatchers created from it still exist and might possibly be used again. |
| * <p> |
| * The matcher will retain a reference to the supplied input string, and all regexp |
| * pattern matching operations happen directly on this original string. It is |
| * critical that the string not be altered or deleted before use by the regular |
| * expression operations is complete. |
| * |
| * @param input The input string to which the regular expression will be applied. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return A RegexMatcher object for this pattern and input. |
| * |
| * @stable ICU 2.4 |
| */ |
| virtual RegexMatcher *matcher(const UnicodeString &input, |
| UErrorCode &status) const; |
| |
| private: |
| /** |
| * Cause a compilation error if an application accidently attempts to |
| * create a matcher with a (UChar *) string as input rather than |
| * a UnicodeString. Avoids a dangling reference to a temporary string. |
| * <p> |
| * To efficiently work with UChar *strings, wrap the data in a UnicodeString |
| * using one of the aliasing constructors, such as |
| * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code> |
| * |
| * @internal |
| */ |
| RegexMatcher *matcher(const UChar *input, |
| UErrorCode &status) const; |
| public: |
| |
| |
| /** |
| * Creates a RegexMatcher that will match against this pattern. The |
| * RegexMatcher can be used to perform match, find or replace operations. |
| * Note that a RegexPattern object must not be deleted while |
| * RegexMatchers created from it still exist and might possibly be used again. |
| * |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return A RegexMatcher object for this pattern and input. |
| * |
| * @stable ICU 2.6 |
| */ |
| virtual RegexMatcher *matcher(UErrorCode &status) const; |
| |
| |
| /** |
| * Test whether a string matches a regular expression. This convenience function |
| * both compiles the reguluar expression and applies it in a single operation. |
| * Note that if the same pattern needs to be applied repeatedly, this method will be |
| * less efficient than creating and reusing a RegexMatcher object. |
| * |
| * @param regex The regular expression |
| * @param input The string data to be matched |
| * @param pe Receives the position of any syntax errors within the regular expression |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return True if the regular expression exactly matches the full input string. |
| * |
| * @stable ICU 2.4 |
| */ |
| static UBool U_EXPORT2 matches(const UnicodeString ®ex, |
| const UnicodeString &input, |
| UParseError &pe, |
| UErrorCode &status); |
| |
| |
| /** |
| * Returns the regular expression from which this pattern was compiled. |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString pattern() const; |
| |
| |
| /** |
| * Split a string into fields. Somewhat like split() from Perl. |
| * The pattern matches identify delimiters that separate the input |
| * into fields. The input data between the matches becomes the |
| * fields themselves. |
| * <p> |
| * For the best performance on split() operations, |
| * <code>RegexMatcher::split</code> is perferable to this function |
| * |
| * @param input The string to be split into fields. The field delimiters |
| * match the pattern (in the "this" object) |
| * @param dest An array of UnicodeStrings to receive the results of the split. |
| * This is an array of actual UnicodeString objects, not an |
| * array of pointers to strings. Local (stack based) arrays can |
| * work well here. |
| * @param destCapacity The number of elements in the destination array. |
| * If the number of fields found is less than destCapacity, the |
| * extra strings in the destination array are not altered. |
| * If the number of destination strings is less than the number |
| * of fields, the trailing part of the input string, including any |
| * field delimiters, is placed in the last destination string. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return The number of fields into which the input string was split. |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t split(const UnicodeString &input, |
| UnicodeString dest[], |
| int32_t destCapacity, |
| UErrorCode &status) const; |
| |
| |
| /** |
| * ICU "poor man's RTTI", returns a UClassID for the actual class. |
| * |
| * @stable ICU 2.4 |
| */ |
| virtual UClassID getDynamicClassID() const; |
| |
| /** |
| * ICU "poor man's RTTI", returns a UClassID for this class. |
| * |
| * @stable ICU 2.4 |
| */ |
| static UClassID U_EXPORT2 getStaticClassID(); |
| |
| private: |
| // |
| // Implementation Data |
| // |
| UnicodeString fPattern; // The original pattern string. |
| uint32_t fFlags; // The flags used when compiling the pattern. |
| // |
| UVector32 *fCompiledPat; // The compiled pattern p-code. |
| UnicodeString fLiteralText; // Any literal string data from the pattern, |
| // after un-escaping, for use during the match. |
| |
| UVector *fSets; // Any UnicodeSets referenced from the pattern. |
| Regex8BitSet *fSets8; // (and fast sets for latin-1 range.) |
| |
| |
| UErrorCode fDeferredStatus; // status if some prior error has left this |
| // RegexPattern in an unusable state. |
| |
| int32_t fMinMatchLen; // Minimum Match Length. All matches will have length |
| // >= this value. For some patterns, this calculated |
| // value may be less than the true shortest |
| // possible match. |
| |
| int32_t fFrameSize; // Size of a state stack frame in the |
| // execution engine. |
| |
| int32_t fDataSize; // The size of the data needed by the pattern that |
| // does not go on the state stack, but has just |
| // a single copy per matcher. |
| |
| UVector32 *fGroupMap; // Map from capture group number to position of |
| // the group's variables in the matcher stack frame. |
| |
| int32_t fMaxCaptureDigits; |
| |
| UnicodeSet **fStaticSets; // Ptr to static (shared) sets for predefined |
| // regex character classes, e.g. Word. |
| |
| Regex8BitSet *fStaticSets8; // Ptr to the static (shared) latin-1 only |
| // sets for predefined regex classes. |
| |
| int32_t fStartType; // Info on how a match must start. |
| int32_t fInitialStringIdx; // |
| int32_t fInitialStringLen; |
| UnicodeSet *fInitialChars; |
| UChar32 fInitialChar; |
| Regex8BitSet *fInitialChars8; |
| |
| friend class RegexCompile; |
| friend class RegexMatcher; |
| friend class RegexCImpl; |
| |
| // |
| // Implementation Methods |
| // |
| void init(); // Common initialization, for use by constructors. |
| void zap(); // Common cleanup |
| #ifdef REGEX_DEBUG |
| void dumpOp(int32_t index) const; |
| friend void U_EXPORT2 RegexPatternDump(const RegexPattern *); |
| #endif |
| |
| }; |
| |
| |
| |
| /** |
| * class RegexMatcher bundles together a reular expression pattern and |
| * input text to which the expression can be applied. It includes methods |
| * for testing for matches, and for find and replace operations. |
| * |
| * <p>Class RegexMatcher is not intended to be subclassed.</p> |
| * |
| * @stable ICU 2.4 |
| */ |
| class U_I18N_API RegexMatcher: public UObject { |
| public: |
| |
| /** |
| * Construct a RegexMatcher for a regular expression. |
| * This is a convenience method that avoids the need to explicitly create |
| * a RegexPattern object. Note that if several RegexMatchers need to be |
| * created for the same expression, it will be more efficient to |
| * separately create and cache a RegexPattern object, and use |
| * its matcher() method to create the RegexMatcher objects. |
| * |
| * @param regexp The Regular Expression to be compiled. |
| * @param flags Regular expression options, such as case insensitive matching. |
| * @see UREGEX_CASE_INSENSITIVE |
| * @param status Any errors are reported by setting this UErrorCode variable. |
| * @stable ICU 2.6 |
| */ |
| RegexMatcher(const UnicodeString ®exp, uint32_t flags, UErrorCode &status); |
| |
| /** |
| * Construct a RegexMatcher for a regular expression. |
| * This is a convenience method that avoids the need to explicitly create |
| * a RegexPattern object. Note that if several RegexMatchers need to be |
| * created for the same expression, it will be more efficient to |
| * separately create and cache a RegexPattern object, and use |
| * its matcher() method to create the RegexMatcher objects. |
| * <p> |
| * The matcher will retain a reference to the supplied input string, and all regexp |
| * pattern matching operations happen directly on the original string. It is |
| * critical that the string not be altered or deleted before use by the regular |
| * expression operations is complete. |
| * |
| * @param regexp The Regular Expression to be compiled. |
| * @param input The string to match. The matcher retains a reference to the |
| * caller's string; mo copy is made. |
| * @param flags Regular expression options, such as case insensitive matching. |
| * @see UREGEX_CASE_INSENSITIVE |
| * @param status Any errors are reported by setting this UErrorCode variable. |
| * @stable ICU 2.6 |
| */ |
| RegexMatcher(const UnicodeString ®exp, const UnicodeString &input, |
| uint32_t flags, UErrorCode &status); |
| |
| private: |
| /** |
| * Cause a compilation error if an application accidently attempts to |
| * create a matcher with a (UChar *) string as input rather than |
| * a UnicodeString. Avoids a dangling reference to a temporary string. |
| * <p> |
| * To efficiently work with UChar *strings, wrap the data in a UnicodeString |
| * using one of the aliasing constructors, such as |
| * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code> |
| * |
| * @internal |
| */ |
| RegexMatcher(const UnicodeString ®exp, const UChar *input, |
| uint32_t flags, UErrorCode &status); |
| public: |
| |
| |
| /** |
| * Destructor. |
| * |
| * @stable ICU 2.4 |
| */ |
| virtual ~RegexMatcher(); |
| |
| |
| /** |
| * Attempts to match the entire input region against the pattern. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return TRUE if there is a match |
| * @stable ICU 2.4 |
| */ |
| virtual UBool matches(UErrorCode &status); |
| |
| /** |
| * Resets the matcher, then attempts to match the input beginning |
| * at the specified startIndex, and extending to the end of the input. |
| * The input region is reset to include the entire input string. |
| * A successful match must extend to the end of the input. |
| * @param startIndex The input string index at which to begin matching. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return TRUE if there is a match |
| * @stable ICU 2.8 |
| */ |
| virtual UBool matches(int32_t startIndex, UErrorCode &status); |
| |
| |
| |
| |
| /** |
| * Attempts to match the input string, starting from the beginning of the region, |
| * against the pattern. Like the matches() method, this function |
| * always starts at the beginning of the input region; |
| * unlike that function, it does not require that the entire region be matched. |
| * |
| * <p>If the match succeeds then more information can be obtained via the <code>start()</code>, |
| * <code>end()</code>, and <code>group()</code> functions.</p> |
| * |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return TRUE if there is a match at the start of the input string. |
| * @stable ICU 2.4 |
| */ |
| virtual UBool lookingAt(UErrorCode &status); |
| |
| |
| /** |
| * Attempts to match the input string, starting from the specified index, against the pattern. |
| * The match may be of any length, and is not required to extend to the end |
| * of the input string. Contrast with match(). |
| * |
| * <p>If the match succeeds then more information can be obtained via the <code>start()</code>, |
| * <code>end()</code>, and <code>group()</code> functions.</p> |
| * |
| * @param startIndex The input string index at which to begin matching. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return TRUE if there is a match. |
| * @stable ICU 2.8 |
| */ |
| virtual UBool lookingAt(int32_t startIndex, UErrorCode &status); |
| |
| /** |
| * Find the next pattern match in the input string. |
| * The find begins searching the input at the location following the end of |
| * the previous match, or at the start of the string if there is no previous match. |
| * If a match is found, <code>start(), end()</code> and <code>group()</code> |
| * will provide more information regarding the match. |
| * <p>Note that if the input string is changed by the application, |
| * use find(startPos, status) instead of find(), because the saved starting |
| * position may not be valid with the altered input string.</p> |
| * @return TRUE if a match is found. |
| * @stable ICU 2.4 |
| */ |
| virtual UBool find(); |
| |
| |
| /** |
| * Resets this RegexMatcher and then attempts to find the next substring of the |
| * input string that matches the pattern, starting at the specified index. |
| * |
| * @param start the position in the input string to begin the search |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return TRUE if a match is found. |
| * @stable ICU 2.4 |
| */ |
| virtual UBool find(int32_t start, UErrorCode &status); |
| |
| |
| /** |
| * Returns a string containing the text matched by the previous match. |
| * If the pattern can match an empty string, an empty string may be returned. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * Possible errors are U_REGEX_INVALID_STATE if no match |
| * has been attempted or the last match failed. |
| * @return a string containing the matched input text. |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString group(UErrorCode &status) const; |
| |
| |
| /** |
| * Returns a string containing the text captured by the given group |
| * during the previous match operation. Group(0) is the entire match. |
| * |
| * @param groupNum the capture group number |
| * @param status A reference to a UErrorCode to receive any errors. |
| * Possible errors are U_REGEX_INVALID_STATE if no match |
| * has been attempted or the last match failed and |
| * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number. |
| * @return the captured text |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const; |
| |
| |
| /** |
| * Returns the number of capturing groups in this matcher's pattern. |
| * @return the number of capture groups |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t groupCount() const; |
| |
| |
| /** |
| * Returns the index in the input string of the start of the text matched |
| * during the previous match operation. |
| * @param status a reference to a UErrorCode to receive any errors. |
| * @return The position in the input string of the start of the last match. |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t start(UErrorCode &status) const; |
| |
| |
| /** |
| * Returns the index in the input string of the start of the text matched by the |
| * specified capture group during the previous match operation. Return -1 if |
| * the capture group exists in the pattern, but was not part of the last match. |
| * |
| * @param group the capture group number |
| * @param status A reference to a UErrorCode to receive any errors. Possible |
| * errors are U_REGEX_INVALID_STATE if no match has been |
| * attempted or the last match failed, and |
| * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number |
| * @return the start position of substring matched by the specified group. |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t start(int32_t group, UErrorCode &status) const; |
| |
| |
| /** |
| * Returns the index in the input string of the first character following the |
| * text matched during the previous match operation. |
| * @param status A reference to a UErrorCode to receive any errors. Possible |
| * errors are U_REGEX_INVALID_STATE if no match has been |
| * attempted or the last match failed. |
| * @return the index of the last character matched, plus one. |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t end(UErrorCode &status) const; |
| |
| |
| /** |
| * Returns the index in the input string of the character following the |
| * text matched by the specified capture group during the previous match operation. |
| * @param group the capture group number |
| * @param status A reference to a UErrorCode to receive any errors. Possible |
| * errors are U_REGEX_INVALID_STATE if no match has been |
| * attempted or the last match failed and |
| * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number |
| * @return the index of the first character following the text |
| * captured by the specifed group during the previous match operation. |
| * Return -1 if the capture group exists in the pattern but was not part of the match. |
| * @stable ICU 2.4 |
| */ |
| virtual int32_t end(int32_t group, UErrorCode &status) const; |
| |
| |
| /** |
| * Resets this matcher. The effect is to remove any memory of previous matches, |
| * and to cause subsequent find() operations to begin at the beginning of |
| * the input string. |
| * |
| * @return this RegexMatcher. |
| * @stable ICU 2.4 |
| */ |
| virtual RegexMatcher &reset(); |
| |
| |
| /** |
| * Resets this matcher, and set the current input position. |
| * The effect is to remove any memory of previous matches, |
| * and to cause subsequent find() operations to begin at |
| * the specified position in the input string. |
| * <p> |
| * The matcher's region is reset to its default, which is the entire |
| * input string. |
| * <p> |
| * An alternative to this function is to set a match region |
| * beginning at the desired index. |
| * |
| * @return this RegexMatcher. |
| * @stable ICU 2.8 |
| */ |
| virtual RegexMatcher &reset(int32_t index, UErrorCode &status); |
| |
| |
| /** |
| * Resets this matcher with a new input string. This allows instances of RegexMatcher |
| * to be reused, which is more efficient than creating a new RegexMatcher for |
| * each input string to be processed. |
| * @param input The new string on which subsequent pattern matches will operate. |
| * The matcher retains a reference to the callers string, and operates |
| * directly on that. Ownership of the string remains with the caller. |
| * Because no copy of the string is made, it is essential that the |
| * caller not delete the string until after regexp operations on it |
| * are done. |
| * @return this RegexMatcher. |
| * @stable ICU 2.4 |
| */ |
| virtual RegexMatcher &reset(const UnicodeString &input); |
| |
| private: |
| /** |
| * Cause a compilation error if an application accidently attempts to |
| * reset a matcher with a (UChar *) string as input rather than |
| * a UnicodeString. Avoids a dangling reference to a temporary string. |
| * <p> |
| * To efficiently work with UChar *strings, wrap the data in a UnicodeString |
| * using one of the aliasing constructors, such as |
| * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code> |
| * |
| * @internal |
| */ |
| RegexMatcher &reset(const UChar *input); |
| public: |
| |
| /** |
| * Returns the input string being matched. The returned string is not a copy, |
| * but the live input string. It should not be altered or deleted. |
| * @return the input string |
| * @stable ICU 2.4 |
| */ |
| virtual const UnicodeString &input() const; |
| |
| |
| |
| /** Sets the limits of this matcher's region. |
| * The region is the part of the input string that will be searched to find a match. |
| * Invoking this method resets the matcher, and then sets the region to start |
| * at the index specified by the start parameter and end at the index specified |
| * by the end parameter. |
| * |
| * Depending on the transparency and anchoring being used (see useTransparentBounds |
| * and useAnchoringBounds), certain constructs such as anchors may behave differently |
| * at or around the boundaries of the region |
| * |
| * The function will fail if start is greater than limit, or if either index |
| * is less than zero or greater than the length of the string being matched. |
| * |
| * @param start The index to begin searches at. |
| * @param limit The index to end searches at (exclusive). |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @draft ICU 4.0 |
| */ |
| virtual RegexMatcher ®ion(int32_t start, int32_t limit, UErrorCode &status); |
| |
| |
| /** |
| * Reports the start index of this matcher's region. The searches this matcher |
| * conducts are limited to finding matches within regionStart (inclusive) and |
| * regionEnd (exclusive). |
| * |
| * @return The starting index of this matcher's region. |
| * @draft ICU 4.0 |
| */ |
| virtual int32_t regionStart() const; |
| |
| |
| /** |
| * Reports the end (limit) index (exclusive) of this matcher's region. The searches |
| * this matcher conducts are limited to finding matches within regionStart |
| * (inclusive) and regionEnd (exclusive). |
| * |
| * @return The ending point of this matcher's region. |
| * @draft ICU 4.0 |
| */ |
| virtual int32_t regionEnd() const; |
| |
| /** |
| * Queries the transparency of region bounds for this matcher. |
| * See useTransparentBounds for a description of transparent and opaque bounds. |
| * By default, a matcher uses opaque region boundaries. |
| * |
| * @return TRUE if this matcher is using opaque bounds, false if it is not. |
| * @draft ICU 4.0 |
| */ |
| virtual UBool hasTransparentBounds() const; |
| |
| /** |
| * Sets the transparency of region bounds for this matcher. |
| * Invoking this function with an argument of true will set this matcher to use transparent bounds. |
| * If the boolean argument is false, then opaque bounds will be used. |
| * |
| * Using transparent bounds, the boundaries of this matcher's region are transparent |
| * to lookahead, lookbehind, and boundary matching constructs. Those constructs can |
| * see text beyond the boundaries of the region while checking for a match. |
| * |
| * With opaque bounds, no text outside of the matcher's region is visible to lookahead, |
| * lookbehind, and boundary matching constructs. |
| * |
| * By default, a matcher uses opaque bounds. |
| * |
| * @param b TRUE for transparent bounds; FALSE for opaque bounds |
| * @return This Matcher; |
| * @draft ICU 4.0 |
| **/ |
| virtual RegexMatcher &useTransparentBounds(UBool b); |
| |
| |
| /** |
| * Return true if this matcher is using anchoring bounds. |
| * By default, matchers use anchoring region boounds. |
| * |
| * @return TRUE if this matcher is using anchoring bounds. |
| * @draft ICU 4.0 |
| */ |
| virtual UBool hasAnchoringBounds() const; |
| |
| /** |
| * Set whether this matcher is using Anchoring Bounds for its region. |
| * With anchoring bounds, pattern anchors such as ^ and $ will match at the start |
| * and end of the region. Without Anchoring Bounds, anchors will only match at |
| * the positions they would in the complete text. |
| * |
| * Anchoring Bounds are the default for regions. |
| * |
| * @param b TRUE if to enable anchoring bounds; FALSE to disable them. |
| * @return This Matcher |
| * @draft ICU 4.0 |
| */ |
| virtual RegexMatcher &useAnchoringBounds(UBool b); |
| |
| /** |
| * Return TRUE if the most recent matching operation touched the |
| * end of the text being processed. In this case, additional input text could |
| * change the results of that match. |
| * |
| * hitEnd() is defined for both successful and unsuccessful matches. |
| * In either case hitEnd() will return TRUE if if the end of the text was |
| * reached at any point during the matching process. |
| * |
| * @return TRUE if the most recent match hit the end of input |
| * @draft ICU 4.0 |
| */ |
| virtual UBool hitEnd() const; |
| |
| /** |
| * Return TRUE the most recent match succeeded and additional input could cause |
| * it to fail. If this method returns false and a match was found, then more input |
| * might change the match but the match won't be lost. If a match was not found, |
| * then requireEnd has no meaning. |
| * |
| * @return TRUE if more input could cause the most recent match to no longer match. |
| * @draft ICU 4.0 |
| */ |
| virtual UBool requireEnd() const; |
| |
| |
| |
| |
| |
| /** |
| * Returns the pattern that is interpreted by this matcher. |
| * @return the RegexPattern for this RegexMatcher |
| * @stable ICU 2.4 |
| */ |
| virtual const RegexPattern &pattern() const; |
| |
| |
| /** |
| * Replaces every substring of the input that matches the pattern |
| * with the given replacement string. This is a convenience function that |
| * provides a complete find-and-replace-all operation. |
| * |
| * This method first resets this matcher. It then scans the input string |
| * looking for matches of the pattern. Input that is not part of any |
| * match is left unchanged; each match is replaced in the result by the |
| * replacement string. The replacement string may contain references to |
| * capture groups. |
| * |
| * @param replacement a string containing the replacement text. |
| * @param status a reference to a UErrorCode to receive any errors. |
| * @return a string containing the results of the find and replace. |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status); |
| |
| |
| /** |
| * Replaces the first substring of the input that matches |
| * the pattern with the replacement string. This is a convenience |
| * function that provides a complete find-and-replace operation. |
| * |
| * <p>This function first resets this RegexMatcher. It then scans the input string |
| * looking for a match of the pattern. Input that is not part |
| * of the match is appended directly to the result string; the match is replaced |
| * in the result by the replacement string. The replacement string may contain |
| * references to captured groups.</p> |
| * |
| * <p>The state of the matcher (the position at which a subsequent find() |
| * would begin) after completing a replaceFirst() is not specified. The |
| * RegexMatcher should be reset before doing additional find() operations.</p> |
| * |
| * @param replacement a string containing the replacement text. |
| * @param status a reference to a UErrorCode to receive any errors. |
| * @return a string containing the results of the find and replace. |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status); |
| |
| /** |
| * Implements a replace operation intended to be used as part of an |
| * incremental find-and-replace. |
| * |
| * <p>The input string, starting from the end of the previous replacement and ending at |
| * the start of the current match, is appended to the destination string. Then the |
| * replacement string is appended to the output string, |
| * including handling any substitutions of captured text.</p> |
| * |
| * <p>For simple, prepackaged, non-incremental find-and-replace |
| * operations, see replaceFirst() or replaceAll().</p> |
| * |
| * @param dest A UnicodeString to which the results of the find-and-replace are appended. |
| * @param replacement A UnicodeString that provides the text to be substituted for |
| * the input text that matched the regexp pattern. The replacement |
| * text may contain references to captured text from the |
| * input. |
| * @param status A reference to a UErrorCode to receive any errors. Possible |
| * errors are U_REGEX_INVALID_STATE if no match has been |
| * attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR |
| * if the replacement text specifies a capture group that |
| * does not exist in the pattern. |
| * |
| * @return this RegexMatcher |
| * @stable ICU 2.4 |
| * |
| */ |
| virtual RegexMatcher &appendReplacement(UnicodeString &dest, |
| const UnicodeString &replacement, UErrorCode &status); |
| |
| |
| /** |
| * As the final step in a find-and-replace operation, append the remainder |
| * of the input string, starting at the position following the last appendReplacement(), |
| * to the destination string. <code>appendTail()</code> is intended to be invoked after one |
| * or more invocations of the <code>RegexMatcher::appendReplacement()</code>. |
| * |
| * @param dest A UnicodeString to which the results of the find-and-replace are appended. |
| * @return the destination string. |
| * @stable ICU 2.4 |
| */ |
| virtual UnicodeString &appendTail(UnicodeString &dest); |
| |
| |
| |
| /** |
| * Split a string into fields. Somewhat like split() from Perl. |
| * The pattern matches identify delimiters that separate the input |
| * into fields. The input data between the matches becomes the |
| * fields themselves. |
| * <p> |
| * |
| * @param input The string to be split into fields. The field delimiters |
| * match the pattern (in the "this" object). This matcher |
| * will be reset to this input string. |
| * @param dest An array of UnicodeStrings to receive the results of the split. |
| * This is an array of actual UnicodeString objects, not an |
| * array of pointers to strings. Local (stack based) arrays can |
| * work well here. |
| * @param destCapacity The number of elements in the destination array. |
| * If the number of fields found is less than destCapacity, the |
| * extra strings in the destination array are not altered. |
| * If the number of destination strings is less than the number |
| * of fields, the trailing part of the input string, including any |
| * field delimiters, is placed in the last destination string. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @return The number of fields into which the input string was split. |
| * @stable ICU 2.6 |
| */ |
| virtual int32_t split(const UnicodeString &input, |
| UnicodeString dest[], |
| int32_t destCapacity, |
| UErrorCode &status); |
| |
| /** |
| * Set a processing time limit for match operations with this Matcher. |
| * |
| * Some patterns, when matching certain strings, can run in exponential time. |
| * For practical purposes, the match operation may appear to be in an |
| * infinite loop. |
| * When a limit is set a match operation will fail with an error if the |
| * limit is exceeded. |
| * <p> |
| * The units of the limit are steps of the match engine. |
| * Correspondence with actual processor time will depend on the speed |
| * of the processor and the details of the specific pattern, but will |
| * typically be on the order of milliseconds. |
| * <p> |
| * By default, the matching time is not limited. |
| * <p> |
| * |
| * @param limit The limit value, or 0 for no limit. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @draft ICU 4.0 |
| */ |
| virtual void setTimeLimit(int32_t limit, UErrorCode &status); |
| |
| /** |
| * Get the time limit, if any, for match operations made with this Matcher. |
| * |
| * @return the maximum allowed time for a match, in units of processing steps. |
| * @draft ICU 4.0 |
| */ |
| virtual int32_t getTimeLimit() const; |
| |
| /** |
| * Set the amount of heap storage avaliable for use by the match backtracking stack. |
| * The matcher is also reset, discarding any results from previous matches. |
| * <p> |
| * ICU uses a backtracking regular expression engine, with the backtrack stack |
| * maintained on the heap. This function sets the limit to the amount of memory |
| * that can be used for this purpose. A backtracking stack overflow will |
| * result in an error from the match operation that caused it. |
| * <p> |
| * A limit is desirable because a malicious or poorly designed pattern can use |
| * excessive memory, potentially crashing the process. A limit is enabled |
| * by default. |
| * <p> |
| * @param limit The maximum size, in bytes, of the matching backtrack stack. |
| * A value of zero means no limit. |
| * The limit must be greater or equal to zero. |
| * |
| * @param status A reference to a UErrorCode to receive any errors. |
| * |
| * @draft ICU 4.0 |
| */ |
| virtual void setStackLimit(int32_t limit, UErrorCode &status); |
| |
| /** |
| * Get the size of the heap storage available for use by the back tracking stack. |
| * |
| * @return the maximum backtracking stack size, in bytes, or zero if the |
| * stack size is unlimited. |
| * @draft ICU 4.0 |
| */ |
| virtual int32_t getStackLimit() const; |
| |
| |
| /** |
| * Set a callback function for use with this Matcher. |
| * During matching operations the function will be called periodically, |
| * giving the application the opportunity to terminate a long-running |
| * match. |
| * |
| * @param callback A pointer to the user-supplied callback function. |
| * @param context User context pointer. The value supplied at the |
| * time the callback function is set will be saved |
| * and passed to the callback each time that it is called. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @draft ICU 4.0 |
| */ |
| virtual void setMatchCallback(URegexMatchCallback *callback, |
| const void *context, |
| UErrorCode &status); |
| |
| |
| |
| /** |
| * Get the callback function for this URegularExpression. |
| * |
| * @param callback Out paramater, receives a pointer to the user-supplied |
| * callback function. |
| * @param context Out parameter, receives the user context pointer that |
| * was set when uregex_setMatchCallback() was called. |
| * @param status A reference to a UErrorCode to receive any errors. |
| * @draft ICU 4.0 |
| */ |
| virtual void getMatchCallback(URegexMatchCallback *&callback, |
| const void *&context, |
| UErrorCode &status); |
| |
| |
| /** |
| * setTrace Debug function, enable/disable tracing of the matching engine. |
| * For internal ICU development use only. DO NO USE!!!! |
| * @internal |
| */ |
| void setTrace(UBool state); |
| |
| |
| /** |
| * ICU "poor man's RTTI", returns a UClassID for this class. |
| * |
| * @stable ICU 2.2 |
| */ |
| static UClassID U_EXPORT2 getStaticClassID(); |
| |
| /** |
| * ICU "poor man's RTTI", returns a UClassID for the actual class. |
| * |
| * @stable ICU 2.2 |
| */ |
| virtual UClassID getDynamicClassID() const; |
| |
| private: |
| // Constructors and other object boilerplate are private. |
| // Instances of RegexMatcher can not be assigned, copied, cloned, etc. |
| RegexMatcher(); // default constructor not implemented |
| RegexMatcher(const RegexPattern *pat); |
| RegexMatcher(const RegexMatcher &other); |
| RegexMatcher &operator =(const RegexMatcher &rhs); |
| void init(UErrorCode &status); // Common initialization |
| void init2(const UnicodeString &s, UErrorCode &e); // Common initialization, part 2. |
| |
| friend class RegexPattern; |
| friend class RegexCImpl; |
| public: |
| /** @internal */ |
| void resetPreserveRegion(); // Reset matcher state, but preserve any region. |
| private: |
| |
| // |
| // MatchAt This is the internal interface to the match engine itself. |
| // Match status comes back in matcher member variables. |
| // |
| void MatchAt(int32_t startIdx, UBool toEnd, UErrorCode &status); |
| inline void backTrack(int32_t &inputIdx, int32_t &patIdx); |
| UBool isWordBoundary(int32_t pos); // perform Perl-like \b test |
| UBool isUWordBoundary(int32_t pos); // perform RBBI based \b test |
| REStackFrame *resetStack(); |
| inline REStackFrame *StateSave(REStackFrame *fp, int32_t savePatIdx, UErrorCode &status); |
| void IncrementTime(UErrorCode &status); |
| |
| |
| const RegexPattern *fPattern; |
| RegexPattern *fPatternOwned; // Non-NULL if this matcher owns the pattern, and |
| // should delete it when through. |
| |
| const UnicodeString *fInput; // The text being matched. Is never NULL. |
| int32_t fFrameSize; // The size of a frame in the backtrack stack. |
| |
| int32_t fRegionStart; // Start of the input region, default = 0. |
| int32_t fRegionLimit; // End of input region, default to input.length. |
| |
| int32_t fAnchorStart; // Region bounds for anchoring operations (^ or $). |
| int32_t fAnchorLimit; // See useAnchoringBounds |
| |
| int32_t fLookStart; // Region bounds for look-ahead/behind and |
| int32_t fLookLimit; // and other boundary tests. See |
| // useTransparentBounds |
| |
| int32_t fActiveStart; // Currently active bounds for matching. |
| int32_t fActiveLimit; // Usually is the same as region, but |
| // is changed to fLookStart/Limit when |
| // entering look around regions. |
| |
| UBool fTransparentBounds; // True if using transparent bounds. |
| UBool fAnchoringBounds; // True if using anchoring bounds. |
| |
| UBool fMatch; // True if the last attempted match was successful. |
| int32_t fMatchStart; // Position of the start of the most recent match |
| int32_t fMatchEnd; // First position after the end of the most recent match |
| // Zero if no previous match, even when a region |
| // is active. |
| int32_t fLastMatchEnd; // First position after the end of the previous match, |
| // or -1 if there was no previous match. |
| int32_t fAppendPosition; // First position after the end of the previous |
| // appendReplacement(). As described by the |
| // JavaDoc for Java Matcher, where it is called |
| // "append position" |
| UBool fHitEnd; // True if the last match touched the end of input. |
| UBool fRequireEnd; // True if the last match required end-of-input |
| // (matched $ or Z) |
| |
| UVector32 *fStack; |
| REStackFrame *fFrame; // After finding a match, the last active stack frame, |
| // which will contain the capture group results. |
| // NOT valid while match engine is running. |
| |
| int32_t *fData; // Data area for use by the compiled pattern. |
| int32_t fSmallData[8]; // Use this for data if it's enough. |
| |
| int32_t fTimeLimit; // Max time (in arbitrary steps) to let the |
| // match engine run. Zero for unlimited. |
| |
| int32_t fTime; // Match time, accumulates while matching. |
| int32_t fTickCounter; // Low bits counter for time. Counts down StateSaves. |
| // Kept separately from fTime to keep as much |
| // code as possible out of the inline |
| // StateSave function. |
| |
| int32_t fStackLimit; // Maximum memory size to use for the backtrack |
| // stack, in bytes. Zero for unlimited. |
| |
| URegexMatchCallback *fCallbackFn; // Pointer to match progress callback funct. |
| // NULL if there is no callback. |
| const void *fCallbackContext; // User Context ptr for callback function. |
| |
| UBool fTraceDebug; // Set true for debug tracing of match engine. |
| |
| UErrorCode fDeferredStatus; // Save error state that cannot be immediately |
| // reported, or that permanently disables this matcher. |
| |
| RuleBasedBreakIterator *fWordBreakItr; |
| |
| |
| }; |
| |
| U_NAMESPACE_END |
| #endif // UCONFIG_NO_REGULAR_EXPRESSIONS |
| #endif |
