Gleam Time

https://hexdocs.pm/gleam_time/
Admin
Gleam Time is a package for working with time in Gleam, providing modules for handling epoch time,...
Tokens:6,526
Snippets:40
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get System Time

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Retrieves the current system time as a Timestamp. Note that this time is not guaranteed to be unique or monotonic and its behavior depends on the runtime environment.

```gleam
pub fn system_time() -> Timestamp
```

--------------------------------

### Get Local Time Zone Offset in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Provides the `local_offset` function to retrieve the UTC offset for the computer's currently configured time zone. It warns that this might not be the user's correct time zone and can be affected by daylight saving time.

```gleam
pub fn local_offset() -> duration.Duration
```

--------------------------------

### Gleam Duration Constructor: Minutes

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Creates a `Duration` value representing a specified number of minutes in Gleam.

```gleam
pub fn minutes(amount: Int) -> Duration
```

--------------------------------

### Gleam Duration Constructor: Seconds

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Creates a `Duration` value representing a specified number of seconds in Gleam.

```gleam
pub fn seconds(amount: Int) -> Duration
```

--------------------------------

### Gleam Duration Constructor: Hours

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Creates a `Duration` value representing a specified number of hours in Gleam.

```gleam
pub fn hours(amount: Int) -> Duration
```

--------------------------------

### Gleam Duration Constructor: Milliseconds

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Creates a `Duration` value representing a specified number of milliseconds in Gleam.

```gleam
pub fn milliseconds(amount: Int) -> Duration
```

--------------------------------

### Gleam Create Timestamp from Unix Seconds

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Creates a `Timestamp` from a specified number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

```gleam
pub fn from_unix_seconds(seconds: Int) -> Timestamp
```

--------------------------------

### Gleam Duration Approximate Function

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Converts a `Duration` to a human-understandable rough description using the largest possible `Unit`. It returns a tuple of an integer amount and the unit, rounding towards zero.

```gleam
pub fn approximate(duration: Duration) -> #(Int, Unit)
```

--------------------------------

### Gleam Create Timestamp from Unix Seconds and Nanoseconds

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Creates a `Timestamp` from both seconds and nanoseconds since the Unix epoch. It includes a note about JavaScript's integer limitations, advising to use seconds primarily for precision.

```gleam
pub fn from_unix_seconds_and_nanoseconds(
  seconds seconds: Int,
  nanoseconds nanoseconds: Int,
) -> Timestamp
```

--------------------------------

### Gleam Duration Constructor: Nanoseconds

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Creates a `Duration` value representing a specified number of nanoseconds in Gleam. Warns about JavaScript integer limitations for very large values.

```gleam
pub fn nanoseconds(amount: Int) -> Duration
```

--------------------------------

### Gleam Duration to Seconds and Nanoseconds Conversion

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Converts a `Duration` to a tuple of seconds and nanoseconds in Gleam, preserving full precision without loss.

```gleam
pub fn to_seconds_and_nanoseconds(
  duration: Duration,
) -> #(Int, Int)
```

--------------------------------

### Gleam Create Timestamp from Calendar Time

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Creates a `Timestamp` from human-readable date, time, and timezone offset components. This function allows for the construction of timestamps from structured calendar information.

```gleam
pub fn from_calendar(
  date date: calendar.Date,
  time time: calendar.TimeOfDay,
  offset offset: duration.Duration,
) -> Timestamp
```

--------------------------------

### Gleam Unit Enum Definition

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Defines the `Unit` enum for Gleam, representing different divisions of time like Nanosecond, Second, Minute, Hour, Day, Week, Month, and Year. Averages are used for months and years.

```gleam
pub type Unit {
  Nanosecond
  Microsecond
  Millisecond
  Second
  Minute
  Hour
  Day
  Week
  Month
  Year
}
```

--------------------------------

### Convert Month to String (Gleam)

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Returns the English name for a given month. This function is helpful for displaying month names in a human-readable format.

```gleam
pub fn month_to_string(month: Month) -> String {
  // Implementation details would go here
}

month_to_string(April)
// -> "April"
```

--------------------------------

### Gleam Duration to Seconds Conversion

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Converts a `Duration` to a `Float` representing the total number of seconds in Gleam. May involve minor precision loss due to `Float` limitations.

```gleam
pub fn to_seconds(duration: Duration) -> Float
```

--------------------------------

### Gleam Parse RFC 3339 Timestamp

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Parses a string formatted according to RFC 3339 into a `Timestamp` type. It returns a `Result` which is either a `Timestamp` on success or `Nil` on failure.

```gleam
pub fn parse_rfc3339(input: String) -> Result(Timestamp, Nil)
```

--------------------------------

### Convert Timestamp to RFC 3339 String

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Formats a Timestamp into an RFC 3339 compliant string, including a provided duration offset. Offsets are rounded to the nearest minute. It's recommended to use Unix timestamps for APIs due to payload size and potential ambiguity.

```gleam
pub fn to_rfc3339(
  timestamp: Timestamp,
  offset: duration.Duration,
) -> String
```

```gleam
timestamp.from_unix_seconds_and_nanoseconds(1000, 123_000_000)
|> to_rfc3339(calendar.utc_offset)
// -> "1970-01-01T00:16:40.123Z"
```

```gleam
timestamp.from_unix_seconds(1000)
|> to_rfc3339(duration.seconds(3600))
// -> "1970-01-01T01:16:40+01:00"
```

--------------------------------

### Gleam Duration to ISO8601 String Conversion

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Converts a `Duration` to an ISO8601 formatted string in Gleam. The format encodes days, hours, and seconds, excluding leap seconds and handling month/year ambiguity.

```gleam
pub fn to_iso8601_string(duration: Duration) -> String
```

--------------------------------

### Gleam Timestamp Type

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Defines the opaque `Timestamp` type in Gleam, which is the main time type to be favored over other types. It is efficient, unambiguous, and cannot be constructed in an invalid state.

```gleam
pub opaque type Timestamp
```

--------------------------------

### Gleam Duration Compare Function

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Compares two `Duration` values in Gleam, returning an `order.Order` enum (`Lt`, `Eq`, `Gt`) indicating if the first duration is less than, equal to, or greater than the second.

```gleam
pub fn compare(left: Duration, right: Duration) -> order.Order
```

--------------------------------

### Gleam Duration Add Function

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Adds two `Duration` values together in Gleam. The function takes two durations as input and returns a new duration representing their sum.

```gleam
pub fn add(left: Duration, right: Duration) -> Duration
```

--------------------------------

### Convert Integer to Month in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

The `month_from_int` function converts an integer (1 for January, 12 for December) into a `Month` type, returning a `Result` to handle invalid inputs.

```gleam
pub fn month_from_int(month: Int) -> Result(Month, Nil)

month_from_int(1)
// -> Ok(January)
```

--------------------------------

### Convert Timestamp to Unix Seconds and Nanoseconds

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Converts a Timestamp to a tuple containing the number of seconds and nanoseconds elapsed since January 1, 1970, 00:00:00 UTC. This conversion preserves the full precision of the Timestamp.

```gleam
pub fn to_unix_seconds_and_nanoseconds(
  timestamp: Timestamp,
) -> #(Int, Int)
```

--------------------------------

### Parse RFC 3339 Timestamp

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Parses a timestamp string in RFC 3339 format. Handles valid and invalid timestamp formats, returning either the parsed timestamp or an error.

```gleam
let assert Ok(ts) = timestamp.parse_rfc3339("1970-01-01T00:00:01Z")
timestamp.to_unix_seconds_and_nanoseconds(ts)
// -> #(1, 0)
```

```gleam
let assert Error(Nil) = timestamp.parse_rfc3339("1995-10-31")
```

--------------------------------

### Gleam Compare Timestamps

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Compares two timestamps to determine their chronological order. It returns an `order.Order` enum value indicating if the first timestamp is less than, equal to, or greater than the second.

```gleam
pub fn compare(left: Timestamp, right: Timestamp) -> order.Order
```

--------------------------------

### Convert Month to Integer (Gleam)

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Converts a month representation to its corresponding integer value. This function is useful for numerical processing of dates.

```gleam
month_to_int(January)
// -> 1
```

--------------------------------

### Convert Timestamp to Calendar Time

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Converts a Timestamp to a human-readable calendar date and time, using a specified duration offset. This is intended for presentation, not machine processing.

```gleam
pub fn to_calendar(
  timestamp: Timestamp,
  offset: duration.Duration,
) -> #(calendar.Date, calendar.TimeOfDay)
```

```gleam
timestamp.from_unix_seconds(0)
|> timestamp.to_calendar(calendar.utc_offset)
// -> #(Date(1970, January, 1), TimeOfDay(0, 0, 0, 0))
```

--------------------------------

### UTC Offset Constant (Gleam)

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Provides the offset for the Coordinated Universal Time (UTC) time zone. UTC has no time adjustments, never observes daylight-saving time, and is not affected by political restructuring.

```gleam
pub const utc_offset: duration.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.
```

--------------------------------

### Validate Date in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Provides the `is_valid_date` function to check if a given `Date` is valid, correctly accounting for leap years, especially for February.

```gleam
pub fn is_valid_date(date: Date) -> Bool {
  // ... implementation details ...
}

is_valid_date(Date(2023, April, 15))
// -> True

is_valid_date(Date(2023, April, 31))
// -> False

is_valid_date(Date(2024, February, 29))
// -> True (2024 is a leap year)
```

--------------------------------

### Gleam Duration Difference Function

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Calculates the difference between two `Duration` values in Gleam, effectively subtracting the first duration from the second.

```gleam
pub fn difference(left: Duration, right: Duration) -> Duration
```

--------------------------------

### Convert Timestamp to Unix Seconds

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Converts a Timestamp to the number of seconds elapsed since January 1, 1970, 00:00:00 UTC. This conversion may involve a small loss of precision because Timestamp is nanosecond-accurate while Float is not.

```gleam
pub fn to_unix_seconds(timestamp: Timestamp) -> Float
```

--------------------------------

### Convert Month to Integer in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

The `month_to_int` function converts a `Month` type back into its corresponding integer representation, where January is 1 and December is 12.

```gleam
pub fn month_to_int(month: Month) -> Int
```

--------------------------------

### Define Month Enum Type in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Defines the `Month` enumeration type, representing the 12 months of the Gregorian calendar. Each month from January to December is listed as a distinct value.

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

--------------------------------

### Define TimeOfDay Type in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Defines the `TimeOfDay` type for representing the time of day, including hours, minutes, seconds, and nanoseconds. This type is ambiguous without a date and time zone.

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

--------------------------------

### Validate TimeOfDay in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Implements the `is_valid_time_of_day` function to validate a `TimeOfDay` value, ensuring hours are 0-23, minutes 0-59, seconds 0-59, and nanoseconds 0-999,999,999.

```gleam
pub fn is_valid_time_of_day(time: TimeOfDay) -> Bool {
  // ... implementation details ...
}

is_valid_time_of_day(TimeOfDay(12, 30, 45, 123456789))
// -> True
```

--------------------------------

### Define Gregorian Calendar Date Type in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Defines the `Date` type for representing a Gregorian calendar date, including year, month, and day. It's noted that this type is ambiguous without a time zone and users should prefer the `Timestamp` type for computer-readable time.

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

--------------------------------

### Gleam Calculate Timestamp Difference

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Calculates the duration between two timestamps by subtracting the second timestamp from the first. This is useful for measuring time intervals.

```gleam
pub fn difference(
  left: Timestamp,
  right: Timestamp,
) -> duration.Duration
```

--------------------------------

### Gleam Duration Type Definition

Source: https://hexdocs.pm/gleam_time/gleam/time/duration

Defines the opaque `Duration` type in Gleam, representing an amount of time with nanosecond precision. It is not suitable for calendar periods.

```gleam
pub opaque type Duration
```

--------------------------------

### Check for Leap Year in Gleam

Source: https://hexdocs.pm/gleam_time/gleam/time/calendar

Implements the `is_leap_year` function to determine if a given year is a leap year. A leap year occurs every 4 years, except for years divisible by 100 unless they are also divisible by 400.

```gleam
pub fn is_leap_year(year: Int) -> Bool {
  // ... implementation details ...
}

is_leap_year(2024)
// -> True

is_leap_year(2023)
// -> False
```

--------------------------------

### Gleam Add Duration to Timestamp

Source: https://hexdocs.pm/gleam_time/gleam/time/timestamp

Adds a duration to a given timestamp, returning a new timestamp. This function is useful for time calculations where you need to advance a specific point in time by a certain duration.

```gleam
pub fn add(
  timestamp: Timestamp,
  duration: duration.Duration,
) -> Timestamp
```
Tokens:
Raw