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