Extract or Assign Date and Time Components of Datetime Array

This example shows two ways to extract date and time components from existing datetime arrays: accessing the array properties or calling a function. Then, the example shows how to modify the date and time components by modifying the array properties.

Access Properties to Retrieve Date and Time Component

Create a datetime array.

t = datetime('now') + calyears(0:2) + calmonths(0:2) + hours(20:20:60)
t = 1x3 datetime array
   13-Apr-2019 20:04:36   14-May-2020 16:04:36   15-Jun-2021 12:04:36

Get the year values of each datetime in the array. Use dot notation to access the Year property of t.

t_years = t.Year
t_years = 1×3

        2019        2020        2021

The output, t_years, is a numeric array.

Get the month values of each datetime in t by accessing the Month property.

t_months = t.Month
t_months = 1×3

     4     5     6

You can retrieve the day, hour, minute, and second components of each datetime in t by accessing the Hour, Minute, and Second properties, respectively.

Use Functions to Retrieve Date and Time Component

Use the month function to get the month number for each datetime in t. Using functions is an alternate way to retrieve specific date or time components of t.

m = month(t)
m = 1×3

     4     5     6

Use the month function rather than the Month property to get the full month names of each datetime in t.

m = month(t,'name')
m = 1x3 cell array
    {'April'}    {'May'}    {'June'}

You can retrieve the year, quarter, week, day, hour, minute, and second components of each datetime in t using the year, quarter, week, hour, minute, and second functions, respectively.

Get the week of year numbers for each datetime in t.

w = week(t)
w = 1×3

    15    20    25

Get Multiple Date and Time Components

Use the ymd function to get the year, month, and day values of t as three separate numeric arrays.

[y,m,d] = ymd(t)
y = 1×3

        2019        2020        2021

m = 1×3

     4     5     6

d = 1×3

    13    14    15

Use the hms function to get the hour, minute, and second values of t as three separate numeric arrays.

[h,m,s] = hms(t)
h = 1×3

    20    16    12

m = 1×3

     4     4     4

s = 1×3

   36.5403   36.5403   36.5403

Modify Date and Time Components

Assign new values to components in an existing datetime array by modifying the properties of the array. Use dot notation to access a specific property.

Change the year number of all datetime values in t to 2014. Use dot notation to modify the Year property.

t.Year = 2014
t = 1x3 datetime array
   13-Apr-2014 20:04:36   14-May-2014 16:04:36   15-Jun-2014 12:04:36

Change the months of the three datetime values in t to January, February, and March, respectively. You must specify the new value as a numeric array.

t.Month = [1,2,3]
t = 1x3 datetime array
   13-Jan-2014 20:04:36   14-Feb-2014 16:04:36   15-Mar-2014 12:04:36

Set the time zone of t by assigning a value to the TimeZone property.

t.TimeZone = 'Europe/Berlin';

Change the display format of t to display only the date, and not the time information.

t.Format = 'dd-MMM-yyyy'
t = 1x3 datetime array
   13-Jan-2014   14-Feb-2014   15-Mar-2014

If you assign values to a datetime component that are outside the conventional range, MATLAB® normalizes the components. The conventional range for day of month numbers is from 1 to 31. Assign day values that exceed this range.

t.Day = [-1 1 32]
t = 1x3 datetime array
   30-Dec-2013   01-Feb-2014   01-Apr-2014

The month and year numbers adjust so that all values remain within the conventional range for each date component. In this case, January -1, 2014 converts to December 30, 2013.

See Also

| | |