Procedure

   void convrt_c ( SpiceDouble       x,
                   ConstSpiceChar  * in,
                   ConstSpiceChar  * out,
                   SpiceDouble     * y    ) 

Abstract

 
    Take a measurement X, the units associated with 
    X, and units to which X should be converted; return Y --- 
    the value of the measurement in the output units. 
 

Required_Reading

 
   None. 
 

Keywords

 
    CONVERSION, UNITS 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  ------------------------------------------------- 
   x          I   Number representing a measurement in some units. 
   in         I   The units in which x is measured. 
   out        I   Desired units for the measurement. 
   y          O   The measurment in the desired units. 
 

Detailed_Input

 
   x          is a number representing a measurement in the units 
              specified by in. 

   in         represents the units associated with a measurement x. 
              Acceptable units are: 

              Angles:                 "RADIANS" 
                                      "DEGREES" 
                                      "ARCMINUTES" 
                                      "ARCSECONDS" 
                                      "HOURANGLE" 
                                      "MINUTEANGLE" 
                                      "SECONDANGLE" 

              Metric Distances:       "METERS" 
                                      "M"
                                      "KILOMETERS"
                                      "KM" 
                                      "CENTIMETERS"
                                      "CM" 
                                      "MILLIMETERS"
                                      "MM" 

              English Distances:      "FEET" 
                                      "INCHES" 
                                      "YARDS" 
                                      "STATUTE_MILES" 
                                      "NAUTICAL_MILES" 

              Astrometric Distances:  "AU" 
                                      "PARSECS" 
                                      "LIGHTSECS" 
                                      "LIGHTYEARS" julian lightyears 

              Time:                   "SECONDS" 
                                      "MINUTES" 
                                      "HOURS" 
                                      "DAYS" 
                                      "JULIAN_YEARS" 
                                      "TROPICAL_YEARS" 
                                      "YEARS" (same as julian years) 


              The case of the string in is not significant.


   out        represents the units desired for the measurement x. 
              See the description of in. 
 
              The case of the string out is not significant.
              
              

Detailed_Output

 
   y          is the input measurement converted to the desired units. 
 
 

Parameters

 
   None. 
 

Exceptions

 
   1) If the input units, output units, or both input and 
      output units are not recognized, the error 
      SPICE(UNITSNOTREC) is signaled. 

   2) If the units being converted between are incompatible, the 
      error SPICE(INCOMPATIBLEUNITS) is signaled. 
 

Files

 
   None. 
 

Particulars

 
   This routine converts a measurement x given in units specified by 
   in to the equivalent value y in units specified by out. 

   If a unit is not recognized, an error message is produced that 
   indicates which one was not recognized. 

   If input and output units are incompatible (for example angle 
   and distance units) and error message will be produced stating 
   the requested units and associated types. 
 

Examples

 
   To convert 1 meter to statute miles and feet you could make the
   calls
   

      convrt_c ( 1.0,   "meters",        "statute_miles", &miles ); 
      convrt_c ( miles, "statute_miles", "feet",          &feet  ); 

   or 

      convrt_c ( 1.0,   "METERS",        "STATUTE_MILES", &miles ); 
      convrt_c ( 1.0,   "METERS",        "FEET",          &feet  ); 
 
 

Restrictions

 
   You should make sure that your units are appropriate for the 
   measurement. This routine does not do any checking for over- 
   flow. Something like 

         convrt_c ( 10.0e302, "LIGHTYEARS", "MM", &y ); 

   will cause a floating point overflow. 

   Some of the units are not "defined" quantities.  In such a case 
   a best estimate is provided as of the date of the current version 
   of this routine.  Those estimated quantities are: 

      1 AU    --- the astronomical unit. The value was taken from 
                  the JPL ephemeris DE125. This value is an
                  approximation and should not be used for
                  high-accuracy work. It agrees with the value used in
                  the JPL planetary ephemeris DE430 (149597870.700 km)
                  at the 100m level.

      The tropical year is the time from equinox to equinox.  This 
      varies slightly with time. 

      1 PARSEC --- is dependent upon the value of the astronomical 
                   unit. 
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL)
   C.A. Curzon     (JPL) 
   H.A. Neilan     (JPL) 
   W.M. Owen       (JPL) 
   W.L. Taber      (JPL) 
   I.M. Underwood  (JPL) 
   
 

Version

 
   -CSPICE Version 2.0.0 13-MAY-2016 (NJB)

       Updated to support expanded names of metric distance
       units, as well as to support the abbreviation "M" 
       indicating meters.

   -CSPICE Version 1.0.0, 17-MAY-1999 (NJB)(CAC)(HAN)(WMO)(WLT)(IMU)

Index_Entries

 
   convert units 
 

Link to routine convrt_c source file convrt_c.c