Import std.time.calendar

std.time.calendar

Dates, times of day, and the two together, without a time zone.

The calendar's types, in the proleptic Gregorian calendar and without a zone: Date, a day; TimeOfDay, a time on a day's clock, to the nanosecond; and LocalDateTime, the two together. Their zeros are 1970-01-01, midnight, and the two of those. Adding months or years clamps the day to the month's last, so Jan 31 plus a month is Feb 28 or 29. ToString and Parse write and read ISO 8601, like "2026-10-23", "12:30:00.5", and "2026-10-23T12:30:00", and Format and Parse take patterns too (in format.fb).

std/time/calendar.fb

Types

`Weekday` enum

Public Enum Weekday

A day of the week, as ISO 8601 numbers them, from Monday's 1 to Sunday's 7.

std/time/calendar.fb, line 17

MONDAY = 1 enum member #

Monday, 1.
TUESDAY enum member #

Tuesday, 2.
WEDNESDAY enum member #

Wednesday, 3.
THURSDAY enum member #

Thursday, 4.
FRIDAY enum member #

Friday, 5.
SATURDAY enum member #

Saturday, 6.
SUNDAY enum member #

Sunday, 7.

`Date` struct

Public Struct Date Implements Comparable, Hashable, Printable, Defaultable

A day, from the year -2147483648 to 2147483647, the years an Int holds.

Examples

Local day = Date(2024, 2, 28)
Expect(day.AddDays(1) == Date(2024, 2, 29))
Expect(day.IsLeapYear && day.DaysInMonth == 29)
Expect(day.DayOfWeek == Weekday.WEDNESDAY)
Expect(Date(2024, 1, 31).AddMonths(1) == Date(2024, 2, 29))
Expect("{day}" == "2024-02-28")
Expect(Date.Parse("2024-02-30") == Null)

std/time/calendar.fb, line 47

@PanicsAtCaller Public New(year: Int, month: Int, day: Int) constructor #

The date, which panics when it isn't one, like 2026-02-30.
@PanicsAtCaller Public Static Method FromDays(days: Int64): Date static method #

The date that many days after 1970-01-01, or before it for a count below 0. One whose year isn't an Int panics.
Public Static Method DefaultValue(): Date static method #

1970-01-01, the Unix epoch's day.
Public Static Method MinValue(): Date static method #

The earliest Date there is.
Public Static Method MaxValue(): Date static method #

The latest Date there is.
Public Static Method Today(zone: TimeZone): Date static method #

Today, where the zone is, or the OS's zone.
Public Static Method Today(): Date static method #

Today, in the OS's zone.
Public Static Method IsValid(year: Int, month: Int, day: Int): Bool static method #

Whether the year, month, and day are a date.
Public Static Method IsLeap(year: Int64): Bool static method #

Whether the year has a Feb 29.
Public Static Method DaysIn(year: Int64, month: Int): Int static method #

How many days the month has in the year, or 0 for a month that isn't from 1 to 12.
Public Static Method Parse(text: String): Date? static method #

The date ISO 8601 writes, like "2026-10-23", with a sign before a year past 4 digits, or Null.
@PanicsAtCaller Public Static Method Parse(text: String, pattern: String): Date? static method #

The date the text writes as the pattern says (see format.fb), or Null. A pattern without the year, or without the month and day or the day of the year, panics.
Public Property Year: Int property #

Its year.
Public Property Month: Int property #

From 1, January's, to 12.
Public Property Day: Int property #

Of the month, from 1.
Public Property DayOfWeek: Weekday property #

Its day of the week.
Public Property DayOfYear: Int property #

From 1, Jan 1's, to 365, or 366 in a leap year.
Public Property DaysSinceEpoch: Int64 property #

Its days since 1970-01-01, below 0 before it.
Public Property IsLeapYear: Bool property #

Whether its year is a leap year.
Public Property DaysInMonth: Int property #

How many days its month has.
@PanicsAtCaller Public Method AddDays(count: Int64): Date method #

The date that many days after, or before for a count below 0.
@PanicsAtCaller Public Method AddMonths(count: Int64): Date method #

The date that many months after, or before, on the same day, or the month's last when it's shorter: Jan 31 plus a month is Feb 28, or 29 in a leap year.
@PanicsAtCaller Public Method AddYears(count: Int64): Date method #

The date that many years after, or before, on the same day, or Feb 28 for Feb 29 in a year that has none.
Public Method DaysUntil(other: Date): Int64 method #

How many days it is to the other date, below 0 when it's earlier.
@PanicsAtCaller Public Method StartOfWeek(): Date method #

The first day of its week, a Monday. The first Date's week starts before it, so its StartOfWeek panics, as the last Date's EndOfWeek does.
@PanicsAtCaller Public Method EndOfWeek(): Date method #

The last day of its week, a Sunday.
Public Method StartOfMonth(): Date method #

The first day of its month.
Public Method EndOfMonth(): Date method #

The last day of its month.
Public Method StartOfYear(): Date method #

The first day of its year.
Public Method EndOfYear(): Date method #

The last day of its year.
Public Method At(time: TimeOfDay): LocalDateTime method #

It at that time of day.
@PanicsAtCaller Public Method StartOfDay(zone: TimeZone): ZonedDateTime method #

Its first moment where the zone is: midnight, or when its clocks reach the day, where they skip midnight.
Public Method ToString(): String method #

As ISO 8601 writes it, like "2026-10-23".
@PanicsAtCaller Public Method Format(pattern: String): String method #

As the pattern says (see format.fb): Format("EEE d MMM yyyy") is "Fri 23 Oct 2026". A pattern letter of a time or a zone panics.
Operator <(a: Date, b: Date): Bool operator #

Whether a is before b.

`TimeOfDay` struct

Public Struct TimeOfDay Implements Comparable, Hashable, Printable, Defaultable

A time on a day's clock, from midnight to a nanosecond before the next.

Examples

Local late = TimeOfDay(23, 30)
Expect("{late}" == "23:30:00")
Expect(late + 2.Hours == TimeOfDay(1, 30))
Expect(late.Format("h:mm a") == "11:30 PM")

std/time/calendar.fb, line 266

@PanicsAtCaller Public New(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0) constructor #

The time, which panics when it isn't one: hours from 0 to 23, minutes and seconds from 0 to 59, and nanoseconds from 0 to 999999999.
@PanicsAtCaller Public Static Method FromNanosecondOfDay(nanoseconds: Int64): TimeOfDay static method #

The time that many nanoseconds after midnight, which panics when it's not on the day.
Public Static Method Midnight(): TimeOfDay static method #

The time at the start of a day: 00:00.
Public Static Method Noon(): TimeOfDay static method #

The time in the middle of a day: 12:00.
Public Static Method DefaultValue(): TimeOfDay static method #

Midnight, 00:00:00.
Public Static Method MinValue(): TimeOfDay static method #

The earliest time of day: 00:00.
Public Static Method MaxValue(): TimeOfDay static method #

The latest time of day: a nanosecond before midnight.
Public Static Method Now(zone: TimeZone): TimeOfDay static method #

Now, where the zone is, or the OS's zone.
Public Static Method Now(): TimeOfDay static method #

Now, in the OS's zone.
Public Static Method IsValid(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): Bool static method #

Whether hour, minute, second, and nanosecond are a time of day.
Public Static Method Parse(text: String): TimeOfDay? static method #

The time ISO 8601 writes, like "12:30", "12:30:15", or "12:30:15.25", or Null.
@PanicsAtCaller Public Static Method Parse(text: String, pattern: String): TimeOfDay? static method #

The time the text writes as the pattern says (see format.fb), or Null. A pattern without the hour panics.
Public Property Hour: Int property #

From 0 to 23.
Public Property Minute: Int property #

From 0 to 59.
Public Property Second: Int property #

From 0 to 59.
Public Property Nanosecond: Int property #

Of the second, from 0 to 999999999.
Public Property SecondOfDay: Int property #

How many seconds of the day have gone by, from 0 to 86399.
Public Property NanosecondOfDay: Int64 property #

How many nanoseconds of the day have gone by.
Operator +(a: TimeOfDay, b: Duration): TimeOfDay operator #

a on the clock b after, around midnight as a clock goes: 23:00 plus 2 hours is 01:00.
Operator -(a: TimeOfDay, b: Duration): TimeOfDay operator #

a on the clock b earlier, around midnight as a clock goes: 01:00 minus 2 hours is 23:00.
Operator -(a: TimeOfDay, b: TimeOfDay): Duration operator #

How long it is from b to a on the same day, below 0 when a is earlier.
Operator <(a: TimeOfDay, b: TimeOfDay): Bool operator #

Whether a is earlier on the clock than b.
Public Method ToString(): String method #

As ISO 8601 writes it, with seconds, and a fraction only when there is one, like "12:30:00" and "12:30:00.25".
@PanicsAtCaller Public Method Format(pattern: String): String method #

As the pattern says (see format.fb): Format("h:mm a") is "1:30 PM". A pattern letter of a date or a zone panics.

`LocalDateTime` struct

Public Struct LocalDateTime Implements Comparable, Hashable, Printable, Defaultable

A date and a time of day, without a zone, as a wall calendar and clock show them.

Examples

Local meeting = LocalDateTime(2024, 3, 9, 14, 30)
Expect("{meeting}" == "2024-03-09T14:30:00")
Expect(meeting.AddDays(1).Date == Date(2024, 3, 10))
Expect(LocalDateTime.Parse("2024-03-09T14:30:00") == meeting)

std/time/calendar.fb, line 407

Public New(date: Date, time: TimeOfDay) constructor #

The time of day time on date.
@PanicsAtCaller Public New(year: Int, month: Int, day: Int, hour: Int = 0, minute: Int = 0, second: Int = 0, nanosecond: Int = 0) constructor #

The date and time, which panics when either isn't one.
Public Static Method DefaultValue(): LocalDateTime static method #

Midnight on 1970-01-01.
Public Static Method MinValue(): LocalDateTime static method #

The earliest LocalDateTime there is.
Public Static Method MaxValue(): LocalDateTime static method #

The latest LocalDateTime there is.
Public Static Method Now(zone: TimeZone): LocalDateTime static method #

Now, where the zone is, or the OS's zone.
Public Static Method Now(): LocalDateTime static method #

Now, in the OS's zone.
Public Static Method Parse(text: String): LocalDateTime? static method #

The date and time ISO 8601 writes, like "2026-10-23T12:30:00", with "T", "t", or a space between them, or Null.
@PanicsAtCaller Public Static Method Parse(text: String, pattern: String): LocalDateTime? static method #

The date and time the text writes as the pattern says (see format.fb), or Null. A pattern without the year, or without the month and day or the day of the year, panics; the time's parts it doesn't have are 0.
Public Property Date: Date property #

Its date.
Public Property Time: TimeOfDay property #

Its time of day.
Public Property Year: Int property #

Its date's year.
Public Property Month: Int property #

Its date's month, from 1 to 12.
Public Property DayOfMonth: Int property #

Its date's day of the month, from 1.
Public Property Hour: Int property #

Its hour, from 0 to 23.
Public Property Minute: Int property #

Its minute, from 0 to 59.
Public Property Second: Int property #

Its second, from 0 to 59.
Public Property Nanosecond: Int property #

Its nanosecond of the second.
Public Property DayOfWeek: Weekday property #

Its date's day of the week.
Public Property DayOfYear: Int property #

Its date's day of the year, from 1.
@PanicsAtCaller Public Method AddDays(count: Int64): LocalDateTime method #

The same time count days after, or before, as Date's AddDays goes.
@PanicsAtCaller Public Method AddMonths(count: Int64): LocalDateTime method #

The same time count months after, or before, as Date's AddMonths goes.
@PanicsAtCaller Public Method AddYears(count: Int64): LocalDateTime method #

The same time count years after, or before, as Date's AddYears goes.
Public Method StartOfDay(): LocalDateTime method #

Midnight on its day.
@PanicsAtCaller Public Method InZone(zone: TimeZone, disambiguation: Disambiguation = Disambiguation.COMPATIBLE): ZonedDateTime method #

It where the zone is. When the zone's clocks show it twice, as they're turned back, or never, as they skip it, the disambiguation says which moment it is (see zone.fb).
@PanicsAtCaller Operator +(a: LocalDateTime, b: Duration): LocalDateTime operator #

b after a, on a clock that's never turned: 23:00 plus 2 hours is 01:00 the next day.
@PanicsAtCaller Operator -(a: LocalDateTime, b: Duration): LocalDateTime operator #

b before a, on a clock that's never turned: 01:00 minus 2 hours is 23:00 the day before.
@PanicsAtCaller Operator -(a: LocalDateTime, b: LocalDateTime): Duration operator #

How long it is from b to a, on a clock that's never turned, which panics past the longest Duration.
Operator <(a: LocalDateTime, b: LocalDateTime): Bool operator #

Whether a is before b.
Public Method ToString(): String method #

As ISO 8601 writes it, like "2026-10-23T12:30:00".
@PanicsAtCaller Public Method Format(pattern: String): String method #

As the pattern says (see format.fb): Format("yyyy-MM-dd HH:mm") is "2026-10-23 12:30". A pattern letter of a zone panics.

Report an issue with this page or with FutureBlitz on GitHub.

std.time.calendar

Types

Weekday enum

Date struct

Examples

TimeOfDay struct

Examples

LocalDateTime struct

Examples

`Weekday` enum

`Date` struct

`TimeOfDay` struct

`LocalDateTime` struct