XPath/XQuery parse-ietf-date function

Summary

Parses a string containing the date and time in IETF format, returning the corresponding xs:dateTime value.

Signature

fn:parse-ietf-date(
$value as xs:string?
) as xs:dateTime?

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function accepts a string matching the production input in the following grammar:

input ::= S? (dayname ","? S)? ((datespec S time) | asctime) S?
dayname ::= "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" | "Monday | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
datespec ::= daynum dsep monthname dsep year
asctime ::= monthname dsep daynum S time S year
dsep ::= S | (S? "-" S?)
daynum ::= digit digit?
year ::= digit digit (digit digit)?
digit ::= [0-9]
monthname ::= "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec"
time ::= hours ":" minutes (":" seconds)? (S? timezone)?
hours ::= digit digit?
minutes ::= digit digit
seconds ::= digit digit ("." digit+)?
timezone ::= tzname | tzoffset (S? "(" S? tzname S? ")")?
tzname ::= "UT" | "UTC" | "GMT" | "EST" | "EDT" | "CST" | "CDT" | "MST" | "MDT" | "PST" | "PDT"
tzoffset ::= ("+"|"-") hours ":"? minutes?
S ::= ( x09 | x0A | x0D | x20 )+

The input is case-insensitive: upper-case and lower-case distinctions in the above grammar show the conventional usage, but otherwise have no significance.

If the input is an empty sequence, the result is an empty sequence.

The dayname, if present, is ignored.

The daynum, monthname, and year supply the day, month, and year of the resulting xs:dateTime value. A two-digit year must have 1900 added to it. A year such as 0070 is to be treated as given; negative years are not permitted.

The hours, minutes, and seconds (including fractional seconds) values supply the corresponding components of the resulting xs:dateTime value; if the seconds value or the fractional seconds value is absent then zero is assumed.

If both a tzoffset and a tzname are supplied then the tzname is ignored.

If a tzoffset is supplied then this defines the hours and minutes parts of the timezone offset:

  • If it contains a colon, this separates the hours part from the minutes part.

  • Otherwise, the grammar allows a sequence of from one to four digits. These are interpreted as H, HH, HMM, or HHMM respectively, where H or HH is the hours part, and MM (if present) is the minutes part.

  • If the minutes part is absent it defaults to 00.

If a tzname is supplied with no tzoffset then it is translated to a timezone offset as follows:

tznameOffset
UT, UTC, GMT 00:00
EST -05:00
EDT -04:00
CST -06:00
CDT -05:00
MST -07:00
MDT -06:00
PST -08:00
PDT -07:00

If neither a tzoffset nor tzname is supplied, a timezone offset of 00:00 is assumed.

Examples

The expression fn:parse-ietf-date("Wed, 06 Jun 1994 07:29:35 GMT") returns xs:dateTime("1994-06-06T07:29:35Z").

The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 GMT") returns xs:dateTime("1994-06-06T07:29:35Z").

The expression fn:parse-ietf-date("Wed Jun 06 11:54:45 EST 2013") returns xs:dateTime("2013-06-06T11:54:45-05:00").

The expression fn:parse-ietf-date("Sunday, 06-Nov-94 08:49:37 GMT") returns xs:dateTime("1994-11-06T08:49:37Z").

The expression fn:parse-ietf-date("Wed, 6 Jun 94 07:29:35 +0500") returns xs:dateTime("1994-06-06T07:29:35+05:00").

Error Conditions

A dynamic error is raised if the input does not match the grammar, or if the resulting date/time value is invalid (for example, 31 February).

Notes

The parse-ietf-date function attempts to interpret its input as a date in any of the three formats specified by HTTP .

These formats are used widely on the Internet to represent timestamps, and were specified in:

(electronic mail), extended in to allow four-digit years; (Usenet Messages), obsoleted by ; POSIX asctime() format

(HTTP) officially uses a subset of those three formats restricted to GMT.

The grammar for this function is slightly more liberal than the RFCs (reflecting the internet tradition of being liberal in what is accepted). For example the function:

Accepts a single-digit value where appropriate in place of a two-digit value with a leading zero (so "Wed 1 Jun" is acceptable in place of "Wed 01 Jun", and the timezone offset "-5:00" is equivalent to "-05:00") Accepts one or more whitespace characters (x20, x09, x0A, x0D) wherever a single space is required, and allows whitespace to be omitted where it is not required for parsing Accepts and ignores whitespace characters (x20, x09, x0A, x0D) at the start or end of the string.

In new protocols IETF recommends the format of which is based on a profile of ISO 8601 similar to that already used in XPath and XSD, but the "approximate" format described here is very widely used.

An date can be generated approximately using fn:format-dateTime with a picture string of "[FNn3], [D01] [MNn3] [Y04] [H01]:[m01]:[s01] [Z0000]".