Procedure

   copy_c ( Copy a SPICE cell ) 

   void copy_c (  SpiceCell   * cell,
                  SpiceCell   * copy  )

Abstract

   Copy the contents of a SpiceCell of any data type to another
   cell of the same type.

Required_Reading

   CELLS

Keywords

   CELLS

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   cell       I   Cell to be copied.
   copy       O   New cell.

Detailed_Input

   cell        is a SPICE cell of character, double precision, or integer 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

   copy        is a SPICE cell which contains the same elements as the input
               cell, in the same order.

               `copy' must be declared as a SpiceCell of the same data type
               as `cell'.

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

                  SPICECHAR_CELL          ( copy, COPYSZ, COPYMLEN );
                  SPICEDOUBLE_CELL        ( copy, COPYSZ );
                  SPICEINT_CELL           ( copy, COPYSZ );

               where COPYSZ is the maximum capacity of `copy' and COPYMLEN is
               the maximum length of any member in the character cell.

Parameters

   None.

Exceptions

   1)  If the output cell in not large enough to hold the elements of
       the input cell, the error SPICE(CELLTOOSMALL) is signaled by a
       routine in the call tree of this routine.

   2)  If the `cell' and `copy' cell arguments are of type SpiceChar and
       the length of the elements of the output cell is less than the
       length of the elements of the input cell, the error
       SPICE(INSUFFLEN) is signaled.

   3)  If the `cell' and `copy' cell arguments do not have identical data
       types, the error SPICE(TYPEMISMATCH) is signaled.

   4)  If any of the `cell' or `copy' cell arguments does not have a
       recognized data type, the error SPICE(NOTSUPPORTED) is signaled.

   5)  If the cell arguments are of type SpiceChar and the string length
       associated with any of them is non-positive or too short to be
       usable when constructing the equivalent SPICE character cells
       required by the wrapped SPICELIB routine, an error is signaled by
       a routine in the call tree of this routine.

Files

   None.

Particulars

   This routine is used primarily to manipulate working cells, since
   many routines that use cells (binary set routines, for instance) do
   not allow cells to be combined or manipulated in place.

Examples

   In the following example, copy_c is used to copy the result
   of the union of two character CSICE sets from a temporary
   working set back into the one of the original set.

      #include "SpiceUsr.h"
           .
           .
           .
      /.
      Declare the cell names with string length LNSIZE and maximum
      number of strings SIZE.
      ./
      SPICECHAR_CELL ( bodies,  SIZE, LNSIZE );
      SPICECHAR_CELL ( planets, SIZE, LNSIZE );
      SPICECHAR_CELL ( temp,    SIZE, LNSIZE );
           .
           .
           .
      union_c ( &bodies, &planets, &temp );
      copy_c  ( &temp,   &bodies         );


   If the size of the temporary cell is greater than the size
   of the original set, the function failed_c should be checked to be
   sure that no overflow occurred. If bodies is at least as
   large as temp, no such check is necessary.

Restrictions

   None.

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, 27-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard.

       Extended description of arguments "cell" and "copy" to include
       type and preferred declaration method.

       Added entry #4 and #5 in -Exceptions section.

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

Index_Entries

   copy a character cell