# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materials including this page, select Japan from the country navigator on the bottom of this page.

# duration

Lengths of time in fixed-length time 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 long) 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(___,'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`, respectively.```
````D = duration(H,MI,S,MS)` adds milliseconds to the duration array, specified by `MS`.```
````D = duration(X)` creates a column vector of durations from a numeric matrix.```

example

````D = duration(___,'Format',displayFormat)` additionally specifies `displayFormat` as the value of the `Format` property of `D`. The `Format` 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. These arrays either must be the same size, or any one can be a scalar.

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

Millisecond array, specified as a numeric array. `MS` either must be 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.

## Properties

expand all

Display format, specified as a character vector. The format can be either a single number with time units (such as `0.5 yrs`) or a digital timer (such as `10:30:15` for 10 hours, 30 minutes, and 15 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

expand all

Create a datetime value.

`D = datetime('today')`
```D = datetime 19-Sep-2017 ```

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 array 0 hr 2 hr 4 hr 6 hr ```

Then, add `D` and `H`.

`T = D + H`
```T = 1x4 datetime array Columns 1 through 3 19-Sep-2017 00:00:00 19-Sep-2017 02:00:00 19-Sep-2017 04:00:00 Column 4 19-Sep-2017 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 array 01:30:00 01:31:00 01:32:00 01:33:00 ```

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 = 2 3 16 1 5 59 1 45 0 ```
`D = duration(X,'Format','mm:ss')`
```D = 3x1 duration array 123:16 65:59 105:00 ```

## Tips

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

## See Also

#### Introduced in R2014b

Was this topic helpful?

#### The Manager's Guide to Solving the Big Data Conundrum

Download white paper