SLA_DAFIN - Sexagesimal character string to angle

ACTION:

Decode a free-format sexagesimal string (degrees, arcminutes, arcseconds) into a double precision floating point number (radians).

CALL:

CALL sla_DAFIN (STRING, NSTRT, DRESLT, JF)

GIVEN:

STRING	C*(*)	string containing deg, arcmin, arcsec fields
NSTRT	I	pointer to start of decode (beginning of STRING = 1)

RETURNED:

NSTRT	I	advanced past the decoded angle
DRESLT	D	angle in radians
JF	I	status:
		0 = OK
		$+1$ = default, DRESLT unchanged (note 2)
		$-1$ = bad degrees (note 3)
		$-2$ = bad arcminutes (note 3)
		$-3$ = bad arcseconds (note 3)

EXAMPLE

:

argument	before	after
STRING	$'$-57 17 44.806 12 34 56.7$'$	unchanged
NSTRT	1	16 (i.e. pointing to 12...)
RESLT	-	$-1.00000$D0
JF	-	0

A further call to sla_DAFIN, without adjustment of NSTRT, will decode the second angle, $12^{\circ} 34^{'} 56^{''}.7$.

NOTES:

1. The first three ``fields'' in STRING are degrees, arcminutes, arcseconds, separated by spaces or commas. The degrees field may be signed, but not the others. The decoding is carried out by the sla_DFLTIN routine and is free-format.
2. Successive fields may be absent, defaulting to zero. For zero status, the only combinations allowed are degrees alone, degrees and arcminutes, and all three fields present. If all three fields are omitted, a status of +1 is returned and DRESLT is unchanged. In all other cases DRESLT is changed.
3. Range checking:
   • The degrees field is not range checked. However, it is expected to be integral unless the other two fields are absent.
   • The arcminutes field is expected to be 0-59, and integral if the arcseconds field is present. If the arcseconds field is absent, the arcminutes is expected to be 0-59.9999...
   • The arcseconds field is expected to be 0-59.9999...
   • Decoding continues even when a check has failed. Under these circumstances the field takes the supplied value, defaulting to zero, and the result DRESLT is computed and returned.
4. Further fields after the three expected ones are not treated as an error. The pointer NSTRT is left in the correct state for further decoding with the present routine or with sla_DFLTIN etc. See the example, above.
5. If STRING contains hours, minutes, seconds instead of degrees etc, or if the required units are turns (or days) instead of radians, the result DRESLT should be multiplied as follows:
   
   
   

   for STRING	to obtain	multiply DRESLT by
   ${\circ}$  $'$  $''$	radians	$1.0D0$
   ${\circ}$  $'$  $''$	turns	$1/{2 \pi} = 0.1591549430918953358D0$
   h m s	radians	$15.0D0$
   h m s	days	$15/{2\pi} = 2.3873241463784300365D0$