Abstract

   CSPICE_VZERO returns a boolean indicating whether an arbitrary
   double precision 3-vector is the zero vector - a vector with
   all elements of 0.

I/O

   Given:

      v        a vector in 3-space.

               help, v
                  DOUBLE = Array[3]

   the call:

      vzero = cspice_vzero( v )

   returns:

      vzero    the value True if and only if `v' is the zero vector.

               help, vzero
                  BOOLEAN = Scalar

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) Given a set of three-dimensional vectors, check which ones are
      the zero vector.

      Example code begins here.


      PRO vzero_ex1

         ;;
         ;; Create an array of 3-dimensional vectors.
         ;;
         vec = [[ 0.d, 0.d, 0.d ], [ 0.d, 0.d, 0.01d ]]

         ;;
         ;; Check each 3-dimensional vector within the array.
         ;;
         for i = 0,1 do begin

            ;;
            ;; Check if the ith vector is the zero vector.
            ;;
            print, 'Test vector: ', vec(*,i)
            if ( cspice_vzero( vec(*,i) ) ) then begin

               print, '   The zero vector.'

            endif else begin

               print, '   Not all elements of the vector are zero.'

            endelse

          endfor

       END


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


      Test vector:        0.0000000       0.0000000       0.0000000
         The zero vector.
      Test vector:        0.0000000       0.0000000     0.010000000
         Not all elements of the vector are zero.

Particulars

   This function has the same truth value as the logical expression

      cspice_vnorm ( v )  ==  0.

   Replacing the above expression by

      cspice_vzero ( v )

   has several advantages: the latter expresses the test more
   clearly, looks better, and doesn't go through the work of scaling,
   squaring, taking a square root, and re-scaling (all of which
   cspice_vnorm must do) just to find out that a vector is non-zero.

   A related function is cspice_vzerog, which accepts vectors of arbitrary
   dimension.

Exceptions

   1)  If the input argument `v' is undefined, an error is signaled
       by the IDL error handling system.

   2)  If the input argument `v' 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

   None.

Required_Reading

   ICY.REQ

Literature_References

   None.

Author_and_Institution

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

Version

   -Icy Version 1.0.3, 10-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard. Added
       example's problem statement. Extended example to test different
       vectors.

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

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

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

   -Icy Version 1.0.2, 13-JUN-2011 (EDW)

       Edits to comply with NAIF standard for Icy headers.

   -Icy Version 1.0.1, 09-DEC-2005 (EDW)

       Added -Examples section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   test whether a 3-dimensional vector is the zero vector