idlastro / Astronomical Utilities: ADSTRING

[Source code]

NAME
ADSTRING
PURPOSE
Return RA and Dec as character string(s) in sexagesimal format.
EXPLANATION
RA and Dec may be entered as either a 2 element vector or as
two separate vectors (or scalars).  One can also specify the precision 
of the declination in digits after the decimal point.
CALLING SEQUENCE
result = ADSTRING( ra_dec, precision, /TRUNCATE )           
        or
result = ADSTRING( ra,dec,[ precision, /TRUNCATE ] )
        or
result = ADSTRING( dec, [ PRECISION= ]   
INPUTS
RA_DEC - 2 element vector giving the Right Ascension and declination
        in decimal degrees.
              or
RA     - Right ascension in decimal degrees, numeric scalar or vector
DEC    - Declination in decimal degrees, numeric scalar or vector
 only one parameter is supplied then it must be either a scalar (which
 converted to sexagesimal) or a two element [RA, Dec] vector.
OPTIONAL INPUT
PRECISION  - Integer scalar (0-4) giving the number of digits after the 
        decimal of DEClination.   The RA is automatically 1 digit more.
        This parameter may either be the third parameter after RA,DEC 
        or the second parameter after [RA,DEC].  If only DEC is supplied 
        then precision must be supplied as a keyword parameter.   If no
        PRECISION parameter or keyword is passed, a  precision of 1 for
        both RA and DEC is returned to maintain  compatibility with past
        ADSTRING versions.    Values of  precision larger than 4 will 
        be truncated to 4.    If PRECISION is 3 or 4, then RA and Dec 
        should be input as double precision.
OPTIONAL INPUT KEYWORD
/TRUNCATE - if set, then the last displayed digit in the output is 
        truncated in precision rather than rounded.   This option is
        useful if ADSTRING() is used to form an official IAU name 
        (see http://vizier.u-strasbg.fr/Dic/iau-spec.htx) with 
        coordinate specification.   The IAU name will typically be
        be created by applying STRCOMPRESS/REMOVE) after the ADSTRING()
        call, e.g. 
       strcompress( adstring(ra,dec,0,/truncate), /remove)   ;IAU format
 PRECISION = Alternate method of supplying the precision parameter, 
OUTPUT
RESULT - Character string(s) containing HR,MIN,SEC,DEC,MIN,SEC formatted
        as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION 
        parameter.    If only a single scalar is supplied it is 
        converted to a sexagesimal string (2I3,F5.1).
EXAMPLE
(1) Display CRVAL coordinates in a FITS header, H
IDL> crval = sxpar(h,'CRVAL*')  ;Extract 2 element CRVAL vector (degs)
IDL> print, adstring(crval)     ;Print CRVAL vector sexagesimal format
(2)  print,adstring(30.42,-1.23,1)  ==>  ' 02 01 40.80  -01 13 48.0'
     print,adstring(30.42,+0.23)    ==>  ' 02 01 40.8   +00 13 48.0'    
     print,adstring(+0.23)          ==>  '+00 13 48.0'
(3) The first two calls in (2) can be combined in a single call using
    vector input
       print,adstring([30.42,30.42],[-1.23,0.23], 1)
PROCEDURES CALLED
RADEC, SIXTY()
REVISION HISTORY
Written   W. Landsman                      June 1988
Addition of variable precision and DEC seconds precision fix. 
ver.  Aug. 1990 [E. Deutsch]
Output formatting spiffed up       October 1991 [W. Landsman]
Remove ZPARCHECK call, accept 1 element vector  April 1992 [W. Landsman]
Call ROUND() instead of NINT()    February 1996  [W. Landsman]
Check roundoff past 60s           October 1997   [W. Landsman]
Work for Precision =4             November 1997  [W. Landsman]
Major rewrite to allow vector inputs   W. Landsman  February 2000
Fix possible error in seconds display when Precision=0 
                        P. Broos/W. Landsman April 2002
Added /TRUNCATE keyword, put leading zeros in seconds display
                        P. Broos/W. Landsman September 2002
Fix declination zero values under vector processing W.Landsman Feb 2004
Fix possible problem in leading zero display W. Landsman June 2004
Assume since V5.4, omit fstring() call  W. Landsman April 2006
Fix significant bug when round a declination with -199.99  W. L.  Sep 2012