valid_c |

Table of contents## Procedurevalid_c ( Validate a set ) void valid_c ( SpiceInt size, SpiceInt n, SpiceCell * a ) ## AbstractCreate a valid SPICE set from a SPICE Cell of any data type. ## Required_ReadingSETS ## KeywordsCELLS SETS ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- size I Size (maximum cardinality) of the set. n I Initial no. of (possibly non-distinct) elements. a I-O Set to be validated. ## Detailed_Inputsize is the maximum cardinality (number of elements) of the set. `size' must not exceed the declared size of the set's data array. n is the number of (possibly non-distinct) elements initially contained in the set's data array. `n' cannot be greater than the size of the set. a is a SPICE set. On input, `a' contains `n' elements. `a' must be declared as a character, double precision or integer SpiceCell. CSPICE provides the following macros, which declare and initialize the cell SPICECHAR_CELL ( a, ASZ, AMLEN ); SPICEDOUBLE_CELL ( a, ASZ ); SPICEINT_CELL ( a, ASZ ); where ASZ is the maximum capacity of `a' and AMLEN is the maximum length of any member in the character cell. ## Detailed_Outputa on output, is a valid set created from the input set. To create a valid set, the elements are ordered, and duplicate elements are removed. The set's size and cardinality members are assigned their correct values. The set is ready for use with other set routines. When validating a character set, trailing blanks are not considered significant in process of sorting and removing duplicates. Trailing blanks are not preserved on output. ## ParametersNone. ## Exceptions1) If the size of the set is too small to hold the set BEFORE validation, the error SPICE(INVALIDSIZE) is signaled by a routine in the call tree of this routine. The set `a' is not modified. 2) If the cell argument does not have a recognized data type, the error SPICE(NOTSUPPORTED) is signaled. 3) If the cell argument is of type SpiceChar and the string length associated with it is non-positive or too short to be usable when constructing the equivalent SPICE character cell required by the wrapped SPICELIB routine, an error is signaled by a routine in the call tree of this routine. ## FilesNone. ## ParticularsBecause a set is ordered and contains distinct values, to create a set from a cell, it is necessary to sort the data array and remove duplicates. Once the array has been sorted, duplicate elements (adjacent after sorting) are removed. The size and cardinality of the set are initialized, and the set is ready to go. This routine is typically used to create a SPICE set from a SPICE cell whose array which has been initialized via calls the appndX_c routines, or through compile-time array initializers, or I/O statements. The resulting set can then be used with the other set routines. When a set is constructed from a large set of unordered values, it is far more efficient to append the values to the set and then validate the set, than to build up the set via calls to the insrtX_c routines. The latter sort the set and remove duplicates on each insertion. Because validation is done in place, there is no chance of overflow. ## ExamplesThe numerical results shown for this example may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, and the machine specific arithmetic implementation. 1) Build a double precision cell via a series of calls to appndd_c. Create a set from this set by calling ## Restrictions1) String comparisons performed by this routine are Fortran-style: trailing blanks in the input sets 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. ## Literature_ReferencesNone. ## Author_and_InstitutionN.J. Bachman (JPL) C.A. Curzon (JPL) J. Diaz del Rio (ODC Space) W.L. Taber (JPL) I.M. Underwood (JPL) E.D. Wright (JPL) ## Version-CSPICE Version 1.1.0, 24-NOV-2021 (JDR) Changed the argument name "set" to "a" for consistency with other routines. Edited the header to comply with NAIF standard. Extended code example to generate outputs and inserted example's solution. Moved misplaced documentation from -Literature_References to -Restrictions. Extended description of argument "a" in -Detailed_Input to include type and preferred declaration method. Added entries #2 and #3 in -Exceptions section. -CSPICE Version 1.0.1, 12-NOV-2006 (EDW) Corrected minor typo, the -Literature_References header lacked the prefix "-". -CSPICE Version 1.0.0, 08-AUG-2002 (NJB) (CAC) (WLT) (IMU) ## Index_Entriesvalidate a set |

Fri Dec 31 18:41:14 2021