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 @a index is
  69         interpreted as above. Empty string is returned if match failed
  70         May only be called after successful call to Matches()
  71         and only if @c wxRE_NOSUB was @b not used in
  72         Compile().
  73     */
  74     bool GetMatch(size_t* start, size_t* len, size_t index = 0) const;
  75     const not used in
  76     Compile().
  77     Returns false if no match or if an error occurred.
  78         wxString  GetMatch(const wxString& text, size_t index = 0) const;
  79     //@}
  80
  81     /**
  82         Returns the size of the array of matches, i.e. the number of bracketed
  83         subexpressions plus one for the expression itself, or 0 on error.
  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() const;
  88
  89     /**
  90         Return @true if this is a valid compiled regular expression, @false
  91         otherwise.
  92     */
  93     bool IsValid() const;
  94
  95     //@{
  96     /**
  97         Matches the precompiled regular expression against the string @e text,
  98         returns @true if matches and @false otherwise.
  99         @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL.
 100         Some regex libraries assume that the text given is null terminated, while
 101         others require the length be given as a separate parameter. Therefore for
 102         maximum portability assume that @a text cannot contain embedded nulls.
 103         When the @e Matches(const wxChar *text, int flags = 0) form is used,
 104         a @e wxStrlen() will be done internally if the regex library requires the
 105         length. When using @e Matches() in a loop
 106         the @e Matches(text, flags, len) form can be used instead, making it
 107         possible to avoid a @e wxStrlen() inside the loop.
 108         May only be called after successful call to Compile().
 109     */
 110     bool Matches(const wxChar* text, int flags = 0) const;
 111     const bool Matches(const wxChar* text, int flags, size_t len) const;
 112     const bool Matches(const wxString& text, int flags = 0) const;
 113     //@}
 114
 115     /**
 116         Replaces the current regular expression in the string pointed to by
 117         @e text, with the text in @a replacement and return number of matches
 118         replaced (maybe 0 if none found) or -1 on error.
 119         The replacement text may contain back references @c \number which will be
 120         replaced with the value of the corresponding subexpression in the
 121         pattern match. @c \0 corresponds to the entire match and @c  is a
 122         synonym for it. Backslash may be used to quote itself or @c  character.
 123         @a maxMatches may be used to limit the number of replacements made, setting
 124         it to 1, for example, will only replace first occurrence (if any) of the
 125         pattern in the text while default value of 0 means replace all.
 126     */
 127     int Replace(wxString* text, const wxString& replacement,
 128                 size_t maxMatches = 0) const;
 129
 130     /**
 131         Replace all occurrences: this is actually a synonym for
 132         Replace().
 133
 134         @see ReplaceFirst()
 135     */
 136     int ReplaceAll(wxString* text, const wxString& replacement) const;
 137
 138     /**
 139         Replace the first occurrence.
 140     */
 141     int ReplaceFirst(wxString* text, const wxString& replacement) const;
 142 };