# timeofday

Elapsed time since midnight for `datetime` arrays

## Syntax

``T = timeofday(DT)``
``[T,D] = timeofday(DT)``

## Description

example

````T = timeofday(DT)` returns a `duration` array whose values equal the elapsed time since midnight for each element in `DT`.For `datetime` arrays without time zones, and in most other cases, `T` is equal toE = 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')```.```

example

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

collapse all

Create a `datetime` array.

`DT = datetime('now') + hours(1:3)`
```DT = 1x3 datetime 03-Mar-2023 08:06:28 03-Mar-2023 09:06:28 03-Mar-2023 10:06:28 ```

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

`T = timeofday(DT)`
```T = 1x3 duration 08:06:28 09:06:28 10:06:28 ```

Create a `datetime` array.

`DT = datetime('now') + hours(1:3)`
```DT = 1x3 datetime 03-Mar-2023 07:11:50 03-Mar-2023 08:11:50 03-Mar-2023 09:11:50 ```

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 07:11:50 08:11:50 09:11:50 ```
```D = 1x3 datetime 03-Mar-2023 03-Mar-2023 03-Mar-2023 ```

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

collapse all

Input dates and times, specified as a `datetime` array.

## Output Arguments

collapse all

Time portions of input array, returned as a `duration` 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.

## Version History

Introduced in R2014b