1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/regex.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1849 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (C) 2002-2013, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 +* file name: regex.h
1.10 +* encoding: US-ASCII
1.11 +* indentation:4
1.12 +*
1.13 +* created on: 2002oct22
1.14 +* created by: Andy Heninger
1.15 +*
1.16 +* ICU Regular Expressions, API for C++
1.17 +*/
1.18 +
1.19 +#ifndef REGEX_H
1.20 +#define REGEX_H
1.21 +
1.22 +//#define REGEX_DEBUG
1.23 +
1.24 +/**
1.25 + * \file
1.26 + * \brief C++ API: Regular Expressions
1.27 + *
1.28 + * <h2>Regular Expression API</h2>
1.29 + *
1.30 + * <p>The ICU API for processing regular expressions consists of two classes,
1.31 + * <code>RegexPattern</code> and <code>RegexMatcher</code>.
1.32 + * <code>RegexPattern</code> objects represent a pre-processed, or compiled
1.33 + * regular expression. They are created from a regular expression pattern string,
1.34 + * and can be used to create <code>RegexMatcher</code> objects for the pattern.</p>
1.35 + *
1.36 + * <p>Class <code>RegexMatcher</code> bundles together a regular expression
1.37 + * pattern and a target string to which the search pattern will be applied.
1.38 + * <code>RegexMatcher</code> includes API for doing plain find or search
1.39 + * operations, for search and replace operations, and for obtaining detailed
1.40 + * information about bounds of a match. </p>
1.41 + *
1.42 + * <p>Note that by constructing <code>RegexMatcher</code> objects directly from regular
1.43 + * expression pattern strings application code can be simplified and the explicit
1.44 + * need for <code>RegexPattern</code> objects can usually be eliminated.
1.45 + * </p>
1.46 + */
1.47 +
1.48 +#include "unicode/utypes.h"
1.49 +
1.50 +#if !UCONFIG_NO_REGULAR_EXPRESSIONS
1.51 +
1.52 +#include "unicode/uobject.h"
1.53 +#include "unicode/unistr.h"
1.54 +#include "unicode/utext.h"
1.55 +#include "unicode/parseerr.h"
1.56 +
1.57 +#include "unicode/uregex.h"
1.58 +
1.59 +// Forward Declarations
1.60 +
1.61 +U_NAMESPACE_BEGIN
1.62 +
1.63 +struct Regex8BitSet;
1.64 +class RegexCImpl;
1.65 +class RegexMatcher;
1.66 +class RegexPattern;
1.67 +struct REStackFrame;
1.68 +class RuleBasedBreakIterator;
1.69 +class UnicodeSet;
1.70 +class UVector;
1.71 +class UVector32;
1.72 +class UVector64;
1.73 +
1.74 +#ifndef U_HIDE_INTERNAL_API
1.75 +/**
1.76 + * RBBIPatternDump Debug function, displays the compiled form of a pattern.
1.77 + * @internal
1.78 + */
1.79 +#ifdef REGEX_DEBUG
1.80 +U_INTERNAL void U_EXPORT2
1.81 + RegexPatternDump(const RegexPattern *pat);
1.82 +#else
1.83 + #undef RegexPatternDump
1.84 + #define RegexPatternDump(pat)
1.85 +#endif
1.86 +#endif /* U_HIDE_INTERNAL_API */
1.87 +
1.88 +
1.89 +
1.90 +/**
1.91 + * Class <code>RegexPattern</code> represents a compiled regular expression. It includes
1.92 + * factory methods for creating a RegexPattern object from the source (string) form
1.93 + * of a regular expression, methods for creating RegexMatchers that allow the pattern
1.94 + * to be applied to input text, and a few convenience methods for simple common
1.95 + * uses of regular expressions.
1.96 + *
1.97 + * <p>Class RegexPattern is not intended to be subclassed.</p>
1.98 + *
1.99 + * @stable ICU 2.4
1.100 + */
1.101 +class U_I18N_API RegexPattern: public UObject {
1.102 +public:
1.103 +
1.104 + /**
1.105 + * default constructor. Create a RegexPattern object that refers to no actual
1.106 + * pattern. Not normally needed; RegexPattern objects are usually
1.107 + * created using the factory method <code>compile()</code>.
1.108 + *
1.109 + * @stable ICU 2.4
1.110 + */
1.111 + RegexPattern();
1.112 +
1.113 + /**
1.114 + * Copy Constructor. Create a new RegexPattern object that is equivalent
1.115 + * to the source object.
1.116 + * @param source the pattern object to be copied.
1.117 + * @stable ICU 2.4
1.118 + */
1.119 + RegexPattern(const RegexPattern &source);
1.120 +
1.121 + /**
1.122 + * Destructor. Note that a RegexPattern object must persist so long as any
1.123 + * RegexMatcher objects that were created from the RegexPattern are active.
1.124 + * @stable ICU 2.4
1.125 + */
1.126 + virtual ~RegexPattern();
1.127 +
1.128 + /**
1.129 + * Comparison operator. Two RegexPattern objects are considered equal if they
1.130 + * were constructed from identical source patterns using the same match flag
1.131 + * settings.
1.132 + * @param that a RegexPattern object to compare with "this".
1.133 + * @return TRUE if the objects are equivalent.
1.134 + * @stable ICU 2.4
1.135 + */
1.136 + UBool operator==(const RegexPattern& that) const;
1.137 +
1.138 + /**
1.139 + * Comparison operator. Two RegexPattern objects are considered equal if they
1.140 + * were constructed from identical source patterns using the same match flag
1.141 + * settings.
1.142 + * @param that a RegexPattern object to compare with "this".
1.143 + * @return TRUE if the objects are different.
1.144 + * @stable ICU 2.4
1.145 + */
1.146 + inline UBool operator!=(const RegexPattern& that) const {return ! operator ==(that);}
1.147 +
1.148 + /**
1.149 + * Assignment operator. After assignment, this RegexPattern will behave identically
1.150 + * to the source object.
1.151 + * @stable ICU 2.4
1.152 + */
1.153 + RegexPattern &operator =(const RegexPattern &source);
1.154 +
1.155 + /**
1.156 + * Create an exact copy of this RegexPattern object. Since RegexPattern is not
1.157 + * intended to be subclasses, <code>clone()</code> and the copy construction are
1.158 + * equivalent operations.
1.159 + * @return the copy of this RegexPattern
1.160 + * @stable ICU 2.4
1.161 + */
1.162 + virtual RegexPattern *clone() const;
1.163 +
1.164 +
1.165 + /**
1.166 + * Compiles the regular expression in string form into a RegexPattern
1.167 + * object. These compile methods, rather than the constructors, are the usual
1.168 + * way that RegexPattern objects are created.
1.169 + *
1.170 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.171 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.172 + * back to their pattern, so premature deletion of the pattern is a
1.173 + * catastrophic error.</p>
1.174 + *
1.175 + * <p>All pattern match mode flags are set to their default values.</p>
1.176 + *
1.177 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.178 + * from a pattern string rather than separately compiling the pattern and
1.179 + * then creating a RegexMatcher object from the pattern.</p>
1.180 + *
1.181 + * @param regex The regular expression to be compiled.
1.182 + * @param pe Receives the position (line and column nubers) of any error
1.183 + * within the regular expression.)
1.184 + * @param status A reference to a UErrorCode to receive any errors.
1.185 + * @return A regexPattern object for the compiled pattern.
1.186 + *
1.187 + * @stable ICU 2.4
1.188 + */
1.189 + static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex,
1.190 + UParseError &pe,
1.191 + UErrorCode &status);
1.192 +
1.193 + /**
1.194 + * Compiles the regular expression in string form into a RegexPattern
1.195 + * object. These compile methods, rather than the constructors, are the usual
1.196 + * way that RegexPattern objects are created.
1.197 + *
1.198 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.199 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.200 + * back to their pattern, so premature deletion of the pattern is a
1.201 + * catastrophic error.</p>
1.202 + *
1.203 + * <p>All pattern match mode flags are set to their default values.</p>
1.204 + *
1.205 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.206 + * from a pattern string rather than separately compiling the pattern and
1.207 + * then creating a RegexMatcher object from the pattern.</p>
1.208 + *
1.209 + * @param regex The regular expression to be compiled. Note, the text referred
1.210 + * to by this UText must not be deleted during the lifetime of the
1.211 + * RegexPattern object or any RegexMatcher object created from it.
1.212 + * @param pe Receives the position (line and column nubers) of any error
1.213 + * within the regular expression.)
1.214 + * @param status A reference to a UErrorCode to receive any errors.
1.215 + * @return A regexPattern object for the compiled pattern.
1.216 + *
1.217 + * @stable ICU 4.6
1.218 + */
1.219 + static RegexPattern * U_EXPORT2 compile( UText *regex,
1.220 + UParseError &pe,
1.221 + UErrorCode &status);
1.222 +
1.223 + /**
1.224 + * Compiles the regular expression in string form into a RegexPattern
1.225 + * object using the specified match mode flags. These compile methods,
1.226 + * rather than the constructors, are the usual way that RegexPattern objects
1.227 + * are created.
1.228 + *
1.229 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.230 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.231 + * back to their pattern, so premature deletion of the pattern is a
1.232 + * catastrophic error.</p>
1.233 + *
1.234 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.235 + * from a pattern string instead of than separately compiling the pattern and
1.236 + * then creating a RegexMatcher object from the pattern.</p>
1.237 + *
1.238 + * @param regex The regular expression to be compiled.
1.239 + * @param flags The match mode flags to be used.
1.240 + * @param pe Receives the position (line and column numbers) of any error
1.241 + * within the regular expression.)
1.242 + * @param status A reference to a UErrorCode to receive any errors.
1.243 + * @return A regexPattern object for the compiled pattern.
1.244 + *
1.245 + * @stable ICU 2.4
1.246 + */
1.247 + static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex,
1.248 + uint32_t flags,
1.249 + UParseError &pe,
1.250 + UErrorCode &status);
1.251 +
1.252 + /**
1.253 + * Compiles the regular expression in string form into a RegexPattern
1.254 + * object using the specified match mode flags. These compile methods,
1.255 + * rather than the constructors, are the usual way that RegexPattern objects
1.256 + * are created.
1.257 + *
1.258 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.259 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.260 + * back to their pattern, so premature deletion of the pattern is a
1.261 + * catastrophic error.</p>
1.262 + *
1.263 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.264 + * from a pattern string instead of than separately compiling the pattern and
1.265 + * then creating a RegexMatcher object from the pattern.</p>
1.266 + *
1.267 + * @param regex The regular expression to be compiled. Note, the text referred
1.268 + * to by this UText must not be deleted during the lifetime of the
1.269 + * RegexPattern object or any RegexMatcher object created from it.
1.270 + * @param flags The match mode flags to be used.
1.271 + * @param pe Receives the position (line and column numbers) of any error
1.272 + * within the regular expression.)
1.273 + * @param status A reference to a UErrorCode to receive any errors.
1.274 + * @return A regexPattern object for the compiled pattern.
1.275 + *
1.276 + * @stable ICU 4.6
1.277 + */
1.278 + static RegexPattern * U_EXPORT2 compile( UText *regex,
1.279 + uint32_t flags,
1.280 + UParseError &pe,
1.281 + UErrorCode &status);
1.282 +
1.283 + /**
1.284 + * Compiles the regular expression in string form into a RegexPattern
1.285 + * object using the specified match mode flags. These compile methods,
1.286 + * rather than the constructors, are the usual way that RegexPattern objects
1.287 + * are created.
1.288 + *
1.289 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.290 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.291 + * back to their pattern, so premature deletion of the pattern is a
1.292 + * catastrophic error.</p>
1.293 + *
1.294 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.295 + * from a pattern string instead of than separately compiling the pattern and
1.296 + * then creating a RegexMatcher object from the pattern.</p>
1.297 + *
1.298 + * @param regex The regular expression to be compiled.
1.299 + * @param flags The match mode flags to be used.
1.300 + * @param status A reference to a UErrorCode to receive any errors.
1.301 + * @return A regexPattern object for the compiled pattern.
1.302 + *
1.303 + * @stable ICU 2.6
1.304 + */
1.305 + static RegexPattern * U_EXPORT2 compile( const UnicodeString ®ex,
1.306 + uint32_t flags,
1.307 + UErrorCode &status);
1.308 +
1.309 + /**
1.310 + * Compiles the regular expression in string form into a RegexPattern
1.311 + * object using the specified match mode flags. These compile methods,
1.312 + * rather than the constructors, are the usual way that RegexPattern objects
1.313 + * are created.
1.314 + *
1.315 + * <p>Note that RegexPattern objects must not be deleted while RegexMatcher
1.316 + * objects created from the pattern are active. RegexMatchers keep a pointer
1.317 + * back to their pattern, so premature deletion of the pattern is a
1.318 + * catastrophic error.</p>
1.319 + *
1.320 + * <p>Note that it is often more convenient to construct a RegexMatcher directly
1.321 + * from a pattern string instead of than separately compiling the pattern and
1.322 + * then creating a RegexMatcher object from the pattern.</p>
1.323 + *
1.324 + * @param regex The regular expression to be compiled. Note, the text referred
1.325 + * to by this UText must not be deleted during the lifetime of the
1.326 + * RegexPattern object or any RegexMatcher object created from it.
1.327 + * @param flags The match mode flags to be used.
1.328 + * @param status A reference to a UErrorCode to receive any errors.
1.329 + * @return A regexPattern object for the compiled pattern.
1.330 + *
1.331 + * @stable ICU 4.6
1.332 + */
1.333 + static RegexPattern * U_EXPORT2 compile( UText *regex,
1.334 + uint32_t flags,
1.335 + UErrorCode &status);
1.336 +
1.337 + /**
1.338 + * Get the match mode flags that were used when compiling this pattern.
1.339 + * @return the match mode flags
1.340 + * @stable ICU 2.4
1.341 + */
1.342 + virtual uint32_t flags() const;
1.343 +
1.344 + /**
1.345 + * Creates a RegexMatcher that will match the given input against this pattern. The
1.346 + * RegexMatcher can then be used to perform match, find or replace operations
1.347 + * on the input. Note that a RegexPattern object must not be deleted while
1.348 + * RegexMatchers created from it still exist and might possibly be used again.
1.349 + * <p>
1.350 + * The matcher will retain a reference to the supplied input string, and all regexp
1.351 + * pattern matching operations happen directly on this original string. It is
1.352 + * critical that the string not be altered or deleted before use by the regular
1.353 + * expression operations is complete.
1.354 + *
1.355 + * @param input The input string to which the regular expression will be applied.
1.356 + * @param status A reference to a UErrorCode to receive any errors.
1.357 + * @return A RegexMatcher object for this pattern and input.
1.358 + *
1.359 + * @stable ICU 2.4
1.360 + */
1.361 + virtual RegexMatcher *matcher(const UnicodeString &input,
1.362 + UErrorCode &status) const;
1.363 +
1.364 +private:
1.365 + /**
1.366 + * Cause a compilation error if an application accidentally attempts to
1.367 + * create a matcher with a (UChar *) string as input rather than
1.368 + * a UnicodeString. Avoids a dangling reference to a temporary string.
1.369 + * <p>
1.370 + * To efficiently work with UChar *strings, wrap the data in a UnicodeString
1.371 + * using one of the aliasing constructors, such as
1.372 + * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
1.373 + * or in a UText, using
1.374 + * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
1.375 + *
1.376 + */
1.377 + RegexMatcher *matcher(const UChar *input,
1.378 + UErrorCode &status) const;
1.379 +public:
1.380 +
1.381 +
1.382 + /**
1.383 + * Creates a RegexMatcher that will match against this pattern. The
1.384 + * RegexMatcher can be used to perform match, find or replace operations.
1.385 + * Note that a RegexPattern object must not be deleted while
1.386 + * RegexMatchers created from it still exist and might possibly be used again.
1.387 + *
1.388 + * @param status A reference to a UErrorCode to receive any errors.
1.389 + * @return A RegexMatcher object for this pattern and input.
1.390 + *
1.391 + * @stable ICU 2.6
1.392 + */
1.393 + virtual RegexMatcher *matcher(UErrorCode &status) const;
1.394 +
1.395 +
1.396 + /**
1.397 + * Test whether a string matches a regular expression. This convenience function
1.398 + * both compiles the regular expression and applies it in a single operation.
1.399 + * Note that if the same pattern needs to be applied repeatedly, this method will be
1.400 + * less efficient than creating and reusing a RegexMatcher object.
1.401 + *
1.402 + * @param regex The regular expression
1.403 + * @param input The string data to be matched
1.404 + * @param pe Receives the position of any syntax errors within the regular expression
1.405 + * @param status A reference to a UErrorCode to receive any errors.
1.406 + * @return True if the regular expression exactly matches the full input string.
1.407 + *
1.408 + * @stable ICU 2.4
1.409 + */
1.410 + static UBool U_EXPORT2 matches(const UnicodeString ®ex,
1.411 + const UnicodeString &input,
1.412 + UParseError &pe,
1.413 + UErrorCode &status);
1.414 +
1.415 + /**
1.416 + * Test whether a string matches a regular expression. This convenience function
1.417 + * both compiles the regular expression and applies it in a single operation.
1.418 + * Note that if the same pattern needs to be applied repeatedly, this method will be
1.419 + * less efficient than creating and reusing a RegexMatcher object.
1.420 + *
1.421 + * @param regex The regular expression
1.422 + * @param input The string data to be matched
1.423 + * @param pe Receives the position of any syntax errors within the regular expression
1.424 + * @param status A reference to a UErrorCode to receive any errors.
1.425 + * @return True if the regular expression exactly matches the full input string.
1.426 + *
1.427 + * @stable ICU 4.6
1.428 + */
1.429 + static UBool U_EXPORT2 matches(UText *regex,
1.430 + UText *input,
1.431 + UParseError &pe,
1.432 + UErrorCode &status);
1.433 +
1.434 + /**
1.435 + * Returns the regular expression from which this pattern was compiled. This method will work
1.436 + * even if the pattern was compiled from a UText.
1.437 + *
1.438 + * Note: If the pattern was originally compiled from a UText, and that UText was modified,
1.439 + * the returned string may no longer reflect the RegexPattern object.
1.440 + * @stable ICU 2.4
1.441 + */
1.442 + virtual UnicodeString pattern() const;
1.443 +
1.444 +
1.445 + /**
1.446 + * Returns the regular expression from which this pattern was compiled. This method will work
1.447 + * even if the pattern was compiled from a UnicodeString.
1.448 + *
1.449 + * Note: This is the original input, not a clone. If the pattern was originally compiled from a
1.450 + * UText, and that UText was modified, the returned UText may no longer reflect the RegexPattern
1.451 + * object.
1.452 + *
1.453 + * @stable ICU 4.6
1.454 + */
1.455 + virtual UText *patternText(UErrorCode &status) const;
1.456 +
1.457 +
1.458 + /**
1.459 + * Split a string into fields. Somewhat like split() from Perl or Java.
1.460 + * Pattern matches identify delimiters that separate the input
1.461 + * into fields. The input data between the delimiters becomes the
1.462 + * fields themselves.
1.463 + *
1.464 + * If the delimiter pattern includes capture groups, the captured text will
1.465 + * also appear in the destination array of output strings, interspersed
1.466 + * with the fields. This is similar to Perl, but differs from Java,
1.467 + * which ignores the presence of capture groups in the pattern.
1.468 + *
1.469 + * Trailing empty fields will always be returned, assuming sufficient
1.470 + * destination capacity. This differs from the default behavior for Java
1.471 + * and Perl where trailing empty fields are not returned.
1.472 + *
1.473 + * The number of strings produced by the split operation is returned.
1.474 + * This count includes the strings from capture groups in the delimiter pattern.
1.475 + * This behavior differs from Java, which ignores capture groups.
1.476 + *
1.477 + * For the best performance on split() operations,
1.478 + * <code>RegexMatcher::split</code> is preferable to this function
1.479 + *
1.480 + * @param input The string to be split into fields. The field delimiters
1.481 + * match the pattern (in the "this" object)
1.482 + * @param dest An array of UnicodeStrings to receive the results of the split.
1.483 + * This is an array of actual UnicodeString objects, not an
1.484 + * array of pointers to strings. Local (stack based) arrays can
1.485 + * work well here.
1.486 + * @param destCapacity The number of elements in the destination array.
1.487 + * If the number of fields found is less than destCapacity, the
1.488 + * extra strings in the destination array are not altered.
1.489 + * If the number of destination strings is less than the number
1.490 + * of fields, the trailing part of the input string, including any
1.491 + * field delimiters, is placed in the last destination string.
1.492 + * @param status A reference to a UErrorCode to receive any errors.
1.493 + * @return The number of fields into which the input string was split.
1.494 + * @stable ICU 2.4
1.495 + */
1.496 + virtual int32_t split(const UnicodeString &input,
1.497 + UnicodeString dest[],
1.498 + int32_t destCapacity,
1.499 + UErrorCode &status) const;
1.500 +
1.501 +
1.502 + /**
1.503 + * Split a string into fields. Somewhat like split() from Perl or Java.
1.504 + * Pattern matches identify delimiters that separate the input
1.505 + * into fields. The input data between the delimiters becomes the
1.506 + * fields themselves.
1.507 + *
1.508 + * If the delimiter pattern includes capture groups, the captured text will
1.509 + * also appear in the destination array of output strings, interspersed
1.510 + * with the fields. This is similar to Perl, but differs from Java,
1.511 + * which ignores the presence of capture groups in the pattern.
1.512 + *
1.513 + * Trailing empty fields will always be returned, assuming sufficient
1.514 + * destination capacity. This differs from the default behavior for Java
1.515 + * and Perl where trailing empty fields are not returned.
1.516 + *
1.517 + * The number of strings produced by the split operation is returned.
1.518 + * This count includes the strings from capture groups in the delimiter pattern.
1.519 + * This behavior differs from Java, which ignores capture groups.
1.520 + *
1.521 + * For the best performance on split() operations,
1.522 + * <code>RegexMatcher::split</code> is preferable to this function
1.523 + *
1.524 + * @param input The string to be split into fields. The field delimiters
1.525 + * match the pattern (in the "this" object)
1.526 + * @param dest An array of mutable UText structs to receive the results of the split.
1.527 + * If a field is NULL, a new UText is allocated to contain the results for
1.528 + * that field. This new UText is not guaranteed to be mutable.
1.529 + * @param destCapacity The number of elements in the destination array.
1.530 + * If the number of fields found is less than destCapacity, the
1.531 + * extra strings in the destination array are not altered.
1.532 + * If the number of destination strings is less than the number
1.533 + * of fields, the trailing part of the input string, including any
1.534 + * field delimiters, is placed in the last destination string.
1.535 + * @param status A reference to a UErrorCode to receive any errors.
1.536 + * @return The number of destination strings used.
1.537 + *
1.538 + * @stable ICU 4.6
1.539 + */
1.540 + virtual int32_t split(UText *input,
1.541 + UText *dest[],
1.542 + int32_t destCapacity,
1.543 + UErrorCode &status) const;
1.544 +
1.545 +
1.546 + /**
1.547 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.548 + *
1.549 + * @stable ICU 2.4
1.550 + */
1.551 + virtual UClassID getDynamicClassID() const;
1.552 +
1.553 + /**
1.554 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.555 + *
1.556 + * @stable ICU 2.4
1.557 + */
1.558 + static UClassID U_EXPORT2 getStaticClassID();
1.559 +
1.560 +private:
1.561 + //
1.562 + // Implementation Data
1.563 + //
1.564 + UText *fPattern; // The original pattern string.
1.565 + UnicodeString *fPatternString; // The original pattern UncodeString if relevant
1.566 + uint32_t fFlags; // The flags used when compiling the pattern.
1.567 + //
1.568 + UVector64 *fCompiledPat; // The compiled pattern p-code.
1.569 + UnicodeString fLiteralText; // Any literal string data from the pattern,
1.570 + // after un-escaping, for use during the match.
1.571 +
1.572 + UVector *fSets; // Any UnicodeSets referenced from the pattern.
1.573 + Regex8BitSet *fSets8; // (and fast sets for latin-1 range.)
1.574 +
1.575 +
1.576 + UErrorCode fDeferredStatus; // status if some prior error has left this
1.577 + // RegexPattern in an unusable state.
1.578 +
1.579 + int32_t fMinMatchLen; // Minimum Match Length. All matches will have length
1.580 + // >= this value. For some patterns, this calculated
1.581 + // value may be less than the true shortest
1.582 + // possible match.
1.583 +
1.584 + int32_t fFrameSize; // Size of a state stack frame in the
1.585 + // execution engine.
1.586 +
1.587 + int32_t fDataSize; // The size of the data needed by the pattern that
1.588 + // does not go on the state stack, but has just
1.589 + // a single copy per matcher.
1.590 +
1.591 + UVector32 *fGroupMap; // Map from capture group number to position of
1.592 + // the group's variables in the matcher stack frame.
1.593 +
1.594 + int32_t fMaxCaptureDigits;
1.595 +
1.596 + UnicodeSet **fStaticSets; // Ptr to static (shared) sets for predefined
1.597 + // regex character classes, e.g. Word.
1.598 +
1.599 + Regex8BitSet *fStaticSets8; // Ptr to the static (shared) latin-1 only
1.600 + // sets for predefined regex classes.
1.601 +
1.602 + int32_t fStartType; // Info on how a match must start.
1.603 + int32_t fInitialStringIdx; //
1.604 + int32_t fInitialStringLen;
1.605 + UnicodeSet *fInitialChars;
1.606 + UChar32 fInitialChar;
1.607 + Regex8BitSet *fInitialChars8;
1.608 + UBool fNeedsAltInput;
1.609 +
1.610 + friend class RegexCompile;
1.611 + friend class RegexMatcher;
1.612 + friend class RegexCImpl;
1.613 +
1.614 + //
1.615 + // Implementation Methods
1.616 + //
1.617 + void init(); // Common initialization, for use by constructors.
1.618 + void zap(); // Common cleanup
1.619 +#ifdef REGEX_DEBUG
1.620 + void dumpOp(int32_t index) const;
1.621 + friend void U_EXPORT2 RegexPatternDump(const RegexPattern *);
1.622 +#endif
1.623 +
1.624 +};
1.625 +
1.626 +
1.627 +
1.628 +/**
1.629 + * class RegexMatcher bundles together a regular expression pattern and
1.630 + * input text to which the expression can be applied. It includes methods
1.631 + * for testing for matches, and for find and replace operations.
1.632 + *
1.633 + * <p>Class RegexMatcher is not intended to be subclassed.</p>
1.634 + *
1.635 + * @stable ICU 2.4
1.636 + */
1.637 +class U_I18N_API RegexMatcher: public UObject {
1.638 +public:
1.639 +
1.640 + /**
1.641 + * Construct a RegexMatcher for a regular expression.
1.642 + * This is a convenience method that avoids the need to explicitly create
1.643 + * a RegexPattern object. Note that if several RegexMatchers need to be
1.644 + * created for the same expression, it will be more efficient to
1.645 + * separately create and cache a RegexPattern object, and use
1.646 + * its matcher() method to create the RegexMatcher objects.
1.647 + *
1.648 + * @param regexp The Regular Expression to be compiled.
1.649 + * @param flags Regular expression options, such as case insensitive matching.
1.650 + * @see UREGEX_CASE_INSENSITIVE
1.651 + * @param status Any errors are reported by setting this UErrorCode variable.
1.652 + * @stable ICU 2.6
1.653 + */
1.654 + RegexMatcher(const UnicodeString ®exp, uint32_t flags, UErrorCode &status);
1.655 +
1.656 + /**
1.657 + * Construct a RegexMatcher for a regular expression.
1.658 + * This is a convenience method that avoids the need to explicitly create
1.659 + * a RegexPattern object. Note that if several RegexMatchers need to be
1.660 + * created for the same expression, it will be more efficient to
1.661 + * separately create and cache a RegexPattern object, and use
1.662 + * its matcher() method to create the RegexMatcher objects.
1.663 + *
1.664 + * @param regexp The regular expression to be compiled.
1.665 + * @param flags Regular expression options, such as case insensitive matching.
1.666 + * @see UREGEX_CASE_INSENSITIVE
1.667 + * @param status Any errors are reported by setting this UErrorCode variable.
1.668 + *
1.669 + * @stable ICU 4.6
1.670 + */
1.671 + RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);
1.672 +
1.673 + /**
1.674 + * Construct a RegexMatcher for a regular expression.
1.675 + * This is a convenience method that avoids the need to explicitly create
1.676 + * a RegexPattern object. Note that if several RegexMatchers need to be
1.677 + * created for the same expression, it will be more efficient to
1.678 + * separately create and cache a RegexPattern object, and use
1.679 + * its matcher() method to create the RegexMatcher objects.
1.680 + * <p>
1.681 + * The matcher will retain a reference to the supplied input string, and all regexp
1.682 + * pattern matching operations happen directly on the original string. It is
1.683 + * critical that the string not be altered or deleted before use by the regular
1.684 + * expression operations is complete.
1.685 + *
1.686 + * @param regexp The Regular Expression to be compiled.
1.687 + * @param input The string to match. The matcher retains a reference to the
1.688 + * caller's string; mo copy is made.
1.689 + * @param flags Regular expression options, such as case insensitive matching.
1.690 + * @see UREGEX_CASE_INSENSITIVE
1.691 + * @param status Any errors are reported by setting this UErrorCode variable.
1.692 + * @stable ICU 2.6
1.693 + */
1.694 + RegexMatcher(const UnicodeString ®exp, const UnicodeString &input,
1.695 + uint32_t flags, UErrorCode &status);
1.696 +
1.697 + /**
1.698 + * Construct a RegexMatcher for a regular expression.
1.699 + * This is a convenience method that avoids the need to explicitly create
1.700 + * a RegexPattern object. Note that if several RegexMatchers need to be
1.701 + * created for the same expression, it will be more efficient to
1.702 + * separately create and cache a RegexPattern object, and use
1.703 + * its matcher() method to create the RegexMatcher objects.
1.704 + * <p>
1.705 + * The matcher will make a shallow clone of the supplied input text, and all regexp
1.706 + * pattern matching operations happen on this clone. While read-only operations on
1.707 + * the supplied text are permitted, it is critical that the underlying string not be
1.708 + * altered or deleted before use by the regular expression operations is complete.
1.709 + *
1.710 + * @param regexp The Regular Expression to be compiled.
1.711 + * @param input The string to match. The matcher retains a shallow clone of the text.
1.712 + * @param flags Regular expression options, such as case insensitive matching.
1.713 + * @see UREGEX_CASE_INSENSITIVE
1.714 + * @param status Any errors are reported by setting this UErrorCode variable.
1.715 + *
1.716 + * @stable ICU 4.6
1.717 + */
1.718 + RegexMatcher(UText *regexp, UText *input,
1.719 + uint32_t flags, UErrorCode &status);
1.720 +
1.721 +private:
1.722 + /**
1.723 + * Cause a compilation error if an application accidentally attempts to
1.724 + * create a matcher with a (UChar *) string as input rather than
1.725 + * a UnicodeString. Avoids a dangling reference to a temporary string.
1.726 + * <p>
1.727 + * To efficiently work with UChar *strings, wrap the data in a UnicodeString
1.728 + * using one of the aliasing constructors, such as
1.729 + * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
1.730 + * or in a UText, using
1.731 + * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
1.732 + *
1.733 + */
1.734 + RegexMatcher(const UnicodeString ®exp, const UChar *input,
1.735 + uint32_t flags, UErrorCode &status);
1.736 +public:
1.737 +
1.738 +
1.739 + /**
1.740 + * Destructor.
1.741 + *
1.742 + * @stable ICU 2.4
1.743 + */
1.744 + virtual ~RegexMatcher();
1.745 +
1.746 +
1.747 + /**
1.748 + * Attempts to match the entire input region against the pattern.
1.749 + * @param status A reference to a UErrorCode to receive any errors.
1.750 + * @return TRUE if there is a match
1.751 + * @stable ICU 2.4
1.752 + */
1.753 + virtual UBool matches(UErrorCode &status);
1.754 +
1.755 +
1.756 + /**
1.757 + * Resets the matcher, then attempts to match the input beginning
1.758 + * at the specified startIndex, and extending to the end of the input.
1.759 + * The input region is reset to include the entire input string.
1.760 + * A successful match must extend to the end of the input.
1.761 + * @param startIndex The input string (native) index at which to begin matching.
1.762 + * @param status A reference to a UErrorCode to receive any errors.
1.763 + * @return TRUE if there is a match
1.764 + * @stable ICU 2.8
1.765 + */
1.766 + virtual UBool matches(int64_t startIndex, UErrorCode &status);
1.767 +
1.768 +
1.769 + /**
1.770 + * Attempts to match the input string, starting from the beginning of the region,
1.771 + * against the pattern. Like the matches() method, this function
1.772 + * always starts at the beginning of the input region;
1.773 + * unlike that function, it does not require that the entire region be matched.
1.774 + *
1.775 + * <p>If the match succeeds then more information can be obtained via the <code>start()</code>,
1.776 + * <code>end()</code>, and <code>group()</code> functions.</p>
1.777 + *
1.778 + * @param status A reference to a UErrorCode to receive any errors.
1.779 + * @return TRUE if there is a match at the start of the input string.
1.780 + * @stable ICU 2.4
1.781 + */
1.782 + virtual UBool lookingAt(UErrorCode &status);
1.783 +
1.784 +
1.785 + /**
1.786 + * Attempts to match the input string, starting from the specified index, against the pattern.
1.787 + * The match may be of any length, and is not required to extend to the end
1.788 + * of the input string. Contrast with match().
1.789 + *
1.790 + * <p>If the match succeeds then more information can be obtained via the <code>start()</code>,
1.791 + * <code>end()</code>, and <code>group()</code> functions.</p>
1.792 + *
1.793 + * @param startIndex The input string (native) index at which to begin matching.
1.794 + * @param status A reference to a UErrorCode to receive any errors.
1.795 + * @return TRUE if there is a match.
1.796 + * @stable ICU 2.8
1.797 + */
1.798 + virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);
1.799 +
1.800 +
1.801 + /**
1.802 + * Find the next pattern match in the input string.
1.803 + * The find begins searching the input at the location following the end of
1.804 + * the previous match, or at the start of the string if there is no previous match.
1.805 + * If a match is found, <code>start(), end()</code> and <code>group()</code>
1.806 + * will provide more information regarding the match.
1.807 + * <p>Note that if the input string is changed by the application,
1.808 + * use find(startPos, status) instead of find(), because the saved starting
1.809 + * position may not be valid with the altered input string.</p>
1.810 + * @return TRUE if a match is found.
1.811 + * @stable ICU 2.4
1.812 + */
1.813 + virtual UBool find();
1.814 +
1.815 +
1.816 + /**
1.817 + * Resets this RegexMatcher and then attempts to find the next substring of the
1.818 + * input string that matches the pattern, starting at the specified index.
1.819 + *
1.820 + * @param start The (native) index in the input string to begin the search.
1.821 + * @param status A reference to a UErrorCode to receive any errors.
1.822 + * @return TRUE if a match is found.
1.823 + * @stable ICU 2.4
1.824 + */
1.825 + virtual UBool find(int64_t start, UErrorCode &status);
1.826 +
1.827 +
1.828 + /**
1.829 + * Returns a string containing the text matched by the previous match.
1.830 + * If the pattern can match an empty string, an empty string may be returned.
1.831 + * @param status A reference to a UErrorCode to receive any errors.
1.832 + * Possible errors are U_REGEX_INVALID_STATE if no match
1.833 + * has been attempted or the last match failed.
1.834 + * @return a string containing the matched input text.
1.835 + * @stable ICU 2.4
1.836 + */
1.837 + virtual UnicodeString group(UErrorCode &status) const;
1.838 +
1.839 +
1.840 + /**
1.841 + * Returns a string containing the text captured by the given group
1.842 + * during the previous match operation. Group(0) is the entire match.
1.843 + *
1.844 + * @param groupNum the capture group number
1.845 + * @param status A reference to a UErrorCode to receive any errors.
1.846 + * Possible errors are U_REGEX_INVALID_STATE if no match
1.847 + * has been attempted or the last match failed and
1.848 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
1.849 + * @return the captured text
1.850 + * @stable ICU 2.4
1.851 + */
1.852 + virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;
1.853 +
1.854 +
1.855 + /**
1.856 + * Returns the number of capturing groups in this matcher's pattern.
1.857 + * @return the number of capture groups
1.858 + * @stable ICU 2.4
1.859 + */
1.860 + virtual int32_t groupCount() const;
1.861 +
1.862 +
1.863 + /**
1.864 + * Returns a shallow clone of the entire live input string with the UText current native index
1.865 + * set to the beginning of the requested group.
1.866 + *
1.867 + * @param dest The UText into which the input should be cloned, or NULL to create a new UText
1.868 + * @param group_len A reference to receive the length of the desired capture group
1.869 + * @param status A reference to a UErrorCode to receive any errors.
1.870 + * Possible errors are U_REGEX_INVALID_STATE if no match
1.871 + * has been attempted or the last match failed and
1.872 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
1.873 + * @return dest if non-NULL, a shallow copy of the input text otherwise
1.874 + *
1.875 + * @stable ICU 4.6
1.876 + */
1.877 + virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const;
1.878 +
1.879 + /**
1.880 + * Returns a shallow clone of the entire live input string with the UText current native index
1.881 + * set to the beginning of the requested group.
1.882 + *
1.883 + * @param groupNum The capture group number.
1.884 + * @param dest The UText into which the input should be cloned, or NULL to create a new UText.
1.885 + * @param group_len A reference to receive the length of the desired capture group
1.886 + * @param status A reference to a UErrorCode to receive any errors.
1.887 + * Possible errors are U_REGEX_INVALID_STATE if no match
1.888 + * has been attempted or the last match failed and
1.889 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
1.890 + * @return dest if non-NULL, a shallow copy of the input text otherwise
1.891 + *
1.892 + * @stable ICU 4.6
1.893 + */
1.894 + virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;
1.895 +
1.896 + /**
1.897 + * Returns a string containing the text captured by the given group
1.898 + * during the previous match operation. Group(0) is the entire match.
1.899 + *
1.900 + * @param groupNum the capture group number
1.901 + * @param dest A mutable UText in which the matching text is placed.
1.902 + * If NULL, a new UText will be created (which may not be mutable).
1.903 + * @param status A reference to a UErrorCode to receive any errors.
1.904 + * Possible errors are U_REGEX_INVALID_STATE if no match
1.905 + * has been attempted or the last match failed.
1.906 + * @return A string containing the matched input text. If a pre-allocated UText
1.907 + * was provided, it will always be used and returned.
1.908 + *
1.909 + * @internal ICU 4.4 technology preview
1.910 + */
1.911 + virtual UText *group(int32_t groupNum, UText *dest, UErrorCode &status) const;
1.912 +
1.913 +
1.914 + /**
1.915 + * Returns the index in the input string of the start of the text matched
1.916 + * during the previous match operation.
1.917 + * @param status a reference to a UErrorCode to receive any errors.
1.918 + * @return The (native) position in the input string of the start of the last match.
1.919 + * @stable ICU 2.4
1.920 + */
1.921 + virtual int32_t start(UErrorCode &status) const;
1.922 +
1.923 + /**
1.924 + * Returns the index in the input string of the start of the text matched
1.925 + * during the previous match operation.
1.926 + * @param status a reference to a UErrorCode to receive any errors.
1.927 + * @return The (native) position in the input string of the start of the last match.
1.928 + * @stable ICU 4.6
1.929 + */
1.930 + virtual int64_t start64(UErrorCode &status) const;
1.931 +
1.932 +
1.933 + /**
1.934 + * Returns the index in the input string of the start of the text matched by the
1.935 + * specified capture group during the previous match operation. Return -1 if
1.936 + * the capture group exists in the pattern, but was not part of the last match.
1.937 + *
1.938 + * @param group the capture group number
1.939 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.940 + * errors are U_REGEX_INVALID_STATE if no match has been
1.941 + * attempted or the last match failed, and
1.942 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1.943 + * @return the (native) start position of substring matched by the specified group.
1.944 + * @stable ICU 2.4
1.945 + */
1.946 + virtual int32_t start(int32_t group, UErrorCode &status) const;
1.947 +
1.948 + /**
1.949 + * Returns the index in the input string of the start of the text matched by the
1.950 + * specified capture group during the previous match operation. Return -1 if
1.951 + * the capture group exists in the pattern, but was not part of the last match.
1.952 + *
1.953 + * @param group the capture group number.
1.954 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.955 + * errors are U_REGEX_INVALID_STATE if no match has been
1.956 + * attempted or the last match failed, and
1.957 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
1.958 + * @return the (native) start position of substring matched by the specified group.
1.959 + * @stable ICU 4.6
1.960 + */
1.961 + virtual int64_t start64(int32_t group, UErrorCode &status) const;
1.962 +
1.963 +
1.964 + /**
1.965 + * Returns the index in the input string of the first character following the
1.966 + * text matched during the previous match operation.
1.967 + *
1.968 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.969 + * errors are U_REGEX_INVALID_STATE if no match has been
1.970 + * attempted or the last match failed.
1.971 + * @return the index of the last character matched, plus one.
1.972 + * The index value returned is a native index, corresponding to
1.973 + * code units for the underlying encoding type, for example,
1.974 + * a byte index for UTF-8.
1.975 + * @stable ICU 2.4
1.976 + */
1.977 + virtual int32_t end(UErrorCode &status) const;
1.978 +
1.979 + /**
1.980 + * Returns the index in the input string of the first character following the
1.981 + * text matched during the previous match operation.
1.982 + *
1.983 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.984 + * errors are U_REGEX_INVALID_STATE if no match has been
1.985 + * attempted or the last match failed.
1.986 + * @return the index of the last character matched, plus one.
1.987 + * The index value returned is a native index, corresponding to
1.988 + * code units for the underlying encoding type, for example,
1.989 + * a byte index for UTF-8.
1.990 + * @stable ICU 4.6
1.991 + */
1.992 + virtual int64_t end64(UErrorCode &status) const;
1.993 +
1.994 +
1.995 + /**
1.996 + * Returns the index in the input string of the character following the
1.997 + * text matched by the specified capture group during the previous match operation.
1.998 + *
1.999 + * @param group the capture group number
1.1000 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.1001 + * errors are U_REGEX_INVALID_STATE if no match has been
1.1002 + * attempted or the last match failed and
1.1003 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1.1004 + * @return the index of the first character following the text
1.1005 + * captured by the specified group during the previous match operation.
1.1006 + * Return -1 if the capture group exists in the pattern but was not part of the match.
1.1007 + * The index value returned is a native index, corresponding to
1.1008 + * code units for the underlying encoding type, for example,
1.1009 + * a byte index for UTF8.
1.1010 + * @stable ICU 2.4
1.1011 + */
1.1012 + virtual int32_t end(int32_t group, UErrorCode &status) const;
1.1013 +
1.1014 + /**
1.1015 + * Returns the index in the input string of the character following the
1.1016 + * text matched by the specified capture group during the previous match operation.
1.1017 + *
1.1018 + * @param group the capture group number
1.1019 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.1020 + * errors are U_REGEX_INVALID_STATE if no match has been
1.1021 + * attempted or the last match failed and
1.1022 + * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1.1023 + * @return the index of the first character following the text
1.1024 + * captured by the specified group during the previous match operation.
1.1025 + * Return -1 if the capture group exists in the pattern but was not part of the match.
1.1026 + * The index value returned is a native index, corresponding to
1.1027 + * code units for the underlying encoding type, for example,
1.1028 + * a byte index for UTF8.
1.1029 + * @stable ICU 4.6
1.1030 + */
1.1031 + virtual int64_t end64(int32_t group, UErrorCode &status) const;
1.1032 +
1.1033 +
1.1034 + /**
1.1035 + * Resets this matcher. The effect is to remove any memory of previous matches,
1.1036 + * and to cause subsequent find() operations to begin at the beginning of
1.1037 + * the input string.
1.1038 + *
1.1039 + * @return this RegexMatcher.
1.1040 + * @stable ICU 2.4
1.1041 + */
1.1042 + virtual RegexMatcher &reset();
1.1043 +
1.1044 +
1.1045 + /**
1.1046 + * Resets this matcher, and set the current input position.
1.1047 + * The effect is to remove any memory of previous matches,
1.1048 + * and to cause subsequent find() operations to begin at
1.1049 + * the specified (native) position in the input string.
1.1050 + * <p>
1.1051 + * The matcher's region is reset to its default, which is the entire
1.1052 + * input string.
1.1053 + * <p>
1.1054 + * An alternative to this function is to set a match region
1.1055 + * beginning at the desired index.
1.1056 + *
1.1057 + * @return this RegexMatcher.
1.1058 + * @stable ICU 2.8
1.1059 + */
1.1060 + virtual RegexMatcher &reset(int64_t index, UErrorCode &status);
1.1061 +
1.1062 +
1.1063 + /**
1.1064 + * Resets this matcher with a new input string. This allows instances of RegexMatcher
1.1065 + * to be reused, which is more efficient than creating a new RegexMatcher for
1.1066 + * each input string to be processed.
1.1067 + * @param input The new string on which subsequent pattern matches will operate.
1.1068 + * The matcher retains a reference to the callers string, and operates
1.1069 + * directly on that. Ownership of the string remains with the caller.
1.1070 + * Because no copy of the string is made, it is essential that the
1.1071 + * caller not delete the string until after regexp operations on it
1.1072 + * are done.
1.1073 + * Note that while a reset on the matcher with an input string that is then
1.1074 + * modified across/during matcher operations may be supported currently for UnicodeString,
1.1075 + * this was not originally intended behavior, and support for this is not guaranteed
1.1076 + * in upcoming versions of ICU.
1.1077 + * @return this RegexMatcher.
1.1078 + * @stable ICU 2.4
1.1079 + */
1.1080 + virtual RegexMatcher &reset(const UnicodeString &input);
1.1081 +
1.1082 +
1.1083 + /**
1.1084 + * Resets this matcher with a new input string. This allows instances of RegexMatcher
1.1085 + * to be reused, which is more efficient than creating a new RegexMatcher for
1.1086 + * each input string to be processed.
1.1087 + * @param input The new string on which subsequent pattern matches will operate.
1.1088 + * The matcher makes a shallow clone of the given text; ownership of the
1.1089 + * original string remains with the caller. Because no deep copy of the
1.1090 + * text is made, it is essential that the caller not modify the string
1.1091 + * until after regexp operations on it are done.
1.1092 + * @return this RegexMatcher.
1.1093 + *
1.1094 + * @stable ICU 4.6
1.1095 + */
1.1096 + virtual RegexMatcher &reset(UText *input);
1.1097 +
1.1098 +
1.1099 + /**
1.1100 + * Set the subject text string upon which the regular expression is looking for matches
1.1101 + * without changing any other aspect of the matching state.
1.1102 + * The new and previous text strings must have the same content.
1.1103 + *
1.1104 + * This function is intended for use in environments where ICU is operating on
1.1105 + * strings that may move around in memory. It provides a mechanism for notifying
1.1106 + * ICU that the string has been relocated, and providing a new UText to access the
1.1107 + * string in its new position.
1.1108 + *
1.1109 + * Note that the regular expression implementation never copies the underlying text
1.1110 + * of a string being matched, but always operates directly on the original text
1.1111 + * provided by the user. Refreshing simply drops the references to the old text
1.1112 + * and replaces them with references to the new.
1.1113 + *
1.1114 + * Caution: this function is normally used only by very specialized,
1.1115 + * system-level code. One example use case is with garbage collection that moves
1.1116 + * the text in memory.
1.1117 + *
1.1118 + * @param input The new (moved) text string.
1.1119 + * @param status Receives errors detected by this function.
1.1120 + *
1.1121 + * @stable ICU 4.8
1.1122 + */
1.1123 + virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);
1.1124 +
1.1125 +private:
1.1126 + /**
1.1127 + * Cause a compilation error if an application accidentally attempts to
1.1128 + * reset a matcher with a (UChar *) string as input rather than
1.1129 + * a UnicodeString. Avoids a dangling reference to a temporary string.
1.1130 + * <p>
1.1131 + * To efficiently work with UChar *strings, wrap the data in a UnicodeString
1.1132 + * using one of the aliasing constructors, such as
1.1133 + * <code>UnicodeString(UBool isTerminated, const UChar *text, int32_t textLength);</code>
1.1134 + * or in a UText, using
1.1135 + * <code>utext_openUChars(UText *ut, const UChar *text, int64_t textLength, UErrorCode *status);</code>
1.1136 + *
1.1137 + */
1.1138 + RegexMatcher &reset(const UChar *input);
1.1139 +public:
1.1140 +
1.1141 + /**
1.1142 + * Returns the input string being matched. Ownership of the string belongs to
1.1143 + * the matcher; it should not be altered or deleted. This method will work even if the input
1.1144 + * was originally supplied as a UText.
1.1145 + * @return the input string
1.1146 + * @stable ICU 2.4
1.1147 + */
1.1148 + virtual const UnicodeString &input() const;
1.1149 +
1.1150 + /**
1.1151 + * Returns the input string being matched. This is the live input text; it should not be
1.1152 + * altered or deleted. This method will work even if the input was originally supplied as
1.1153 + * a UnicodeString.
1.1154 + * @return the input text
1.1155 + *
1.1156 + * @stable ICU 4.6
1.1157 + */
1.1158 + virtual UText *inputText() const;
1.1159 +
1.1160 + /**
1.1161 + * Returns the input string being matched, either by copying it into the provided
1.1162 + * UText parameter or by returning a shallow clone of the live input. Note that copying
1.1163 + * the entire input may cause significant performance and memory issues.
1.1164 + * @param dest The UText into which the input should be copied, or NULL to create a new UText
1.1165 + * @param status error code
1.1166 + * @return dest if non-NULL, a shallow copy of the input text otherwise
1.1167 + *
1.1168 + * @stable ICU 4.6
1.1169 + */
1.1170 + virtual UText *getInput(UText *dest, UErrorCode &status) const;
1.1171 +
1.1172 +
1.1173 + /** Sets the limits of this matcher's region.
1.1174 + * The region is the part of the input string that will be searched to find a match.
1.1175 + * Invoking this method resets the matcher, and then sets the region to start
1.1176 + * at the index specified by the start parameter and end at the index specified
1.1177 + * by the end parameter.
1.1178 + *
1.1179 + * Depending on the transparency and anchoring being used (see useTransparentBounds
1.1180 + * and useAnchoringBounds), certain constructs such as anchors may behave differently
1.1181 + * at or around the boundaries of the region
1.1182 + *
1.1183 + * The function will fail if start is greater than limit, or if either index
1.1184 + * is less than zero or greater than the length of the string being matched.
1.1185 + *
1.1186 + * @param start The (native) index to begin searches at.
1.1187 + * @param limit The index to end searches at (exclusive).
1.1188 + * @param status A reference to a UErrorCode to receive any errors.
1.1189 + * @stable ICU 4.0
1.1190 + */
1.1191 + virtual RegexMatcher ®ion(int64_t start, int64_t limit, UErrorCode &status);
1.1192 +
1.1193 + /**
1.1194 + * Identical to region(start, limit, status) but also allows a start position without
1.1195 + * resetting the region state.
1.1196 + * @param regionStart The region start
1.1197 + * @param regionLimit the limit of the region
1.1198 + * @param startIndex The (native) index within the region bounds at which to begin searches.
1.1199 + * @param status A reference to a UErrorCode to receive any errors.
1.1200 + * If startIndex is not within the specified region bounds,
1.1201 + * U_INDEX_OUTOFBOUNDS_ERROR is returned.
1.1202 + * @stable ICU 4.6
1.1203 + */
1.1204 + virtual RegexMatcher ®ion(int64_t regionStart, int64_t regionLimit, int64_t startIndex, UErrorCode &status);
1.1205 +
1.1206 + /**
1.1207 + * Reports the start index of this matcher's region. The searches this matcher
1.1208 + * conducts are limited to finding matches within regionStart (inclusive) and
1.1209 + * regionEnd (exclusive).
1.1210 + *
1.1211 + * @return The starting (native) index of this matcher's region.
1.1212 + * @stable ICU 4.0
1.1213 + */
1.1214 + virtual int32_t regionStart() const;
1.1215 +
1.1216 + /**
1.1217 + * Reports the start index of this matcher's region. The searches this matcher
1.1218 + * conducts are limited to finding matches within regionStart (inclusive) and
1.1219 + * regionEnd (exclusive).
1.1220 + *
1.1221 + * @return The starting (native) index of this matcher's region.
1.1222 + * @stable ICU 4.6
1.1223 + */
1.1224 + virtual int64_t regionStart64() const;
1.1225 +
1.1226 +
1.1227 + /**
1.1228 + * Reports the end (limit) index (exclusive) of this matcher's region. The searches
1.1229 + * this matcher conducts are limited to finding matches within regionStart
1.1230 + * (inclusive) and regionEnd (exclusive).
1.1231 + *
1.1232 + * @return The ending point (native) of this matcher's region.
1.1233 + * @stable ICU 4.0
1.1234 + */
1.1235 + virtual int32_t regionEnd() const;
1.1236 +
1.1237 + /**
1.1238 + * Reports the end (limit) index (exclusive) of this matcher's region. The searches
1.1239 + * this matcher conducts are limited to finding matches within regionStart
1.1240 + * (inclusive) and regionEnd (exclusive).
1.1241 + *
1.1242 + * @return The ending point (native) of this matcher's region.
1.1243 + * @stable ICU 4.6
1.1244 + */
1.1245 + virtual int64_t regionEnd64() const;
1.1246 +
1.1247 + /**
1.1248 + * Queries the transparency of region bounds for this matcher.
1.1249 + * See useTransparentBounds for a description of transparent and opaque bounds.
1.1250 + * By default, a matcher uses opaque region boundaries.
1.1251 + *
1.1252 + * @return TRUE if this matcher is using opaque bounds, false if it is not.
1.1253 + * @stable ICU 4.0
1.1254 + */
1.1255 + virtual UBool hasTransparentBounds() const;
1.1256 +
1.1257 + /**
1.1258 + * Sets the transparency of region bounds for this matcher.
1.1259 + * Invoking this function with an argument of true will set this matcher to use transparent bounds.
1.1260 + * If the boolean argument is false, then opaque bounds will be used.
1.1261 + *
1.1262 + * Using transparent bounds, the boundaries of this matcher's region are transparent
1.1263 + * to lookahead, lookbehind, and boundary matching constructs. Those constructs can
1.1264 + * see text beyond the boundaries of the region while checking for a match.
1.1265 + *
1.1266 + * With opaque bounds, no text outside of the matcher's region is visible to lookahead,
1.1267 + * lookbehind, and boundary matching constructs.
1.1268 + *
1.1269 + * By default, a matcher uses opaque bounds.
1.1270 + *
1.1271 + * @param b TRUE for transparent bounds; FALSE for opaque bounds
1.1272 + * @return This Matcher;
1.1273 + * @stable ICU 4.0
1.1274 + **/
1.1275 + virtual RegexMatcher &useTransparentBounds(UBool b);
1.1276 +
1.1277 +
1.1278 + /**
1.1279 + * Return true if this matcher is using anchoring bounds.
1.1280 + * By default, matchers use anchoring region bounds.
1.1281 + *
1.1282 + * @return TRUE if this matcher is using anchoring bounds.
1.1283 + * @stable ICU 4.0
1.1284 + */
1.1285 + virtual UBool hasAnchoringBounds() const;
1.1286 +
1.1287 +
1.1288 + /**
1.1289 + * Set whether this matcher is using Anchoring Bounds for its region.
1.1290 + * With anchoring bounds, pattern anchors such as ^ and $ will match at the start
1.1291 + * and end of the region. Without Anchoring Bounds, anchors will only match at
1.1292 + * the positions they would in the complete text.
1.1293 + *
1.1294 + * Anchoring Bounds are the default for regions.
1.1295 + *
1.1296 + * @param b TRUE if to enable anchoring bounds; FALSE to disable them.
1.1297 + * @return This Matcher
1.1298 + * @stable ICU 4.0
1.1299 + */
1.1300 + virtual RegexMatcher &useAnchoringBounds(UBool b);
1.1301 +
1.1302 +
1.1303 + /**
1.1304 + * Return TRUE if the most recent matching operation attempted to access
1.1305 + * additional input beyond the available input text.
1.1306 + * In this case, additional input text could change the results of the match.
1.1307 + *
1.1308 + * hitEnd() is defined for both successful and unsuccessful matches.
1.1309 + * In either case hitEnd() will return TRUE if if the end of the text was
1.1310 + * reached at any point during the matching process.
1.1311 + *
1.1312 + * @return TRUE if the most recent match hit the end of input
1.1313 + * @stable ICU 4.0
1.1314 + */
1.1315 + virtual UBool hitEnd() const;
1.1316 +
1.1317 + /**
1.1318 + * Return TRUE the most recent match succeeded and additional input could cause
1.1319 + * it to fail. If this method returns false and a match was found, then more input
1.1320 + * might change the match but the match won't be lost. If a match was not found,
1.1321 + * then requireEnd has no meaning.
1.1322 + *
1.1323 + * @return TRUE if more input could cause the most recent match to no longer match.
1.1324 + * @stable ICU 4.0
1.1325 + */
1.1326 + virtual UBool requireEnd() const;
1.1327 +
1.1328 +
1.1329 + /**
1.1330 + * Returns the pattern that is interpreted by this matcher.
1.1331 + * @return the RegexPattern for this RegexMatcher
1.1332 + * @stable ICU 2.4
1.1333 + */
1.1334 + virtual const RegexPattern &pattern() const;
1.1335 +
1.1336 +
1.1337 + /**
1.1338 + * Replaces every substring of the input that matches the pattern
1.1339 + * with the given replacement string. This is a convenience function that
1.1340 + * provides a complete find-and-replace-all operation.
1.1341 + *
1.1342 + * This method first resets this matcher. It then scans the input string
1.1343 + * looking for matches of the pattern. Input that is not part of any
1.1344 + * match is left unchanged; each match is replaced in the result by the
1.1345 + * replacement string. The replacement string may contain references to
1.1346 + * capture groups.
1.1347 + *
1.1348 + * @param replacement a string containing the replacement text.
1.1349 + * @param status a reference to a UErrorCode to receive any errors.
1.1350 + * @return a string containing the results of the find and replace.
1.1351 + * @stable ICU 2.4
1.1352 + */
1.1353 + virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);
1.1354 +
1.1355 +
1.1356 + /**
1.1357 + * Replaces every substring of the input that matches the pattern
1.1358 + * with the given replacement string. This is a convenience function that
1.1359 + * provides a complete find-and-replace-all operation.
1.1360 + *
1.1361 + * This method first resets this matcher. It then scans the input string
1.1362 + * looking for matches of the pattern. Input that is not part of any
1.1363 + * match is left unchanged; each match is replaced in the result by the
1.1364 + * replacement string. The replacement string may contain references to
1.1365 + * capture groups.
1.1366 + *
1.1367 + * @param replacement a string containing the replacement text.
1.1368 + * @param dest a mutable UText in which the results are placed.
1.1369 + * If NULL, a new UText will be created (which may not be mutable).
1.1370 + * @param status a reference to a UErrorCode to receive any errors.
1.1371 + * @return a string containing the results of the find and replace.
1.1372 + * If a pre-allocated UText was provided, it will always be used and returned.
1.1373 + *
1.1374 + * @stable ICU 4.6
1.1375 + */
1.1376 + virtual UText *replaceAll(UText *replacement, UText *dest, UErrorCode &status);
1.1377 +
1.1378 +
1.1379 + /**
1.1380 + * Replaces the first substring of the input that matches
1.1381 + * the pattern with the replacement string. This is a convenience
1.1382 + * function that provides a complete find-and-replace operation.
1.1383 + *
1.1384 + * <p>This function first resets this RegexMatcher. It then scans the input string
1.1385 + * looking for a match of the pattern. Input that is not part
1.1386 + * of the match is appended directly to the result string; the match is replaced
1.1387 + * in the result by the replacement string. The replacement string may contain
1.1388 + * references to captured groups.</p>
1.1389 + *
1.1390 + * <p>The state of the matcher (the position at which a subsequent find()
1.1391 + * would begin) after completing a replaceFirst() is not specified. The
1.1392 + * RegexMatcher should be reset before doing additional find() operations.</p>
1.1393 + *
1.1394 + * @param replacement a string containing the replacement text.
1.1395 + * @param status a reference to a UErrorCode to receive any errors.
1.1396 + * @return a string containing the results of the find and replace.
1.1397 + * @stable ICU 2.4
1.1398 + */
1.1399 + virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status);
1.1400 +
1.1401 +
1.1402 + /**
1.1403 + * Replaces the first substring of the input that matches
1.1404 + * the pattern with the replacement string. This is a convenience
1.1405 + * function that provides a complete find-and-replace operation.
1.1406 + *
1.1407 + * <p>This function first resets this RegexMatcher. It then scans the input string
1.1408 + * looking for a match of the pattern. Input that is not part
1.1409 + * of the match is appended directly to the result string; the match is replaced
1.1410 + * in the result by the replacement string. The replacement string may contain
1.1411 + * references to captured groups.</p>
1.1412 + *
1.1413 + * <p>The state of the matcher (the position at which a subsequent find()
1.1414 + * would begin) after completing a replaceFirst() is not specified. The
1.1415 + * RegexMatcher should be reset before doing additional find() operations.</p>
1.1416 + *
1.1417 + * @param replacement a string containing the replacement text.
1.1418 + * @param dest a mutable UText in which the results are placed.
1.1419 + * If NULL, a new UText will be created (which may not be mutable).
1.1420 + * @param status a reference to a UErrorCode to receive any errors.
1.1421 + * @return a string containing the results of the find and replace.
1.1422 + * If a pre-allocated UText was provided, it will always be used and returned.
1.1423 + *
1.1424 + * @stable ICU 4.6
1.1425 + */
1.1426 + virtual UText *replaceFirst(UText *replacement, UText *dest, UErrorCode &status);
1.1427 +
1.1428 +
1.1429 + /**
1.1430 + * Implements a replace operation intended to be used as part of an
1.1431 + * incremental find-and-replace.
1.1432 + *
1.1433 + * <p>The input string, starting from the end of the previous replacement and ending at
1.1434 + * the start of the current match, is appended to the destination string. Then the
1.1435 + * replacement string is appended to the output string,
1.1436 + * including handling any substitutions of captured text.</p>
1.1437 + *
1.1438 + * <p>For simple, prepackaged, non-incremental find-and-replace
1.1439 + * operations, see replaceFirst() or replaceAll().</p>
1.1440 + *
1.1441 + * @param dest A UnicodeString to which the results of the find-and-replace are appended.
1.1442 + * @param replacement A UnicodeString that provides the text to be substituted for
1.1443 + * the input text that matched the regexp pattern. The replacement
1.1444 + * text may contain references to captured text from the
1.1445 + * input.
1.1446 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.1447 + * errors are U_REGEX_INVALID_STATE if no match has been
1.1448 + * attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR
1.1449 + * if the replacement text specifies a capture group that
1.1450 + * does not exist in the pattern.
1.1451 + *
1.1452 + * @return this RegexMatcher
1.1453 + * @stable ICU 2.4
1.1454 + *
1.1455 + */
1.1456 + virtual RegexMatcher &appendReplacement(UnicodeString &dest,
1.1457 + const UnicodeString &replacement, UErrorCode &status);
1.1458 +
1.1459 +
1.1460 + /**
1.1461 + * Implements a replace operation intended to be used as part of an
1.1462 + * incremental find-and-replace.
1.1463 + *
1.1464 + * <p>The input string, starting from the end of the previous replacement and ending at
1.1465 + * the start of the current match, is appended to the destination string. Then the
1.1466 + * replacement string is appended to the output string,
1.1467 + * including handling any substitutions of captured text.</p>
1.1468 + *
1.1469 + * <p>For simple, prepackaged, non-incremental find-and-replace
1.1470 + * operations, see replaceFirst() or replaceAll().</p>
1.1471 + *
1.1472 + * @param dest A mutable UText to which the results of the find-and-replace are appended.
1.1473 + * Must not be NULL.
1.1474 + * @param replacement A UText that provides the text to be substituted for
1.1475 + * the input text that matched the regexp pattern. The replacement
1.1476 + * text may contain references to captured text from the input.
1.1477 + * @param status A reference to a UErrorCode to receive any errors. Possible
1.1478 + * errors are U_REGEX_INVALID_STATE if no match has been
1.1479 + * attempted or the last match failed, and U_INDEX_OUTOFBOUNDS_ERROR
1.1480 + * if the replacement text specifies a capture group that
1.1481 + * does not exist in the pattern.
1.1482 + *
1.1483 + * @return this RegexMatcher
1.1484 + *
1.1485 + * @stable ICU 4.6
1.1486 + */
1.1487 + virtual RegexMatcher &appendReplacement(UText *dest,
1.1488 + UText *replacement, UErrorCode &status);
1.1489 +
1.1490 +
1.1491 + /**
1.1492 + * As the final step in a find-and-replace operation, append the remainder
1.1493 + * of the input string, starting at the position following the last appendReplacement(),
1.1494 + * to the destination string. <code>appendTail()</code> is intended to be invoked after one
1.1495 + * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.
1.1496 + *
1.1497 + * @param dest A UnicodeString to which the results of the find-and-replace are appended.
1.1498 + * @return the destination string.
1.1499 + * @stable ICU 2.4
1.1500 + */
1.1501 + virtual UnicodeString &appendTail(UnicodeString &dest);
1.1502 +
1.1503 +
1.1504 + /**
1.1505 + * As the final step in a find-and-replace operation, append the remainder
1.1506 + * of the input string, starting at the position following the last appendReplacement(),
1.1507 + * to the destination string. <code>appendTail()</code> is intended to be invoked after one
1.1508 + * or more invocations of the <code>RegexMatcher::appendReplacement()</code>.
1.1509 + *
1.1510 + * @param dest A mutable UText to which the results of the find-and-replace are appended.
1.1511 + * Must not be NULL.
1.1512 + * @param status error cod
1.1513 + * @return the destination string.
1.1514 + *
1.1515 + * @stable ICU 4.6
1.1516 + */
1.1517 + virtual UText *appendTail(UText *dest, UErrorCode &status);
1.1518 +
1.1519 +
1.1520 + /**
1.1521 + * Split a string into fields. Somewhat like split() from Perl.
1.1522 + * The pattern matches identify delimiters that separate the input
1.1523 + * into fields. The input data between the matches becomes the
1.1524 + * fields themselves.
1.1525 + *
1.1526 + * @param input The string to be split into fields. The field delimiters
1.1527 + * match the pattern (in the "this" object). This matcher
1.1528 + * will be reset to this input string.
1.1529 + * @param dest An array of UnicodeStrings to receive the results of the split.
1.1530 + * This is an array of actual UnicodeString objects, not an
1.1531 + * array of pointers to strings. Local (stack based) arrays can
1.1532 + * work well here.
1.1533 + * @param destCapacity The number of elements in the destination array.
1.1534 + * If the number of fields found is less than destCapacity, the
1.1535 + * extra strings in the destination array are not altered.
1.1536 + * If the number of destination strings is less than the number
1.1537 + * of fields, the trailing part of the input string, including any
1.1538 + * field delimiters, is placed in the last destination string.
1.1539 + * @param status A reference to a UErrorCode to receive any errors.
1.1540 + * @return The number of fields into which the input string was split.
1.1541 + * @stable ICU 2.6
1.1542 + */
1.1543 + virtual int32_t split(const UnicodeString &input,
1.1544 + UnicodeString dest[],
1.1545 + int32_t destCapacity,
1.1546 + UErrorCode &status);
1.1547 +
1.1548 +
1.1549 + /**
1.1550 + * Split a string into fields. Somewhat like split() from Perl.
1.1551 + * The pattern matches identify delimiters that separate the input
1.1552 + * into fields. The input data between the matches becomes the
1.1553 + * fields themselves.
1.1554 + *
1.1555 + * @param input The string to be split into fields. The field delimiters
1.1556 + * match the pattern (in the "this" object). This matcher
1.1557 + * will be reset to this input string.
1.1558 + * @param dest An array of mutable UText structs to receive the results of the split.
1.1559 + * If a field is NULL, a new UText is allocated to contain the results for
1.1560 + * that field. This new UText is not guaranteed to be mutable.
1.1561 + * @param destCapacity The number of elements in the destination array.
1.1562 + * If the number of fields found is less than destCapacity, the
1.1563 + * extra strings in the destination array are not altered.
1.1564 + * If the number of destination strings is less than the number
1.1565 + * of fields, the trailing part of the input string, including any
1.1566 + * field delimiters, is placed in the last destination string.
1.1567 + * @param status A reference to a UErrorCode to receive any errors.
1.1568 + * @return The number of fields into which the input string was split.
1.1569 + *
1.1570 + * @stable ICU 4.6
1.1571 + */
1.1572 + virtual int32_t split(UText *input,
1.1573 + UText *dest[],
1.1574 + int32_t destCapacity,
1.1575 + UErrorCode &status);
1.1576 +
1.1577 + /**
1.1578 + * Set a processing time limit for match operations with this Matcher.
1.1579 + *
1.1580 + * Some patterns, when matching certain strings, can run in exponential time.
1.1581 + * For practical purposes, the match operation may appear to be in an
1.1582 + * infinite loop.
1.1583 + * When a limit is set a match operation will fail with an error if the
1.1584 + * limit is exceeded.
1.1585 + * <p>
1.1586 + * The units of the limit are steps of the match engine.
1.1587 + * Correspondence with actual processor time will depend on the speed
1.1588 + * of the processor and the details of the specific pattern, but will
1.1589 + * typically be on the order of milliseconds.
1.1590 + * <p>
1.1591 + * By default, the matching time is not limited.
1.1592 + * <p>
1.1593 + *
1.1594 + * @param limit The limit value, or 0 for no limit.
1.1595 + * @param status A reference to a UErrorCode to receive any errors.
1.1596 + * @stable ICU 4.0
1.1597 + */
1.1598 + virtual void setTimeLimit(int32_t limit, UErrorCode &status);
1.1599 +
1.1600 + /**
1.1601 + * Get the time limit, if any, for match operations made with this Matcher.
1.1602 + *
1.1603 + * @return the maximum allowed time for a match, in units of processing steps.
1.1604 + * @stable ICU 4.0
1.1605 + */
1.1606 + virtual int32_t getTimeLimit() const;
1.1607 +
1.1608 + /**
1.1609 + * Set the amount of heap storage available for use by the match backtracking stack.
1.1610 + * The matcher is also reset, discarding any results from previous matches.
1.1611 + * <p>
1.1612 + * ICU uses a backtracking regular expression engine, with the backtrack stack
1.1613 + * maintained on the heap. This function sets the limit to the amount of memory
1.1614 + * that can be used for this purpose. A backtracking stack overflow will
1.1615 + * result in an error from the match operation that caused it.
1.1616 + * <p>
1.1617 + * A limit is desirable because a malicious or poorly designed pattern can use
1.1618 + * excessive memory, potentially crashing the process. A limit is enabled
1.1619 + * by default.
1.1620 + * <p>
1.1621 + * @param limit The maximum size, in bytes, of the matching backtrack stack.
1.1622 + * A value of zero means no limit.
1.1623 + * The limit must be greater or equal to zero.
1.1624 + *
1.1625 + * @param status A reference to a UErrorCode to receive any errors.
1.1626 + *
1.1627 + * @stable ICU 4.0
1.1628 + */
1.1629 + virtual void setStackLimit(int32_t limit, UErrorCode &status);
1.1630 +
1.1631 + /**
1.1632 + * Get the size of the heap storage available for use by the back tracking stack.
1.1633 + *
1.1634 + * @return the maximum backtracking stack size, in bytes, or zero if the
1.1635 + * stack size is unlimited.
1.1636 + * @stable ICU 4.0
1.1637 + */
1.1638 + virtual int32_t getStackLimit() const;
1.1639 +
1.1640 +
1.1641 + /**
1.1642 + * Set a callback function for use with this Matcher.
1.1643 + * During matching operations the function will be called periodically,
1.1644 + * giving the application the opportunity to terminate a long-running
1.1645 + * match.
1.1646 + *
1.1647 + * @param callback A pointer to the user-supplied callback function.
1.1648 + * @param context User context pointer. The value supplied at the
1.1649 + * time the callback function is set will be saved
1.1650 + * and passed to the callback each time that it is called.
1.1651 + * @param status A reference to a UErrorCode to receive any errors.
1.1652 + * @stable ICU 4.0
1.1653 + */
1.1654 + virtual void setMatchCallback(URegexMatchCallback *callback,
1.1655 + const void *context,
1.1656 + UErrorCode &status);
1.1657 +
1.1658 +
1.1659 + /**
1.1660 + * Get the callback function for this URegularExpression.
1.1661 + *
1.1662 + * @param callback Out parameter, receives a pointer to the user-supplied
1.1663 + * callback function.
1.1664 + * @param context Out parameter, receives the user context pointer that
1.1665 + * was set when uregex_setMatchCallback() was called.
1.1666 + * @param status A reference to a UErrorCode to receive any errors.
1.1667 + * @stable ICU 4.0
1.1668 + */
1.1669 + virtual void getMatchCallback(URegexMatchCallback *&callback,
1.1670 + const void *&context,
1.1671 + UErrorCode &status);
1.1672 +
1.1673 +
1.1674 + /**
1.1675 + * Set a progress callback function for use with find operations on this Matcher.
1.1676 + * During find operations, the callback will be invoked after each return from a
1.1677 + * match attempt, giving the application the opportunity to terminate a long-running
1.1678 + * find operation.
1.1679 + *
1.1680 + * @param callback A pointer to the user-supplied callback function.
1.1681 + * @param context User context pointer. The value supplied at the
1.1682 + * time the callback function is set will be saved
1.1683 + * and passed to the callback each time that it is called.
1.1684 + * @param status A reference to a UErrorCode to receive any errors.
1.1685 + * @stable ICU 4.6
1.1686 + */
1.1687 + virtual void setFindProgressCallback(URegexFindProgressCallback *callback,
1.1688 + const void *context,
1.1689 + UErrorCode &status);
1.1690 +
1.1691 +
1.1692 + /**
1.1693 + * Get the find progress callback function for this URegularExpression.
1.1694 + *
1.1695 + * @param callback Out parameter, receives a pointer to the user-supplied
1.1696 + * callback function.
1.1697 + * @param context Out parameter, receives the user context pointer that
1.1698 + * was set when uregex_setFindProgressCallback() was called.
1.1699 + * @param status A reference to a UErrorCode to receive any errors.
1.1700 + * @stable ICU 4.6
1.1701 + */
1.1702 + virtual void getFindProgressCallback(URegexFindProgressCallback *&callback,
1.1703 + const void *&context,
1.1704 + UErrorCode &status);
1.1705 +
1.1706 +#ifndef U_HIDE_INTERNAL_API
1.1707 + /**
1.1708 + * setTrace Debug function, enable/disable tracing of the matching engine.
1.1709 + * For internal ICU development use only. DO NO USE!!!!
1.1710 + * @internal
1.1711 + */
1.1712 + void setTrace(UBool state);
1.1713 +#endif /* U_HIDE_INTERNAL_API */
1.1714 +
1.1715 + /**
1.1716 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.1717 + *
1.1718 + * @stable ICU 2.2
1.1719 + */
1.1720 + static UClassID U_EXPORT2 getStaticClassID();
1.1721 +
1.1722 + /**
1.1723 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.1724 + *
1.1725 + * @stable ICU 2.2
1.1726 + */
1.1727 + virtual UClassID getDynamicClassID() const;
1.1728 +
1.1729 +private:
1.1730 + // Constructors and other object boilerplate are private.
1.1731 + // Instances of RegexMatcher can not be assigned, copied, cloned, etc.
1.1732 + RegexMatcher(); // default constructor not implemented
1.1733 + RegexMatcher(const RegexPattern *pat);
1.1734 + RegexMatcher(const RegexMatcher &other);
1.1735 + RegexMatcher &operator =(const RegexMatcher &rhs);
1.1736 + void init(UErrorCode &status); // Common initialization
1.1737 + void init2(UText *t, UErrorCode &e); // Common initialization, part 2.
1.1738 +
1.1739 + friend class RegexPattern;
1.1740 + friend class RegexCImpl;
1.1741 +public:
1.1742 +#ifndef U_HIDE_INTERNAL_API
1.1743 + /** @internal */
1.1744 + void resetPreserveRegion(); // Reset matcher state, but preserve any region.
1.1745 +#endif /* U_HIDE_INTERNAL_API */
1.1746 +private:
1.1747 +
1.1748 + //
1.1749 + // MatchAt This is the internal interface to the match engine itself.
1.1750 + // Match status comes back in matcher member variables.
1.1751 + //
1.1752 + void MatchAt(int64_t startIdx, UBool toEnd, UErrorCode &status);
1.1753 + inline void backTrack(int64_t &inputIdx, int32_t &patIdx);
1.1754 + UBool isWordBoundary(int64_t pos); // perform Perl-like \b test
1.1755 + UBool isUWordBoundary(int64_t pos); // perform RBBI based \b test
1.1756 + REStackFrame *resetStack();
1.1757 + inline REStackFrame *StateSave(REStackFrame *fp, int64_t savePatIdx, UErrorCode &status);
1.1758 + void IncrementTime(UErrorCode &status);
1.1759 + UBool ReportFindProgress(int64_t matchIndex, UErrorCode &status);
1.1760 +
1.1761 + int64_t appendGroup(int32_t groupNum, UText *dest, UErrorCode &status) const;
1.1762 +
1.1763 + UBool findUsingChunk();
1.1764 + void MatchChunkAt(int32_t startIdx, UBool toEnd, UErrorCode &status);
1.1765 + UBool isChunkWordBoundary(int32_t pos);
1.1766 +
1.1767 + const RegexPattern *fPattern;
1.1768 + RegexPattern *fPatternOwned; // Non-NULL if this matcher owns the pattern, and
1.1769 + // should delete it when through.
1.1770 +
1.1771 + const UnicodeString *fInput; // The string being matched. Only used for input()
1.1772 + UText *fInputText; // The text being matched. Is never NULL.
1.1773 + UText *fAltInputText; // A shallow copy of the text being matched.
1.1774 + // Only created if the pattern contains backreferences.
1.1775 + int64_t fInputLength; // Full length of the input text.
1.1776 + int32_t fFrameSize; // The size of a frame in the backtrack stack.
1.1777 +
1.1778 + int64_t fRegionStart; // Start of the input region, default = 0.
1.1779 + int64_t fRegionLimit; // End of input region, default to input.length.
1.1780 +
1.1781 + int64_t fAnchorStart; // Region bounds for anchoring operations (^ or $).
1.1782 + int64_t fAnchorLimit; // See useAnchoringBounds
1.1783 +
1.1784 + int64_t fLookStart; // Region bounds for look-ahead/behind and
1.1785 + int64_t fLookLimit; // and other boundary tests. See
1.1786 + // useTransparentBounds
1.1787 +
1.1788 + int64_t fActiveStart; // Currently active bounds for matching.
1.1789 + int64_t fActiveLimit; // Usually is the same as region, but
1.1790 + // is changed to fLookStart/Limit when
1.1791 + // entering look around regions.
1.1792 +
1.1793 + UBool fTransparentBounds; // True if using transparent bounds.
1.1794 + UBool fAnchoringBounds; // True if using anchoring bounds.
1.1795 +
1.1796 + UBool fMatch; // True if the last attempted match was successful.
1.1797 + int64_t fMatchStart; // Position of the start of the most recent match
1.1798 + int64_t fMatchEnd; // First position after the end of the most recent match
1.1799 + // Zero if no previous match, even when a region
1.1800 + // is active.
1.1801 + int64_t fLastMatchEnd; // First position after the end of the previous match,
1.1802 + // or -1 if there was no previous match.
1.1803 + int64_t fAppendPosition; // First position after the end of the previous
1.1804 + // appendReplacement(). As described by the
1.1805 + // JavaDoc for Java Matcher, where it is called
1.1806 + // "append position"
1.1807 + UBool fHitEnd; // True if the last match touched the end of input.
1.1808 + UBool fRequireEnd; // True if the last match required end-of-input
1.1809 + // (matched $ or Z)
1.1810 +
1.1811 + UVector64 *fStack;
1.1812 + REStackFrame *fFrame; // After finding a match, the last active stack frame,
1.1813 + // which will contain the capture group results.
1.1814 + // NOT valid while match engine is running.
1.1815 +
1.1816 + int64_t *fData; // Data area for use by the compiled pattern.
1.1817 + int64_t fSmallData[8]; // Use this for data if it's enough.
1.1818 +
1.1819 + int32_t fTimeLimit; // Max time (in arbitrary steps) to let the
1.1820 + // match engine run. Zero for unlimited.
1.1821 +
1.1822 + int32_t fTime; // Match time, accumulates while matching.
1.1823 + int32_t fTickCounter; // Low bits counter for time. Counts down StateSaves.
1.1824 + // Kept separately from fTime to keep as much
1.1825 + // code as possible out of the inline
1.1826 + // StateSave function.
1.1827 +
1.1828 + int32_t fStackLimit; // Maximum memory size to use for the backtrack
1.1829 + // stack, in bytes. Zero for unlimited.
1.1830 +
1.1831 + URegexMatchCallback *fCallbackFn; // Pointer to match progress callback funct.
1.1832 + // NULL if there is no callback.
1.1833 + const void *fCallbackContext; // User Context ptr for callback function.
1.1834 +
1.1835 + URegexFindProgressCallback *fFindProgressCallbackFn; // Pointer to match progress callback funct.
1.1836 + // NULL if there is no callback.
1.1837 + const void *fFindProgressCallbackContext; // User Context ptr for callback function.
1.1838 +
1.1839 +
1.1840 + UBool fInputUniStrMaybeMutable; // Set when fInputText wraps a UnicodeString that may be mutable - compatibility.
1.1841 +
1.1842 + UBool fTraceDebug; // Set true for debug tracing of match engine.
1.1843 +
1.1844 + UErrorCode fDeferredStatus; // Save error state that cannot be immediately
1.1845 + // reported, or that permanently disables this matcher.
1.1846 +
1.1847 + RuleBasedBreakIterator *fWordBreakItr;
1.1848 +};
1.1849 +
1.1850 +U_NAMESPACE_END
1.1851 +#endif // UCONFIG_NO_REGULAR_EXPRESSIONS
1.1852 +#endif
