#### Description:

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.

#### Synopsis

char ∗astChrSub( const char ∗test, const char ∗pattern, const char ∗subs[], int nsub )

#### Parameters:

##### test

The string to be tested.

##### pattern

The template string. See `"` Template Syntax:`"` below.

##### subs

An array of strings that are to replace the sections of the test string that match each parenthesised sub-string in `"` pattern`"` . The first element of `"` subs`"` replaces the part of the test string that matches the first parenthesised sub-string in the template, etc.

If `"` nsub`"` is zero, then the `"` subs`"` pointer is ignored. In this case, substitution strings may be specified by appended them to the end of the `"` pattern`"` string, separated by `"` =`"` characters. Note, if you need to include a literal `"` =`"` character in the pattern, precede it by an escape `"` ∖`"` character.

##### nsub

The number of substitution strings supplied in array `"` subs`"` .

#### Returned Value

##### astChrSub()

A pointer to a dynamically allocated string holding the result of the substitutions, or NULL if the test string does not match the template string. This string should be freed using astFree when no longer needed. If no substituions are specified then a copy of the test string is returned if it matches the template.

#### Notes:

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

#### Template Syntax

The template syntax is a minimal form of regular expression, The quantifiers allowed are `"` ∗`"` , `"` ?`"` , `"` +`"` , `"` {n}`"` , `"` ∗?`"` 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.

- ∖x: Always matches the character x (except for [dDsSwW]).

- ∖d: Matches a single digit.

- ∖D: Matches anything but a single digit.

- ∖w: Matches any alphanumeric character, and `"` _`"` .

- ∖W: Matches anything but alphanumeric characters, and `"` _`"` .

- ∖s: Matches white space.

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

Copyright (C) 2021 East Asian Observatory