1 /*
2 
3 -Procedure bsrchd_c ( Binary search for a double precision value )
4 
5 -Abstract
6 
7    Do a binary search for a key value within a double precision array,
8    assumed to be in increasing order. Return the index of the matching
9    array entry, or -1 if the key value is not found.
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    ARRAY
43    SEARCH
44 
45 */
46 
47    #include "SpiceUsr.h"
48    #include "SpiceZfc.h"
49    #include "SpiceZim.h"
50    #undef    bsrchd_c
51 
bsrchd_c(SpiceDouble value,SpiceInt ndim,ConstSpiceDouble * array)52    SpiceInt bsrchd_c ( SpiceDouble          value,
53                        SpiceInt             ndim,
54                        ConstSpiceDouble   * array )
55 /*
56 
57 -Brief_I/O
58 
59    VARIABLE  I/O  DESCRIPTION
60    --------  ---  --------------------------------------------------
61    value      I   Value to find in array.
62    ndim       I   Dimension of array.
63    array      I   Array to be searched.
64 
65    The function returns the index of the input key value in the
66    input array, or -1 if the value is not found.
67 
68 -Detailed_Input
69 
70    value       is the value to be found in the input array.
71 
72    ndim        is the number of elements in the input array.
73 
74    array       is the array to be searched. The elements in the
75                array are assumed to sorted in increasing order.
76 
77 -Detailed_Output
78 
79    The function returns the index of the input value in the input array.
80    Indices range from zero to ndim-1.
81 
82    If the input array does not contain the specified value, the function
83    returns -1.
84 
85    If the input array contains more than one occurrence of the specified
86    value, the returned index may point to any of the occurrences.
87 
88 -Parameters
89 
90    None.
91 
92 -Exceptions
93 
94    Error free.
95 
96    If ndim < 1 the value of the function is -1.
97 
98 -Files
99 
100    None.
101 
102 -Particulars
103 
104    A binary search is performed on the input array. If an element of
105    the array is found to match the input value, the index of that
106    element is returned. If no matching element is found, -1 is
107    returned.
108 
109 -Examples
110 
111    Let array contain the following elements:
112 
113       -11.0
114         0.0
115        22.0
116       750.0
117 
118    Then
119 
120       bsrchd_c ( -11.0, 4, array )   ==  0
121       bsrchd_c (  22.0, 4, array )   ==  2
122       bsrchd_c ( 751.0, 4, array )   == -1
123 
124 -Restrictions
125 
126    array is assumed to be sorted in increasing order. If this
127    condition is not met, the results of bsrchd_c are unpredictable.
128 
129 -Author_and_Institution
130 
131    N.J. Bachman    (JPL)
132    I.M. Underwood  (JPL)
133 
134 -Literature_References
135 
136    None.
137 
138 -Version
139 
140    -CSPICE Version 1.0.0, 22-AUG-2002 (NJB) (IMU)
141 
142 -Index_Entries
143 
144    binary search for a double precision value
145 
146 -&
147 */
148 
149 { /* Begin bsrchd_c */
150 
151 
152    /*
153    Note that we adjust the return value to make it a C-style index.
154    */
155 
156    return (   bsrchd_ ( (doublereal *) &value,
157                         (integer    *) &ndim,
158                         (doublereal *) array  )   - 1  );
159 
160 } /* End bsrchd_c */
161 
162