codekingpro/portable-devtools
116k
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 BreakIterator;
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 ®ex,
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 ®ex,
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 ®ex,
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 ®ex,
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 int32_t fStartType; // Info on how a match must start.
616 int32_t fInitialStringIdx; //
617 int32_t fInitialStringLen;
618 UnicodeSet *fInitialChars;
619 UChar32 fInitialChar;
620 Regex8BitSet *fInitialChars8;
621 UBool fNeedsAltInput;
622
623 UHashtable *fNamedCaptureMap; // Map from capture group names to numbers.
624
625 friend class RegexCompile;
626 friend class RegexMatcher;
627 friend class RegexCImpl;
628
629 //
630 // Implementation Methods
631 //
632 void init(); // Common initialization, for use by constructors.
633 bool initNamedCaptureMap(); // Lazy init for fNamedCaptureMap.
634 void zap(); // Common cleanup
635
636 void dumpOp(int32_t index) const;
637
638 public:
639#ifndef U_HIDE_INTERNAL_API
640 /**
641 * Dump a compiled pattern. Internal debug function.
642 * @internal
643 */
644 void dumpPattern() const;
645#endif /* U_HIDE_INTERNAL_API */
646};
647
648
649
650/**
651 * class RegexMatcher bundles together a regular expression pattern and
652 * input text to which the expression can be applied. It includes methods
653 * for testing for matches, and for find and replace operations.
654 *
655 * <p>Class RegexMatcher is not intended to be subclassed.</p>
656 *
657 * @stable ICU 2.4
658 */
659class U_I18N_API RegexMatcher U_FINAL : public UObject {
660public:
661
662 /**
663 * Construct a RegexMatcher for a regular expression.
664 * This is a convenience method that avoids the need to explicitly create
665 * a RegexPattern object. Note that if several RegexMatchers need to be
666 * created for the same expression, it will be more efficient to
667 * separately create and cache a RegexPattern object, and use
668 * its matcher() method to create the RegexMatcher objects.
669 *
670 * @param regexp The Regular Expression to be compiled.
671 * @param flags #URegexpFlag options, such as #UREGEX_CASE_INSENSITIVE.
672 * @param status Any errors are reported by setting this UErrorCode variable.
673 * @stable ICU 2.6
674 */
675 RegexMatcher(const UnicodeString ®exp, uint32_t flags, UErrorCode &status);
676
677 /**
678 * Construct a RegexMatcher for a regular expression.
679 * This is a convenience method that avoids the need to explicitly create
680 * a RegexPattern object. Note that if several RegexMatchers need to be
681 * created for the same expression, it will be more efficient to
682 * separately create and cache a RegexPattern object, and use
683 * its matcher() method to create the RegexMatcher objects.
684 *
685 * @param regexp The regular expression to be compiled.
686 * @param flags #URegexpFlag options, such as #UREGEX_CASE_INSENSITIVE.
687 * @param status Any errors are reported by setting this UErrorCode variable.
688 *
689 * @stable ICU 4.6
690 */
691 RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);
692
693 /**
694 * Construct a RegexMatcher for a regular expression.
695 * This is a convenience method that avoids the need to explicitly create
696 * a RegexPattern object. Note that if several RegexMatchers need to be
697 * created for the same expression, it will be more efficient to
698 * separately create and cache a RegexPattern object, and use
699 * its matcher() method to create the RegexMatcher objects.
700 *
701 * The matcher will retain a reference to the supplied input string, and all regexp
702 * pattern matching operations happen directly on the original string. It is
703 * critical that the string not be altered or deleted before use by the regular
704 * expression operations is complete.
705 *
706 * @param regexp The Regular Expression to be compiled.
707 * @param input The string to match. The matcher retains a reference to the
708 * caller's string; mo copy is made.
709 * @param flags #URegexpFlag options, such as #UREGEX_CASE_INSENSITIVE.
710 * @param status Any errors are reported by setting this UErrorCode variable.
711 * @stable ICU 2.6
712 */
713 RegexMatcher(const UnicodeString ®exp, const UnicodeString &input,
714 uint32_t flags, UErrorCode &status);
715
716 /**
717 * Construct a RegexMatcher for a regular expression.
718 * This is a convenience method that avoids the need to explicitly create
719 * a RegexPattern object. Note that if several RegexMatchers need to be
720 * created for the same expression, it will be more efficient to
721 * separately create and cache a RegexPattern object, and use
722 * its matcher() method to create the RegexMatcher objects.
723 *
724 * The matcher will make a shallow clone of the supplied input text, and all regexp
725 * pattern matching operations happen on this clone. While read-only operations on
726 * the supplied text are permitted, it is critical that the underlying string not be
727 * altered or deleted before use by the regular expression operations is complete.
728 *
729 * @param regexp The Regular Expression to be compiled.
730 * @param input The string to match. The matcher retains a shallow clone of the text.
731 * @param flags #URegexpFlag options, such as #UREGEX_CASE_INSENSITIVE.
732 * @param status Any errors are reported by setting this UErrorCode variable.
733 *
734 * @stable ICU 4.6
735 */
736 RegexMatcher(UText *regexp, UText *input,
737 uint32_t flags, UErrorCode &status);
738
739private:
740 /**
741 * Cause a compilation error if an application accidentally attempts to
742 * create a matcher with a (char16_t *) string as input rather than
743 * a UnicodeString. Avoids a dangling reference to a temporary string.
744 *
745 * To efficiently work with char16_t *strings, wrap the data in a UnicodeString
746 * using one of the aliasing constructors, such as
747 * `UnicodeString(UBool isTerminated, const char16_t *text, int32_t textLength);`
748 * or in a UText, using
749 * `utext_openUChars(UText *ut, const char16_t *text, int64_t textLength, UErrorCode *status);`
750 */
751 RegexMatcher(const UnicodeString ®exp, const char16_t *input,
752 uint32_t flags, UErrorCode &status);
753public:
754
755
756 /**
757 * Destructor.
758 *
759 * @stable ICU 2.4
760 */
761 virtual ~RegexMatcher();
762
763
764 /**
765 * Attempts to match the entire input region against the pattern.
766 * @param status A reference to a UErrorCode to receive any errors.
767 * @return TRUE if there is a match
768 * @stable ICU 2.4
769 */
770 virtual UBool matches(UErrorCode &status);
771
772
773 /**
774 * Resets the matcher, then attempts to match the input beginning
775 * at the specified startIndex, and extending to the end of the input.
776 * The input region is reset to include the entire input string.
777 * A successful match must extend to the end of the input.
778 * @param startIndex The input string (native) index at which to begin matching.
779 * @param status A reference to a UErrorCode to receive any errors.
780 * @return TRUE if there is a match
781 * @stable ICU 2.8
782 */
783 virtual UBool matches(int64_t startIndex, UErrorCode &status);
784
785
786 /**
787 * Attempts to match the input string, starting from the beginning of the region,
788 * against the pattern. Like the matches() method, this function
789 * always starts at the beginning of the input region;
790 * unlike that function, it does not require that the entire region be matched.
791 *
792 * If the match succeeds then more information can be obtained via the start(),
793 * end(), and group() functions.
794 *
795 * @param status A reference to a UErrorCode to receive any errors.
796 * @return TRUE if there is a match at the start of the input string.
797 * @stable ICU 2.4
798 */
799 virtual UBool lookingAt(UErrorCode &status);
800
801
802 /**
803 * Attempts to match the input string, starting from the specified index, against the pattern.
804 * The match may be of any length, and is not required to extend to the end
805 * of the input string. Contrast with match().
806 *
807 * If the match succeeds then more information can be obtained via the start(),
808 * end(), and group() functions.
809 *
810 * @param startIndex The input string (native) index at which to begin matching.
811 * @param status A reference to a UErrorCode to receive any errors.
812 * @return TRUE if there is a match.
813 * @stable ICU 2.8
814 */
815 virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);
816
817
818 /**
819 * Find the next pattern match in the input string.
820 * The find begins searching the input at the location following the end of
821 * the previous match, or at the start of the string if there is no previous match.
822 * If a match is found, `start()`, `end()` and `group()`
823 * will provide more information regarding the match.
824 * Note that if the input string is changed by the application,
825 * use find(startPos, status) instead of find(), because the saved starting
826 * position may not be valid with the altered input string.
827 * @return TRUE if a match is found.
828 * @stable ICU 2.4
829 */
830 virtual UBool find();
831
832
833 /**
834 * Find the next pattern match in the input string.
835 * The find begins searching the input at the location following the end of
836 * the previous match, or at the start of the string if there is no previous match.
837 * If a match is found, `start()`, `end()` and `group()`
838 * will provide more information regarding the match.
839 *
840 * Note that if the input string is changed by the application,
841 * use find(startPos, status) instead of find(), because the saved starting
842 * position may not be valid with the altered input string.
843 * @param status A reference to a UErrorCode to receive any errors.
844 * @return TRUE if a match is found.
845 * @stable ICU 55
846 */
847 virtual UBool find(UErrorCode &status);
848
849 /**
850 * Resets this RegexMatcher and then attempts to find the next substring of the
851 * input string that matches the pattern, starting at the specified index.
852 *
853 * @param start The (native) index in the input string to begin the search.
854 * @param status A reference to a UErrorCode to receive any errors.
855 * @return TRUE if a match is found.
856 * @stable ICU 2.4
857 */
858 virtual UBool find(int64_t start, UErrorCode &status);
859
860
861 /**
862 * Returns a string containing the text matched by the previous match.
863 * If the pattern can match an empty string, an empty string may be returned.
864 * @param status A reference to a UErrorCode to receive any errors.
865 * Possible errors are U_REGEX_INVALID_STATE if no match
866 * has been attempted or the last match failed.
867 * @return a string containing the matched input text.
868 * @stable ICU 2.4
869 */
870 virtual UnicodeString group(UErrorCode &status) const;
871
872
873 /**
874 * Returns a string containing the text captured by the given group
875 * during the previous match operation. Group(0) is the entire match.
876 *
877 * A zero length string is returned both for capture groups that did not
878 * participate in the match and for actual zero length matches.
879 * To distinguish between these two cases use the function start(),
880 * which returns -1 for non-participating groups.
881 *
882 * @param groupNum the capture group number
883 * @param status A reference to a UErrorCode to receive any errors.
884 * Possible errors are U_REGEX_INVALID_STATE if no match
885 * has been attempted or the last match failed and
886 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
887 * @return the captured text
888 * @stable ICU 2.4
889 */
890 virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;
891
892 /**
893 * Returns the number of capturing groups in this matcher's pattern.
894 * @return the number of capture groups
895 * @stable ICU 2.4
896 */
897 virtual int32_t groupCount() const;
898
899
900 /**
901 * Returns a shallow clone of the entire live input string with the UText current native index
902 * set to the beginning of the requested group.
903 *
904 * @param dest The UText into which the input should be cloned, or NULL to create a new UText
905 * @param group_len A reference to receive the length of the desired capture group
906 * @param status A reference to a UErrorCode to receive any errors.
907 * Possible errors are U_REGEX_INVALID_STATE if no match
908 * has been attempted or the last match failed and
909 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
910 * @return dest if non-NULL, a shallow copy of the input text otherwise
911 *
912 * @stable ICU 4.6
913 */
914 virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const;
915
916 /**
917 * Returns a shallow clone of the entire live input string with the UText current native index
918 * set to the beginning of the requested group.
919 *
920 * A group length of zero is returned both for capture groups that did not
921 * participate in the match and for actual zero length matches.
922 * To distinguish between these two cases use the function start(),
923 * which returns -1 for non-participating groups.
924 *
925 * @param groupNum The capture group number.
926 * @param dest The UText into which the input should be cloned, or NULL to create a new UText.
927 * @param group_len A reference to receive the length of the desired capture group
928 * @param status A reference to a UErrorCode to receive any errors.
929 * Possible errors are U_REGEX_INVALID_STATE if no match
930 * has been attempted or the last match failed and
931 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
932 * @return dest if non-NULL, a shallow copy of the input text otherwise
933 *
934 * @stable ICU 4.6
935 */
936 virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;
937
938 /**
939 * Returns the index in the input string of the start of the text matched
940 * during the previous match operation.
941 * @param status a reference to a UErrorCode to receive any errors.
942 * @return The (native) position in the input string of the start of the last match.
943 * @stable ICU 2.4
944 */
945 virtual int32_t start(UErrorCode &status) const;
946
947 /**
948 * Returns the index in the input string of the start of the text matched
949 * during the previous match operation.
950 * @param status a reference to a UErrorCode to receive any errors.
951 * @return The (native) position in the input string of the start of the last match.
952 * @stable ICU 4.6
953 */
954 virtual int64_t start64(UErrorCode &status) const;
955
956
957 /**
958 * Returns the index in the input string of the start of the text matched by the
959 * specified capture group during the previous match operation. Return -1 if
960 * the capture group exists in the pattern, but was not part of the last match.
961 *
962 * @param group the capture group number
963 * @param status A reference to a UErrorCode to receive any errors. Possible
964 * errors are U_REGEX_INVALID_STATE if no match has been
965 * attempted or the last match failed, and
966 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
967 * @return the (native) start position of substring matched by the specified group.
968 * @stable ICU 2.4
969 */
970 virtual int32_t start(int32_t group, UErrorCode &status) const;
971
972 /**
973 * Returns the index in the input string of the start of the text matched by the
974 * specified capture group during the previous match operation. Return -1 if
975 * the capture group exists in the pattern, but was not part of the last match.
976 *
977 * @param group the capture group number.
978 * @param status A reference to a UErrorCode to receive any errors. Possible
979 * errors are U_REGEX_INVALID_STATE if no match has been
980 * attempted or the last match failed, and
981 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number.
982 * @return the (native) start position of substring matched by the specified group.
983 * @stable ICU 4.6
984 */
985 virtual int64_t start64(int32_t group, UErrorCode &status) const;
986
987 /**
988 * Returns the index in the input string of the first character following the
989 * text matched during the previous match operation.
990 *
991 * @param status A reference to a UErrorCode to receive any errors. Possible
992 * errors are U_REGEX_INVALID_STATE if no match has been
993 * attempted or the last match failed.
994 * @return the index of the last character matched, plus one.
995 * The index value returned is a native index, corresponding to
996 * code units for the underlying encoding type, for example,
997 * a byte index for UTF-8.
998 * @stable ICU 2.4
999 */
1000 virtual int32_t end(UErrorCode &status) const;
1001
1002 /**
1003 * Returns the index in the input string of the first character following the
1004 * text matched during the previous match operation.
1005 *
1006 * @param status A reference to a UErrorCode to receive any errors. Possible
1007 * errors are U_REGEX_INVALID_STATE if no match has been
1008 * attempted or the last match failed.
1009 * @return the index of the last character matched, plus one.
1010 * The index value returned is a native index, corresponding to
1011 * code units for the underlying encoding type, for example,
1012 * a byte index for UTF-8.
1013 * @stable ICU 4.6
1014 */
1015 virtual int64_t end64(UErrorCode &status) const;
1016
1017
1018 /**
1019 * Returns the index in the input string of the character following the
1020 * text matched by the specified capture group during the previous match operation.
1021 *
1022 * @param group the capture group number
1023 * @param status A reference to a UErrorCode to receive any errors. Possible
1024 * errors are U_REGEX_INVALID_STATE if no match has been
1025 * attempted or the last match failed and
1026 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1027 * @return the index of the first character following the text
1028 * captured by the specified group during the previous match operation.
1029 * Return -1 if the capture group exists in the pattern but was not part of the match.
1030 * The index value returned is a native index, corresponding to
1031 * code units for the underlying encoding type, for example,
1032 * a byte index for UTF8.
1033 * @stable ICU 2.4
1034 */
1035 virtual int32_t end(int32_t group, UErrorCode &status) const;
1036
1037 /**
1038 * Returns the index in the input string of the character following the
1039 * text matched by the specified capture group during the previous match operation.
1040 *
1041 * @param group the capture group number
1042 * @param status A reference to a UErrorCode to receive any errors. Possible
1043 * errors are U_REGEX_INVALID_STATE if no match has been
1044 * attempted or the last match failed and
1045 * U_INDEX_OUTOFBOUNDS_ERROR for a bad capture group number
1046 * @return the index of the first character following the text
1047 * captured by the specified group during the previous match operation.
1048 * Return -1 if the capture group exists in the pattern but was not part of the match.
1049 * The index value returned is a native index, corresponding to
1050 * code units for the underlying encoding type, for example,
1051 * a byte index for UTF8.
1052 * @stable ICU 4.6
1053 */
1054 virtual int64_t end64(int32_t group, UErrorCode &status) const;
1055
1056 /**
1057 * Resets this matcher. The effect is to remove any memory of previous matches,
1058 * and to cause subsequent find() operations to begin at the beginning of
1059 * the input string.
1060 *
1061 * @return this RegexMatcher.
1062 * @stable ICU 2.4
1063 */
1064 virtual RegexMatcher &reset();
1065
1066
1067 /**
1068 * Resets this matcher, and set the current input position.
1069 * The effect is to remove any memory of previous matches,
1070 * and to cause subsequent find() operations to begin at
1071 * the specified (native) position in the input string.
1072 *
1073 * The matcher's region is reset to its default, which is the entire
1074 * input string.
1075 *
1076 * An alternative to this function is to set a match region
1077 * beginning at the desired index.
1078 *
1079 * @return this RegexMatcher.
1080 * @stable ICU 2.8
1081 */
1082 virtual RegexMatcher &reset(int64_t index, UErrorCode &status);
1083
1084
1085 /**
1086 * Resets this matcher with a new input string. This allows instances of RegexMatcher
1087 * to be reused, which is more efficient than creating a new RegexMatcher for
1088 * each input string to be processed.
1089 * @param input The new string on which subsequent pattern matches will operate.
1090 * The matcher retains a reference to the callers string, and operates
1091 * directly on that. Ownership of the string remains with the caller.
1092 * Because no copy of the string is made, it is essential that the
1093 * caller not delete the string until after regexp operations on it
1094 * are done.
1095 * Note that while a reset on the matcher with an input string that is then
1096 * modified across/during matcher operations may be supported currently for UnicodeString,
1097 * this was not originally intended behavior, and support for this is not guaranteed
1098 * in upcoming versions of ICU.
1099 * @return this RegexMatcher.
1100 * @stable ICU 2.4
1101 */
1102 virtual RegexMatcher &reset(const UnicodeString &input);
1103
1104
1105 /**
1106 * Resets this matcher with a new input string. This allows instances of RegexMatcher
1107 * to be reused, which is more efficient than creating a new RegexMatcher for
1108 * each input string to be processed.
1109 * @param input The new string on which subsequent pattern matches will operate.
1110 * The matcher makes a shallow clone of the given text; ownership of the
1111 * original string remains with the caller. Because no deep copy of the
1112 * text is made, it is essential that the caller not modify the string
1113 * until after regexp operations on it are done.
1114 * @return this RegexMatcher.
1115 *
1116 * @stable ICU 4.6
1117 */
1118 virtual RegexMatcher &reset(UText *input);
1119
1120
1121 /**
1122 * Set the subject text string upon which the regular expression is looking for matches
1123 * without changing any other aspect of the matching state.
1124 * The new and previous text strings must have the same content.
1125 *
1126 * This function is intended for use in environments where ICU is operating on
1127 * strings that may move around in memory. It provides a mechanism for notifying
1128 * ICU that the string has been relocated, and providing a new UText to access the
1129 * string in its new position.
1130 *
1131 * Note that the regular expression implementation never copies the underlying text
1132 * of a string being matched, but always operates directly on the original text
1133 * provided by the user. Refreshing simply drops the references to the old text
1134 * and replaces them with references to the new.
1135 *
1136 * Caution: this function is normally used only by very specialized,
1137 * system-level code. One example use case is with garbage collection that moves
1138 * the text in memory.
1139 *
1140 * @param input The new (moved) text string.
1141 * @param status Receives errors detected by this function.
1142 *
1143 * @stable ICU 4.8
1144 */
1145 virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);
1146
1147private:
1148 /**
1149 * Cause a compilation error if an application accidentally attempts to
1150 * reset a matcher with a (char16_t *) string as input rather than
1151 * a UnicodeString. Avoids a dangling reference to a temporary string.
1152 *
1153 * To efficiently work with char16_t *strings, wrap the data in a UnicodeString
1154 * using one of the aliasing constructors, such as
1155 * `UnicodeString(UBool isTerminated, const char16_t *text, int32_t textLength);`
1156 * or in a UText, using
1157 * `utext_openUChars(UText *ut, const char16_t *text, int64_t textLength, UErrorCode *status);`
1158 *
1159 */
1160 RegexMatcher &reset(const char16_t *input);
1161public:
1162
1163 /**
1164 * Returns the input string being matched. Ownership of the string belongs to
1165 * the matcher; it should not be altered or deleted. This method will work even if the input
1166 * was originally supplied as a UText.
1167 * @return the input string
1168 * @stable ICU 2.4
1169 */
1170 virtual const UnicodeString &input() const;
1171
1172 /**
1173 * Returns the input string being matched. This is the live input text; it should not be
1174 * altered or deleted. This method will work even if the input was originally supplied as
1175 * a UnicodeString.
1176 * @return the input text
1177 *
1178 * @stable ICU 4.6
1179 */
1180 virtual UText *inputText() const;
1181
1182 /**
1183 * Returns the input string being matched, either by copying it into the provided
1184 * UText parameter or by returning a shallow clone of the live input. Note that copying
1185 * the entire input may cause significant performance and memory issues.
1186 * @param dest The UText into which the input should be copied, or NULL to create a new UText
1187 * @param status error code
1188 * @return dest if non-NULL, a shallow copy of the input text otherwise
1189 *
1190 * @stable ICU 4.6
1191 */
1192 virtual UText *getInput(UText *dest, UErrorCode &status) const;
1193
1194
1195 /** Sets the limits of this matcher's region.
1196 * The region is the part of the input string that will be searched to find a match.
1197 * Invoking this method resets the matcher, and then sets the region to start
1198 * at the index specified by the start parameter and end at the index specified
1199 * by the end parameter.
1200 *