docs/latex/wx/regex.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        regex.tex
   3 %% Purpose:     wxRegEx documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     14.07.01
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2001 Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxRegEx}}\label{wxregex}
  13
  14 wxRegEx represents a regular expression. The regular expressions syntax
  15 supported is the POSIX one. Both basic and extended regular expressions are
  16 supported but, unlike POSIX C API, the extended ones are used by default.
  17
  18 This class provides support for regular expressions matching and also
  19 replacement. It is built on top of either the system library (if it has support
  20 for POSIX regular expressions - which is the case of the most modern Unices) or
  21 uses a version of Henry Spencer's library from tcl.
  22
  23 \wxheading{Derived from}
  24
  25 No base class
  26
  27 \wxheading{Data structures}
  28
  29 Flags for regex compilation to be used with \helpref{Compile()}{wxregexcompile}:
  30
  31 \begin{verbatim}
  32 enum
  33 {
  34     // use extended regex syntax (default)
  35     wxRE_EXTENDED = 0,
  36
  37     // use basic RE syntax
  38     wxRE_BASIC    = 2,
  39
  40     // ignore case in match
  41     wxRE_ICASE    = 4,
  42
  43     // only check match, don't set back references
  44     wxRE_NOSUB    = 8,
  45
  46     // if not set, treat '\n' as an ordinary character, otherwise it is
  47     // special: it is not matched by '.' and '^' and '$' always match
  48     // after/before it regardless of the setting of wxRE_NOT[BE]OL
  49     wxRE_NEWLINE  = 16,
  50
  51     // default flags
  52     wxRE_DEFAULT  = wxRE_EXTENDED
  53 }
  54 \end{verbatim}
  55
  56 Flags for regex matching to be used with \helpref{Matches()}{wxregexmatches}.
  57
  58 These flags are mainly useful when doing several matches in a long string
  59 to prevent erroneous matches for {\tt '\textasciicircum'} and {\tt '\$'}:
  60
  61 \begin{verbatim}
  62 enum
  63 {
  64     // '^' doesn't match at the start of line
  65     wxRE_NOTBOL = 32,
  66
  67     // '$' doesn't match at the end of line
  68     wxRE_NOTEOL = 64
  69 }
  70 \end{verbatim}
  71
  72 \wxheading{Examples}
  73
  74 A bad example of processing some text containing email addresses (the example
  75 is bad because the real email addresses can have more complicated form than
  76 {\tt user@host.net}):
  77
  78 \begin{verbatim}
  79 wxString text;
  80 ...
  81 wxRegEx reEmail = "([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)";
  82 if ( reEmail.Matches(text) )
  83 {
  84     wxString text = reEmail.GetMatch(email);
  85     wxString username = reEmail.GetMatch(email, 1);
  86     if ( reEmail.GetMatch(email, 3) == "com" ) // .com TLD?
  87     {
  88         ...
  89     }
  90 }
  91
  92 // or we could do this to hide the email address
  93 size_t count = reEmail.ReplaceAll(text, "HIDDEN@\\2\\3");
  94 printf("text now contains %u hidden addresses", count);
  95 \end{verbatim}
  96
  97 \latexignore{\rtfignore{\wxheading{Members}}}
  98
  99 \membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
 100
 101 \func{}{wxRegEx}{\void}
 102
 103 Default ctor: use \helpref{Compile()}{wxregexcompile} later.
 104
 105 \func{}{wxRegEx}{\param{const wxString\& }{expr}, \param{int }{flags = wxRE\_DEFAULT}}
 106
 107 Create and compile the regular expression, use
 108 \helpref{IsValid}{wxregexisvalid} to test for compilation errors.
 109
 110 \membersection{wxRegEx::\destruct{wxRegEx}}\label{wxregexdtor}
 111
 112 \func{}{\destruct{wxRegEx}}{\void}
 113
 114 dtor not virtual, don't derive from this class
 115
 116 \membersection{wxRegEx::Compile}\label{wxregexcompile}
 117
 118 \func{bool}{Compile}{\param{const wxString\& }{pattern}, \param{int }{flags = wxRE\_DEFAULT}}
 119
 120 Compile the string into regular expression, return {\tt true} if ok or {\tt false}
 121 if string has a syntax error.
 122
 123 \membersection{wxRegEx::IsValid}\label{wxregexisvalid}
 124
 125 \constfunc{bool}{IsValid}{\void}
 126
 127 Return {\tt true} if this is a valid compiled regular expression, {\tt false}
 128 otherwise.
 129
 130 \membersection{wxRegEx::GetMatch}\label{wxregexgetmatch}
 131
 132 \constfunc{bool}{GetMatch}{\param{size\_t* }{start}, \param{size\_t* }{len}, \param{size\_t }{index = 0}}
 133
 134 Get the start index and the length of the match of the expression
 135 (if {\it index} is $0$) or a bracketed subexpression ({\it index} different
 136 from $0$).
 137
 138 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 139 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 140 \helpref{Compile()}{wxregexcompile}.
 141
 142 Returns {\tt false} if no match or if an error occured.
 143
 144 \constfunc{wxString}{GetMatch}{\param{const wxString\& }{text}, \param{size\_t }{index = 0}}
 145
 146 Returns the part of string corresponding to the match where {\it index} is
 147 interpreted as above. Empty string is returned if match failed
 148
 149 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 150 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 151 \helpref{Compile()}{wxregexcompile}.
 152
 153 \membersection{wxRegEx::Matches}\label{wxregexmatches}
 154
 155 \constfunc{bool}{Matches}{\param{const wxChar* }{text}, \param{int }{flags = 0}}
 156
 157 Matches the precompiled regular expression against the string {\it text},
 158 returns {\tt true} if matches and {\tt false} otherwise.
 159
 160 Flags may be combination of {\tt wxRE\_NOTBOL} and {\tt wxRE\_NOTEOL}.
 161
 162 May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
 163
 164 \membersection{wxRegEx::Replace}\label{wxregexreplace}
 165
 166 \constfunc{int}{Replace}{\param{wxString* }{text}, \param{const wxString\& }{replacement}, \param{size\_t }{maxMatches = 0}}
 167
 168 Replaces the current regular expression in the string pointed to by
 169 {\it text}, with the text in {\it replacement} and return number of matches
 170 replaced (maybe $0$ if none found) or $-1$ on error.
 171
 172 The replacement text may contain back references {\tt $\backslash$number} which will be
 173 replaced with the value of the corresponding subexpression in the
 174 pattern match. {\tt $\backslash$0} corresponds to the entire match and {\tt \&} is a
 175 synonym for it. Backslash may be used to quote itself or {\tt \&} character.
 176
 177 {\it maxMatches} may be used to limit the number of replacements made, setting
 178 it to $1$, for example, will only replace first occurrence (if any) of the
 179 pattern in the text while default value of $0$ means replace all.
 180
 181 \membersection{wxRegEx::ReplaceAll}\label{wxregexreplaceall}
 182
 183 \constfunc{int}{ReplaceAll}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 184
 185 Replace all occurrences: this is actually a synonym for
 186 \helpref{Replace()}{wxregexreplace}.
 187
 188 \wxheading{See also}
 189
 190 \helpref{ReplaceFirst}{wxregexreplacefirst}
 191
 192 \membersection{wxRegEx::ReplaceFirst}\label{wxregexreplacefirst}
 193
 194 \constfunc{int}{ReplaceFirst}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 195
 196 Replace the first occurrence.
 197
 198 \wxheading{See also}
 199
 200 \helpref{Replace}{wxregexreplace}
 201