Procedure

     CONVRT ( Convert Units )

     SUBROUTINE CONVRT ( X, IN, OUT, 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

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION X
     CHARACTER*(*)    IN
     CHARACTER*(*)    OUT
     DOUBLE PRECISION Y

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 measurement in the desired units.

Detailed_Input

     X        is a number representing a measurement in the units
              specified by IN.

     IN       is the identifier of the units associated with the
              measurement X. Acceptable units are:

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

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

                 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)

     OUT      is the identifier of the units desired for the
              measurement X. See the description of IN.

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

        CALL CONVRT ( 1.0D0, 'METERS',        'STATUTE_MILES', MILES )
        CALL CONVRT ( MILES, 'STATUTE_MILES', 'FEET',          FEET  )

     or

        CALL CONVRT ( 1.0D0, 'METERS', 'STATUTE_MILES', MILES )
        CALL CONVRT ( 1.0D0, 'METERS', 'FEET',          FEET  )

Restrictions

     1)  This routine does not do any checking for overflow. The caller
         is required to make sure that the units used for the
         measurement are such that no floating point overflow will
         occur when the conversion is performed.

     2)  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:

            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.

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

            PARSECS          The parsec is the distance to an object
                             whose parallax angle is one arcsecond. Its
                             value is dependent upon the value of the
                             astronomical unit.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     C.A. Curzon        (JPL)
     J. Diaz del Rio    (ODC Space)
     W.M. Owen          (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 2.1.0, 06-JUL-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section.

        Corrected a typo in $Restrictions section.

    SPICELIB Version 2.0.0, 12-MAY-2015 (NJB)

        Added support for full names of metric distance units. Added
        support for the abbreviation 'M' indicating meters.

    SPICELIB Version 1.0.2, 01-JUL-2014 (NJB)

        Updated the description of the AU in the $Restrictions
        section.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (CAC) (WMO) (WLT) (IMU)