Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Essential Tools Module User's Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

3.3 International Standards for Dates and Times

International Standard ISO 8601 specifies numeric representations of date and time. RWDateTime now supports this standard, allowing you to construct from any ISO 8601-compliant string an RWDateTime object.

The application of the ISO standard will help to avoid confusion among international users and support your application's portability. Using the ISO standard will offer you the following benefits:

The ISO 8601 format may be used with the Gregorian and the Julian systems, as well as many others.

3.3.1 Representing Dates

The ISO 8601 offers numerous choices when formatting dates. The Essential Tools Module supports all calendar dates and formats, with the exception of expanded formats.

3.3.1.1 Complete Extended Format

The complete and extended format date notation is:

YYYY-MM-DD

where YYYY is the year, MM is the month, and DD is the day.

3.3.1.2 Ordinal Dates Format

The 8601 standard also allows formatting dates based on the ordinal week or the ordinal day, rather than the month, as follows:

3.3.2 Representing Times

The complete extended format for representing time is:

HH:MM:SS

where HH is the hour, MM is the minute, and SS is the second. The time string may carry a leading "T" as in:

THH:MM:SS

The leading T may appear even when the time string is not a part of a date-time string. For example:

16:59:59 (Hour 16, minutes 59, seconds 59) or

T16:59:59

Using the same basic format, you may omit the colons (:) as follows: 165959.

For truncated representations, you may omit the seconds and/or minutes.

3.3.2.1 Applying the ISO Standard to Time Zone Offsets

Unless otherwise specified, the ISO standard applies the local time zone. To apply another time zone, use its offset from UTC (GMT).

Specifying UTC time: To specify the UTC time zone, add a "Z" to the end of the time zone string (representing "zero meridian"). For example:

01-12-24T23:59:59Z

Specifying other times: For time zone offsets east, or ahead of, UTC time, use the notation+/-HH:MM where "HH" is the hour and "MM" is the minute. For time zone offsets west, or behind, UTC time, use the notation "-HH:MM", "-HHMM", or" -HH".

Be careful when specifying times as offsets of UTC. Offsets are strictly the number of minutes and seconds offset from UTC. For this reason, a time zone may be represented as an offset from UTC in addition to the application of Daylight Saving Time (DST) rules.

You may also identify different time zones using RWZone. See Section 3.4, "Setting the Time Zone."

3.3.3 Putting Dates and Times Together

Represent a complete extended format as shown here:

YYYY-MM-DDThh:mm:ss

where T serves as a separator between date and time.

Figure 1: Breakdown of a date and time combination

3.3.4 Omitting Elements of a Date or Time String

The ISO standard allows the omission of certain components of the date or time string by substituting a hyphen to implicitly represent the omitted element. In this case, RWDateTime obtains the implied component from calls to the system.

Table 3 describes the formats for calendar dates, where Y represents year, M represents month, and D represents day.

Table 3: Calendar dates

Format Description
-YY two-digit year
-YYMM two-digit year, two-digit month
-YY-MM two-digit year, two-digit month
--MMDD two-digit month, two-digit day
--MM-DD two-digit month, two-digit day
--MM two-digit month
---DD two-digit day

Table 4 describes the formats for ordinal dates, where Y is year, Www is week number, and D is week day number.

Table 4: Ordinal dates

Format Description
-YWwwD -Y-Www-D

One-digit year followed by week number, and week day number.

Example:-1W521 and -1-W52-1 represent the first day of the 52nd week of the first year of the current decade in the current century.

-YWww -Y-Www One-digit year followed by week number
-WwwD -Www-D

Week number and week day number in default year.

Example:-W521 and -W52-1 represent the first day of the 52nd week of the current year.

-Www Week number, with default year and week day number
-W-D

Week day number in default year and week number.

Example:-358 represents the 358th day of the current year.

Examples of combined date-time formats:

When an RWDateTime is converted into a string in ISO 8601 format, the string will take on the YYYY-MM-DDThh:mm:ss form.

You may also omit the century digits without adding an additional hyphen to imply the current century.

Example: 01-12-24 to define the year as 2001

3.3.5 Complete List of Supported Formats

In conclusion, this section lists all of the supported combinations of date and time formats discussed in the sections above.

The Essential Tools Module supports all combinations of these date formats:

YYYYMMDD --MM YY-Www-D
YYYY-MM-DD ---DD YYWww
YYYY-MM YYYYDDD YY-Www
YYYY YYYY-DDD -YWwwD
YY YYDDD -Y-Www-D
YYMMDD YY-DDD -YWww
YY-MM-DD -DDD -Y-Www
-YYMM YYYYWwwD -WwwD
-YY-MM YYYY-Www-D -Www-D
-YY YYYYWww -Www
--MMDD YYYY-Www -W-D
--MM-DD YYWwwD  

The Essential Tools Module supports all combinations of the time formats shown here. Note that all of these formats may include a leading T and/or a time zone indication:

HHMMSS HH:MM:SS,SS -MM
HH:MM:SS HHMM,MM --SS
HHMM HH:MM,MM -MMSS,SS
HH:MM HH,HH -MM:SS,SS
HH -MMSS -MM,MM
HHMMSS,SS -MM:SS --SS,SS


Previous fileTop of DocumentContentsNo linkNext file

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.