duration - Lengths of time in fixed-length units - MATLAB (original) (raw)

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.

The datetime data type represents points in time, while the duration and calendarDuration data types represent elapsed time using fixed-length and calendar time units, respectively.

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 thehours function.

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

Description

D = duration([H,MI,S](#d126e455135)) creates a duration array from numeric arrays containing the number of hours, minutes, and seconds specified by H, MI, andS.

example

D = duration(H,MI,S,[MS](#d126e455180)) adds milliseconds to the duration array, specified byMS.

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

example

D = duration([TimeStrings](#d126e455282)) 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](#d126e455282),'InputFormat',[infmt](#d126e455358)) 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.

example

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.

If any value is a NaN, then the corresponding duration value is aNaN.
If any value is Inf or-Inf, then the correspondingduration value is aInf or -Inf.

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.

If any value is a NaN, then the corresponding duration value is aNaN.
If any value is Inf or-Inf, then the correspondingduration value is aInf or -Inf.

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.

If any value is a NaN, then the corresponding duration value is aNaN.
If any value is Inf or-Inf, then the correspondingduration value is aInf or -Inf.

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. Theduration function attempts to match the format of TimeStrings to either the'hh:mm:ss' or 'dd:hh:mm:ss' format, where dd, hh,mm, and ss represent days, hours, minutes, and seconds.

To represent fractional seconds, use a decimal mark and specify digits to its right.
To represent a negative elapsed time, use a leading negative sign.
(Leading positive signs, '+', are not accepted. If there is no sign, then the time is a positive elapsed time.)

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.867') returns a duration of 5 minutes and 23.867 seconds.

Example: duration('-04:23:45') returns a duration of negative 4 hours, 23 minutes, and 45 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, followed by a decimal mark and up to nine S characters to indicate fractional second digits, such as'hh:mm:ss.SSS'

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, followed by a decimal mark and up to nine S characters to indicate fractional second digits, such as'hh:mm:ss.SSS'.

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

Examples

collapse all

Create a datetime value.

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 = 1×4 duration 0 hr 2 hr 4 hr 6 hr

Then, add D and H.

T = 1×4 datetime 01-Feb-2025 00:00:00 01-Feb-2025 02:00:00 01-Feb-2025 04:00:00 01-Feb-2025 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 = 1×4 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.

Convert the matrix to a duration array.

D = 2×1 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)

Convert a cell array of character vectors.

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

D = 1×2 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)

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)

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 = 1×2 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 = 1×2 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 = 3×1 duration 123:16 65:59 105:00

Tips

For more information on functions that accept or return duration arrays, seeDates 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

expand all

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

Version History

Introduced in R2014b