datetime — Create host datetime arrays from text, date vectors, or calendar components.
datetime constructs host-side datetime objects from date/time text, numeric m-by-3 or m-by-6 date vectors, or calendar components. An explicit ConvertFrom='datenum' form reads serial date numbers. datetime() reads the current local date and time.
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
textOrArray- Type
Any- Required
- Yes
- Description
- Date/time string, string array, character array, or cell array of character vectors.
dateVectors- Type
NumericArray- Required
- Yes
- Description
- m-by-3 or m-by-6 numeric date-vector matrix.
year- Type
NumericArray- Required
- Yes
- Description
- Calendar year.
month- Type
NumericArray- Required
- Yes
- Description
- Calendar month.
day- Type
NumericArray- Required
- Yes
- Description
- Calendar day.
hour- Type
NumericArray- Required
- Yes
- Description
- Hour component.
minute- Type
NumericArray- Required
- Yes
- Description
- Minute component.
second- Type
NumericArray- Required
- Yes
- Description
- Second component; may be fractional.
millisecond- Type
NumericArray- Required
- Yes
- Description
- Millisecond component.
serialDateNumbers- Type
NumericArray- Required
- Yes
- Description
- Serial date numbers to convert.
ConvertFrom- Type
StringScalar- Required
- Yes
- Description
- Conversion option name.
dateType- Type
StringScalar- Required
- Yes
- Description
- Currently only 'datenum' is implemented.
args- Type
Any- Required
- Variadic
- Description
- Constructor arguments followed by Format, InputFormat, or ConvertFrom pairs.
Returns
t- Type
Any- Description
- Host datetime object array.
Errors
RunMat:datetime:InvalidArgument- When
- Arguments or option grammar do not match supported datetime forms.
- Message
datetime: invalid argument
RunMat:datetime:InvalidInput- When
- Input values cannot be parsed, converted, or broadcast to a valid datetime result.
- Message
datetime: invalid input
RunMat:datetime:Internal- When
- Internal datetime state is invalid.
- Message
datetime: internal operation failed
Inputs and shapes
datetime(Y,M,D) and datetime(Y,M,D,H,MI,S) accept scalar or equally sized arrays of real numeric components. Scalars expand to the non-scalar component shape. A seventh millisecond component is supported; when it is supplied, the second component must be integral. The constructor accepts double, single, and all eight fixed-width integer classes. Date-vector matrices have three or six columns and return one datetime per row.
Calendar components carry into adjacent units. NaN components produce NaT, and infinite components retain an infinite serial marker in the current host representation. Integer values are checked in exact storage before conversion to RunMat's floating serial-date representation.
String scalars, string arrays, character arrays, and cell arrays of character vectors accept common ISO-like date/time text, dd-MMM-yyyy, and the relative words now, today, tomorrow, and yesterday. Character-array rows yield a datetime column; cell arrays retain their shape. Relative words read the local clock.
Options and compatibility
Format changes the object's display text, not its stored date. InputFormat selects a parsing format for text input. ConvertFrom='datenum' interprets numeric input as serial date numbers. Other conversion epochs, Locale, PivotYear, TimeZone, Epoch, and TicksPerSecond are not implemented; unsupported forms report an error rather than silently approximating their semantics.
A one-argument numeric input outside the m-by-3 and m-by-6 date-vector forms is treated as a raw serial date only in RunMat mode. Four- and five-component calls, logical numeric inputs, and resident numeric inputs are also RunMat-only extensions. MATLAB mode rejects these extension forms, including resident input before provider access.
Representation and execution
A datetime is a host object backed by a serial-date tensor and a Format property. There is no resident datetime class or GPU calendar kernel. RunMat mode may gather admitted resident numeric input through its provider owner; the result is still a host object. Construction is a fusion boundary and may suspend for a gather or throw for invalid input.
The no-argument and relative-text forms read the local clock and are nondeterministic. The other supported forms have no filesystem, network, callback, workspace, randomness, or user-interface effect. Native and WebAssembly runtimes use the same host representation; shared injectable clock, timezone, and locale services are not implemented.
Related operations
Assign t.Format to change rendering without changing the stored date. Linear indexing preserves datetime values. Component extractors such as year, month, day, and hour return numeric values. Datetime comparison and day arithmetic are supported; subtracting two datetimes returns a numeric day interval. Adding or subtracting a calendarDuration applies month-aware arithmetic, including end-of-month clamping.
datenum, datevec, datestr, weekday, eomday, etime, and isbetween cover common legacy serial-date workflows. Business-day functions provide market-calendar calculations; their exact limitations are documented with those functions.
Examples
Construct a scalar from calendar components
t = datetime(2024,4,9,13,30,0); disp(t);Expected output:
09-Apr-2024 13:30:00Parse two text dates
t = datetime(["2024-04-09 13:30:00"; "2024-04-10 08:15:00"]); disp(t);Expected output:
09-Apr-2024 13:30:00
10-Apr-2024 08:15:00Parse a cell array of character vectors
dates = {'2024-04-09';'2024-04-10'}; t = datetime(dates,'InputFormat','yyyy-MM-dd'); disp(t);Expected output:
09-Apr-2024
10-Apr-2024Extract calendar and clock components
t = datetime(2024,4,9,13,30,5); y = year(t); m = month(t); d = day(t); h = hour(t); fprintf('y = %.0f\nm = %.0f\nd = %.0f\nh = %.0f\n',y,m,d,h);Expected output:
y = 2024
m = 4
d = 9
h = 13Convert explicit serial date numbers
serials = [739351; 739352]; t = datetime(serials,'ConvertFrom','datenum'); disp(t);Expected output:
09-Apr-2024 00:00:00
10-Apr-2024 00:00:00Change display format without changing the date
t = datetime(2024,4,9,13,30,0); before = datenum(t); t.Format = 'yyyy-MM-dd HH:mm:ss'; disp(t);Expected output:
2024-04-09 13:30:00Add a calendar month at month end
t = datetime(2024,1,31,'Format','yyyy-MM-dd'); shifted = t + calmonths(1); disp(shifted);Expected output:
2024-02-29Shift a date and subtract two datetimes
t0 = datetime(2024,4,9); t1 = t0 + 7; delta = t1 - t0; fprintf('delta = %.0f\n',delta);Expected output:
delta = 7Use serial-date conversion helpers
n = datenum(2024,4,9); v = datevec(n); s = datestr(n,'yyyy-mm-dd'); disp(s);Expected output:
2024-04-09Use RunMat's implicit serial-date form
serial = datenum(2024,4,9); t = datetime(serial);Using 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 Format change?⌄
Only display text. The serial date is unchanged, so comparison and arithmetic refer to the same date and time.
Can I index a datetime array?⌄
Yes. Linear () indexing returns datetime values. Component functions return numeric values.
Does datetime run on the GPU?⌄
No. MATLAB mode rejects resident numeric constructor input before provider access. RunMat mode can gather it and returns a host datetime object.
How is subtraction interpreted?⌄
Subtracting another datetime returns a numeric day interval; subtracting a numeric day count shifts the datetime.
Related Datetime functions
Calendar Duration
caldays · calendarDuration · calendarDuration.eq · calendarDuration.minus · calendarDuration.ne · calendarDuration.plus · calmonths · calquarters · calweeks · calyears · datetick · iscalendarduration · isdatetime
Datetime
Operators
datetime.eq · datetime.ge · datetime.gt · datetime.le · datetime.lt · datetime.minus · datetime.ne · datetime.plus
Indexing
Duration
days · duration · 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
Source you can read
Every RunMat function's source is public. 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 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.