wxWidgets 使用 Henry Spencer 为 Tcl 8.2 开发的完全相同的正则表达式引擎。这表示 wxWidgets 支持相同的三种正则表达式风格：Tcl 高端正则表达式、POSIX 扩展正则表达式和 POSIX 基本正则表达式。与 Tcl 不同的是，ERE 而不是功能强大的 ARE 是默认值。wxRegEx::Replace() 方法使用与 Tcl 的 regsub 指令相同的语法作为替换文本。

wxRegEx 类别

若要使用 wxWidgets 正则表达式引擎，您需要实例化 wxRegEx 类别。该类别有两个构造函数。wxRegEx() 会创建一个空的正则表达式对象。在使用对象之前，您必须调用 wxRegEx::Compile()。wxRegEx::IsValid 会传回 false，直到您运行此动作。

wxRegEx(const wxString& expr, int flags = wxRE_EXTENDED) 会创建一个包含已编译正则表达式的 wxRegEx 对象。即使您的正则表达式无效，构造函数仍会创建对象。检查 wxRegEx::IsValid 以确定正则表达式是否已成功编译。

bool wxRegEx::Compile(const wxString& pattern, int flags = wxRE_EXTENDED) 编译正则表达式。您可以在任何 wxRegEx 对象上调用此方法，包括已包含编译正则表达式的对象。这样做只会取代 wxRegEx 对象所包含的正则表达式。将您的正则表达式作为字符串传递，作为第一个参数。第二个参数允许您设置某些比对选项。

若要设置 regex 风格，请指定旗标 wxRE_EXTENDED、wxRE_ADVANCED 或 wxRE_BASIC 之一。如果您指定一种风格，wxRE_EXTENDED 为默认值。我建议您始终指定 wxRE_ADVANCED 旗标。ARE 远比 ERE 强大。每个有效的 ERE 也是有效的 ARE，且会产生相同的结果。使用 ERE 风格的唯一原因是当您的代码必须在未编译「内置」正则表达式函数库（即 Henry Spencer 的代码）的情况下使用 wxWidgets 时。

除了风格之外，您还可以设置其他三个旗标。wxRE_ICASE 使正则表达式不区分大小写。默认值区分大小写。wxRE_NOSUB 使 regex 引擎将所有捕获组视为非截取。这表示您无法在替换文本中使用反向引用，或查找每个捕获组比对的 regex 部分。如果您不会使用这些功能，设置 wxRE_NOSUB 旗标可提升性能。

如 Tcl 区段所述，Henry Spencer 的「ARE」regex 引擎消除了令人困惑的「单行」(?s) 和「多行」(?m) 比对模式，并以同样令人困惑的「不区分换行」(?s)、「部分区分换行」(?p)、「反向部分区分换行」(?w) 和「区分换行比对」(?n) 取代它们。由于 wxRegEx 类别封装 ARE 引擎，因此当您在正则表达式中使用模式修改器时，它支持所有 4 种模式。但 flags 参数只允许您设置两个。

如果您将 wxRE_NEWLINE 加入旗标，您将打开「换行敏感比对」(?n)。在此模式中，点将不比对换行字符 (\n)。插入符号和美元符号将比对字符串中换行字符的前后，以及主旨字符串的开头和结尾。

如果您未设置 wxRE_NEWLINE 旗标，缺省为「非换行敏感」(?s)。在此模式中，点将比对所有字符，包括换行字符 (\n)。插入符号和美元符号将只比对主旨字符串的开头和结尾。请注意，此默认值与 Perl 和地球上其他所有正则表达式引擎的默认值不同。在 Perl 中，缺省情况下，点不比对换行字符，插入符号和美元符号只比对主旨字符串的开头和结尾。在 wxWidgets 中设置此模式的唯一方法是在正则表达式的开头加上(?p)。

将所有内容放在一起，wxRegex(_T("(?p)^[a-z].*$"), wxRE_ADVANCED + wxRE_ICASE) 将检查您的主旨字符串是否包含以字母开头的单行。Perl 中的等效表达式为 m/^[a-z].*$/i。

wxRegEx 状态函数

wxRegEx::IsValid() 在 wxRegEx 对象包含已编译的正则表达式时传回 true。

wxRegEx::GetMatchCount() 的命名相当不恰当。它不会传回 Matches() 找到的比对数。事实上，您可以在 Compile() 之后、调用 Matches 之前，立即调用 GetMatchCount()。 GetMatchCount() 会传回正则表达式中捕获组的数量，再加上整体正则表达式比对的数量。您可以使用此信息来确定您可以在替换文本中使用的反向引用数量，以及您可以传递给 GetMatch() 的最高索引。如果您的正则表达式没有捕获组，GetMatchCount() 会传回 1。在这种情况下，\0 是您可以在替换文本中使用的唯一有效反向引用。

发生错误时，GetMatchCount() 会传回 0。如果 wxRegEx 对象不包含已编译的正则表达式，或者您使用 wxRE_NOSUB 编译它，就会发生这种情况。

寻找和截取比对

如果您想要测试正则表达式是否比对字符串，或截取正则表达式比对的子字符串，您首先需要调用 wxRegEx::Matches() 方法。它有 3 个变体，让您可以传递 wxChar 或 wxString 作为主旨字符串。使用 wxChar 时，您可以将长度指定为第三个参数。如果您不这样做，系统将调用 wxStrLen() 来计算长度。如果您计划逐一循环处理字符串中的所有正则表达式比对，您应该在循环外自行调用 wxStrLen()，并将结果传递给 wxRegEx::Matches()。

bool wxRegEx::Matches(const wxChar* text, int flags = 0) const bool wxRegEx::Matches(const wxChar* text, int flags, size_t len) const bool wxRegEx::Matches(const wxString& text, int flags = 0) const

Matches() 传回 true，表示 regex 与您在 text 参数中传入的主旨字符串全部或部分相符。如果您想设置 regex 是否与整个主旨字符串相符，请将锚点加入您的 regex。

不要将 flags 参数与传递给 Compile() 方法或 wxRegEx() 构造函数的参数混淆。所有风格和比对模式选项只能在编译 regex 时设置。

Matches() 方法只允许两个旗标：wxRE_NOTBOL 和 wxRE_NOTEOL。如果您设置 wxRE_NOTBOL，则 ^ 和 \A 将不会与字符串开头相符。如果您已打开该比对模式，它们仍会在嵌入换行符号后相符。同样地，指定 wxRE_NOTEOL 会告知 $ 和 \Z 不要与字符串结尾相符。

wxRE_NOTBOL 通常用于实作「寻找下一个」常式。wxRegEx 类别未提供此类函数。若要找出字符串中的第二个相符项，您需要调用 wxRegEx::Matches()，并传递第一个相符项后原始主旨字符串的部分。传递 wxRE_NOTBOL 旗标，以表示您已切断所传递字符串的开头。

如果您正在处理大量数据，且您想在读取完整数据前套用 regex，则 wxRE_NOTEOL 可能会很有用。只要您尚未读取完整字符串，请在调用 wxRegEx::Matches() 时传递 wxRE_NOTEOL。在对不完整数据进行「寻找下一个」时，请同时传递 wxRE_NOTBOL 和 wxRE_NOTEOL。

在调用 Matches() 传回 true 之后，且您在未设置 wxRE_NOSUB 旗标的情况下编译 regex，您可以调用 GetMatch() 以取得关于整体 regex 相符项和 regex 中捕获组所相符字符串部分的详细数据。

bool wxRegEx::GetMatch(size_t* start, size_t* len, size_t index = 0) const 截取相符项在主旨字符串中的起始位置和相符项中的字符数。

wxString wxRegEx::GetMatch(const wxString& text, size_t index = 0) const 传回相符的文本。

对于这两个调用，将 index 参数设置为零（或省略它）以取得整体 regex 相符项。设置 1 <= index < GetMatchCount() 以取得正则表达式中捕获组的相符项。若要判断群组的数量，请从左至右计算正则表达式中的打开括号。

搜索和取代

wxRegEx 类别提供三个方法来运行搜索和取代。 Replace() 是运行实际工作的函数。您可以使用 ReplaceAll() 和 ReplaceFirst() 作为更易于阅读的方式来指定 Replace() 的第 3 个参数。

int wxRegEx::ReplaceAll(wxString* text, const wxString& replacement) const 会以 replacement 取代 text 中所有符合正则表达式的部分。

int wxRegEx::ReplaceFirst(wxString* text, const wxString& replacement) const 会以 replacement 取代 text 中符合正则表达式的第一个部分。

int wxRegEx::Replace(wxString* text, const wxString& replacement, size_t maxMatches = 0) const 允许您指定要取代的次数。传递 0 给 maxMatches 或省略它会运行与 ReplaceAll() 相同的动作。设置为 1 会运行与 ReplaceFirst() 相同的动作。传递大于 1 的数字只会取代前 maxMatches 个符合的部分。如果 text 包含的符合部分比您要求的少，则会取代所有符合的部分，而不会触发错误。

这三个调用都会传回实际取代的次数。如果正则表达式无法符合主旨文本，则会传回 0。传回值 -1 表示错误。取代会直接对您传递为第一个参数的 wxString 运行。

wxWidgets 使用与 Tcl 相同的语法作为取代文本。您可以使用 \0 作为整个正则表达式符合部分的占位符，并使用 \1 到 \9 作为符合前九个捕获组之一文本的占位符。您也可以使用 & 作为 \0 的同义字。请注意，& 前面没有反斜线。 & 会以整个正则表达式符合部分取代，而 \& 会以一个字面上的 & 取代。使用 \\ 插入一个字面上的反斜线。您只需要在反斜线后接数字时才需要转义反斜线，以避免组合被视为反向引用。当在 C++ 代码中指定取代文本为字面上的字符串时，您需要将所有反斜线加倍，因为 C++ 编译器也会将反斜线视为转义字符。因此，如果您想用第一个反向引用加上文本 &co 取代符合部分，您需要在 C++ 中将其编码为 _T("\\1\\&co")。

關於正規表示式 » 正規表示式工具和實用程式 » wxWidgets 支援三種正規表示式風格

正規表示式工具

資料庫

本網站的更多內容

wxWidgets 支援三種正規表示式風格

wxWidgets 使用 Henry Spencer 為 Tcl 8.2 開發的完全相同的正規表示式引擎。這表示 wxWidgets 支援相同的三種正規表示式風格：Tcl 進階正規表示式、POSIX 延伸正規表示式和 POSIX 基本正規表示式。與 Tcl 不同的是，ERE 而不是功能強大的 ARE 是預設值。wxRegEx::Replace() 方法使用與 Tcl 的 regsub 指令相同的語法作為替換文字。

wxRegEx 類別

若要使用 wxWidgets 正規表示式引擎，您需要實例化 wxRegEx 類別。該類別有兩個建構函式。wxRegEx() 會建立一個空的正規表示式物件。在使用物件之前，您必須呼叫 wxRegEx::Compile()。wxRegEx::IsValid 會傳回 false，直到您執行此動作。

wxRegEx(const wxString& expr, int flags = wxRE_EXTENDED) 會建立一個包含已編譯正規表示式的 wxRegEx 物件。即使您的正規表示式無效，建構函式仍會建立物件。檢查 wxRegEx::IsValid 以確定正規表示式是否已成功編譯。

bool wxRegEx::Compile(const wxString& pattern, int flags = wxRE_EXTENDED) 編譯正規表示式。您可以在任何 wxRegEx 物件上呼叫此方法，包括已包含編譯正規表示式的物件。這樣做只會取代 wxRegEx 物件所包含的正規表示式。將您的正規表示式作為字串傳遞，作為第一個參數。第二個參數允許您設定某些比對選項。

若要設定 regex 風格，請指定旗標 wxRE_EXTENDED、wxRE_ADVANCED 或 wxRE_BASIC 之一。如果您指定一種風格，wxRE_EXTENDED 為預設值。我建議您始終指定 wxRE_ADVANCED 旗標。ARE 遠比 ERE 強大。每個有效的 ERE 也是有效的 ARE，且會產生相同的結果。使用 ERE 風格的唯一原因是當您的程式碼必須在未編譯「內建」正規表示式函式庫（即 Henry Spencer 的程式碼）的情況下使用 wxWidgets 時。

除了風格之外，您還可以設定其他三個旗標。wxRE_ICASE 使正規表示式不區分大小寫。預設值區分大小寫。wxRE_NOSUB 使 regex 引擎將所有擷取群組視為非擷取。這表示您無法在替換文字中使用反向參照，或查詢每個擷取群組比對的 regex 部分。如果您不會使用這些功能，設定 wxRE_NOSUB 旗標可提升效能。

如 Tcl 區段所述，Henry Spencer 的「ARE」regex 引擎消除了令人困惑的「單行」(?s) 和「多行」(?m) 比對模式，並以同樣令人困惑的「不區分換行」(?s)、「部分區分換行」(?p)、「反向部分區分換行」(?w) 和「區分換行比對」(?n) 取代它們。由於 wxRegEx 類別封裝 ARE 引擎，因此當您在正規表示式中使用模式修改器時，它支援所有 4 種模式。但 flags 參數只允許您設定兩個。

如果您將 wxRE_NEWLINE 加入旗標，您將開啟「換行敏感比對」(?n)。在此模式中，點將不比對換行字元 (\n)。插入符號和美元符號將比對字串中換行字元的前後，以及主旨字串的開頭和結尾。

如果您未設定 wxRE_NEWLINE 旗標，預設為「非換行敏感」(?s)。在此模式中，點將比對所有字元，包括換行字元 (\n)。插入符號和美元符號將只比對主旨字串的開頭和結尾。請注意，此預設值與 Perl 和地球上其他所有正規表示式引擎的預設值不同。在 Perl 中，預設情況下，點不比對換行字元，插入符號和美元符號只比對主旨字串的開頭和結尾。在 wxWidgets 中設定此模式的唯一方法是在正規表示式的開頭加上(?p)。

將所有內容放在一起，wxRegex(_T("(?p)^[a-z].*$"), wxRE_ADVANCED + wxRE_ICASE) 將檢查您的主旨字串是否包含以字母開頭的單行。Perl 中的等效表示式為 m/^[a-z].*$/i。

wxRegEx 狀態函式

wxRegEx::IsValid() 在 wxRegEx 物件包含已編譯的正規表示式時傳回 true。

wxRegEx::GetMatchCount() 的命名相當不恰當。它不會傳回 Matches() 找到的比對數。事實上，您可以在 Compile() 之後、呼叫 Matches 之前，立即呼叫 GetMatchCount()。 GetMatchCount() 會傳回正規表示式中擷取群組的數量，再加上整體正規表示式比對的數量。您可以使用此資訊來確定您可以在替換文字中使用的反向參照數量，以及您可以傳遞給 GetMatch() 的最高索引。如果您的正規表示式沒有擷取群組，GetMatchCount() 會傳回 1。在這種情況下，\0 是您可以在替換文字中使用的唯一有效反向參照。

發生錯誤時，GetMatchCount() 會傳回 0。如果 wxRegEx 物件不包含已編譯的正規表示式，或者您使用 wxRE_NOSUB 編譯它，就會發生這種情況。

尋找和擷取比對

如果您想要測試正規表示式是否比對字串，或擷取正規表示式比對的子字串，您首先需要呼叫 wxRegEx::Matches() 方法。它有 3 個變體，讓您可以傳遞 wxChar 或 wxString 作為主旨字串。使用 wxChar 時，您可以將長度指定為第三個參數。如果您不這樣做，系統將呼叫 wxStrLen() 來計算長度。如果您計畫逐一迴圈處理字串中的所有正規表示式比對，您應該在迴圈外自行呼叫 wxStrLen()，並將結果傳遞給 wxRegEx::Matches()。

Matches() 傳回 true，表示 regex 與您在 text 參數中傳入的主旨字串全部或部分相符。如果您想設定 regex 是否與整個主旨字串相符，請將錨點加入您的 regex。

不要將 flags 參數與傳遞給 Compile() 方法或 wxRegEx() 建構函式的參數混淆。所有風味和比對模式選項只能在編譯 regex 時設定。

Matches() 方法只允許兩個旗標：wxRE_NOTBOL 和 wxRE_NOTEOL。如果您設定 wxRE_NOTBOL，則 ^ 和 \A 將不會與字串開頭相符。如果您已開啟該比對模式，它們仍會在嵌入換行符號後相符。同樣地，指定 wxRE_NOTEOL 會告知 $ 和 \Z 不要與字串結尾相符。

wxRE_NOTBOL 通常用於實作「尋找下一個」常式。wxRegEx 類別未提供此類函式。若要找出字串中的第二個相符項，您需要呼叫 wxRegEx::Matches()，並傳遞第一個相符項後原始主旨字串的部分。傳遞 wxRE_NOTBOL 旗標，以表示您已切斷所傳遞字串的開頭。

如果您正在處理大量資料，且您想在讀取完整資料前套用 regex，則 wxRE_NOTEOL 可能會很有用。只要您尚未讀取完整字串，請在呼叫 wxRegEx::Matches() 時傳遞 wxRE_NOTEOL。在對不完整資料進行「尋找下一個」時，請同時傳遞 wxRE_NOTBOL 和 wxRE_NOTEOL。

在呼叫 Matches() 傳回 true 之後，且您在未設定 wxRE_NOSUB 旗標的情況下編譯 regex，您可以呼叫 GetMatch() 以取得關於整體 regex 相符項和 regex 中擷取群組所相符字串部分的詳細資料。

bool wxRegEx::GetMatch(size_t* start, size_t* len, size_t index = 0) const 擷取相符項在主旨字串中的起始位置和相符項中的字元數。

wxString wxRegEx::GetMatch(const wxString& text, size_t index = 0) const 傳回相符的文字。

對於這兩個呼叫，將 index 參數設定為零（或省略它）以取得整體 regex 相符項。設定 1 <= index < GetMatchCount() 以取得正規表示式中擷取群組的相符項。若要判斷群組的數量，請從左至右計算正規表示式中的開啟括號。

搜尋和取代

wxRegEx 類別提供三個方法來執行搜尋和取代。 Replace() 是執行實際工作的函式。您可以使用 ReplaceAll() 和 ReplaceFirst() 作為更易於閱讀的方式來指定 Replace() 的第 3 個參數。

int wxRegEx::ReplaceAll(wxString* text, const wxString& replacement) const 會以 replacement 取代 text 中所有符合正規表示式的部分。

int wxRegEx::ReplaceFirst(wxString* text, const wxString& replacement) const 會以 replacement 取代 text 中符合正規表示式的第一個部分。

int wxRegEx::Replace(wxString* text, const wxString& replacement, size_t maxMatches = 0) const 允許您指定要取代的次數。傳遞 0 給 maxMatches 或省略它會執行與 ReplaceAll() 相同的動作。設定為 1 會執行與 ReplaceFirst() 相同的動作。傳遞大於 1 的數字只會取代前 maxMatches 個符合的部分。如果 text 包含的符合部分比您要求的少，則會取代所有符合的部分，而不會觸發錯誤。

這三個呼叫都會傳回實際取代的次數。如果正規表示式無法符合主旨文字，則會傳回 0。傳回值 -1 表示錯誤。取代會直接對您傳遞為第一個參數的 wxString 執行。

wxWidgets 使用與 Tcl 相同的語法作為取代文字。您可以使用 \0 作為整個正規表示式符合部分的佔位符，並使用 \1 到 \9 作為符合前九個擷取群組之一文字的佔位符。您也可以使用 & 作為 \0 的同義字。請注意，& 前面沒有反斜線。 & 會以整個正規表示式符合部分取代，而 \& 會以一個字面上的 & 取代。使用 \\ 插入一個字面上的反斜線。您只需要在反斜線後接數字時才需要跳脫反斜線，以避免組合被視為反向參照。當在 C++ 程式碼中指定取代文字為字面上的字串時，您需要將所有反斜線加倍，因為 C++ 編譯器也會將反斜線視為跳脫字元。因此，如果您想用第一個反向參照加上文字 &co 取代符合部分，您需要在 C++ 中將其編碼為 _T("\\1\\&co")。

About Regular Expressions » Tools and Utilities for Regular Expressions » wxWidgets Supports Three Regular Expression Flavors

Regex Tools

grep

Languages & Libraries

Databases

wxWidgets Supports Three Regular Expression Flavors

wxWidgets uses the exact same regular expression engine that was developed by Henry Spencer for Tcl 8.2. This means that wxWidgets supports the same three regular expressions flavors: Tcl Advanced Regular Expressions, POSIX Extended Regular Expressions and POSIX Basic Regular Expressions. Unlike in Tcl, EREs rather than the far more powerful AREs are the default. The wxRegEx::Replace() method uses the same syntax for the replacement text as Tcl’s regsub command.

The wxRegEx Class

To use the wxWidgets regex engine, you need to instantiate the wxRegEx class. The class has two constructors. wxRegEx() creates an empty regex object. Before you can use the object, you have to call wxRegEx::Compile(). wxRegEx::IsValid will return false until you do.

wxRegEx(const wxString& expr, int flags = wxRE_EXTENDED) creates a wxRegEx object with a compiled regular expression. The constructor will always create the object, even if your regular expression is invalid. Check wxRegEx::IsValid to determine if the regular expression was compiled successfully.

bool wxRegEx::Compile(const wxString& pattern, int flags = wxRE_EXTENDED) 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.

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).

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 capturing groups 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.

As discussed in the Tcl section, Henry Spencer’s “ARE” regex engine did away with the confusing “single line” (?s) and “multi line” (?m) matching modes, replacing them with the equally confusing “non-newline-sensitive” (?s), “partial newline-sensitive” (?p), “inverse partial newline-sensitive” (?w) and “newline-sensitive matching” (?n). 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 flags parameter only allows you to set two.

If you add wxRE_NEWLINE to the flags, you’re turning on “newline-sensitive matching” (?n). In this mode, the dot will not match newline characters (\n). The caret and dollar will match after and before newlines in the string, as well as at the start and end of the subject string.

If you don’t set the wxRE_NEWLINE flag, the default is “non-newline-sensitive” (?s). In this mode, the dot will match all characters, including newline characters (\n). The caret and dollar 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 (?p) at the start of your regex.

Putting it all together, wxRegex(_T("(?p)^[a-z].*$"), wxRE_ADVANCED + wxRE_ICASE) will check if your subject string consists of a single line that starts with a letter. The equivalent in Perl is m/^[a-z].*$/i.

wxRegEx Status Functions

wxRegEx::IsValid() returns true when the wxRegEx object holds a compiled regular expression.

wxRegEx::GetMatchCount() is rather poorly named. It does not return the number of matches found by Matches(). In fact, you can call GetMatchCount() right after Compile(), before you call Matches. GetMatchCount() it returns the number of capturing groups 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 GetMatch(). If your regex has no capturing groups, GetMatchCount() returns 1. In that case, \0 is the only valid backreference you can use in the replacement text.

GetMatchCount() 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.

Finding and Extracting Matches

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 wxRegEx::Matches() 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().

Matches() returns true if the regex matches all or part of the subject string that you passed in the text parameter. Add anchors to your regex if you want to set whether the regex matches the whole subject string.

Do not confuse the flags parameter with the one you pass to the Compile() method or the wxRegEx() constructor. All the flavor and matching mode options can only be set when compiling the regex.

The Matches() method allows only two flags: wxRE_NOTBOL and wxRE_NOTEOL. If you set wxRE_NOTBOL, then ^ and \A 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 $ and \Z not to match at the end of the string.

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.

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.

After a call to Matches() returns true, and you compiled your regex without the wxRE_NOSUB flag, you can call GetMatch() to get details about the overall regex match, and the parts of the string matched by the capturing groups in your regex.

bool wxRegEx::GetMatch(size_t* start, size_t* len, size_t index = 0) const retrieves the starting position of the match in the subject string, and the number of characters in the match.

wxString wxRegEx::GetMatch(const wxString& text, size_t index = 0) const returns the text that was matched.

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.

Searching and Replacing

The wxRegEx class offers three methods to do a search-and-replace. Replace() is the method that does the actual work. You can use ReplaceAll() and ReplaceFirst() as more readable ways to specify the 3rd parameter to Replace().

int wxRegEx::ReplaceAll(wxString* text, const wxString& replacement) const replaces all regex matches in text with replacement.

int wxRegEx::ReplaceFirst(wxString* text, const wxString& replacement) const replaces the first match of the regular expression in text with replacement.

int wxRegEx::Replace(wxString* text, const wxString& replacement, size_t maxMatches = 0) const allows you to specify how many replacements will be made. Passing 0 for maxMatches or omitting it does the same as ReplaceAll(). Setting it to 1 does the same as ReplaceFirst(). Pass a number greater than 1 to replace only the first maxMatches matches. If text contains fewer matches than you’ve asked for, then all matches will be replaced, without triggering an error.

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.

wxWidgets uses the same syntax as Tcl for the replacement text. You can use \0 as a placeholder for the whole regex match, and \1 through \9 for the text matched by one of the first nine capturing groups. You can also use & as a synonym of \0. Note that there’s no backslash in front of the ampersand. & is substituted with the whole regex match, while \& is substituted with a literal ampersand. Use \\ 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 &co, you’ll need to code that in C++ as _T("\\1\\&co").