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 \begin{verbatim}
  55 enum
  56 {
  57     // use extended regex syntax (default)
  58     wxRE\_EXTENDED = 0,
  59
  60     // use basic RE syntax
  61     wxRE\_BASIC    = 2,
  62
  63     // ignore case in match
  64     wxRE\_ICASE    = 4,
  65
  66     // only check match, don't set back references
  67     wxRE\_NOSUB    = 8,
  68
  69     // if not set, treat '\n' as an ordinary character, otherwise it is
  70     // special: it is not matched by '.' and '^' and '$' always match
  71     // after/before it regardless of the setting of wxRE\_NOT[BE]OL
  72     wxRE\_NEWLINE  = 16,
  73
  74     // default flags
  75     wxRE\_DEFAULT  = wxRE\_EXTENDED
  76 }
  77 \end{verbatim}
  78
  79 Flags for regex matching to be used with \helpref{Matches()}{wxregexmatches}.
  80
  81 These flags are mainly useful when doing several matches in a long string
  82 to prevent erroneous matches for {\tt '\^'} and {\tt '\$'}
  83 \begin{verbatim}
  84 enum
  85 {
  86     // '^' doesn't match at the start of line
  87     wxRE\_NOTBOL = 32,
  88
  89     // '$' doesn't match at the end of line
  90     wxRE\_NOTEOL = 64
  91 }
  92 \end{verbatim}
  93
  94 \latexignore{\rtfignore{\wxheading{Members}}}
  95
  96 \membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
  97
  98 \func{}{wxRegEx}{\void}
  99
 100 Default ctor: use \helpref{Compile()}{wxregexcompile} later.
 101
 102 \membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
 103
 104 \func{}{wxRegEx}{\param{const wxString\& }{expr}, \param{int }{flags = wxRE\_DEFAULT}}
 105
 106 Create and compile the regular expression, use
 107 \helpref{IsValid}{wxregexisvalid} to test for compilation errors.
 108
 109 \membersection{wxRegEx::\destruct{wxRegEx}}\label{wxregexdtor}
 110
 111 \func{}{\destruct{wxRegEx}}{\void}
 112
 113 dtor not virtual, don't derive from this class
 114
 115 \membersection{wxRegEx::Compile}\label{wxregexcompile}
 116
 117 \func{bool}{Compile}{\param{const wxString\& }{pattern}, \param{int }{flags = wxRE\_DEFAULT}}
 118
 119 Compile the string into regular expression, return {\tt TRUE} if ok or {\tt FALSE}
 120 if string has a syntax error.
 121
 122 \membersection{wxRegEx::IsValid}\label{wxregexisvalid}
 123
 124 \constfunc{bool}{IsValid}{\void}
 125
 126 Return {\tt TRUE} if this is a valid compiled regular expression, {\tt FALSE}
 127 otherwise.
 128
 129 \membersection{wxRegEx::GetMatch}\label{wxregexgetmatch}
 130
 131 \constfunc{bool}{GetMatch}{\param{size\_t* }{start}, \param{size\_t* }{len}, \param{size\_t }{index = 0}}
 132
 133 Get the start index and the length of the match of the expression
 134 (if {\it index} is $0$) or a bracketed subexpression ({\it index} different
 135 from $0$).
 136
 137 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 138 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 139 \helpref{Compile()}{wxregexcompile}.
 140
 141 Returns {\tt FALSE} if no match or if an error occured.
 142
 143 \constfunc{wxString}{GetMatch}{\param{const wxString\& }{text}, \param{size\_t }{index = 0}}
 144
 145 Returns the part of string corresponding to the match where {\it index} is
 146 interpreted as above. Empty string is returned if match failed
 147
 148 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
 149 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
 150 \helpref{Compile()}{wxregexcompile}.
 151
 152 \membersection{wxRegEx::Matches}\label{wxregexmatches}
 153
 154 \constfunc{bool}{Matches}{\param{const wxChar* }{text}, \param{int }{flags = 0}}
 155
 156 Matches the precompiled regular expression against the string {\it text},
 157 returns {\tt TRUE} if matches and {\tt FALSE} otherwise.
 158
 159 Flags may be combination of {\tt wxRE\_NOTBOL} and {\tt wxRE\_NOTEOL}.
 160
 161 May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
 162
 163 \membersection{wxRegEx::Replace}\label{wxregexreplace}
 164
 165 \constfunc{int}{Replace}{\param{wxString* }{text}, \param{const wxString\& }{replacement}, \param{size\_t }{maxMatches = 0}}
 166
 167 Replaces the current regular expression in the string pointed to by
 168 {\it text}, with the text in {\it replacement} and return number of matches
 169 replaced (maybe $0$ if none found) or $-1$ on error.
 170
 171 The replacement text may contain back references {\tt \\number} which will be
 172 replaced with the value of the corresponding subexpression in the
 173 pattern match. {\tt \\0} corresponds to the entire match and {\tt \&} is a
 174 synonym for it. Backslash may be used to quote itself or {\tt \&} character.
 175
 176 {\it maxMatches} may be used to limit the number of replacements made, setting
 177 it to $1$, for example, will only replace first occurence (if any) of the
 178 pattern in the text while default value of $0$ means replace all.
 179
 180 \membersection{wxRegEx::ReplaceAll}\label{wxregexreplaceall}
 181
 182 \constfunc{int}{ReplaceAll}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 183
 184 Replace all occurences: this is actually a synonym for
 185 \helpref{Replace()}{wxregexreplace}.
 186
 187 \wxheading{See also}
 188
 189 \helpref{ReplaceFirst}{wxregexreplacefirst}
 190
 191 \membersection{wxRegEx::ReplaceFirst}\label{wxregexreplacefirst}
 192
 193 \constfunc{int}{ReplaceFirst}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
 194
 195 Replace the first occurence.
 196
 197 \wxheading{See also}
 198
 199 \helpref{Replace}{wxregexreplace}
 200