wxWidgets: wxRegEx Class Reference

| Version: 3.1.5

Public Member Functions | Static Public Member Functions | List of all members
wxRegEx Class Reference
Class List by Category » Data Structures

`#include </home/Hamis/wxwidgets-3.1/wxWidgets3.1-3.1.5-1.i686/src/wxWidgets-3.1.5/interface/wx/regex.h>`

## Detailed Description

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.

##

Library: wxBase

<>< =''>:</>&;&;< =''>\ </></>

Example:

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@.nosp@m.host.nosp@m..net`):

wxString originalText = "This is some text with foo@example.com and bar@example.com";
// Regex. to match an email address and extract its subparts.
wxRegEx reEmail("([^@ -]+)@([[:alnum:]_]+).([[:alnum:]]{2,4})");
wxString processText = originalText;
while ( reEmail.Matches(processText) )
{
// Find the size of the first match and print it.
size_t start, len;
reEmail.GetMatch(&start, &len, 0);
std::cout << "Email: " << reEmail.GetMatch(processText, 0) << std::endl;
// Print the submatches.
std::cout << "Name: " << reEmail.GetMatch(processText, 1) << std::endl;
std::cout << "Domain: " << reEmail.GetMatch(processText, 2) << std::endl;
std::cout << "TLD: " << reEmail.GetMatch(processText, 3) << std::endl;
// Process the remainder of the text if there is any.
processText = processText.Mid (start + len);
}
// Or this will replace all names with "HIDDEN".
size_t count = reEmail.ReplaceAll(&originalText, "HIDDEN@\\2.\\3");
std::cout << "text now contains " << count << " hidden addresses" << std::endl;
std::cout << originalText << std::endl;
wxRegEx
wxRegEx represents a regular expression.
Definition: regex.h:123
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:315
wxString::Mid
wxString Mid(size_t first, size_t nCount=wxString::npos) const
Returns a substring starting at first, with length count, or the rest of the string if count is the d...
endl
wxTextOutputStream & endl(wxTextOutputStream &stream)
Writes '\n' to stream.

## Public Member Functions
| wxRegEx ()
| Default constructor: use Compile() later. More...
| wxRegEx (const wxString &expr, int flags=wxRE_DEFAULT)
| Create and compile the regular expression, use IsValid() to test for compilation errors. More...
| ~wxRegEx ()
| Destructor. More...
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. More...
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). More...
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. More...
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. More...
bool | IsValid () const
| Return true if this is a valid compiled regular expression, false otherwise. More...
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. More...
bool | Matches (const wxChar *text, int flags, size_t len) const
bool | Matches (const wxString &text, int flags=0) const
| Matches the precompiled regular expression against the string text, returns true if matches and false otherwise. More...
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. More...
int | ReplaceAll (wxString *text, const wxString &replacement) const
| Replace all occurrences: this is actually a synonym for Replace(). More...
int | ReplaceFirst (wxString *text, const wxString &replacement) const
| Replace the first occurrence. More...

## Static Public Member Functions
static wxString | QuoteMeta (const wxString &str)
| Escapes any of the characters having special meaning for wxRegEx. More...

## Constructor & Destructor Documentation

## ◆ wxRegEx() [1/2]

wxRegEx::wxRegEx | ( |  | ) |

Default constructor: use Compile() later.

## ◆ wxRegEx() [2/2]

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

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

As for the flags, please see wxRE_FLAGS.

## ◆ ~wxRegEx()

wxRegEx::~wxRegEx | ( |  | ) |

Destructor.

It's not virtual, don't derive from this class.

## Member Function Documentation

## ◆ Compile()

bool wxRegEx::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.

As for the flags, please see wxRE_FLAGS.

## ◆ GetMatch() [1/2]

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

## ◆ GetMatch() [2/2]

bool wxRegEx::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 occurred.

## ◆ GetMatchCount()

size_t wxRegEx::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.

## ◆ IsValid()

bool wxRegEx::IsValid | ( |  | ) | const

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

## ◆ Matches() [1/3]

bool wxRegEx::Matches | ( | const wxChar * | text,
|  | int | flags,
|  | size_t | len
| ) |  | const

## ◆ Matches() [2/3]

bool wxRegEx::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`, see wxRE_NOT_FLAGS.

Some regex libraries assume that the text given is null terminated, while others require the length be given as a separate parameter. Therefore for maximum portability assume that text cannot contain embedded nulls.

When the Matches(const wxChar *text, int flags = 0) form is used, a wxStrlen() will be done internally if the regex library requires the length. When using Matches() in a loop the Matches(text, flags, len) form can be used instead, making it possible to avoid a wxStrlen() inside the loop.

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

## ◆ Matches() [3/3]

bool wxRegEx::Matches | ( | const wxString & | 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`, see wxRE_NOT_FLAGS.

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

## ◆ QuoteMeta()

static wxString wxRegEx::QuoteMeta | ( | const wxString & | str | ) |
| static

Escapes any of the characters having special meaning for wxRegEx.

Currently the following characters are special: \, ^, $, ., |, ?, *, +, (, ), [, ], { and }. All occurrences of any of these characters in the passed string are escaped, i.e. a backslash is inserted before them, to remove their special meaning.

For example:

wxString quoted = wxRegEx::QuoteMeta("foo.*bar");
assert( quoted == R"(foo\.\*bar)" );
wxRegEx::QuoteMeta
static wxString QuoteMeta(const wxString &str)
Escapes any of the characters having special meaning for wxRegEx.

This function can be useful when using wxRegEx to search for a literal string entered by user, for example.

Parameters

  str | A string that may contain metacharacters to escape.

Returns
  A string with all metacharacters escaped.

Since
  3.1.3

## ◆ Replace()

int wxRegEx::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.

## ◆ ReplaceAll()

int wxRegEx::ReplaceAll | ( | wxString * | text,
|  | const wxString & | replacement
| ) |  | const

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

See also
  ReplaceFirst()

## ◆ ReplaceFirst()

int wxRegEx::ReplaceFirst | ( | wxString * | text,
|  | const wxString & | replacement
| ) |  | const

Replace the first occurrence.