Table of contents
CSPICE_CARD returns the cardinality (current number of elements) in a
cell of any data type.
Given:
cell a SPICE cell of any data type.
help, cell
STRUCT = cspice_celld(N)
or
STRUCT = cspice_celli(N)
The user must create `cell' using cspice_celli or cspice_celld,
for integer or double precision cells, respectively.
the call:
card = cspice_card( cell )
returns:
card a scalar integer describing the cardinality (current number of
elements) of the input `cell'.
help, card
LONG = Scalar
None.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) The cspice_size procedure is typically used in conjunction
with the cspice_card procedure to predict (and subsequently
avoid) overflows when manipulating cells. In the following
example, cspice_card and cspice_size are used to determine whether
the union of two sets is safe.
Example code begins here.
PRO card_ex1
;;
;; Local constants.
;;
SETDIM = 5L
;;
;; Local variables.
;;
;; Declare two SPICE cells.
;;
seta = cspice_celli( SETDIM )
setb = cspice_celli( SETDIM )
setc = cspice_celli( SETDIM )
even = [ 0L, 2L, 4L, 4L, 8L ]
items = [ 0L, 1L, 1L, 2L, 8L ]
;;
;; Initialize the empty sets.
;;
cspice_valid, SETDIM, 0L, seta
cspice_valid, SETDIM, 0L, setb
;;
;; Insert `even' on `seta' and `items' on `setb'
;;
for i=0L, SETDIM-1L do begin
cspice_insrti, even[i], seta
cspice_insrti, items[i], setb
endfor
;;
;; Perform the union if possible.
;;
if ( cspice_card( seta ) + cspice_card( setb ) le $
cspice_size( setc ) ) then begin
print, 'Union will not overflow the output set.'
cspice_union, seta, setb, setc
endif else begin
print, 'Union may overflow...'
cspice_inter, seta, setb, setc
if ( cspice_card( seta ) + cspice_card( setb ) - $
cspice_card( setc ) le cspice_size( setc ) ) then begin
print, ' ... but cspice_inter indicates it is safe!'
cspice_union, seta, setb, setc
endif else begin
print, ' ... and cspice_inter confirms it!'
endelse
endelse
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Union may overflow...
... but cspice_inter indicates it is safe!
2) The cardinality function cspice_card is also typically used to
process each of the elements of a cell, set or window. In this
example, we will build a double precision cell via a series of
calls to cspice_appndd. Create a set from this set by calling
cspice_valid and display the results.
Example code begins here.
PRO card_ex2
;;
;; 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.
This is a generic procedure which may be used on SPICE Cells of
double precision or integer data type.
1) If the input cell has invalid cardinality, the error
SPICE(INVALIDCARDINALITY) is signaled by a routine in the call
tree of this routine. cspice_card returns an unspecified value in
this case.
2) If the input array has invalid size, the error
SPICE(INVALIDSIZE) is signaled by a routine in the call tree
of this routine. cspice_card returns an unspecified value in this
case.
3) If the input argument `cell' is undefined, an error is
signaled by the IDL error handling system.
4) If the input argument `cell' 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
WINDOWS.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.3, 26-AUG-2021 (JDR)
Added arguments' type and size information in the -I/O section.
Edited the header to comply with NAIF standard. Added complete
code example based on existing example fragments.
Added sets.req and windows.req to the list of required readings.
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.2, 23-SEP-2008 (EDW)
Eliminated error in English.
Correct Required Reading citation cell.req to cells.req.
-Icy Version 1.0.0, 08-OCT-2004 (EDW)
cardinality of an integer cell
|