datetime.plus — Shift datetime values by fixed or calendar-relative amounts.
The datetime class method datetime.plus applies the existing typed host serial-date operation. It retains operation-specific RHS dispatch, scalar-or-exact geometry and native result-class behavior rather than assuming generic numeric comparison or duration arithmetic.
Syntax
out = datetime.plus(lhs, rhs)Inputs
lhs- Type
Any- Required
- Yes
- Default
- —
- Description
- Datetime value receiver, with host serial-date storage.
rhs- Type
Any- Required
- Yes
- Default
- —
- Description
- Operation-specific datetime, duration, calendarDuration or host real numeric/logical operand.
Returns
out- Type
Any- Description
- Host double 0/1 comparison, datetime arithmetic result, or double day difference for datetime subtraction.
Errors
RunMat:datetime.plus:InvalidArgument- When
- The method input count is not exactly two.
- Message
datetime.plus: expected datetime receiver and RHS
RunMat:datetime:InvalidInput- When
- Receiver storage or the operation-specific RHS class is invalid, shapes differ without scalar expansion, or calendar/integer range validation fails.
- Message
datetime: invalid operator input
RunMat:datetime.plus:TooManyOutputs- When
- More than one output is requested.
- Message
datetime.plus: too many output arguments
Actual result and operand classes
The left receiver must be a datetime value object. Comparisons accept another datetime or host real numeric/logical serial day values. They currently publish double 0/1, not logical arrays. Text comparisons, duration/calendarDuration comparison operands and handle-object wrappers are not admitted by these methods.
Addition accepts duration, calendarDuration or host real numeric/logical day counts and returns datetime. It does not accept datetime on the right. Subtracting datetime returns double elapsed days, not a duration object; subtracting duration, calendarDuration or numeric/logical day counts returns datetime. Arithmetic preserves the left Format property and constructs results through the actual selected Runtime context.
Native single and integer numeric operands enter binary64 host serial arithmetic. Native integer RHS values are checked exactly against [-1000000000,1000000000] before conversion. Logical RHS values use the declared datetime logical-input extension; compatibility mode rejects that extension. The existing raw numeric method forms are RunMat behavior and are not gated by the constructor-only implicit-datenum extension.
Geometry and comparisons
A one-element operand expands to the other operand. Otherwise full non-scalar shapes must match exactly, including empty axes and low-rank storage. General dimension-wise implicit expansion is not implemented here. A one-element numeric comparison or datetime difference publishes a scalar double; empty results retain their complete array geometry.
Finite equality retains the existing absolute tolerance of 1e-12 serial days. Inequality is the complement of that equality relation. Missing/NaN serials are unequal to everything including themselves, while equal-sign infinities compare equal. Ordering uses the stored binary64 ordering and is false when either operand is NaN.
Calendar-relative shifts apply integral month offsets with month-end clamping, then day offsets. Calendar month/day range validation and civil calendar limits remain those of the existing host calendar owner. Time-zone/time-standard and full MATLAB NaT construction/display parity are not established by this method migration.
Execution boundary and remaining frontiers
These are MethodOnly entries reached by the existing typed datetime class declaration and ordinary operator syntax, not independent command-style functions. The actual default binding retains BuiltinArguments and selected context, checks output demand before work and admits the existing UnboundedCalendarWork owner before legacy temporary arrays or object assembly.
All results are host values and the operation is a fusion boundary. Resident arguments are rejected without a provider lookup, download, gather, kernel, input retirement or replay. No new accelerator, distributed or native integer provider coverage is claimed.
The current synchronous host kernels remain Incomplete: complete finite scratch/output ownership and bounded browser cooperation are not implemented. Managed calls fail closed. NativeAndWasm is portable source/link eligibility, not a claim that fresh browser or AOT qualification has run.
Examples
Shift datetime values by fixed or calendar-relative amounts.
a = datetime(2024,1,31); b = a + calmonths(1); c = a + days(1);Check the actual result class and geometry
a = datetime(2024,1,1); b = a + int32([1 2]);Using datetime.plus with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how datetime.plus changes the result.
Run a small datetime.plus example, explain the result, then change one input and compare the output.
FAQ
Do datetime comparisons return logical in this implementation?⌄
No. These methods currently publish double 0/1. The canonical result facts and example assertions intentionally retain that implementation boundary.
Does subtracting two dates construct duration?⌄
No. This Runtime path currently returns a double day difference. Subtracting a duration or calendarDuration instead returns a shifted datetime.
Related Datetime functions
Operators
datetime.eq · datetime.ge · datetime.gt · datetime.le · datetime.lt · datetime.minus · datetime.ne
Calendar Duration
caldays · calendarDuration · calendarDuration.eq · calendarDuration.minus · calendarDuration.ne · calendarDuration.plus · calmonths · calquarters · calweeks · calyears · datetick · iscalendarduration · isdatetime
Datetime
Construction
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.plus is executed, line by line, in Rust.
- View the source for datetime.plus 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.