FunctionPackage: util.date-timeToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version

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

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version