dates

A calendar period: the parts of an ISO 8601 duration. Years and months have no fixed length, so they are applied with Time.add_months (clamping the day to the month's end); weeks and days are 7 and 1 days of 24 hours; the rest are exact. Parts may be negative.

A half-open span of time, from start (included) to end (excluded), with start <= end.

An ISO 8601 week date: the ISO week-numbering year, the week (1 to 53) and the weekday (1 is Monday).

The unit of a step in a date range, or of add_units.

Which days are business days: the weekdays of the weekend (1 is Monday, 7 Sunday) and a list of holidays (only their UTC dates count).

Whether y is a leap year in the proleptic Gregorian calendar (year 0 is a leap year).

The number of days in month m (1 to 12) of year y.

The number of days in year y: 365 or 366.

The quarter of the year t is in (UTC): 1 for January to March, up to 4.

The English name of weekday d (1 is Monday): "Monday" to "Sunday".

The three-letter English abbreviation of weekday d: "Mon" to "Sun".

The English name of month m: "January" to "December".

The three-letter English abbreviation of month m: "Jan" to "Dec".

The number of days from 1970-01-01 to the UTC date of t, rounded down (negative before 1970).

Midnight UTC of the date n days after 1970-01-01.

Whether a and b fall on the same UTC date.

Whether a and b fall on the same local date in zone z.

Whether t is on a Saturday or a Sunday (UTC).

Midnight UTC at the start of t's date.

The last millisecond of t's UTC date (23:59:59.999).

Midnight at the start of the week containing t, where weeks start on weekday first (1 is Monday, as in ISO 8601; 7 is Sunday, as in the US).

The last millisecond of the week containing t, where weeks start on weekday first.

Midnight UTC on the first day of t's month.

The last millisecond of t's month (UTC).

Midnight UTC on the first day of t's quarter (January, April, July or October 1).

The last millisecond of t's quarter (UTC).

Midnight UTC on January 1 of t's year.

The last millisecond of t's year (UTC): December 31, 23:59:59.999.

The instant at which the wall clock of zone z shows wall (a Time whose UTC fields are read as local fields, as Zone.local returns). In an overlap (clocks turned back) it is the earlier instant; in a gap (clocks turned forward, so wall never shows) it is the first instant after the gap, the moment the clocks jump.

The first instant of t's local date in zone z (usually local midnight; where midnight falls in a DST gap, the first instant after the gap).

The last millisecond of t's local date in zone z: one millisecond before the start of the next local date, so a day can be 23 or 25 hours long.

The first instant of the local week containing t in zone z, weeks starting on first.

The last millisecond of the local week containing t in zone z, weeks starting on first.

The first instant of t's local month in zone z.

The last millisecond of t's local month in zone z.

The first instant of t's local quarter in zone z.

The last millisecond of t's local quarter in zone z.

The first instant of t's local year in zone z.

The last millisecond of t's local year in zone z.

The local date of t in zone z, as midnight UTC of that date (for date arithmetic and comparisons that should ignore the zone afterwards).

A calendar with Saturday and Sunday as the weekend and the given holidays.

Whether the UTC date of t is a business day of cal: not a weekend day and not a holiday.

t moved by n business days of cal (backwards when n is negative), keeping the time of day. Counting starts from the day after (or before) t, so t itself need not be a business day; n == 0 returns t unchanged. The weekend must leave at least one business day a week.

The number of business days of cal from the date of a (included) to the date of b (excluded); negative when b is before a. Times of day are ignored.

The first business day of cal strictly after t's date, keeping the time of day.

The last business day of cal strictly before t's date, keeping the time of day.

t if it is a business day of cal, else the next business day (the "following" convention).

t if it is a business day of cal, else the previous business day ("preceding").

The first instant after t that is on weekday d, at the same time of day: 1 to 7 days later.

The last instant before t that is on weekday d, at the same time of day: 1 to 7 days earlier.

t if it is on weekday d, else next_weekday(t, d).

t if it is on weekday d, else previous_weekday(t, d).

The nth weekday d of month m of year y, at midnight UTC: n is 1 to 5 counting from the start (3 and Monday is the third Monday), or -1 to -5 counting from the end (-1 and Friday is the last Friday). none when the month has no such day (a fifth Monday).

The last weekday d of month m of year y, at midnight UTC (the last Friday).

Western (Gregorian) Easter Sunday of year y, at midnight UTC, by the anonymous Gregorian algorithm (Meeus, Jones, Butcher). It is computed for any year from 1, proleptically before 1583.

The ISO 8601 week date of t (UTC): weeks start on Monday and week 1 is the week with the year's first Thursday, so early January can be in the previous year's week 52 or 53 and late December in the next year's week 1.

The number of ISO weeks in ISO year y: 53 when January 1 is a Thursday, or a Wednesday in a leap year, else 52.

Midnight UTC of ISO week date (y, w, d); none when the week or weekday is out of range.

The ISO week date of t as text: "2026-W42-5".

Parses an ISO week date, extended ("2026-W42-5", "2026-W42") or basic ("2026W425", "2026W42"); a missing weekday is Monday. none for anything else or a week the year doesn't have.

The ordinal date of t (UTC) as text: year and day of the year, "2026-289".

Midnight UTC of day n (1 to 365 or 366) of year y; none when n is out of range.

Parses an ordinal date, "2026-289" or "2026289".

t moved by n units (backwards when negative). Months, quarters and years use Time.add_months, which clamps the day to the end of the month (January 31 plus one month is February 28 or 29); days and weeks are exact multiples of 24 hours.

The times start, start + every units, start + 2 * every units, ... that are before end (end excluded); empty when end <= start. Each element is computed from start (add_units(start, k * every, unit)), so a monthly range from January 31 gives February 28, March 31, April 30 rather than drifting to the 28th.

Like date_range but end is included when the steps land on it exactly.

The number of calendar days from the UTC date of a to the UTC date of b (negative when b is earlier); times of day are ignored.

The number of whole months from a to b: the largest m with a.add_months(m) <= b, or the negation of months_between(b, a) when b is before a.

The number of whole years from a to b, by the rule of months_between.

The age in whole years on date on of someone born on birth, from their dates (UTC; times of day are ignored). A February 29 birthday is reached on February 28 in common years. Negative when on is before birth.

The calendar difference from a to b as years, months, days, hours, minutes, seconds and milliseconds (weeks 0), such that add_period(a, diff(a, b)) == b when a <= b (except when a month end clamps). When b is before a every part is negated from diff(b, a).

The interval from a to b; none when b is before a.

The length of interval iv.

Whether iv is empty (its start equals its end).

Whether instant t is in iv: start <= t < end.

Whether outer contains all of inner.

Whether a and b share some instant (empty intervals overlap nothing).

Whether one interval ends exactly where the other starts.

The part a and b share; none when they don't overlap.

The interval between a and b when they are apart; none when they overlap or abut.

The smallest interval that contains both a and b.

The intervals sorted by start, with overlapping and abutting ones merged; empty ones dropped.

The period with every part 0.

The period with every part of p negated.

Whether every part of p is 0.

t moved by period p: first the years and months together with Time.add_months (clamping the day to the month's end), then the weeks, days, hours, minutes, seconds and milliseconds as exact durations.

The exact length of p when it has no years or months (days count 24 hours); none otherwise.

Duration d split into days, hours, minutes, seconds and milliseconds (no weeks, months or years); every part has the sign of d.

p as an ISO 8601 duration: "P1Y2M3DT4H5M6.5S", "P2W", "PT0S" for zero. When every non-zero part is negative the text starts with "-" ("-P1D"); mixed signs are written per part ("P1M-2D"), as java.time does. Milliseconds are written as a fraction of the seconds.

Parses an ISO 8601 duration: "P1Y2M10DT2H30M", "PT1.5S", "P3W", "-P1D", "P1M-2D". Units must come in the order Y M W D, then "T" and H M S; at least one part is required, and "T" must be followed by one. Only seconds may have a fraction ("." or ","), kept to milliseconds and truncated beyond. A leading "-" negates every part. none for anything else, or for a value that does not fit an Int.

The Unix time of t in whole seconds, rounded down.

The time s seconds after 1970-01-01T00:00:00Z; none when s * 1000 overflows an Int.

t as RFC 3339 text in zone z, with milliseconds only when they are not 0: "2026-10-16T21:43:27+05:30", "2026-10-16T16:13:27.123Z" in UTC.

Parses an RFC 3339 timestamp: date, "T" (or "t" or a space), hours, minutes and seconds, an optional fraction (kept to milliseconds, truncated beyond), and "Z" or an offset "+05:30". A leap second (":60") is rejected, as Time can't hold one. Stricter than the builtin parse_time, which also takes dates alone and offsets without minutes.

t as an RFC 5322 (RFC 2822) date in zone z: "Fri, 16 Oct 2026 21:43:27 +0530".

Parses an RFC 5322 (RFC 2822) date: an optional weekday and comma, a day of one or two digits, an English month abbreviation, a year (four digits; the obsolete two-digit years are 2000 to 2049 for 00 to 49 and 1950 to 1999 for 50 to 99, three-digit years add 1900), hours and minutes with optional seconds, and a zone: "+0530", "-0000", or the obsolete "UT", "GMT", "Z", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", "PDT" (military letters count as +0000, as RFC 5322 says). Names are case-insensitive, comments in parentheses and extra whitespace are ignored. A weekday that doesn't match the date gives none.

t as an HTTP date (IMF-fixdate, RFC 9110 section 5.6.7), always in GMT: "Sun, 06 Nov 1994 08:49:37 GMT".

Parses an HTTP date in the three forms RFC 9110 requires recipients to accept: IMF-fixdate ("Sun, 06 Nov 1994 08:49:37 GMT"), the obsolete RFC 850 form ("Sunday, 06-Nov-94 08:49:37 GMT", two-digit years 00 to 69 are 2000 to 2069 and 70 to 99 are 1970 to 1999) and asctime ("Sun Nov 6 08:49:37 1994"). Names are case-sensitive, as the RFC specifies. A weekday that doesn't match the date gives none.

Parses s by strftime pattern pat, the directives Time.format writes plus %z: %Y (four digits), %m %d %H %M %S (two digits), %L (three-digit milliseconds), %j (three-digit day of the year), %u (weekday digit, 1 is Monday), %a %A %b %B (English names, case-insensitive), %F (%Y-%m-%d), %T (%H:%M:%S), %z ("Z", "+0530" or "+05:30") and %%; every other character must match itself. Missing fields default to 1970-01-01 00:00:00.000 UTC; %j sets the month and day unless %m or %d is given, and then they must agree. A weekday that disagrees with the date, an unknown directive, an invalid date or leftover text gives none. Zone names (%Z) can't be parsed, since abbreviations are ambiguous.

How the local date of t relates to the local date of now in zone z, in words: "today", "yesterday", "tomorrow", a weekday within six days ("last Tuesday", "next Friday"), "last week" or "next week" (7 to 13 days), "3 weeks ago" or "in 2 weeks" (under a month), "last month", "in 5 months", "last year", "in 3 years". Times of day are ignored; whole months and years are counted by months_between of the local dates.

Like relative_date but with numbers instead of weekday names and "last"/"next": "today", "yesterday", "tomorrow", "3 days ago", "in 5 days", "1 week ago", "in 2 months", "4 years ago".