timeofday

Elapsed time since midnight for datetime arrays

Syntax

T = timeofday(DT)

[T,D] = timeofday(DT)

Description

T = timeofday(DT) returns the clock time for every day in the input datetime array. The function returns the clock times as a duration array whose values equal the elapsed time since midnight for each element in the datetime array.

For datetime arrays without time zones, and in most other cases, the elapsed time since midnight, E, is equal to

E = hours(DT.Hour) + minutes(DT.Minute) + seconds(DT.Second)

If DT has its TimeZone property set to a time zone that respects Daylight Saving Time (DST), then timeofday takes DST into account. For more information, see Algorithms.

The output argument T is also equivalent to DT - dateshift(DT,'start','day').

[T,D] = timeofday(DT) also returns the date portions of the values in DT as the datetime array D.

The output argument D is equivalent to dateshift(DT,'start','day').

Examples

Calculate Elapsed Times Since Midnight

Create a datetime array.

DT = datetime('now') + hours(1:3)

DT = 1x3 datetime
   05-Sep-2024 16:22:10   05-Sep-2024 17:22:10   05-Sep-2024 18:22:10

Calculate the elapsed time since midnight for each input value. Display the times as hours, minutes, and seconds.

T = timeofday(DT)

T = 1x3 duration
   16:22:10   17:22:10   18:22:10

Return Date Portions of datetime Array

Create a datetime array.

DT = datetime('now') + hours(1:3)

DT = 1x3 datetime
   05-Sep-2024 15:28:05   05-Sep-2024 16:28:05   05-Sep-2024 17:28:05

Return the date portions of DT as a second datetime array. Because the hour, minute, and second components of D are all set to midnight (or 00:00:00 in 24-hour format), D displays only the dates.

[T,D] = timeofday(DT)

T = 1x3 duration
   15:28:05   16:28:05   17:28:05

D = 1x3 datetime
   05-Sep-2024   05-Sep-2024   05-Sep-2024

Elapsed Times with DST Shift

Calculate elapsed times since midnight on a day with a Daylight Saving Time (DST) shift.

Create a datetime array. Set its TimeZone property to a time zone that observes DST. Set the date to a day when a DST shift occurred.

tz = 'America/New_York';
fmt = 'dd-MMM-yyyy HH:mm:ss z';
DT = datetime(2015,3,8,'TimeZone',tz,'Format',fmt) + hours(1:4)

DT = 1x4 datetime
   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT   08-Mar-2015 04:00:00 EDT   08-Mar-2015 05:00:00 EDT

Calculate the elapsed times. The DST shift occurred at 02:00 on March 8, 2015 in this time zone. timeofday accounts for the shift for times at or after 02:00 on this date. Set the format of T to display elapsed times in hours.

T = timeofday(DT);
T.Format = 'h'

T = 1x4 duration
   1 hr   2 hr   3 hr   4 hr

For comparison, calculate elapsed times using the hour, minute, and second components of DT. This calculation does not account for the DST shift.

E = hours(DT.Hour) + minutes(DT.Minute) + seconds(DT.Second)

E = 1x4 duration
   1 hr   3 hr   4 hr   5 hr

Set Times of Day for datetime Arrays

Set the times of day in a datetime array according to the times of day in another datetime array.

There are two ways to set the times of day.

• Split the time portions from the first datetime array by using timeofday and add the time portions to the second datetime array.

• Set the Hour, Minute, and Second components of the second datetime array equal to the Hour, Minute, and Second components of the first datetime array.

If you use the first way, you might not always account for Daylight Saving Time (DST) shifts correctly. Only the second way is always correct across any DST shifts.

Create a datetime array. Each element has a different time component.

DT1 = datetime(2015,3,7) + hours(1:4)

DT1 = 1x4 datetime
   07-Mar-2015 01:00:00   07-Mar-2015 02:00:00   07-Mar-2015 03:00:00   07-Mar-2015 04:00:00

Create a second datetime array. Each element has the same date and time components.

DT2 = datetime(2015,3,[8 8 8 8])

DT2 = 1x4 datetime
   08-Mar-2015   08-Mar-2015   08-Mar-2015   08-Mar-2015

Set the times of day in DT2 according to the times of day in DT1. Because DT1 and DT2 do not have time zones their time components are identical.

DT2 = dateshift(DT2,'start','day') + timeofday(DT1)

DT2 = 1x4 datetime
   08-Mar-2015 01:00:00   08-Mar-2015 02:00:00   08-Mar-2015 03:00:00   08-Mar-2015 04:00:00

Create a datetime array with elements that have the TimeZone property set to 'America/New_York'. Because DT3 has a time zone and a DST shift that occurs on March 8, 2015, the time components of DT3 are not the same as those of DT1.

tz = 'America/New_York';
fmt = 'dd-MMM-yyyy HH:mm:ss z';
DT3 = datetime(2015,3,8,'TimeZone',tz,'Format',fmt) + timeofday(DT1)

DT3 = 1x4 datetime
   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT   08-Mar-2015 04:00:00 EDT   08-Mar-2015 05:00:00 EDT

Display the elapsed times since midnight. timeofday accounts for the DST shift. The elapsed times show that the times in DT3 are incorrect. The last time in DT3 corresponds to 5:00 a.m. But in DT1 only four hours elapsed since midnight.

T = timeofday(DT3)

T = 1x4 duration
   01:00:00   02:00:00   03:00:00   04:00:00

To set the times of day of DT4 correctly regardless of the time zone or the day of year, use the Hour, Minute, and Second properties of DT1.

DT4 = datetime(2015,3,[8 8 8 8],'TimeZone',tz,'Format',fmt);
DT4.Hour = DT1.Hour;
DT4.Minute = DT1.Minute;
DT4.Second = DT1.Second;
DT4

DT4 = 1x4 datetime
   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT   08-Mar-2015 03:00:00 EDT   08-Mar-2015 04:00:00 EDT

In this time zone, 2:00 a.m. Eastern Standard Time did not exist on March 8, 2015, because the DST shift occurred then. The second element of the result has a time component of 3:00 a.m. Eastern Daylight Time.

Input Arguments

DT — Input dates and times

datetime array

Input dates and times, specified as a datetime array.

Output Arguments

T — Time portions of input array

duration array

Time portions of input array, returned as a duration array.

D — Date portions of input array

datetime array

Date portions of input array, returned as a datetime array.

Algorithms

A datetime array can have its TimeZone property set to a time zone that observes Daylight Saving Time (DST). The timeofday function takes DST into account.

• If the input argument DT is a datetime array with no time zone, then the output T is also equal to

  E = hours(DT.Hour) + minutes(DT.Minute) + seconds(DT.Second)
  

• If DT has its TimeZone property set to a time zone that does not observe DST, then T is equal to E.

• If DT has its TimeZone property set to a time zone that observes DST, then timeofday accounts for the DST shift on days when the shift occurs. On those days, for times after the DST shift occurs, T differs from E by the amount of the shift.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The timeofday function fully supports tall arrays. For more information, see Tall Arrays.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2014b