next up previous 264
Next: astStringCase - Convert a string to upper or lower case
Up: AST Memory Management and Utility Functions
Previous: astString - Create a C string from an array of characters


astStringArray - 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 astFree.

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.


next up previous 264
Next: astStringCase - Convert a string to upper or lower case
Up: AST Memory Management and Utility Functions
Previous: astString - Create a C string from an array of characters

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council