Lengths of time in fixed-length time units
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.
You can create duration arrays that have specified time units using the
milliseconds functions. For example, to
create an array that has elapsed times of 1, 2, and 3 hours, use the
D = hours(1:3)
D = 1×3 duration array 1 hr 2 hr 3 hr
You also can create a duration array using the
D = duration(H,MI,S)
D = duration(H,MI,S,MS)
D = duration(X)
D = duration(___,'Format',displayFormat)
D = duration( creates a
duration array from numeric arrays containing the number of hours, minutes,
and seconds specified by
D = duration(H,MI,S, adds
milliseconds to the duration array, specified by
D = duration( creates a column
vector of durations from a numeric matrix.
H,MI,S— Hour, minute, and second arrays
Hour, minute, and second arrays, specified as numeric arrays. These arrays either must be the same size, or any one can be a scalar.
duration(12,45,07.451) returns a duration
of 12 hours, 45 minutes, and 7.451 seconds.
MS— Millisecond array
Millisecond array, specified as a numeric array.
either must be scalar or the same size as the
duration(12,45,30,35) returns a duration of
12 hours, 45 minutes, 30 seconds, and 35 milliseconds.
X— Input matrix
Input matrix, specified as a numeric matrix.
have three columns, containing the numbers of hours, minutes, and
duration([12 30 16]) returns a duration of
12 hours, 30 minutes, and 16 seconds.
Format— Display format
'hh:mm:ss'(default) | character vector
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:
Any of the first three formats, with up to nine
S characters to indicate fractional
second digits, such as
D.Format = 'm' displays each value in
D as a number of minutes.
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
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
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
For more information on functions that accept or return duration arrays, see Dates and Time.
This function fully supports tall arrays. For more information, see Tall Arrays.