Docs / Standard Library / Calendar

Calendar

The Calendar module provides functions for calendar-related operations such as determining days in a month, checking for leap years, and finding period boundaries (start/end of week, month, year, etc.).

Date Information

Calendar.days-in-month
Int -> Int -> Int
Returns the number of days in a month. Takes year and month (1-12). 
println (Calendar.days-in-month 2024 2)
# => 29 (leap year)

println (Calendar.days-in-month 2023 2)
# => 28
Calendar.days-in-year
Int -> Int
Returns the number of days in a year (365 or 366). 
println (Calendar.days-in-year 2024)
# => 366

println (Calendar.days-in-year 2023)
# => 365
Calendar.day-of-year
Int -> Int
Returns the day of year (1-366) for a timestamp. 
ts = Time.parse "2024-03-01" "%Y-%m-%d"
println (Calendar.day-of-year ts)
# => 61
Calendar.week-of-year
Int -> Int
Returns the ISO week number (1-53) for a timestamp. 
ts = Time.parse "2024-01-15" "%Y-%m-%d"
println (Calendar.week-of-year ts)
# => 3
Calendar.quarter
Int -> Int
Returns the quarter (1-4) for a timestamp. 
ts = Time.parse "2024-05-15" "%Y-%m-%d"
println (Calendar.quarter ts)
# => 2

Predicates

Calendar.leap-year?
Int -> Bool
Returns true if the year is a leap year. 
println (Calendar.leap-year? 2024)
# => true

println (Calendar.leap-year? 2023)
# => false
Calendar.weekend?
Int -> Bool
Returns true if the timestamp falls on a weekend (Saturday or Sunday). 
ts = Time.parse "2024-12-21" "%Y-%m-%d"  # Saturday
println (Calendar.weekend? ts)
# => true
Calendar.weekday?
Int -> Bool
Returns true if the timestamp falls on a weekday (Monday through Friday). 
ts = Time.parse "2024-12-19" "%Y-%m-%d"  # Thursday
println (Calendar.weekday? ts)
# => true

Period Boundaries

These functions return timestamps for the start or end of various calendar periods relative to a given timestamp.

Calendar.start-of-day
Int -> Int
Returns the timestamp for the start of the day (00:00:00.000). 
now = Time.now
start = Calendar.start-of-day now
println (Time.format start "%Y-%m-%d %H:%M:%S")
# => "2024-12-19 00:00:00"
Calendar.end-of-day
Int -> Int
Returns the timestamp for the end of the day (23:59:59.999).
Calendar.start-of-week
Int -> Int
Returns the timestamp for the start of the week (Monday 00:00:00). 
ts = Time.parse "2024-12-19" "%Y-%m-%d"  # Thursday
start = Calendar.start-of-week ts
println (Time.format start "%Y-%m-%d")
# => "2024-12-16" (Monday)
Calendar.end-of-week
Int -> Int
Returns the timestamp for the end of the week (Sunday 23:59:59.999).
Calendar.start-of-month
Int -> Int
Returns the timestamp for the start of the month. 
ts = Time.parse "2024-12-19" "%Y-%m-%d"
start = Calendar.start-of-month ts
println (Time.format start "%Y-%m-%d")
# => "2024-12-01"
Calendar.end-of-month
Int -> Int
Returns the timestamp for the end of the month. 
ts = Time.parse "2024-02-15" "%Y-%m-%d"
end = Calendar.end-of-month ts
println (Time.format end "%Y-%m-%d")
# => "2024-02-29" (leap year)
Calendar.start-of-quarter
Int -> Int
Returns the timestamp for the start of the quarter. 
ts = Time.parse "2024-05-15" "%Y-%m-%d"  # Q2
start = Calendar.start-of-quarter ts
println (Time.format start "%Y-%m-%d")
# => "2024-04-01"
Calendar.end-of-quarter
Int -> Int
Returns the timestamp for the end of the quarter.
Calendar.start-of-year
Int -> Int
Returns the timestamp for the start of the year (January 1st 00:00:00). 
ts = Time.parse "2024-06-15" "%Y-%m-%d"
start = Calendar.start-of-year ts
println (Time.format start "%Y-%m-%d")
# => "2024-01-01"
Calendar.end-of-year
Int -> Int
Returns the timestamp for the end of the year (December 31st 23:59:59.999).