Date, Time & Calendar Math

Kalc includes a natural language calendar and clock engine (DateEngine), allowing you to calculate project deadlines, working day allocations, timezone differences, and travel itineraries directly on your notepad.

---

1. System Clock & Epoch Timestamps

Access system time and convert Unix timestamps:

now()                                           // Current date, time, and timezone
today()                                         // Today's date anchored at midnight
time()                                          // Current system clock time
fromunix(1710000000)                            // Mar 9, 2024 4:00 PM

---

2. Calendar Offsets & Arithmetic

Add or subtract calendar durations (days, weeks, months, years, hours, mins):

today + 2 weeks                                 // Date 14 days ahead
today + 90 days                                 // Quarter-end milestone date
now + 45 mins                                   // Meeting end time
today - 30 days                                 // Net 30 lookback
1 month in days                                 // 30.44 days

---

3. Durations Between Dates & Clock Times

Clock Time Durations

Calculate elapsed hours and minutes between two times of day:

17:30 to 20:45                                  // 3 hours 15 min
9:00am to 5:30pm                                // 8 hours 30 min
10:15 to 11:45                                  // 1 hour 30 min

Combine clock durations with hourly rates for instant freelancer billing:

shift = 9:15am to 5:45pm                        // 8 hours 30 min
rate = $125 / hr
total_due = shift * rate                        // $1,062.50

Calendar Differences

Measure elapsed days between specific dates:

days between March 1 and April 15               // 45 days
days between 12 June and July 15                // 33 days
December 25 - today in days                     // Countdown to Christmas

---

4. Working Days & Business Hours

In project planning and sprint scheduling, calendar days are misleading because weekends skew delivery estimates. Kalc natively skips Saturdays and Sundays:

Business Day Offsets

today + 15 business days                        // Skips weekends to find exact sprint end
June 15 in 10 business days                     // Target release date

Working Days in a Date Range

work days between 1 March and 1 June            // Total productive business days
work days between 1 Sept and 30 Nov             // Q4 billable days

Billable Work Hours

Calculates billable capacity based on a standard 8-hour working day:

work hours between March 12 and March 25        // 72 hours
work hours between 1 May and 31 May             // Full month working capacity
hours = work hours between Oct 1 and Dec 31
hours * $150/hr                                 // Consulting retainer estimate

---

5. World Clocks & Timezone Conversions

Coordinate international meetings across timezones without mental UTC conversions:

Current Time in Cities

time in Paris                                   // 2:18 pm
time in Tokyo                                   // 10:18 pm
time in San Francisco                           // 5:18 am

City-to-City Time Differences

Calculates the signed hour offset, automatically accounting for local Daylight Saving Time (DST):

time difference between Zurich and Tokyo        // +7 hours
time difference between London and New York     // -5 hours
time difference between JFK and LHR             // +5 hours

Clock Time Conversions (Cities & Airports)

Converts clock times across world cities and IATA airport codes (JFK, LHR, SFO, HND, SYD, CDG):

3:30pm NYC to London                            // 8:30 pm
9am JFK to SFO                                  // 6:00 am
12pm London to Paris                            // 1:00 pm
8:30pm LHR to JFK                               // 3:30 pm

---

6. Travel & Itinerary Planning

Kalc supports cumulative multi-city trip planning. Start with an anchor departure date, list sequential night stays, and use subtotal or total to calculate your final return date:

Leave August 10
Tokyo 4 nights                                  // 14 August
Kyoto 3 nights                                  // 17 August
Osaka 3 nights                                  // 20 August
subtotal                                        // 20 August (Final return date)

---

7. Stopwatch Laps & Split Times

Entering sequential timestamps in HH:mm:ss format records split lap times. Calling subtotal or total calculates the cumulative elapsed time:

00:01:30
00:02:00
subtotal                                        // 00:03:30

Leg 1: 03:45:00
Layover: 01:30:00
Leg 2: 05:20:00
total                                           // 10:35:00