Procedure

   ssize_c ( Set the size of a cell ) 

   void ssize_c (  SpiceInt      size,
                   SpiceCell   * cell  )

Abstract

   Set the size (maximum cardinality) of a SPICE cell of any data
   type.

Required_Reading

   CELLS

Keywords

   CELLS

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   size       I   Size (maximum cardinality) of the cell.
   cell       O   The cell.

Detailed_Input

   size        is the new value of the size (maximum number of elements) of
               the cell.

               `size' must be non-negative and must be no larger than the
               initial declared size of the cell.

   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

   cell        on output, is the input cell with its size updated to the value
               given by the input argument size.

               The cardinality of the cell is set to 0.

               The cell becomes a  SPICE set: the cell's "is a set?" attribute
               becomes SPICETRUE. The cell then can be used as an input to the
               SPICE set routines such as insrtX_c.

               Unlike the cell "set size" routines in the Fortran SPICE
               Toolkit's SPICELIB library, this routine does not clear the
               unused portion of the cell's control area.

Parameters

   None.

Exceptions

   1)  If an attempt is made to set the size of the cell to a negative
       number, the error SPICE(INVALIDSIZE) is signaled.

   2)  The size of a cell may not be set to a value larger than the
       original declared size. However, the SPICE cell routines
       cannot detect this error.

   3)  If the input `cell' cell argument does not have a recognized data
       type, the error SPICE(NOTSUPPORTED) is signaled.

Files

   None.

Particulars

   Unlike their counterparts in the Fortran SPICELIB library, cells in
   CSPICE are initialized automatically when accessed via the SPICE cell
   API routines, so there is normally no reason to call this routine.

   This routine is provided for the sake of completeness.

Examples

   1) Declare an integer cell. Populate the cell, then reset
      the size to 1/2 the originally declared size, in order
      to inhibit write access to the last portion of the cell.

         #include "SpiceUsr.h"
               .
               .
               .

         #define SIZE          10

         /.
         Declare a cell with room for SIZE integers.
         ./
         SPICEINT_CELL         ( icell, SIZE );
               .
               .
               .
         /.
         Reduce the size of the cell.
         ./
         ssize_c ( SIZE/2, &icell );

Restrictions

   1)  See exception (2) in the -Exceptions section.

Literature_References

   None.

Author_and_Institution

   N.J. Bachman        (JPL)
   C.A. Curzon         (JPL)
   J. Diaz del Rio     (ODC Space)
   W.L. Taber          (JPL)
   I.M. Underwood      (JPL)

Version

   -CSPICE Version 1.0.1, 24-NOV-2021 (JDR)

       Edited the header to comply with NAIF standard.

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

       Added entry #3 in -Exceptions section.

   -CSPICE Version 1.0.0, 21-AUG-2002 (NJB) (CAC) (WLT) (IMU)

Index_Entries

   set the size of a cell