| Allegro CL version 10.0 Significantly revised from 9.0. 9.0 version | ||||||||||
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.
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.
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:
t or
nil),
seconds (an integer or a ratio),
minutes (an integer),
hours (an integer),
and days
(an integer).
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.
(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"
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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had significant revisions compared to the 9.0 page.
Created 2019.8.20.
| Allegro CL version 10.0 Significantly revised from 9.0. 9.0 version | ||||||||||