Function | Package: excl | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| 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):

- `: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 http://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):

### 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

- For some formats, it is possible that a legal values for string cannot be represented by a proper universal time. This can happen in `: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.
- The `: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.

### 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.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version