1 /*
2 
3 -Procedure lstlei_c ( Last integer element less than or equal)
4 
5 -Abstract
6 
7    Given a number x and an array of non-decreasing numbers,
8    find the index of the largest array element less than or equal
9    to x.
10 
11 -Disclaimer
12 
13    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
14    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
15    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
16    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
17    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
18    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
19    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
20    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
21    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
22    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
23 
24    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
25    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
26    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
27    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
28    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
29    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
30 
31    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
32    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
33    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
34    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
35 
36 -Required_Reading
37 
38    None.
39 
40 -Keywords
41 
42    SEARCH,  ARRAY
43 
44 */
45 
46    #include "SpiceUsr.h"
47    #include "SpiceZfc.h"
48    #include "SpiceZim.h"
49    #undef    lstlei_c
50 
lstlei_c(SpiceInt x,SpiceInt n,ConstSpiceInt * array)51    SpiceInt lstlei_c ( SpiceInt            x,
52                        SpiceInt            n,
53                        ConstSpiceInt     * array )
54 /*
55 
56 -Brief_I/O
57 
58    VARIABLE  I/O  DESCRIPTION
59    --------  ---  --------------------------------------------------
60    x          I   Value to search against
61    n          I   Number elements in array
62    array      I   Array of possible lower bounds
63 
64    The function returns the index of the last element of array that
65    is less than or equal to x.
66 
67 -Detailed_Input
68 
69    x       Integer.
70 
71    n       Total number of elements in array.
72 
73    array   Array of integers which forms a non-decreasing sequence.
74            The elements of array need not be distinct.
75 
76 
77 -Detailed_Output
78 
79    The function returns the index of the highest-indexed element in the
80    input array that is less than or equal to x.  The routine assumes
81    the array elements are sorted in non-decreasing order.
82 
83    Indices range from 0 to n-1.
84 
85    If all elements of array are greater than x, this routine returns
86    the value -1.
87 
88 -Parameters
89 
90    None.
91 
92 -Exceptions
93 
94    Error free.
95 
96    1) In the case that n is input with value less than or equal
97       to zero, the function returns -1.
98 
99    2) If the input array is not sorted in increasing order, the
100       output of this routine are undefined.  No error is signaled.
101 
102 -Files
103 
104    None.
105 
106 -Particulars
107 
108    Note:  If you need to find the first element of the array that
109           is greater than x, simply add 1 to the result returned
110           by this function and check to see if the result is
111           within the array bounds given by n.
112 
113 -Examples
114 
115    1)  Let array be assigned the following values:
116 
117           array[0] = -2;
118           array[1] = -2;
119           array[2] =  0;
120           array[3] =  1;
121           array[4] =  1;
122           array[5] = 11;
123 
124 
125        The table below demonstrates the behavior of lstlei_c:
126 
127                     Call                       Returned Value
128           =========================            ==============
129           lstlei_c ( -3, 6, array )                -1
130 
131           lstlei_c ( -2, 6, array )                 1
132 
133           lstlei_c (  0, 6, array )                 2
134 
135           lstlei_c (  1, 6, array )                 4
136 
137           lstlei_c ( 12, 6, array )                 5
138 
139 
140 -Restrictions
141 
142    If the sequence of elements in array is not non-decreasing,
143    the program will run to completion but the index found will
144    not mean anything.
145 
146 -Author_and_Institution
147 
148    N.J. Bachman    (JPL)
149    W.L. Taber      (JPL)
150 
151 -Literature_References
152 
153    None.
154 
155 -Version
156 
157    -CSPICE Version 1.0.0, 10-JUL-2002 (NJB) (WLT)
158 
159 -Index_Entries
160 
161    last integer element less_than_or_equal_to
162 
163 -&
164 */
165 
166 { /* Begin lstlei_c */
167 
168 
169   /*
170   Map the index returned by the f2c'd routine to the range 0 : n-1.
171   The return value -1 indicates "not found."
172   */
173 
174   return ( (SpiceInt) lstlei_ (  (integer *) &x,
175                                  (integer *) &n,
176                                  (integer *) array )   -  1 );
177 
178 } /* End lstlei_c */
179