Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page size_c
Table of contents
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       size_c ( Size of a cell )

       SpiceInt size_c ( SpiceCell  * cell )
#### Abstract
       Return the size (maximum cardinality) of a SPICE cell of any
       data type.
#### Required_Reading
       CELLS
       SETS
#### Keywords
       CELLS
       SETS
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       cell       I   Input cell.

       The function returns the size of the input cell.
#### Detailed_Input
       cell        is a SPICE cell of any data type.

                   `cell' must be declared as a character, double precision or
                   integer SpiceCell.

                   CSPICE provides the following macros, which declare and
                   initialize the cell

                      SPICECHAR_CELL          ( cell, CELLSZ, CELLMLEN );
                      SPICEDOUBLE_CELL        ( cell, CELLSZ );
                      SPICEINT_CELL           ( cell, CELLSZ );

                   where CELLSZ is the maximum capacity of `cell' and CELLMLEN is
                   the maximum length of any member in the character cell.
#### Detailed_Output
       The function returns the size of (maximum number of elements in)
       the input cell.
#### Parameters
       None.
#### Exceptions
       1)  If the input `cell' cell argument does not have a recognized data
           type, the error SPICE(NOTSUPPORTED) is signaled.

       2)  If the input `cell' has invalid cardinality, the error
           SPICE(INVALIDCARDINALITY) is signaled by a routine in the call
           tree of this routine. size_c returns an unspecified value in this
           case.

       3)  If the input `cell' has invalid size, the error
           SPICE(INVALIDSIZE) is signaled by a routine in the call tree of
           this routine. size_c returns an unspecified value in this case.
#### Files
       None.
#### Particulars
       None.
#### Examples
       The 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) The size_c function is typically used in conjunction
          with the card_c function to predict (and subsequently
          avoid) overflows when manipulating cells. In the following
          example, card_c and size_c are used to determine whether
          the union of two sets is safe.

          Example code begins here.

          /.
             Program size_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local constants.
             ./
             #define SETDIM       5

             /.
             Local variables.

             Declare two SPICE cells.
             ./
             SPICEINT_CELL      ( seta, SETDIM );
             SPICEINT_CELL      ( setb, SETDIM );
             SPICEINT_CELL      ( setc, SETDIM );

             SpiceInt             i;

             /.
             Create a list of items and even numbers.
             ./
             SpiceInt             even   [SETDIM] = {  0,  2,  4,  4,  8 };

             SpiceInt             items  [SETDIM] = {  0,  1,  1,  2,  8 };

             /.
             Initialize the empty sets.
             ./
             valid_c ( SETDIM, 0, &seta );
             valid_c ( SETDIM, 0, &setb );

             /.
             Insert `even' on `seta' and `items' on `setb'
             ./
             for ( i = 0; i < SETDIM; i++ )
             {
                insrti_c ( even[i],  &seta );
                insrti_c ( items[i], &setb );
             }

             /.
             Perform the union if possible.
             ./
             if ( card_c ( &seta ) + card_c ( &setb ) <= size_c ( &setc ) )
             {
                printf( "Union will not overflow the output set.\n" );
                union_c ( &seta, &setb, &setc );
             }
             else
             {
                printf( "Union may overflow...\n" );
                inter_c ( &seta, &setb, &setc );

                if ( card_c ( &seta ) + card_c ( &setb ) - card_c ( &setc ) <=
                     size_c ( &setc ) )
                {
                   printf( "   ... but inter_c indicates it is safe!\n" );
                   union_c ( &seta, &setb, &setc );
                }
                else
                {
                   printf( "  ... and inter_c confirms it!\n" );
                }

             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, the output was:

          Union may overflow...
             ... but inter_c indicates it is safe!
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman        (JPL)
       C.A. Curzon         (JPL)
       J. Diaz del Rio     (ODC Space)
       H.A. Neilan         (JPL)
       W.L. Taber          (JPL)
       I.M. Underwood      (JPL)
#### Version
       -CSPICE Version 1.0.1, 27-AUG-2021 (JDR)

           Edited the header to comply with NAIF standard. Added complete
           code example based on existing example fragments.

           Added SETS to the list of required readings and keywords.

           Extended description of argument "cell" in -Detailed_Input to include
           type and preferred declaration method.

           Added entry #1 in -Exceptions section.

       -CSPICE Version 1.0.0, 06-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU)
#### Index_Entries
       size of a cell
#### Link to routine size_c source file size_c.c

    Fri Dec 31 18:41:12 2021