astStringArrayastStringArray - Create an array of C strings from an array of characters

Description:
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 )
Parameters:
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.
Returned Value:
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.

Notes:
  • 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.