Re-order the elements of an array of character strings according to a given order vector.
VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- iorder I Order vector to be used to re-order array. ndim I Dimension of array. lenvals I String length. array I/O Array to be re-ordered.
iorder is the order vector to be used to re-order the input array. The first element of iorder is the index of the first item of the re-ordered array, and so on. Note that the order imposed by reordc_c is not the same order that would be imposed by a sorting routine. In general, the order vector will have been created (by one of the order routines) for a related array, as illustrated in the example below. The elements of iorder range from zero to ndim-1. ndim is the number of elements in the input array. lenvals is the declared length of the strings in the input string array, including null terminators. The input array should be declared with dimension [ndim][lenvals] array on input, is an array containing some number of elements in unspecified order.
array on output, is the same array, with the elements in re-ordered as specified by iorder.
reordc_c uses a cyclical algorithm to re-order the elements of the array in place. After re-ordering, element iorder of the input array is the first element of the output array, element iorder of the input array is the second element of the output array, and so on. The order vector used by reordc_c is typically created for a related array by one of the order*_c routines, as shown in the example below.
In the following example, the order*_c and reord*_c routines are used to sort four related arrays (containing the names, masses, integer ID codes, and visual magnitudes for a group of satellites). This is representative of the typical use of these routines. #include "SpiceUsr.h" . . . /. Sort the object arrays by name. ./ orderc_c ( namlen, names, n, iorder ); reordc_c ( iorder, n, namlen, names ); reordd_c ( iorder, n, masses ); reordi_c ( iorder, n, codes ); reordd_c ( iorder, n, vmags );
1) If the input string array pointer is null, the error SPICE(NULLPOINTER) will be signaled. 2) If the input array string's length is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. 3) If memory cannot be allocated to create a Fortran-style version of the input order vector, the error SPICE(MALLOCFAILED) is signaled. 4) If ndim < 2, this routine executes a no-op. This case is not an error.
N.J. Bachman (JPL) W.L. Taber (JPL) I.M. Underwood (JPL)
-CSPICE Version 1.0.0, 10-JUL-2002 (NJB) (WLT) (IMU)
reorder a character array