tempo/offset

Functions to use with the Offset type in Tempo. The offset values represents the time difference between the current time and UTC time.

Example

import tempo/offset

pub fn get_system_offset() {
  offset.local()
  |> offset.to_string
  // -> "+05:00"
}

Calendar and range of valid offsets

An offset is a signed number of minutes from UTC with no date attached, so nothing in this module depends on the Gregorian calendar or on any other, and there is no range of valid dates.

The range of valid offsets is -12:00 through +14:00, which covers every offset in current use, including the 30 and 45 minute ones. new, from_string and from_duration reject anything outside it.

Values

describe_parse_error

</>

pub fn describe_parse_error(
  error: error.OffsetParseError,
) -> String

Converts an offset parse error to a human readable error message.

Example

offset.from_string("bad offset")
|> snag.map_error(with: offset.describe_parse_error)
// -> snag.error("Invalid offset format: "bad offset"")

from_duration

</>

pub fn from_duration(
  duration: duration.Duration,
) -> Result(tempo.Offset, Nil)

Creates a new validated offset from a duration. Offsets are most commonly expressed as a number of minutes or hours.

Example

offset.new(duration.minutes(-65))
|> result.map(offset.to_string)
// -> Ok("-01:05")

offset.new(duration.hours(36))
// -> Error(Nil)

from_string

</>

pub fn from_string(
  offset: String,
) -> Result(tempo.Offset, error.OffsetParseError)

Tries to create a new offset from a string. Accepted formats are (+-)hh:mm, (+-)hhmm, (+-)hh, and (+-)h.

Example

offset.from_string("-04")
|> result.map(offset.to_string)
// -> Ok("-04:00")

literal

</>

pub fn literal(offset: String) -> tempo.Offset

Creates a new offset from a string literal, but will panic if the string is invalid. Accepted formats are (+-)hh:mm, (+-)hhmm, (+-)hh, and (+-)h.

Useful for declaring offset literals that you know are valid within your program.

Example

offset.literal("-04:00")
|> offset.to_string
// -> "-04:00"

local

</>

pub fn local() -> tempo.Offset

Returns the local offset of the host.

Example

offset.local()
|> offset.to_string
// -> "+05:00"

new

</>

pub fn new(
  from duration: duration.Duration,
) -> Result(tempo.Offset, Nil)

Deprecated: Use the more explicitly named `from_duration` function instead

to_duration

</>

pub fn to_duration(offset: tempo.Offset) -> duration.Duration

Converts an offset to a duration.

Example

offset.literal("-04:00")
|> offset.to_duration
// -> duration.hours(4)

to_string

</>

pub fn to_string(offset: tempo.Offset) -> String

Converts an offset to a string representation.

Will not return “Z” for a zero offset because it is probably not what the user wants without the context of a full datetime. Datetime modules building on this should cover formatting for Z themselves.

Example

offset.literal("-00")
|> offset.to_string
// -> "-00:00"

utc

</>

pub const utc: tempo.Offset

The Tempo representation of the UTC offset.