ICU 59.1  59.1
regex.h
Go to the documentation of this file.
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 
47 #include "unicode/utypes.h"
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 
60 struct UHashtable;
61 
63 
64 struct Regex8BitSet;
65 class RegexCImpl;
66 class RegexMatcher;
67 class RegexPattern;
68 struct REStackFrame;
69 class RuleBasedBreakIterator;
70 class UnicodeSet;
71 class UVector;
72 class UVector32;
73 class UVector64;
74 
75 
87 class U_I18N_API RegexPattern U_FINAL : public UObject {
88 public:
89 
97  RegexPattern();
98 
105  RegexPattern(const RegexPattern &source);
106 
112  virtual ~RegexPattern();
113 
122  UBool operator==(const RegexPattern& that) const;
123 
132  inline UBool operator!=(const RegexPattern& that) const {return ! operator ==(that);}
133 
139  RegexPattern &operator =(const RegexPattern &source);
140 
148  virtual RegexPattern *clone() const;
149 
150 
175  static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
176  UParseError &pe,
177  UErrorCode &status);
178 
205  static RegexPattern * U_EXPORT2 compile( UText *regex,
206  UParseError &pe,
207  UErrorCode &status);
208 
233  static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
234  uint32_t flags,
235  UParseError &pe,
236  UErrorCode &status);
237 
264  static RegexPattern * U_EXPORT2 compile( UText *regex,
265  uint32_t flags,
266  UParseError &pe,
267  UErrorCode &status);
268 
291  static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
292  uint32_t flags,
293  UErrorCode &status);
294 
319  static RegexPattern * U_EXPORT2 compile( UText *regex,
320  uint32_t flags,
321  UErrorCode &status);
322 
328  virtual uint32_t flags() const;
329 
347  virtual RegexMatcher *matcher(const UnicodeString &input,
348  UErrorCode &status) const;
349 
350 private:
363  RegexMatcher *matcher(const char16_t *input,
364  UErrorCode &status) const;
365 public:
366 
367 
379  virtual RegexMatcher *matcher(UErrorCode &status) const;
380 
381 
396  static UBool U_EXPORT2 matches(const UnicodeString &regex,
397  const UnicodeString &input,
398  UParseError &pe,
399  UErrorCode &status);
400 
415  static UBool U_EXPORT2 matches(UText *regex,
416  UText *input,
417  UParseError &pe,
418  UErrorCode &status);
419 
428  virtual UnicodeString pattern() const;
429 
430 
441  virtual UText *patternText(UErrorCode &status) const;
442 
443 
457  virtual int32_t groupNumberFromName(const UnicodeString &groupName, UErrorCode &status) const;
458 
459 
476  virtual int32_t groupNumberFromName(const char *groupName, int32_t nameLength, UErrorCode &status) const;
477 
478 
517  virtual int32_t split(const UnicodeString &input,
518  UnicodeString dest[],
519  int32_t destCapacity,
520  UErrorCode &status) const;
521 
522 
561  virtual int32_t split(UText *input,
562  UText *dest[],
563  int32_t destCapacity,
564  UErrorCode &status) const;
565 
566 
572  virtual UClassID getDynamicClassID() const;
573 
579  static UClassID U_EXPORT2 getStaticClassID();
580 
581 private:
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 
649  void dumpPattern() const;
650 #endif /* U_HIDE_INTERNAL_API */
651 };
652 
653 
654 
664 class U_I18N_API RegexMatcher U_FINAL : public UObject {
665 public:
666 
681  RegexMatcher(const UnicodeString &regexp, uint32_t flags, UErrorCode &status);
682 
698  RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);
699 
721  RegexMatcher(const UnicodeString &regexp, const UnicodeString &input,
722  uint32_t flags, UErrorCode &status);
723 
745  RegexMatcher(UText *regexp, UText *input,
746  uint32_t flags, UErrorCode &status);
747 
748 private:
761  RegexMatcher(const UnicodeString &regexp, const char16_t *input,
762  uint32_t flags, UErrorCode &status);
763 public:
764 
765 
771  virtual ~RegexMatcher();
772 
773 
780  virtual UBool matches(UErrorCode &status);
781 
782 
793  virtual UBool matches(int64_t startIndex, UErrorCode &status);
794 
795 
809  virtual UBool lookingAt(UErrorCode &status);
810 
811 
825  virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);
826 
827 
840  virtual UBool find();
841 
842 
856  virtual UBool find(UErrorCode &status);
857 
867  virtual UBool find(int64_t start, UErrorCode &status);
868 
869 
879  virtual UnicodeString group(UErrorCode &status) const;
880 
881 
899  virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;
900 
906  virtual int32_t groupCount() const;
907 
908 
923  virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const;
924 
945  virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;
946 
954  virtual int32_t start(UErrorCode &status) const;
955 
963  virtual int64_t start64(UErrorCode &status) const;
964 
965 
979  virtual int32_t start(int32_t group, UErrorCode &status) const;
980 
994  virtual int64_t start64(int32_t group, UErrorCode &status) const;
995 
1009  virtual int32_t end(UErrorCode &status) const;
1010 
1024  virtual int64_t end64(UErrorCode &status) const;
1025 
1026 
1044  virtual int32_t end(int32_t group, UErrorCode &status) const;
1045 
1063  virtual int64_t end64(int32_t group, UErrorCode &status) const;
1064 
1073  virtual RegexMatcher &reset();
1074 
1075 
1091  virtual RegexMatcher &reset(int64_t index, UErrorCode &status);
1092 
1093 
1111  virtual RegexMatcher &reset(const UnicodeString &input);
1112 
1113 
1127  virtual RegexMatcher &reset(UText *input);
1128 
1129 
1154  virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);
1155 
1156 private:
1169  RegexMatcher &reset(const char16_t *input);
1170 public:
1171 
1179  virtual const UnicodeString &input() const;
1180 
1189  virtual UText *inputText() const;
1190 
1201  virtual UText *getInput(UText *dest, UErrorCode &status) const;
1202 
1203 
1222  virtual RegexMatcher &region(int64_t start, int64_t limit, UErrorCode &status);
1223 
1235  virtual RegexMatcher &region(int64_t regionStart, int64_t regionLimit, int64_t startIndex, UErrorCode &status);
1236 
1245  virtual int32_t regionStart() const;
1246 
1255  virtual int64_t regionStart64() const;
1256 
1257 
1266  virtual int32_t regionEnd() const;
1267 
1276  virtual int64_t regionEnd64() const;
1277 
1286  virtual UBool hasTransparentBounds() const;
1287 
1306  virtual RegexMatcher &useTransparentBounds(UBool b);
1307 
1308 
1316  virtual UBool hasAnchoringBounds() const;
1317 
1318 
1331  virtual RegexMatcher &useAnchoringBounds(UBool b);
1332 
1333 
1346  virtual UBool hitEnd() const;
1347 
1357  virtual UBool requireEnd() const;
1358 
1359 
1365  virtual const RegexPattern &pattern() const;
1366 
1367 
1384  virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);
1385 
1386 
1407  virtual UText *replaceAll(UText *replacement, UText *dest, UErrorCode &status);
1408 
1409 
1430  virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status);
1431 
1432 
1457  virtual UText *replaceFirst(UText *replacement, UText *dest, UErrorCode &status);
1458 
1459 
1487  virtual RegexMatcher &appendReplacement(UnicodeString &dest,
1488  const UnicodeString &replacement, UErrorCode &status);
1489 
1490 
1518  virtual RegexMatcher &appendReplacement(UText *dest,
1519  UText *replacement, UErrorCode &status);
1520 
1521 
1532  virtual UnicodeString &appendTail(UnicodeString &dest);
1533 
1534 
1548  virtual UText *appendTail(UText *dest, UErrorCode &status);
1549 
1550 
1574  virtual int32_t split(const UnicodeString &input,
1575  UnicodeString dest[],
1576  int32_t destCapacity,
1577  UErrorCode &status);
1578 
1579 
1603  virtual int32_t split(UText *input,
1604  UText *dest[],
1605  int32_t destCapacity,
1606  UErrorCode &status);
1607 
1629  virtual void setTimeLimit(int32_t limit, UErrorCode &status);
1630 
1637  virtual int32_t getTimeLimit() const;
1638 
1660  virtual void setStackLimit(int32_t limit, UErrorCode &status);
1661 
1669  virtual int32_t getStackLimit() const;
1670 
1671 
1685  virtual void setMatchCallback(URegexMatchCallback *callback,
1686  const void *context,
1687  UErrorCode &status);
1688 
1689 
1700  virtual void getMatchCallback(URegexMatchCallback *&callback,
1701  const void *&context,
1702  UErrorCode &status);
1703 
1704 
1718  virtual void setFindProgressCallback(URegexFindProgressCallback *callback,
1719  const void *context,
1720  UErrorCode &status);
1721 
1722 
1733  virtual void getFindProgressCallback(URegexFindProgressCallback *&callback,
1734  const void *&context,
1735  UErrorCode &status);
1736 
1737 #ifndef U_HIDE_INTERNAL_API
1738 
1743  void setTrace(UBool state);
1744 #endif /* U_HIDE_INTERNAL_API */
1745 
1751  static UClassID U_EXPORT2 getStaticClassID();
1752 
1758  virtual UClassID getDynamicClassID() const;
1759 
1760 private:
1761  // Constructors and other object boilerplate are private.
1762  // Instances of RegexMatcher can not be assigned, copied, cloned, etc.
1763  RegexMatcher(); // default constructor not implemented
1764  RegexMatcher(const RegexPattern *pat);
1765  RegexMatcher(const RegexMatcher &other);
1766  RegexMatcher &operator =(const RegexMatcher &rhs);
1767  void init(UErrorCode &status); // Common initialization
1768  void init2(UText *t, UErrorCode &e); // Common initialization, part 2.
1769 
1770  friend class RegexPattern;
1771  friend class RegexCImpl;
1772 public:
1773 #ifndef U_HIDE_INTERNAL_API
1774 
1775  void resetPreserveRegion(); // Reset matcher state, but preserve any region.
1776 #endif /* U_HIDE_INTERNAL_API */
1777 private:
1778 
1779  //
1780  // MatchAt This is the internal interface to the match engine itself.
1781  // Match status comes back in matcher member variables.
1782  //
1783  void MatchAt(int64_t startIdx, UBool toEnd, UErrorCode &status);
1784  inline void backTrack(int64_t &inputIdx, int32_t &patIdx);
1785  UBool isWordBoundary(int64_t pos); // perform Perl-like \b test
1786  UBool isUWordBoundary(int64_t pos); // perform RBBI based \b test
1787  REStackFrame *resetStack();
1788  inline REStackFrame *StateSave(REStackFrame *fp, int64_t savePatIdx, UErrorCode &status);
1789  void IncrementTime(UErrorCode &status);
1790 
1791  // Call user find callback function, if set. Return TRUE if operation should be interrupted.
1792  inline UBool findProgressInterrupt(int64_t matchIndex, UErrorCode &status);
1793 
1794  int64_t appendGroup(int32_t groupNum, UText *dest, UErrorCode &status) const;
1795 
1796  UBool findUsingChunk(UErrorCode &status);
1797  void MatchChunkAt(int32_t startIdx, UBool toEnd, UErrorCode &status);
1798  UBool isChunkWordBoundary(int32_t pos);
1799 
1800  const RegexPattern *fPattern;
1801  RegexPattern *fPatternOwned; // Non-NULL if this matcher owns the pattern, and
1802  // should delete it when through.
1803 
1804  const UnicodeString *fInput; // The string being matched. Only used for input()
1805  UText *fInputText; // The text being matched. Is never NULL.
1806  UText *fAltInputText; // A shallow copy of the text being matched.
1807  // Only created if the pattern contains backreferences.
1808  int64_t fInputLength; // Full length of the input text.
1809  int32_t fFrameSize; // The size of a frame in the backtrack stack.
1810 
1811  int64_t fRegionStart; // Start of the input region, default = 0.
1812  int64_t fRegionLimit; // End of input region, default to input.length.
1813 
1814  int64_t fAnchorStart; // Region bounds for anchoring operations (^ or $).
1815  int64_t fAnchorLimit; // See useAnchoringBounds
1816 
1817  int64_t fLookStart; // Region bounds for look-ahead/behind and
1818  int64_t fLookLimit; // and other boundary tests. See
1819  // useTransparentBounds
1820 
1821  int64_t fActiveStart; // Currently active bounds for matching.
1822  int64_t fActiveLimit; // Usually is the same as region, but
1823  // is changed to fLookStart/Limit when
1824  // entering look around regions.
1825 
1826  UBool fTransparentBounds; // True if using transparent bounds.
1827  UBool fAnchoringBounds; // True if using anchoring bounds.
1828 
1829  UBool fMatch; // True if the last attempted match was successful.
1830  int64_t fMatchStart; // Position of the start of the most recent match
1831  int64_t fMatchEnd; // First position after the end of the most recent match
1832  // Zero if no previous match, even when a region
1833  // is active.
1834  int64_t fLastMatchEnd; // First position after the end of the previous match,
1835  // or -1 if there was no previous match.
1836  int64_t fAppendPosition; // First position after the end of the previous
1837  // appendReplacement(). As described by the
1838  // JavaDoc for Java Matcher, where it is called
1839  // "append position"
1840  UBool fHitEnd; // True if the last match touched the end of input.
1841  UBool fRequireEnd; // True if the last match required end-of-input
1842  // (matched $ or Z)
1843 
1844  UVector64 *fStack;
1845  REStackFrame *fFrame; // After finding a match, the last active stack frame,
1846  // which will contain the capture group results.
1847  // NOT valid while match engine is running.
1848 
1849  int64_t *fData; // Data area for use by the compiled pattern.
1850  int64_t fSmallData[8]; // Use this for data if it's enough.
1851 
1852  int32_t fTimeLimit; // Max time (in arbitrary steps) to let the
1853  // match engine run. Zero for unlimited.
1854 
1855  int32_t fTime; // Match time, accumulates while matching.
1856  int32_t fTickCounter; // Low bits counter for time. Counts down StateSaves.
1857  // Kept separately from fTime to keep as much
1858  // code as possible out of the inline
1859  // StateSave function.
1860 
1861  int32_t fStackLimit; // Maximum memory size to use for the backtrack
1862  // stack, in bytes. Zero for unlimited.
1863 
1864  URegexMatchCallback *fCallbackFn; // Pointer to match progress callback funct.
1865  // NULL if there is no callback.
1866  const void *fCallbackContext; // User Context ptr for callback function.
1867 
1868  URegexFindProgressCallback *fFindProgressCallbackFn; // Pointer to match progress callback funct.
1869  // NULL if there is no callback.
1870  const void *fFindProgressCallbackContext; // User Context ptr for callback function.
1871 
1872 
1873  UBool fInputUniStrMaybeMutable; // Set when fInputText wraps a UnicodeString that may be mutable - compatibility.
1874 
1875  UBool fTraceDebug; // Set true for debug tracing of match engine.
1876 
1877  UErrorCode fDeferredStatus; // Save error state that cannot be immediately
1878  // reported, or that permanently disables this matcher.
1879 
1880  RuleBasedBreakIterator *fWordBreakItr;
1881 };
1882 
1884 #endif // UCONFIG_NO_REGULAR_EXPRESSIONS
1885 #endif
C++ API: Unicode String.
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:93
Class RegexPattern represents a compiled regular expression.
Definition: regex.h:87
UBool URegexFindProgressCallback(const void *context, int64_t matchIndex)
Function pointer for a regular expression find callback function.
Definition: uregex.h:1573
C API: Abstract Unicode Text API.
class RegexMatcher bundles together a regular expression pattern and input text to which the expressi...
Definition: regex.h:664
UBool operator!=(const RegexPattern &that) const
Comparison operator.
Definition: regex.h:132
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:360
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
C API: Regular Expressions.
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:396
virtual UClassID getDynamicClassID() const
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
A mutable set of Unicode characters and multicharacter strings.
Definition: uniset.h:278
C++ API: Common ICU base class UObject.
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:132
UBool URegexMatchCallback(const void *context, int32_t steps)
Function pointer for a regular expression matching callback function.
Definition: uregex.h:1499
C API: Parse Error Information.
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:396
UText struct.
Definition: utext.h:1345
A subclass of BreakIterator whose behavior is specified using a list of rules.
Definition: rbbi.h:63
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:58
Basic definitions for ICU, for both C and C++ APIs.
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
int8_t UBool
The ICU boolean type.
Definition: umachine.h:236