---
epic: 4
story: 4.1
title: "Date Math"
status: draft
---

## Epic 4 — Date, Time & Time Zones
**Goal:** Full date/time math, business day calculations, and timezone awareness.

### Story 4.1: Date Math

As a CalcPad user,
I want to perform arithmetic on dates including addition, subtraction, and duration between dates,
So that I can quickly compute deadlines, durations, and future/past dates.

**Acceptance Criteria:**

**Given** the expression `today + 3 weeks 2 days`
**When** the engine evaluates it
**Then** it returns a `DateTime` result representing the date 23 days from the current date
**And** the result is formatted in the user's preferred date format

**Given** the expression `March 12 to July 30`
**When** the engine evaluates it
**Then** it returns a `TimeDelta` representing the duration between the two dates
**And** the result shows days (and optionally months/weeks) e.g., "140 days" or "4 months 18 days"

**Given** the expression `days until Christmas`
**When** the engine evaluates it on a date before December 25 of the current year
**Then** it returns the number of days until December 25 of the current year

**Given** the expression `days until Christmas`
**When** the engine evaluates it on December 26 or later
**Then** it returns the number of days until December 25 of the next year

**Given** the expression `January 15, 2025 - 30 days`
**When** the engine evaluates it
**Then** the result is `December 16, 2024`

**Given** the expression `today - March 1`
**When** the engine evaluates it
**Then** it returns the number of days between March 1 of the current year and today

**Given** a date expression with an ambiguous format such as `3/4/2025`
**When** the engine evaluates it
**Then** it uses the user's configured date format preference (US: month/day, EU: day/month)
**And** the default is US format (MM/DD/YYYY) unless configured otherwise