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:
- They are ambiguous if you don’t know what time-zone they are for.
- The type permits invalid states. e.g.
days
could be set to the number 32, but this should not be possible! - There is not a single unique canonical value for each point in time,
thanks to time zones. Two different
Date
+TimeOfDay
value pairs could represent the same point in time. This means that you can’t check for time equality with==
when using calendar types.
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
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.