duration — Create duration arrays from numeric component or three-column matrix inputs.
duration(H, MI, S) and duration(H, MI, S, MS) construct duration arrays from numeric components. duration(X) accepts an N-by-3 numeric matrix whose columns are hours, minutes, and seconds. RunMat stores elapsed time as binary64 day counts and supports display-format controls.
Syntax
t = duration(X)
t = duration(hours, minutes)
t = duration(hours, minutes, seconds)
t = duration(hours, minutes, seconds, milliseconds)
t = duration(___, "Format", format)
t = duration(___, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | NumericArray | Yes | — | N-by-3 matrix of hour, minute, and second components. |
hours | NumericArray | Yes | — | Hour component. |
minutes | NumericArray | Yes | — | Minute component. |
seconds | NumericArray | Yes | — | Second component. |
milliseconds | NumericArray | Yes | — | Millisecond component. |
args | Any | Variadic | — | Duration constructor arguments. |
Returns
| Name | Type | Description |
|---|---|---|
t | Any | Duration object result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:duration:InvalidArgument | Arguments or option grammar do not match supported duration forms. | duration: invalid argument |
RunMat:duration:InvalidInput | Input values cannot be converted/broadcast/formatted to a valid duration result. | duration: invalid input |
RunMat:duration:Internal | Internal duration state or indexing/evaluation failed unexpectedly. | duration: internal operation failed |
How duration works
duration(X)requires a numeric matrix with exactly three columns and returns anN-by-1 duration array.duration(H, M, S)treats the inputs as hours, minutes, and seconds.duration(H, M, S, MS)adds the millisecond component to the elapsed time.- All eight signed and unsigned integer classes are accepted in the documented numeric forms. Computation and storage use binary64 day counts, so wide integer values follow the constructor's documented numeric conversion boundary rather than preserving integer storage.
NaN, positive infinity, and negative infinity components remain nonfinite duration values and display asNaN,Inf, and-Infwithout changing their stored values.- The one-component
duration(H)and two-componentduration(H, M)conveniences are compatibility-gated RunMat extensions. days(X),hours(X),minutes(X),seconds(X),milliseconds(X), andyears(X)create duration values from numeric inputs.- Calling the unit helpers on a duration converts that duration back to numeric counts in the requested unit.
isduration(x)returns true for duration objects and false for non-duration values.- Scalar component inputs broadcast to match non-scalar component arrays; non-scalar inputs must share the same shape.
- GPU numeric inputs are a compatibility-gated RunMat extension, are rejected before provider access in strict mode, and produce host duration objects after owner-resolved gathering.
- Text parsing forms of
durationare not yet implemented. - The
Formatproperty controls text rendering. Supported values arehh:mm:ss,hh:mm,mm:ss,s, andss. - Linear indexing
d(k)is supported and returns duration values. - Comparison operators and
plus/minusduration arithmetic are supported. - Adding a duration to a datetime returns a datetime shifted by that elapsed time.
Does RunMat run duration on the GPU?
duration does not allocate GPU objects or invoke provider kernels. GPU numeric constructor input is a RunMat extension; strict compatibility mode rejects it before provider access, while extension mode gathers through the owning provider before building the host object.
GPU memory and residency
No. RunMat represents duration values as host-side objects with an internal day-count tensor and a Format property. Even when the constructor receives gathered numeric data, the resulting object remains resident on the CPU.
Examples
Constructing a scalar duration from numeric components
t = duration(1, 30, 45)Expected output:
t =
01:30:45Broadcasting scalar minutes across an hour vector
t = duration([1 2], 15, 0)Expected output:
t =
01:15:00 02:15:00Changing the display format without changing the stored value
t = duration(1, 5, 0);
t.Format = 'hh:mm';
disp(t)Expected output:
01:05Adding a duration to a datetime
t0 = datetime(2024, 4, 9, 8, 0, 0);
t1 = t0 + duration(1, 30, 0)Expected output:
t1 =
09-Apr-2024 09:30:00Constructing and converting duration units
d = days(1);
h = hours(d)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 the Format property change?⌄
Only the textual representation. The stored elapsed time is unchanged, so comparisons and arithmetic still refer to the same duration.
Can I index duration arrays?⌄
Yes. Linear () indexing is supported and preserves the duration type.
Does duration run on the GPU?⌄
The resulting duration object is always host-side. RunMat can accept GPU numeric inputs as a compatibility-gated extension, gather them through their owning provider, and then build the host object.
Can I add a duration to a datetime?⌄
Yes. RunMat supports datetime + duration and returns a datetime shifted by the specified elapsed time.
Related Datetime functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.