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:
language independence
consistency with the common 24-hour time notation system
easy comparison and sorting of combined dates and times
compatibility with many international notations, including the Chinese date notation, which already uses the sorting order of year-month-day
a four-digit year representation
The ISO 8601 format may be used with the Gregorian and the Julian systems, as well as many others.
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.
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.
Example: 2001-12-24 or December 24, 2001. You may omit the hyphens (-), as follows: 20011224 (basic format).
The 8601 standard also allows formatting dates based on the ordinal week or the ordinal day, rather than the month, as follows:
YYDDD, YY-DDD
This is a two-digit year followed by year-day number.
Example: 67-256 corresponds to 09/13/1967
YYYYDDD YYYY-DDD: four-digit year followed by year day number
Example: 1967-256 corresponds to 09/13/1967
-DDD year day number
YYYY-Www-D YYYYWwwD: Four-digit year followed by week number and week day number
YYYYWww YYYY-Www: Four-digit year number followed by week number
YYWwwD YY-Www-D: Two-digit year, week number and week day number
YYWww YY-Www: Two-digit year, week number
-YWww -Y-Www: One-digit year, week number
-WwwD -Www-D: Week number and week day number in default year
-Www: Week number; default year and week day number
-W-D: Week day number in default year and week number
Note that the week number is calculated with first week of the year which is 1. The first week of the year is the first week which contains a Thursday. Thus, the first week of the year 1994 is not the week containing the 1st of January but rather the week 03/01-09/01/1994. Year 2004 is an example of a year that has 53 ISO8601 weeks since it contains both the week containing 1st of January and the week containing 31st of December.
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.
Example:
23:59 for 23:59 and zero seconds
23 for the hour 23 with zero minutes and zero seconds
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."
Represent a complete extended format as shown here:
YYYY-MM-DDThh:mm:ss
where T serves as a separator between date and time.
Example: 2001-12-24T23:59:59 or December 24, 2001 at one minute before midnight. The separators may also be removed, as shown here: 20011224T235959
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.
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.
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:
-12-24T-59:59 represents December 24th of the current year; and 59 minutes and 59 seconds into the current hour.
--24T--59 represents the 24th day of the current month in the current year; and 59 seconds into the current minute in the current hour.
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
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 |
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.