ut-to-date-time

Arguments: universal-time &key time-zone (complete t)

Returns the date-time object corresponding to the universal time specified by the argument. This function is the inverse of date-time-to-ut. Note 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 time-zone keyword argument must be an ANSI time zone value (a rational multiple of 1/3600 between -24 and 24 inclusive) specifying a time zone. If time-zone is not specified, then the host computer's current time-zone is used (corrected for Daylight Saving Time if applicable).

The complete keyword argument should be a boolean. If it is false, the complete-date-time is not called. If complete is true (which is the default), then the return value is the result of calling complete-date-time on the result decoded from the universal-time.

Examples

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

 (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>

;; Here we use the time-zone keyword argument (done on March 12, 2007):
 (ut-to-date-time (get-universal-time) :time-zone 6)
   => #<date-time "2007-03-12T12:20:02-06:00" @ #x71cdf832>

See also universal-time-to-string, which converts a universal time to a string in a variety of formats including ISO 8601.. 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.