gtempo - v3.0.0

tempo/time

Types

Boundary

</> 
pub type Boundary {
  Boundary(time: tempo.Time, inclusive: Bool)
}

Constructors 

  • Boundary(time: tempo.Time, inclusive: Bool)

Functions

add

</> 
pub fn add(a: Time, duration b: Duration) -> Time

Adds a duration to a time.

Example

time.literal("08:42:53")
|> time.add(duration.mintues(36))
// -> time.literal("09:18:53")

compare

</> 
pub fn compare(a: Time, to b: Time) -> Order

Compares two time values.

Example

time.literal("13:42:11")
|> time.compare(to: time.literal("13:42:11"))
// -> order.Eq

time.literal("15:32:01")
|> time.compare(to: time.literal("13:42:11"))
// -> order.Gt

time.literal("13:10:11")
|> time.compare(to: time.literal("13:42:11"))
// -> order.Lt

difference

</> 
pub fn difference(a: Time, from b: Time) -> Duration

Gets the difference between two times as a duration.

Example

time.literal("23:42:11.435")
|> time.difference(from: time.literal("23:42:09.743"))
|> duration.as_milliseconds
// -> 1692

time.literal("13:30:11")
|> time.difference(from: time.literal("13:55:13"))
|> duration.as_minutes
// -> -25

difference_abs

</> 
pub fn difference_abs(a: Time, from b: Time) -> Duration

Gets the absolute difference between two times as a duration.

Example

time.literal("23:42:11.435")
|> time.difference(from: time.literal("23:42:09.743"))
|> duration.as_milliseconds
// -> 1692

time.literal("13:30:11")
|> time.difference(from: time.literal("13:55:13"))
|> duration.as_minutes
// -> 25

from_duration

</> 
pub fn from_duration(duration: Duration) -> Time

Converts a duration to the equivalent time of day, assuming the duration epoch is “00:00:00”. Durations longer than 24 hours will be wrapped to fit within a 24 hour representation.

Example

duration.seconds(58)
|> time.from_duration
|> time.to_second_precision
|> time.to_string
// -> "00:00:58"

duration.minutes(17)
|> time.from_duration
|> time.to_string
// -> "00:17:00.000000000"

duration.hours(25)
|> time.from_duration
|> time.to_string
// -> "01:00:00.000000000"

duration.nanoseconds(-3_000_000_000)
|> time.from_duration
|> time.to_string
// -> "23:59:57.000000000"

from_string

</> 
pub fn from_string(time: String) -> Result(Time, Error)

Converts a string to a time value. Accepted formats are hh:mm:ss.s, hhmmss.s, hh:mm:ss, hhmmss, hh:mm, or hhmm.

Example

time.from_string("00:00:00.000000300")
// -> Ok(time.literal("00:00:00.000000300"))

time.from_string("34:54:16")
// -> Error(tempo.TimeOutOfBounds)

from_tuple

</> 
pub fn from_tuple(time: #(Int, Int, Int)) -> Result(Time, Error)

Converts a tuple of hours, minutes, and seconds to a time value. Useful for using with another time library.

Example

#(13, 42, 11)
|> time.from_tuple
// -> time.literal("13:42:11")

from_tuple_nanosecond

</> 
pub fn from_tuple_nanosecond(
  time: #(Int, Int, Int, Int),
) -> Result(Time, Error)

Converts a tuple of hours, minutes, seconds, and nanoseconds to a time value. Useful for using with another time library.

Example

#(13, 42, 11, 872000000)
|> time.from_tuple_nanosecond
|> time.to_milli_precision
// -> time.literal("13:42:11.872")

is_between

</> 
pub fn is_between(
  time: Time,
  start: Boundary,
  and end: Boundary,
) -> Bool

Checks if a time is between two boundaries.

Example

time.literal("13:42:11")
|> time.is_between(
    Boundary(time.literal("05:00:00"), inclusive: True), 
    and: Boundary(time.literal("15:00:00"), inclusive: False),
  )
// -> True

is_earlier

</> 
pub fn is_earlier(a: Time, than b: Time) -> Bool

Checks if the first time is earlier than the second time.

Example

time.literal("13:42:11")
|> time.is_earlier(than: time.literal("13:42:12"))
// -> True

time.literal("13:42:11")
|> time.is_earlier(than: time.literal("13:42:11"))
// -> False

time.literal("13:22:15")
|> time.is_earlier(than: time.literal("07:42:11"))
// -> False

is_earlier_or_equal

</> 
pub fn is_earlier_or_equal(a: Time, to b: Time) -> Bool

Checks if the first time is earlier or equal to the second time.

Example

time.literal("13:42:11")
|> time.is_earlier_or_equal(to: time.literal("13:42:12"))
// -> True

time.literal("13:42:11")
|> time.is_earlier_or_equal(to: time.literal("13:42:11.000"))
// -> True

time.literal("13:22:15")
|> time.is_earlier_or_equal(to: time.literal("07:42:12"))
// -> False

is_equal

</> 
pub fn is_equal(a: Time, to b: Time) -> Bool

Checks if the first time is equal to the second time.

Example

time.literal("13:42:11.000")
|> time.is_equal(to: time.literal("13:42:11"))
// -> True

time.literal("13:42:11.002")
|> time.is_equal(to: time.literal("13:42:11"))
// -> False

is_later

</> 
pub fn is_later(a: Time, than b: Time) -> Bool

Checks if the first time is later than the second time.

Example

time.literal("13:22:15")
|> time.is_later(than: time.literal("07:42:11"))
// -> True

time.literal("13:42:11")
|> time.is_later(than: time.literal("13:42:12"))
// -> False

time.literal("13:42:11")
|> time.is_later(than: time.literal("13:42:11"))
// -> False

is_later_or_equal

</> 
pub fn is_later_or_equal(a: Time, to b: Time) -> Bool

Checks if the first time is earlier or equal to the second time.

Example

time.literal("13:22:15")
|> time.is_later_or_equal(to: time.literal("07:42:12"))
// -> True

```gleam
time.literal("13:42")
|> time.is_later_or_equal(to: time.literal("13:42:00.000"))
// -> True

time.literal("13:42:11")
|> time.is_later_or_equal(to: time.literal("13:42:12"))
// -> False

is_outside

</> 
pub fn is_outside(
  time: Time,
  start: Boundary,
  and end: Boundary,
) -> Bool

Checks if a time is outside of two boundaries.

Example

time.literal("13:42:11")
|> time.is_outside(
    time.Boundary(time.literal("05:00:00"), inclusive: True), 
    and: time.Boundary(time.literal("15:00:00"), inclusive: False),
  )
// -> False

left_in_day

</> 
pub fn left_in_day(time: Time) -> Time

Converts a time to the equivalent time left in the day.

Example

time.literal("23:59:03") |> time.left_in_day
// -> time.literal("00:00:57")

time.literal("08:05:20") |> time.left_in_day
// -> time.literal("15:54:40")

literal

</> 
pub fn literal(time: String) -> Time

Creates a new time value from a string literal, but will panic if the string is invalid. Accepted formats are hh:mm:ss.s, hhmmss.s, hh:mm:ss, hhmmss, hh:mm, or hhmm.

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

Example

case 
  time.now_local() 
  |> time.is_later(than: time.literal("11:50:00")) 
{ 
  True -> "We are late!"
  False -> "No rush :)"
}

new

</> 
pub fn new(
  hour: Int,
  minute: Int,
  second: Int,
) -> Result(Time, Error)

Creates a new time value with second precision.

Example

time.new(13, 42, 11)
// -> Ok(time.literal("13:42:11"))

time.new(53, 42, 61)
// -> Error(tempo.TimeOutOfBounds)

new_micro

</> 
pub fn new_micro(
  hour: Int,
  minute: Int,
  second: Int,
  microsecond: Int,
) -> Result(Time, Error)

Creates a new time value with microsecond precision.

Example

time.new_micro(13, 42, 11, 20)
// -> Ok(time.literal("13:42:11.000020"))

time.new_micro(13, 42, 11, 200_000)
// -> Ok(time.literal("13:42:11.200000"))

time.new_micro(13, 42, 11, 7_500_000)
// -> Error(tempo.TimeOutOfBounds)

new_milli

</> 
pub fn new_milli(
  hour: Int,
  minute: Int,
  second: Int,
  millisecond: Int,
) -> Result(Time, Error)

Creates a new time value with millisecond precision.

Example

time.new_milli(13, 42, 11, 20)
// -> Ok(time.literal("13:42:11.020"))

time.new_milli(13, 42, 11, 200)
// -> Ok(time.literal("13:42:11.200"))

time.new_milli(13, 42, 11, 7_500)
// -> Error(tempo.TimeOutOfBounds)

new_nano

</> 
pub fn new_nano(
  hour: Int,
  minute: Int,
  second: Int,
  nanosecond: Int,
) -> Result(Time, Error)

Creates a new time value with nanosecond precision.

Example

time.new_nano(13, 42, 11, 20)
// -> Ok(time.literal("13:42:11.000000020"))

time.new_nano(13, 42, 11, 200_000_000)
// -> Ok(time.literal("13:42:11.200000000"))

time.new_nano(13, 42, 11, 7_500_000_000)
// -> Error(tempo.TimeOutOfBounds)

now_local

</> 
pub fn now_local() -> Time

Gets the local time of the host.

Example

case 
  time.now_local() 
  |> time.is_later(than: time.literal("11:50:00")) 
{ 
  True -> "We are late!"
  False -> "No rush :)"
}

now_utc

</> 
pub fn now_utc() -> Time

Gets the UTC time of the host.

Example

case 
  time.now_utc() 
  |> time.is_later(than: time.literal("11:50:00")) 
{ 
  True -> "We are all late!"
  False -> "No rush :)"
}

since

</> 
pub fn since(time: Time, since: Time) -> Duration

Returns a duration representing the time since a given time.

Example

time.literal("23:54:00")
|> time.since(time.literal("13:30:04"))
|> duration.as_hours
// -> 10

time.literal("12:30:54")
|> time.since(time.literal("22:00:00"))
|> duration.as_milliseconds
// -> 0

subtract

</> 
pub fn subtract(a: Time, duration b: Duration) -> Time

Subtracts a duration from a time.

Example

time.literal("13:42:02")
|> time.subtract(duration.hours(2))
// -> time.literal("11:42:02")

to_duration

</> 
pub fn to_duration(time: Time) -> Duration

Converts a time to duration, assuming the duration epoch is “00:00:00”.

Example

time.literal("00:00:00.000000300")
|> time.to_duration
|> duration.as_nanoseconds
// -> 300

time.literal("00:03:06")
|> time.to_duration 
|> duration.as_milliseconds
// -> 186_000

to_micro_precision

</> 
pub fn to_micro_precision(time: Time) -> Time

Sets the time to a microsecond precision. Drops any nanoseconds from the underlying time value.

Example

time.literal("21:53:03.534670892")
|> time.to_micro_precision
|> time.to_string
// -> "21:53:03.534670"

to_milli_precision

</> 
pub fn to_milli_precision(time: Time) -> Time

Sets the time to a millisecond precision. Drops any microseconds from the underlying time value.

Example

time.literal("21:53:03.530673092")
|> time.to_milli_precision
|> time.to_string
// -> "21:53:03.530"

to_nano_precision

</> 
pub fn to_nano_precision(time: Time) -> Time

Sets the time to a nanosecond precision. Does not alter the underlying time value.

Example

time.literal("21:53:03.534")
|> time.to_nano_precision
|> time.to_string
// -> "21:53:03.534000000"

to_second_precision

</> 
pub fn to_second_precision(time: Time) -> Time

Sets the time to a second precision. Drops any milliseconds from the underlying time value.

Example

time.literal("21:53:30.730673092")
|> time.to_second_precision
|> time.to_string
// -> "21:53:30"

to_string

</> 
pub fn to_string(time: Time) -> String

Converts a time value to a string in the format hh:mm:ss.s

Example

time.to_string(my_time)
|> time.to_string
// -> "21:53:03.534"

to_tuple

</> 
pub fn to_tuple(time: Time) -> #(Int, Int, Int)

Returns a time value as a tuple of hours, minutes, and seconds. Useful for using with another time library.

Example

time.literal("13:42:11")
|> time.to_tuple
// -> #(13, 42, 11)

to_tuple_nanosecond

</> 
pub fn to_tuple_nanosecond(time: Time) -> #(Int, Int, Int, Int)

Returns a time value as a tuple of hours, minutes, seconds, and nanoseconds. Useful for using with another time library.

Example

time.literal("13:42:11.872")
|> time.to_tuple_nanosecond
// -> #(13, 42, 11, 872000000)

until

</> 
pub fn until(time: Time, until: Time) -> Duration

Returns a duration representing the time left until a given time.

Example

time.literal("23:54:00")
|> time.until(time.literal("23:59:04"))
|> duration.as_seconds
// -> 304

time.literal("23:59:03")
|> time.until(time.literal("22:00:00"))
|> duration.as_milliseconds
// -> 0
✨ Search Document