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

#include <regex.h>

Inheritance diagram for icu::RegexPattern:

Public Member Functions
	RegexPattern ()
	default constructor. More...

	RegexPattern (const RegexPattern &source)
	Copy Constructor. More...

virtual	~RegexPattern ()
	Destructor. More...

bool	operator== (const RegexPattern &that) const
	Comparison operator. More...

bool	operator!= (const RegexPattern &that) const
	Comparison operator. More...

RegexPattern &	operator= (const RegexPattern &source)
	Assignment operator. More...

virtual RegexPattern *	clone () const
	Create an exact copy of this RegexPattern object. More...

virtual uint32_t	flags () const
	Get the URegexpFlag match mode flags that were used when compiling this pattern. More...

virtual RegexMatcher *	matcher (const UnicodeString &input, UErrorCode &status) const
	Creates a RegexMatcher that will match the given input against this pattern. More...

virtual RegexMatcher *	matcher (UErrorCode &status) const
	Creates a RegexMatcher that will match against this pattern. More...

virtual UnicodeString	pattern () const
	Returns the regular expression from which this pattern was compiled. More...

virtual UText *	patternText (UErrorCode &status) const
	Returns the regular expression from which this pattern was compiled. More...

virtual int32_t	groupNumberFromName (const UnicodeString &groupName, UErrorCode &status) const
	Get the group number corresponding to a named capture group. More...

virtual int32_t	groupNumberFromName (const char *groupName, int32_t nameLength, UErrorCode &status) const
	Get the group number corresponding to a named capture group. More...

virtual int32_t	split (const UnicodeString &input, UnicodeString dest[], int32_t destCapacity, UErrorCode &status) const
	Split a string into fields. More...

virtual int32_t	split (UText input, UText dest[], int32_t destCapacity, UErrorCode &status) const
	Split a string into fields. More...

virtual UClassID	getDynamicClassID () const override
	ICU "poor man's RTTI", returns a UClassID for the actual class. More...

void	dumpPattern () const
	Dump a compiled pattern. More...

Public Member Functions inherited from icu::UObject
virtual	~UObject ()
	Destructor. More...

virtual UClassID	getDynamicClassID () const
	ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...

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

static RegexPattern *	compile (UText *regex, UParseError &pe, UErrorCode &status)
	Compiles the regular expression in string form into a RegexPattern object. More...

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 URegexpFlag match mode flags. More...

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 URegexpFlag match mode flags. More...

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 URegexpFlag match mode flags. More...

static RegexPattern *	compile (UText *regex, uint32_t flags, UErrorCode &status)
	Compiles the regular expression in string form into a RegexPattern object using the specified URegexpFlag match mode flags. More...

static UBool	matches (const UnicodeString &regex, const UnicodeString &input, UParseError &pe, UErrorCode &status)
	Test whether a string matches a regular expression. More...

static UBool	matches (UText regex, UText input, UParseError &pe, UErrorCode &status)
	Test whether a string matches a regular expression. More...

static UClassID	getStaticClassID ()
	ICU "poor man's RTTI", returns a UClassID for this class. More...

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 87 of file regex.h.

Constructor & Destructor Documentation

◆ RegexPattern() [1/2]

icu::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() [2/2]

icu::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

◆ ~RegexPattern()

virtual icu::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

◆ clone()

virtual RegexPattern * icu::RegexPattern::clone ( ) const

virtual

Create an exact copy of this RegexPattern object.

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

Returns: the copy of this RegexPattern

Stable:: ICU 2.4

◆ compile() [1/6]

static RegexPattern * icu::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 URegexpFlag 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 URegexpFlag match mode flags to be used, e.g. UREGEX_CASE_INSENSITIVE.
status	A reference to a UErrorCode to receive any errors.

Returns: A regexPattern object for the compiled pattern.

Stable:: ICU 2.6

◆ compile() [2/6]

static RegexPattern * icu::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 URegexpFlag 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 URegexpFlag match mode flags to be used, e.g. UREGEX_CASE_INSENSITIVE.
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

◆ compile() [3/6]

static RegexPattern * icu::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 URegexpFlag 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

◆ compile() [4/6]

static RegexPattern * icu::RegexPattern::compile	(	UText *	regex,
		uint32_t	flags,
		UErrorCode &	status
	)

static

Compiles the regular expression in string form into a RegexPattern object using the specified URegexpFlag 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 URegexpFlag match mode flags to be used, e.g. UREGEX_CASE_INSENSITIVE.
status	A reference to a UErrorCode to receive any errors.

Returns: A regexPattern object for the compiled pattern.

Stable:: ICU 4.6

◆ compile() [5/6]

static RegexPattern * icu::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 URegexpFlag 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 URegexpFlag match mode flags to be used, e.g. UREGEX_CASE_INSENSITIVE.
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 4.6

◆ compile() [6/6]

static RegexPattern * icu::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 URegexpFlag 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.

Stable:: ICU 4.6

◆ dumpPattern()

void icu::RegexPattern::dumpPattern ( ) const

Dump a compiled pattern.

Internal debug function.

Internal:: Do not use. This API is for internal use only.

◆ flags()

virtual uint32_t icu::RegexPattern::flags ( ) const

virtual

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

Returns: the URegexpFlag match mode flags

Stable:: ICU 2.4

◆ getDynamicClassID()

virtual UClassID icu::RegexPattern::getDynamicClassID ( ) const

overridevirtual

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

Stable:: ICU 2.4

Reimplemented from icu::UObject.

◆ getStaticClassID()

static UClassID icu::RegexPattern::getStaticClassID ( )

static

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

Stable:: ICU 2.4

◆ groupNumberFromName() [1/2]

virtual int32_t icu::RegexPattern::groupNumberFromName	(	const char *	groupName,
		int32_t	nameLength,
		UErrorCode &	status
	)		const

virtual

Get the group number corresponding to a named capture group.

The returned number can be used with any function that access capture groups by number.

The function returns an error status if the specified name does not appear in the pattern.

Parameters

groupName	The capture group name, platform invariant characters only.
nameLength	The length of the name, or -1 if the name is nul-terminated.
status	A UErrorCode to receive any errors.

Stable:: ICU 55

◆ groupNumberFromName() [2/2]

virtual int32_t icu::RegexPattern::groupNumberFromName	(	const UnicodeString &	groupName,
		UErrorCode &	status
	)		const

virtual

Get the group number corresponding to a named capture group.

The returned number can be used with any function that access capture groups by number.

The function returns an error status if the specified name does not appear in the pattern.

Parameters

groupName	The capture group name.
status	A UErrorCode to receive any errors.

Stable:: ICU 55

◆ matcher() [1/2]

virtual RegexMatcher * icu::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

◆ matcher() [2/2]

virtual RegexMatcher * icu::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

◆ matches() [1/2]

static UBool icu::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 regular 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

◆ matches() [2/2]

static UBool icu::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 regular 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 4.6

◆ operator!=()

bool icu::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 URegexpFlag settings.

Parameters

that	a RegexPattern object to compare with "this".

Returns: true if the objects are different.

Stable:: ICU 2.4

Definition at line 132 of file regex.h.

References icu::operator==().

◆ operator=()

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

Assignment operator.

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

Stable:: ICU 2.4

◆ operator==()

bool icu::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 URegexpFlag settings.

Parameters

that	a RegexPattern object to compare with "this".

Returns: true if the objects are equivalent.

Stable:: ICU 2.4

◆ pattern()

virtual UnicodeString icu::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

◆ patternText()

virtual UText * icu::RegexPattern::patternText ( UErrorCode & status ) 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.

Stable:: ICU 4.6

◆ split() [1/2]

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

virtual

Split a string into fields.

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

If the delimiter pattern includes capture groups, the captured text will also appear in the destination array of output strings, interspersed with the fields. This is similar to Perl, but differs from Java, which ignores the presence of capture groups in the pattern.

Trailing empty fields will always be returned, assuming sufficient destination capacity. This differs from the default behavior for Java and Perl where trailing empty fields are not returned.

The number of strings produced by the split operation is returned. This count includes the strings from capture groups in the delimiter pattern. This behavior differs from Java, which ignores capture groups.

For the best performance on split() operations, RegexMatcher::split is preferable 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

◆ split() [2/2]

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

virtual

Split a string into fields.

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

If the delimiter pattern includes capture groups, the captured text will also appear in the destination array of output strings, interspersed with the fields. This is similar to Perl, but differs from Java, which ignores the presence of capture groups in the pattern.

Trailing empty fields will always be returned, assuming sufficient destination capacity. This differs from the default behavior for Java and Perl where trailing empty fields are not returned.

The number of strings produced by the split operation is returned. This count includes the strings from capture groups in the delimiter pattern. This behavior differs from Java, which ignores capture groups.

For the best performance on split() operations, RegexMatcher::split() is preferable 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 destination strings used.

Stable:: ICU 4.6

Friends And Related Function Documentation

◆ RegexCImpl

friend class RegexCImpl

friend

Definition at line 627 of file regex.h.

◆ RegexCompile

friend class RegexCompile

friend

Definition at line 625 of file regex.h.

◆ RegexMatcher

friend class RegexMatcher

friend

Definition at line 626 of file regex.h.

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

regex.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ RegexPattern() [1/2]

◆ RegexPattern() [2/2]

◆ ~RegexPattern()

Member Function Documentation

◆ clone()

◆ compile() [1/6]

◆ compile() [2/6]

◆ compile() [3/6]

◆ compile() [4/6]

◆ compile() [5/6]

◆ compile() [6/6]

◆ dumpPattern()

◆ flags()

◆ getDynamicClassID()

◆ getStaticClassID()

◆ groupNumberFromName() [1/2]

◆ groupNumberFromName() [2/2]

◆ matcher() [1/2]

◆ matcher() [2/2]

◆ matches() [1/2]

◆ matches() [2/2]

◆ operator!=()

◆ operator=()

◆ operator==()

◆ pattern()

◆ patternText()

◆ split() [1/2]

◆ split() [2/2]

Friends And Related Function Documentation

◆ RegexCImpl

◆ RegexCompile

◆ RegexMatcher