datetime — Create host datetime arrays from date vectors, text, calendar components, or explicit serial-date conversions.
datetime constructs host-side datetime objects from m-by-3 or m-by-6 date vectors, text, and the documented 3-, 6-, or 7-component forms. All eight integer classes are read from authoritative storage before RunMat crosses into its current floating serial-date representation. ConvertFrom='datenum' is implemented; other documented conversion epochs, time zones, locale and pivot-year options, and general nanosecond fidelity remain explicit gaps.
Syntax
t = datetime()
t = datetime(textOrArray)
t = datetime(dateVectors)
t = datetime(year, month, day)
t = datetime(year, month, day, hour, minute, second)
t = datetime(year, month, day, hour, minute, second, millisecond)All supported datetime forms
t = datetime()
t = datetime(textOrArray)
t = datetime(dateVectors)
t = datetime(year, month, day)
t = datetime(year, month, day, hour, minute, second)
t = datetime(year, month, day, hour, minute, second, millisecond)
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. |
dateVectors | NumericArray | Yes | — | An m-by-3 or m-by-6 numeric date-vector matrix. |
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 | — | Datetime constructor arguments. |
args | Any | Variadic | — | Numeric serial input with ConvertFrom option. |
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(dateVectors)accepts m-by-3 and m-by-6 numeric matrices.datetime(Y, M, D),datetime(Y, M, D, H, MN, S), anddatetime(Y, M, D, H, MN, S, MS)accept single, double, and all eight integer classes; scalar inputs expand to matching non-scalar component arrays.- Calendar components normalize by carrying into adjacent units. NaN components produce NaT and infinite components retain the corresponding infinite serial marker within the current host representation.
datetime(text)accepts string scalars, string arrays, and character vectors. Supported text includes common ISO-like forms,dd-MMM-yyyy,now,today,tomorrow, andyesterday.datetime(serials, 'ConvertFrom', 'datenum')interprets numeric values as MATLAB serial date numbers.- A one-argument numeric value that is not an m-by-3 or m-by-6 date-vector matrix is interpreted as a raw serial date only when RunMat compatibility extensions are enabled. MATLAB-compatible mode requires the explicit
ConvertFromform. - Four- and five-component forms, logical numeric inputs, and gathering resident numeric arrays are compatibility-gated RunMat extensions. The resident gate is checked before provider access and the result is always a host datetime object.
- Only
Format,InputFormat, andConvertFrom='datenum'are currently implemented. Other documentedConvertFromvalues and theLocale,PivotYear,TimeZone,Epoch, andTicksPerSecondoptions report unsupported-input errors rather than silently approximating semantics. - 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. now,today, andclockexpose current local time in MATLAB-compatible serial, datetime, and date-vector forms.datenum,datevec,datestr,weekday,eomday,etime, andisbetweencover common legacy serial-date conversion, formatting, query, and interval operations.datetime + calendarDurationanddatetime - calendarDurationapply month-aware calendar arithmetic with end-of-month clamping.isbusday,holidays,busdays,days252bus,daysdif,fbusdate, andlbusdateprovide weekday plus market-holiday business-calendar compatibility for standard scripts. Custom weekend definitions and all Financial Toolbox option forms are not yet implemented.
Does RunMat run datetime on the GPU?
datetime does not allocate GPU objects or invoke provider kernels. MATLAB-compatible mode rejects resident inputs before lookup; RunMat extension mode gathers before building the host object.
GPU memory and residency
No. RunMat represents datetime values as host-side objects with an internal serial-date tensor and a Format property. Resident numeric constructor input is compatibility-gated before provider access, and an enabled extension gathers to a CPU result.
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 serial-date conversion helpers
n = datenum(2024, 4, 9);
v = datevec(n);
s = datestr(n, 'yyyy-MM-dd')Expected output:
s =
2024-04-09Adding a calendar month clamps at month end
t = datetime(2024, 1, 31, 'Format', 'yyyy-MM-dd');
t + calmonths(1)Expected output:
ans =
2024-02-29Using 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 public resident datetime type is implemented. MATLAB-compatible mode rejects resident numeric constructor inputs before provider access; RunMat extension mode may gather them and still returns a host-side datetime object.
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.