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
cspice_union

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_UNION computes the union of two sets of any data type to
   form a third set.

I/O


   Given:

      a,
      b        two SPICE sets, each of the same type, double precision, or
               integer.

               help, a
                  STRUCT = cspice_celld(N)   or   STRUCT = cspice_celli(N)
               help, b
                  STRUCT = cspice_celld(M)   or   STRUCT = cspice_celli(M)

               The user must create `a' and `b' using either cspice_celld,
               or cspice_celli.

   the call:

      cspice_union, a, b, d

   returns:

      c        the SPICE set, distinct from sets `a' and `b' but with the same
               type, containing the union of `a' and `b' (that is, all of the
               elements which are in `a' or `b' or both).

               help, c
                  STRUCT = cspice_celld(R)   or   STRUCT = cspice_celli(R)

Parameters


   None.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Compute the union of two sets of double precision data, and
      the union of two sets of integer data. Output the resulting
      SPICE sets.

      Example code begins here.


      PRO union_ex1

         ;;
         ;; Create the cells...
         ;;
         SIZE = 10

         a = cspice_celli( SIZE )
         b = cspice_celli( SIZE )
         c = cspice_celli( SIZE )
         d = cspice_celli( SIZE )

         e = cspice_celld( SIZE )
         f = cspice_celld( SIZE )
         g = cspice_celld( SIZE )
         h = cspice_celld( SIZE )

         ;;
         ;; ... insert the test data so that
         ;; 'b' = 'c' define strict subsets of 'a'.
         ;;
         cspice_insrti, [ 1l, 2, 3, 4 ], a
         cspice_insrti, [ 1l, 3       ], b
         cspice_insrti, [ 1l, 3       ], c

         cspice_union, a, b, d

         ;;
         ;; Output set data array for set 'd'. Recall, the 'base' field
         ;; describes a vector of length
         ;;
         ;;   d.data + cspice_size(d)
         ;;
         ;; The set data being a slice of this vector. The slice begins at
         ;; index:
         ;;
         ;;    d.data
         ;;
         ;; ending at:
         ;;
         ;;    d.data + cspice_card(d) - 1
         ;;
         ;; for cspice_card(d) > 0.
         ;;
         print, "Union of a and b", d.base[d.data : d.data+cspice_card(d)-1 ]

         cspice_union, b, c, d

         print, "Union of b and c", d.base[d.data : d.data+cspice_card(d)-1 ]

         print

         ;;
         ;; Same example for double precision.
         ;;
         cspice_insrtd, [ 1.d, 2.d, 3.d, 4.d ], e
         cspice_insrtd, [ 1.d, 3.d           ], f
         cspice_insrtd, [ 1.d, 3.d           ], g

         cspice_union, e, f, h

         ;;
         ;; Output set data array for set 'h'.
         ;;
         print, FORMAT='(A,4F12.5)', $
                "Union of e and f", h.base[h.data : h.data+cspice_card(h)-1 ]

         cspice_union, f, g, h

         print, FORMAT='(A,4F12.5)', $
                "Union of f and g", h.base[h.data : h.data+cspice_card(h)-1 ]

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Union of a and b           1           2           3           4
      Union of b and c           1           3

      Union of e and f     1.00000     2.00000     3.00000     4.00000
      Union of f and g     1.00000     3.00000


Particulars


   The user must create any needed cell structures with cspice_celld,
   cspice_celli prior to use regardless of whether the routine
   uses the cell as input or returns it as output.

Exceptions


   1)  If the input set arguments don't have identical data types,
       the error SPICE(TYPEMISMATCH) is signaled by a routine in the
       call tree of this routine.

   2)  If the union 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.

   3)  If either of the input arguments may be unordered or contain
       duplicates, the error SPICE(NOTASET) is signaled by a routine
       in the call tree of this routine.

   4)  If any of the input arguments, `a', `b' or `c', is undefined,
       an error is signaled by the IDL error handling system.

   5)  If any of the input arguments, `a', `b' or `c', is not of the
       expected type, or it does not have the expected dimensions and
       size, an error is signaled by the Icy interface.

Files


   None.

Restrictions


   1)  The output set must be distinct from both of the input sets.
       For example, the following calls are invalid.

          cspice_union, current, new,     current
          cspice_union, 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.

          cspice_union, current, new, temp
          new = temp

Required_Reading


   ICY.REQ
   CELLS.REQ
   SETS.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.2, 24-AUG-2021 (JDR)

       Added arguments' type and size information in the -I/O section.

       Edited the header to comply with NAIF standard. Added
       example's problem statement and reformatted example's output.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

   -Icy Version 1.0.1, 28-SEP-2006 (EDW)

       Corrections to English.
       Correct Required Reading citation cell.req to cells.req.

   -Icy Version 1.0.0, 22-AUG-2005 (EDW)

Index_Entries


   union of two sets



Fri Dec 31 18:43:08 2021