astBrackets

Identify a bracketed sub-string

Description:

This function searches a specified section of the supplied text string for the first sub-string that is delimited by opening and closing brackets. If found, the positions of the opening and closing brackets are returned. Optionally, null-terminated copies of the strings, before, in and after the brackets can be returned. The characters to be used as the opening and closing brackets can be specified.

Synopsis

int astBrackets( const char text, size_t start, size_t end, char opchar, char clchar, int strip, size_t openat, size_t closeat, char before, char in, char after )

Parameters:

text
The text string to be seached.
start
The zero-based index of the first character to be checked within " text" . The whole string is used if " start" is greater than " end" .
end
The zero-based index of the last character to be checked within " text" . The whole string is used if " start" is greater than " end" . The last character is used if " end" is greater than the length of the string.
opchar
The character to be used as the opening bracket (e.g. [ ).
clchar
The character to be used as the closing bracket (e.g. ] ).
strip
If non-zero, leading and trailing spaces are removed from the returned " before" , " in" and " after" strings.
openat
Returned holding the zero-based index of the opening bracket. Ignored if NULL.
closeat
Returned holding the zero-based index of the closing bracket. Ignored if NULL.
before
Address at which to return a pointer to a null-terminated copy of the string that came before the opening bracket. This will be a null string " " if the opening bracket is the first character in the search. The returned pointer should be freed using astFree when no longer needed. Ignored if " before" is NULL.
in
Address at which to return a pointer to a null-terminated copy of the string that came between the opening and closing bracket. This will be a null string " " if the bracket was empty. The returned pointer should be freed using astFree when no longer needed. Ignored if " in" is NULL.
after
Address at which to return a pointer to a null-terminated copy of the string that came after the opening bracket. This will be a null string " " if the closing bracket is the last character in the search. The returned pointer should be freed using astFree when no longer needed. Ignored if " after" is NULL.

Returned Value

astBrackets()
A value of 1 is returned if a correctly bracketed sub-string was found. A value of 0 is returned if no bracketed sub-string was found. A value of -1 is returned if too many closing brackets were found. A value of -2 is returned if too many opening brackets were found.

Notes: