sscan_time - input conversion of date/time representations


     #include <timeio.h>

     TIME sscan_time(char *string);

     int time_is_invalid(TIME t);


     sscan_time reads from a character string representing a calendar  date
     / clock time in a standard format, returning a double-precision float-
     ing point number representing the elapsed time in SI  seconds  between
     the  represented  time  and  an arbitrary epoch.

     The function supports a range of clock systems including  Atomic  Time
     (Temps  Atomique  Internationale,  TAI),  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]

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


     JSOC TN-07-001


     None.   When  an  indecipherable  string  is  encountered,  sscan_time
     returns  the valid time JULIAN_DAY_ZERO, represented by sprint_time as
     -4712.01.01_12:00:00.000_TT or -4712.01.01_11:59:27.816_UT or  JD_0.0.
     The  function time_is_invalid, called with JULIAN_DAY_ZERO, or a ,NaN, as
     an argument will return a 1; otherwise it returns 0..


     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
     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.

     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.  In particular, there is currently no support for scanning
     of strings in ISO-8601 format, though they can be generated.

     Because  of  the  use  of  strtok  in  parsing  strings in sscan_time,
     repeated separator symbols (.:_) are treated as single symbols.

     Strings with a plus or minus symbol in the hours or minutes field  are
     subject  to misinterpretation by sscan_time, sue to confusion with the
     ISO time-zone designator.

     Ephemeris Time and "Carrington Time" are not supported.