daydate

Dates for deadlines and time-based rules: building dates, adding days, months and years, weekdays, ISO weeks and leap years. Import it with IMPORT daydate. Weeks start on Monday, following ISO 8601.

Most functions take either a DATE or a day number (the date's serial number, as given by Day), so `Weekday of` (Date 1 1 2024) and `Weekday of` 739250 give the same answer.

Example:

-- Daydate Example: Date calculations and temporal logic
IMPORT daydate

-- Date construction from components
DECIDE `Christmas 2024` IS Date 25 12 2024
DECIDE `New Year 2025` IS Date 1 1 2025

#EVAL `Christmas 2024`
#EVAL `New Year 2025`

-- Date construction in ISO 8601 order: year, month, day
DECIDE `Christmas 2024, year first` IS YMD 2024 12 25
#EVAL `Christmas 2024, year first`                          -- DATE OF 25, 12, 2024
#EVAL `Christmas 2024, year first` EQUALS `Christmas 2024`  -- TRUE
#ASSERT `Year month day` 2024 12 25 EQUALS YMD 2024 12 25
#ASSERT YMD 2024 2 29 EQUALS Date 29 2 2024
#ASSERT YMD 0 1 1 EQUALS Date 1 1 0  -- a whole-number year is not otherwise checked

-- Date rolls a day past the end of the month, or a month past 12, forward
#ASSERT Date 29 2 2025 EQUALS Date 1 3 2025
#ASSERT Date 7 28 2026 EQUALS Date 7 4 2028
#ASSERT Date 2025 1 15 EQUALS Date 17 7 20  -- Date takes the day first

-- YMD refuses a year that is not a whole number, and a month or a day that does not exist, and says which part is wrong
#EVAL YMD 2023 2 29
#ASSERT REFUSED YMD 2023 2 29 BECAUSE "YMD: that month has no such day in that year"
#ASSERT REFUSED YMD 2026 28 7 BECAUSE "YMD: the month is not a whole number from 1 to 12"
#ASSERT REFUSED YMD 2026 13 32 BECAUSE "YMD: the month is not a whole number from 1 to 12"
#ASSERT REFUSED YMD 2026.5 7 1 BECAUSE "YMD: the year is not a whole number"

-- Date from ISO string (returns MAYBE DATE, ignores time/timezone if present)
DECIDE `from iso date` IS Date "2025-06-15"
DECIDE `from iso datetime` IS Date "2025-06-15T10:30:00Z"
#EVAL `from iso date`       -- JUST OF (DATE OF 15, 6, 2025)
#EVAL `from iso datetime`   -- JUST OF (DATE OF 15, 6, 2025)

-- Date arithmetic
DECIDE `week later` IS `Christmas 2024` PLUS 7
#EVAL `week later`  -- January 1, 2025

DECIDE `week before` IS `Christmas 2024` MINUS 7
#EVAL `week before`  -- December 18, 2024

-- Date components
#EVAL DATE_DAY `Christmas 2024`    -- 25
#EVAL DATE_MONTH `Christmas 2024`  -- 12
#EVAL DATE_YEAR `Christmas 2024`   -- 2024

-- Weekday calculations
DECIDE `day of week` IS `Weekday of` `Christmas 2024`
#EVAL `day of week`  -- Wednesday (3)

#EVAL `Name of weekday` `Christmas 2024`  -- "Wednesday"

-- Weekend checks
#EVAL `is weekend` `Christmas 2024`   -- FALSE
#EVAL `is weekday` `Christmas 2024`   -- TRUE

DECIDE `last Saturday in 2024` IS Date 28 12 2024
#EVAL `is weekend` `last Saturday in 2024` -- TRUE

-- Week of year
#EVAL `Week of the year` `Christmas 2024`  -- 52

-- Leap year
#EVAL `is leap year` 2024  -- TRUE
#EVAL `is leap year` 2023  -- FALSE

-- Relative time phrases
DECIDE `tomorrow` IS `the day after` `Christmas 2024`
#EVAL `tomorrow`

DECIDE `next week` IS `the week after` `Christmas 2024`
#EVAL `next week`


-- Date comparison (via operator overloads)
#EVAL `Christmas 2024` < `New Year 2025`   -- TRUE
#EVAL `Christmas 2024` >= `New Year 2025`  -- FALSE

-- Readable comparisons
DECIDE `christmas is before new year` IS `Christmas 2024` `is before` `New Year 2025`
DECIDE `new year is after christmas` IS `New Year 2025` `is after` `Christmas 2024`
#EVAL `christmas is before new year`  -- TRUE
#EVAL `new year is after christmas`   -- TRUE

-- Month helpers
DECIDE `July 4th` IS July 4 2024
#EVAL `July 4th`
#EVAL `Name of month` `July 4th`  -- "July"

Constants

Constant Value
Monday to Saturday (also Mon to Sat) 1 to 6
Sunday (also Sun) 0
January to December (also Jan to Dec) 1 to 12
Days in a week 7
Months in a year 12
Days in a year 365.2425, the average over the 400-year leap cycle
Days in a month 30.436875, the average month

The month names also build dates: January 15 2024 is 15 January 2024.

Building a date

Function Gives What it does
Date day month year DATE The date from its parts: Date 25 12 2024
YMD year month day DATE The date from its parts, year first: YMD 2024 12 25
Date days DATE The date with this day number
Date text MAYBE DATE Reads an ISO date such as "2025-06-15"; any time and time zone are ignored
Date datetime DATE The date part of a DATETIME, ignoring time and time zone
Week week year DATE The Monday of that ISO week
Month month year DATE The first day of that month
Year year DATE 1 January of that year
Month date, Week date, Year date DATE The first day of the month, ISO week or year that contains date
January day year, ... DATE The date in that month: March 1 2025

When the day is past the end of the month, or the month is past 12, Date day month year rolls forward: Date 29 2 2025 is 1 March 2025, and Date 7 28 2026 is 7 April 2028. Days to date is another name for Date.

YMD year month day takes the year first, the month second and the day third, as ISO 8601 writes a date. YMD gives the date when that day exists in that month and year: YMD 2024 2 29 is 29 February 2024, the same date as Date 29 2 2024. A year that is a whole number is not otherwise checked: YMD 0 1 1 is 1 January of year 0. When the month or the day does not exist, or the year is not a whole number, it refuses to answer, with a reason that says which part is wrong (REFUSE). #EVAL YMD 2026 28 7, where the day and the month have changed places, prints:

The model refuses to answer:
  YMD: the month is not a whole number from 1 to 12

and #EVAL YMD 2023 2 29, a day that 2023 does not have, prints:

The model refuses to answer:
  YMD: that month has no such day in that year

and #EVAL YMD 2026.5 7 1, a year that is not a whole number, prints:

The model refuses to answer:
  YMD: the year is not a whole number

(Date 1 7 2026.5 stops with an internal error, "DATE_FROM_DMY expects integer year", where YMD refuses.) YMD checks the month first, then the year, then the day, and gives the reason of the first that is wrong. A wrong month gives the month's reason, even when the year or the day is wrong too, and a wrong year gives the year's reason, even when the day is wrong too. Year month day is another name for YMD.

What to know before using YMD:

  • A rule that calls YMD has no query plan, even when the date exists, as in YMD 2026 7 28. So a questionnaire built on the rule cannot ask for only the inputs it still needs; the same rule written with Date has a query plan (REFUSE: the query plan).
  • The WASM backend (jl4-mlir) does not evaluate an @export that calls YMD, with the reason "REFUSE is not supported by the WASM backend"; evaluate it with jl4-service (REFUSE: limits).
  • YMD and Year month day are names in every file that imports daydate, or a library that imports it, such as datetime. A file that also defines its own YMD or Year month day that takes three numbers and gives a date fails to check at each place it uses that name, with "There are multiple definitions for the identifier". The more places a rule uses the name, the longer the file takes to check, and each place about triples the time: in measurements, eight uses took one to two seconds, ten took eight to twenty-three seconds, and twelve took more than a minute, where the same file with its own definition renamed checked in under a second. Rename its own definition.

Reading a date

Function Gives What it does
Day date NUMBER The date's day number; Date to days is another name
Weekday of date NUMBER 1 for Monday to 6 for Saturday, 0 for Sunday
Week of the year date NUMBER The ISO week number
Month of the year date NUMBER 1 to 12
Name of month date STRING "February"
Name of weekday date STRING "Monday"
is weekend date BOOLEAN Saturday or Sunday
is weekday date BOOLEAN Monday to Friday
is leap year year (or date) BOOLEAN 366 days in the year
Days in month month year (or date) NUMBER 28 to 31
Days in year year (or date) NUMBER 365 or 366
Weeks in year year (or date) NUMBER 52 or 53 ISO weeks
Weekday of 1st day of month month year NUMBER The weekday of the 1st of the month
Weekday of 1st day of year year NUMBER The weekday of 1 January
Months since year start to days month year NUMBER The days in the year before that month begins
Years to days year NUMBER The day number of 1 January of that year

To read the day, month or year of a date as a number, use the built-ins DATE_DAY, DATE_MONTH and DATE_YEAR, or date-compat.

Moving a date

Function Gives What it does
date PLUS n, date + n DATE n days later
date MINUS n DATE n days earlier
add months date months DATE The same day, whole months later (or earlier for a negative number)
add years date years DATE The same day, whole years later (or earlier)
the day after date DATE The next day
the day before date DATE The previous day
the week after date DATE The Monday of the following week
the week before date DATE The Monday of the previous week
the month after date DATE The 1st of the following month
the month before date DATE The 1st of the previous month
the year after date DATE 1 January of the following year
the year before date DATE 1 January of the previous year
on day n date DATE The nth day counting date as day 1: `on day` 15 (Month 2 2024) is 15 February 2024

add months and add years round a fractional number down. When the day does not exist in the month they land in, they use that month's last day, as Excel's EDATE does: 31 January plus one month is 29 February in 2024 and 28 February in 2023, and 29 February 2024 plus one year is 28 February 2025. Use add years for an anniversary, since Date 29 2 2025 rolls forward to 1 March.

Comparing dates

  • =, <, <=, >, >= and their word forms (EQUALS, LESS THAN, AT MOST, GREATER THAN, AT LEAST) compare two dates.
  • date1 MINUS date2 is the number of days between them.
  • d1 `is before` d2 and d1 `is after` d2 read as sentences. Put each date in parentheses: (Date 10 1 2024) `is before` (Date 11 1 2024).
  • `the earlier of` d1 d2 and `the later of` d1 d2 pick one of two dates.

date-compat

date-compat is a separate library for files written before DATE became a built-in type. Import it with IMPORT `date-compat` (the backticks are needed because of the hyphen). IMPORT daydate (and so IMPORT datetime) also gives you its functions.

Function Gives What it does
DATE day month year DATE The older spelling of Date day month year: DATE 15 3 1990
DATE days DATE The date with this day number
Day of date (or day of) NUMBER The day of the month, like DATE_DAY
Month of date (or month of) NUMBER The month, like DATE_MONTH
Year of date (or year of) NUMBER The year, like DATE_YEAR

New files should use Date or YMD from daydate, and DATE_DAY, DATE_MONTH and DATE_YEAR.