CINXE.COM
wxRegEx Class - wxWidgets Regular Expressions
<!DOCTYPE html> <html lang="en"><head><meta charset="utf-8"><link rel=canonical href='https://https://www.regular-expressions.info//wxwidgets.html'><title>wxRegEx Class - wxWidgets Regular Expressions</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="author" content="Jan Goyvaerts"> <meta name="description" content="Complete explanation of the wxRegEx class that adds support for advanced regular expressions to the wxWidgets library"> <meta name="keywords" content=""> <link rel=stylesheet href="regex.css" type="text/css"><script src="theme.js" type="text/javascript"></script><link rel="alternate" type="application/rss+xml" title="New at Regular-Expressions.info" href="updates.xml"> </head> <body bgcolor=white text=black> <div id=top></div> <div id=btntop><div id=btngrid><a href="quickstart.html" target="_top"><div>Quick Start</div></a><a href="tutorial.html" target="_top"><div>Tutorial</div></a><a href="tools.html" target="_top"><div>Tools & Languages</div></a><a href="examples.html" target="_top"><div>Examples</div></a><a href="refflavors.html" target="_top"><div>Reference</div></a><a href="books.html" target="_top"><div>Book Reviews</div></a></div></div> <div id=contents><div id=side> <TABLE CLASS=side CELLSPACING=0 CELLPADDING=4><TR><TD CLASS=sideheader>Regex Tools</TD></TR><TR><TD><A HREF="grep.html" TARGET=_top>grep</A></TD></TR><TR><TD><A HREF="powergrep.html" TARGET=_top>PowerGREP</A></TD></TR><TR><TD><A HREF="regexbuddy.html" TARGET=_top>RegexBuddy</A></TD></TR><TR><TD><A HREF="regexmagic.html" TARGET=_top>RegexMagic</A></TD></TR> </TABLE><TABLE CLASS=side CELLSPACING=0 CELLPADDING=4><TR><TD CLASS=sideheader>General Applications</TD></TR><TR><TD><A HREF="editpadlite.html" TARGET=_top>EditPad Lite</A></TD></TR><TR><TD><A HREF="editpadpro.html" TARGET=_top>EditPad Pro</A></TD></TR> </TABLE><TABLE CLASS=side CELLSPACING=0 CELLPADDING=4><TR><TD CLASS=sideheader>Languages & Libraries</TD></TR><TR><TD><A HREF="boost.html" TARGET=_top>Boost</A></TD></TR><TR><TD><A HREF="delphi.html" TARGET=_top>Delphi</A></TD></TR><TR><TD><A HREF="gnu.html" TARGET=_top>GNU (Linux)</A></TD></TR><TR><TD><A HREF="groovy.html" TARGET=_top>Groovy</A></TD></TR><TR><TD><A HREF="java.html" TARGET=_top>Java</A></TD></TR><TR><TD><A HREF="javascript.html" TARGET=_top>JavaScript</A></TD></TR><TR><TD><A HREF="dotnet.html" TARGET=_top>.NET</A></TD></TR><TR><TD><A HREF="pcre.html" TARGET=_top>PCRE (C/C++)</A></TD></TR><TR><TD><A HREF="pcre2.html" TARGET=_top>PCRE2 (C/C++)</A></TD></TR><TR><TD><A HREF="perl.html" TARGET=_top>Perl</A></TD></TR><TR><TD><A HREF="php.html" TARGET=_top>PHP</A></TD></TR><TR><TD><A HREF="posix.html" TARGET=_top>POSIX</A></TD></TR><TR><TD><A HREF="powershell.html" TARGET=_top>PowerShell</A></TD></TR><TR><TD><A HREF="python.html" TARGET=_top>Python</A></TD></TR><TR><TD><A HREF="rlanguage.html" TARGET=_top>R</A></TD></TR><TR><TD><A HREF="ruby.html" TARGET=_top>Ruby</A></TD></TR><TR><TD><A HREF="stdregex.html" TARGET=_top>std::regex</A></TD></TR><TR><TD><A HREF="tcl.html" TARGET=_top>Tcl</A></TD></TR><TR><TD><A HREF="vbscript.html" TARGET=_top>VBScript</A></TD></TR><TR><TD><A HREF="vb.html" TARGET=_top>Visual Basic 6</A></TD></TR><TR><TD><A HREF="wxwidgets.html" TARGET=_top>wxWidgets</A></TD></TR><TR><TD><A HREF="xml.html" TARGET=_top>XML Schema</A></TD></TR><TR><TD><A HREF="realbasic.html" TARGET=_top>Xojo</A></TD></TR><TR><TD><A HREF="xpath.html" TARGET=_top>XQuery & XPath</A></TD></TR><TR><TD><A HREF="xregexp.html" TARGET=_top>XRegExp</A></TD></TR> </TABLE><TABLE CLASS=side CELLSPACING=0 CELLPADDING=4><TR><TD CLASS=sideheader>Databases</TD></TR><TR><TD><A HREF="mysql.html" TARGET=_top>MySQL</A></TD></TR><TR><TD><A HREF="oracle.html" TARGET=_top>Oracle</A></TD></TR><TR><TD><A HREF="postgresql.html" TARGET=_top>PostgreSQL</A></TD></TR> </TABLE><TABLE CLASS=side CELLSPACING=0 CELLPADDING=4><TR><TD CLASS=sideheader>More on This Site</TD></TR><TR><TD><A HREF="index.html" TARGET=_top>Introduction</A></TD></TR><TR><TD><A HREF="quickstart.html" TARGET=_top>Regular Expressions Quick Start</A></TD></TR><TR><TD><A HREF="tutorial.html" TARGET=_top>Regular Expressions Tutorial</A></TD></TR><TR><TD><A HREF="replacetutorial.html" TARGET=_top>Replacement Strings Tutorial</A></TD></TR><TR><TD><A HREF="tools.html" TARGET=_top>Applications and Languages</A></TD></TR><TR><TD><A HREF="examples.html" TARGET=_top>Regular Expressions Examples</A></TD></TR><TR><TD><A HREF="refflavors.html" TARGET=_top>Regular Expressions Reference</A></TD></TR><TR><TD><A HREF="refreplace.html" TARGET=_top>Replacement Strings Reference</A></TD></TR><TR><TD><A HREF="books.html" TARGET=_top>Book Reviews</A></TD></TR><TR><TD><A HREF="print.html" TARGET=_top>Printable PDF</A></TD></TR><TR><TD><A HREF="about.html" TARGET=_top>About This Site</A></TD></TR><TR><TD><A HREF="updates.html" TARGET=_top>RSS Feed & Blog</A></TD></TR></TABLE></DIV><div class=bodytext><div class=topad><A HREF="https://www.regexbuddy.com/wxwidgets.html" TARGET="_top"><picture><source media="(max-width: 370px)" srcset="ads/320/rxbwxwidgets100.png 1x, ads/320/rxbwxwidgets150.png 1.5x, ads/320/rxbwxwidgets200.png 2x, ads/320/rxbwxwidgets250.png 2.5x, ads/320/rxbwxwidgets300.png 3x, ads/320/rxbwxwidgets350.png 3.5x, ads/320/rxbwxwidgets400.png 4x"><source media="(max-width: 500px)" srcset="ads/360/rxbwxwidgets100.png 1x, ads/360/rxbwxwidgets150.png 1.5x, ads/360/rxbwxwidgets200.png 2x, ads/360/rxbwxwidgets250.png 2.5x, ads/360/rxbwxwidgets300.png 3x, ads/360/rxbwxwidgets350.png 3.5x, ads/360/rxbwxwidgets400.png 4x"><source media="(max-width: 660px)" srcset="ads/480/rxbwxwidgets100.png 1x, ads/480/rxbwxwidgets150.png 1.5x, ads/480/rxbwxwidgets200.png 2x, ads/480/rxbwxwidgets250.png 2.5x, ads/480/rxbwxwidgets300.png 3x, ads/480/rxbwxwidgets350.png 3.5x, ads/480/rxbwxwidgets400.png 4x"><source media="(max-width: 747px)" srcset="ads/640/rxbwxwidgets100.png 1x, ads/640/rxbwxwidgets150.png 1.5x, ads/640/rxbwxwidgets200.png 2x, ads/640/rxbwxwidgets250.png 2.5x, ads/640/rxbwxwidgets300.png 3x, ads/640/rxbwxwidgets350.png 3.5x, ads/640/rxbwxwidgets400.png 4x"><img src="ads/728/rxbwxwidgets100.png" srcset="ads/728/rxbwxwidgets100.png 1x, ads/728/rxbwxwidgets125.png 1.25x, ads/728/rxbwxwidgets150.png 1.5x, ads/728/rxbwxwidgets175.png 1.75x, ads/728/rxbwxwidgets200.png 2x, ads/728/rxbwxwidgets250.png 2.5x, ads/728/rxbwxwidgets300.png 3x, ads/728/rxbwxwidgets350.png 3.5x, ads/728/rxbwxwidgets400.png 4x" alt="RegexBuddy—The best regex editor and tester for wxWidgets developers!"></picture></A></div> <div class=bulb><h1>wxWidgets Supports Three Regular Expression Flavors</h1><script type="text/javascript">showbulb();</script></div> <p>wxWidgets uses the exact same regular expression engine that was developed by Henry Spencer for <A HREF="tcl.html" TARGET="_top">Tcl 8.2</A>. This means that wxWidgets supports the same three regular expressions flavors: <A HREF="tcl.html" TARGET="_top">Tcl Advanced Regular Expressions</A>, <a href="posix.html#ere">POSIX Extended Regular Expressions</a> and <a href="posix.html#bre">POSIX Basic Regular Expressions</a>. Unlike in Tcl, EREs rather than the far more powerful AREs are the default. The <tt>wxRegEx::Replace()</tt> method uses the same syntax for the replacement text as Tcl’s <tt>regsub</tt> command.</p> <h2>The wxRegEx Class</h2> <p>To use the wxWidgets regex engine, you need to instantiate the wxRegEx class. The class has two constructors. <tt><b>wxRegEx()</b></tt> creates an empty regex object. Before you can use the object, you have to call <tt>wxRegEx::Compile()</tt>. <tt>wxRegEx::IsValid</tt> will return false until you do.</p> <p><tt><b>wxRegEx</b>(const wxString& expr, int flags = wxRE_EXTENDED)</tt> creates a wxRegEx object with a compiled regular expression. The constructor will always create the object, even if your regular expression is invalid. Check <tt>wxRegEx::IsValid</tt> to determine if the regular expression was compiled successfully.</p> <p><tt>bool <b>wxRegEx::Compile</b>(const wxString& pattern, int flags = wxRE_EXTENDED)</tt> compiles a regular expression. You can call this method on any wxRegEx object, including one that already holds a compiled regular expression. Doing so will simply replace the regular expression held by the wxRegEx object. Pass your regular expression as a string as the first parameter. The second parameter allows you to set certain matching options.</p> <p>To set the regex flavor, specify one of the flags wxRE_EXTENDED, wxRE_ADVANCED or wxRE_BASIC. If you specify a flavor, wxRE_EXTENDED is the default. I recommend you always specify the wxRE_ADVANCED flag. AREs are far more powerful than EREs. Every valid ERE is also a valid ARE, and will give identical results. The only reason to use the ERE flavor is when your code has to work when wxWidgets is compiled without the “built-in” regular expression library (i.e. Henry Spencer’s code).</p> <p>You can set three other flags in addition to the flavor. wxRE_ICASE makes the regular expression case insensitive. The default is case sensitive. wxRE_NOSUB makes the regex engine treat all <A HREF="brackets.html" TARGET="_top">capturing groups</A> as non-capturing. This means you won’t be able to use backreferences in the replacement text, or query the part of the regex matched by each capturing group. If you won’t be using these anyway, setting the wxRE_NOSUB flag improves performance.</p> <p>As discussed in the <A HREF="tcl.html" TARGET="_top">Tcl</A> section, Henry Spencer’s “ARE” regex engine did away with the confusing “single line” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">s</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT> and “multi line” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">m</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT> matching modes, replacing them with the equally confusing “non-newline-sensitive” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">s</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT>, “partial newline-sensitive” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">p</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT>, “inverse partial newline-sensitive” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">w</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT> and “newline-sensitive matching” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">n</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT>. Since the wxRegEx class encapsulates the ARE engine, it supports all 4 modes when you use the mode modifiers inside the regular expression. But the <tt>flags</tt> parameter only allows you to set two.</p> <p>If you add wxRE_NEWLINE to the flags, you’re turning on “newline-sensitive matching” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">n</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT>. In this mode, the <A HREF="dot.html" TARGET="_top">dot</A> will not match newline characters (\n). The <A HREF="anchors.html" TARGET="_top">caret and dollar</A> will match after and before newlines in the string, as well as at the start and end of the subject string.</p> <p>If you don’t set the wxRE_NEWLINE flag, the default is “non-newline-sensitive” <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">s</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT>. In this mode, the <A HREF="dot.html" TARGET="_top">dot</A> will match all characters, including newline characters (\n). The <A HREF="anchors.html" TARGET="_top">caret and dollar</A> will match only at the start and end of the subject string. Note that this default is different from the default in Perl and every other regex engine on the planet. In Perl, by default, the dot does not match newline characters, and the caret and dollar only match at the start and end of the subject string. The only way to set this mode in wxWidgets is to put <TT CLASS=syntax><SPAN CLASS="regexmeta">(?</SPAN><SPAN CLASS="regexmeta">p</SPAN><SPAN CLASS="regexmeta">)</SPAN></TT> at the start of your regex.</p> <p>Putting it all together, <tt>wxRegex(_T("(?p)^[a-z].*$"), wxRE_ADVANCED + wxRE_ICASE)</tt> will check if your subject string consists of a single line that starts with a letter. The equivalent in Perl is <tt>m/^[a-z].*$/i</tt>.</p> <h2>wxRegEx Status Functions</h2> <p><tt>wxRegEx::<b>IsValid()</b></tt> returns true when the wxRegEx object holds a compiled regular expression.</p> <p><tt>wxRegEx::<b>GetMatchCount()</b></tt> is rather poorly named. It does not return the number of matches found by <tt>Matches()</tt>. In fact, you can call <tt>GetMatchCount()</tt> right after <tt>Compile()</tt>, before you call <tt>Matches</tt>. <tt>GetMatchCount()</tt> it returns the number of <A HREF="brackets.html" TARGET="_top">capturing groups</A> in your regular expression, plus one for the overall regex match. You can use this to determine the number of backreferences you can use the replacement text, and the highest index you can pass to <tt>GetMatch()</tt>. If your regex has no capturing groups, <tt>GetMatchCount()</tt> returns 1. In that case, <tt>\0</tt> is the only valid backreference you can use in the replacement text.</p> <p><tt>GetMatchCount()</tt> returns 0 in case of an error. This will happen if the wxRegEx object does not hold a compiled regular expression, or if you compiled it with wxRE_NOSUB.</p> <h2>Finding and Extracting Matches</h2> <p>If you want to test whether a regex matches a string, or extract the substring matched by the regex, you first need to call the <tt>wxRegEx::<b>Matches()</b></tt> method. It has 3 variants, allowing you to pass wxChar or wxString as the subject string. When using a wxChar, you can specify the length as a third parameter. If you don’t, wxStrLen() will be called to compute the length. If you plan to loop over all regex matches in a string, you should call wxStrLen() yourself outside the loop and pass the result to wxRegEx::Matches().</p> <p><tt class=code>bool wxRegEx::<b>Matches</b>(const wxChar* text, int flags = 0) const<br> bool wxRegEx::<b>Matches</b>(const wxChar* text, int flags, size_t len) const<br> bool wxRegEx::<b>Matches</b>(const wxString& text, int flags = 0) const</tt></p> <p>Matches() returns true if the regex matches all or part of the subject string that you passed in the <tt>text</tt> parameter. Add <A HREF="anchors.html" TARGET="_top">anchors</A> to your regex if you want to set whether the regex matches the whole subject string.</p> <p>Do not confuse the <tt>flags</tt> parameter with the one you pass to the <tt>Compile()</tt> method or the <tt>wxRegEx()</tt> constructor. All the flavor and matching mode options can only be set when compiling the regex.</p> <p>The Matches() method allows only two flags: wxRE_NOTBOL and wxRE_NOTEOL. If you set wxRE_NOTBOL, then <TT CLASS=syntax><SPAN CLASS="regexspecial">^</SPAN></TT> and <TT CLASS=syntax><SPAN CLASS="regexspecial">\A</SPAN></TT> will not match at the start of the string. They will still match after embedded newlines if you turned on that matching mode. Likewise, specifying wxRE_NOTEOL tells <TT CLASS=syntax><SPAN CLASS="regexspecial">$</SPAN></TT> and <TT CLASS=syntax><SPAN CLASS="regexspecial">\Z</SPAN></TT> not to match at the end of the string.</p> <p>wxRE_NOTBOL is commonly used to implement a “find next” routine. The wxRegEx class does not provide such a function. To find the second match in the string, you’ll need to call wxRegEx::Matches() and pass it the part of the original subject string after the first match. Pass the wxRE_NOTBOL flag to indicate that you’ve cut off the start of the string you’re passing.</p> <p>wxRE_NOTEOL can be useful if you’re processing a large set of data, and you want to apply the regex before you’ve read the whole data. Pass wxRE_NOTEOL while calling wxRegEx::Matches() as long as you haven’t read the entire string yet. Pass both wxRE_NOTBOL and wxRE_NOTEOL when doing a “find next” on incomplete data.</p> <p>After a call to <tt>Matches()</tt> returns true, and you compiled your regex without the wxRE_NOSUB flag, you can call <tt>GetMatch()</tt> to get details about the overall regex match, and the parts of the string matched by the <A HREF="brackets.html" TARGET="_top">capturing groups</A> in your regex.</p> <p><tt>bool wxRegEx::<b>GetMatch</b>(size_t* start, size_t* len, size_t index = 0) const</tt> retrieves the starting position of the match in the subject string, and the number of characters in the match.</p> <p><tt>wxString wxRegEx::<b>GetMatch</b>(const wxString& text, size_t index = 0) const</tt> returns the text that was matched.</p> <p>For both calls, set the index parameter to zero (or omit it) to get the overall regex match. Set 1 <= index < GetMatchCount() to get the match of a capturing group in your regular expression. To determine the number of a group, count the opening brackets in your regular expression from left to right.</p> <h2>Searching and Replacing</h2> <p>The wxRegEx class offers three methods to do a search-and-replace. <tt>Replace()</tt> is the method that does the actual work. You can use <tt>ReplaceAll()</tt> and <tt>ReplaceFirst()</tt> as more readable ways to specify the 3rd parameter to <tt>Replace()</tt>.</p> <p><tt>int wxRegEx::<b>ReplaceAll</b>(wxString* text, const wxString& replacement) const</tt> replaces all regex matches in <tt>text</tt> with <tt>replacement</tt>.</p> <p><tt>int wxRegEx::<b>ReplaceFirst</b>(wxString* text, const wxString& replacement) const</tt> replaces the first match of the regular expression in <tt>text</tt> with <tt>replacement</tt>.</p> <p><tt>int wxRegEx::<b>Replace</b>(wxString* text, const wxString& replacement, size_t maxMatches = 0) const</tt> allows you to specify how many replacements will be made. Passing 0 for <tt>maxMatches</tt> or omitting it does the same as <tt>ReplaceAll()</tt>. Setting it to 1 does the same as <tt>ReplaceFirst()</tt>. Pass a number greater than 1 to replace only the first maxMatches matches. If <tt>text</tt> contains fewer matches than you’ve asked for, then all matches will be replaced, without triggering an error.</p> <p>All three calls return the actual number of replacements made. They return zero if the regex failed to match the subject text. A return value of -1 indicates an error. The replacements are made directly to the wxString that you pass as the first parameter.</p> <p>wxWidgets uses the same syntax as <A HREF="tcl.html" TARGET="_top">Tcl</A> for the replacement text. You can use <tt>\0</tt> as a placeholder for the whole regex match, and <tt>\1</tt> through <tt>\9</tt> for the text matched by one of the first nine <A HREF="brackets.html" TARGET="_top">capturing groups</A>. You can also use <tt>&</tt> as a synonym of <tt>\0</tt>. Note that there’s no backslash in front of the ampersand. <tt>&</tt> is substituted with the whole regex match, while <tt>\&</tt> is substituted with a literal ampersand. Use <tt>\\</tt> to insert a literal backslash. You only need to escape backslashes if they’re followed by a digit, to prevent the combination from being seen as a backreference. When specifying the replacement text as a literal string in C++ code, you need to double up all the backslashes, as the C++ compiler also treats backslashes as escape characters. So if you want to replace the match with the first backreference followed by the text <tt class=string>&co</tt>, you’ll need to code that in C++ as <tt>_T("\\1\\&co")</tt>.</p><div id=cntmobi><p>| <a href='quickstart.html'>Quick Start</a> | <a href='tutorial.html'>Tutorial</a> | <a href='tools.html'>Tools & Languages</a> | <a href='examples.html'>Examples</a> | <a href='refflavors.html'>Reference</a> | <a href='books.html'>Book Reviews</a> |</p><p>| <a href='grep.html'>grep</a> | <a href='powergrep.html'>PowerGREP</a> | <a href='regexbuddy.html'>RegexBuddy</a> | <a href='regexmagic.html'>RegexMagic</a> |</p><p>| <a href='editpadlite.html'>EditPad Lite</a> | <a href='editpadpro.html'>EditPad Pro</a> |</p><p>| <a href='boost.html'>Boost</a> | <a href='delphi.html'>Delphi</a> | <a href='gnu.html'>GNU (Linux)</a> | <a href='groovy.html'>Groovy</a> | <a href='java.html'>Java</a> | <a href='javascript.html'>JavaScript</a> | <a href='dotnet.html'>.NET</a> | <a href='pcre.html'>PCRE (C/C++)</a> | <a href='pcre2.html'>PCRE2 (C/C++)</a> | <a href='perl.html'>Perl</a> | <a href='php.html'>PHP</a> | <a href='posix.html'>POSIX</a> | <a href='powershell.html'>PowerShell</a> | <a href='python.html'>Python</a> | <a href='rlanguage.html'>R</a> | <a href='ruby.html'>Ruby</a> | <a href='stdregex.html'>std::regex</a> | <a href='tcl.html'>Tcl</a> | <a href='vbscript.html'>VBScript</a> | <a href='vb.html'>Visual Basic 6</a> | <a href='wxwidgets.html'>wxWidgets</a> | <a href='xml.html'>XML Schema</a> | <a href='realbasic.html'>Xojo</a> | <a href='xpath.html'>XQuery & XPath</a> | <a href='xregexp.html'>XRegExp</a> |</p><p>| <a href='mysql.html'>MySQL</a> | <a href='oracle.html'>Oracle</a> | <a href='postgresql.html'>PostgreSQL</a> |</p></div> <div id=copyright> <P CLASS=copyright>Page URL: <A HREF="https://www.regular-expressions.info/wxwidgets.html" TARGET="_top">https://www.regular-expressions.info/wxwidgets.html</A><BR> Page last updated: 24 August 2021<BR> Site last updated: 06 November 2024<BR> Copyright © 2003-2024 Jan Goyvaerts. All rights reserved.</P> </div> </div> </div> </body></html>