sprint_time(3)

NAME

     sprint_time, sprint_ut, sprint_at,  sprint_dt  - 
     output conversion of date/time representations

SYNOPSIS

     #include <soi_time.h>

     void sprint_time(char *str,TIME t, char *type, int precision);
     sprint_at(char *str, TIME t);
     sprint_dt(char *str, TIME t);
     sprint_ut(char *str, TIME t);

DESCRIPTION

     sprint_time  writes a string  corresponding  to the elapsed time t  (a
     double-precision floating point number representing  the  elapsed time
     in SI seconds since an arbitrary epoch, .into the string location str,
     making the  appropriate conversions for the clock system designated by
     type.  The  precision of the clock seconds field  is controlled by the
     precision  argument,  which  determines the  number  of digits written
     beyond  the decimal point.  Negative  values  of  precision result  in
     suppression of increasing numbers of clock and date fields, up to val-
     ues of -5. For example, a precision of -1 will  suppress  the  seconds
     field,  and a precision of -5 (or less) will cause only the year to be
     written.

     The macros sprint_at, sprint_dt, and sprint_ut invoke sprint_time with
     the  appropriate  type and with a precision of 0 ( to the nearest sec-
     ond).

     The function supports a range of clock systems including  Atomic  Time
     (TAI,  Temps  Atomique  Internationale),  Terrestrial  Dynamical  Time
     (TDT), and Coordinated Universal Time (UTC), and a  bewildering  array
     of civil time zones tied to Universal Time.

     The detailed specifications for the format  of  date-time  representa-
     tions can be found in JSOC TN-07-001 Time Data Type and Representation
     of Dates and Times in the SDO JSOC.  Basically, three formats  are sup-
     ported: calendar, calender-clock, and Julian date:

     1.  year.month.fracday[type]

     2.  year.month.day_hour:minute:second[type]
     2a.  year-month-dayThour:minute:second

     3.  {MJD|JD}_ julday

     month  can  either  be an integer month number, a string containing at
     least the first three letters of the English month name,  or  a  Roman
     numeral;  year,  day,  hour, and minute are integers; julday, fracday,
     and second can either be decimal fractions or integers; and type is  a
     character string representing either the clock system, or, in the case
     of civil time, the time  zone.   If  the  type  field  is  empty,  the
     defaults  assumed by sscan_time() are TDT if the notation is in Julian
     day format, UTC otherwise.  TT is an acceptable substitute for TDT and
     UT for UTC.  Time zone designations can be any of the standard single-
     letter zone designations, signed 4-digit hour/minute offsets from  UT,
     or  some of the common 3- or 4-letter designations, e.g.  PST or NZDT.
     (See Table 2 of JSOC TN-07-001  for  a  listing  of  accepted  codes.)
 
     For example, the call

         char name[32];
         sprint_ut (name, sscan_time ("1981.Jul.01_00:00:19.5_TAI"));

     will place in name the string  "1981.06.30_00.00.60.500_UT" The call:

         char name[32];
         sprint_time (name, sscan_time ("1582.10.15_03:30"),"PDT");

     will place in name the string "1582.10.04_20.30.00.000_PDT".

SEE ALSO

     JSOC TN-07-001

     sscan_time

DIAGNOSTICS

     None.

BUGS

     Years  prior to 1 are assumed  written in  "astronomical" rather  than
     "historical"  fashion.  For example,  the year 0 corresponds to 1 BCE,
     -1 to 2 BCE, etc. The proleptic Julian reckoning of leap years is con-
     inued throughout.

     Times  during  UT leap seconds are represented and assumed represented
     as xxx_23:59:60.yyy_UT or the equivalent.  The leap seconds  occurring
     prior  to  1972  are proleptic.  Predicted  future UT leap seconds are
     not automatically  included  at the time  of announcement, and require
     recompilation of the library. It is assumed that leap seconds occur in
     the final minute  of  the  UT  day, regardless   of   the   zone  time
     designation.  UT times before 1959.12.31:23:59:60 are identical to TAI
     times.
     
     All times corresponding to dates on or before  4.Oct.1582  are  repre-
     sented in the Julian calendar, and all times corresponding to dates on
     or after 15.Oct.1582 are represented in the Gregorian calendar.

     When clock and date fields are suppressed with negative precision val-
     ues,  the remaining  clock and date  fields are truncated  rather than
     rounded.

     Single-letter time_zone designations are suppressed when only the date
     field    or    less    is    printed,    e.g.   1582.10.04_13:00Z   or
     1582.10.04_13:00_UT but 1582.10.04 or 1582.10.04_UT.

     All  times  represented in Julian Day formats JD or MJD are assumed to
     be in Terrestrial Dynamical Time, which is offset by an  assumed  con-
     stant 32.184 sec from Atomic Time.

     There  is  not complete reciprocity between date-time strings that can
     be produced by sprint_time and those that  can  be  properly  read  by
     sscan_time.

     Ephemeris Time and "Carrington Time" are not supported.