interface/regex.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        regex.h
   3 // Purpose:     documentation for wxRegEx class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRegEx
  11     @wxheader{regex.h}
  12
  13     wxRegEx represents a regular expression.  This class provides support
  14     for regular expressions matching and also replacement.
  15
  16     It is built on top of either the system library (if it has support
  17     for POSIX regular expressions - which is the case of the most modern
  18     Unices) or uses the built in Henry Spencer's library.  Henry Spencer
  19     would appreciate being given credit in the documentation of software
  20     which uses his library, but that is not a requirement.
  21
  22     Regular expressions, as defined by POSIX, come in two flavours: @e extended
  23     and @e basic.  The builtin library also adds a third flavour
  24     of expression advanced, which is not available
  25     when using the system library.
  26
  27     Unicode is fully supported only when using the builtin library.
  28     When using the system library in Unicode mode, the expressions and data
  29     are translated to the default 8-bit encoding before being passed to
  30     the library.
  31
  32     On platforms where a system library is available, the default is to use
  33     the builtin library for Unicode builds, and the system library otherwise.
  34     It is possible to use the other if preferred by selecting it when building
  35     the wxWidgets.
  36
  37     @library{wxbase}
  38     @category{data}
  39
  40     @seealso
  41     wxRegEx::ReplaceFirst
  42 */
  43 class wxRegEx
  44 {
  45 public:
  46     //@{
  47     /**
  48         Create and compile the regular expression, use
  49         IsValid() to test for compilation errors.
  50     */
  51     wxRegEx();
  52     wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT);
  53     //@}
  54
  55     /**
  56         dtor not virtual, don't derive from this class
  57     */
  58     ~wxRegEx();
  59
  60     /**
  61         Compile the string into regular expression, return @true if ok or @false
  62         if string has a syntax error.
  63     */
  64     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
  65
  66     //@{
  67     /**
  68         Returns the part of string corresponding to the match where @e index is
  69         interpreted as above. Empty string is returned if match failed
  70
  71         May only be called after successful call to Matches()
  72         and only if @c wxRE_NOSUB was @b not used in
  73         Compile().
  74     */
  75     bool GetMatch(size_t* start, size_t* len, size_t index = 0);
  76     not wxString  GetMatch(const wxString& text,
  77                            size_t index = 0);
  78     //@}
  79
  80     /**
  81         Returns the size of the array of matches, i.e. the number of bracketed
  82         subexpressions plus one for the expression itself, or 0 on error.
  83
  84         May only be called after successful call to Compile().
  85         and only if @c wxRE_NOSUB was @b not used.
  86     */
  87     size_t GetMatchCount();
  88
  89     /**
  90         Return @true if this is a valid compiled regular expression, @false
  91         otherwise.
  92     */
  93     bool IsValid();
  94
  95     //@{
  96     /**
  97         Matches the precompiled regular expression against the string @e text,
  98         returns @true if matches and @false otherwise.
  99
 100         @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL.
 101
 102         Some regex libraries assume that the text given is null terminated, while
 103         others require the length be given as a separate parameter. Therefore for
 104         maximum portability assume that @e text cannot contain embedded nulls.
 105
 106         When the @e Matches(const wxChar *text, int flags = 0) form is used,
 107         a @e wxStrlen() will be done internally if the regex library requires the
 108         length. When using @e Matches() in a loop
 109         the @e Matches(text, flags, len) form can be used instead, making it
 110         possible to avoid a @e wxStrlen() inside the loop.
 111
 112         May only be called after successful call to Compile().
 113     */
 114     bool Matches(const wxChar* text, int flags = 0);
 115     bool Matches(const wxChar* text, int flags, size_t len);
 116     bool Matches(const wxString& text, int flags = 0);
 117     //@}
 118
 119     /**
 120         Replaces the current regular expression in the string pointed to by
 121         @e text, with the text in @e replacement and return number of matches
 122         replaced (maybe 0 if none found) or -1 on error.
 123
 124         The replacement text may contain back references @c \number which will be
 125         replaced with the value of the corresponding subexpression in the
 126         pattern match. @c \0 corresponds to the entire match and @c  is a
 127         synonym for it. Backslash may be used to quote itself or @c  character.
 128
 129         @e maxMatches may be used to limit the number of replacements made, setting
 130         it to 1, for example, will only replace first occurrence (if any) of the
 131         pattern in the text while default value of 0 means replace all.
 132     */
 133     int Replace(wxString* text, const wxString& replacement,
 134                 size_t maxMatches = 0);
 135
 136     /**
 137         Replace all occurrences: this is actually a synonym for
 138         Replace().
 139
 140         @sa ReplaceFirst()
 141     */
 142     int ReplaceAll(wxString* text, const wxString& replacement);
 143
 144     /**
 145         Replace the first occurrence.
 146     */
 147     int ReplaceFirst(wxString* text, const wxString& replacement);
 148 };