1 /* 2 3 -Header_File SpiceCel.h ( CSPICE Cell definitions ) 4 5 -Abstract 6 7 Perform CSPICE definitions for the SpiceCell data type. 8 9 -Disclaimer 10 11 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 12 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 13 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 14 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 15 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 16 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 17 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 18 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 19 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 20 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 21 22 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 23 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 24 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 25 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 26 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 27 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 28 29 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 30 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 31 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 32 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 33 34 -Required_Reading 35 36 CELLS 37 38 -Particulars 39 40 This header defines structures, macros, and enumerated types that 41 may be referenced in application code that calls CSPICE cell 42 functions. 43 44 CSPICE cells are data structures that implement functionality 45 parallel to that of the cell abstract data type in SPICELIB. In 46 CSPICE, a cell is a C structure containing bookkeeping information, 47 including a pointer to an associated data array. 48 49 For numeric data types, the data array is simply a SPICELIB-style 50 cell, including a valid control area. For character cells, the data 51 array has the same number of elements as the corresponding 52 SPICELIB-style cell, but the contents of the control area are not 53 maintained, and the data elements are null-terminated C-style 54 strings. 55 56 CSPICE cells should be declared using the declaration macros 57 provided in this header file. See the table of macros below. 58 59 60 Structures 61 ========== 62 63 Name Description 64 ---- ---------- 65 66 SpiceCell Structure containing CSPICE cell metadata. 67 68 The members are: 69 70 dtype: Data type of cell: character, 71 integer, or double precision. 72 73 dtype has type 74 SpiceCellDataType. 75 76 length: For character cells, the 77 declared length of the 78 cell's string array. 79 80 size: The maximum number of data 81 items that can be stored in 82 the cell's data array. 83 84 card: The cell's "cardinality": the 85 number of data items currently 86 present in the cell. 87 88 isSet: Boolean flag indicating whether 89 the cell is a CSPICE set. 90 Sets have no duplicate data 91 items, and their data items are 92 stored in increasing order. 93 94 adjust: Boolean flag indicating whether 95 the cell's data area has 96 adjustable size. Adjustable 97 size cell data areas are not 98 currently implemented. 99 100 init: Boolean flag indicating whether 101 the cell has been initialized. 102 103 base: is a void pointer to the 104 associated data array. base 105 points to the start of the 106 control area of this array. 107 108 data: is a void pointer to the 109 first data slot in the 110 associated data array. This 111 slot is the element following 112 the control area. 113 114 115 ConstSpiceCell A const SpiceCell. 116 117 118 119 120 Declaration Macros 121 ================== 122 123 Name Description 124 ---- ---------- 125 126 SPICECHAR_CELL ( name, size, length ) Declare a 127 character CSPICE 128 cell having cell 129 name name, 130 maximum cell 131 cardinality size, 132 and string length 133 length. The 134 macro declares 135 both the cell and 136 the associated 137 data array. The 138 name of the data 139 array begins with 140 "SPICE_". 141 142 143 SPICEDOUBLE_CELL ( name, size ) Like SPICECHAR_CELL, 144 but declares a 145 double precision 146 cell. 147 148 149 SPICEINT_CELL ( name, size ) Like 150 SPICECHAR_CELL, 151 but declares an 152 integer cell. 153 154 Assignment Macros 155 ================= 156 157 Name Description 158 ---- ---------- 159 SPICE_CELL_SET_C( item, i, cell ) Assign the ith 160 element of a 161 character cell. 162 Arguments cell 163 and item are 164 pointers. 165 166 SPICE_CELL_SET_D( item, i, cell ) Assign the ith 167 element of a 168 double precision 169 cell. Argument 170 cell is a 171 pointer. 172 173 SPICE_CELL_SET_I( item, i, cell ) Assign the ith 174 element of an 175 integer cell. 176 Argument cell is 177 a pointer. 178 179 180 Fetch Macros 181 ============== 182 183 Name Description 184 ---- ---------- 185 SPICE_CELL_GET_C( cell, i, lenout, item ) Fetch the ith 186 element from a 187 character cell. 188 Arguments cell 189 and item are 190 pointers. 191 Argument lenout 192 is the available 193 space in item. 194 195 SPICE_CELL_GET_D( cell, i, item ) Fetch the ith 196 element from a 197 double precision 198 cell. Arguments 199 cell and item are 200 pointers. 201 202 SPICE_CELL_GET_I( cell, i, item ) Fetch the ith 203 element from an 204 integer cell. 205 Arguments cell 206 and item are 207 pointers. 208 Element Pointer Macros 209 ====================== 210 211 Name Description 212 ---- ---------- 213 SPICE_CELL_ELEM_C( cell, i ) Macro evaluates 214 to a SpiceChar 215 pointer to the 216 ith data element 217 of a character 218 cell. Argument 219 cell is a 220 pointer. 221 222 SPICE_CELL_ELEM_D( cell, i ) Macro evaluates 223 to a SpiceDouble 224 pointer to the 225 ith data element 226 of a double 227 precision cell. 228 Argument cell is 229 a pointer. 230 231 SPICE_CELL_ELEM_I( cell, i ) Macro evaluates 232 to a SpiceInt 233 pointer to the 234 ith data element 235 of an integer 236 cell. Argument 237 cell is a 238 pointer. 239 240 -Literature_References 241 242 None. 243 244 -Author_and_Institution 245 246 N.J. Bachman (JPL) 247 248 -Restrictions 249 250 None. 251 252 -Version 253 254 -CSPICE Version 1.0.0, 22-AUG-2002 (NJB) 255 256 */ 257 #ifndef HAVE_SPICE_CELLS_H 258 259 #define HAVE_SPICE_CELLS_H 260 261 262 /* 263 Data type codes: 264 */ 265 typedef enum _SpiceDataType SpiceCellDataType; 266 267 268 /* 269 Cell structure: 270 */ 271 struct _SpiceCell 272 273 { SpiceCellDataType dtype; 274 SpiceInt length; 275 SpiceInt size; 276 SpiceInt card; 277 SpiceBoolean isSet; 278 SpiceBoolean adjust; 279 SpiceBoolean init; 280 void * base; 281 void * data; }; 282 283 typedef struct _SpiceCell SpiceCell; 284 285 typedef const SpiceCell ConstSpiceCell; 286 287 288 /* 289 SpiceCell control area size: 290 */ 291 #define SPICE_CELL_CTRLSZ 6 292 293 294 /* 295 Declaration macros: 296 */ 297 298 #define SPICECHAR_CELL( name, size, length ) \ 299 \ 300 static SpiceChar SPICE_CELL_##name[SPICE_CELL_CTRLSZ + size][length]; \ 301 \ 302 static SpiceCell name = \ 303 \ 304 { SPICE_CHR, \ 305 length, \ 306 size, \ 307 0, \ 308 SPICETRUE, \ 309 SPICEFALSE, \ 310 SPICEFALSE, \ 311 (void *) &(SPICE_CELL_##name), \ 312 (void *) &(SPICE_CELL_##name[SPICE_CELL_CTRLSZ]) } 313 314 315 #define SPICEDOUBLE_CELL( name, size ) \ 316 \ 317 static SpiceDouble SPICE_CELL_##name [SPICE_CELL_CTRLSZ + size]; \ 318 \ 319 static SpiceCell name = \ 320 \ 321 { SPICE_DP, \ 322 0, \ 323 size, \ 324 0, \ 325 SPICETRUE, \ 326 SPICEFALSE, \ 327 SPICEFALSE, \ 328 (void *) &(SPICE_CELL_##name), \ 329 (void *) &(SPICE_CELL_##name[SPICE_CELL_CTRLSZ]) } 330 331 332 #define SPICEINT_CELL( name, size ) \ 333 \ 334 static SpiceInt SPICE_CELL_##name [SPICE_CELL_CTRLSZ + size]; \ 335 \ 336 static SpiceCell name = \ 337 \ 338 { SPICE_INT, \ 339 0, \ 340 size, \ 341 0, \ 342 SPICETRUE, \ 343 SPICEFALSE, \ 344 SPICEFALSE, \ 345 (void *) &(SPICE_CELL_##name), \ 346 (void *) &(SPICE_CELL_##name[SPICE_CELL_CTRLSZ]) } 347 348 349 /* 350 Access macros for individual elements: 351 */ 352 353 /* 354 Data element pointer macros: 355 */ 356 357 #define SPICE_CELL_ELEM_C( cell, i ) \ 358 \ 359 ( ( (SpiceChar *) (cell)->data ) + (i)*( (cell)->length ) ) 360 361 362 #define SPICE_CELL_ELEM_D( cell, i ) \ 363 \ 364 ( ( (SpiceDouble *) (cell)->data )[(i)] ) 365 366 367 #define SPICE_CELL_ELEM_I( cell, i ) \ 368 \ 369 ( ( (SpiceInt *) (cell)->data )[(i)] ) 370 371 372 /* 373 "Fetch" macros: 374 */ 375 376 #define SPICE_CELL_GET_C( cell, i, lenout, item ) \ 377 \ 378 { \ 379 SpiceInt nBytes; \ 380 \ 381 nBytes = brckti_c ( (cell)->length, 0, (lenout-1) ) \ 382 * sizeof ( SpiceChar ); \ 383 \ 384 memmove ( (item), SPICE_CELL_ELEM_C((cell), (i)), nBytes ); \ 385 \ 386 item[nBytes] = NULLCHAR; \ 387 } 388 389 390 #define SPICE_CELL_GET_D( cell, i, item ) \ 391 \ 392 ( (*item) = ( (SpiceDouble *) (cell)->data)[i] ) 393 394 395 #define SPICE_CELL_GET_I( cell, i, item ) \ 396 \ 397 ( (*item) = ( (SpiceInt *) (cell)->data)[i] ) 398 399 400 /* 401 Assignment macros: 402 */ 403 404 #define SPICE_CELL_SET_C( item, i, cell ) \ 405 \ 406 { \ 407 SpiceChar * sPtr; \ 408 SpiceInt nBytes; \ 409 \ 410 nBytes = brckti_c ( strlen(item), 0, (cell)->length - 1 ) \ 411 * sizeof ( SpiceChar ); \ 412 \ 413 sPtr = SPICE_CELL_ELEM_C((cell), (i)); \ 414 \ 415 memmove ( sPtr, (item), nBytes ); \ 416 \ 417 sPtr[nBytes] = NULLCHAR; \ 418 } 419 420 421 #define SPICE_CELL_SET_D( item, i, cell ) \ 422 \ 423 ( ( (SpiceDouble *) (cell)->data)[i] = (item) ) 424 425 426 #define SPICE_CELL_SET_I( item, i, cell ) \ 427 \ 428 ( ( (SpiceInt *) (cell)->data)[i] = (item) ) 429 430 431 /* 432 The enum SpiceTransDir is used to indicate language translation 433 direction: C to Fortran or vice versa. 434 */ 435 enum _SpiceTransDir { C2F = 0, F2C = 1 }; 436 437 typedef enum _SpiceTransDir SpiceTransDir; 438 439 440 #endif 441 442