Procedure

   lstlec_c ( Last character element less than or equal to. ) 

   SpiceInt lstlec_c ( ConstSpiceChar  * string,
                       SpiceInt          n,
                       SpiceInt          arrlen,
                       const void      * array   )

Abstract

   Find the index of the largest array element less than or equal to
   a given character string in an ordered array of character strings.

Required_Reading

   None.

Keywords

   ARRAY
   SEARCH

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   string     I   Upper bound value to search against.
   n          I   Number of elements in `array'.
   arrlen     I   Declared length of the strings in `array'.
   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 element of
               `array' 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 total number of elements in `array'.

   arrlen      is the declared length of the strings in the input
               string array, including null terminators. The input
               array should be declared with dimension

                  [n][arrlen]

   array       is an array of character strings to be searched. Trailing
               blanks in the strings in this array are not significant.
               The strings in `array' 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 lexically less than or equal to `string'.
   The routine assumes the array elements are sorted in
   non-decreasing order.

   Indices range from 0 to n-1.

   If all elements of `array' are lexically greater than `string', the
   routine returns the value -1. If `n' is less than or equal to zero,
   the routine returns the value -1.

Parameters

   None.

Exceptions

   1)  If `n' is less than or equal to zero, the function returns -1.
       This case is not treated as an error.

   2)  If the input array is not sorted in non-decreasing order, the
       output of this routine is undefined. No error is signaled.

   3)  If the `string' input string pointer is null, the error
       SPICE(NULLPOINTER) is signaled. The function returns the value
       -1.

   4)  If the `array' input array pointer is null, the error
       SPICE(NULLPOINTER) is signaled. The function returns the value
       -1.

   5)  If the `array' input array strings have length less than two
       characters, the error SPICE(STRINGTOOSHORT) is signaled. The
       function returns the value -1.

Files

   None.

Particulars

   This routine uses a binary search algorithm and so requires
   at most on the order of

      log (n)
         2

   steps to compute the value of lstlec_c.

   Note: If you need to find the first element of the array that is
   lexically 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][arrlen]

   which contains the following elements:

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

   Then

      lstlec_c ( "NEWTON",   5, arrlen, array )    ==   4
      lstlec_c ( "EINSTEIN", 5, arrlen, array )    ==   1
      lstlec_c ( "GALILEO",  5, arrlen, array )    ==   3
      lstlec_c ( "Galileo",  5, arrlen, array )    ==   3
      lstlec_c ( "BETHE",    5, arrlen, array )    ==  -1

Restrictions

   1)  If the sequence of character strings in the input array `array'
       is not non-decreasing, the program will run to completion but
       the index found will not mean anything.

   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)
   J. Diaz del Rio     (ODC Space)
   H.A. Neilan         (JPL)
   W.L. Taber          (JPL)

Version

   -CSPICE Version 1.1.0, 01-NOV-2021 (JDR)

       Changed the input argument name "lenvals" to "arrlen" for consistency
       with other routines.

       Edited the header to comply with NAIF standard. Improved
       -Detailed_Input, -Detailed_Output, -Particulars, -Exceptions and
       -Restrictions sections.

   -CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (HAN) (WLT)

Index_Entries

   last character element less_than_or_equal_to