Convert Between Datetime Arrays and Character Vectors

A date can be a character vector composed of fields related to a specific date and time. There are several ways to represent dates and times in several text formats. For example, all the following are character vectors represent August 23, 2010 at 04:35:42 PM:

'23-Aug-2010 04:35:06 PM'
'Wednesday, August 23'
'08/23/10 16:35'
'Aug 23 16:35:42.946'

A date character vector includes characters that separate the fields, such as the hyphen, space, and colon used here:

d = '23-Aug-2010 16:35:42'	

Convert one or more date character vectors to a datetime array using the datetime function. For the best performance, specify the format of the input character vectors as an input to datetime.

t = datetime(d,'InputFormat','dd-MMM-yyyy HH:mm:ss')

t = 

   23-Aug-2010 16:35:42

Although the date string, d, and the datetime scalar, t, look similar, they are not equal. View the size and data type of each variable.

whos d t

    Name      Size            Bytes  Class       Attributes

  d         1x20               40  char                  
  t         1x1               121  datetime              

Convert a datetime array to a character vector that uses char or cellstr. For example, convert the current date and time to a timestamp to append to a file name.

t = datetime('now','Format','yyyy-MM-dd''T''HHmmss')

t = 

  datetime

   2016-12-11T125628

S = char(t);
filename = ['myTest_',S]

filename =

    'myTest_2016-12-11T125628'

Convert Serial Date Numbers to Datetime Arrays

Serial time can represent fractions of days beginning at midnight. For example, 6 p.m. equals 0.75 serial days, so the character vector '31-Oct-2003, 6:00 PM' in MATLAB is date number 731885.75.

Convert one or more serial date numbers to a datetime array using the datetime function. Specify the type of date number that is being converted:

t = datetime(731885.75,'ConvertFrom','datenum')

t = 

  datetime

   31-Oct-2003 18:00:00

Convert Datetime Arrays to Numeric Values

Some MATLAB functions accept numeric data types but not datetime values as inputs. To apply these functions to your date and time data, first, convert datetime values to meaningful numeric values, and then call the function. For example, the log function accepts double inputs but not datetime inputs. Suppose that you have a datetime array of dates spanning the course of a research study or experiment.

t = datetime(2014,6,18) + calmonths(1:4)

t = 

  1×4 datetime array

   18-Jul-2014   18-Aug-2014   18-Sep-2014   18-Oct-2014

Subtract the origin value. For example, the origin value can be the starting day of an experiment.

dt = t - datetime(2014,7,1)

dt = 

  1×4 duration array

    408:00:00   1152:00:00   1896:00:00   2616:00:00

dt is a duration array. Convert dt to a double array of values in units of years, days, hours, minutes, or seconds by using the years, days, hours, minutes, or seconds function, respectively.

x = hours(dt)

x =

         408        1152        1896        2616

Pass the double array as the input to the log function.

y = log(x)

y =

    6.0113    7.0493    7.5475    7.8694

Input Conversions with datenum

The datenum function is important for using Financial Toolbox software efficiently. datenum takes an input date character vector in any of several formats, with 'dd-mmm-yyyy', 'mm/dd/yyyy', or 'dd-mmm-yyyy, hh:mm:ss.ss' formats being the most common. The input date character vector can have up to six fields formed by letters and numbers separated by any other characters, such that:

For example, if the current year is 1999, then all these dates are equivalent:

'17-May-1999'
'17-May-99'
'17-may'
'May 17, 1999'
'5/17/99'
'5/17'

Also, both of these formats represent the same time.

'17-May-1999, 18:30'
'5/17/99/6:30 pm'

The default format for numbers-only input follows the US convention. Therefore, 3/6 is March 6, not June 3.

With datenum, you can convert dates into serial date format, store them in a matrix variable, and then later pass the variable to a function. Alternatively, you can use datenum directly in a function input argument list.

For example, consider the function bndprice that computes the price of a bond given the yield to maturity. First set up variables for the yield to maturity, coupon rate, and the necessary dates.

Yield       = 0.07;
CouponRate  = 0.08;
Settle      = datenum('17-May-2000');
Maturity    = datenum('01-Oct-2000');

Then call the function with the variables.

bndprice(Yield,CouponRate,Settle,Maturity)

ans =

  100.3503

Alternatively, convert date character vectors to serial date numbers directly in the function input argument list.

bndprice(0.07,0.08,datenum('17-May-2000'),... 
datenum('01-Oct-2000'))

ans =

  100.3503

bndprice is an example of a function designed to detect the presence of date character vectors and make the conversion automatically. For functions like bndprice, date character vectors can be passed directly.

bndprice(0.07,0.08,'17-May-2000','01-Oct-2000')

ans =

  100.3503

The decision to represent dates as either date character vectors or serial date numbers is often a matter of convenience. For example, when formatting data for visual display or for debugging date-handling code, you can view dates more easily as date character vectors because serial date numbers are difficult to interpret. Alternately, serial date numbers are just another type of numeric data, which you can place in a matrix along with any other numeric data for convenient manipulation.

Remember that if you create a vector of input date character vectors, use a column vector, and be sure that all character vectors are the same length. To ensure that the character vectors are the same length, fill the character vectors with spaces or zeros. For more information, see Character Vector Input.

Output Conversions with datestr

The datestr function converts a serial date number to one of 19 different date character vector output formats showing date, time, or both. The default output for dates is a day-month-year character vector, for example, 24-Aug-2000. The datestr function is useful for preparing output reports.