SPRINT_TIME(3)



NAME

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


SYNOPSIS

     #include <soi_time.h>

     TIME sscan_time(char *string);

     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

     Sscan_time reads from  a  character  string  representing  a
     calendar date / clock time in a standard format, returning a
     double-precision  floating  point  number  representing  the
     elapsed  time in SI seconds between the represented time and
     an arbitrary epoch.  Sprint_time writes a string correspond-
     ing  to  the elapsed time t into the 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 the clock seconds field.

     The  macros  sprint_at,  sprint_dt,  and  sprint_ut   invoke
     sprint_time  with  the appropriate type and with a precision
     of 0 (i.e. to the nearest second).

     The functions support a range  of  clock  systems  including
     Atomic  Time  (Temps  Atomique Internationale, TAI), Terres-
     trial 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
     representations  can  be  found  in SOI TN 94-116, "SDS Time
     Data Type and Representation of  Dates  and  Times".   Basi-
     cally,  three  formats  are  supported:  calendar, calender-
     clock, and Julian date:

     1.  year.month.fracday[_type]

     2.  year.month.day_hour:minute[:second][_type]

     3.  {MJD|JD}_ julday[_type]

     month can either be an integer month number, a  string  con-
     taining  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 SOI TN 94-116 for a listing of accepted codes.)
     sscan_time() is case-insensitive.

     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

     SOI TN 94-116


DIAGNOSTICS

     None.   When  an  indecipherable  string   is   encountered,
     sscan_time sets soi_errno to ILLEGAL_TIME_FORMAT and returns
     a valid time normally within a  day  of  the  epoch  of  the
     Julian   period,  1  Jan.  4713  BC.   (Its  internal  epoch
     representation is approximately -2.1109e11.)   It  does  not
     always  produce exactly the same time, depending on how much
     of the string could be successfully decoded.


BUGS

     Years prior to 1 are written in "astronomical"  rather  than
     "historical"  fashion.   For example, the year 0 corresponds
     to 1 B.C, -1 to 2 B.C., etc. The proleptic Julian  reckoning
     of leap years is continued 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;  those
     after  1997  are  predictions.  No predicted UT leap seconds
     are included in  reckonings  beyond  July  2009.   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
     represented   in   the   Julian   calendar,  and  all  times
     corresponding  to  dates  on  or   after   15.Oct.1582   are
     represented in the Gregorian calendar.

     Ephemeris Time and "Carrington Time" are not supported.