Date

Standard library struct · Written Date(2026, 9, 25)

A Date is a day on the calendar, with no time of day and no time zone: a birthday, a due date, a holiday. Use one when the question is “which day?”, and a DateTime or an Instant when it is also “what time?”.

const launch = Date(2026, 9, 25)
print(launch)
print("#{launch.weekday}, #{launch.month_name} #{launch.day}, #{launch.year}")
print(launch.add(months: 1))

2026-09-25
Friday, September 25, 2026
2026-10-25

A Date uses the Gregorian calendar, extended back before 1582 as the international standard does, for the years 1 through 9999. It is a value: two dates for the same day are equal, an earlier date is less than a later one, and a date can be a dictionary key.

A date prints as 2026-09-25, year first, which reads the same in every country and sorts correctly as text. For another layout, put the parts into text yourself, as above.

At a glance

Making one
`Date(year, month, day)`	A date from its parts
`Date.today(zone)`	Today’s date
`Date.parse(text)`, `Date.parse_maybe(text)`	A date read from `2026-09-25`

Parts
`year`, `month`, `day`	The three numbers
`weekday`	The day of the week, as a `Weekday`
`month_name`	The month’s name, such as `"September"`
`day_of_year`	1 for 1 January, up to 365 or 366
`days_in_month`	28, 29, 30, or 31
`leap_year?()`	Whether the year has a 29 February

Calendar arithmetic
`add(years:, months:, weeks:, days:)`	A later date
`subtract(years:, months:, weeks:, days:)`	An earlier date
`days_until(other)`	Days from this date to another
`months_until(other)`	Whole months to another date
`years_until(other)`	Whole years to another date

Combining
`at(time)`	This date at a time of day, as a `DateTime`

Making one

Date(year: Int, month: Int, day: Int): Date

A date from its parts. Months are numbered from 1, so Date(2026, 9, 25) is 25 September 2026.

try {
    print(Date(2026, 2, 30))
}
catch error: DateTimeError {
    print(error.message)
}

day 30 is not between 1 and 28: February 2026 has 28 days

Raises a DateTimeError for a year outside 1 to 9999, a month outside 1 to 12, or a day the month doesn’t have.

Date.today(zone: TimeZone = TimeZone.local): Date

Today’s date, in zone, which is the computer’s own zone unless you say otherwise. The date changes at midnight where you are, so two zones can disagree about what today is.

const today = Date.today()
print(today.year >= 2026)

true

Date.parse(text: String): Date

Reads a date written as YYYY-MM-DD, ignoring spaces around it. That is the form a Date prints in, so reading a printed date gives the same date back.

print(Date.parse("2026-09-25").weekday)

Friday

Raises a DateTimeError when the text is in any other layout, saying which one was expected, or names a day that doesn’t exist.

Date.parse_maybe(text: String): Date?

Like parse, but gives nothing instead of raising an error. It suits text a person typed, where a mistake is expected:

const typed = "25/09/2026"
print(Date.parse_maybe(typed).or(Date(2026, 1, 1)))

2026-01-01

Parts

year: Int

The parts of the date as whole numbers: year, month (1 to 12), and day (1 to 31). Each is read without parentheses, and cannot be assigned. To get a different date, make a new one.

const day = Date(2026, 9, 25)
print(day.year, day.month, day.day)

2026 9 25

weekday: Weekday

The day of the week, as a Weekday.

print(Date(1969, 7, 20).weekday)

Sunday

month_name: String

The month’s English name, for building text.

print(Date(2026, 9, 25).month_name)

September

day_of_year: Int

1 for 1 January, counting up to 365, or 366 in a leap year.

print(Date(2026, 9, 25).day_of_year)

days_in_month: Int

How many days the date’s month has: 28, 29, 30, or 31.

print(Date(2026, 2, 1).days_in_month)
print(Date(2028, 2, 1).days_in_month)

28
29

leap_year?(): Bool

Whether the date’s year has a 29 February: every fourth year, except century years that aren’t divisible by 400. The year 2000 was a leap year; 1900 was not.

print(Date(2000, 1, 1).leap_year?())
print(Date(1900, 1, 1).leap_year?())

true
false

Calendar arithmetic

A step on the calendar depends on where it starts: a month from 31 January isn’t the same number of days as a month from 1 March. So dates have methods with named units, rather than + and -. For exact lengths of time, use a Duration with an Instant.

add(years: Int = 0, months: Int = 0, weeks: Int = 0, days: Int = 0): Date

A later date. A negative amount goes back. Every amount must be named, because add(1) would silently mean one year; Emerald refuses it and lists the units.

const start = Date(2026, 9, 25)
print(start.add(weeks: 2, days: 3))
print(start.add(years: 1, months: 1))

2026-10-12
2027-10-25

Years and months are moved first. If the new month doesn’t have that day, the date becomes the month’s last day, so a month after 31 January is the end of February, and a year after 29 February is 28 February. Weeks and days then count calendar days.

print(Date(2026, 1, 31).add(months: 1))
print(Date(2024, 2, 29).add(years: 1))

2026-02-28
2025-02-28

Raises a DateTimeError when the result falls outside the years 1 to 9999.

subtract(years: Int = 0, months: Int = 0, weeks: Int = 0, days: Int = 0): Date

An earlier date: add with every amount made negative.

print(Date(2026, 9, 25).subtract(months: 9))

2025-12-25

days_until(other: Date): Int

The number of days from this date to other, negative when other is earlier.

const today = Date(2026, 9, 25)
const holiday = Date(2026, 12, 25)
print(today.days_until(holiday))
print(holiday.days_until(today))

91
-91

months_until(other: Date): Int

Whole months from this date to other: the most months that add(months:) can move this date without going past it.

print(Date(2026, 1, 31).months_until(Date(2026, 2, 28)))

years_until(other: Date): Int

Whole years from this date to other, so born.years_until(Date.today()) is an age. Someone born on 29 February has their birthday on 28 February in other years.

const born = Date(1990, 6, 15)
print(born.years_until(Date(2026, 6, 14)))
print(born.years_until(Date(2026, 6, 15)))

35
36

Combining

at(time: Time): DateTime

This date at a time of day, as a DateTime.

print(Date(2026, 9, 25).at(Time(9)))

2026-09-25T09:00:00