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

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.

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

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.

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

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

H,MI,S — Hour, minute, and second arrays

numeric arrays

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.

• If any value is a NaN, then the corresponding druation value is a NaN.

• If any value is Inf or -Inf, then the corresponding duration value is a Inf or -Inf.

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

MS — Millisecond array

numeric array

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.

• If any value is a NaN, then the corresponding druation value is a NaN.

• If any value is Inf or -Inf, then the corresponding duration value is a Inf or -Inf.

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

X — Input matrix

numeric matrix

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

• If any value is a NaN, then the corresponding druation value is a NaN.

• If any value is Inf or -Inf, then the corresponding duration value is a Inf or -Inf.

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

TimeStrings — Text representing elapsed times

character vector | cell array of character vectors | string array

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.

infmt — Format of input text

character vector | string scalar

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

Format — Display format

'hh:mm:ss' (default) | character vector | string scalar

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

Use Durations with Datetime Values

Create a datetime value.

D = datetime('today')

D = datetime
   05-Sep-2024

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
   05-Sep-2024 00:00:00   05-Sep-2024 02:00:00   05-Sep-2024 04:00:00   05-Sep-2024 06:00:00

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

Create Duration Array

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

Convert Matrix

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 Text to Duration Arrays

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 Input Format of Text

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

Specify Output Format of Duration Array

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.

• To convert duration arrays to numeric arrays, use the years, days, hours, minutes, seconds, and milliseconds functions. When the input argument is a duration array, these functions return numeric arrays that represent the number of years, days, hours, minutes, seconds, or milliseconds that were stored in the duration array.

Extended Capabilities

Tall Arrays

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

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Starting in R2019b, you can use duration arrays in MATLAB^® code intended for code generation. For more information, see Code Generation for Duration Arrays (MATLAB Coder) and Duration Array Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

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

Version History

Introduced in R2014b