SourcePro® API Reference Guide

 
SourcePro ISO 8601:2000 Parser Reference

Table of Contents

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

The ISO 8601:2000 parser can be used by RWDateTime for parsing date, time, and date-time values from strings compatible with the ISO 8601:2000 format specification. It is selected when the RWDateTime::iso8601_2000 enumerator is passed to the appropriate RWDateTime constructor.

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.

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 1901-01-01T06:15:12Z
hh:mm:ss 06:15:12 1901-01-01T06:15:12Z
hhmm 0615 1901-01-01T06:15:00Z
hh:mm 06:15 1901-01-01T06:15:00Z
hh 06 1901-01-01T06:00:00Z
hhmmss,ss 061512,00 1901-01-01T06:15:12Z
hhmmss.ss 061512.00 1901-01-01T06:15:12Z
hh:mm:ss,ss 06:15:12,00 1901-01-01T06:15:12Z
hh:mm:ss.ss 06:15:12.00 1901-01-01T06:15:12Z
hhmm,mm 0615,20 1901-01-01T06:15:12Z
hhmm.mm 0615.20 1901-01-01T06:15:12Z
hh:mm,mm 06:15,20 1901-01-01T06:15:12Z
hh:mm.mm 06:15.20 1901-01-01T06:15:12Z
hh,hh 06,2533334 1901-01-01T06:15:12Z
hh.hh 06.2533334 1901-01-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 section entitled Avoiding Parsing Errors below for more information on avoiding these issues.

Zone Designator Formats

Zone Format Example Result
Z 13:47:42Z 1901-01-01T13:47:42Z
+hh 13:47:42+01 1901-01-01T12:47:42Z
-hh 13:47:42-01 1901-01-01T14:47:42Z
+hhmm 13:47:42+0130 1901-01-01T12:17:42Z
-hhmm 13:47:42-0130 1901-01-01T15:17:42Z
+hh:mm 13:47:42+01:30 1901-01-01T12:17:42Z
-hh:mm 13:47:42-01:30 1901-01-01T15:17:42Z
Note
Negative offsets represent minutes west of UTC, and positive offsets represent minutes east of UTC.

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. This parser will correctly handle all date-time representations that follow this format.

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-01-01T00:00:00Z
YY 18 1801-01-01T00:00:00Z
YYMMDD 130414 1913-04-14T00:00:00Z
YY-MM-DD 13-04-14 1913-04-14T00:00:00Z
-YYMM -1304 1913-04-01T00:00:00Z
-YY-MM -13-04 1913-04-01T00:00:00Z
-YY -13 1913-01-01T00:00:00Z
-–MMDD -–0414 1901-04-14T00:00:00Z
-–MM-DD -–04-14 1901-04-14T00:00:00Z
-–MM -–04 1901-04-01T00:00:00Z
-–-DD -–-14 1901-01-14T00:00:00Z
YYDDD 13104 1913-04-14T00:00:00Z
YY-DDD 13-104 1913-04-14T00:00:00Z
-DDD -104 1901-04-14T00:00:00Z
YYYYWww 1865W15 1865-04-10T00:00:00Z
YYYY-Www 1865-W15 1865-04-10T00:00:00Z
YYWwwD 13W155 1913-04-11T00:00:00Z
YY-Www-D 13-W15-5 1913-04-11T00:00:00Z
YYWww 13W15 1913-04-07T00:00:00Z
-YWwwD -3W155 1903-04-10T00:00:00Z
-Y-Www-D -3-W15-5 1903-04-10T00:00:00Z
-YWww -3W15 1903-04-06T00:00:00Z
-Y-Www -3-W15 1903-04-06T00:00:00Z
-WwwD -W155 1901-04-12T00:00:00Z
-Www-D -W15-5 1901-04-12T00:00:00Z
-Www -W15 1901-04-08T00:00:00Z
-W-D -W-5 1901-01-04T00:00:00Z

Truncated Time Formats

The ISO 8601 specification allows times to be expressed with one or more implied time components. The rules used by this parser to determine the value for any implied component are discussed in the Parsing for Implied Date and Time Components section below. The following table shows the expected result for a few example time values.

Time Format Example Result
-mmss -1512 1901-01-01T00:15:12Z
-mm:ss -15:12 1901-01-01T00:15:12Z
-mm -15 1901-01-01T00:15:00Z
-–ss -–12 1901-01-01T00:00:12Z
-mmss,ss -1512,00 1901-01-01T00:15:12Z
-mmss.ss -1512.00 1901-01-01T00:15:12Z
-mm:ss,ss -15:12,00 1901-01-01T00:15:12Z
-mm:ss.ss -15:12.00 1901-01-01T00:15:12Z
-mm,mm -15,20 1901-01-01T00:15:12Z
-mm.mm -15.20 1901-01-01T00:15:12Z
Note
Some truncated time formats cannot be reliably parsed when specified alone. See the Avoiding Parsing Errors" section below for more information on avoiding these issues.

Parsing for Implied Date and Time Components

Any implied date or time component will always have its value taken from the epoch time value 1901-01-01T00:00:00. As an example, the input 2013-04 will be parsed as a date and the resulting date-time value will be 2013-04-01T00:00:00.

Avoiding Parsing Errors

Given an input string, the ISO 8601:2000 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.