### Why This Function? ###
Fast conversion of a Date Vector or Serial Date Number to a string, the style of which is controlled by (optional) input token/s. The string may be an ISO 8601 timestamp or a single date/time value: multiple tokens may be used to output multiple strings (faster than multiple function calls).
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).
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 ###
Examples use the date+time described by the vector [1999,1,3,15,6,48.0568].
datestr8601(datenum8601('19990103T150648'),'ymdHMS4')
ans = '19990103T150648.0568'
datestr8601
ans = '19990103T150648'
datestr8601([],'yn_HM')
ans = '1999003_1506'
datestr8601(now-1,'DDDD')
ans = 'Saturday'
datestr8601(clock,'*ymdHMS')
ans = '1999-01-03T15:06:48'
[A,B,C,D] = datestr8601(clock,'ddd','mmmm','yyyy','*YWD')
sprintf('The %s of %s %s has the ISO week-date "%s".',A,B,C,D)
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 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 ###
# Faster than "datestr"!
# One date/time value per string.
# ANY combination of date/time strings can be concatenated afterward (including combinations not permitted by "datestr"): this is still faster than "datestr".
# Consistent token syntax.
# 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.
### Note ###
This function is NOT a drop-in replacement for "datestr": it has a very different syntax and application. |
