| Allegro CL version 10.0 Significantly revised from 9.0. 9.0 version | ||||||||||
Arguments: string &key format native time-zone
This function is in the :anydate module, which is
autoloaded, if necessary, when this function is called.
This function converts a string containing a date and possibly a time
representation into a universal time, or, with the right arguments
including a non-nil value for
the native keyword argument, a date-time
object. This function is a rough inverse of
universal-time-to-string
(exact inverse or not depending on the format
argument and the native argument).
string is parsed according to the value of
the format. If format is not
specified, then possible formats are tried in order and the first that
results in a successful parse is used. If none of the formats results
in a successful parse, nil is returned (note:
an error is not signaled in that case).
The format supported are (in the order they will be tried if format is not specified):
:rfc2822: sample string is "Wed, 02 Jan 2013
15:16:17 -0800",
see http://www.ietf.org/rfc/rfc2822.txt.
:w3cdtf: sample string is
"2013-01-02T15:16:17-08:00",
see https://www.w3.org/TR/NOTE-datetime.
This format accepts dates prior to midnight, January 1, 1900
(universal time 0) and even negative years (years BCE). See
below under the heading Years prior to
1900 and BCE years for further information.
:iso8601: sample string is
"2013-01-02T15:16:17-08:00", see date-time.htm.
:asctime: sample string is "Wed Jan 2 15:16:17
2013",
see http://www.cplusplus.com/reference/ctime/asctime/.
:mssql: sample string is "2013-01-02 15:16:17",
see http://msdn.microsoft.com/en-us/library/ms187819.aspx.
All sample strings are the universal time 3566157377 in the US/Pacific time zone. The linked websites describe the given formats.
If specified, format should be a single
keyword from the list above, or a list of those keywords. If a list,
each format in the list will be used to attempt to
parse string, and the first successful parse will
be returned (if none succeeds, nil is
returned). The value may also be nil, which
is the same as not specifying a value and, equivalently, as specifying
all the above keywords in order.
The native keyword argument: if specified
non-nil when format is
:iso8601 or nil
and string parses as
an :iso8601 string, then a date-time object is returned as the
first returned value rather than a universal time. This provides
better performance than the form (util.date-time:ut-to-date-time
(string-to-universal-time string :format
:iso8601)). native is ignored
if format is neither nil
nor :iso8601 or if string does
not parse as an :iso8601 string.
The time-zone keyword argument: if
non-nil, then it is the time zone in which to
interpret the time given by string. If the time
zone is given
in string, time-zone is
ignored. If non-nil, time-zone must be a
numerical time zone, acceptable as an argument to encode-universal-time. If time-zone
is nil or not given
and string has no time zone, then the currently
defined time zone is used.
Some formats,
namely :rfc2822, :iso8601 and
:w3cdtf require that a time zone is specified, so
in these cases, time-zone is ignored.
Lisp and iso8601 use opposite signs for time zones. So
cl-user(2): (string-to-universal-time "2003-12-31T10:14:55-08:00" :format :w3cdtf) 3281883295 :w3cdtf 28800 cl-user(3): (decode-universal-time *) 55 14 10 31 12 2003 2 nil 8 cl-user(4): cl-user(6): (universal-time-to-string 3281883295 :format :w3cdtf :time-zone -8) "2004-01-01T02:14:55+08:00" cl-user(7): (universal-time-to-string 3281883295 :format :w3cdtf :time-zone 8) "2003-12-31T10:14:55-08:00" cl-user(8):
If a successful parse is completed, then multiple values are returned,
otherwise the single value nil is returned.
Malformed dates merely cause nil to be
returned rather than an error being signaled. It is the responsibility
of the caller to signal an error, if one is desired. A correctly
formed date outside the range of universal time (which is times after
is midnight GMT January 1, 1900) as can happen with some formats, as
noted below) will signal an error.
The values returned upon a successful parse:
nil, the
first returned value is the universal time corresponding to the date in
string, when fractional seconds are not used in
string. If fractional seconds are used, a ratio
is returned that represents the universal time plus the fractional
seconds. The formats which allow fractional seconds
are :iso8601, :w3cdtf and
:mssql. For
example, (string-to-universal-time
"2013-01-01T00:00:00.1") returns (as the first value)
35660160001/10, where 3566016000 is the universal time corresponding
to "2013-01-01T00:00:00" and 1/10 is the fractional seconds
corresponding to ".1". When native is
non-nil and format
is :iso8601 (or nil and
string is parsed as
an :iso8601 string), the first return value is a
date-time
object rather than an integer or
ratio. When format is any other value
or nil and string is not
parsed as an :iso8601
string, native is ignored and the behavior is as
if native were nil.
:asctime and :mssql)
or string does not contain a time zone, then
:time-zone-not-specified is returned for this third
returned value. Otherwise, the time zone, in positive seconds west of
GMT or negative seconds east of GMT, is returned.
:iso8601
and :mssql. When the format
is :iso8601, you may get a negative result (as
universal times are extended to work with
date-time
objects outside the range of universal time). Note it is an error to
for string to specify a time outside the universal time range and the
consequences are undefined if such a time is specified.
:rfc2822 parser recognizes the character-based
time zone abbreviations defined in RFC 2822, which are:
EST / EDT CST / CDT MST / MDT PST / PDT
In addition, we recognize the following (technically) invalid time zones:
ET is treated as EST CT is treated as CST MT is treated as MST PT is treated as PST
See universal-time-to-string, ut-to-string-formatter, 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
will accepts dates and times prior to midnight, January 1, 1900 GMT
(universal time 0), but specified
in :w3cdtf format
only. :w3cdtf only accepts four digit years
so years between 1000 BCE and 1000 CE must have leading 0's (so 0001, -0044, and
0999). Negative years are accepted. Note there is a year 0 (which
indicates 1 BCE), so 44 BCE is specified -0043. Also, it is assumed
the Gregorian Calendar (used more or less worldwide today although
other calendars are also used for some purposes) has been used
throughout history when in fact it was introduced in 1582 and not
adopted more or less worldwide until the twentieth century. See
encode-extended-time
and decode-extended-time for more
information. Dates and times prior to prior to midnight, January 1,
1900 GMT (universal time 0) have negative universal times. See also
universal-time-to-string.
cg-user(20): (string-to-universal-time "2003-12-31T10:14:55-08:00" :format :w3cdtf) 3281883295 :w3cdtf 28800 cg-user(21): (string-to-universal-time "0003-12-31T10:14:55-08:00" :format :w3cdtf) -59832020705 :w3cdtf 28800 cg-user(22): (string-to-universal-time "-0012-12-31T10:14:55-08:00" :format :w3cdtf) -60305319905 :w3cdtf 28800 cg-user(23): (string-to-universal-time "-0043-03-15T10:00:00+01:00" :format :w3cdtf) -61308802800 :w3cdtf -3600 cg-user(24): (string-to-universal-time "1492-12-31T10:00:00+01:00" :format :w3cdtf) -12843673200 :w3cdtf -3600
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 | ||||||||||