### Why This Function? ###
Fast conversion of an ISO 8601 formatted Date String (timestamp) to a Serial Date Number. The input timestamp is automatically detected, or by supplying an optional input token the timestamp can be restricted to one particular style.
The ISO 8601 timestamp style options are:
- Date in ordinal, calendar or week-numbering notation.
- Basic or Extended format (without/with unit separation characters).
- Any date-time separator character (with a few exceptions).
- Full or lower precision (fewer trailing date/time units).
- Decimal fraction of the trailing unit (decimal places).
Three function outputs:
1) The Serial Date Number of the timestamp in the input string.
2) The input string parts that are split by the detected timestamp (i.e. before & after the timestamp).
3) A string token showing the detected timestamp style.
### Examples ###
Examples use the date+time described by the vector [1999,1,3,15,6,48.0568].
datenum8601(datestr8601([1999,1,3,15,6,48.0568],'ymdHMS4'))
ans = 730123.62972287962
datenum8601('1999-01-03 15:06:48.0568')
ans = 730123.62972287962
datenum8601('1999003T150648.0568')
ans = 730123.62972287962
[dtn,spl,tok] = datenum8601('AA1998W537_150648.0568ZZ')
dtn = 730123.62972287962
spl = {'AA','ZZ'}
tok = 'YWD_HMS4'
[dtn,spl,tok] = datenum8601('1999-003T15')
dtn = 730123.6250
spl = {'',''}
tok = '*ynH'
[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'
### Note ###
This function is NOT a drop-in replacement for "datenum": it has a very
different syntax and application. |
