1 /* 2 3 -Procedure appndc_c ( Append an item to a character cell ) 4 5 -Abstract 6 7 Append an item to a character cell. 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 -Keywords 39 40 CELLS 41 42 */ 43 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 #include "SpiceZmc.h" 48 #include "f2cMang.h" 49 50 appndc_c(ConstSpiceChar * item,SpiceCell * cell)51 void appndc_c ( ConstSpiceChar * item, 52 SpiceCell * cell ) 53 54 /* 55 56 -Brief_I/O 57 58 VARIABLE I/O DESCRIPTION 59 -------- --- -------------------------------------------------- 60 item I The item to append. 61 cell I/O The cell to which item will be appended. 62 63 -Detailed_Input 64 65 item is a character string which is to be appended to cell. 66 67 cell is a character SpiceCell to which item will be appended. 68 69 -Detailed_Output 70 71 cell is the input SpiceCell with item appended. item is the 72 last member of cell. 73 74 If cell is actually a CSPICE set on input and ceases to 75 qualify as a set as result of the append operation, 76 the isSet member of cell will be set to SPICEFALSE. 77 78 -Parameters 79 80 None. 81 82 -Exceptions 83 84 1) If the input cell argument is a SpiceCell of type other than 85 character, the error SPICE(TYPEMISMATCH) is signaled. 86 87 2) If the cell is not large enough to accommodate the addition 88 of a new element, the error SPICE(CELLTOOSMALL) is signaled. 89 90 3) If the length of the item is longer than the length of the 91 cell, ITEM is truncated on the right. 92 93 4) If on input cell is actually a CSPICE set, that is, it 94 contains sorted elements with no duplicates, and if item 95 is not strictly greater than the last element, on output the 96 isSet member of cell will be set to SPICEFALSE. This case 97 is not considered an error. 98 99 5) If the input string pointer is null, the error SPICE(NULLPOINTER) 100 is signaled. 101 102 -Files 103 104 None. 105 106 -Particulars 107 108 None. 109 110 -Examples 111 112 1) In the following example, the item "PLUTO" is appended to 113 the character cell planets. planets is declared with 114 string length NAMLEN. 115 116 #include "SpiceUsr.h" 117 . 118 . 119 . 120 /. 121 Declare the cell with string length NAMLEN and with maximum 122 number of elements MAXSIZ. 123 ./ 124 SPICECHAR_CELL ( planets, MAXSIZ, NAMLEN ); 125 . 126 . 127 . 128 /. 129 Before appending "PLUTO", suppose the cell planets' data array 130 contains: 131 132 Element 0: == "MERCURY" 133 Element 1: == "VENUS" 134 Element 2: == "EARTH" 135 Element 3: == "MARS" 136 Element 4: == "JUPITER" 137 Element 5: == "SATURN" 138 Element 6: == "URANUS" 139 Element 7: == "NEPTUNE" 140 141 Append the string "PLUTO" at index 8, and update the 142 cell's cardinality. 143 ./ 144 145 appndc_c ( "PLUTO", &planets ); 146 147 /. 148 The cell's data array now has the contents 149 150 Element 0: == "MERCURY" 151 Element 1: == "VENUS" 152 Element 2: == "EARTH" 153 Element 3: == "MARS" 154 Element 4: == "JUPITER" 155 Element 5: == "SATURN" 156 Element 6: == "URANUS" 157 Element 7: == "NEPTUNE" 158 Element 8: == "PLUTO" 159 ./ 160 161 -Restrictions 162 163 1) String comparisons performed by this routine are Fortran-style: 164 trailing blanks in the input array or key value are ignored. 165 This gives consistent behavior with CSPICE code generated by 166 the f2c translator, as well as with the Fortran SPICE Toolkit. 167 168 Note that this behavior is not identical to that of the ANSI 169 C library functions strcmp and strncmp. 170 171 -Literature_References 172 173 None. 174 175 -Author_and_Institution 176 177 N.J. Bachman (JPL) 178 H.A. Neilan (JPL) 179 180 -Version 181 182 -CSPICE Version 1.1.0, 07-MAR-2009 (NJB) 183 184 This file now includes the header file f2cMang.h. 185 This header supports name mangling of f2c library 186 functions. 187 188 Header sections were re-ordered. 189 190 -CSPICE Version 1.0.0, 21-AUG-2002 (NJB) (HAN) 191 192 -Index_Entries 193 194 append an item to a character cell 195 196 -& 197 */ 198 199 { /* Begin appndc_c */ 200 201 202 /* 203 f2c library utility prototypes 204 */ 205 extern integer s_cmp (char *a, char *b, ftnlen la, ftnlen lb ); 206 207 208 /* 209 Local variables 210 */ 211 SpiceChar * sPtr; 212 213 SpiceInt card; 214 SpiceInt diff; 215 216 217 /* 218 Use discovery check-in. 219 */ 220 if ( return_c() ) 221 { 222 return; 223 } 224 225 226 /* 227 Check the input string pointer to make sure it's not null. 228 */ 229 CHKPTR ( CHK_DISCOVER, "appndc_c", item ); 230 231 232 /* 233 Make sure we're working with a character cell. 234 */ 235 CELLTYPECHK ( CHK_DISCOVER, "appndc_c", SPICE_CHR, cell ); 236 237 238 /* 239 Initialize the cell if necessary. 240 */ 241 CELLINIT ( cell ); 242 243 244 card = cell->card; 245 246 if ( card == cell->size ) 247 { 248 chkin_c ( "appndc_c" ); 249 setmsg_c ( "The cell cannot accommodate the addition of the " 250 "element *" ); 251 errch_c ( "*", item ); 252 sigerr_c ( "SPICE(CELLTOOSMALL)" ); 253 chkout_c ( "appndc_c" ); 254 return; 255 } 256 257 258 if ( ( cell->isSet ) && ( card > 0 ) ) 259 { 260 /* 261 The item must be strictly greater than its predecessor, or 262 the input cell is no longer a set. 263 */ 264 sPtr = SPICE_CELL_ELEM_C(cell, card-1 ); 265 266 diff = s_cmp ( (char *) item, 267 (char *) sPtr, 268 (ftnlen ) strlen(item), 269 (ftnlen ) strlen(sPtr) ); 270 271 if ( diff < 1 ) 272 { 273 cell->isSet = SPICEFALSE; 274 } 275 } 276 277 278 /* 279 Append the item to the cell and increment the cell's cardinality. 280 */ 281 SPICE_CELL_SET_C ( item, card, cell ); 282 283 (cell->card) ++; 284 285 286 } /* End appndc_c */ 287