Procedure

   lstled_c ( Last double precision element less than or equal) 

   SpiceInt lstled_c ( SpiceDouble         x,
                       SpiceInt            n,
                       ConstSpiceDouble  * array )

Abstract

   Find the index of the largest array element less than or equal
   to a given number `x' in an array of non-decreasing numbers.

Required_Reading

   None.

Keywords

   ARRAY
   SEARCH

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   x          I   Upper bound value to search against.
   n          I   Number of elements in `array'.
   array      I   Array of possible lower bounds.

   The function returns the index of the last element of `array' that
   is less than or equal to `x'.

Detailed_Input

   x           is a double precision value acting as an upper bound: the
               element of `array' that is the greatest element less than
               or equal to `x' is to be found.

   n           is the total number of elements in `array'.

   array       is an array of double precision numbers that forms a
               non-decreasing sequence. 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 `x'. 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 greater than `x', the routine returns
   the value -1. If `n' is less than or equal to zero, the routine
   returns the value -1.

Parameters

   None.

Exceptions

   Error free.

   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.

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 lstled_c.

   Note: If you need to find the first element of the array that is
   greater than `x', 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

   1)  Let array be assigned the following values:

          array[0] = -2.0;
          array[1] = -2.0;
          array[2] =  0.0;
          array[3] =  1.0;
          array[4] =  1.0;
          array[5] = 11.0;


       The table below demonstrates the behavior of lstled_c:

                    Call                       Returned Value
          ===========================          ==============
          lstled_c ( -3.0, 6, array )                -1

          lstled_c ( -2.0, 6, array )                 1

          lstled_c (  0.0, 6, array )                 2

          lstled_c (  1.0, 6, array )                 4

          lstled_c ( 11.1, 6, array )                 5

Restrictions

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

Literature_References

   None.

Author_and_Institution

   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   W.L. Taber          (JPL)

Version

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

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

   -CSPICE Version 1.0.0, 09-JUL-2002 (NJB) (WLT)

Index_Entries

   last d.p. element less_than_or_equal_to