# RegexPattern Class Reference

Class `RegexPattern` represents a compiled regular expression. More...

`#include <regex.h>`

Inheritance diagram for RegexPattern:

## Public Types
enum | PatternIsUTextFlag { PATTERN_IS_UTEXT }
| Flag to disambiguate RegexPattern::matcher signature. More...
## Public Member Functions
| RegexPattern ()
| default constructor.
| RegexPattern (const RegexPattern &source)
| Copy Constructor.
virtual | ~RegexPattern ()
| Destructor.
UBool | operator== (const RegexPattern &that) const
| Comparison operator.
UBool | operator!= (const RegexPattern &that) const
| Comparison operator.
RegexPattern & | operator= (const RegexPattern &source)
| Assignment operator.
virtual RegexPattern * | clone () const
| Create an exact copy of this RegexPattern object.
virtual uint32_t | flags () const
| Get the match mode flags that were used when compiling this pattern.
virtual RegexMatcher * | matcher (const UnicodeString &input, UErrorCode &status) const
| Creates a RegexMatcher that will match the given input against this pattern.
virtual RegexMatcher * | matcher (UText *input, PatternIsUTextFlag flag, UErrorCode &status) const
| Creates a RegexMatcher that will match the given input against this pattern.
virtual RegexMatcher * | matcher (UErrorCode &status) const
| Creates a RegexMatcher that will match against this pattern.
virtual UnicodeString | pattern () const
| Returns the regular expression from which this pattern was compiled.
virtual UText * | patternText () const
| Returns the regular expression from which this pattern was compiled.
virtual int32_t | split (const UnicodeString &input, UnicodeString dest[], int32_t destCapacity, UErrorCode &status) const
| Split a string into fields.
virtual int32_t | split (UText *input, UText *dest[], int32_t destCapacity, UErrorCode &status) const
| Split a string into fields.
virtual UClassID | getDynamicClassID () const
| ICU "poor man's RTTI", returns a UClassID for the actual class.
## Static Public Member Functions
static RegexPattern * | compile (const UnicodeString &regex, UParseError &pe, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object.
static RegexPattern * | compile (UText *regex, UParseError &pe, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object.
static RegexPattern * | compile (const UnicodeString &regex, uint32_t flags, UParseError &pe, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.
static RegexPattern * | compile (UText *regex, uint32_t flags, UParseError &pe, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.
static RegexPattern * | compile (const UnicodeString &regex, uint32_t flags, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.
static RegexPattern * | compile (UText *regex, uint32_t flags, UErrorCode &status)
| Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.
static UBool | matches (const UnicodeString &regex, const UnicodeString &input, UParseError &pe, UErrorCode &status)
| Test whether a string matches a regular expression.
static UBool | matches (UText *regex, UText *input, UParseError &pe, UErrorCode &status)
| Test whether a string matches a regular expression.
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.
## Friends
class | RegexCompile
class | RegexMatcher
class | RegexCImpl

## Detailed Description

Class `RegexPattern` represents a compiled regular expression.

It includes factory methods for creating a RegexPattern object from the source (string) form of a regular expression, methods for creating RegexMatchers that allow the pattern to be applied to input text, and a few convenience methods for simple common uses of regular expressions.

Class RegexPattern is not intended to be subclassed.

Stable:
  ICU 2.4

Definition at line 100 of file regex.h.

## Member Enumeration Documentation

enum RegexPattern::PatternIsUTextFlag

Flag to disambiguate RegexPattern::matcher signature.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

Definition at line 373 of file regex.h.

## Constructor & Destructor Documentation

RegexPattern::RegexPattern | ( |  | ) |

default constructor.

Create a RegexPattern object that refers to no actual pattern. Not normally needed; RegexPattern objects are usually created using the factory method `compile()`.

Stable:
  ICU 2.4

RegexPattern::RegexPattern | ( | const RegexPattern & | source | ) |

Copy Constructor.

Create a new RegexPattern object that is equivalent to the source object.

Parameters:

  | source | the pattern object to be copied.

Stable:
  ICU 2.4

virtual RegexPattern::~RegexPattern | ( |  | ) | `[virtual]`

Destructor.

Note that a RegexPattern object must persist so long as any RegexMatcher objects that were created from the RegexPattern are active.

Stable:
  ICU 2.4

## Member Function Documentation

virtual RegexPattern* RegexPattern::clone | ( |  | ) | const`[virtual]`

Create an exact copy of this RegexPattern object.

Since RegexPattern is not intended to be subclasses, `clone()` and the copy construction are equivalent operations.

Returns:
  the copy of this RegexPattern

Stable:
  ICU 2.4

static RegexPattern* RegexPattern::compile | ( | UText * | regex,
|  | uint32_t | flags,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string instead of than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled. Note, the text referred to by this UText must not be deleted during the lifetime of the RegexPattern object or any RegexMatcher object created from it.
  | flags | The match mode flags to be used.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

static RegexPattern* RegexPattern::compile | ( | const UnicodeString & | regex,
|  | uint32_t | flags,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string instead of than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled.
  | flags | The match mode flags to be used.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Stable:
  ICU 2.6

static RegexPattern* RegexPattern::compile | ( | UText * | regex,
|  | uint32_t | flags,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string instead of than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled. Note, the text referred to by this UText must not be deleted during the lifetime of the RegexPattern object or any RegexMatcher object created from it.
  | flags | The match mode flags to be used.
  | pe | Receives the position (line and column numbers) of any error within the regular expression.)
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

static RegexPattern* RegexPattern::compile | ( | const UnicodeString & | regex,
|  | uint32_t | flags,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object using the specified match mode flags.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string instead of than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled.
  | flags | The match mode flags to be used.
  | pe | Receives the position (line and column numbers) of any error within the regular expression.)
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Stable:
  ICU 2.4

static RegexPattern* RegexPattern::compile | ( | UText * | regex,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

All pattern match mode flags are set to their default values.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string rather than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled. Note, the text referred to by this UText must not be deleted during the lifetime of the RegexPattern object or any RegexMatcher object created from it.
  | pe | Receives the position (line and column nubers) of any error within the regular expression.)
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

static RegexPattern* RegexPattern::compile | ( | const UnicodeString & | regex,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Compiles the regular expression in string form into a RegexPattern object.

These compile methods, rather than the constructors, are the usual way that RegexPattern objects are created.

Note that RegexPattern objects must not be deleted while RegexMatcher objects created from the pattern are active. RegexMatchers keep a pointer back to their pattern, so premature deletion of the pattern is a catastrophic error.

All pattern match mode flags are set to their default values.

Note that it is often more convenient to construct a RegexMatcher directly from a pattern string rather than separately compiling the pattern and then creating a RegexMatcher object from the pattern.

Parameters:

  | regex | The regular expression to be compiled.
  | pe | Receives the position (line and column nubers) of any error within the regular expression.)
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A regexPattern object for the compiled pattern.

Stable:
  ICU 2.4

virtual uint32_t RegexPattern::flags | ( |  | ) | const`[virtual]`

Get the match mode flags that were used when compiling this pattern.

Returns:
  the match mode flags

Stable:
  ICU 2.4

virtual UClassID RegexPattern::getDynamicClassID | ( |  | ) | const`[virtual]`

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
  ICU 2.4

Implements UObject.

static UClassID RegexPattern::getStaticClassID | ( |  | ) | `[static]`

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
  ICU 2.4

virtual RegexMatcher* RegexPattern::matcher | ( | UErrorCode & | status | ) | const`[virtual]`

Creates a RegexMatcher that will match against this pattern.

The RegexMatcher can be used to perform match, find or replace operations. Note that a RegexPattern object must not be deleted while RegexMatchers created from it still exist and might possibly be used again.

Parameters:

  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A RegexMatcher object for this pattern and input.

Stable:
  ICU 2.6

virtual RegexMatcher* RegexPattern::matcher | ( | UText * | input,
|  | PatternIsUTextFlag | flag,
|  | UErrorCode & | status |
| ) |  |  | const`[virtual]`

Creates a RegexMatcher that will match the given input against this pattern.

The RegexMatcher can then be used to perform match, find or replace operations on the input. Note that a RegexPattern object must not be deleted while RegexMatchers created from it still exist and might possibly be used again.

The matcher will make a shallow clone of the supplied input text, and all regexp pattern matching operations happen on this clone. While read-only operations on the supplied text are permitted, it is critical that the underlying string not be altered or deleted before use by the regular expression operations is complete.

Parameters:

  | input | The input text to which the regular expression will be applied.
  | flag | Must be RegexPattern::PATTERN_IS_UTEXT; used to disambiguate method signature.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A RegexMatcher object for this pattern and input.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

virtual RegexMatcher* RegexPattern::matcher | ( | const UnicodeString & | input,
|  | UErrorCode & | status |
| ) |  |  | const`[virtual]`

Creates a RegexMatcher that will match the given input against this pattern.

The RegexMatcher can then be used to perform match, find or replace operations on the input. Note that a RegexPattern object must not be deleted while RegexMatchers created from it still exist and might possibly be used again.

The matcher will retain a reference to the supplied input string, and all regexp pattern matching operations happen directly on this original string. It is critical that the string not be altered or deleted before use by the regular expression operations is complete.

Parameters:

  | input | The input string to which the regular expression will be applied.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  A RegexMatcher object for this pattern and input.

Stable:
  ICU 2.4

static UBool RegexPattern::matches | ( | UText * | regex,
|  | UText * | input,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Test whether a string matches a regular expression.

This convenience function both compiles the reguluar expression and applies it in a single operation. Note that if the same pattern needs to be applied repeatedly, this method will be less efficient than creating and reusing a RegexMatcher object.

Parameters:

  | regex | The regular expression
  | input | The string data to be matched
  | pe | Receives the position of any syntax errors within the regular expression
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  True if the regular expression exactly matches the full input string.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

static UBool RegexPattern::matches | ( | const UnicodeString & | regex,
|  | const UnicodeString & | input,
|  | UParseError & | pe,
|  | UErrorCode & | status |
| ) |  |  | `[static]`

Test whether a string matches a regular expression.

This convenience function both compiles the reguluar expression and applies it in a single operation. Note that if the same pattern needs to be applied repeatedly, this method will be less efficient than creating and reusing a RegexMatcher object.

Parameters:

  | regex | The regular expression
  | input | The string data to be matched
  | pe | Receives the position of any syntax errors within the regular expression
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  True if the regular expression exactly matches the full input string.

Stable:
  ICU 2.4

UBool RegexPattern::operator!= | ( | const RegexPattern & | that | ) | const`[inline]`

Comparison operator.

Two RegexPattern objects are considered equal if they were constructed from identical source patterns using the same match flag settings.

Parameters:

  | that | a RegexPattern object to compare with "this".

Returns:
  TRUE if the objects are different.

Stable:
  ICU 2.4

Definition at line 145 of file regex.h.

References operator==().

RegexPattern& RegexPattern::operator= | ( | const RegexPattern & | source | ) |

Assignment operator.

After assignment, this RegexPattern will behave identically to the source object.

Stable:
  ICU 2.4

UBool RegexPattern::operator== | ( | const RegexPattern & | that | ) | const

Comparison operator.

Two RegexPattern objects are considered equal if they were constructed from identical source patterns using the same match flag settings.

Parameters:

  | that | a RegexPattern object to compare with "this".

Returns:
  TRUE if the objects are equivalent.

Stable:
  ICU 2.4

virtual UnicodeString RegexPattern::pattern | ( |  | ) | const`[virtual]`

Returns the regular expression from which this pattern was compiled.

This method will work even if the pattern was compiled from a UText.

Note: If the pattern was originally compiled from a UText, and that UText was modified, the returned string may no longer reflect the RegexPattern object.

Stable:
  ICU 2.4

virtual UText* RegexPattern::patternText | ( |  | ) | const`[virtual]`

Returns the regular expression from which this pattern was compiled.

This method will work even if the pattern was compiled from a UnicodeString.

Note: This is the original input, not a clone. If the pattern was originally compiled from a UText, and that UText was modified, the returned UText may no longer reflect the RegexPattern object.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

virtual int32_t RegexPattern::split | ( | UText * | input,
|  | UText * | dest[],
|  | int32_t | destCapacity,
|  | UErrorCode & | status |
| ) |  |  | const`[virtual]`

Split a string into fields.

Somewhat like split() from Perl. The pattern matches identify delimiters that separate the input into fields. The input data between the matches becomes the fields themselves.

For the best performance on split() operations, `RegexMatcher::split` is perferable to this function

Parameters:

  | input | The string to be split into fields. The field delimiters match the pattern (in the "this" object)
  | dest | An array of mutable UText structs to receive the results of the split. If a field is NULL, a new UText is allocated to contain the results for that field. This new UText is not guaranteed to be mutable.
  | destCapacity | The number of elements in the destination array. If the number of fields found is less than destCapacity, the extra strings in the destination array are not altered. If the number of destination strings is less than the number of fields, the trailing part of the input string, including any field delimiters, is placed in the last destination string.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  The number of fields into which the input string was split.

Internal:
  Do not use. This API is for internal use only. ICU 4.4 technology preview

virtual int32_t RegexPattern::split | ( | const UnicodeString & | input,
|  | UnicodeString | dest[],
|  | int32_t | destCapacity,
|  | UErrorCode & | status |
| ) |  |  | const`[virtual]`

Split a string into fields.

Somewhat like split() from Perl. The pattern matches identify delimiters that separate the input into fields. The input data between the matches becomes the fields themselves.

For the best performance on split() operations, `RegexMatcher::split` is perferable to this function

Parameters:

  | input | The string to be split into fields. The field delimiters match the pattern (in the "this" object)
  | dest | An array of UnicodeStrings to receive the results of the split. This is an array of actual UnicodeString objects, not an array of pointers to strings. Local (stack based) arrays can work well here.
  | destCapacity | The number of elements in the destination array. If the number of fields found is less than destCapacity, the extra strings in the destination array are not altered. If the number of destination strings is less than the number of fields, the trailing part of the input string, including any field delimiters, is placed in the last destination string.
  | status | A reference to a UErrorCode to receive any errors.

Returns:
  The number of fields into which the input string was split.

Stable:
  ICU 2.4

The documentation for this class was generated from the following file:

- regex.h

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines