sscan_time(3)
NAME
sscan_time - input conversion of date/time representations
SYNOPSIS
#include <timeio.h>
TIME sscan_time(char *string);
int time_is_invalid(TIME t);
DESCRIPTION
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.
SEE ALSO
JSOC TN-07-001
sprint_time
DIAGNOSTICS
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..
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.
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.