AST Memory Management and Utility Functions

AST provides a memory management layer that can be used in place of system functions such as malloc, free, realloc, etc. The AST replacements for these functions ( astMallocastMalloc, astFreeastFree and astReallocastRealloc) add extra information to each allocated memory block that allows AST to check the validity of supplied pointers. For example, this extra information allows astFree to detect if the supplied pointer has already been freed, and if so to issue an appropriate error message. The existence of this extra information is invisible to outside callers, and stored in a header block located just before the returned memory block.

In addition to the standard functions, AST provides other memory management functions, such as:

astStoreastStore
- stores data in dynamically allocated memory, allocating the memory (or adjusting the size of previously allocated memory) to match the amount of data to be stored.
astGrowastGrow
- allocates and expands memory to hold an adjustable-sized array.
astAppendStringastAppendString
- allocates and expands memory to hold a concatenated string.

Theses are just a few of the available utilities functions in the AST memory management layer. Prototypes for all AST memory management functions are included in the header file “ast.h”.

An important restriction on these functions is that pointers created by other memory management functions, such as the system version of malloc etc., should never supplied to an AST memory management function. Only pointers created by AST should be used by these functions.

In addition to memory management functions, AST provides various other utility functions, such as a basic regular expression facility, and other string manipulation functions. These are also documented in this appendix.

The AST memory management layer is implemented on top of the usual malloc, tt free and realloc functions. By default these will be the standard functions provided by <stdlib.h>. However, the facilities of the STARMEM package (included in the Starlink Software Collection) can be used to specify alternative functions to use. This requires that AST be configured using the “–with-starmem” option when it is built.

The STARMEM package provides a wrapper for the standard malloc implementation that enables the user to switch malloc schemes at runtime by setting the STARMEM_MALLOC environment variable. Currently allowed values for this variable are:

SYSTEM
- standard system malloc/free - the default
DL
- Doug Lea's malloc/free
GC
- Hans-Boehm Garbage Collection

astAppendString Append a string to another string which grows dynamically 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 ) 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" . 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 astFreeastFree. 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. astAppendStringf Append a string to another string, allowing printf format specifiers 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). It is the same as astAppendStringastAppendString, except that the " str2" string ay include printf format specifiers. Synopsis char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... ) 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" . It may contain format specifications such as used with the C " printf" family of functions. ... Additional optional arguments (as used by e.g. " printf" ) which specify values which are to be substituted into the " str2" string in place of any format specifications. 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 astFreeastFree. 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. astBrackets Identify a bracketed sub-string 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 ) 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 astFreeastFree 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. 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. 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. astCalloc Allocate and initialise memory This function allocates memory in a similar manner to the standard C " calloc" function, but with improved security (against memory leaks, etc.) and with error reporting. It also fills the allocated memory with zeros.

Like astMallocastMalloc, it allows zero-sized memory allocation (without error), resulting in a NULL returned pointer value. Synopsis void $*$astCalloc( size_t nmemb, size_t size ) nmemb The number of array elements for which memory is to be allocated. size The size of each array element, in bytes. astCalloc() If successful, the function returns a pointer to the start of the allocated memory region. If the size allocated is zero, this will be a NULL pointer. A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. astChr2Double read a double value from a string This function reads a double from the supplied null-terminated string, ignoring leading and trailing white space. AST__BAD is ereturned without error if the string is not a numerical value. Synopsis double astChr2Double( const char $*$str ) str Pointer to the string. astChr2Double() The double value, or AST__BAD. A value of AST__BAD is returned if this function is invoked with the global error status set or if it should fail for any reason. astChrCase Convert a string to upper or lower case This function converts a supplied string to upper or lower case, storing the result in a supplied buffer. The astStringCaseastStringCase function is similar, but stores the result in a dynamically allocated buffer. Synopsis void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status ) in Pointer to the null terminated string to be converted. If this is NULL, the supplied contents of the " out" string are used as the input string. out Pointer to the buffer to receive the converted string. The length of this buffer is given by " blen" . If NULL is supplied for " in" , then the supplied contents of " out" are converted and written back into " out" over-writing the supplied contents. upper If non-zero, the string is converted to upper case. Otherwise it is converted to lower case. blen The length of the output buffer. Ignored if " in" is NULL. No more than " blen - 1" characters will be copied from " in" to " out" , and a terminating null character will then be added. astChrClean Replace unprintable characters in a string with spaces This function replaces all unprintable characters in the given string with spaces. It is assumed that the string contains only ASCII characters. Synopsis void astChrClean( char $*$text ) text Pointer to the null terminated string to be modified. astChrLen Determine the used length of a string This function returns the used length of a string. This excludes any trailing white space or non-printable characters (such as the trailing null character). Synopsis size_t astChrLen( const char $*$string ) string Pointer to the string. astChrLen() The number of characters in the supplied string, not including the trailing newline, and any trailing white-spaces or non-printable characters. astChrMatch Case insensitive string comparison This function compares two null terminated strings for equality, discounting differences in case and any trailing white space in either string. Synopsis int astChrMatch( const char $*$str1, const char $*$str2 ) str1 Pointer to the first string. str2 Pointer to the second string. astChrMatch() Non-zero if the two strings match, otherwise zero. A value of zero is returned if this function is invoked with the global error status set or if it should fail for any reason. astChrMatchN Case insensitive string comparison of at most N characters This function compares two null terminated strings for equality, discounting differences in case and any trailing white space in either string. No more than " n" characters are compared. Synopsis int astChrMatchN( const char $*$str1, const char $*$str2, size_t n ) str1 Pointer to the first string. str2 Pointer to the second string. n Maximum number of characters to compare. astChrMatchN() Non-zero if the two strings match, otherwise zero. A value of zero is returned if this function is invoked with the global error status set or if it should fail for any reason. astChrRemoveBlanks Remove all spaces from a string This function removes all spaces form the supplied string by moving non-space characters to the left. The string is terminated to remove any trailing spaces. Synopsis void astChrCleanastChrClean( char $*$text ) text Pointer to the null terminated string to be modified. astChrSplit Extract words from a supplied string This function extracts all space-separated words form the supplied string and returns them in an array of dynamically allocated strings. Synopsis char $*$$*$astChrSplit( const char $*$str, int $*$n ) str Pointer to the string to be split. n Address of an int in which to return the number of words returned. astChrSplit() A pointer to a dynamically allocated array containing " $*$n" elements. Each element is a pointer to a dynamically allocated character string containing a word extracted from the supplied string. Each of these words will have no leading or trailing white space. 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 string contains no words. astChrSplitC Split a string using a specified character delimiter This function extracts all sub-strings separated by a given character from the supplied string and returns them in an array of dynamically allocated strings. The delimiter character itself is not included in the returned strings.

Delimiter characters that are preceded by " $\backslash$" are not used as delimiters but are included in the returned word instead (without the " $\backslash$" ). Synopsis char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n ) str Pointer to the string to be split. c The delimiter character. n Address of an int in which to return the number of words returned. astChrSplitC() A pointer to a dynamically allocated array containing " $*$n" elements. Each element is a pointer to a dynamically allocated character string containing a word extracted from the supplied string. 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 string contains no words. astChrSplitRE Extract sub-strings matching a specified regular expression This function compares the supplied string with the supplied regular expression. If they match, each section of the test string that corresponds to a parenthesised sub-string in the regular expression is copied and stored in the returned array. Synopsis char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n, const char $*$$*$matchend ) str Pointer to the string to be split. regexp The regular expression. See " Template Syntax:" in the astChrSubastChrSub prologue. Note, this function differs from astChrSub in that any equals signs (=) in the regular expression are treated literally. n Address of an int in which to return the number of sub-strings returned. matchend A pointer to a location at which to return a pointer to the character that follows the last character within the supplied test string that matched any parenthesises sub-section of " regexp" . A NULL pointer is returned if no matches were found. A NULL pointer may be supplied if the location of the last matching character is not needed. astChrSplitRE() A pointer to a dynamically allocated array containing " $*$n" elements. Each element is a pointer to a dynamically allocated character string containing a sub-string extracted from the supplied string. The array itself, and the strings within it, should all be freed using astFreeastFree when no longer needed. If a parenthesised sub-string in the regular expression is matched by more than one sub-string within the test string, then only the first is returned. To return multiple matches, the regular expression should include multiple copies of the parenthesised sub-string (for instance, separated by " .$+$?" if the intervening string is immaterial).

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 string contains no words. astChrSub Performs substitutions on a supplied string 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 ) 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 " $\backslash$" character. nsub The number of substitution strings supplied in array " subs" . 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 astFreeastFree when no longer needed. If no substituions are specified then a copy of the test string is returned if it matches the template. 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. astChrTrunc Terminate a string to exclude trailing spaces This function pokes a null character into the supplied string to remove any trailing spaces. Synopsis void astChrTrunc( char $*$text ) text The string to be truncated. astFandl Identify the used section of a string This function searches a specified section of the supplied text for non-space characters, returning the indices of the first and last. Synopsis void astFandl_( const char $*$text, size_t start, size_t end, size_t $*$f, size_t $*$l ) 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. f Returned holding the zero-based index of the first non-space character. Ignored if NULL. l Returned holding the zero-based index of the last non-space character. Ignored if NULL. " f" is returned greater than " l" if the specified section of the string is entirely blank. astFree Free previously allocated memory This function frees memory that has previouly been dynamically allocated using one of the AST memory function. Synopsis void $*$astFree( void $*$ptr ) ptr Pointer to previously allocated memory. An error will result if the memory has not previously been allocated by another function in this module. However, a NULL pointer value is accepted (without error) as indicating that no memory has yet been allocated, so that no action is required. astFree() Always returns a NULL pointer. astFreeDouble Free previously double allocated memory This function frees memory that has previouly been dynamically allocated using one of the AST memory function. It assumes that the supplied pointer is a pointer to an array of pointers. Each of these pointers is first freed, and then the supplied pointer is freed.

Note, this routine should not be used with arrays allocated by astGrowastGrow since astGrow over-allocates and so there may be non-initialised pointers at the end of the array. Synopsis void $*$astFreeDouble( void $*$ptr ) ptr Pointer to previously allocated memory. An error will result if the memory has not previously been allocated by another function in this module. However, a NULL pointer value is accepted (without error) as indicating that no memory has yet been allocated, so that no action is required. astFreeDouble() Always returns a NULL pointer. astGrow Allocate memory for an adjustable array This function allocates memory in which to store an array of data whose eventual size is unknown. It should be invoked whenever a new array size is determined and will appropriately increase the amount of memory allocated when necessary. In general, it will over-allocate in anticipation of future growth so that the amount of memory does not need adjusting on every invocation. Synopsis void $*$astGrow( void $*$ptr, size_t n, size_t size ) ptr Pointer to previously allocated memory (or NULL if none has yet been allocated). n Number of array elements to be stored (may be zero). size The size of each array element. astGrow() If the memory was allocated successfully, a pointer to the start of the possibly new memory region is returned (this may be the same as the original pointer). When new memory is allocated, the existing contents are preserved.

This function does not free memory once it is allocated, so the size allocated grows to accommodate the maximum size of the array (or " high water mark" ). Other memory handling routines may be used to free the memory (or alter its size) if necessary.

If this function is invoked with the global error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. astIsDynamic Returns a flag indicating if memory was allocated dynamically This function takes a pointer to a region of memory and tests if the memory has previously been dynamically allocated using other functions from this module. It does this by checking for the presence of a " magic" number in the header which precedes the allocated memory. If the magic number is not present (or the pointer is invalid for any other reason), zero is returned. Otherwise 1 is returned. Synopsis int astIsDynamic( const void $*$ptr ) ptr Pointer to test. astIsDynamic() Non-zero if the memory was allocated dynamically. Zero is returned if the supplied pointer is NULL. A value of zero is returned if this function is invoked with the global error status set, or if it fails for any reason. astMalloc Allocate memory This function allocates memory in a similar manner to the standard C " malloc" function, but with improved security (against memory leaks, etc.) and with error reporting. It also allows zero-sized memory allocation (without error), resulting in a NULL returned pointer value. Synopsis void $*$astMalloc( size_t size ) size The size of the memory region required (may be zero). astMalloc() If successful, the function returns a pointer to the start of the allocated memory region. If the size allocated is zero, this will be a NULL pointer. A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. astMemCaching Controls whether allocated but unused memory is cached in this module This function sets a flag indicating if allocated but unused memory should be cached or not. It also returns the original value of the flag.

If caching is switched on or off as a result of this call, then the current contents of the cache are discarded.

Note, each thread has a separate cache. Calling this function affects only the currently executing thread. Synopsis int astMemCaching( int newval ) newval The new value for the MemoryCaching tuning parameter (see astTuneastTune in objectc.c). If AST__TUNULL is supplied, the current value is left unchanged. astMemCaching() The original value of the MemoryCaching tuning parameter. astRealloc Change the size of a dynamically allocated region of memory This function changes the size of a dynamically allocated region of memory, preserving its contents up to the minimum of the old and new sizes. This may involve copying the contents to a new location, so a new pointer is returned (and the old memory freed if necessary).

This function is similar to the standard C " realloc" function except that it provides better security against programming errors and also supports the allocation of zero-size memory regions (indicated by a NULL pointer). Synopsis void $*$astRealloc( void $*$ptr, size_t size ) ptr Pointer to previously allocated memory (or NULL if the previous size of the allocated memory was zero). size New size required for the memory region. This may be zero, in which case a NULL pointer is returned (no error results). It should not be negative. astRealloc() If the memory was reallocated successfully, a pointer to the start of the new memory region is returned (this may be the same as the original pointer). If size was given as zero, a NULL pointer is returned. If this function is invoked with the error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. Note that this behaviour differs from that of the standard C " realloc" function which returns NULL if it fails. astRemoveLeadingBlanks Remove any leading white space from a string This function moves characters in the supplied string to the left in order to remove any leading white space. Synopsis void astRemoveLeadingBlanks( char $*$string ) string Pointer to the string. astSizeOf Determine the size of a dynamically allocated region of memory This function returns the size of a region of dynamically allocated memory. Synopsis size_t astSizeOf( const void $*$ptr ) ptr Pointer to dynamically allocated memory (or NULL if the size of the allocated memory was zero). astSizeOf() The allocated size. This will be zero if a NULL pointer was supplied (no error will result). A value of zero is returned if this function is invoked with the global error status set, or if it fails for any reason. astStore Store data in dynamically allocated memory This function stores data in dynamically allocated memory, allocating the memory (or adjusting the size of previously allocated memory) to match the amount of data to be stored. Synopsis void $*$astStore( void $*$ptr, const void $*$data, size_t size ) ptr Pointer to previously allocated memory (or NULL if none has yet been allocated). data Pointer to the start of the data to be stored. This may be given as NULL if there are no data, in which case it will be ignored and this function behaves like astReallocastRealloc, preserving the existing memory contents. size The total size of the data to be stored and/or the size of memory to be allocated. This may be zero, in which case the data parameter is ignored, any previously-allocated memory is freed and a NULL pointer is returned. astStore() If the data were stored successfully, a pointer to the start of the possibly new memory region is returned (this may be the same as the original pointer). If size was given as zero, a NULL pointer is returned. This is a convenience function for use when storing data of arbitrary size in memory which is to be allocated dynamically. It is appropriate when the size of the data will not change frequently because the size of the memory region will be adjusted to fit the data on every invocation.

If this function is invoked with the error status set, or if it fails for any reason, the original pointer value is returned and the memory contents are unchanged. astString Create a C string from an array of characters This function allocates memory to hold a C string and fills the string with the sequence of characters supplied. It then terminates the string with a null character and returns a pointer to its start. The memory used for the string may later be de-allocated using astFreeastFree.

This function is intended for constructing null terminated C strings from arrays of characters which are not null terminated, such as when importing a character argument from a Fortran 77 program. Synopsis char $*$astString( const char $*$chars, int nchars ) chars Pointer to the array of characters to be used to fill the string. nchars The number of characters in the array (zero or more). astString() If successful, the function returns a pointer to the start of the allocated string. If the number of characters is zero, a zero-length string is still allocated and a pointer to it is returned. A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason. astStringArray Create an array of C strings from an array of characters This function turns an array of fixed-length character data into a dynamicllay allocated array of null-terminated C strings with an index array that may be used to access them.

The array of character data supplied is assumed to hold " nel" adjacent fixed-length strings (without terminating nulls), each of length " len" characters. This function allocates memory and creates a null-terminated copy of each of these strings. It also creates an array of " nel" pointers which point at the start of each of these new strings. A pointer to this index array is returned.

The memory used is allocated in a single block and should later be de-allocated using astFreeastFree. Synopsis char $*$$*$astStringArray( const char $*$chars, int nel, int len ) chars Pointer to the array of input characters. The number of characters in this array should be at least equal to (nel $*$ len). nel The number of fixed-length strings in the input character array. This may be zero but should not be negative. len The number of characters in each fixed-length input string. This may be zero but should not be negative. astStringArray() A pointer to the start of the index array, which contains " nel" pointers pointing at the start of each null-terminated output string.

The returned pointer should be passed to astFree to de-allocate the memory used when it is no longer required. This will free both the index array and the memory used by the strings it points at. A NULL pointer will also be returned if the value of " nel" is zero, in which case no memory is allocated.

A pointer value of NULL will also be returned if this function is invoked with the global error status set or if it fails for any reason. astStringCase Convert a string to upper or lower case This function converts a supplied string to upper or lower case, storing the result in dynamically allocated memory. The astChrCaseastChrCase function is similar, but stores the result in a supplied buffer. Synopsis char $*$astStringCase( const char string, int upper ) string Pointer to the null terminated string to be converted. upper If non-zero, the string is converted to upper case. Otherwise it is converted to lower case. astStringCase() If successful, the function returns a pointer to the start of the allocated string. The returned memory should be freed using astFreeastFree when no longer needed. A pointer value of NULL is returned if this function is invoked with the global error status set or if it fails for any reason.