]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/regex.tex
clean up of memory debugging macros and chanegs to compile with CW7 (patch 548408)
[wxWidgets.git] / 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 {\tt '^'} 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 \func{}{wxRegEx}{\param{const wxString\& }{expr}, \param{int }{flags = wxRE\_DEFAULT}}
130
131 Create and compile the regular expression, use
132 \helpref{IsValid}{wxregexisvalid} to test for compilation errors.
133
134 \membersection{wxRegEx::\destruct{wxRegEx}}\label{wxregexdtor}
135
136 \func{}{\destruct{wxRegEx}}{\void}
137
138 dtor not virtual, don't derive from this class
139
140 \membersection{wxRegEx::Compile}\label{wxregexcompile}
141
142 \func{bool}{Compile}{\param{const wxString\& }{pattern}, \param{int }{flags = wxRE\_DEFAULT}}
143
144 Compile the string into regular expression, return {\tt TRUE} if ok or {\tt FALSE}
145 if string has a syntax error.
146
147 \membersection{wxRegEx::IsValid}\label{wxregexisvalid}
148
149 \constfunc{bool}{IsValid}{\void}
150
151 Return {\tt TRUE} if this is a valid compiled regular expression, {\tt FALSE}
152 otherwise.
153
154 \membersection{wxRegEx::GetMatch}\label{wxregexgetmatch}
155
156 \constfunc{bool}{GetMatch}{\param{size\_t* }{start}, \param{size\_t* }{len}, \param{size\_t }{index = 0}}
157
158 Get the start index and the length of the match of the expression
159 (if {\it index} is $0$) or a bracketed subexpression ({\it index} different
160 from $0$).
161
162 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
163 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
164 \helpref{Compile()}{wxregexcompile}.
165
166 Returns {\tt FALSE} if no match or if an error occured.
167
168 \constfunc{wxString}{GetMatch}{\param{const wxString\& }{text}, \param{size\_t }{index = 0}}
169
170 Returns the part of string corresponding to the match where {\it index} is
171 interpreted as above. Empty string is returned if match failed
172
173 May only be called after successful call to \helpref{Matches()}{wxregexmatches}
174 and only if {\tt wxRE\_NOSUB} was {\bf not} used in
175 \helpref{Compile()}{wxregexcompile}.
176
177 \membersection{wxRegEx::Matches}\label{wxregexmatches}
178
179 \constfunc{bool}{Matches}{\param{const wxChar* }{text}, \param{int }{flags = 0}}
180
181 Matches the precompiled regular expression against the string {\it text},
182 returns {\tt TRUE} if matches and {\tt FALSE} otherwise.
183
184 Flags may be combination of {\tt wxRE\_NOTBOL} and {\tt wxRE\_NOTEOL}.
185
186 May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
187
188 \membersection{wxRegEx::Replace}\label{wxregexreplace}
189
190 \constfunc{int}{Replace}{\param{wxString* }{text}, \param{const wxString\& }{replacement}, \param{size\_t }{maxMatches = 0}}
191
192 Replaces the current regular expression in the string pointed to by
193 {\it text}, with the text in {\it replacement} and return number of matches
194 replaced (maybe $0$ if none found) or $-1$ on error.
195
196 The replacement text may contain back references {\tt $\backslash$number} which will be
197 replaced with the value of the corresponding subexpression in the
198 pattern match. {\tt $\backslash$0} corresponds to the entire match and {\tt \&} is a
199 synonym for it. Backslash may be used to quote itself or {\tt \&} character.
200
201 {\it maxMatches} may be used to limit the number of replacements made, setting
202 it to $1$, for example, will only replace first occurence (if any) of the
203 pattern in the text while default value of $0$ means replace all.
204
205 \membersection{wxRegEx::ReplaceAll}\label{wxregexreplaceall}
206
207 \constfunc{int}{ReplaceAll}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
208
209 Replace all occurences: this is actually a synonym for
210 \helpref{Replace()}{wxregexreplace}.
211
212 \wxheading{See also}
213
214 \helpref{ReplaceFirst}{wxregexreplacefirst}
215
216 \membersection{wxRegEx::ReplaceFirst}\label{wxregexreplacefirst}
217
218 \constfunc{int}{ReplaceFirst}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
219
220 Replace the first occurence.
221
222 \wxheading{See also}
223
224 \helpref{Replace}{wxregexreplace}
225