Representing time in a computer system is surprisingly complicated. There are a large number of time representations in use, and the correct choice depends on factors such as compactness, resolution and desired operations. Humans tend to think about time in hours, days, months, years or centuries. Physicists think about time in seconds. But, a month does not have a defined number of seconds. Even a day does not have a defined number of seconds as sometimes a leap-second is introduced to synchronise properly with our earth's rotation. At the same time, resolution demands a range from better than pico-seconds to millions of years. Finally, civilizations have a wide range of calendars. Although there exist libraries dealing with most of this complexity, our desire to keep Prolog clean and lean stops us from fully supporting these.
For human-oriented tasks, time can be broken into years, months, days, hours, minutes, seconds and a timezone. Physicists prefer to have time in an arithmetic type representing seconds or fraction thereof, so basic arithmetic deals with comparison and durations. An additional advantage of the physicist's approach is that it requires much less space. For these reasons, SWI-Prolog uses an arithmetic type as its prime time representation.
Many C libraries deal with time using fixed-point arithmetic, dealing with a large but finite time interval at constant resolution. In our opinion, using a floating point number is a more natural choice as we can use a natural unit and the interface does not need to be changed if a higher resolution is required in the future. Our unit of choice is the second as it is the scientific unit.151Using Julian days is a choice made by the Eclipse team. As conversion to dates is needed for a human readable notation of time and Julian days cannot deal naturally with leap seconds, we decided for the second as our unit. We have placed our origin at 1970-01-01T0:0:0Z for compatibility with the POSIX notion of time as well as with older time support provided by SWI-Prolog.
Where older versions of SWI-Prolog relied on the POSIX conversion functions, the current implementation uses libtai to realise conversion between time-stamps and calendar dates for a period of 10 million years.
We use the following time representations
-true if daylight saving time applies to the current
time, false if daylight saving time is relevant but not
effective, and -
local
to extract the local time, ’UTC’ to extract a
UTC time or an integer describing the seconds west of Greenwich.Values for month, day, hour, minute or second need not be normalized. This flexibility allows for easy computation of the time at any given number of these units from a given timestamp. Normalization can be achieved following this call with stamp_date_time/3. This example computes the date 200 days after 2006-07-14:
?- date_time_stamp(date(2006,7,214,0,0,0,0,-,-), Stamp), stamp_date_time(Stamp, D, 0), date_time_value(date, D, Date). Date = date(2007, 1, 30)
When computing a time stamp from a local time specification, the UTC offset (arg 7), TZ (arg 8) and DST (arg 9) argument may be left unbound and are unified with the proper information. The example below, executed in Amsterdam, illustrates this behaviour. On the 25th of March at 01:00, DST does not apply. At 02.00, the clock is advanced by one hour and thus both 02:00 and 03:00 represent the same time stamp.
1 ?- date_time_stamp(date(2012,3,25,1,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -3600,
TZ = 'CET',
DST = false,
Stamp = 1332633600.0.
2 ?- date_time_stamp(date(2012,3,25,2,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -7200,
TZ = 'CEST',
DST = true,
Stamp = 1332637200.0.
3 ?- date_time_stamp(date(2012,3,25,3,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -7200,
TZ = 'CEST',
DST = true,
Stamp = 1332637200.0.
Note that DST and offset calculation are based on the POSIX function
mktime(). If mktime() returns an error, a
representation_error
dst is generated.
| key | value |
year | Calendar year as an integer |
month | Calendar month as an integer 1..12 |
day | Calendar day as an integer 1..31 |
hour | Clock hour as an integer 0..23 |
minute | Clock minute as an integer 0..59 |
second | Clock second as a float 0.0..60.0 |
utc_offset | Offset to UTC in seconds (positive is west) |
time_zone | Name of timezone; fails if unknown |
daylight_saving | Bool (true)
if dst is in effect |
date | Term date(Y,M,D) |
time | Term time(H,M,S) |
date(Y,M,D,H,M,S,O,TZ,DST) or a term date(Y,M,D).
aAbBcCdDeEff can be prefixed by an integer
to print the desired number of digits. E.g., %3f prints
milliseconds. This format is not covered by any standard, but available
with different format specifiers in various incarnations of the strftime()
function.FgGVhHIjklmMnOpam or pm
in lower case.PrRsStTuUwWxXyYz’%a, %d %b %Y %T %z’).
Our implementation supports
%:z, which modifies the output to HH:mm as required by
XML-Schema. Note that both notations are valid in ISO 8601. The sequence %:z
is compatible to the GNU date(1) command.Z+%
The table below gives some format strings for popular time
representations. RFC1123 is used by HTTP. The full implementation of
http_timestamp/2
as available from library(http/http_header) is here.
http_timestamp(Time, Atom) :-
stamp_date_time(Time, Date, 'UTC'),
format_time(atom(Atom),
'%a, %d %b %Y %T GMT',
Date, posix).
| Standard | Format string |
| xsd | ’%FT%T%:z’ |
| ISO8601 | ’%FT%T%z’ |
| RFC822 | ’%a, %d %b %Y %T %z’ |
| RFC1123 | ’%a, %d %b %Y %T GMT’ |
posix, which
currently only modifies the behaviour of the a, A, b
and B format specifiers. The predicate is used to be able
to emit POSIX locale week and month names for emitting standardised
time-stamps such as RFC1123.parse_time(Text, _Format, Stamp). See parse_time/3.
| Name | Example |
| rfc_1123 | Fri, 08 Dec 2006 15:29:44
GMT |
Fri, 08 Dec 2006 15:29:44 +0000 | |
| iso_8601 | 2006-12-08T17:29:44+02:00 |
20061208T172944+0200 | |
2006-12-08T15:29Z | |
2006-12-08 | |
20061208 | |
2006-12 | |
2006-W49-5 | |
2006-342 |
Date = date(Year,Month,Day).
Days of the week are numbered from one to seven: Monday = 1, Tuesday =
2, ... , Sunday = 7.