CVTSIXTY

Name

cvtsixty

Purpose (one Line Only)

General purpose routine for converting between sexigesimal and decimal.

Description

This routine encapsulates all of the parsing and conversion routines for
handling all conversions between sexigeismal strings and double
precision forms of angular coordinates. Floating point is allowed on
input but its precision is not really good enough for the taks so any
decimal output will always be double precision. Scalar and vector
inputs are permitted. A string on input is always an indication that
the input is sexigesimal and the information is to be converted to
decimal format. If the input is floating point or double then the
conversion is to a sexigeismal string. There are a number of specialized
conversion routines in the library but they all call this basic routine
setting all the required options.
A word about the parser: When reading strings, the information is parsed
character by character. This routine ignores leading blanks. But, a
blank is considered to be a terminating character once the parser has
seen a non-blank. Legal field separation characters are ':' and ','.
Any and all fields can be floating point though decimal fields only
really make sense if that is the last field provided.
On output you can modify the separator character to anything you like but
this routine will not be able to read arbitrary seperators.
Enough options are provided to permit meaningful range checking on the
input values for different types of angular quantities. The quantities
envisioned for this routine include Right Ascension [0-24h), Declination
[-90,90], Hour angle [12W,12E), Longitude [0,360) to name a few.

Calling Sequence

cvtsixty,input,minvalue,maxvalue,wrap,signchar,output

Inputs

input - scalar or vector. String ==> sexigesimal to decimal
Double or float ==> decimal to sexigesimal
minvalue - scalar, minimum allowed value for coordinate in decimal form.
maxvalue - scalar, maximum allowed value for coordinates in decimal form.
signchar - two-element string giving the characters to be used to indicate
the sign of the number on reading or writing.
signchar[0] = Character for positive numbers
signchar[1] = Character for negative numbers
wrap - Flag, if set indicates the coordinates wrap across from max
to min. This further indicates the range is inclusive
of minvalue and exclusive of maxvalue. If not set, the
range is inclusive of minvalue and maxvalue and an
out-of-range is an error.

Optional Input Parameters

Keyword Input Parameters

HOURS - Flag, if set, indicates the sexigesimal string is in units
of hours. The default is degrees.
DEGREES - Flag, if set, indicates the decimal value is in degrees.
The default is radians.
Keywords are grouped by the input data type since that dictates the
operation that ensues:
Double or float input:
PLACES - Resolution of output string (default=0)
= -8 Pure decimal output XX.xxxxx
= -7 nearest top level unit XX
= -6 nearest 30 minutes. XX:(00,30)
= -5 nearest 15 minutes. XX:(00,15,30,45)
= -4 nearest 10 minutes. XX:M0
= -3 nearest 5 minutes. XX:M(0,5)
= -2 nearest minute. XX:MM
= -1 nearest ten seconds. XX:MM:S0
= 0 nearest second. XX:MM:SS
= 1 nearest tenth of a second. XX:MM:SS.s
= 2 nearest hundredth of a second. XX:MM:SS.ss
= 3 nearest thousandth of a second. XX:MM:SS.sss
= 4 nearest thousandth of a second. XX:MM:SS.ssss
SEPCHAR - Scalar string of the separator character to use between
fields on output. Default=':'. Note that if you set
this to something other than ':', ',' or ' ' the output cannot
be parsed by this routine as input.

Outputs

output - length matches input. Double if input is string, string if input
is double or float.

Keyword Output Parameters

CARRY - Used on decimal to sexigesimal string conversion only. This is
a flag that will incidate if the number rolled over the cut
in the coordinate (if a cut exists).
ERROR - Flag (length matches input). Set if there was a conversion error.

Common Blocks

Side Effects

Restrictions

Procedure

Examples

Right ascension, radians in decimal form, hours in sexigesimal
cvtsixty,'15:43:21.1',0.0d0,2.0d0*!dpi,1,['',''],output,/HOURS
Right ascension, degrees in decimal form, hours in sexigesimal
cvtsixty,'15:43:21.1',0.0d0,360.0d0,1,['',''],output,/HOURS,/DEGREES
Declination, radians in decimal form, degrees in sexigesimal
cvtsixty,'-45:28:12',-0.5d0*!dpi,0.5d0*!dpi,0,['+','-'],output
Hour angle, radians in decimal form, hours in sexigesimal
cvtsixty,'W02:28',-1.0d0*!dpi,1.0d0*!dpi,0,['W','E'],output,/HOURS

Modification History

Written by Marc W. Buie, Southwest Research Institute, 2009/04/24
This is created from a large suite of independent but very similar
routines with the intent of removing all duplicate code and having
the independent routines call this master routine.
2010/04/18, MWB, modified internal loop variable to handle long input
vectors.