File Exchange

image thumbnail

ISO 8601 Date String to Serial Date Number

version 2.0.1 (15.5 KB) by Stephen Cobeldick
Convert an ISO 8601 Date String to Serial Date Numbers. Auto-detect or select the timestamp style.


Updated 29 Nov 2020

View Version History

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:
string: '1999-01-03T15:06:48'
token: '*ymdHMS'

2) Ordinal:
string: '1999-003T15:06:48'
token: '*ynHMS'

3) Week-numbering:
string: '1998-W53-7T15:06:48'
token: '*YWDHMS'

Cite As

Stephen Cobeldick (2021). ISO 8601 Date String to Serial Date Number (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (3)

Stephen Cobeldick

Jorge: thank you for your feedback. Multirow char array parsing can also be achieved in one line, using your example char array:
If any of the rows might contain multiple dates (or no date!):

Note that your example strings have six decimal digits: serial date numbers are stored in MATLAB as a double, limiting the absolute precision, as do MATLAB's date conversion functions too. Up to four decimal digits seem to be reliably converted, although the documentation only mentions milliseconds.

Currently the function only accepts a single string input (i.e. a char array of size 1*N). The design decision to not parse multirow char arrays (or cell arrays of strings) is one that I put considerable thought into. It is important to note that multiple dates are possible in the string (or possibly none!). If multirow char arrays were able to be parsed, then:
- if the converted date numbers are returned in a numeric array, then it would need to be padded with zeros (and as MATLAB has no NA value, an index of the valid entries would also be required),
- else if the converted date numbers are returned in a cell array (one cell per row), then this requires an untidy special case for char arrays of one row (as most users would expect a simple string to return the date number, and not a scalar cell array containing the date number).

Ultimately the end-user is in the best position to know what kind of strings they have (e.g. your examples with one date per string and no split parts), and as a result also to know how they want to collect the output date numbers together (e.g. in a numeric vector given one date per string, or in a cell of vectors given multiple dates per string). All of these points also must be considered with respect to the string split parts and date format tokens too...


Does what it says on the tin.


Great! However, I wasn't able to make it run (without a loop I mean) with multirow chars like this :

t =


I think it could be a good addition! (Or maybe I'm doing it wrong!)

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!