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