Search for a given value within a character string array. Return the index of the first equivalent array entry, or -1 if no equivalent element is found.
VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- value I Key value to be found in array. ndim I Dimension of array. lenvals I String length. array I Character string array to search. The function returns the index of the first array entry equivalent to value, or -1 if none is found.
value is the key value to be found in the array. Trailing blanks in this key are not significant: string matches found by this routine do not require trailing blanks in value to match those in the corresponding element of array. ndim is the dimension of the 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 is the array of character srings to be searched. Trailing blanks in the strings in this array are not significant.
The function returns the index of the first element of the input array equivalent to the input value, or -1 if the array contains no such elements. Two strings are equivalent if they contain the same characters in the same order, when blanks are ignored and uppercase and lowercase characters are considered equal.
esrchc_c is identical to isrchc_c, except that it looks for the first equivalent string (as defined by eqstr_c) instead of the first identical one.
Let array be declared with dimension [NDIM][STRLEN] and contain the following elements: array == "This" array == "little" array == "piggy" array == "went" array == "to" array == "market" Then esrchc_c ( "PIGGY", NDIM, STRLEN, array ) == 2 esrchc_c ( " LiTtLe ", NDIM, STRLEN, array ) == 1 esrchc_c ( "W e n t", NDIM, STRLEN, array ) == 3 esrchc_c ( "mall", NDIM, STRLEN, array ) == -1
1) If ndim < 1 the function value is -1. This is not considered an error. 2) If input key value pointer is null, the error SPICE(NULLPOINTER) will be signaled. The function returns -1. 3) The input key value may have length zero. This case is not considered an error. 4) If the input array pointer is null, the error SPICE(NULLPOINTER) will be signaled. The function returns -1. 5) If the input array string's length is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. The function returns -1.
N.J. Bachman (JPL) I.M. Underwood (JPL)
-CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (IMU)
search array for equivalent character_string