sdiff_c

Index Page sdiff_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
       void sdiff_c (  SpiceCell   * a,
                       SpiceCell   * b,
                       SpiceCell   * c  )
#### Abstract
       Take the symmetric difference of two sets of any data type to form a
       third set.
#### Required_Reading
       SETS
#### Keywords
       CELLS, SETS
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       a          I   First input set.
       b          I   Second input set.
       c          O   Symmetric difference of a and b.
#### Detailed_Input
       a           is a CSPICE set.  a must be declared as a SpiceCell
                   of data type character, double precision, or integer.

       b           is a CSPICE set, distinct from a.  b must have the
                   same data type as a.
#### Detailed_Output
       c           is a CSPICE set, distinct from sets a and b, which
                   contains the symmetric difference of a and b (that is,
                   all of the elements which are in a or in b but not in
                   both). c must have the same data type as a and b.

                   When comparing elements of character sets, this routine
                   ignores trailing blanks.  Trailing blanks will be
                   trimmed from the members of the output set c.
#### Parameters
       None.
#### Exceptions
       1) If the input set arguments don't have identical data types,
          the error SPICE(TYPEMISMATCH) is signaled.

       2) If the symmetric difference of the two sets contains more
           elements than can be contained in the output set, the error
           SPICE(SETEXCESS) is signaled.

       3) If the set arguments have character type and the length of the
          elements of the output set is less than the maximum of the
          lengths of the elements of the input sets, the error
          SPICE(ELEMENTSTOOSHORT) is signaled.

       4) If either of the input arguments may be unordered or contain
          duplicates, the error SPICE(NOTASET) is signaled.
#### Files
       None.
#### Particulars
       This is a generic CSPICE set routine; it operates on sets of any
       supported data type.

       The symmetric difference of two sets contains every element which is
       in the first set OR in the second set, but NOT in both sets.

             {a,b}      sym. difference {c,d}     =  {a,b,c,d}
             {a,b,c}                    {b,c,d}      {a,d}
             {a,b,c,d}                  {}           {a,b,c,d}
             {}                         {a,b,c,d}    {a,b,c,d}
             {}                         {}           {}
#### Examples
       1) The following code fragment places the symmetric difference of
          the character sets planets and asteroids into the character set
          result.

             #include "SpiceUsr.h"
                    .
                    .
                    .
             /.
             Declare the sets with string length NAMLEN and with maximum
             number of elements MAXSIZ.
             ./
             SPICECHAR_CELL ( planets,   MAXSIZ, NAMLEN );
             SPICECHAR_CELL ( asteroids, MAXSIZ, NAMLEN );
             SPICECHAR_CELL ( result,    MAXSIZ, NAMLEN );
                    .
                    .
                    .
             /.
             Compute the symmetric difference.
             ./
             sdiff_c ( &planets, &asteroids, &result );

       2) Repeat example #1, this time using integer sets containing
          ID codes of the bodies of interest.

             #include "SpiceUsr.h"
                    .
                    .
                    .
             /.
             Declare the sets with maximum number of elements MAXSIZ.
             ./
             SPICEINT_CELL ( planets,   MAXSIZ );
             SPICEINT_CELL ( asteroids, MAXSIZ );
             SPICEINT_CELL ( result,    MAXSIZ );
                    .
                    .
                    .
             /.
             Compute the symmetric difference.
             ./
             sdiff_c ( &planets, &asteroids, &result );
#### Restrictions
       1) The output set must be distinct from both of the input sets.
          For example, the following calls are invalid.

             sdiff_c  ( &current,  &new,      &current );
             sdiff_c  ( &new,      &current,  &current );

          In each of the examples above, whether or not the subroutine
          signals an error, the results will almost certainly be wrong.
          Nearly the same effect can be achieved, however, by placing the
          result into a temporary set, which is immediately copied back
          into one of the input sets, as shown below.

             sdiff_c  ( &current,  &new,  &temp );
             copy_c  ( &temp,     &new         );

       2) String comparisons performed by this routine are Fortran-style:
          trailing blanks in the input sets are ignored. This gives
          consistent behavior with CSPICE code generated by the f2c
          translator, as well as with the Fortran SPICE Toolkit.

          Note that this behavior is not identical to that of the ANSI
          C library functions strcmp and strncmp.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       C.A. Curzon     (JPL)
       W.L. Taber      (JPL)
       I.M. Underwood  (JPL)
#### Version
       -CSPICE Version 1.1.0, 15-FEB-2005 (NJB)

           Bug fix:  loop bound changed from 2 to 3 in loop used
           to free dynamically allocated arrays.

       -CSPICE Version 1.0.0, 08-AUG-2002 (NJB) (CAC) (WLT) (IMU)
#### Index_Entries
       symmetric difference of two sets
#### Link to routine sdiff_c source file sdiff_c.c

    Thu Apr 16 08:59:06 2009