In addition to the standard functions, AST provides other memory management functions, such as:
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:
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
If " str1" is NULL, the initial value supplied for "
If " str1" is NULL, the initial value supplied for "
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.
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.
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.
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.
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 "
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
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 "
[chars]: Matches any of the specified characters.
[
.: Matches any single character.
x: Matches the character x so long as x has no other significance.
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 "
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 " are not used as
delimiters but are included in the returned word instead (without
the "
" ).
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).
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.
" 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 "
" and " $" . The following atoms are allowed:
chars]: Matches anything but the specified characters.
x: Always matches the character x (except for [dDsSwW]).
d: Matches a single digit.
D: Matches anything but a single digit.
w: Matches any alphanumeric character, and " _" .
W: Matches anything but alphanumeric characters, and " _" .
s: Matches white space.
S: Matches anything but white space.
"
character to separate them. The test string is compared against
each one in turn until a match is found.
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
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 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.
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
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.
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.
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
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 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.
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.