/* ********************************************************************** * 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 * *

Regular Expression API

* *

The ICU API for processing regular expressions consists of two classes, * RegexPattern and RegexMatcher. * RegexPattern objects represent a pre-processed, or compiled * regular expression. They are created from a regular expression pattern string, * and can be used to create RegexMatcher objects for the pattern.

* *

Class RegexMatcher bundles together a regular expression * pattern and a target string to which the search pattern will be applied. * RegexMatcher includes API for doing plain find or search * operations, for search and replace operations, and for obtaining detailed * information about bounds of a match.

* *

Note that by constructing RegexMatcher objects directly from regular * expression pattern strings application code can be simplified and the explicit * need for RegexPattern objects can usually be eliminated. *

*/ #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 RegexPattern 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. * *

Class RegexPattern is not intended to be subclassed.

* * @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 compile(). * * @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, clone() 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. * *

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.

* *

All pattern match mode flags are set to their default values.

* *

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.

* * @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. * *

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.

* *

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.

* * @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. * *

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.

* *

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.

* * @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. *

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

* To efficiently work with UChar *strings, wrap the data in a UnicodeString * using one of the aliasing constructors, such as * UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength); * * @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. *

* For the best performance on split() operations, * RegexMatcher::split 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. * *

Class RegexMatcher is not intended to be subclassed.

* * @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. *

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

* To efficiently work with UChar *strings, wrap the data in a UnicodeString * using one of the aliasing constructors, such as * UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength); * * @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. * *

If the match succeeds then more information can be obtained via the start(), * end(), and group() functions.

* * @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(). * *

If the match succeeds then more information can be obtained via the start(), * end(), and group() functions.

* * @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, start(), end() and group() * will provide more information regarding the match. *

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.

* @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. *

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

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

* To efficiently work with UChar *strings, wrap the data in a UnicodeString * using one of the aliasing constructors, such as * UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength); * * @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. * *

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.

* *

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.

* * @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. * *

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.

* *

For simple, prepackaged, non-incremental find-and-replace * operations, see replaceFirst() or replaceAll().

* * @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. appendTail() is intended to be invoked after one * or more invocations of the RegexMatcher::appendReplacement(). * * @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. *

* * @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); /** * 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); 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, int32_t frameSize, 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 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. UBool fTraceDebug; // Set true for debug tracing of match engine. UErrorCode fDeferredStatus; // Save error state if that cannot be immediately // reported, or that permanently disables this matcher. RuleBasedBreakIterator *fWordBreakItr; }; U_NAMESPACE_END #endif // UCONFIG_NO_REGULAR_EXPRESSIONS #endif