Main Content

duration

在fixed-l长度的时间ength units

expand all in page

Description

The values in aduration arrayrepresent 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 theyears,days,hours,minutes,seconds, andmillisecondsfunctions. For example, to create an array that has elapsed times of 1, 2, and 3 hours, use thehoursfunction.

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

You also can create a duration array using thedurationfunction, 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 byH,MI, andS.

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

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.TimeStringsmust represent times using either the'hh:mm:ss'或the'dd:hh:mm:ss'format.

example

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

example

D = duration(___,'Format',displayFormat)additionally specifies a display format forD. This property changes the display ofD, 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.MSeither must be a scalar or the same size as theH,MI, andSinput arguments.

Example:持续时间(12,45岁,30岁,35)returns a duration of 12 hours, 45 minutes, 30 seconds, and 35 milliseconds.

Input matrix, specified as a numeric matrix.Xmust 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. Thedurationfunction attempts to match the format ofTimeStringsto either the'hh:mm:ss'或'dd:hh:mm:ss'formats, wheredd,hh,mm, andssrepresent 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 correspondinginfmtvalue.

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.

指定infmtas any of the following formats, wheredd,hh,mm, andss代表天,小时,分钟,秒:

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • Any of the first three formats, with up to nineScharacters 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 nineScharacters to indicate fractional second digits, such as'hh:mm:ss.SSSS'

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

Examples

collapse all

Open Live Script

Create a datetime value.

D = datetime('today')
D =datetime26-Feb-2022

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

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

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

Then, addDandH.

T = D + H
T =1x4 datetimeColumns 1 through 3 26-Feb-2022 00:00:00 26-Feb-2022 02:00:00 26-Feb-2022 04:00:00 Column 4 26-Feb-2022 06:00:00

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

Open Live Script

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

D = duration(1,30:33,0)
D =1x4 duration01:30:00 01:31:00 01:32:00 01:33:00
Open Live Script

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

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

Convert the matrix to a duration array.

D = duration(X)
D =2x1 duration12:17:54 09:32:03
Open Live Script

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

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

Convert a cell array of character vectors.

T = {'12:54:37','8:03:12'}; D = duration(T)
D =1x2 duration12: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 =duration24:54:21

Open Live Script

指定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 =duration01: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'}

ConvertT一个数组。指定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 duration00:01:34.862 01:07:07.218
Open Live Script

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

Tips

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

Extended Capabilities

Version History

介绍了R2014b

See Also

|||||

Topics