1 /*
2 
3 -Procedure vzerog_c ( Is a vector the zero vector?---general dim. )
4 
5 -Abstract
6 
7    Indicate whether a general-dimensional vector is the zero vector.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    None.
37 
38 -Keywords
39 
40    MATH
41    VECTOR
42 
43 */
44 
45    #include "SpiceUsr.h"
46    #undef    vzerog_c
47 
vzerog_c(ConstSpiceDouble * v,SpiceInt ndim)48    SpiceBoolean vzerog_c ( ConstSpiceDouble * v, SpiceInt ndim )
49 
50 /*
51 
52 -Brief_I/O
53 
54    Variable  I/O  Description
55    --------  ---  --------------------------------------------------
56    v          I   Vector to be tested.
57    ndim       I   Dimension of v.
58 
59    The function returns the value SPICETRUE if and only if v is the
60    zero vector.
61 
62 -Detailed_Input
63 
64    v,
65    ndim           are, respectively, a vector and its dimension.
66 
67 -Detailed_Output
68 
69    The function returns the value SPICETRUE if and only if v is the
70    zero vector.
71 
72 -Parameters
73 
74    None.
75 
76 -Exceptions
77 
78    Error free.
79 
80    1)   When ndim is non-positive, this function returns the value
81         SPICEFALSE  (A vector of non-positive dimension cannot be the
82         zero vector.)
83 
84 -Files
85 
86    None.
87 
88 -Particulars
89 
90    This function has the same truth value as the logical expression
91 
92       ( vnormg_c ( v, ndim )  ==  0. )
93 
94    Replacing the above expression by
95 
96       vzerog_c ( v, ndim );
97 
98    has several advantages:  the latter expresses the test more
99    clearly, looks better, and doesn't go through the work of scaling,
100    squaring, taking a square root, and re-scaling (all of which
101    vnormg_c must do) just to find out that a vector is non-zero.
102 
103    A related function is vzero_c, which accepts three-dimensional
104    vectors.
105 
106 -Examples
107 
108    1)  When testing whether a vector is the zero vector, one
109        normally constructs tests like
110 
111           if (  vnormg_c ( v, ndim )  ==  0.  )
112              {
113                       .
114                       .
115                       .
116 
117        These can be replaced with the code
118 
119           if (  vzerog_c ( v, ndim )  )
120              {
121                       .
122                       .
123                       .
124 
125    2)  Make sure that a `unit' quaternion is non-zero before
126        converting it to a rotation matrix.
127 
128           if (  vzerog_c ( q, 4 )  )
129              {
130 
131              [ handle error ]
132 
133           else
134              {
135              vhatg_c ( q, 4, q )
136              q2m_c   ( q, m )
137                       .
138                       .
139                       .
140 
141 -Restrictions
142 
143    None.
144 
145 -Literature_References
146 
147    None.
148 
149 -Author_and_Institution
150 
151    N.J. Bachman    (JPL)
152    I.M. Underwood  (JPL)
153    E.D. Wright     (JPL)
154 
155 -Version
156 
157    -CSPICE Version 1.0.0, 29-JUN-1999
158 
159 -Index_Entries
160 
161    test whether an n-dimensional vector is the zero vector
162 
163 -&
164 */
165 
166 { /* Begin vzerog_c */
167 
168 
169    /*
170    Local variables.
171    */
172    SpiceInt       i;
173 
174    /* ndim must be at least 1. */
175    if ( ndim < 1 )
176       {
177       return SPICEFALSE;
178       }
179 
180 
181    /* Check for any non-zero entries.  If they exist, test fails. */
182    for ( i=0; i < ndim; i++ )
183       {
184       if ( v[i] != 0. )
185          {
186          return SPICEFALSE;
187          }
188       }
189 
190 
191    /* If we are here, the vector is zero. */
192    return SPICETRUE;
193 
194 
195 
196 } /* End vzerog_c */
197