include/wx/regex.h

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