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 = 1×3 datetime
   02-Feb-2025 05:07:08   03-Mar-2026 01:07:08   03-Apr-2027 21:07:08

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

        2025        2026        2027

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

     2     3     4

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

     2     3     4

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 = 1×3 cell
    {'February'}    {'March'}    {'April'}

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

     6    10    14

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

        2025        2026        2027

m = 1×3

     2     3     4

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

     5     1    21

m = 1×3

     7     7     7

s = 1×3

    8.9992    8.9992    8.9992

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 = 1×3 datetime
   02-Feb-2014 05:07:08   03-Mar-2014 01:07:08   03-Apr-2014 21:07:08

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 = 1×3 datetime
   02-Jan-2014 05:07:08   03-Feb-2014 01:07:08   03-Mar-2014 21:07:08

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 = 1×3 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 = 1×3 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.