File Exchange

image thumbnail

Date Vector/Number to ISO 8601 Date String

version 2.0.0 (17.9 KB) by Stephen Cobeldick
Convert a Date Vector/Number to an ISO 8601 Date String. Tokens control the date/time notation.

4 Downloads

Updated 01 May 2019

View License

Easy conversion of a date vector or a serial date number into a date string. The date string may be an ISO 8601 timestamp or a single date/time value, selected by (optional) input token/s. Multiple tokens may be used to output multiple strings.

The ISO 8601 timestamp style options supported by this function are:
* Date in calendar, ordinal 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).

By default the function uses the current time and returns the basic ISO 8601 calendar timestamp: this is very useful for naming files that sort alphabetically into chronological order!

### Examples ###

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

>> datestr8601()
ans = '19990103T150648'

>> datestr8601([],'yn_HM')
ans = '1999003_1506'

>> datestr8601(clock,'*ymdHMS')
ans = '1999-01-03T15:06:48'

>> [D1,D3] = datestr8601(now-2,'D','DDD')
D1 = '5'
D3 = 'Fri'

>> datestr8601(datetime,'DDDD','d*','mmmm','yyyy')
ans = 'Sunday 3rd January 1999'

>> [da,YWD,mmyy] = datestr8601([],'d*','*YWD','mmmm','yyyy');
>> sprintf('The %s of %s has the ISO week-date "%s".',da,mmyy,YWD)
ans = 'The 3rd of January 1999 has the ISO week-date "1998-W53-7".'

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

### Single-Value Strings ###

* One date/time value per output string (note: can be joined afterwards, e.g. using SPRINTF).
* Consistent token syntax (UPPERCASE = week-numbering year, lowercase = calendar year).
* Easily adapted to other languages.
* Single-Values include: day of the year or days remaining in year; year quarter (3-month or 13-week); year; month as digit or name; day of week as digit or name; date of month; hour; minute; second; deci/centi/milliseconds.

Cite As

Stephen Cobeldick (2019). Date Vector/Number to ISO 8601 Date String (https://www.mathworks.com/matlabcentral/fileexchange/34095-date-vector-number-to-iso-8601-date-string), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (5)

Tago

@Tago: you seem to be trying to use DATESTR8601 as if it was MATLAB's inbuilt DATESTR. In actual fact DATESTR8601 is not the same function as the inbuilt DATESTR: they are different functions with different syntaxes and different documentation. You should try reading the DATESTR8601 documentation, as then you would know how to use it.

Both of your cases are easy to achieve:

>> datestr8601([],'ymdHMS3')
ans = 20181117T144652.899

>> datestr8601([],'ymd')
ans = 20181117

Tago

Sometimes simple to use, but not working fine. Simple requests like:
datestr8601([],'yyyy-mm-dd HH:MM:SS.FFF')
datestr8601([], 'yyyy-mm-dd');
Everything failed,

Long

Thanks a lot. A very useful subroutine.

Updates

2.0.0

* Better parsing algorithm.
* Add HTML documentation.

1.17.0.0

* Update online blurb.
* Add concatenation of remaining strings into last output (if more tokens than outputs).

1.16.0.0

- Downloadable as toolbox

1.15.0.0

- Remove calendar week number (confusing!)

1.14.0.0

- Improve token input checking and error messages.
- Restrict date-time separator character to ' ','T','@','_'.
- Add ordinals for Day of Year (required token format change).

1.13.0.0

- Removed 'F' from ISO 8601 timestamps: please use decimal fraction instead.
- Complete list of date-time separator exclusions.
- Improve examples.
- Simpler Midnight/AM/Noon/PM calculation.

1.12.0.0

- Disallow period '.' as date-time separator character.

1.11.0.0

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

1.9.0.0

- Allow 'F' (millisecond) in 8601 timestamp tokens.

1.8.0.0

- Fix bug in Midnight/AM/Noon/PM calculation.
- More examples.

1.7.0.0

- Help improved to better contrast calendar vs week-numbering dates.
- Remove basic format prefix 'B', and add extended format prefix '*' (logical, easier to read and search for).
- Test function string can be displayed directly in command window.

1.6.0.0

- Add day-of-week (as a number) and year (week-date) tokens.
- Examples that better illustrate the ISO 8601 week date.
- Change token syntax (for consistency with calendar / week-date year-type).

1.5.0.0

Add default time (current time).
Add default token 'BymdHMS'.
Add ordinal date with suffix, eg '3rd'.

1.4.0.0

- Now accepts Date Number OR Date Vector.
- Now accepts multiple input Tokens (to provide multiple output Strings).
- Add 13-week year-quarter token.
- Improve help documentation.

1.3.0.0

Added Ordinal Date style, and format control.

1.2.0.0

Some corrections to Description field and Mfile help comments.

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