card_c

Index Page card_c
A B C D E F G H I J K L M N O P Q R S T U V W X
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
       SpiceInt card_c ( SpiceCell  * cell )
#### Abstract
       Return the cardinality (current number of elements) in a
       cell of any data type.
#### Required_Reading
       CELLS
#### Keywords
       CELLS
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       cell       I   Input cell.

       The function returns the cardinality of the input cell.
#### Detailed_Input
       cell        is a cell of character, double precision, or
                   integer data type.
#### Detailed_Output
       The function returns the cardinality of (current number of elements
       in) the input cell.
#### Parameters
       None.
#### Exceptions
       1)  If the input cell has invalid cardinality, the error
           SPICE(INVALIDCARDINALITY) is signaled.  card_c returns
           an unspecified value in this case.

       2)  If the input array has invalid size, the error
           SPICE(INVALIDSIZE) is signaled.  card_c returns
           an unspecified value in this case.
#### Files
       None.
#### Particulars
       This is a generic function which may be used on SpiceCells of
       character, double precision, or integer data type.
#### Examples
       The cardinality function card_c is typically used to process
       each of the elements of a cell. In the following example, cardc_c
       is used to step through the individual elements of the character
       cell names.

          #include "SpiceUsr.h"
               .
               .
               .
          /.
          Declare the cell names with string length LNSIZE and maximum
          number of strings SIZE.
          ./
          SPICECHAR_CELL ( names, SIZE, LNSIZE );
               .
               .
               .
          for ( i = 0;  i < card_c(&names);  i++ )
          {
               .
               .
               .
          }

       In conjunction with the size_c function, card_c may be used
       to predict (and subsequently avoid) overflows when manipulating
       cells. In the following example, size_c is used to determine
       whether the integer cell original can be safely copied into
       the integer cell save before actually attempting the operation.
       If original contains more elements than save can hold, then
       the operation would fail.

          if (  card_c(&original)  <=  size_c(&save)  )
          {
             copy_c ( &original, &save );
          }
          else
          {
               .
               .
               .
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       C.A. Curzon     (JPL)
       H.A. Neilan     (JPL)
       W.L. Taber      (JPL)
       I.M. Underwood  (JPL)
#### Version
       -CSPICE Version 1.0.0, 06-AUG-2002 (NJB) (CAC) (HAN) (WLT) (IMU)
#### Index_Entries
       cardinality of an integer cell
#### Link to routine card_c source file card_c.c

    Thu Apr 16 08:57:27 2009