Table of contents
CSPICE_VALID creates a valid SPICE set from a SPICE Cell of any data type.
Given:
size the scalar integer defining the maximum cardinality (number of
elements) of `a'.
help, size
LONG = Scalar
`size' must not exceed the declared size of the set's data
array.
n the scalar integer number of (possibly non-distinct) elements
initially contained in the set's data array.
help, n
LONG = Scalar
`n' cannot be greater than the size of the set `size'.
a a SPICE cell of any data type.
help, a
STRUCT = cspice_celld(N) or STRUCT = cspice_celli(N)
`a' must be declared double precision, or integer.
The user must create `a' using either cspice_celld
or cspice_celli.
the call:
cspice_valid, size, n, a
returns:
a on output is a valid set created from the input cell `a'.
help, a
STRUCT = cspice_celld(R) or STRUCT = cspice_celli(R)
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.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Generate a list of ten double precision values, from 9 to 0,
and append them to a cell. Check if the cell, after the append
operation is a set. Validate the cell as a set, and verify
that now the cell is indeed a set.
Example code begins here.
PRO valid_ex1
;;
;; Create the cell...
;;
SIZE = 100L
INISIZ = 10L
;;
;; Create a set `a' of size 'SIZE'
;;
a = cspice_celld( SIZE )
;;
;; Generate a list of double precision values, 0 to INISIZ-1.
;; Reverse the order of the list so that in descending order.
;;
list = reverse( dindgen( INISIZ ) )
;;
;; Add the `list' data to set `a'.
;;
cspice_appndd, list, a
print, 'Initial cell:'
for i=0, cspice_card(a)-1 do begin
print, a.base[ a.data + i]
endfor
;;
;; After the append, does the cell key as a set?
;;
if( a.isset ) then print, "Cell is a set after append."
if( ~a.isset ) then print, "Cell is not a set after append."
;;
;; Validate the cell as a set, ordered elements and
;; duplicate elements are removed, ordered as ascending
;; value.
;;
cspice_valid, SIZE , INISIZ, a
;;
;; Output the new set elements
;;
print, 'Cell after cspice_valid call:'
for i=0, cspice_card(a)-1 do begin
print, a.base[ a.data + i]
endfor
;;
;; After the cspice_valid call, does the cell key as a set?
;;
if( a.isset ) then print, "Cell is a set after validate."
if( ~a.isset ) then print, "Cell is not a set after validate."
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Initial cell:
9.0000000
8.0000000
7.0000000
6.0000000
5.0000000
4.0000000
3.0000000
2.0000000
1.0000000
0.0000000
Cell is not a set after append.
Cell after cspice_valid call:
0.0000000
1.0000000
2.0000000
3.0000000
4.0000000
5.0000000
6.0000000
7.0000000
8.0000000
9.0000000
Cell is a set after validate.
The user must create any needed cell structures with cspice_celld,
cspice_celli prior to use regardless of whether the routine
uses the cell as input or returns it as output.
Because 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 cspice_appndX
routines. 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
cspice_insrtX routines. The latter sort the set and remove duplicates
on each insertion.
Because validation is done in place, there is no chance of
overflow.
1) 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 is not
modified.
2) If any of the input arguments, `size', `n' or `a', is
undefined, an error is signaled by the IDL error handling
system.
3) If any of the input arguments, `size', `n' or `a', is not of
the expected type, or it does not have the expected dimensions
and size, an error is signaled by the Icy interface.
None.
None.
ICY.REQ
CELLS.REQ
SETS.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 24-NOV-2021 (JDR)
Added arguments' type and size information in the -I/O section.
Changed the argument name "set" to "a" for consistency with other
routines.
Edited the header to comply with NAIF standard. Added example's
problem statement and reformatted example's output.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
-Icy Version 1.0.1, 14-JAN-2009 (EDW)
Corrected code error in Example; replaced a cspice_insrtd call.
with a cspice_appndd call. Edited argument descriptions in -I/O
section for clarity.
-Icy Version 1.0.0, 12-SEP-2006 (EDW)
validate a set
|