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 the built in Henry Spencer's library. In the latter case you need to abide
  22 by the terms of its copyright:
  23
  24 \begin{verbatim}
  25 Copyright 1992, 1993, 1994, 1997 Henry Spencer.  All rights reserved.
  26 This software is not subject to any license of the American Telephone
  27 and Telegraph Company or of the Regents of the University of California.
  28
  29 Permission is granted to anyone to use this software for any purpose on
  30 any computer system, and to alter it and redistribute it, subject
  31 to the following restrictions:
  32
  33 1. The author is not responsible for the consequences of use of this
  34    software, no matter how awful, even if they arise from flaws in it.
  35
  36 2. The origin of this software must not be misrepresented, either by
  37    explicit claim or by omission.  Since few users ever read sources,
  38    credits must appear in the documentation.
  39
  40 3. Altered versions must be plainly marked as such, and must not be
  41    misrepresented as being the original software.  Since few users
  42    ever read sources, credits must appear in the documentation.
  43
  44 4. This notice may not be removed or altered.
  45 \end{verbatim}
  46
  47 \wxheading{Derived from}
  48
  49 No base class
  50
  51 \wxheading{Data structures}
  52
  53 Flags for regex compilation to be used with \helpref{Compile()}{wxregexcompile}:
  54
  55 \begin{verbatim}
  56 enum
  57 {
  58     // use extended regex syntax (default)
  59     wxRE_EXTENDED = 0,
  60
  61     // use basic RE syntax
  62     wxRE_BASIC    = 2,
  63
  64     // ignore case in match
  65     wxRE_ICASE    = 4,
  66
  67     // only check match, don't set back references
  68     wxRE_NOSUB    = 8,
  69
  70     // if not set, treat '\n' as an ordinary character, otherwise it is
  71     // special: it is not matched by '.' and '^' and '$' always match
  72     // after/before it regardless of the setting of wxRE_NOT[BE]OL
  73     wxRE_NEWLINE  = 16,
  74
  75     // default flags
  76     wxRE_DEFAULT  = wxRE_EXTENDED
  77 }
  78 \end{verbatim}
  79
  80 Flags for regex matching to be used with \helpref{Matches()}{wxregexmatches}.
  81
  82 These flags are mainly useful when doing several matches in a long string
  83 to prevent erroneous matches for \verb|'^'| and {\tt '\$'}:
  84
  85 \begin{verbatim}
  86 enum
  87 {
  88     // '^' doesn't match at the start of line
  89     wxRE_NOTBOL = 32,
  90
  91     // '$' doesn't match at the end of line
  92     wxRE_NOTEOL = 64
  93 }
  94 \end{verbatim}
  95
  96 \wxheading{Examples}
  97
  98 A bad example of processing some text containing email addresses (the example
  99 is bad because the real email addresses can have more complicated form than
 100 {\tt user@host.net}):
 101
 102 \begin{verbatim}
 103 wxString text;
 104 ...
 105 wxRegEx reEmail = "([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)";
 106 if ( reEmail.Matches(text) )
 107 {
 108     wxString text = reEmail.GetMatch(email);
 109     wxString username = reEmail.GetMatch(email, 1);
 110     if ( reEmail.GetMatch(email, 3) == "com" ) // .com TLD?
 111     {
 112         ...
 113     }
 114 }
 115
 116 // or we could do this to hide the email address
 117 size_t count = reEmail.ReplaceAll(text, "HIDDEN@\\2\\3");
 118 printf("text now contains %u hidden addresses", count);
 119 \end{verbatim}
 120
 121 \latexignore{\rtfignore{\wxheading{Members}}}
 122
 123 \membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
 124
 125 \func{}{wxRegEx}{\void}
 126
 127 Default ctor: use \helpref{Compile()}{wxregexcompile} later.
 128
 129 \membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
 130
 131 \func{}{wxRegEx}{\param{const wxString\& }{expr}, \param{int }{flags = wxRE\_DEFAULT}}
 132
 133 Create and compile the regular expression, use
 134 \helpref{IsValid}{wxregexisvalid} to test for compilation errors.
 135
 136 \membersection{wxRegEx::\destruct{wxRegEx}}\label{wxregexdtor}
 137
 138 \func{}{\destruct{wxRegEx}}{\void}
 139
 140 dtor not virtual, don't derive from this class
 141
 142 \membersection{wxRegEx::Compile}\label{wxregexcompile}
 143
 144 \func{bool}{Compile}{\param{const wxString\& }{pattern}, \param{int }{flags = wxRE\_DEFAULT}}
 145
 146 Compile the string into regular expression, return {\tt TRUE} if ok or {\tt FALSE}
 147 if string has a syntax error.
 148
 149 \membersection{wxRegEx::IsValid}\label{wxregexisvalid}
 150
 151 \constfunc{bool}{IsValid}{\void}
 152
 153 Return {\tt TRUE} if this is a valid compiled regular expression, {\tt FALSE}
 154 otherwise.
 155
 156 \membersection{wxRegEx::GetMatch}\label{wxregexgetmatch}
 157
 158 \constfunc{bool}{GetMatch}{\param{size\_t* }{start}, \param{size\_t* }{len}, \param{size\_t }{index = 0}}
 159
 160 Get the start index and the length of the match of the expression
 161 (if {\it index} is $0$) or a bracketed subexpression ({\it index} different
 162 from $0$).
 163
 164 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 165 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 166 \helpref{Compile()}{wxregexcompile}.
 167
 168 Returns {\tt FALSE} if no match or if an error occured.
 169
 170 \constfunc{wxString}{GetMatch}{\param{const wxString\& }{text}, \param{size\_t }{index = 0}}
 171
 172 Returns the part of string corresponding to the match where {\it index} is
 173 interpreted as above. Empty string is returned if match failed
 174
 175 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 176 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 177 \helpref{Compile()}{wxregexcompile}.
 178
 179 \membersection{wxRegEx::Matches}\label{wxregexmatches}
 180
 181 \constfunc{bool}{Matches}{\param{const wxChar* }{text}, \param{int }{flags = 0}}
 182
 183 Matches the precompiled regular expression against the string {\it text},
 184 returns {\tt TRUE} if matches and {\tt FALSE} otherwise.
 185
 186 Flags may be combination of {\tt wxRE\_NOTBOL} and {\tt wxRE\_NOTEOL}.
 187
 188 May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
 189
 190 \membersection{wxRegEx::Replace}\label{wxregexreplace}
 191
 192 \constfunc{int}{Replace}{\param{wxString* }{text}, \param{const wxString\& }{replacement}, \param{size\_t }{maxMatches = 0}}
 193
 194 Replaces the current regular expression in the string pointed to by
 195 {\it text}, with the text in {\it replacement} and return number of matches
 196 replaced (maybe $0$ if none found) or $-1$ on error.
 197
 198 The replacement text may contain back references {\tt $\backslash$number} which will be
 199 replaced with the value of the corresponding subexpression in the
 200 pattern match. {\tt $\backslash$0} corresponds to the entire match and {\tt \&} is a
 201 synonym for it. Backslash may be used to quote itself or {\tt \&} character.
 202
 203 {\it maxMatches} may be used to limit the number of replacements made, setting
 204 it to $1$, for example, will only replace first occurence (if any) of the
 205 pattern in the text while default value of $0$ means replace all.
 206
 207 \membersection{wxRegEx::ReplaceAll}\label{wxregexreplaceall}
 208
 209 \constfunc{int}{ReplaceAll}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 210
 211 Replace all occurences: this is actually a synonym for
 212 \helpref{Replace()}{wxregexreplace}.
 213
 214 \wxheading{See also}
 215
 216 \helpref{ReplaceFirst}{wxregexreplacefirst}
 217
 218 \membersection{wxRegEx::ReplaceFirst}\label{wxregexreplacefirst}
 219
 220 \constfunc{int}{ReplaceFirst}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 221
 222 Replace the first occurence.
 223
 224 \wxheading{See also}
 225
 226 \helpref{Replace}{wxregexreplace}
 227