Index Page convrt_c

A B C D E F G H I J K L M N O P Q R S T U V W X

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

       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

    Wed Apr  5 17:54:30 2017