regex.h

Go to the documentation of this file.

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
**********************************************************************
*   Copyright (C) 2002-2016, International Business Machines
*   Corporation and others.  All Rights Reserved.
**********************************************************************
*   file name:  regex.h
*   encoding:   UTF-8
*   indentation:4
*
*   created on: 2002oct22
*   created by: Andy Heninger
*
*   ICU Regular Expressions, API for C++
*/

#ifndef REGEX_H
#define REGEX_H

//#define REGEX_DEBUG

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

#if !UCONFIG_NO_REGULAR_EXPRESSIONS

#include "unicode/uobject.h"
#include "unicode/unistr.h"
#include "unicode/utext.h"
#include "unicode/parseerr.h"

#include "unicode/uregex.h"

// Forward Declarations

struct UHashtable;

U_NAMESPACE_BEGIN

struct Regex8BitSet;
class  RegexCImpl;
class  RegexMatcher;
class  RegexPattern;
struct REStackFrame;
class  BreakIterator;
class  UnicodeSet;
class  UVector;
class  UVector32;
class  UVector64;


class U_I18N_API RegexPattern final : public UObject {
public:

    RegexPattern();

    RegexPattern(const RegexPattern &source);

    virtual ~RegexPattern();

    bool            operator==(const RegexPattern& that) const;

    inline bool     operator!=(const RegexPattern& that) const {return ! operator ==(that);}

    RegexPattern  &operator =(const RegexPattern &source);

    virtual RegexPattern  *clone() const;


    static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
        UParseError          &pe,
        UErrorCode           &status);

    static RegexPattern * U_EXPORT2 compile( UText *regex,
        UParseError          &pe,
        UErrorCode           &status);

    static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
        uint32_t             flags,
        UParseError          &pe,
        UErrorCode           &status);

    static RegexPattern * U_EXPORT2 compile( UText *regex,
        uint32_t             flags,
        UParseError          &pe,
        UErrorCode           &status);

    static RegexPattern * U_EXPORT2 compile( const UnicodeString &regex,
        uint32_t             flags,
        UErrorCode           &status);

    static RegexPattern * U_EXPORT2 compile( UText *regex,
        uint32_t             flags,
        UErrorCode           &status);

    virtual uint32_t flags() const;

    virtual RegexMatcher *matcher(const UnicodeString &input,
        UErrorCode          &status) const;
        
private:
    RegexMatcher *matcher(const char16_t *input,
        UErrorCode          &status) const = delete;
public:


    virtual RegexMatcher *matcher(UErrorCode  &status) const;


    static UBool U_EXPORT2 matches(const UnicodeString   &regex,
        const UnicodeString   &input,
              UParseError     &pe,
              UErrorCode      &status);

    static UBool U_EXPORT2 matches(UText *regex,
        UText           *input,
        UParseError     &pe,
        UErrorCode      &status);

    virtual UnicodeString pattern() const;
    
    
    virtual UText *patternText(UErrorCode      &status) const;


    virtual int32_t groupNumberFromName(const UnicodeString &groupName, UErrorCode &status) const;


    virtual int32_t groupNumberFromName(const char *groupName, int32_t nameLength, UErrorCode &status) const;


    virtual int32_t  split(const UnicodeString &input,
        UnicodeString    dest[],
        int32_t          destCapacity,
        UErrorCode       &status) const;


    virtual int32_t  split(UText *input,
        UText            *dest[],
        int32_t          destCapacity,
        UErrorCode       &status) const;


    virtual UClassID getDynamicClassID() const override;

    static UClassID U_EXPORT2 getStaticClassID();

private:
    //
    //  Implementation Data
    //
    UText          *fPattern;      // The original pattern string.
    UnicodeString  *fPatternString; // The original pattern UncodeString if relevant
    uint32_t        fFlags;        // The flags used when compiling the pattern.
                                   //
    UVector64       *fCompiledPat; // The compiled pattern p-code.
    UnicodeString   fLiteralText;  // Any literal string data from the pattern,
                                   //   after un-escaping, for use during the match.

    UVector         *fSets;        // Any UnicodeSets referenced from the pattern.
    Regex8BitSet    *fSets8;       //      (and fast sets for latin-1 range.)


    UErrorCode      fDeferredStatus; // status if some prior error has left this
                                   //  RegexPattern in an unusable state.

    int32_t         fMinMatchLen;  // Minimum Match Length.  All matches will have length
                                   //   >= this value.  For some patterns, this calculated
                                   //   value may be less than the true shortest
                                   //   possible match.
    
    int32_t         fFrameSize;    // Size of a state stack frame in the
                                   //   execution engine.

    int32_t         fDataSize;     // The size of the data needed by the pattern that
                                   //   does not go on the state stack, but has just
                                   //   a single copy per matcher.

    UVector32       *fGroupMap;    // Map from capture group number to position of
                                   //   the group's variables in the matcher stack frame.

    int32_t         fStartType;    // Info on how a match must start.
    int32_t         fInitialStringIdx;     //
    int32_t         fInitialStringLen;
    UnicodeSet     *fInitialChars;
    UChar32         fInitialChar;
    Regex8BitSet   *fInitialChars8;
    UBool           fNeedsAltInput;

    UHashtable     *fNamedCaptureMap;  // Map from capture group names to numbers.

    friend class RegexCompile;
    friend class RegexMatcher;
    friend class RegexCImpl;

    //
    //  Implementation Methods
    //
    void        init();                 // Common initialization, for use by constructors.
    bool        initNamedCaptureMap();  // Lazy init for fNamedCaptureMap.
    void        zap();                  // Common cleanup

    void        dumpOp(int32_t index) const;

  public:
#ifndef U_HIDE_INTERNAL_API

    void        dumpPattern() const;
#endif  /* U_HIDE_INTERNAL_API */
};



class U_I18N_API RegexMatcher final : public UObject {
public:

    RegexMatcher(const UnicodeString &regexp, uint32_t flags, UErrorCode &status);

    RegexMatcher(UText *regexp, uint32_t flags, UErrorCode &status);

    RegexMatcher(const UnicodeString &regexp, const UnicodeString &input,
        uint32_t flags, UErrorCode &status);

    RegexMatcher(UText *regexp, UText *input,
        uint32_t flags, UErrorCode &status);

private:
    RegexMatcher(const UnicodeString &regexp, const char16_t *input,
        uint32_t flags, UErrorCode &status) = delete;
public:


    virtual ~RegexMatcher();


    virtual UBool matches(UErrorCode &status);


    virtual UBool matches(int64_t startIndex, UErrorCode &status);


    virtual UBool lookingAt(UErrorCode &status);


    virtual UBool lookingAt(int64_t startIndex, UErrorCode &status);


    virtual UBool find();


    virtual UBool find(UErrorCode &status);

    virtual UBool find(int64_t start, UErrorCode &status);


    virtual UnicodeString group(UErrorCode &status) const;


    virtual UnicodeString group(int32_t groupNum, UErrorCode &status) const;

    virtual int32_t groupCount() const;


    virtual UText *group(UText *dest, int64_t &group_len, UErrorCode &status) const; 

    virtual UText *group(int32_t groupNum, UText *dest, int64_t &group_len, UErrorCode &status) const;

    virtual int32_t start(UErrorCode &status) const;

    virtual int64_t start64(UErrorCode &status) const;


    virtual int32_t start(int32_t group, UErrorCode &status) const;

    virtual int64_t start64(int32_t group, UErrorCode &status) const;

    virtual int32_t end(UErrorCode &status) const;

    virtual int64_t end64(UErrorCode &status) const;


    virtual int32_t end(int32_t group, UErrorCode &status) const;

    virtual int64_t end64(int32_t group, UErrorCode &status) const;

    virtual RegexMatcher &reset();


    virtual RegexMatcher &reset(int64_t index, UErrorCode &status);


    virtual RegexMatcher &reset(const UnicodeString &input);


    virtual RegexMatcher &reset(UText *input);


    virtual RegexMatcher &refreshInputText(UText *input, UErrorCode &status);

private:
    RegexMatcher &reset(const char16_t *input) = delete;
public:

    virtual const UnicodeString &input() const;
    
    virtual UText *inputText() const;
    
    virtual UText *getInput(UText *dest, UErrorCode &status) const;
    

     virtual RegexMatcher &region(int64_t start, int64_t limit, UErrorCode &status);

     virtual RegexMatcher &region(int64_t regionStart, int64_t regionLimit, int64_t startIndex, UErrorCode &status);

     virtual int32_t regionStart() const;

     virtual int64_t regionStart64() const;


      virtual int32_t regionEnd() const;

      virtual int64_t regionEnd64() const;

      virtual UBool hasTransparentBounds() const;

      virtual RegexMatcher &useTransparentBounds(UBool b);

     
      virtual UBool hasAnchoringBounds() const;


      virtual RegexMatcher &useAnchoringBounds(UBool b);


      virtual UBool hitEnd() const;

      virtual UBool requireEnd() const;


    virtual const RegexPattern &pattern() const;


    virtual UnicodeString replaceAll(const UnicodeString &replacement, UErrorCode &status);


    virtual UText *replaceAll(UText *replacement, UText *dest, UErrorCode &status);
    

    virtual UnicodeString replaceFirst(const UnicodeString &replacement, UErrorCode &status);
    

    virtual UText *replaceFirst(UText *replacement, UText *dest, UErrorCode &status);
    
    
    virtual RegexMatcher &appendReplacement(UnicodeString &dest,
        const UnicodeString &replacement, UErrorCode &status);
    
    
    virtual RegexMatcher &appendReplacement(UText *dest,
        UText *replacement, UErrorCode &status);


    virtual UnicodeString &appendTail(UnicodeString &dest);


    virtual UText *appendTail(UText *dest, UErrorCode &status);


    virtual int32_t  split(const UnicodeString &input,
        UnicodeString    dest[],
        int32_t          destCapacity,
        UErrorCode       &status);


    virtual int32_t  split(UText *input,
        UText           *dest[],
        int32_t          destCapacity,
        UErrorCode       &status);
    
    virtual void setTimeLimit(int32_t limit, UErrorCode &status);

    virtual int32_t getTimeLimit() const;

    virtual void setStackLimit(int32_t  limit, UErrorCode &status);
    
    virtual int32_t  getStackLimit() const;


    virtual void setMatchCallback(URegexMatchCallback     *callback,
                                  const void              *context,
                                  UErrorCode              &status);


    virtual void getMatchCallback(URegexMatchCallback     *&callback,
                                  const void              *&context,
                                  UErrorCode              &status);


    virtual void setFindProgressCallback(URegexFindProgressCallback      *callback,
                                              const void                              *context,
                                              UErrorCode                              &status);


    virtual void getFindProgressCallback(URegexFindProgressCallback      *&callback,
                                              const void                      *&context,
                                              UErrorCode                      &status);

#ifndef U_HIDE_INTERNAL_API

    void setTrace(UBool state);
#endif  /* U_HIDE_INTERNAL_API */

    static UClassID U_EXPORT2 getStaticClassID();

    virtual UClassID getDynamicClassID() const override;

private:
    // Constructors and other object boilerplate are private.
    // Instances of RegexMatcher can not be assigned, copied, cloned, etc.
    RegexMatcher() = delete;                  // default constructor not implemented
    RegexMatcher(const RegexPattern *pat);
    RegexMatcher(const RegexMatcher &other) = delete;
    RegexMatcher &operator =(const RegexMatcher &rhs) = delete;
    void init(UErrorCode &status);                      // Common initialization
    void init2(UText *t, UErrorCode &e);  // Common initialization, part 2.

    friend class RegexPattern;
    friend class RegexCImpl;
public:
#ifndef U_HIDE_INTERNAL_API

    void resetPreserveRegion();  // Reset matcher state, but preserve any region.
#endif  /* U_HIDE_INTERNAL_API */
private:

    //
    //  MatchAt   This is the internal interface to the match engine itself.
    //            Match status comes back in matcher member variables.
    //
    void                 MatchAt(int64_t startIdx, UBool toEnd, UErrorCode &status);
    inline void          backTrack(int64_t &inputIdx, int32_t &patIdx);
    UBool                isWordBoundary(int64_t pos);         // perform Perl-like  \b test
    UBool                isUWordBoundary(int64_t pos, UErrorCode &status);   // perform RBBI based \b test
    // Find a grapheme cluster boundary using a break iterator. For handling \X in regexes.
    int64_t              followingGCBoundary(int64_t pos, UErrorCode &status);
    REStackFrame        *resetStack();
    inline REStackFrame *StateSave(REStackFrame *fp, int64_t savePatIdx, UErrorCode &status);
    void                 IncrementTime(UErrorCode &status);

    // Call user find callback function, if set. Return true if operation should be interrupted.
    inline UBool         findProgressInterrupt(int64_t matchIndex, UErrorCode &status);
    
    int64_t              appendGroup(int32_t groupNum, UText *dest, UErrorCode &status) const;
    
    UBool                findUsingChunk(UErrorCode &status);
    void                 MatchChunkAt(int32_t startIdx, UBool toEnd, UErrorCode &status);
    UBool                isChunkWordBoundary(int32_t pos);

    const RegexPattern  *fPattern;
    RegexPattern        *fPatternOwned;    // Non-nullptr if this matcher owns the pattern, and
                                           //   should delete it when through.

    const UnicodeString *fInput;           // The string being matched. Only used for input()
    UText               *fInputText;       // The text being matched. Is never nullptr.
    UText               *fAltInputText;    // A shallow copy of the text being matched.
                                           //   Only created if the pattern contains backreferences.
    int64_t              fInputLength;     // Full length of the input text.
    int32_t              fFrameSize;       // The size of a frame in the backtrack stack.
    
    int64_t              fRegionStart;     // Start of the input region, default = 0.
    int64_t              fRegionLimit;     // End of input region, default to input.length.
    
    int64_t              fAnchorStart;     // Region bounds for anchoring operations (^ or $).
    int64_t              fAnchorLimit;     //   See useAnchoringBounds
    
    int64_t              fLookStart;       // Region bounds for look-ahead/behind and
    int64_t              fLookLimit;       //   and other boundary tests.  See
                                           //   useTransparentBounds

    int64_t              fActiveStart;     // Currently active bounds for matching.
    int64_t              fActiveLimit;     //   Usually is the same as region, but
                                           //   is changed to fLookStart/Limit when
                                           //   entering look around regions.

    UBool                fTransparentBounds;  // True if using transparent bounds.
    UBool                fAnchoringBounds; // True if using anchoring bounds.

    UBool                fMatch;           // True if the last attempted match was successful.
    int64_t              fMatchStart;      // Position of the start of the most recent match
    int64_t              fMatchEnd;        // First position after the end of the most recent match
                                           //   Zero if no previous match, even when a region
                                           //   is active.
    int64_t              fLastMatchEnd;    // First position after the end of the previous match,
                                           //   or -1 if there was no previous match.
    int64_t              fAppendPosition;  // First position after the end of the previous
                                           //   appendReplacement().  As described by the
                                           //   JavaDoc for Java Matcher, where it is called 
                                           //   "append position"
    UBool                fHitEnd;          // True if the last match touched the end of input.
    UBool                fRequireEnd;      // True if the last match required end-of-input
                                           //    (matched $ or Z)

    UVector64           *fStack;
    REStackFrame        *fFrame;           // After finding a match, the last active stack frame,
                                           //   which will contain the capture group results.
                                           //   NOT valid while match engine is running.

    int64_t             *fData;            // Data area for use by the compiled pattern.
    int64_t             fSmallData[8];     //   Use this for data if it's enough.

    int32_t             fTimeLimit;        // Max time (in arbitrary steps) to let the
                                           //   match engine run.  Zero for unlimited.
    
    int32_t             fTime;             // Match time, accumulates while matching.
    int32_t             fTickCounter;      // Low bits counter for time.  Counts down StateSaves.
                                           //   Kept separately from fTime to keep as much
                                           //   code as possible out of the inline
                                           //   StateSave function.

    int32_t             fStackLimit;       // Maximum memory size to use for the backtrack
                                           //   stack, in bytes.  Zero for unlimited.

    URegexMatchCallback *fCallbackFn;       // Pointer to match progress callback funct.
                                           //   nullptr if there is no callback.
    const void         *fCallbackContext;  // User Context ptr for callback function.

    URegexFindProgressCallback  *fFindProgressCallbackFn;  // Pointer to match progress callback funct.
                                                           //   nullptr if there is no callback.
    const void         *fFindProgressCallbackContext;      // User Context ptr for callback function.


    UBool               fInputUniStrMaybeMutable;  // Set when fInputText wraps a UnicodeString that may be mutable - compatibility.

    UBool               fTraceDebug;       // Set true for debug tracing of match engine.

    UErrorCode          fDeferredStatus;   // Save error state that cannot be immediately
                                           //   reported, or that permanently disables this matcher.

    BreakIterator       *fWordBreakItr;
    BreakIterator       *fGCBreakItr;
};

U_NAMESPACE_END
#endif  // UCONFIG_NO_REGULAR_EXPRESSIONS

#endif /* U_SHOW_CPLUSPLUS_API */

#endif