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.