universal-time-to-string

Arguments: ut &key relative format time-zone (show-date t) (show-time t) (show-time-zone t) (locale *locale*) stream

This function is in the :anydate module, which is autoloaded, if necessary, when this function is called.

This function takes a universal time (perhaps an extended universal time which includes fractional seconds and dates and times prior to universal time 0) and creates a string which represents the time in a specified format. That string is printed to stream, if stream is non-nil, and returned if stream is nil. :stream t causes the output to be printed to *standard-output*. If stream is t or a stream, nil is returned. If steam is nil or unspecified, the output string is returned.

This function is a rough inverse of string-to-universal-time (an exact inverse when the value of the format argument to each function is the same and non-nil and the universal time value/string are valid values).

The output is controlled by the relative keyword argument. If nil (the default) a string representing the time in standard format (modified as necessary by other keyword arguments) is created. If relative is non-nil, it should be another universal time value and the output will describe the duration from the value of relative to the value of ut. We describe the behavior when relative is nil and then the behavior when relative is a universal time. Note that the allowable values for the format argument are different in the two cases.

relative is nil

format should be one of the following keywords: :rfc2822, :w3cdtf (the default), :iso8601, :asctime, or :mssql (see string-to-universal-time for information on how the various keywords display dates and times); or a string containing field descriptor definitions (and other charaters as desired) defined in the description of locale-format-time. When format is a string, the locale keyword argument can be used to change the locale used for the rendering the printed representation of ut (see *locale*). format can also be unspecified or nil, either of which are the same as :w3cdtf.

The show-date, show-time, and show-time-zone keyword arguments are used only when format is :iso8601 or :w3cdtf. When format is one of those values, displaying the date, time and/or time zone can be suppressed by specifying nil as the value of the relevant argument (all default to t). It is an error to specify nil as the value of all three arguments.

The time-zone can be used to reinterpret ut in a specific time zone. If not specified, the current, default time zone will be used. Note: you may get different results when specifying the current time zone and letting the default behavior happen, because daylight savings time is not applied when the time-zone is supplied. See encode-universal-time for more information.

Fractional seconds are allowed for certain formats. See string-to-universal-time for details.

relative is a universal time

When relative is a universal-time, the output string will describe the duration between the value of relative and the value of ut. The duration is the time between ut and relative, regardless of which is later (so the absolute value of the difference between the two is used):

;; When :RELATIVE is a universal time, the duration is the same
;; whether :RELATIVE is bigger or smaller that the UT (required) 
;; argument:

cl-user(5): (universal-time-to-string 100 :relative 101)
"00:00:01"
cl-user(6): (universal-time-to-string 101 :relative 100)
"00:00:01"
cl-user(7): 

The content of the string depends on the format argument, which may have any of the following values:

• A function which accepts five arguments: stream (a stream, t or nil), seconds (an integer or a ratio), minutes (an integer), hours (an integer), and days (an integer).
• A string suitable as the first argument to ut-to-string-formatter.

The function ut-to-string-formatter returns a function suitable to be used as the value of format. When format is a string, that string is passed to ut-to-string-formatter.

A function returned by ut-to-string-formatter constructs a string using the supplied formatter string (the string argument to format or the first argument passed to ut-to-string-formatter) and the seconds, minutes, hours, and days values and, like universal-time-to-string itself, writes it to the stream if stream is a stream (and also returns nil); writes it to *standard-output* if stream is t (and also returns nil); and returns it if stream is nil.

When relative is a universal time, the stream argument to universal-time-to-string is passed as the stream argument to the function which is the value of format (or constructed from the string which is the value of format). time-zone is ignored (both ut and relative are taken to be in the same time zone, and a duration is not affected by time zone), as are show-date, show-time, show-time-zone, and locale.

See ut-to-string-formatter, string-to-universal-time, and the General date to universal time parsers section of date-time.htm for more information. The date-time.htm document also describes the date-time module which provides additional ISO-8601 support.

Examples

(string-to-universal-time "Thu, 01 Jan 04 19:48:21 GMT" :format :rfc2822)
  => 3281975301 :rfc2822 0
(universal-time-to-string 3281975301 :format :rfc2822)
  => "Thu, 01 Jan 2004 11:48:21 -0800"
(string-to-universal-time "Thu, 01 Jan 04 19:48:21 GMT")
  => 3281975301 :rfc2822 0
(universal-time-to-string 3281975301)
  => "2004-01-01T11:48:21"

(string-to-universal-time "Thu, 01 Jan 2004 19:48:21 GMT" :format :rfc2822)
  => 3281975301 :rfc2822 0
(universal-time-to-string 3281975301 :format :rfc2822)
  => "Thu, 01 Jan 2004 11:48:21 -0800"
(string-to-universal-time "Thu, 01 Jan 2004 19:48:21 GMT")
  => 3281975301 :rfc2822 0
(universal-time-to-string 3281975301)
  => "2004-01-01T11:48:21"

(string-to-universal-time "2003-12-31T10:14:55-08:00" :format :w3cdtf)
  => 3281883295 :w3cdtf 28800
(universal-time-to-string 3281883295 :format :w3cdtf)
  => "2003-12-31T10:14:55"
(string-to-universal-time "2003-12-31T10:14:55-08:00")
  => 3281883295 :w3cdtf 28800
(universal-time-to-string 3281883295)
  => "2003-12-31T10:14:55"

(string-to-universal-time "2003-12-31T10:14:55Z" :format :w3cdtf)
  => 3281854495 :w3cdtf 0
(universal-time-to-string 3281854495 :format :w3cdtf)
  => "2003-12-31T02:14:55"
(string-to-universal-time "2003-12-31T10:14:55Z")
  => 3281854495 :w3cdtf 0
(universal-time-to-string 3281854495)
  => "2003-12-31T02:14:55"

(string-to-universal-time "2003" :format :w3cdtf)
  => 3250396800 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3250396800 :format :w3cdtf)
  => "2003-01-01T00:00:00"
(string-to-universal-time "2003")
  => 3250396800 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3250396800)
  => "2003-01-01T00:00:00"

(string-to-universal-time "2003-12" :format :w3cdtf)
  => 3279254400 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3279254400 :format :w3cdtf)
  => "2003-12-01T00:00:00"
(string-to-universal-time "2003-12")
  => 3279254400 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3279254400)
  => "2003-12-01T00:00:00"

(string-to-universal-time "2003-12-31" :format :w3cdtf)
  => 3281846400 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3281846400 :format :w3cdtf)
  => "2003-12-31T00:00:00"
(string-to-universal-time "2003-12-31")
  => 3281846400 :w3cdtf :time-zone-not-specified
(universal-time-to-string 3281846400)
  => "2003-12-31T00:00:00"

(string-to-universal-time "20031231" :format :iso8601)
  => 3281846400 :iso8601 :time-zone-not-specified
(universal-time-to-string 3281846400 :format :iso8601)
  => "2003-12-31T00:00:00"
(string-to-universal-time "20031231")
  => 3281846400 :iso8601 :time-zone-not-specified
(universal-time-to-string 3281846400)
  => "2003-12-31T00:00:00"
(string-to-universal-time "20031231" :format :iso8601 :native t)
  => #<util.date-time:date-time "2003-12-31" @ #x1000117b1f2> nil nil

(string-to-universal-time "Sun Jan  4 16:29:06 2004" :format :asctime)
  => 3282251346 :asctime :time-zone-not-specified
(universal-time-to-string 3282251346 :format :asctime)
  => "Sun Jan  4 16:29:06 2004"
(string-to-universal-time "Sun Jan  4 16:29:06 2004")
  => 3282251346 :asctime :time-zone-not-specified
(universal-time-to-string 3282251346)
  => "2004-01-04T16:29:06"

(string-to-universal-time "2004-07-08 23:56:58" :format :mssql)
  => 3298345018 :mssql :time-zone-not-specified
(universal-time-to-string 3298345018 :format :mssql)
  => "2004-07-08 23:56:58"
(string-to-universal-time "2004-07-08 23:56:58")
  => 3298345018 :iso8601 :time-zone-not-specified
(universal-time-to-string 3298345018)
  => "2004-07-08T23:56:58"

(string-to-universal-time "2004-07-08 23:56:58.1" :format :mssql)
  => 32983450181/10 :mssql :time-zone-not-specified
(universal-time-to-string 32983450181/10 :format :mssql)
  => "2004-07-08 23:56:58.1"
(string-to-universal-time "2004-07-08 23:56:58.1")
  => 32983450181/10 :iso8601 :time-zone-not-specified
(universal-time-to-string 32983450181/10)
  => "2004-07-08T23:56:58.1"

;; This example uses *locale*:
(excl::universal-time-to-string (get-universal-time) :format "%H:%M:%S")
  => "11:01:44"

;; When RELATIVE is a universal time, FORMAT can be unspecified and
;; a suitable formatting function will be used:
(setq ut 3603660634)
(universal-time-to-string ut :relative (+ ut 1 (* 10 3600)))
  => "10:00:01"

;; Compiling the function returned by UT-TO-STRING-FORMATTER improves 
;; efficiency but is not required.
(setq f (compile nil (ut-to-string-formatter "%Dd%2Hh%2Mm%2Ss")))
(universal-time-to-string ut :relative (+ ut (* 40 3666)) :format f)
  => "1d16h44m00"

;; The string argument to UT-TO-STRING-FORMATTER can be passed as the
;; format argument to UNIVERSAL-TIME-TO-STRING with the same result:
(universal-time-to-string ut :relative (+ ut (* 40 3666)) 
                          :format "%Dd%2Hh%2Mm%2Ss")
  => "1d16h44m00"


(setq f (compile nil (ut-to-string-formatter
      		      "%D day%p, %H hour%p, %M minute%p and %S second%p")))
(universal-time-to-string 3603660634
			  :relative (+ 3603660634 (* 41 3666))
			  :format f)
  => "1 day, 17 hours, 45 minutes and 6 seconds"

Negative universal times

This function accepts negative values for the ut argument. This produces results prior to midnight, January 1, 1900 GMT (universal time 0). The format must be :w3cdtf (which is the default when ut is negative). That is also the required format for dates and times outside the universal time range passed to universal-time-to-string. See also encode-extended-time and decode-extended-time.

cg-user(52): (string-to-universal-time "2003-12-02T02:14:55" :format :w3cdtf)
3279348895
:w3cdtf
:time-zone-not-specified
cg-user(53): (universal-time-to-string 3279348895 :format :w3cdtf)
"2003-12-02T02:14:55"
cg-user(54): (string-to-universal-time "-0043-03-15T10:00:00" :format :w3cdtf)
-61308770400
:w3cdtf
:time-zone-not-specified
cg-user(55): (universal-time-to-string -61308770400)
"-43-03-15T10:00:00"
cg-user(56): (string-to-universal-time "1492-12-02T02:14:55" :format :w3cdtf)
-12846174305
:w3cdtf
:time-zone-not-specified
cg-user(57): (universal-time-to-string -12846174305)
"1492-12-02T02:14:55"
cg-user(58): 

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.