tempo/duration

Functions to use with the Duration type in Tempo.

Example

import gleam/io
import tempo/duration
import tempo/time

pub fn main() {
  time.literal("01:42:11")
  |> duration.format
  // -> "1 hour, 42 minutes, 11 seconds"
}
import tempo/duration

pub fn timed(func) {
  let start = duration.start_monotonic()
  func() 
  io.println("This took " <> duration.since(start) <> " to run!")
}

Types

pub opaque type MonotonicClock
pub type Unit {
  YearImprecise
  Week
  Day
  Hour
  Minute
  Second
  Millisecond
  Microsecond
  Nanosecond
}

Constructors

  • YearImprecise
  • Week
  • Day
  • Hour
  • Minute
  • Second
  • Millisecond
  • Microsecond
  • Nanosecond

Functions

pub fn absolute(duration: Duration) -> Duration

Returns the absolute value of a duration.

Example

duration.days(1)
|> duration.decrease(by: duration.days(6))
|> duration.abosulte
|> duration.format_as(duration.Day, decimals: 0)
// -> "5 days"
pub fn as_days(duration: Duration) -> Int

Converts a duration to the equivalent number of whole days.

pub fn as_days_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional days.

pub fn as_hours(duration: Duration) -> Int

Converts a duration to the equivalent number of whole hours.

pub fn as_hours_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional hours.

pub fn as_microseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole microseconds.

pub fn as_microseconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional microseconds.

pub fn as_milliseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole milliseconds.

pub fn as_milliseconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional milliseconds.

pub fn as_minutes(duration: Duration) -> Int

Converts a duration to the equivalent number of whole minutes.

pub fn as_minutes_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional minutes.

pub fn as_nanoseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole nanoseconds.

pub fn as_nanoseconds_fractional(duration: Duration) -> Float

Converts a duration to a floating point representation of nanoseconds. Nanoseconds are the smallest unit of time that are used in this package.

pub fn as_seconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole seconds.

pub fn as_seconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional seconds.

pub fn as_unit(duration: Duration, unit: Unit) -> Int

Converts a duration to the specified whole units.

Example

duration.minutes(1)
|> duration.as_unit(duration.Second)
// -> 60
pub fn as_unit_fractional(
  duration: Duration,
  unit: Unit,
) -> Float

Converts a duration to the specified fractional units.

Example

duration.days(8)
|> duration.as_unit_fractional(duration.Week)
// -> 1.142857143
pub fn as_weeks(duration: Duration) -> Int

Converts a duration to the equivalent number of whole weeks.

pub fn as_weeks_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional weeks.

pub fn as_years_fractional_imprecise(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional years, assuming a year is 365 days.

Example

duration.days(375)
|> duration.as_years_fractional_imprecise
// -> 1.02739726
pub fn as_years_imprecise(duration: Duration) -> Int

Converts a duration to the equivalent number of whole years, assuming a year is 365 days.

Example

duration.days(375)
|> duration.as_years_imprecise
// -> 1
pub fn compare(a: Duration, to b: Duration) -> Order

Compares two durations.

Example

duration.days(1)
|> duration.compare(to: duration.days(1))
// -> order.Eq
duration.days(1)
|> duration.compare(to: duration.days(2))
// -> order.Lt
pub fn days(days: Int) -> Duration

Creates a new duration value of the specified number of whole days.

Example

duration.days(3)
|> duration.format_as(duration.Hour, decimals: 0)
// -> "36 hours"
pub fn decrease(a: Duration, by b: Duration) -> Duration

Decreases a duration by the specified duration. If a negative value is passed, the duration will be increased.

Example

duration.days(1)
|> duration.decrease(by: duration.days(6))
|> duration.format_as(duration.Day, decimals: 0)
// -> "-5 days"
duration.days(1)
|> duration.decrease(by: duration.days(6))
|> duration.abosulte
|> duration.format_as(duration.Day, decimals: 0)
// -> "5 days"
pub fn format(duration: Duration) -> String

Formats the duration as a string, inferring the units to use.

Example

duration |> tempo.duration_get_ns(172_980_000_000_000)
|> duration.format
// -> "2 days, 0 hours, and 3 minutes"
duration.seconds(691_332_000_000)
|> duration.format
// -> "1 week, 1 day, 0 hours, and 2 minutes"
pub fn format_as(
  duration: Duration,
  unit unit: Unit,
  decimals decimals: Int,
) -> String

Formats the duration as the specified unit with the specified number of decimals.

Example

duration.minutes(1)
|> duration.format_as(duration.Second, decimals: 3)
// -> "60.000 minutes"
pub fn format_as_many(
  duration: Duration,
  units units: List(Unit),
  decimals decimals: Int,
) -> String

Formats the duration as the specified units, with the last unit having the specified number of decimals.

Example

duration.milliseconds(100_303)
|> duration.format_as_many(
  [duration.Minute, duration.Second],
  decimals: 2,
)
// -> "1 minute and 40.30 seconds"
pub fn hours(hours: Int) -> Duration

Creates a new duration value of the specified number of whole hours.

Example

duration.hours(13)
|> duration.format
// -> "13 hours, 0 minutes, 0.0 seconds"
pub fn increase(a: Duration, by b: Duration) -> Duration

Increases a duration by the specified duration. If a negative value is passed, the duration will be decreased.

Example

duration.days(1)
|> duration.increase(by: duration.days(6))
|> duration.format_as(duration.Day, decimals: 0)
// -> "7 days"
pub fn inverse(duration: Duration) -> Duration

Returns the inverse of a duration.

Example

duration.days(1)
|> duration.inverse
|> duration.format_as(duration.Day, decimals: 0)
// -> "-1 days"
pub fn is_equal(a: Duration, to b: Duration) -> Bool

Checks if a duration is equal to another duration.

Example

duration.weeks(1)
|> duration.is_equal(to: duration.days(7))
// -> True
duration.days(1)
|> duration.is_equal(to: duration.days(2))
// -> False
pub fn is_greater(a: Duration, than b: Duration) -> Bool

Checks if a duration is greater than another duration.

Example

duration.days(1)
|> duration.is_greater(than: duration.days(2))
// -> False
duration.weeks(1)
|> duration.is_greater(than: duration.days(1))
// -> True
pub fn is_greater_or_equal(a: Duration, to b: Duration) -> Bool

Checks if a duration is greater than or equal to another duration.

Example

duration.days(1)
|> duration.is_greater_or_equal(to: duration.days(2))
// -> False
duration.seconds(60)
|> duration.is_greater_or_equal(to: duration.minutes(1))
// -> True
pub fn is_less(a: Duration, than b: Duration) -> Bool

Checks if a duration is less than another duration.

Example

duration.days(1)
|> duration.is_less(than: duration.hours(25))
// -> True
duration.days(1)
|> duration.is_less(than: duration.days(1))
// -> False
pub fn is_less_or_equal(a: Duration, to b: Duration) -> Bool

Checks if a duration is less than or equal to another duration.

Example

duration.days(1)
|> duration.is_less_or_equal(to: duration.days(2))
// -> True
duration.days(1)
|> duration.is_less_or_equal(to: duration.days(1))
// -> True
pub fn is_negative(duration: Duration) -> Bool

Checks if a duration is negative.

Example

duration.days(1)
|> duration.is_negative
// -> False
case 
  time.literal("13:42:05")
  |> time.difference(from: time.literal("13:42:10"))
  |> duration.is_negative
{
  True -> "we are ahead of time!"
  False -> "We are either on time or late!"
}
pub fn microseconds(microseconds: Int) -> Duration

Creates a new duration value of the specified number of whole microseconds.

Example

duration.milliseconds(1)
|> duration.increase(by: duration.microseconds(13))
|> duration.format_as(duration.Microsecond, decimals: 0)
// -> "113 microseconds"
pub fn milliseconds(milliseconds: Int) -> Duration

Creates a new duration value of the specified number of whole milliseconds.

Example

duration.seconds(1)
|> duration.increase(by: duration.milliseconds(13))
|> duration.format_as(duration.Millisecond, decimals: 0)
// -> "113 milliseconds"
pub fn minutes(minutes: Int) -> Duration

Creates a new duration value of the specified number of whole minutes.

Example

duration.minutes(13)
|> duration.format
// -> "13 minutes and 0.0 seconds"
pub fn nanoseconds(nanoseconds: Int) -> Duration

Creates a new duration value of the specified number of whole nanoseconds.

Example

duration.microseconds(1)
|> duration.increase(by: duration |> tempo.duration_get_ns(13))
|> duration.format_as(duration.Nanosecond, decimals: 0)
// -> "113 nanoseconds"
pub fn new(duration: Int, unit: Unit) -> Duration

Creates a new duration from the value and unit provided.

Example

duration.new(100, duration.Millisecond)
|> duration.as_seconds_fractional
// -> 0.0000001
pub fn seconds(seconds: Int) -> Duration

Creates a new duration value of the specified number of whole seconds.

Example

duration.minutes(1)
|> duration.increase(by: duration.seconds(13))
|> duration.format_as(duration.Second, decimals: 0)
// -> "73 seconds"
pub fn since(start: MonotonicClock) -> String

Returns the formatted duration between the monotonic clock start and the current time.

Example

duration.start()
|> fn(timer) { 
  "This operation took "
  <> duration.since(timer)
  <> "!" 
}
// -> "This operation took 263 nanoseconds!"
pub fn start_monotonic() -> MonotonicClock

Starts a new monotonic clock.

Example

duration.start()
|> function.tap(fn(_) { long_function() })
|> duration.stop
// -> duration.mintues(15)
pub fn stop_monotonic(start: MonotonicClock) -> Duration

Returns the duration between the monotonic clock start and the current time.

Example

duration.start()
|> function.tap(fn(_) { long_function() })
|> duration.stop
// -> duration.mintues(15)
pub fn weeks(weeks: Int) -> Duration

Creates a new duration value of the specified number of whole weeks.

Example

duration.weeks(3)
|> duration.format
// -> "3 weeks"
pub fn years_imprecise(years: Int) -> Duration

Creates a new duration value of the specified number of whole years, assuming a year is 365 days.

Example

duration.years_imprecise(1)
|> duration.format
// -> "1 ~year"
Search Document