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

MonotonicClock

opaque </>

pub opaque type MonotonicClock

Unit

</>

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

Constructors

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

Functions

absolute

</>

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"

as_days

</>

pub fn as_days(duration: Duration) -> Int

Converts a duration to the equivalent number of whole days.

as_days_fractional

</>

pub fn as_days_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional days.

as_hours

</>

pub fn as_hours(duration: Duration) -> Int

Converts a duration to the equivalent number of whole hours.

as_hours_fractional

</>

pub fn as_hours_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional hours.

as_microseconds

</>

pub fn as_microseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole microseconds.

as_microseconds_fractional

</>

pub fn as_microseconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional microseconds.

as_milliseconds

</>

pub fn as_milliseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole milliseconds.

as_milliseconds_fractional

</>

pub fn as_milliseconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional milliseconds.

as_minutes

</>

pub fn as_minutes(duration: Duration) -> Int

Converts a duration to the equivalent number of whole minutes.

as_minutes_fractional

</>

pub fn as_minutes_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional minutes.

as_nanoseconds

</>

pub fn as_nanoseconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole nanoseconds.

as_nanoseconds_fractional

</>

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.

as_seconds

</>

pub fn as_seconds(duration: Duration) -> Int

Converts a duration to the equivalent number of whole seconds.

as_seconds_fractional

</>

pub fn as_seconds_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional seconds.

as_unit

</>

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

as_unit_fractional

</>

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

as_weeks

</>

pub fn as_weeks(duration: Duration) -> Int

Converts a duration to the equivalent number of whole weeks.

as_weeks_fractional

</>

pub fn as_weeks_fractional(duration: Duration) -> Float

Converts a duration to the equivalent number of fractional weeks.

as_years_fractional_imprecise

</>

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

as_years_imprecise

</>

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

compare

</>

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

days

</>

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"

decrease

</>

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"

format

</>

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"

format_as

</>

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"

format_as_many

</>

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"

hours

</>

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"

increase

</>

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"

inverse

</>

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"

is_equal

</>

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

is_greater

</>

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

is_greater_or_equal

</>

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

is_less

</>

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

is_less_or_equal

</>

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

is_negative

</>

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!"
}

microseconds

</>

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"

milliseconds

</>

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"

minutes

</>

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"

nanoseconds

</>

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"

new

</>

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

seconds

</>

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"

since

</>

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!"

start_monotonic

</>

pub fn start_monotonic() -> MonotonicClock

Starts a new monotonic clock.

Example

duration.start()
|> function.tap(fn(_) { long_function() })
|> duration.stop
// -> duration.mintues(15)

stop_monotonic

</>

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)

weeks

</>

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"

years_imprecise

</>

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"