dateshift — Shift datetime values to calendar boundaries or weekday occurrences.
dateshift implements the public start, end, and day-of-week forms with singular calendar units and optional current, next, previous, nearest, or integer occurrence rules. Week calculations begin on Sunday. Weekday indices and integer rules are read from authoritative integer storage before calendar evaluation.
Syntax
t2 = dateshift(t, boundary, unit)
t2 = dateshift(t, boundary, unit, rule)
t2 = dateshift(t, "dayofweek", weekday)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
t | Any | Yes | — | Datetime input. |
boundary | StringScalar | Yes | — | Shift form: 'start', 'end', or 'dayofweek'. |
unit | StringScalar | Yes | — | Calendar/time unit. |
rule | Any | No | — | Optional current/next/previous/nearest or integer occurrence rule. |
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 dateshift works
dateshift(t, 'start', unit)anddateshift(t, 'end', unit)default to the current unit. Supported singular units areyear,quarter,month,week,day,hour,minute, andsecond.- The end of a year, quarter, month, or week is midnight at the beginning of its last day. The end of a day, hour, minute, or second is exactly the start of the next unit.
dateshift(t, 'dayofweek', dow)accepts weekday names or numeric indices from 1 for Sunday through 7 for Saturday.weekdayandweekendselect the corresponding day groups.- Rules can be
current,next,previous,nearest, or integer scalar/arrays. Datetime, weekday, and rule arrays must have matching sizes or be scalar; scalar expansion preserves the non-scalar input shape. - Plural unit aliases,
nearestas a boundary token, and a custom week-start argument are rejected because they are not part of this public contract. - There is no resident datetime output. Resident arguments are accepted only through the declared RunMat extension and are gathered to a host result.
Does RunMat run dateshift on the GPU?
No GPU kernel is dispatched. MATLAB-compatible mode rejects resident arguments before provider access; RunMat extension mode gathers them and returns a host object.
GPU memory and residency
No. Inputs and outputs are host datetime objects. A compatibility-gated resident input is gathered before calendar evaluation.
Examples
Shift to the Sunday at the start of the current week
dateshift(datetime(2024, 3, 14), 'start', 'week')Expected output:
ans =
10-Mar-2024Shift to the next Monday occurrence
dateshift(datetime(2024, 3, 14), 'dayofweek', 'Monday')Expected output:
ans =
18-Mar-2024Shift to the end of the current month
dateshift(datetime(2024, 2, 10), 'end', 'month')Expected output:
ans =
29-Feb-2024Using dateshift with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how dateshift changes the result.
Run a small dateshift example, explain the result, then change one input and compare the output.
FAQ
When does a week begin?⌄
Sunday, matching the compatibility contract used by MATLAB calendar weeks.
Does end of month mean the last millisecond?⌄
No. For month, quarter, year, and week, it is midnight at the beginning of the final calendar day.
Related Datetime functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how dateshift is executed, line by line, in Rust.
- View the source for dateshift 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.