next up previous 264
Next: astFree - Free previously allocated memory
Up: AST Memory Management and Utility Functions
Previous: astChrSplitRE - Extract sub-strings matching a specified regular expression


astChrSub - Performs substitutions on a supplied string

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, preceed it by an escape "$\backslash$" 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 "$\wedge$" and "$". The following atoms are allowed:

chars
: Matches any of the specified characters.

$\wedge$chars
: Matches anything but the specified characters.

 $$
.: Matches any single character.

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

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

 $$
$\backslash$d: Matches a single digit.

 $$
$\backslash$D: Matches anything but a single digit.

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

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

 $$
$\backslash$s: Matches white space.

 $$
$\backslash$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 "$\vert$" 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.



next up previous 264
Next: astFree - Free previously allocated memory
Up: AST Memory Management and Utility Functions
Previous: astChrSplitRE - Extract sub-strings matching a specified regular expression

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council