time.calendars

periods, weekdays, business days, week numbers, month grids, cron, zodiacs

Example results generated on 2026-10-08. Ones using now, today or 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

day_of_year

day_of_year(d: date): day of the year, 1-366

date("2026-12-31").day_of_year
# → 365

iso_week

iso_week(d: date): ISO 8601 week number (weeks start Monday)

date("2026-12-31").iso_week
# → 53

quarter

quarter(d: date): quarter of the year, 1-4

today.quarter
# → 4

leap_year

leap_year(d: date|int): whether the year is a leap year

leap_year(2028)
# → true
today.leap_year
# → false

days_in_month

days_in_month(d: date): number of days in the date’s month

date("2028-02-10").days_in_month
# → 29

days_in_year

days_in_year(d: date): 365 or 366

today.days_in_year
# → 365

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
# → "84 d 17 h 1 min"

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

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

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

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"

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

zodiac

zodiac(day?: date): the Western zodiac sign for a date (default today)

zodiac(date("2000-01-01"))
# → "♑ Capricorn"

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"

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"]

Keyboard shortcuts

zil reference