astReallocastRealloc - Change the size of a dynamically allocated region of memory

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