SSCANT(3)



NAME

     sscant, sprintt, sprintut, sprintat, sprintdt - input/output
     conversion of date/time representations


SYNOPSIS

     #include <soi_time.h>

     TIME sscant(char *string);

     void sprintt(char *str,TIME t,char *type);

     sprintat(char *str, TIME t);

     sprintdt(char *str, TIME t);

     sprintut(char *str, TIME t);


DESCRIPTION

     Sscant 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 arbi-
     trary epoch.  Sprintt writes a string corresponding  to  the
     elapsed  time t into the location str making the appropriate
     conversions for the clock system  designated  by  type.  The
     macros  sprintat, sprintdt, and sprintut invoke sprintt with
     the appropriate type.

     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 sscant() 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.)
     sscant() is case-insensitive.

     For example, the call

         char name[32];
         sprintut(name,sscant ("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];
         sprintt(name,sscant ("1582.10.15_03:30"),"PDT");

     will place in name the string `1582.10.04_20:30:00.000_PDT'.


SEE ALSO


DIAGNOSTICS

     None.  When an indecipherable string is encountered,  sscant
     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 corrsponds 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  1994  are  predictions.  No predicted UT leap seconds
     are included in reckonings beyond Jan 2005.

     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.