interface/regex.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        regex.h
   3 // Purpose:     interface of wxRegEx
   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     @see wxRegEx::ReplaceFirst
  41 */
  42 class wxRegEx
  43 {
  44 public:
  45     //@{
  46     /**
  47         Create and compile the regular expression, use
  48         IsValid() to test for compilation errors.
  49     */
  50     wxRegEx();
  51     wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT);
  52     //@}
  53
  54     /**
  55         dtor not virtual, don't derive from this class
  56     */
  57     ~wxRegEx();
  58
  59     /**
  60         Compile the string into regular expression, return @true if ok or @false
  61         if string has a syntax error.
  62     */
  63     bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT);
  64
  65     //@{
  66     /**
  67         Returns the part of string corresponding to the match where @a index is
  68         interpreted as above. Empty string is returned if match failed
  69         May only be called after successful call to Matches()
  70         and only if @c wxRE_NOSUB was @b not used in
  71         Compile().
  72     */
  73     bool GetMatch(size_t* start, size_t* len, size_t index = 0) const;
  74     const not used in
  75     Compile().
  76     Returns false if no match or if an error occurred.
  77         wxString  GetMatch(const wxString& text, size_t index = 0) const;
  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         May only be called after successful call to Compile().
  84         and only if @c wxRE_NOSUB was @b not used.
  85     */
  86     size_t GetMatchCount() const;
  87
  88     /**
  89         Return @true if this is a valid compiled regular expression, @false
  90         otherwise.
  91     */
  92     bool IsValid() const;
  93
  94     //@{
  95     /**
  96         Matches the precompiled regular expression against the string @e text,
  97         returns @true if matches and @false otherwise.
  98         @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL.
  99         Some regex libraries assume that the text given is null terminated, while
 100         others require the length be given as a separate parameter. Therefore for
 101         maximum portability assume that @a text cannot contain embedded nulls.
 102         When the @e Matches(const wxChar *text, int flags = 0) form is used,
 103         a @e wxStrlen() will be done internally if the regex library requires the
 104         length. When using @e Matches() in a loop
 105         the @e Matches(text, flags, len) form can be used instead, making it
 106         possible to avoid a @e wxStrlen() inside the loop.
 107         May only be called after successful call to Compile().
 108     */
 109     bool Matches(const wxChar* text, int flags = 0) const;
 110     const bool Matches(const wxChar* text, int flags, size_t len) const;
 111     const bool Matches(const wxString& text, int flags = 0) const;
 112     //@}
 113
 114     /**
 115         Replaces the current regular expression in the string pointed to by
 116         @e text, with the text in @a replacement and return number of matches
 117         replaced (maybe 0 if none found) or -1 on error.
 118         The replacement text may contain back references @c \number which will be
 119         replaced with the value of the corresponding subexpression in the
 120         pattern match. @c \0 corresponds to the entire match and @c  is a
 121         synonym for it. Backslash may be used to quote itself or @c  character.
 122         @a maxMatches may be used to limit the number of replacements made, setting
 123         it to 1, for example, will only replace first occurrence (if any) of the
 124         pattern in the text while default value of 0 means replace all.
 125     */
 126     int Replace(wxString* text, const wxString& replacement,
 127                 size_t maxMatches = 0) const;
 128
 129     /**
 130         Replace all occurrences: this is actually a synonym for
 131         Replace().
 132
 133         @see ReplaceFirst()
 134     */
 135     int ReplaceAll(wxString* text, const wxString& replacement) const;
 136
 137     /**
 138         Replace the first occurrence.
 139     */
 140     int ReplaceFirst(wxString* text, const wxString& replacement) const;
 141 };
 142