Index Page lstlec_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       SpiceInt lstlec_c ( ConstSpiceChar  * string,
                           SpiceInt          n,
                           SpiceInt          lenvals,
                           const void      * array   )
#### Abstract
       Given a character string and an ordered array of character
       strings, find the index of the largest array element less than
       or equal to the given string.
#### Required_Reading
       None.
#### Keywords
       SEARCH,  ARRAY
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       string     I   Upper bound value to search against.
       n          I   Number elements in array.
       lenvals    I   String length.
       array      I   Array of possible lower bounds.

       The function returns the index of the last element of array that
       is lexically less than or equal to string.
#### Detailed_Input
       string      is a string acting as an upper bound:  the array element
                   that is lexically the greatest element less than or
                   equal to string is to be found.  Trailing blanks in this
                   bound value are not significant.

       n           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

                      [n][lenvals]

       array       is the array of character strings to be searched.
                   Trailing blanks in the strings in this array are not
                   significant. The strings must be sorted in
                   non-decreasing order. The elements of array need not be
                   distinct.
#### Detailed_Output
       The function returns the index of the highest-indexed element in the
       input array that is less than or equal to string.  The routine assumes
       the array elements are sorted in non-decreasing order.

       If all elements of the input array are greater than the specified
       upper bound string, the function returns -1.
#### Parameters
       None.
#### Exceptions
       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.
#### Files
       None.
#### Particulars
       Note:  If you need to find the first element of the array that is
              greater than string, simply add 1 to the result returned by
              this function and check to see if the result is within the
              array bounds given by n.
#### Examples
       Let array be a character array of dimension

          [5][lenvals]

       which contains the following elements:

          "BOHR"
          "EINSTEIN"
          "FEYNMAN"
          "GALILEO"
          "NEWTON"

       Then

          lstlec_c ( "NEWTON",   5, lenvals, array )    ==   4
          lstlec_c ( "EINSTEIN", 5, lenvals, array )    ==   1
          lstlec_c ( "GALILEO",  5, lenvals, array )    ==   3
          lstlec_c ( "Galileo",  5, lenvals, array )    ==   3
          lstlec_c ( "BETHE",    5, lenvals, array )    ==  -1
#### Restrictions
       1)  The input array is assumed to be sorted in increasing order. If
           this condition is not met, the results of bsrchc_c are unpredictable.

       2)  String comparisons performed by this routine are Fortran-style:
           trailing blanks in the input array or key value are ignored.
           This gives consistent behavior with CSPICE code generated by
           the f2c translator, as well as with the Fortran SPICE Toolkit.

           Note that this behavior is not identical to that of the ANSI
           C library functions strcmp and strncmp.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       H.A. Neilan     (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (HAN) (WLT)
#### Index_Entries
       last character element less_than_or_equal_to
#### Link to routine lstlec_c source file lstlec_c.c

    Wed Jun  9 13:05:26 2010