1 /* 2 3 -Procedure card_c ( Cardinality of a cell ) 4 5 -Abstract 6 7 Return the cardinality (current number of elements) in a 8 cell of any data type. 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 CELLS 38 39 -Keywords 40 41 CELLS 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZmc.h" 47 card_c(SpiceCell * cell)48 SpiceInt card_c ( SpiceCell * cell ) 49 50 /* 51 52 -Brief_I/O 53 54 VARIABLE I/O DESCRIPTION 55 -------- --- -------------------------------------------------- 56 cell I Input cell. 57 58 The function returns the cardinality of the input cell. 59 60 -Detailed_Input 61 62 cell is a cell of character, double precision, or 63 integer data type. 64 65 -Detailed_Output 66 67 The function returns the cardinality of (current number of elements 68 in) the input cell. 69 70 -Parameters 71 72 None. 73 74 -Exceptions 75 76 1) If the input cell has invalid cardinality, the error 77 SPICE(INVALIDCARDINALITY) is signaled. card_c returns 78 an unspecified value in this case. 79 80 2) If the input array has invalid size, the error 81 SPICE(INVALIDSIZE) is signaled. card_c returns 82 an unspecified value in this case. 83 84 -Files 85 86 None. 87 88 -Particulars 89 90 This is a generic function which may be used on SpiceCells of 91 character, double precision, or integer data type. 92 93 -Examples 94 95 The cardinality function card_c is typically used to process 96 each of the elements of a cell. In the following example, cardc_c 97 is used to step through the individual elements of the character 98 cell names. 99 100 #include "SpiceUsr.h" 101 . 102 . 103 . 104 /. 105 Declare the cell names with string length LNSIZE and maximum 106 number of strings SIZE. 107 ./ 108 SPICECHAR_CELL ( names, SIZE, LNSIZE ); 109 . 110 . 111 . 112 for ( i = 0; i < card_c(&names); i++ ) 113 { 114 . 115 . 116 . 117 } 118 119 In conjunction with the size_c function, card_c may be used 120 to predict (and subsequently avoid) overflows when manipulating 121 cells. In the following example, size_c is used to determine 122 whether the integer cell original can be safely copied into 123 the integer cell save before actually attempting the operation. 124 If original contains more elements than save can hold, then 125 the operation would fail. 126 127 if ( card_c(&original) <= size_c(&save) ) 128 { 129 copy_c ( &original, &save ); 130 } 131 else 132 { 133 . 134 . 135 . 136 } 137 138 -Restrictions 139 140 None. 141 142 -Literature_References 143 144 None. 145 146 -Author_and_Institution 147 148 N.J. Bachman (JPL) 149 C.A. Curzon (JPL) 150 H.A. Neilan (JPL) 151 W.L. Taber (JPL) 152 I.M. Underwood (JPL) 153 154 -Version 155 156 -CSPICE Version 1.0.0, 06-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU) 157 158 -Index_Entries 159 160 cardinality of an integer cell 161 162 -& 163 */ 164 165 { /* Begin card_c */ 166 167 168 /* 169 Participate in error tracing. 170 */ 171 if ( return_c() ) 172 { 173 return ( cell->card ); 174 } 175 chkin_c ( "card_c" ); 176 177 178 /* 179 Initialize the cell if necessary. 180 */ 181 CELLINIT ( cell ); 182 183 184 /* 185 Check the size and cardinality of the input cell. 186 */ 187 if ( cell->size < 0 ) 188 { 189 setmsg_c ( "Invalid cell size. The size was #." ); 190 errint_c ( "#", cell->size ); 191 sigerr_c ( "SPICE(INVALIDSIZE)" ); 192 chkout_c ( "card_c" ); 193 194 return ( cell->card ); 195 } 196 197 else if ( cell->card < 0 ) 198 { 199 setmsg_c ( "Invalid cell cardinality. The " 200 "cardinality was #." ); 201 errint_c ( "#", cell->card ); 202 sigerr_c ( "SPICE(INVALIDCARDINALITY)" ); 203 chkout_c ( "card_c" ); 204 205 return ( cell->card ); 206 } 207 208 else if ( cell->card > cell->size ) 209 { 210 setmsg_c ( "Invalid cell cardinality; cardinality exceeds " 211 " cell size. The cardinality was #. The size " 212 " was #." ); 213 errint_c ( "#", cell->card ); 214 errint_c ( "#", cell->size ); 215 sigerr_c ( "SPICE(INVALIDCARDINALITY)" ); 216 chkout_c ( "card_c" ); 217 218 return ( cell->card ); 219 } 220 221 222 chkout_c ( "card_c" ); 223 224 return ( cell->card ); 225 226 227 } /* End card_c */ 228 229