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 sdiff_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

       sdiff_c ( Symmetric difference of two sets )

       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 SPICE set.

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

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

                      SPICECHAR_CELL          ( a, ASZ, AMLEN );
                      SPICEDOUBLE_CELL        ( a, ASZ );
                      SPICEINT_CELL           ( a, ASZ );

                   where ASZ is the maximum capacity of `a' and AMLEN is the
                   maximum length of any member in the character cell.

       b           is a SPICE set, distinct from `a'.

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

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

                      SPICECHAR_CELL          ( b, BSZ, BMLEN );
                      SPICEDOUBLE_CELL        ( b, BSZ );
                      SPICEINT_CELL           ( b, BSZ );

                   where BSZ is the maximum capacity of `b' and BMLEN is the
                   maximum length of any member in the character cell.

#### Detailed_Output

       c           is a SPICE 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).

                   When comparing elements of character sets, this routine ignores
                   trailing blanks. Trailing blanks will be trimmed from the
                   members of the output set `c'.

                   `c' must be declared as a SpiceCell of the same data type
                   as `a' and `b'.

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

                      SPICECHAR_CELL          ( c, CSZ, CMLEN );
                      SPICEDOUBLE_CELL        ( c, CSZ );
                      SPICEINT_CELL           ( c, CSZ );

                   where CSZ is the maximum capacity of `c' and CMLEN is the
                   maximum length of any member in the character cell.

#### Parameters

       None.

#### Exceptions

       1)  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 by a routine in the call tree of
           this routine.

       2)  If the `a', `b' and `c' cell arguments are of type SpiceChar 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 by a routine in the
           call tree of this routine.

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

       4)  If any of the `a', `b' or `c' cell arguments does not qualify as a
           SPICE set, the error SPICE(NOTASET) is signaled. SPICE sets
           have their data elements stored in increasing order and contain
           no duplicate elements.

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

       6)  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 is a generic SPICE 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)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)
       I.M. Underwood      (JPL)

#### Version

       -CSPICE Version 1.1.1, 29-OCT-2021 (JDR)

           Edited the header to comply with NAIF standard.

           Extended description of arguments "a", "b" and "c" to include
           type and preferred declaration method.

           Added entries #5 and #6 in -Exceptions section.

       -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

    Fri Dec 31 18:41:12 2021