duration — Create fixed elapsed-time arrays from real numeric or logical components or a three-column matrix.
duration(H,MI,S) and duration(H,MI,S,MS) construct host duration arrays; duration(X) interprets each row of an N-by-3 real numeric or logical matrix as hours, minutes, and seconds. Logical values count as zero or one. The elapsed value is stored as binary64 days. The Format property changes rendering, not arithmetic or comparisons.
Syntax
t = duration(X)
t = duration(hours)
t = duration(hours, minutes)
t = duration(hours, minutes, seconds)
t = duration(hours, minutes, seconds, milliseconds)
t = duration(___, "Format", format)Inputs
X- Type
NumericArray- Required
- Yes
- Description
- N-by-3 matrix of hour, minute, and second components.
hours- Type
NumericArray- Required
- Yes
- Description
- Hours (RunMat-only one-component form).
hours- Type
NumericArray- Required
- Yes
- Description
- Hours.
minutes- Type
NumericArray- Required
- Yes
- Description
- Minutes.
seconds- Type
NumericArray- Required
- Yes
- Description
- Seconds.
milliseconds- Type
NumericArray- Required
- Yes
- Description
- Milliseconds.
args- Type
Any- Required
- Variadic
- Description
- Numeric components followed by an optional Format name-value pair.
Returns
t- Type
Any- Description
- Host duration array.
Errors
RunMat:duration:InvalidArgument- When
- An input is not a supported real numeric, logical, or duration value, or a constructor form is invalid.
- Message
duration: invalid argument
RunMat:duration:InvalidFormat- When
- A textual Format option or property names an unsupported display format.
- Message
duration: invalid Format
RunMat:duration:ShapeMismatch- When
- Component or operand shapes cannot be combined.
- Message
duration: incompatible sizes
RunMat:duration:Internal- When
- A validated duration result cannot be assembled.
- Message
duration: internal operation failed
Numeric construction
All eight fixed-width integer classes and logical values are accepted in component forms, with conversion at the binary64 day-count boundary. Scalar components expand to the shape of non-scalars; non-scalars must have identical shape. Empty and N-D shapes are retained. NaN and positive/negative infinity components remain nonfinite elapsed values and render as NaN, Inf, and -Inf.
An N-by-3 matrix makes an N-by-1 array. The one- and two-component conveniences are RunMat-only forms. Text parsing forms are not implemented. Supported display formats are hh:mm:ss, hh:mm, mm:ss, s, and ss.
Methods and placement
The host object stores a day-count tensor and Format property. Parentheses indexing preserves the duration class; Format can be assigned without changing elapsed values. Comparisons and plus/minus are elementwise; a numeric operand denotes fixed 24-hour days. Duration plus datetime shifts the datetime. Calendar-relative months belong to calendarDuration, not duration.
Resident numeric input is a RunMat-only extension. It is checked before provider access, gathered through its owner, and produces a host duration. There is no duration GPU kernel or fusion; native and WebAssembly runtimes use the same host semantics.
Examples
Construct a scalar
t = duration(1,30,45); h = hours(t); fprintf('t =\n'); disp(t);Expected output:
t =
01:30:45Expand a scalar component
t = duration([1 2],15,0); h = hours(t); fprintf('t =\n'); disp(t);Expected output:
t =
01:15:00 02:15:00Change rendering only
t = duration(1,5,0); t.Format = 'hh:mm'; h = hours(t); disp(t)Expected output:
01:05Shift a datetime
t0 = datetime(2024,4,9,8,0,0); t1 = t0 + duration(1,30,0); fprintf('t1 =\n'); disp(t1);Expected output:
t1 =
09-Apr-2024 09:30:00Convert fixed units
d = days(1); h = hours(d); fprintf('h = %g\n', h);Expected output:
h = 24Using duration with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how duration changes the result.
Run a small duration example, explain the result, then change one input and compare the output.
FAQ
What does Format change?⌄
Only rendering. Stored elapsed time and comparisons are unchanged.
Can I index duration arrays?⌄
Yes. Parentheses indexing preserves the duration class; Format is a separate property.
Does duration run on a GPU?⌄
Duration objects are host-side. In RunMat mode resident numeric input may be gathered through its owner after compatibility admission.
Can I add duration to datetime?⌄
Yes. The result is a datetime shifted by the fixed elapsed time.
Related Datetime functions
Duration
days · duration.eq · duration.ge · duration.gt · duration.le · duration.lt · duration.minus · duration.ne · duration.plus · duration.subsasgn · duration.subsref · hours · isduration · milliseconds · minutes · seconds · years
Calendar Duration
caldays · calendarDuration · calendarDuration.eq · calendarDuration.minus · calendarDuration.ne · calendarDuration.plus · calmonths · calquarters · calweeks · calyears · datetick · iscalendarduration · isdatetime
Datetime
Construction
Operators
datetime.eq · datetime.ge · datetime.gt · datetime.le · datetime.lt · datetime.minus · datetime.ne · datetime.plus
Indexing
Source you can read
Every RunMat function's source is public. Read exactly how duration is executed, line by line, in Rust.
- View the source for duration in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.