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 #ifdef __GNUG__
  16     #pragma interface "regex.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_REGEX
  22
  23 class WXDLLEXPORT wxString;
  24
  25 // ----------------------------------------------------------------------------
  26 // constants
  27 // ----------------------------------------------------------------------------
  28
  29 // max number of subexpression matches, the default should be big enough for
  30 // all uses but may be a bit wasteful
  31 #ifndef WX_REGEX_MAXMATCHES
  32     #define WX_REGEX_MAXMATCHES 1024
  33 #endif
  34
  35 // flags for regex compilation: these can be used with Compile()
  36 enum
  37 {
  38     // use extended regex syntax (default)
  39     wxRE_EXTENDED = 0,
  40
  41     // use basic RE syntax
  42     wxRE_BASIC    = 2,
  43
  44     // ignore case in match
  45     wxRE_ICASE    = 4,
  46
  47     // only check match, don't set back references
  48     wxRE_NOSUB    = 8,
  49
  50     // if not set, treat '\n' as an ordinary character, otherwise it is
  51     // special: it is not matched by '.' and '^' and '$' always match
  52     // after/before it regardless of the setting of wxRE_NOT[BE]OL
  53     wxRE_NEWLINE  = 16,
  54
  55     // default flags
  56     wxRE_DEFAULT  = wxRE_EXTENDED
  57 };
  58
  59 // flags for regex matching: these can be used with Matches()
  60 //
  61 // these flags are mainly useful when doing several matches in a long string,
  62 // they can be used to prevent erroneous matches for '^' and '$'
  63 enum
  64 {
  65     // '^' doesn't match at the start of line
  66     wxRE_NOTBOL = 32,
  67
  68     // '$' doesn't match at the end of line
  69     wxRE_NOTEOL = 64
  70 };
  71
  72 // ----------------------------------------------------------------------------
  73 // wxRegEx: a regular expression
  74 // ----------------------------------------------------------------------------
  75
  76 class WXDLLEXPORT wxRegExImpl;
  77
  78 class WXDLLEXPORT wxRegEx
  79 {
  80 public:
  81     // default ctor: use Compile() later
  82     wxRegEx() { Init(); }
  83
  84     // create and compile
  85     wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT)
  86     {
  87         Init();
  88         (void)Compile(expr, flags);
  89     }
  90
  91     // return TRUE if this is a valid compiled regular expression
  92     bool IsValid() const { return m_impl != NULL; }
  93
  94     // compile the string into regular expression, return TRUE if ok or FALSE
  95     // if string has a syntax error
  96     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
  97
  98     // matches the precompiled regular expression against a string, return
  99     // TRUE if matches and FALSE otherwise
 100     //
 101     // flags may be combination of wxRE_NOTBOL and wxRE_NOTEOL
 102     //
 103     // may only be called after successful call to Compile()
 104     bool Matches(const wxChar *text, int flags = 0) const;
 105
 106     // get the start index and the length of the match of the expression
 107     // (index 0) or a bracketed subexpression (index != 0)
 108     //
 109     // may only be called after successful call to Matches()
 110     //
 111     // return FALSE if no match or on error
 112     bool GetMatch(size_t *start, size_t *len, size_t index = 0) const;
 113
 114     // return the part of string corresponding to the match, empty string is
 115     // returned if match failed
 116     //
 117     // may only be called after successful call to Matches()
 118     wxString GetMatch(const wxString& text, size_t index = 0) const;
 119
 120     // replaces the current regular expression in the string pointed to by
 121     // pattern, with the text in replacement and return number of matches
 122     // replaced (maybe 0 if none found) or -1 on error
 123     //
 124     // the replacement text may contain backreferences (\number) which will be
 125     // replaced with the value of the corresponding subexpression in the
 126     // pattern match
 127     //
 128     // maxMatches may be used to limit the number of replacements made, setting
 129     // it to 1, for example, will only replace first occurence (if any) of the
 130     // pattern in the text while default value of 0 means replace all
 131     int Replace(wxString *text, const wxString& replacement,
 132                 size_t maxMatches = 0) const;
 133
 134     // replace the first occurence
 135     int ReplaceFirst(wxString *text, const wxString& replacement) const
 136         { return Replace(text, replacement, 1); }
 137
 138     // replace all occurences: this is actually a synonym for Replace()
 139     int ReplaceAll(wxString *text, const wxString& replacement) const
 140         { return Replace(text, replacement, 0); }
 141
 142     // dtor not virtual, don't derive from this class
 143     ~wxRegEx();
 144
 145 private:
 146     // common part of all ctors
 147     void Init();
 148
 149     // the real guts of this class
 150     wxRegExImpl *m_impl;
 151 };
 152
 153 #endif // wxUSE_REGEX
 154
 155 #endif // _WX_REGEX_H_
 156