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 lstltc_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
       lstltc_c ( Last character element less than )

       SpiceInt lstltc_c ( ConstSpiceChar  * string,
                           SpiceInt          n,
                           SpiceInt          arrlen,
                           const void      * array   )
#### Abstract
       Find the index of the largest array element less than 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 `string'.
#### Detailed_Input
       string      is a string acting as an upper bound: the element of
                   `array' that is lexically the greatest element less than
                   `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 `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 or equal to
       `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 lstltc_c.

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

          lstltc_c ( "NEWTON",   5, arrlen, array )    ==   3
          lstltc_c ( "EINSTEIN", 5, arrlen, array )    ==   0
          lstltc_c ( "GALILEO",  5, arrlen, array )    ==   2
          lstltc_c ( "Galileo",  5, arrlen, array )    ==   3
          lstltc_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.2.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.1.0, 07-MAR-2009 (NJB)

           This file now includes the header file f2cMang.h.
           This header supports name mangling of f2c library
           functions.

       -CSPICE Version 1.0.0, 22-JUL-2002 (NJB) (HAN) (WLT)
#### Index_Entries
       last character element less_than
#### Link to routine lstltc_c source file lstltc_c.c

    Fri Dec 31 18:41:09 2021