duration

Methods

⌂ duration

Method Reference: duration.duration

duration: D = duration (X)
duration: D = duration (H, MI, S)
duration: D = duration (H, MI, S, MS)
duration: D = duration (TimeStrings)
duration: D = duration (TimeStrings, 'InputFormat', INFMT)
duration: D = duration (…, 'Format', FMT)

Create a new array of fixed-length time durations.

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

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) creates a duration array from numeric arrays containing the number of hours, minutes, seconds, and milliseconds specified by H, MI, S, and MS, respectively.

D = duration (TimeStrings) creates a duration array from text that represents elapsed times. TimeStrings can be a character vector, a cell array of character vectors, or a string array representing times using either the 'hh:mm:ss' or the 'dd:hh:mm:ss' format.

D = duration (TimeStrings, 'InputFormat', INFMT) creates a duration array from text that represents elapsed times according to the format specified by INFMT, which can be any of the following:

  • 'dd:hh:mm:ss'
  • 'hh:mm:ss'
  • 'mm:ss'
  • 'hh:mm'
  • Any of the first three formats can also be appended with up to nine S characters to indicate fractional second digits, such as 'dd:hh:mm:ss.SS' or 'mm:ss.SS'.

D = duration (…, 'Format', FMT) specifies the format in which D is displayed. FMT can specify either a digital timer, which can have any of the valid formats for 'InputFormat' as shown above or a single number with time units by specifying one of the following:

  • 'y' fixed-length years (1 year equals 365.2425 days)
  • 'd' fixed-length days (1 day equals 24 hours)
  • 'h' hours
  • 'm' minutes
  • 's' seconds

D = duration () returns a scalar array of durations with an elapsed time value of zero. To create an empty duration array, use duration ([], [], []).

See also: years, days, hours, minutes, seconds, milliseconds, duration, isduration, calendarDuration, datetime

Source Code: duration

Example: 1

duration represents a fixed-length elapsed time — unlike calendarDuration, here a day is always 24 hours and a year a fixed number of days. Give hours, minutes and seconds:

 duration (1, 30, 15)
ans =
  duration

   01:30:15

Example: 2

Values need not lie in the usual ranges — 25 hours is fine and stays 25 hours in the default hh:mm:ss display. A fourth argument adds milliseconds.

 duration (25, 30, 0)
ans =
  duration

   25:30:00
 duration (0, 0, 1, 500)
ans =
  duration

   00:00:01

Example: 3

Build from time strings, optionally naming the 'InputFormat'.

 duration ('36:15:00')
ans =
  duration

   36:15:00
 duration ('06:15', 'InputFormat', 'mm:ss')
ans =
  duration

   00:06:15

Example: 4

The 'Format' option controls display: a digital timer (hh:mm:ss, dd:hh:mm:ss, mm:ss, ...) or a single number in one unit (y, d, h, m, s). Here the SAME duration shown six ways:

 duration (30, 15, 0, 'Format', 'hh:mm:ss')
ans =
  duration

   30:15:00
 duration (30, 15, 0, 'Format', 'dd:hh:mm:ss')
ans =
  duration

   01:06:15:00
 duration (30, 15, 0, 'Format', 'h')
ans =
  duration

   30.25 hr
 duration (30, 15, 0, 'Format', 'm')
ans =
  duration

   1815 min
 duration (30, 15, 0, 'Format', 's')
ans =
  duration

   108900 sec
 duration (30, 15, 0, 'Format', 'd')
ans =
  duration

   1.26042 days

Example: 5

A numeric matrix builds a column of durations, one per row — columns are hours, minutes and seconds.

 duration ([1, 30, 0; 0, 45, 30])
ans =
  2x1 duration array

    01:30:00    
    00:45:30