Code covered by the BSD License  

Highlights from
ISO 8601 Date String to Serial Date Number

4.5

4.5 | 2 ratings Rate this file 18 Downloads (last 30 days) File Size: 4.1 KB File ID: #39389
image thumbnail

ISO 8601 Date String to Serial Date Number

by

 

10 Dec 2012 (Updated )

Convert an ISO 8601 Date String to Serial Date Numbers. Auto-detect or select the timestamp style.

| Watch this File

File Information
Description

Easy conversion of an ISO 8601 formatted Date String (timestamp) into a Serial Date Number. Any 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 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).

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 ###

Examples use the date+time described by the vector [1999,1,3,15,6,48.0568].

datenum8601('1999-01-03 15:06:48.0568')
 ans = 730123.62972287962

datenum8601('1999003T150648.0568')
 ans = 730123.62972287962

datenum8601('1998W537_150648.0568')
 ans = 730123.62972287962

[DtN,Spl,Tok] = datenum8601('A19990103B1999-003C1998-W53-7D')
 DtN = [730123,730123,730123]
 Spl = {'A','B','C','D'}
 Tok = {'ymd','*yn','*YWD'}

[DtN,Spl,Tok] = datenum8601('1999-003T15')
 DtN = 730123.6250
 Spl = {'',''}
 Tok = {'*ynTH'}

[DtN,Spl,Tok] = datenum8601('1999-01-03T15','*ymd')
 DtN = 730123.0000
 Spl = {'','T15'}
 Tok = {'*ymd'}

### 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'

Acknowledgements

Date Vector/Number To Iso 8601 Date String, Round Serial Date Numbers Or Date Vectors, and Time Str inspired this file.

This file inspired Numeric To English Words and Date Vector/Number To Iso 8601 Date String.

Required Products MATLAB
MATLAB release MATLAB 7.11 (R2010b)
MATLAB Search Path
/
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (3)
20 Jun 2014 Stephen Cobeldick

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

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...

19 Jun 2014 Jack

Does what it says on the tin.

31 May 2014 Jorge

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

t =

2014-02-01T23:55:04.284002Z
2014-02-02T23:55:04.161520Z
2014-02-03T23:55:04.348627Z
2014-02-04T23:55:03.517715Z

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

Updates
18 Dec 2012

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

25 Feb 2013

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

11 Mar 2013

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

24 Jun 2013

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

10 Mar 2014

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

07 Aug 2014

- Simplify week/month regular expression.

03 Nov 2014

- Downloadable as toolbox

Contact us