convrt_c

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"
                                          "KM"
                                          "CM"
                                          "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  is taken from the JPL
                      ephemeris DE125.  It is believed to be accurate to
                      about 40 meters.

          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 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

    Thu Apr 16 08:57:34 2009