#### 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:

- Any nested brackets within a top-level bracketed sub-string are skipped. Any inbalance in brackets is indicated by the function return value.

- If no bracketed sub-string is found, all the returned pointers will be NULL, `"` closeat`"` will be 0 and `"` openat`"` will be 1.

Copyright (C) 2021 East Asian Observatory