Add to date

Description

Pure function moving a date/time by a number of calendar days, weeks, months or years (negative goes backwards). Works on the calendar in the date's own time zone/offset and keeps the time of day, unlike Add duration, which adds an exact length of time (1 DAY = 24 hours). Months and years clamp to the end of the target month: Jan 31 + 1 MONTHS is Feb 28 (or 29 in a leap year).

When to use

Use Add to date when you mean a calendar step: the same time tomorrow, the same day next month, one year ago. Add duration adds an exact length of time, so one DAY is always 24 hours; across a daylight-saving change that lands an hour off the wall clock, while Add to date lands on the same local time. Months and years never overflow into the following month: January 31 plus one month is February 28 (29 in a leap year), and February 29 plus one year is February 28. Use Add duration for hours, minutes and seconds.

Pins

Input pins

Pin	Type	Default	Notes
Value	datetime	1970-01-01T00:00:00Z	The base date/time to move. The calendar is read in this value's own time zone or offset, and the result keeps it.
Amount	integer	0	How many units to move by. Negative goes backwards in time.
Unit	Calendar unit	Days	The calendar unit of the amount: Days, Weeks, Months, or Years.

Output pins

Pin	Type	Notes
Result	datetime	The moved date/time, with the same time of day and offset as the input.

Example

Move a date that falls on a weekend to the following Monday, and leave a weekday as it is. Wire the date into the Value input of Break date, and its Weekday number output (1 = Monday … 7 = Sunday) into Greater than with 5. Wire that into the Condition of Select boolean: the true branch is Subtract, 8 minus Weekday number (2 for a Saturday, 1 for a Sunday), and the false branch is 0. Wire the result into the Amount input of Add to date, with Unit Days and the same date in Value. Every node is pure, so this fits in a function that takes a date and returns the adjusted one.