Skip to content
FutureBlitz

    Install

    Import std.time.calendar

    std.time.calendar

    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 15

    • 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.

    std/time/calendar.fb, line 33

    • @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 #

      The value to start from, like 0 for a number, "" for a String, or an empty collection.

      Doc from std.core.interfaces.Defaultable.DefaultValue.

    • 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 #

      That many days later, or earlier for a count below 0.

    • @PanicsAtCaller Public Method AddMonths(count: Int64): Date method #

      That many months later, or earlier, 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 #

      That many years later, or earlier, 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 and last days of its week, from Monday to Sunday, of its month, and of its year. The first Date's week starts before it, and the last's ends after it, so theirs panic.

    • @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 comes before b.

      Doc from std.core.interfaces.Comparable.Operator<.

    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.

    std/time/calendar.fb, line 240

    • @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 #

      The value to start from, like 0 for a number, "" for a String, or an empty collection.

      Doc from std.core.interfaces.Defaultable.DefaultValue.

    • 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 later, 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 comes before b.

      Doc from std.core.interfaces.Comparable.Operator<.

    • 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.

    std/time/calendar.fb, line 370

    • 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 #

      The value to start from, like 0 for a number, "" for a String, or an empty collection.

      Doc from std.core.interfaces.Defaultable.DefaultValue.

    • 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 later, or earlier, as Date's AddDays goes.

    • @PanicsAtCaller Public Method AddMonths(count: Int64): LocalDateTime method #

      The same time count months later, or earlier, as Date's AddMonths goes.

    • @PanicsAtCaller Public Method AddYears(count: Int64): LocalDateTime method #

      The same time count years later, or earlier, 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 comes before b.

      Doc from std.core.interfaces.Comparable.Operator<.

    • 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.