/*
**********************************************************************
-* Copyright (C) 2002-2003, International Business Machines
+* Copyright (C) 2002-2008, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
* file name: regex.h
#ifndef REGEX_H
#define REGEX_H
+//#define REGEX_DEBUG
/**
* \file
* <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 <RegexMatcher> objects for the pattern.</p>
+ * 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"
#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;
-/**
- * Constants for Regular Expression Match Modes.
- * @draft ICU 2.4
- */
-enum {
- /** Forces normalization of pattern and strings. @draft ICU 2.4 */
- UREGEX_CANON_EQ = 128,
-
- /** Enable case insensitive matching. @draft ICU 2.4 */
- UREGEX_CASE_INSENSITIVE = 2,
-
- /** Allow white space and comments within patterns @draft ICU 2.4 */
- UREGEX_COMMENTS = 4,
- /** If set, '.' matches line terminators, otherwise '.' matching stops at line end.
- * @draft ICU 2.4 */
- UREGEX_DOTALL = 32,
- /** Control behavior of "$" and "^"
- * If set, recognize line terminators within string,
- * otherwise, match only at start and end of input string.
- * @draft ICU 2.4 */
- UREGEX_MULTILINE = 8
-};
+/**
+ * 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
*
* <p>Class RegexPattern is not intended to be subclassed.</p>
*
- * @draft ICU 2.4
+ * @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>.
- *
- * @draft ICU 2.4
- */
+ * 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.
- * @draft ICU 2.4
- */
+ * 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.
- * @draft ICU 2.4
- */
+ * 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.
- * @draft ICU 2.4
- */
+ * 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.
- * @draft ICU 2.4
- */
+ * 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
RegexPattern &operator =(const RegexPattern &source);
* intended to be subclasses, <code>clone()</code> and the copy construction are
* equivalent operations.
* @return the copy of this RegexPattern
- * @draft ICU 2.4
+ * @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.
+ * 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>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>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.
+ * @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.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- static RegexPattern *compile( const UnicodeString ®ex,
+ 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.
+ * 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 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.
+ * @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.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- static RegexPattern *compile( const UnicodeString ®ex,
+ 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.
+ * 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 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>
*
- * @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.
+ * <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>
*
- * @draft ICU 2.6
+ * @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 *compile( const UnicodeString ®ex,
+ 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
- * @draft ICU 2.4
+ * 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.
+ * 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.
+ * @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.
*
- * @draft ICU 2.4
+ * @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.
+ * 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.
+ * @param status A reference to a UErrorCode to receive any errors.
+ * @return A RegexMatcher object for this pattern and input.
*
- * @draft ICU 2.6
+ * @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 RegexPattern object.
+ * 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.
+ * @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.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- static UBool matches(const UnicodeString ®ex,
+ 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UnicodeString pattern() const;
* <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.
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual int32_t split(const UnicodeString &input,
UnicodeString dest[],
UErrorCode &status) const;
-
- /**
- * dump Debug function, displays the compiled form of a pattern.
- * @internal
- */
- void dump() const;
-
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- virtual inline UClassID getDynamicClassID() const;
+ virtual UClassID getDynamicClassID() const;
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- static inline UClassID getStaticClassID();
+ static UClassID U_EXPORT2 getStaticClassID();
private:
//
// sets for predefined regex classes.
int32_t fStartType; // Info on how a match must start.
- int32_t fInitialStringIdx; //
+ int32_t fInitialStringIdx; //
int32_t fInitialStringLen;
- UnicodeSet *fInitialChars;
+ UnicodeSet *fInitialChars;
UChar32 fInitialChar;
Regex8BitSet *fInitialChars8;
- /**
- * The address of this static class variable serves as this class's ID
- * for ICU "poor man's RTTI".
- */
- static const char fgClassID;
-
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
*
* <p>Class RegexMatcher is not intended to be subclassed.</p>
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
class U_I18N_API RegexMatcher: public UObject {
public:
* @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.
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
RegexMatcher(const UnicodeString ®exp, uint32_t flags, UErrorCode &status);
* 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
+ * @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.
- * @draft ICU 2.6
+ * @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.
+ * Destructor.
*
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual ~RegexMatcher();
/**
- * Attempts to match the entire input string against the pattern.
+ * 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
- * @draft ICU 2.4
+ * @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, against the pattern.
- * Like the matches() method, this function always starts at the beginning of the input string;
- * unlike that function, it does not require that the entire input string be matched.
+ * 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.
- * @draft ICU 2.4
+ * @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
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UBool find();
* @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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UBool find(int32_t start, UErrorCode &status);
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UnicodeString group(UErrorCode &status) const;
* has been attempted or the last match failed and
* U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
* @return the captured text
- * @draft ICU 2.4
+ * @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
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual int32_t groupCount() const;
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual int32_t start(UErrorCode &status) const;
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
- virtual int32_t start(int group, UErrorCode &status) const;
+ virtual int32_t start(int32_t group, UErrorCode &status) const;
/**
- * Returns the index in the input string of the character following the
+ * 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual int32_t end(UErrorCode &status) const;
* 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 last character, plus one, of the text
+ * @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 was not part of the match.
- * @draft ICU 2.4
+ * 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(int group, UErrorCode &status) const;
+ virtual int32_t end(int32_t group, UErrorCode &status) const;
/**
* the input string.
*
* @return this RegexMatcher.
- * @draft ICU 2.4
+ * @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.
- * @draft ICU 2.4
+ * @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
- * @draft ICU 2.4
+ * @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
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual const RegexPattern &pattern() const;
* @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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);
* @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.
- * @draft ICU 2.4
+ * @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 match and ending at
+ * <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>
* 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 substitured for
+ * @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.
* does not exist in the pattern.
*
* @return this RegexMatcher
- * @draft ICU 2.4
+ * @stable ICU 2.4
*
*/
virtual RegexMatcher &appendReplacement(UnicodeString &dest,
/**
* As the final step in a find-and-replace operation, append the remainder
- * of the input string, starting at the position following the last match,
+ * 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
virtual UnicodeString &appendTail(UnicodeString &dest);
* 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.
* 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.
- * @draft ICU 2.6
+ * @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);
/**
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
- * @draft ICU 2.2
+ * @stable ICU 2.2
*/
- static inline UClassID getStaticClassID();
+ static UClassID U_EXPORT2 getStaticClassID();
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
- * @draft ICU 2.2
+ * @stable ICU 2.2
*/
- virtual inline UClassID getDynamicClassID() const;
+ 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(); // default constructor not implemented
RegexMatcher(const RegexPattern *pat);
RegexMatcher(const RegexMatcher &other);
RegexMatcher &operator =(const RegexMatcher &rhs);
- friend class RegexPattern;
+ 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, UErrorCode &status);
+ void MatchAt(int32_t startIdx, UBool toEnd, UErrorCode &status);
inline void backTrack(int32_t &inputIdx, int32_t &patIdx);
- UBool isWordBoundary(int32_t pos); // perform the \b test
+ 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);
+ 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;
- UBool fMatch; // True if the last match was successful.
+ 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
- int32_t fLastMatchEnd; // First position after the end of the previous 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.
+ 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.
+ 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.
- UErrorCode fDeferredStatus; // Save error state if that cannot be immediately
- // reported, or that permanently disables this matcher.
+ int32_t fStackLimit; // Maximum memory size to use for the backtrack
+ // stack, in bytes. Zero for unlimited.
- /**
- * The address of this static class variable serves as this class's ID
- * for ICU "poor man's RTTI".
- */
- static const char fgClassID;
+ 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.
-inline UClassID RegexPattern::getStaticClassID() { return (UClassID)&fgClassID; }
-inline UClassID RegexPattern::getDynamicClassID() const { return getStaticClassID(); }
+ RuleBasedBreakIterator *fWordBreakItr;
-inline UClassID RegexMatcher::getStaticClassID() { return (UClassID)&fgClassID; }
-inline UClassID RegexMatcher::getDynamicClassID() const { return getStaticClassID(); }
+};
U_NAMESPACE_END
#endif // UCONFIG_NO_REGULAR_EXPRESSIONS
projects / apple / icu.git / blobdiff