FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

string-to-universal-time

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):

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): 

Return values

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:

  1. When native is 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.
  2. A keyword naming the format for the successful parse -- the values are the same as the valid values of format.
  3. If the format does not support specification of a time zone (as with :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.

Further notes

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.

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"

Years prior to 1900 and BCE years

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version