# clock/add Calendar-aware date arithmetic on an epoch-seconds value. Positional form `[clock/add time n :unit n :unit …]`; spec-map form `[clock/add time %{ :days n :months n :timezone "…" }]`. ## Syntax

[clock/add $t 1 :day]
[clock/add $t 1 :day 2 :months -1 :year]
[clock/add $t %{ :days 7 :hours 3 :timezone "UTC" }]

## Parameters - `$t` — epoch seconds (number) - Positional form: alternating count / unit-keyword pairs, applied left-to-right. A trailing spec map may carry `:timezone` (and extra units). - Spec-map form: keys are unit names (`:days`, `:months`, …), plus optional `:timezone` / `:locale`. ## Units | Unit | Category | Behavior | |------|----------|----------| | `:second` `:minute` `:hour` | Fixed-duration | Add to epoch directly. | | `:day` `:week` | Calendar (wall-clock-preserving) | Convert to local broken-down time, add N days, convert back. Preserves wall-clock time across DST. | | `:month` `:year` | Calendar (date-arithmetic) | Add to year/month; clamp day to the target month's last day (Jan 31 + 1 month = Feb 28/29). | Multiple deltas are applied in order. ## Examples

[clock/add [clock/seconds] 1 :day]

# Month-end clamping
set t [clock/scan "2024-01-31" %{ :format "%Y-%m-%d" :timezone "UTC" }]
[clock/format [clock/add $t 1 :month] "%Y-%m-%d" "UTC"]   # → "2024-02-29"

## Returns Epoch seconds (number). Invalid input returns `%Err{:message}`. ## See Also `clock/format`, `clock/scan`, `clock/seconds`