This function checks a supplied test string to see if it matches a supplied template. If it does, specified sub-sections of the test string may optionally be replaced by supplied substitution strings. The resulting string is returned.

char $\ast$astChrSub( const char $\ast$test, const char $\ast$pattern, const char $\ast$subs[], int nsub )

test

pattern

subs

nsub

astChrSub()

• 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 test string does not match the template.

The template syntax is a minimal form of regular expression, The quantifiers allowed are " $\ast$" , " ?" , " $+$" , " {n}" , " $\ast$?" and " $+$?" (the last two are non-greedy - they match the minimum length possible that still gives an overall match to the template). The only constraints allowed are " $$^" and " $" . The following atoms are allowed:

• [chars]: Matches any of the specified characters.

• [$$^chars]: Matches anything but the specified characters.

• .: Matches any single character.

• x: Matches the character x so long as x has no other significance.

• $\setminus$x: Always matches the character x (except for [dDsSwW]).

• $\setminus$d: Matches a single digit.

• $\setminus$D: Matches anything but a single digit.

• $\setminus$w: Matches any alphanumeric character, and " _" .

• $\setminus$W: Matches anything but alphanumeric characters, and " _" .

• $\setminus$s: Matches white space.

• $\setminus$S: Matches anything but white space.

Note, minus signs (" -" ) within brackets have no special significance, so ranges of characters must be specified explicitly.

Multiple template strings can be concatenated, using the " $|$" character to separate them. The test string is compared against each one in turn until a match is found.

Parentheses are used within each template to identify sub-strings that are to be replaced by the strings supplied in " sub" .

If " nsub" is supplied as zero, then substitution strings may be specified by appended them to the end of the " pattern" string, separated by " =" characters. If " nsub" is not zero, then any substitution strings appended to the end of " pattern" are ignored.

Each element of " subs" may contain a reference to a token of the form " $1" , " $2" , etc. The " $1" token will be replaced by the part of the test string that matched the first parenthesised sub-string in " pattern" . The " $2" token will be replaced by the part of the test string that matched the second parenthesised sub-string in " pattern" , etc.