]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/regex.tex
Updated configure and aclocal.m4 for new 0.1.8 Bakefile on account of
[wxWidgets.git] / docs / latex / wx / regex.tex
CommitLineData
11ec1f16
VZ
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
8795498c 9%% License: wxWindows license
11ec1f16
VZ
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxRegEx}}\label{wxregex}
13
0aa7fa9a
VS
14wxRegEx represents a regular expression. This class provides support
15for regular expressions matching and also replacement.
11ec1f16 16
0aa7fa9a
VS
17It is built on top of either the system library (if it has support
18for POSIX regular expressions - which is the case of the most modern
19Unices) or uses the built in Henry Spencer's library. Henry Spencer
20would appreciate being given credit in the documentation of software
21which uses his library, but that is not a requirement.
22
23Regular expressions, as defined by POSIX, come in two flavours: {\it extended}
24and {\it basic}. The builtin library also adds a third flavour
25of expression \helpref{advanced}{wxresyn}, which is not available
26when using the system library.
27
28Unicode is fully supported only when using the builtin library.
29When using the system library in Unicode mode, the expressions and data
30are translated to the default 8-bit encoding before being passed to
31the library.
32
33On platforms where a system library is available, the default is to use
34the builtin library for Unicode builds, and the system library otherwise.
35It is possible to use the other if preferred by selecting it when building
fc2171bd 36the wxWidgets.
11ec1f16
VZ
37
38\wxheading{Derived from}
39
40No base class
41
42\wxheading{Data structures}
43
44Flags for regex compilation to be used with \helpref{Compile()}{wxregexcompile}:
5ef298b3 45
11ec1f16
VZ
46\begin{verbatim}
47enum
48{
0aa7fa9a 49 // use extended regex syntax
a43e748a 50 wxRE_EXTENDED = 0,
0aa7fa9a
VS
51
52 // use advanced RE syntax (built-in regex only)
53#ifdef wxHAS_REGEX_ADVANCED
54 wxRE_ADVANCED = 1,
55#endif
11ec1f16
VZ
56
57 // use basic RE syntax
a43e748a 58 wxRE_BASIC = 2,
11ec1f16
VZ
59
60 // ignore case in match
a43e748a 61 wxRE_ICASE = 4,
11ec1f16
VZ
62
63 // only check match, don't set back references
a43e748a 64 wxRE_NOSUB = 8,
11ec1f16
VZ
65
66 // if not set, treat '\n' as an ordinary character, otherwise it is
67 // special: it is not matched by '.' and '^' and '$' always match
a43e748a
GT
68 // after/before it regardless of the setting of wxRE_NOT[BE]OL
69 wxRE_NEWLINE = 16,
11ec1f16
VZ
70
71 // default flags
a43e748a 72 wxRE_DEFAULT = wxRE_EXTENDED
11ec1f16
VZ
73}
74\end{verbatim}
75
76Flags for regex matching to be used with \helpref{Matches()}{wxregexmatches}.
77
78These flags are mainly useful when doing several matches in a long string
7af3ca16 79to prevent erroneous matches for {\tt '\textasciicircum'} and {\tt '\$'}:
5ef298b3 80
11ec1f16
VZ
81\begin{verbatim}
82enum
83{
84 // '^' doesn't match at the start of line
a43e748a 85 wxRE_NOTBOL = 32,
11ec1f16
VZ
86
87 // '$' doesn't match at the end of line
a43e748a 88 wxRE_NOTEOL = 64
11ec1f16
VZ
89}
90\end{verbatim}
91
5ef298b3
VZ
92\wxheading{Examples}
93
94A bad example of processing some text containing email addresses (the example
95is bad because the real email addresses can have more complicated form than
96{\tt user@host.net}):
97
98\begin{verbatim}
99wxString text;
100...
54d50c6e 101wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)");
5ef298b3
VZ
102if ( reEmail.Matches(text) )
103{
104 wxString text = reEmail.GetMatch(email);
105 wxString username = reEmail.GetMatch(email, 1);
54d50c6e 106 if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD?
5ef298b3
VZ
107 {
108 ...
109 }
110}
111
112// or we could do this to hide the email address
54d50c6e 113size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3"));
5ef298b3
VZ
114printf("text now contains %u hidden addresses", count);
115\end{verbatim}
116
0e10e38d
VZ
117\wxheading{Include files}
118
119<wx/regex.h>
120
11ec1f16
VZ
121\latexignore{\rtfignore{\wxheading{Members}}}
122
123\membersection{wxRegEx::wxRegEx}\label{wxregexwxregex}
124
125\func{}{wxRegEx}{\void}
126
127Default ctor: use \helpref{Compile()}{wxregexcompile} later.
128
11ec1f16
VZ
129\func{}{wxRegEx}{\param{const wxString\& }{expr}, \param{int }{flags = wxRE\_DEFAULT}}
130
131Create 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
138dtor 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
cc81d32f 144Compile the string into regular expression, return {\tt true} if ok or {\tt false}
11ec1f16
VZ
145if string has a syntax error.
146
147\membersection{wxRegEx::IsValid}\label{wxregexisvalid}
148
149\constfunc{bool}{IsValid}{\void}
150
cc81d32f 151Return {\tt true} if this is a valid compiled regular expression, {\tt false}
11ec1f16
VZ
152otherwise.
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
158Get 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
160from $0$).
161
162May only be called after successful call to \helpref{Matches()}{wxregexmatches}
163and only if {\tt wxRE\_NOSUB} was {\bf not} used in
164\helpref{Compile()}{wxregexcompile}.
165
cc81d32f 166Returns {\tt false} if no match or if an error occured.
11ec1f16
VZ
167
168\constfunc{wxString}{GetMatch}{\param{const wxString\& }{text}, \param{size\_t }{index = 0}}
169
170Returns the part of string corresponding to the match where {\it index} is
171interpreted as above. Empty string is returned if match failed
172
173May only be called after successful call to \helpref{Matches()}{wxregexmatches}
174and only if {\tt wxRE\_NOSUB} was {\bf not} used in
175\helpref{Compile()}{wxregexcompile}.
176
86b79b93
VS
177\membersection{wxRegEx::GetMatchCount}\label{wxregexgetmatchcount}
178
179\constfunc{size\_t}{GetMatchCount}{\void}
180
181Returns the size of the array of matches, i.e. the number of bracketed
182subexpressions plus one for the expression itself, or $0$ on error.
183
184May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
185and only if {\tt wxRE\_NOSUB} was {\bf not} used.
186
11ec1f16
VZ
187\membersection{wxRegEx::Matches}\label{wxregexmatches}
188
189\constfunc{bool}{Matches}{\param{const wxChar* }{text}, \param{int }{flags = 0}}
190
191Matches the precompiled regular expression against the string {\it text},
cc81d32f 192returns {\tt true} if matches and {\tt false} otherwise.
11ec1f16
VZ
193
194Flags may be combination of {\tt wxRE\_NOTBOL} and {\tt wxRE\_NOTEOL}.
195
196May only be called after successful call to \helpref{Compile()}{wxregexcompile}.
197
198\membersection{wxRegEx::Replace}\label{wxregexreplace}
199
200\constfunc{int}{Replace}{\param{wxString* }{text}, \param{const wxString\& }{replacement}, \param{size\_t }{maxMatches = 0}}
201
202Replaces the current regular expression in the string pointed to by
203{\it text}, with the text in {\it replacement} and return number of matches
204replaced (maybe $0$ if none found) or $-1$ on error.
205
6465d401 206The replacement text may contain back references {\tt $\backslash$number} which will be
11ec1f16 207replaced with the value of the corresponding subexpression in the
6465d401 208pattern match. {\tt $\backslash$0} corresponds to the entire match and {\tt \&} is a
11ec1f16
VZ
209synonym for it. Backslash may be used to quote itself or {\tt \&} character.
210
211{\it maxMatches} may be used to limit the number of replacements made, setting
2edb0bde 212it to $1$, for example, will only replace first occurrence (if any) of the
11ec1f16
VZ
213pattern in the text while default value of $0$ means replace all.
214
215\membersection{wxRegEx::ReplaceAll}\label{wxregexreplaceall}
216
217\constfunc{int}{ReplaceAll}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
218
2edb0bde 219Replace all occurrences: this is actually a synonym for
11ec1f16
VZ
220\helpref{Replace()}{wxregexreplace}.
221
222\wxheading{See also}
223
224\helpref{ReplaceFirst}{wxregexreplacefirst}
225
226\membersection{wxRegEx::ReplaceFirst}\label{wxregexreplacefirst}
227
228\constfunc{int}{ReplaceFirst}{\param{wxString* }{text}, \param{const wxString\& }{replacement}}
229
2edb0bde 230Replace the first occurrence.
11ec1f16
VZ
231
232\wxheading{See also}
233
234\helpref{Replace}{wxregexreplace}
235