timeofday

Elapsed time since midnight for datetimes

Syntax

d = timeofday(t)

Description

d = timeofday(t) returns an array of durations equal to the elapsed time since midnight for each of the datetime values in t. The output argument, d, is equal to the result of t - dateshift(t,'start','day'), and is the same size as t.

• If you have datetime values with no time zone, then d also is equal to

  e = hours(t.Hour) + minutes(t.Minute) + seconds(t.Second)

• If a datetime value has its TimeZone property set to a time zone that does not observe Daylight Saving Time (DST), then d is equal to e.

• If a datetime value 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, d differs from e by the amount of the shift.

Examples

Calculate Times of Day

Create a datetime array. Calculate the elapsed time since midnight for each datetime value.

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

t = 1x3 datetime
   21-Feb-2023 15:02:03   21-Feb-2023 16:02:03   21-Feb-2023 17:02:03

d = timeofday(t)

d = 1x3 duration
   15:02:03   16:02:03   17:02:03

List the data type of d. The timeofday function returns a duration array, not a datetime array.

whos d

  Name      Size            Bytes  Class       Attributes

  d         1x3                40  duration              

Calculate Elapsed Times on 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 date when a DST shift occurred.

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

t = 1x4 datetime
Columns 1 through 2

   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT

Columns 3 through 4

   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.

d = timeofday(t)

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

Set Times of Day for Datetimes

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. Only the second method is correct across Daylight Saving Time (DST) shifts.

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

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

t1 = 1x4 datetime
Columns 1 through 3

   07-Mar-2015 01:00:00   07-Mar-2015 02:00:00   07-Mar-2015 03:00:00

Column 4

   07-Mar-2015 04:00:00

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

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

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

Set the times of day in t2 according to the times of day in t1.

t2 = dateshift(t2,'start','day') + timeofday(t1)

t2 = 1x4 datetime
Columns 1 through 3

   08-Mar-2015 01:00:00   08-Mar-2015 02:00:00   08-Mar-2015 03:00:00

Column 4

   08-Mar-2015 04:00:00

Create a datetime array with elements that have the TimeZone property set to 'America/New_York'.

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

t3 = 1x4 datetime
Columns 1 through 2

   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT

Columns 3 through 4

   08-Mar-2015 04:00:00 EDT   08-Mar-2015 05:00:00 EDT

Calculate the elapsed time since midnight. timeofday accounts for the DST shift that occurred on March 8, 2015.

d = timeofday(t3)

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

Set the times of day in t4 according to times of day in t1. To set the times of day correctly regardless of the time zone or the day of year, use the Hour, Minute, and Second properties of t1.

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

t4 = 1x4 datetime
Columns 1 through 2

   08-Mar-2015 01:00:00 EST   08-Mar-2015 03:00:00 EDT

Columns 3 through 4

   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

t — Input date and time

datetime array

Input date and time, specified as a datetime array.

Extended Capabilities

Tall Arrays

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

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

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).