timeofday

Elapsed time since midnight for datetimes

Description

example

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

collapse all

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

t = datetime('now') + hours(1:3)
t = 1x3 datetime
   17-Aug-2020 16:35:44   17-Aug-2020 17:35:44   17-Aug-2020 18:35:44

d = timeofday(t)
d = 1x3 duration
   16:35:44   17:35:44   18:35:44

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

collapse all

Input date and time, specified as a datetime array.

Extended Capabilities

Introduced in R2014b