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:

1. The extended universal time associated with the date-time and defaults arguments.
2. second: value 0-59.
3. minute: value 0-59.
4. hour: value 0-23.
5. ymd-day: the standard universal time specification of the day of the month (value 1-31).
6. ymd-month: the standard universal time specification of the month (value 1-12).
7. 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.
8. time-zone: the time zone value or the symbol :time-zone-not-specified.
9. 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.

(require :datetime)
(use-package :util.date-time)

;;  You will see different values for :now and :today
(date-time :now) => #<date-time "2006-07-11T22:28:08" @ #x7185242a>
(date-time :today) => #<date-time "2006-07-11T00:00:00" @ #x7185ec6a>

(date-time :zero)  => #<date-time "0000-01-01T00:00:00" @ #x717dcad2>

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.

Examples

(require :datetime)
(use-package :util.date-time)

;; Here are two examples showing all the return values
 (date-time-to-ut "1865-11-06")
 
Returns values:

 -1077724800
 0
 0
 0
 6
 11
 2265
 :time-zone-not-specified
 400

 (date-time-to-ut "1960-04-14T11:20:00+0700")

Returns values:

 1902370800
 0
 20
 11
 14
 4
 1960
 -7
 0

;; In the remaining examples, we show only the first return value
;; of DATE-TIME-TO-UT:

 (setq d (date-time "1985-04-12T23:20:50+02:00"))
=> #<date-time "1985-04-12T23:20:50+02:00" @ ...>

 (setq ut (date-time-to-ut d)) => 2691192050


 (setq d (date-time "1885-04-12T23:20:50+02:00"))
=> #<date-time "1885-04-12T23:20:50+02:00" @ ...>

 ;; The following returns a negative number since the date is before 1900.
 ;; 
 (setq ut (date-time-to-ut d)) => -464481550

 (ut-to-date-time (date-time-to-ut "1985-04-12"))
   => #<date-time "1985-04-12T00:00:00+08:00" @ #x718bad0a>

 (ut-to-date-time (date-time-to-ut "1985-04"))
   => #<date-time "1985-04-01T00:00:00+08:00" @ #x718c108a>

 (ut-to-date-time (date-time-to-ut "1985"))
   => #<date-time "1985-01-01T00:00:00+08:00" @ #x718c7092>

 ;; Note that the default may not be desirable in the following case:
 ;;
 (ut-to-date-time (date-time-to-ut "85-04-12"))
   => #<date-time "0085-04-12T00:00:00+08:00" @ #x718ebcba>

 ;; The following are ways to specify different defaults:

 (ut-to-date-time (date-time-to-ut "85-04-12"
                                    :defaults (merge-date-times "1900" :zero)))
   => #<date-time "1985-04-12T00:00:00+08:00" @ #x7191cc8a>

 (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :today))
   => #<date-time "2085-04-12T00:00:00+08:00" @ #x71924f5a>

 (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :now))
   => #<date-time "2085-04-12T22:36:32+08:00" @ #x7192cce2>

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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.