gleam/time/calendar

This module is for working with the Gregorian calendar, established by Pope Gregory XIII in 1582!

When should you use this module?

The types in this module type are useful when you want to communicate time to a human reader, but they are not ideal for computers to work with. Disadvantages of calendar time types include:

Prefer to represent your time using the Timestamp type, and convert it only to calendar types when you need to display them.

Time zone offsets

This package includes the utc_offset value and the local_offset function, which are the offset for the UTC time zone and get the time offset the computer running the program is configured to respectively.

If you need to use other offsets in your program then you will need to get them from somewhere else, such as from a package which loads the IANA Time Zone Database, or from the website visitor’s web browser, which your frontend can send for you.

Use in APIs

If you are making an API such as a HTTP JSON API you are encouraged to use Unix timestamps instead of calendar times.

Types

The Gregorian calendar date. Ambiguous without a time zone.

Prefer to represent your time using the Timestamp type, and convert it only to calendar types when you need to display them. See the documentation for this module for more information.

pub type Date {
  Date(year: Int, month: Month, day: Int)
}

Constructors

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

The 12 months of the year.

pub type Month {
  January
  February
  March
  April
  May
  June
  July
  August
  September
  October
  November
  December
}

Constructors

  • January
  • February
  • March
  • April
  • May
  • June
  • July
  • August
  • September
  • October
  • November
  • December

The time of day. Ambiguous without a date and time zone.

pub type TimeOfDay {
  TimeOfDay(
    hours: Int,
    minutes: Int,
    seconds: Int,
    nanoseconds: Int,
  )
}

Constructors

  • TimeOfDay(
      hours: Int,
      minutes: Int,
      seconds: Int,
      nanoseconds: Int,
    )

Constants

pub const utc_offset: Duration

The offset for the Coordinated Universal Time (UTC) time zone.

The utc zone has no time adjustments, it is always zero. It never observes daylight-saving time and it never shifts around based on political restructuring.

Functions

pub fn local_offset() -> Duration

Get the offset for the computer’s currently configured time zone.

Note this may not be the time zone that is correct to use for your user. For example, if you are making a web application that runs on a server you want their computer’s time zone, not yours.

Search Document