include/wx/regex.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/regex.h
   3 // Purpose:     regular expression matching
   4 // Author:      Karsten Ballueder
   5 // Modified by: VZ at 13.07.01 (integrated to wxWin)
   6 // Created:     05.02.2000
   7 // Copyright:   (c) 2000 Karsten Ballueder <ballueder@gmx.net>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_REGEX_H_
  12 #define _WX_REGEX_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_REGEX
  17
  18 #include "wx/string.h"
  19
  20 // ----------------------------------------------------------------------------
  21 // constants
  22 // ----------------------------------------------------------------------------
  23
  24 // flags for regex compilation: these can be used with Compile()
  25 enum
  26 {
  27     // use extended regex syntax
  28     wxRE_EXTENDED = 0,
  29
  30     // use advanced RE syntax (built-in regex only)
  31 #ifdef wxHAS_REGEX_ADVANCED
  32     wxRE_ADVANCED = 1,
  33 #endif
  34
  35     // use basic RE syntax
  36     wxRE_BASIC    = 2,
  37
  38     // ignore case in match
  39     wxRE_ICASE    = 4,
  40
  41     // only check match, don't set back references
  42     wxRE_NOSUB    = 8,
  43
  44     // if not set, treat '\n' as an ordinary character, otherwise it is
  45     // special: it is not matched by '.' and '^' and '$' always match
  46     // after/before it regardless of the setting of wxRE_NOT[BE]OL
  47     wxRE_NEWLINE  = 16,
  48
  49     // default flags
  50     wxRE_DEFAULT  = wxRE_EXTENDED
  51 };
  52
  53 // flags for regex matching: these can be used with Matches()
  54 //
  55 // these flags are mainly useful when doing several matches in a long string,
  56 // they can be used to prevent erroneous matches for '^' and '$'
  57 enum
  58 {
  59     // '^' doesn't match at the start of line
  60     wxRE_NOTBOL = 32,
  61
  62     // '$' doesn't match at the end of line
  63     wxRE_NOTEOL = 64
  64 };
  65
  66 // ----------------------------------------------------------------------------
  67 // wxRegEx: a regular expression
  68 // ----------------------------------------------------------------------------
  69
  70 class WXDLLIMPEXP_FWD_BASE wxRegExImpl;
  71
  72 class WXDLLIMPEXP_BASE wxRegEx
  73 {
  74 public:
  75     // default ctor: use Compile() later
  76     wxRegEx() { Init(); }
  77
  78     // create and compile
  79     wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT)
  80     {
  81         Init();
  82         (void)Compile(expr, flags);
  83     }
  84
  85     // return true if this is a valid compiled regular expression
  86     bool IsValid() const { return m_impl != NULL; }
  87
  88     // compile the string into regular expression, return true if ok or false
  89     // if string has a syntax error
  90     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
  91
  92     // matches the precompiled regular expression against a string, return
  93     // true if matches and false otherwise
  94     //
  95     // flags may be combination of wxRE_NOTBOL and wxRE_NOTEOL
  96     // len may be the length of text (ignored by most system regex libs)
  97     //
  98     // may only be called after successful call to Compile()
  99     bool Matches(const wxString& text, int flags = 0) const;
 100     bool Matches(const wxChar *text, int flags, size_t len) const
 101         { return Matches(wxString(text, len), flags); }
 102
 103     // get the start index and the length of the match of the expression
 104     // (index 0) or a bracketed subexpression (index != 0)
 105     //
 106     // may only be called after successful call to Matches()
 107     //
 108     // return false if no match or on error
 109     bool GetMatch(size_t *start, size_t *len, size_t index = 0) const;
 110
 111     // return the part of string corresponding to the match, empty string is
 112     // returned if match failed
 113     //
 114     // may only be called after successful call to Matches()
 115     wxString GetMatch(const wxString& text, size_t index = 0) const;
 116
 117     // return the size of the array of matches, i.e. the number of bracketed
 118     // subexpressions plus one for the expression itself, or 0 on error.
 119     //
 120     // may only be called after successful call to Compile()
 121     size_t GetMatchCount() const;
 122
 123     // replaces the current regular expression in the string pointed to by
 124     // pattern, with the text in replacement and return number of matches
 125     // replaced (maybe 0 if none found) or -1 on error
 126     //
 127     // the replacement text may contain backreferences (\number) which will be
 128     // replaced with the value of the corresponding subexpression in the
 129     // pattern match
 130     //
 131     // maxMatches may be used to limit the number of replacements made, setting
 132     // it to 1, for example, will only replace first occurrence (if any) of the
 133     // pattern in the text while default value of 0 means replace all
 134     int Replace(wxString *text, const wxString& replacement,
 135                 size_t maxMatches = 0) const;
 136
 137     // replace the first occurrence
 138     int ReplaceFirst(wxString *text, const wxString& replacement) const
 139         { return Replace(text, replacement, 1); }
 140
 141     // replace all occurrences: this is actually a synonym for Replace()
 142     int ReplaceAll(wxString *text, const wxString& replacement) const
 143         { return Replace(text, replacement, 0); }
 144
 145     // dtor not virtual, don't derive from this class
 146     ~wxRegEx();
 147
 148 private:
 149     // common part of all ctors
 150     void Init();
 151
 152     // the real guts of this class
 153     wxRegExImpl *m_impl;
 154
 155     // as long as the class wxRegExImpl is not ref-counted,
 156     // instances of the handle wxRegEx must not be copied.
 157     wxRegEx(const wxRegEx&);
 158     wxRegEx &operator=(const wxRegEx&);
 159 };
 160
 161 #endif // wxUSE_REGEX
 162
 163 #endif // _WX_REGEX_H_
 164