lstltc_c

Index Page lstltc_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 lstltc_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
       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 string.
#### Detailed_Input
       string      is a string acting as an upper bound:  the array element
                   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 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 lexically less than string.  The routine assumes
       the array elements are sorted in non-decreasing order.

       If all elements of the input array are greater than or equal to 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 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][lenvals]

       which contains the following elements:

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

       Then

          lstltc_c ( "NEWTON",   5, lenvals, array )    ==   3
          lstltc_c ( "EINSTEIN", 5, lenvals, array )    ==   0
          lstltc_c ( "GALILEO",  5, lenvals, array )    ==   2
          lstltc_c ( "Galileo",  5, lenvals, array )    ==   3
          lstltc_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.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

    Thu Apr 16 08:58:31 2009