astChrSplitREastChrSplitRE - Extract sub-strings matching a specified regular expression

Description:

This function compares the supplied string with the supplied regular expression. If they match, each section of the test string that corresponds to a parenthesised sub-string in the regular expression is copied and stored in the returned array.

Synopsis:

char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n, const char $*$$*$matchend )

Parameters:

str

Pointer to the string to be split.

regexp

The regular expression. See "Template Syntax:" in the astChrSubastChrSub prologue. Note, this function differs from astChrSub in that any equals signs (=) in the regular expression are treated literally.

n

Address of an int in which to return the number of sub-strings returned.

matchend

A pointer to a location at which to return a pointer to the character that follows the last character within the supplied test string that matched any parenthesises sub-section of "regexp". A NULL pointer is returned if no matches were found. A NULL pointer may be supplied if the location of the last matching character is not needed.

Returned Value:

astChrSplitRE()

A pointer to a dynamically allocated array containing "$*$n" elements. Each element is a pointer to a dynamically allocated character string containing a sub-string extracted from the supplied string. The array itself, and the strings within it, should all be freed using astFreeastFree when no longer needed.

Notes:

• If a parenthesised sub-string in the regular expression is matched by more than one sub-string within the test string, then only the first is returned. To return multiple matches, the regular expression should include multiple copies of the parenthesised sub-string (for instance, separated by ".$+$?" if the intervening string is immaterial).

• A NULL pointer is returned if this function is invoked with the global error status set or if it should fail for any reason, or if the supplied string contains no words.