Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page lstlec_c

Table of contents

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

       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

#### Link to routine lstlec_c source file lstlec_c.c

    Fri Dec 31 18:41:09 2021