SourcePro® API Reference Guide

 
SourcePro ISO 8601 Compatibility Parser Reference

Table of Contents

Deprecated:
As of SourcePro 14. See RWDateTime::Format for alternative parsers.

The ISO 8601 specification provides a set of requirements for specifying date, time, and date-time values.

The ISO 8601 Compatibility parser can be used by RWDateTime for parsing date, time, and date-time values from strings that are in the ISO 8601 format and are known to be compatible with previous versions of SourcePro. This parser was originally used as the default by RWDateTime for parsing ISO 8601 date-time values. The behavior of the parser remains unchanged to ensure compatibility for existing applications. This parser is selected by passing the RWDateTime::iso8601_compat enumerator to the appropriate RWDateTime constructor.

The parser may accept invalid formats unexpectedly and produce incorrect results. In debug builds, these formats may produce debug assertions. It is suggested that you use only the date, time, and date-time formats described below.

The following sections outline valid date and time formats handled by the parser. Each example assumes that the local time zone is set to UTC, and the current date-time is 2013-05-01T16:28:06,461Z.

Complete Date Formats

Date Format Example Result
YYYYMMDD 18650414 1865-04-14T00:00:00Z
YYYY-MM-DD 1865-04-14 1865-04-14T00:00:00Z
YYYYDDD 1865104 1865-04-14T00:00:00Z
YYYY-DDD 1865-104 1865-04-14T00:00:00Z
YYYYWwwD 1865W155 1865-04-14T00:00:00Z
YYYY-Www-D 1865-W15-5 1865-04-14T00:00:00Z

Complete And Reduced Precision Time Formats

Time Format Example Result
hhmmss 061512 2013-05-01T06:15:12Z
hh:mm:ss 06:15:12 2013-05-01T06:15:12Z
hhmm 0615 2013-05-01T06:15:00Z
hh:mm 06:15 2013-05-01T06:15:00Z
hh 06 2013-05-01T06:00:00Z
hhmmss,ss 061512,00 2013-05-01T06:15:12Z
hhmmss.ss 061512.00 2013-05-01T06:15:12Z
hh:mm:ss,ss 06:15:12,00 2013-05-01T06:15:12Z
hh:mm:ss.ss 06:15:12.00 2013-05-01T06:15:12Z
hhmm,mm 0615,20 2013-05-01T06:15:12Z
hhmm.mm 0615.20 2013-05-01T06:15:12Z
hh:mm,mm 06:15,20 2013-05-01T06:15:12Z
hh:mm.mm 06:15.20 2013-05-01T06:15:12Z
hh,hh 06,2533334 2013-05-01T06:15:12Z
hh.hh 06.2533334 2013-05-01T06:15:12Z
Note
All of the above time formats may be prefixed by a single T to indicate that a time value is being specified.
Some complete and reduced precision time formats cannot be reliably parsed as times when specified alone. See the Parsing for Implied Date and Time Components section below for more information on avoiding these issues.

Zone Designator Formats

Zone Offset Example Result
Z 09:54:16Z 2013-05-01T09:54:16Z
+hh 09:54:16+01 2013-05-01T08:54:16Z
-hh 09:54:16-01 2013-05-01T10:54:16Z
+hhmm 09:54:16+0130 2013-05-01T08:24:16Z
-hhmm 09:54:16-0130 2013-05-01T11:24:16Z
+hh:mm 09:54:16+01:30 2013-05-01T08:24:16Z
-hh:mm 09:54:16-01:30 2013-05-01T11:24:16Z
Note
Negative offsets represent minutes west of UTC, and positive offsets represent minutes east of UTC.
Negative offsets from UTC only behave correctly when used with a full date-time representation. i.e., T09:54:16-08:00 does not work, but 2013-04-19T09:54:16-08:00 does.

Complete Date-Time Formats

The ISO 8601 specification identifies a complete date-time representation as a complete date representation, a single T separator, a complete or reduced precision time representation, and an optional zone designator.

Reduced Precision and Truncated Date Formats

The ISO 8601 specification allows dates to be expressed in ways that do not indicate a specific point in time. RWDateTime is only able to represent a specific time point. As a result, the reduced precision and truncated date formats must be mapped onto specific time points. The rules used by this parser to do that mapping are covered in the Parsing for Implied Date and Time Components section below. The following table shows the expected result for a few example date values.

Date Format Example Result
YYYY-MM 1865-04 1865-04-01T00:00:00Z
YYYY 1865 1865-05-01T00:00:00Z
YY 18 1813-05-01T00:00:00Z
YYMMDD 650414 2065-04-14T00:00:00Z
YY-MM-DD 65-04-14 2065-04-14T00:00:00Z
-YYMM -6504 2065-04-01T00:00:00Z
-YY-MM -65-04 2065-04-01T00:00:00Z
-YY -65 2065-05-01T00:00:00Z
-–MMDD -–0414 2013-04-14T00:00:00Z
-–MM-DD -–04-14 2013-04-14T00:00:00Z
-–MM -–04 2013-04-01T00:00:00Z
-–-DD -–-14 2013-05-14T00:00:00Z
YYDDD 65104 2065-04-14T00:00:00Z
YY-DDD 65-104 2065-04-14T00:00:00Z
-DDD -104 2013-04-14T00:00:00Z
YYYYWww 1865W15 1865-04-10T00:00:00Z
YYYY-Www 1865-W15 1865-04-10T00:00:00Z
YYWww 65W15 2065-04-06T00:00:00Z
-YWwwD -5W155 2015-04-10T00:00:00Z
-Y-Www-D -5-W15-5 2015-04-10T00:00:00Z
-YWww -5W15 2015-04-06T00:00:00Z
-Y-Www -5-W15 2015-04-06T00:00:00Z
-WwwD -W155 2013-04-12T00:00:00Z
-Www-D -W15-5 2013-04-12T00:00:00Z
-Www -W15 2013-04-08T00:00:00Z
-W-D -W-5 2013-01-04T00:00:00Z

Truncated Time Formats

The ISO 8601 specification allows times to be expressed with one or more implied time components. This parser does not correctly handle these time formats.

Parsing for Implied Date and Time Components

Any unspecified date component will have its value determined using the same field from the current date. For example, given the date string -–12-12, the resulting date will be the 12th day of the 12th month of the current year. If the string was passed to the parser on 2013-05-01, the resulting date would be 2013-12-12. Similarly, if given the date string -–07, the resulting date would be 2013-07-01.

The use of the current date can result in some unusual behavior. Consider the case in which the current date is 2013-03-31, and the date string being parsed on that date is 2013-02. The resulting date would be 2013-02-31 which is invalid. The parser then takes this invalid date and wraps it forward into the next month, resulting in the date 2013-03-03.

Any omitted time component will always get the value zero. As an example, the date-time 2013-04-21T06Z will be parsed as 2013-04-21T06:00:00Z.

Avoiding Parsing Errors

Given an input string, the ISO 8601 parser attempts to determine if the input is a date, time or a date-time. If an input could be interpreted as either a date or a time, an attempt will be made to parse the input as a date first. If that fails, an attempt will be made to parse the input as a time. This can make it difficult to use a few of the time formats. Those cases, and appropriate workarounds, are outlined below.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.