ISO 8601 Date String to Serial Date Number

Version 2.0.1 (15.5 KB) by Stephen23
Convert an ISO 8601 Date String to Serial Date Numbers. Auto-detect or select the timestamp style.
1.6K Downloads
Updated 29 Nov 2020

View License

Easy conversion of an ISO 8601 formatted date string (timestamp) into a serial date number. ISO 8601 formatted timestamp/s within the date string are automatically detected, or by supplying an optional input token the timestamp/s format can be restricted to detect only one particular style.

The ISO 8601 timestamp style options supported by this function are:
* Date in ordinal, calendar, or week-numbering notation.
* Basic or extended format.
* Choice of date-time separator character.
* Full or lower precision (fewer trailing date/time units).
* Decimal fraction of the trailing unit (decimal places).

Does NOT parse or support timezones.

The function returns:
1) The serial date numbers converted from the timestamps in the input string.
2) The input string parts that are split by the detected timestamps.
3) A Cell Array of tokens giving the detected timestamps' styles.

### Examples ###

* Using the date+time given by date vector [1999,1,3,15,6,48.0568].

>> datenum8601('1999-01-03 15:06:48.0568') % calendar, extended
ans = 730123.62972287962

>> datenum8601('1999003T150648.0568') % ordinal, basic
ans = 730123.62972287962

>> datenum8601('1998W537_150648.0568') % week numbering, basic
ans = 730123.62972287962

>> [dtn,spl,tkc] = datenum8601('A19990103B1999-003C1998-W53-7D')
dtn = [730123;730123;730123]
spl = {'A','B','C','D'}
tkc = {'ymd';'*yn';'*YWD'}

>> [dtn,spl] = datenum8601('1999-003T15')
dtn = 730123.6250
spl = {'',''}
tkc = {'*ynTH'}

>> [dtn,spl] = datenum8601('1999-01-03T15','*ymd') % specify match token.
dtn = 730123.0000
spl = {'','T15'}

>> datevec(datenum8601('19990103 200012')) % default allows 'T @_' separator.
ans =
1999 1 3 20 0 12
>> datevec(datenum8601('19990103 200012','_')) % date-time separator char.
ans =
1999 1 3 0 0 0
2000 12 1 0 0 0

### ISO 8601 Date Notations ###

Timestamps are shown here in extended format with the default date-time separator character 'T'.

1) Calendar:
<year>-<month>-<dayofmonth>T<hour>:<minute>:<second>
string: '1999-01-03T15:06:48'
token: '*ymdHMS'

2) Ordinal:
<year>-<dayofyear>T<hour>:<minute>:<second>
string: '1999-003T15:06:48'
token: '*ynHMS'

3) Week-numbering:
<year>-W<weeknumber>-<dayofweek>T<hour>:<minute>:<second>
string: '1998-W53-7T15:06:48'
token: '*YWDHMS'

Cite As

Stephen23 (2024). ISO 8601 Date String to Serial Date Number (https://www.mathworks.com/matlabcentral/fileexchange/39389-iso-8601-date-string-to-serial-date-number), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2010b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes
2.0.1

* Add error IDs.

2.0.0

* Better parsing algorithm.
* Add HTML documentation.

1.9.0.0

* Update online blurb.

1.8.0.0

- Downloadable as toolbox

1.7.0.0

- Simplify week/month regular expression.

1.6.0.0

- Improve token input checking and error messages.
- Restrict date-time separator character to ' ','T','@','_'.
- Parse multiple timestamps in one string.

1.5.0.0

- Removed 'F' from ISO 8601 timestamps: please use decimal fraction instead.
- Complete list of date-time separator exclusions.
- Improve examples.

1.4.0.0

- Disallow period '.' as date-time separator character.
- Allow for month zero in string (not handled consistently by "datenum").

1.3.0.0

ISO 8601 dates/timestamps:
- Allow decimal fraction of any trailing unit (N decimal places).
- Allow choice of any date-time separator character.

1.1.0.0

- Allow 'F' (millisecond) in 8601 timestamp tokens.
- Fix bug in ordinal-token date parsing.

1.0.0.0