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