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
02-Sep-2021 06:36:10   03-Oct-2022 02:36:10   03-Nov-2023 22:36:10

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

2021        2022        2023

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

9    10    11

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

9    10    11

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
{'September'}    {'October'}    {'November'}

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

36    41    44

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

2021        2022        2023

m = 1×3

9    10    11

d = 1×3

2     3     3

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

6     2    22

m = 1×3

36    36    36

s = 1×3

10.0904   10.0904   10.0904

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
02-Sep-2014 06:36:10   03-Oct-2014 02:36:10   03-Nov-2014 22:36:10

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
02-Jan-2014 06:36:10   03-Feb-2014 02:36:10   03-Mar-2014 22:36:10

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
02-Jan-2014   03-Feb-2014   03-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
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.