date-time-to-ut

Arguments:
date-time
&key defaults

This function returns multiple value specifying the extended universal
time associated with the argument date-time object (modified, as
described below, by defaults). This function is
the inverse of ut-to-date-time. An 'extended
universal time' is one that has values for years prior to 1900 (see
below for mroe information).

The return values are listed below. The second through seventh are
valid argument to encode-universal-time in any Common Lisp because
the year is modified by some multiple of 400 in order that it be
greater than 1899. The eighth return value (the time zone) is a valid
argument to encode-universal-time if it is a number, but not
if it is the symbol :time-zone-not-specified. The
final return value is the number of multiples of 400 needed to add to
the date-time year needed to bring the year past 1899.

In detail, the nine return values are:

The extended universal time associated with the date-time and
defaults arguments.

second: value 0-59.

minute: value 0-59.

hour: value 0-23.

ymd-day: the standard universal time specification of the day
of the month (value 1-31).

ymd-month: the standard universal time specification of the
month (value 1-12).

extended-year: if the year specified in the date-time argument
is before 1900, then this value will be that year plus a multiple of
400 to make the extended-year be beyond 1900.

time-zone: the time zone value or the symbol
:time-zone-not-specified.

year-ut-delta: the value added to the year in the
date-time argument to calculate the extended-year
value, the seventh return value.

Extended universal time

The universal-time is actually an extension of the Common Lisp
universal-time since ISO 8601 allows for dates/times to be specified
outside the range of those representable by universal-time (i.e.,
dates before 1900, or times containing fractional seconds). This
extended universal-time allows for negative values to represent dates
before 1900. In addition, extended universal-times can be non-integer
rationals representing times with fractional seconds.

The defaults argument

There are three special date-time designators:
:now, :today, and
:zero. :now means current time,
:today means the start (00:00:00) of the current
day, and :zero means the start of Jan 1, 0000.

These special date-time instances can be used as
defaults. The default
defaults is :zero. Thus, the
default behavior is to merge the argument date-time with
(date-time :zero) to get a complete date-time
instance that can be converted to universal-time. You can override
the default by specifying :today, :now, or any other date-time
instance. You can also specify nil as the
defaults, in which case no merging occurs.

See also string-to-universal-time, which converts a
string specifying a date and time (in a variety of formats including
ISO 8601) to a universal time.
See date-time.htm for information on support in
Allegro CL for parsing and generating time expressions using the ISO
8601 standard.

Copyright (c) 1998-2012, Franz Inc. Oakland, CA., USA. All rights reserved.Documentation for Allegro CL version 9.0. This page was not revised from the 8.2 page.Created 2012.5.30.