#### Description:

This function appends one string to another dynamically allocated string, extending the dynamic string as necessary to accommodate the new characters (plus the final null).

#### Synopsis

char ∗astAppendString( char ∗str1, int ∗nc, const char ∗str2 )

#### Parameters:

##### str1

Pointer to the null-terminated dynamic string, whose memory has been allocated using an AST memory allocation function. If no space has yet been allocated for this string, a NULL pointer may be given and fresh space will be allocated by this function.

##### nc

Pointer to an integer containing the number of characters in the dynamic string (excluding the final null). This is used to save repeated searching of this string to determine its length and it defines the point where the new string will be appended. Its value is updated by this function to include the extra characters appended.

If `"` str1`"` is NULL, the initial value supplied for `"` ∗nc`"` will be ignored and zero will be used.

##### str2

Pointer to a constant null-terminated string, a copy of which is to be appended to `"` str1`"` .

#### Returned Value

##### astAppendString()

A possibly new pointer to the dynamic string with the new string appended (its location in memory may have to change if it has to be extended, in which case the original memory is automatically freed by this function). When the string is no longer required, its memory should be freed using astFree.

#### Notes:

- If this function is invoked with the global error status set or if it should fail for any reason, then the returned pointer will be equal to `"` str1`"` and the dynamic string contents will be unchanged.

Copyright (C) 2021 East Asian Observatory