wxRegEx

wxRegEx represents a regular expression. This class provides support for regular expressions matching and also replacement.

It is built on top of either the system library (if it has support for POSIX regular expressions - which is the case of the most modern Unices) or uses the built in Henry Spencer's library. Henry Spencer would appreciate being given credit in the documentation of software which uses his library, but that is not a requirement.

Regular expressions, as defined by POSIX, come in two flavours: extended and basic. The builtin library also adds a third flavour of expression advanced, which is not available when using the system library.

Unicode is fully supported only when using the builtin library. When using the system library in Unicode mode, the expressions and data are translated to the default 8-bit encoding before being passed to the library.

On platforms where a system library is available, the default is to use the builtin library for Unicode builds, and the system library otherwise. It is possible to use the other if preferred by selecting it when building the wxWidgets.

Derived from

No base class

Data structures

Flags for regex compilation to be used with Compile():

enum
{
    // use extended regex syntax
    wxRE_EXTENDED = 0,
    
    // use advanced RE syntax (built-in regex only)
#ifdef wxHAS_REGEX_ADVANCED
    wxRE_ADVANCED = 1,
#endif

    // use basic RE syntax
    wxRE_BASIC    = 2,

    // ignore case in match
    wxRE_ICASE    = 4,

    // only check match, don't set back references
    wxRE_NOSUB    = 8,

    // if not set, treat '\n' as an ordinary character, otherwise it is
    // special: it is not matched by '.' and '^' and '$' always match
    // after/before it regardless of the setting of wxRE_NOT[BE]OL
    wxRE_NEWLINE  = 16,

    // default flags
    wxRE_DEFAULT  = wxRE_EXTENDED
}

These flags are mainly useful when doing several matches in a long string to prevent erroneous matches for '' and '$':

enum
{
    // '^' doesn't match at the start of line
    wxRE_NOTBOL = 32,

    // '$' doesn't match at the end of line
    wxRE_NOTEOL = 64
}

A bad example of processing some text containing email addresses (the example is bad because the real email addresses can have more complicated form than user@host.net):

wxString text;
...
wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)");
if ( reEmail.Matches(text) )
{
    wxString text = reEmail.GetMatch(email);
    wxString username = reEmail.GetMatch(email, 1);
    if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD?
    {
        ...
    }
}

// or we could do this to hide the email address
size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3"));
printf("text now contains %u hidden addresses", count);

wxRegEx::wxRegEx
wxRegEx::~wxRegEx
wxRegEx::Compile
wxRegEx::IsValid
wxRegEx::GetMatch
wxRegEx::GetMatchCount
wxRegEx::Matches
wxRegEx::Replace
wxRegEx::ReplaceAll
wxRegEx::ReplaceFirst

wxRegEx::wxRegEx

wxRegEx()

Default ctor: use Compile() later.

wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT)

Create and compile the regular expression, use IsValid to test for compilation errors.

wxRegEx::~wxRegEx

~wxRegEx()

dtor not virtual, don't derive from this class

wxRegEx::Compile

bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT)

Compile the string into regular expression, return true if ok or false if string has a syntax error.

wxRegEx::IsValid

bool IsValid() const

Return true if this is a valid compiled regular expression, false otherwise.

wxRegEx::GetMatch

bool GetMatch(size_t* start, size_t* len, size_t index = 0) const

Get the start index and the length of the match of the expression (if index is 0) or a bracketed subexpression (index different from 0).

May only be called after successful call to Matches() and only if wxRE_NOSUB was not used in Compile().

Returns false if no match or if an error occured.

wxString GetMatch(const wxString& text, size_t index = 0) const

Returns the part of string corresponding to the match where index is interpreted as above. Empty string is returned if match failed

May only be called after successful call to Matches() and only if wxRE_NOSUB was not used in Compile().

wxRegEx::GetMatchCount

size_t GetMatchCount() const

Returns the size of the array of matches, i.e. the number of bracketed subexpressions plus one for the expression itself, or 0 on error.

May only be called after successful call to Compile(). and only if wxRE_NOSUB was not used.

wxRegEx::Matches

bool Matches(const wxChar* text, int flags = 0) const

Matches the precompiled regular expression against the string text, returns true if matches and false otherwise.

Flags may be combination of wxRE_NOTBOL and wxRE_NOTEOL.

May only be called after successful call to Compile().

wxRegEx::Replace

int Replace(wxString* text, const wxString& replacement, size_t maxMatches = 0) const

Replaces the current regular expression in the string pointed to by text, with the text in replacement and return number of matches replaced (maybe 0 if none found) or -1 on error.

The replacement text may contain back references \number which will be replaced with the value of the corresponding subexpression in the pattern match. \0 corresponds to the entire match and & is a synonym for it. Backslash may be used to quote itself or & character.

maxMatches may be used to limit the number of replacements made, setting it to 1, for example, will only replace first occurrence (if any) of the pattern in the text while default value of 0 means replace all.

wxRegEx::ReplaceAll

int ReplaceAll(wxString* text, const wxString& replacement) const

Replace all occurrences: this is actually a synonym for Replace().

See also

ReplaceFirst

wxRegEx::ReplaceFirst

int ReplaceFirst(wxString* text, const wxString& replacement) const

Replace the first occurrence.

See also

Replace