1 /*
2 
3 -Procedure lstltd_c ( Last double precision element less than)
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 x.
9 
10 -Disclaimer
11 
12    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
13    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
14    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
15    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
16    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
17    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
18    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
19    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
20    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
21    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
22 
23    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
24    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
25    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
26    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
27    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
28    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
29 
30    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
31    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
32    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
33    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
34 
35 -Required_Reading
36 
37    None.
38 
39 -Keywords
40 
41    SEARCH,  ARRAY
42 
43 */
44 
45    #include "SpiceUsr.h"
46    #include "SpiceZfc.h"
47    #include "SpiceZim.h"
48    #undef    lstltd_c
49 
lstltd_c(SpiceDouble x,SpiceInt n,ConstSpiceDouble * array)50    SpiceInt lstltd_c ( SpiceDouble         x,
51                        SpiceInt            n,
52                        ConstSpiceDouble  * array )
53 /*
54 
55 -Brief_I/O
56 
57    VARIABLE  I/O  DESCRIPTION
58    --------  ---  --------------------------------------------------
59    x          I   Value to search against
60    n          I   Number elements in array
61    array      I   Array of possible lower bounds
62 
63    The function returns the index of the last element of array that
64    is less than x.
65 
66 -Detailed_Input
67 
68    x       Double precision number.
69 
70    n       Total number of elements in array.
71 
72    array   Array of double precision numbers which forms a
73            non-decreasing sequence.  The elements of array need not be
74            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 x.  The routine assumes the array elements
81    are sorted in non-decreasing order.
82 
83    Indices range from 0 to n-1.
84 
85    If all elements of the input array are greater than or equal to x,
86    the function returns -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 or equal to x, simply add 1 to the
110           result returned by this function and check to see if the
111           result is 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.0;
118           array[1] = -2.0;
119           array[2] =  0.0;
120           array[3] =  1.0;
121           array[4] =  1.0;
122           array[5] = 11.0;
123 
124 
125        The table below demonstrates the behavior of lstltd_c:
126 
127                     Call                       Returned Value
128           ===========================          ==============
129           lstltd_c ( -3.0, 6, array )                -1
130 
131           lstltd_c ( -2.0, 6, array )                -1
132 
133           lstltd_c (  0.0, 6, array )                 1
134 
135           lstltd_c (  1.0, 6, array )                 2
136 
137           lstltd_c ( 11.1, 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 d.p. element less_than
162 
163 -&
164 */
165 
166 { /* Begin lstltd_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) lstltd_ (  (doublereal *) &x,
175                                  (integer    *) &n,
176                                  (doublereal *) array )   -  1 );
177 
178 } /* End lstltd_c */
179