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
   23-Jan-2025 21:39:06   24-Feb-2026 17:39:06   25-Mar-2027 13:39:06

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

     1     2     3

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

     1     2     3

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
    {'January'}    {'February'}    {'March'}

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

     4     9    13

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

     1     2     3

d = 1×3

    23    24    25

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

    21    17    13

m = 1×3

    39    39    39

s = 1×3

    6.6612    6.6612    6.6612

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
   23-Jan-2014 21:39:06   24-Feb-2014 17:39:06   25-Mar-2014 13:39:06

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
   23-Jan-2014 21:39:06   24-Feb-2014 17:39:06   25-Mar-2014 13:39:06

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
   23-Jan-2014   24-Feb-2014   25-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.