Insert an item into a character set.
VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- item I Item to be inserted. set I/O Insertion set.
item is an item which is to be inserted into the specified set. item may or may not already be an element of the set. Trailing blanks in item are not significant. set is a CSPICE set. set must be declared as a character SpiceCell. On input, set may or may not contain the input item as an element.
set on output contains the union of the input set and the singleton set containing the input item.
1) In the following example, the element "PLUTO" is removed from the character set planets and inserted into the character set asteroids. #include "SpiceUsr.h" . . . /. Declare the sets with string length NAMLEN and with maximum number of elements MAXSIZ. ./ SPICECHAR_CELL ( planets, MAXSIZ, NAMLEN ); SPICECHAR_CELL ( asteroids, MAXSIZ, NAMLEN ); . . . removc_c ( "PLUTO", &planets ); insrtc_c ( "PLUTO", &asteroids ); If "PLUTO" is not an element of planets, then the contents of planets are not changed. Similarly, if "PLUTO" is already an element of asteroids, the contents of asteroids remain unchanged. Because inserting an element into a set can increase the cardinality of the set, an error may occur in the insertion routines.
1) String comparisons performed by this routine are Fortran-style: trailing blanks in the input set or key value are ignored. This gives consistent behavior with CSPICE code generated by the f2c translator, as well as with the Fortran SPICE Toolkit. Note that this behavior is not identical to that of the ANSI C library functions strcmp and strncmp.
1) If the input set argument is a SpiceCell of type other than character, the error SPICE(TYPEMISMATCH) is signaled. 2) If the insertion of the element into the set causes an excess of elements, the error SPICE(SETEXCESS) is signaled. 3) If the input set argument does not qualify as a CSPICE set, the error SPICE(NOTASET) will be signaled. CSPICE sets have their data elements sorted in increasing order and contain no duplicate data elements. 4) If the input string pointer is null, the error SPICE(NULLPOINTER) is signaled.
N.J. Bachman (JPL) C.A. Curzon (JPL) W.L. Taber (JPL) I.M. Underwood (JPL)
-CSPICE Version 2.0.0, 01-NOV-2005 (NJB) Bug fix: when the item to be inserted would, after truncation to the set's string length, match an item already in the set, no insertion is performed. Previously the truncated string was inserted, corrupting the set. Long error message was updated to include size of set into which insertion was attempted. -CSPICE Version 1.0.0, 21-AUG-2002 (NJB) (CAC) (WLT) (IMU)
insert an item into a character set