1 /* 2 3 -Procedure isordv_c ( Is array an order vector? ) 4 5 -Abstract 6 7 Determine whether an array of n items contains the integers 8 0 through n-1. 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 42 SORT 43 UTILITY 44 45 */ 46 47 #include "SpiceUsr.h" 48 #include "SpiceZfc.h" 49 #include "SpiceZst.h" 50 #undef isordv_c 51 isordv_c(ConstSpiceInt * array,SpiceInt n)52 SpiceBoolean isordv_c ( ConstSpiceInt * array, 53 SpiceInt n ) 54 55 /* 56 57 -Brief_I/O 58 59 Variable I/O Description 60 -------- --- -------------------------------------------------- 61 array I Array of integers. 62 n I Number of integers in array. 63 64 The function returns SPICETRUE if the array contains the integers 65 0 through n-1, otherwise it returns SPICEFALSE. 66 67 -Detailed_Input 68 69 array is an array of integers. Often this will be an array 70 that is a candidate order vector to be passed to 71 a routine for re-ordering some parallel array. 72 73 n is the number of elements in array. 74 75 -Detailed_Output 76 77 The function returns SPICETRUE if the array contains the integers 78 1 through n. Otherwise it returns SPICEFALSE. 79 80 -Parameters 81 82 None. 83 84 -Exceptions 85 86 1) If n < 1, the function returns SPICEFALSE. 87 88 2) If memory is not available to create a local copy of the order 89 vector, the error SPICE(MALLOCFAILED) is signaled. 90 91 -Files 92 93 None. 94 95 -Particulars 96 97 This function provides a simple means of determining whether 98 or not an array of n integers contains exactly the integers 99 0 through n-1. An array with this property is called an 100 "order vector." Order vectors are returned by the CSPICE 101 routines 102 103 orderc_c 104 orderd_c 105 orderi_c 106 107 and are accepted as input by the CSPICE routines 108 109 reordc_c 110 reordd_c 111 reordi_c 112 reordl_c 113 114 -Examples 115 116 1) Suppose you wished to reorder an array of strings based upon 117 a ranking array supplied by a user. If the ranking array 118 contains any duplicates or refers to indices that are out 119 of the range of valid indices for the array of strings, 120 the attempt to reorder the array of strings cannot succeed. 121 Its usually better to detect such a possibility before 122 you begin trying to reorder the array of strings. This routine 123 will detect the error. 124 125 The code fragment below illustrates this idea. 126 127 #include "SpiceUsr.h" 128 . 129 . 130 . 131 132 if ( isordv_c ( ordvec, n ) ) 133 { 134 ...reorder the input array of strings 135 136 reordc_c ( ordvec, n, lenvals, strings ); 137 } 138 else 139 { 140 ...state the problem and let the user decide what 141 to do about it. 142 . 143 . 144 . 145 } 146 147 -Restrictions 148 149 None. 150 151 -Literature_References 152 153 None. 154 155 -Author_and_Institution 156 157 N.J. Bachman (JPL) 158 W.L. Taber (JPL) 159 I.M. Underwood (JPL) 160 161 -Version 162 163 -CSPICE Version 1.1.0, 16-FEB-2005 (NJB) 164 165 Bug fix: dynamic memory is now freed. 166 167 -CSPICE Version 1.0.0, 10-JUL-2002 (NJB) (WLT) (IMU) 168 169 -Index_Entries 170 171 test whether an integer array is an order vector 172 173 -& 174 */ 175 176 { /* Begin isordv_c */ 177 178 179 /* 180 Local variables 181 */ 182 SpiceBoolean retval; 183 184 SpiceInt i; 185 SpiceInt vSize; 186 SpiceInt * ordvec; 187 188 189 190 191 /* 192 This routine uses discovery check-in. 193 194 Initialize the return value. 195 */ 196 retval = SPICEFALSE; 197 198 /* 199 Nothing to check if the array is empty. 200 */ 201 if ( n < 1 ) 202 { 203 return ( retval ); 204 } 205 206 /* 207 Get a local copy of the input array; increment each element 208 of this local array. If the array is a C-style order vector, this 209 operation maps the vector to Fortran style. 210 */ 211 vSize = n * sizeof(SpiceInt); 212 213 ordvec = (SpiceInt *) malloc( vSize ); 214 215 if ( ordvec == 0 ) 216 { 217 chkin_c ( "isordv_c" ); 218 setmsg_c ( "Failure on malloc call to create array " 219 "for Fortran-style order vector. Tried " 220 "to allocate # bytes." ); 221 errint_c ( "#", vSize ); 222 sigerr_c ( "SPICE(MALLOCFAILED)" ); 223 chkout_c ( "isordv_c" ); 224 return ( retval ); 225 } 226 227 for ( i = 0; i < n; i++ ) 228 { 229 ordvec[i] = array[i] + 1; 230 } 231 232 233 retval = (SpiceBoolean) isordv_ ( (integer *) ordvec, 234 (integer *) &n ); 235 236 free ( ordvec ); 237 238 return ( retval ); 239 240 } /* End isordv_c */ 241 242 243 244 245 246