datetime — Create datetime arrays from text, components, or serial date numbers in MATLAB and RunMat.
datetime constructs datetime objects from component values, text inputs, and serial date-number forms. Supported creation paths and Format display behavior follow current MATLAB/RunMat datetime semantics.
Syntax
t = datetime()
t = datetime(textOrArray)
t = datetime(serialDateNumbers)
t = datetime(year, month, day)
t = datetime(year, month, day, hour)
t = datetime(year, month, day, hour, minute)All supported datetime forms
t = datetime()
t = datetime(textOrArray)
t = datetime(serialDateNumbers)
t = datetime(year, month, day)
t = datetime(year, month, day, hour)
t = datetime(year, month, day, hour, minute)
t = datetime(year, month, day, hour, minute, second)
t = datetime(serialDateNumbers, "ConvertFrom", "datenum")
t = datetime(___, "Format", format)
t = datetime(textOrArray, "InputFormat", inputFormat)
t = datetime(___, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
textOrArray | Any | Yes | — | String/char/date text input. |
serialDateNumbers | NumericArray | Yes | — | Numeric serial date input. |
year | NumericArray | Yes | — | Year component. |
month | NumericArray | Yes | — | Month component. |
day | NumericArray | Yes | — | Day component. |
hour | NumericArray | Yes | — | Hour component. |
minute | NumericArray | Yes | — | Minute component. |
second | NumericArray | Yes | — | Second component. |
args | Any | Variadic | — | Numeric serial input with ConvertFrom option. |
args | Any | Variadic | — | Datetime constructor arguments. |
Returns
| Name | Type | Description |
|---|---|---|
t | Any | Datetime object result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:datetime:InvalidArgument | Arguments or option grammar do not match supported datetime forms. | datetime: invalid argument |
RunMat:datetime:InvalidInput | Input values cannot be parsed/converted/broadcast to a valid datetime result. | datetime: invalid input |
RunMat:datetime:Internal | Internal datetime state or indexing/evaluation failed unexpectedly. | datetime: internal operation failed |
How datetime works
datetime()with no arguments returns the current local date and time.datetime(Y, M, D)anddatetime(Y, M, D, H, MN, S)construct datetimes from numeric components. Scalar inputs expand to match non-scalar component arrays.datetime(text)accepts string scalars, string arrays, and character vectors. Supported text includes common ISO-like forms,dd-MMM-yyyyforms, andnow.datetime(serials, 'ConvertFrom', 'datenum')interprets numeric values as MATLAB serial date numbers.datetime(serials)also accepts raw serial date numbers for the current implementation, producing datetime values directly from those serials.- The
Formatproperty controls text rendering. Assigningt.Format = 'yyyy-MM-dd HH:mm:ss'updates how the object displays without changing the stored point in time. - Linear indexing
t(k)is supported and returns datetime values. - Comparison operators and
plus/minusday arithmetic are supported. Subtracting two datetime values returns numeric day deltas.
Does RunMat run datetime on the GPU?
datetime does not allocate GPU objects or invoke provider kernels. If a numeric input originates on the GPU, RunMat gathers it before building the datetime object.
GPU memory and residency
No. RunMat represents datetime values as host-side objects with an internal serial-date 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 datetime from numeric components
t = datetime(2024, 4, 9, 13, 30, 0)Expected output:
t =
09-Apr-2024 13:30:00Parsing text into datetimes
t = datetime(["2024-04-09 13:30:00"; "2024-04-10 08:15:00"])Expected output:
t =
09-Apr-2024 13:30:00
10-Apr-2024 08:15:00Creating datetimes from serial date numbers
d = datetime([739351; 739352], 'ConvertFrom', 'datenum')Expected output:
d =
09-Apr-2024 00:00:00
10-Apr-2024 00:00:00Changing display format without changing the stored value
t = datetime(2024, 4, 9, 13, 30, 0);
t.Format = 'yyyy-MM-dd HH:mm:ss';
disp(t)Expected output:
2024-04-09 13:30:00Extracting calendar and clock components
t = datetime(2024, 4, 9, 13, 30, 5);
y = year(t)
m = month(t)
d = day(t)
h = hour(t)Expected output:
y = 2024
m = 4
d = 9
h = 13Adding days and subtracting datetimes
t0 = datetime(2024, 4, 9);
t1 = t0 + 7;
delta = t1 - t0Expected output:
delta = 7Using datetime with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how datetime changes the result.
Run a small datetime 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 serial date number is unchanged, so comparisons and arithmetic still refer to the same instant.
How is subtraction interpreted?⌄
Subtracting one datetime from another returns a numeric delta measured in days. Subtracting a numeric value from a datetime shifts it backward by that many days.
Can I index datetime arrays?⌄
Yes. Linear () indexing is supported and preserves the datetime type.
Does datetime run on the GPU?⌄
No. datetime values are represented as host-side objects. Numeric inputs may be gathered first, but the resulting datetime object remains on the CPU.
Related Datetime functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how datetime is executed, line by line, in Rust.
- View the source for datetime 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.