# duration

Lengths of time in fixed-length units

## Description

The values in a duration array represent elapsed times in units of fixed length, such as hours, minutes, and seconds. You also can create elapsed times in terms of fixed-length (24-hour) days and fixed-length (365.2425-day) years.

Work with duration arrays as you would work with numeric arrays. You can add, subtract, sort, compare, concatenate, and plot duration arrays. Use duration arrays to simplify calculations on datetime arrays that involve time units such as hours and minutes.

## Creation

You can create duration arrays that have specified time units using the `years`, `days`, `hours`, `minutes`, `seconds`, and `milliseconds` functions. For example, to create an array that has elapsed times of 1, 2, and 3 hours, use the `hours` function.

`D = hours(1:3)`
```D = 1×3 duration array 1 hr 2 hr 3 hr ```

You also can create a duration array using the `duration` function, described below.

### Syntax

``D = duration(H,MI,S)``
``D = duration(H,MI,S,MS)``
``D = duration(X)``
``D = duration(TimeStrings)``
``D = duration(TimeStrings,'InputFormat',infmt)``
``D = duration(___,'Format',displayFormat)``

### Description

example

````D = duration(H,MI,S)` creates a duration array from numeric arrays containing the number of hours, minutes, and seconds specified by `H`, `MI`, and `S`.```
````D = duration(H,MI,S,MS)` adds milliseconds to the duration array, specified by `MS`.```

example

````D = duration(X)` creates a column vector of durations from a numeric matrix.```

example

````D = duration(TimeStrings)` converts text that represents elapsed times into a duration array. `TimeStrings` must represent times using either the `'hh:mm:ss'` or the `'dd:hh:mm:ss'` format.```

example

````D = duration(TimeStrings,'InputFormat',infmt)` converts text using the format specified by `infmt`.```

example

````D = duration(___,'Format',displayFormat)` additionally specifies a display format for `D`. This property changes the display of `D`, but not its values. You can use this syntax with any of the arguments from the previous syntaxes.```

### Input Arguments

expand all

Hour, minute, and second arrays, specified as numeric arrays. Any of these arrays can be a scalar. All arrays that are not scalars must be the same size.

Example: `duration(12,45,7)` returns a duration of 12 hours, 45 minutes, and 7 seconds.

Millisecond array, specified as a numeric array. `MS` either must be a scalar or the same size as the `H`, `MI`, and `S` input arguments.

Example: `duration(12,45,30,35)` returns a duration of 12 hours, 45 minutes, 30 seconds, and 35 milliseconds.

Input matrix, specified as a numeric matrix. `X` must have three columns, containing the numbers of hours, minutes, and seconds, respectively.

Example: `duration([12 30 16])` returns a duration of 12 hours, 30 minutes, and 16 seconds.

Text representing elapsed times, specified as a character vector, a cell array of character vectors, or a string array. The `duration` function attempts to match the format of `TimeStrings` to either the `'hh:mm:ss'` or `'dd:hh:mm:ss'` formats, where `dd`, `hh`, `mm`, and `ss` represent days, hours, minutes, and seconds. The last field can include digits to the right of the decimal mark representing fractional seconds.

If you know the format, specify `'InputFormat'` and its corresponding `infmt` value.

Example: `duration('12:30:16')` returns a duration of 12 hours, 30 minutes, and 16 seconds.

Example: `duration('00:05:23.86')` returns a duration of 5 minutes and 23.86 seconds.

Example: `duration({'01:34:21';'23:16:54'})` returns a column vector containing two durations.

Format of the input text, specified as a character vector or string scalar.

Specify `infmt` as any of the following formats, where `dd`, `hh`, `mm`, and `ss` represent days, hours, minutes, and seconds:

• `'dd:hh:mm:ss'`

• `'hh:mm:ss'`

• `'mm:ss'`

• `'hh:mm'`

• Any of the first three formats, with up to nine `S` characters to indicate fractional second digits, such as `'hh:mm:ss.SSSS'`

## Properties

expand all

Display format, specified as a character vector or string scalar. The format can specify either a single number with time units (such as `'y'` for number of years) or a digital timer (such as `'hh:mm:ss'` for numbers of hours, minutes, and seconds).

For numbers with time units, specify one of the following:

• `'y'` — Fixed-length years, where one year equals 365.2425 days

• `'d'` — Fixed-length days, where one day equals 24 hours

• `'h'` — Hours

• `'m'` — Minutes

• `'s'` — Seconds

For digital timer formats, specify one of the following:

• `'dd:hh:mm:ss'`

• `'hh:mm:ss'`

• `'mm:ss'`

• `'hh:mm'`

• Any of the first three formats, with up to nine `S` characters to indicate fractional second digits, such as `'hh:mm:ss.SSSS'`

Example: `D.Format = 'm'` displays each value in `D` as a number of minutes.

## Examples

collapse all

Create a datetime value.

`D = datetime('today')`
```D = datetime 29-Feb-2020 ```

Create a datetime array in which each value has the same date but different time components. One convenient way to create such an array is to add a duration array to `D`.

First, create an array of hours using the `hours` function. Each element is two hours longer than the previous element.

`H = hours(0:2:6)`
```H = 1x4 duration 0 hr 2 hr 4 hr 6 hr ```

Then, add `D` and `H`.

`T = D + H`
```T = 1x4 datetime Columns 1 through 3 29-Feb-2020 00:00:00 29-Feb-2020 02:00:00 29-Feb-2020 04:00:00 Column 4 29-Feb-2020 06:00:00 ```

Use duration arrays for arithmetic operations with datetime arrays and fixed lengths of time.

Create a duration array, specifying hours, minutes, and seconds as input arguments. Since the second argument is an array, output `D` is an array that has the same size.

`D = duration(1,30:33,0)`
```D = 1x4 duration 01:30:00 01:31:00 01:32:00 01:33:00 ```

Create a numeric matrix with three columns. The columns represent hours, minutes, and seconds respectively.

`X = [12 17 54;9 32 3]`
```X = 2×3 12 17 54 9 32 3 ```

Convert the matrix to a duration array.

`D = duration(X)`
```D = 2x1 duration 12:17:54 09:32:03 ```

Convert a character vector representing a time as hours, minutes, and seconds.

```T = '6:34:12'; D = duration(T)```
```D = duration 06:34:12 ```

Convert a cell array of character vectors.

```T = {'12:54:37','8:03:12'}; D = duration(T)```
```D = 1x2 duration 12:54:37 08:03:12 ```

Convert text that also has a day component. For display, the default format for duration arrays converts the number of days to hours.

```T = '1:00:54:21'; D = duration(T)```
```D = duration 24:54:21 ```

Specify the format of text representing elapsed times, and then convert them to duration arrays.

Convert a character vector. The input format represents minutes and seconds. The output argument is a duration value, whose format represents hours, minutes, and seconds.

```T = '78:34'; infmt = 'mm:ss'; D = duration(T,'InputFormat',infmt)```
```D = duration 01:18:34 ```

Create a cell array of character vectors whose format represents minutes, seconds, and fractions of a second to three decimal places.

```infmt = 'mm:ss.SSS'; T = {'1:34.862' '67:07.218'}```
```T = 1x2 cell {'1:34.862'} {'67:07.218'} ```

Convert `T` to a duration array. Specify that the format of the duration array represents hours, minutes, seconds, and fractions of a second.

```outfmt = 'hh:mm:ss.SSS'; D = duration(T,'InputFormat',infmt,'Format',outfmt)```
```D = 1x2 duration 00:01:34.862 01:07:07.218 ```

Create a duration array from a matrix. The three columns specify hours, minutes, and seconds, respectively. Display the values in digital timer format showing minutes and seconds.

`X = [2 3 16;1 5 59;1 45 0]`
```X = 3×3 2 3 16 1 5 59 1 45 0 ```
`D = duration(X,'Format','mm:ss')`
```D = 3x1 duration 123:16 65:59 105:00 ```

## Tips

• For more information on functions that accept or return duration arrays, see Dates and Time.