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.