time.calendars
periods, weekdays, business days, week numbers, month grids, cron, zodiacs
Example results generated on 2026-10-08. Ones using
now,todayor randomness will differ when you run them: press Run on any example to run it in your browser, after editing it if you like.
Functions
| function | description |
|---|---|
weekday_num(d: date) | weekday as a number, Monday = 1 … Sunday = 7 |
day_of_year(d: date) | day of the year, 1-366 |
iso_week(d: date) | ISO 8601 week number (weeks start Monday) |
quarter(d: date) | quarter of the year, 1-4 |
leap_year(d: date|int) | whether the year is a leap year |
days_in_month(d: date) | number of days in the date’s month |
days_in_year(d: date) | 365 or 366 |
start_of(d: date, period: str) | start of the second/minute/hour/day/week/month/quarter/year |
end_of(d: date, period: str) | last moment of the period |
next(d: date, weekday: str) / next(cron: str, n?: int) | the next given weekday strictly after d; or the next run of a cron expression, or a list of the next n |
prev(d: date, weekday: str) | the last given weekday strictly before d |
nth_weekday(d: date, n: int, weekday: str) | nth weekday of d’s month; negative counts from the end |
add_workdays(d: date, n: int, holidays?: list|str) | move n Monday-Friday days, skipping holidays (a list of dates, or “US”/“UK”); negative goes back |
workdays(a: date, b: date, holidays?: list|str) | Monday-Friday days from a up to (not including) b, minus holidays |
holidays(year: int, country: str) | public holidays as observed (moved off weekends): “US” federal or “UK” England bank holidays |
cron(expr: str) | a cron expression (minute hour day month weekday, or @daily etc.) in plain English |
calendar(d: date) / calendar(year: int, month: int) | month grid, weeks starting Monday |
zodiac(day?: date) | the Western zodiac sign for a date (default today) |
chinese_zodiac(year: int|date) | the Chinese zodiac element and animal; by Gregorian year, so January dates before Lunar New Year come out a year late |
weekday_num
weekday_num(d: date): weekday as a number, Monday = 1 … Sunday = 7
today.weekday_num
# → 4
See also: weekday
day_of_year
day_of_year(d: date): day of the year, 1-366
date("2026-12-31").day_of_year
# → 365
See also: iso_week
iso_week
iso_week(d: date): ISO 8601 week number (weeks start Monday)
date("2026-12-31").iso_week
# → 53
See also: day_of_year, quarter
quarter
quarter(d: date): quarter of the year, 1-4
today.quarter
# → 4
See also: iso_week
leap_year
leap_year(d: date|int): whether the year is a leap year
leap_year(2028)
# → true
today.leap_year
# → false
See also: days_in_year
days_in_month
days_in_month(d: date): number of days in the date’s month
date("2028-02-10").days_in_month
# → 29
See also: days_in_year
days_in_year
days_in_year(d: date): 365 or 366
today.days_in_year
# → 365
See also: leap_year
start_of
start_of(d: date, period: str): start of the second/minute/hour/day/week/month/quarter/year
now.start_of("week")
# → 2026-10-05
now.start_of("quarter")
# → 2026-10-01
end_of
end_of(d: date, period: str): last moment of the period
now.end_of("month")
# → 2026-10-31 23:59:59 -05:00
(today.end_of("year") - now).parts
# → "85 d 31 min"
See also: start_of
next
next(d: date, weekday: str) / next(cron: str, n?: int): the next given weekday strictly after d; or the next run of a cron expression, or a list of the next n
today.next("friday")
# → 2026-10-09
now.next("mon")
# → 2026-10-12 00:29:18 -05:00
"0 9 * * mon".next
# → 2026-10-12 09:00:00 -05:00
"@monthly".next(2)
# → [2026-11-01, 2026-12-01]
See also: prev, nth_weekday, cron
prev
prev(d: date, weekday: str): the last given weekday strictly before d
today.prev("sunday")
# → 2026-10-04
See also: next
nth_weekday
nth_weekday(d: date, n: int, weekday: str): nth weekday of d’s month; negative counts from the end
date(2026, 11, 1).nth_weekday(4, "thu")
# → 2026-11-26
date(2026, 5, 1).nth_weekday(-1, "mon")
# → 2026-05-25
See also: next
add_workdays
add_workdays(d: date, n: int, holidays?: list|str): move n Monday-Friday days, skipping holidays (a list of dates, or “US”/“UK”); negative goes back
today.add_workdays(10)
# → 2026-10-22
date("2026-12-24").add_workdays(1, "US")
# → 2026-12-28
date("2026-12-24").add_workdays(1, [date("2026-12-28")])
# → 2026-12-25
See also: workdays, holidays, is_weekend
workdays
workdays(a: date, b: date, holidays?: list|str): Monday-Friday days from a up to (not including) b, minus holidays
workdays(today, date("2026-12-25"))
# → 56
workdays(date("2026-12-01"), date("2027-01-01"), "UK")
# → 21
See also: add_workdays, holidays
holidays
holidays(year: int, country: str): public holidays as observed (moved off weekends): “US” federal or “UK” England bank holidays
holidays(2026, "US")
# → [2026-01-01, 2026-01-19, 2026-02-16, 2026-05-25, 2026-06-19, 2026-07-03, 2026-09-07, 2026-10-12, 2026-11-11, 2026-11-26, 2026-12-25]
holidays(2026, "UK").len
# → 8
See also: add_workdays, workdays
cron
cron(expr: str): a cron expression (minute hour day month weekday, or @daily etc.) in plain English
cron("0 9 * * 1-5")
# → "at 09:00, on Monday through Friday"
cron("30 4 1,15 * fri")
# → "at 04:30, on days 1 and 15 of the month, or on Friday"
cron("@hourly")
# → "at minute 0 of every hour"
See also: next
calendar
calendar(d: date) / calendar(year: int, month: int): month grid, weeks starting Monday
calendar(2026, 12)
# → December 2026
# → Mo Tu We Th Fr Sa Su
# → 1 2 3 4 5 6
# → 7 8 9 10 11 12 13
# → 14 15 16 17 18 19 20
# → 21 22 23 24 25 26 27
# → 28 29 30 31
See also: date
zodiac
zodiac(day?: date): the Western zodiac sign for a date (default today)
zodiac(date("2000-01-01"))
# → "♑ Capricorn"
See also: chinese_zodiac
chinese_zodiac
chinese_zodiac(year: int|date): the Chinese zodiac element and animal; by Gregorian year, so January dates before Lunar New Year come out a year late
chinese_zodiac(2026)
# → "Fire Horse"
chinese_zodiac(1984)
# → "Wood Rat"
See also: zodiac
More examples
calendars
# Thanksgiving: 4th Thursday
date(2026, 11, 1).nth_weekday(4, "thu")
# → 2026-11-26
# Memorial Day: last Monday
date(2026, 5, 1).nth_weekday(-1, "mon")
# → 2026-05-25
# 3 business days later
date("2026-12-24").add_workdays(3)
# → 2026-12-29
# workdays in December
workdays(date("2026-12-01"), date("2026-12-31"))
# → 22
# skipping US holidays
date("2026-12-24").add_workdays(3, "US")
# → 2026-12-30
# ISO week number
today.iso_week
# → 41
# what does this cron line mean?
cron("*/15 9-17 * * mon-fri")
# → "every 15 minutes, during hours 9 through 17, on Monday through Friday"
# when does it run next?
"0 9 * * 1-5".next(3)
# → [2026-10-08 09:00:00 -05:00, 2026-10-09 09:00:00 -05:00, 2026-10-12 09:00:00 -05:00]
# your sign
[zodiac(date("1990-08-10")), chinese_zodiac(1990)]
# → ["♌ Leo", "Metal Horse"]