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")
  |> time.since(time.literal("00:00:01"))
  |> duration.format
  // -> "1 hour, 42 minutes, 10 seconds"
}

Calendar

Durations are a fixed number of microseconds and carry no calendar context, so no function in this module depends on the Gregorian calendar or on any other. There is no range of valid dates because a duration is not tied to a point in time.

The consequence is that the units larger than a day are fixed lengths rather than calendar ones, which is what the imprecise in their names refers to:

Unit	Length
`Day`	24 hours
`Week`	7 days
`YearImprecise`	364 days, that is 52 weeks

A Gregorian calendar year is 365 or 366 days, so converting a duration to years will not agree with calendar arithmetic. A Day is likewise always 24 hours, which is not true of a calendar day in a time zone that observes daylight saving time. When you need the calendar-accurate answer, work from dates with tempo/date or tempo/period instead.

Types

Unit

</>

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

Constructors

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

Values

absolute

</>

pub fn absolute(duration: duration.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.Duration) -> Int

Converts a duration to the equivalent number of whole days.

as_days_fractional

</>

pub fn as_days_fractional(duration: duration.Duration) -> Float

Converts a duration to the equivalent number of fractional days.

as_hours

</>

pub fn as_hours(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole hours.

as_hours_fractional

</>

pub fn as_hours_fractional(duration: duration.Duration) -> Float

Converts a duration to the equivalent number of fractional hours.

as_microseconds

</>

pub fn as_microseconds(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole microseconds.

as_microseconds_fractional

</>

pub fn as_microseconds_fractional(
  duration: duration.Duration,
) -> Float

Converts a duration to the equivalent number of fractional microseconds. Microseconds are the smallest unit of time that are used in this package.

as_milliseconds

</>

pub fn as_milliseconds(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole milliseconds.

as_milliseconds_fractional

</>

pub fn as_milliseconds_fractional(
  duration: duration.Duration,
) -> Float

Converts a duration to the equivalent number of fractional milliseconds.

as_minutes

</>

pub fn as_minutes(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole minutes.

as_minutes_fractional

</>

pub fn as_minutes_fractional(
  duration: duration.Duration,
) -> Float

Converts a duration to the equivalent number of fractional minutes.

as_seconds

</>

pub fn as_seconds(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole seconds.

as_seconds_fractional

</>

pub fn as_seconds_fractional(
  duration: duration.Duration,
) -> Float

Converts a duration to the equivalent number of fractional seconds.

as_unit

</>

pub fn as_unit(duration: 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.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.Duration) -> Int

Converts a duration to the equivalent number of whole weeks.

as_weeks_fractional

</>

pub fn as_weeks_fractional(duration: 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.Duration,
) -> Float

Converts a duration to the equivalent number of fractional years, assuming a year is exactly 364 days (52 weeks), not a Gregorian calendar year.

Example

duration.days(375)
|> duration.as_years_fractional_imprecise
// -> 1.0302197802197801

as_years_imprecise

</>

pub fn as_years_imprecise(duration: duration.Duration) -> Int

Converts a duration to the equivalent number of whole years, assuming a year is exactly 364 days (52 weeks), not a Gregorian calendar year.

Example

duration.days(375)
|> duration.as_years_imprecise
// -> 1

compare

</>

pub fn compare(
  a: duration.Duration,
  to b: duration.Duration,
) -> order.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.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.Duration,
  by b: duration.Duration,
) -> 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.Duration) -> String

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

Example

duration.microseconds(172_980_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.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.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.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.Duration,
  by b: duration.Duration,
) -> 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) -> 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.Duration,
  to b: duration.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.Duration,
  than b: duration.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.Duration,
  to b: duration.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.Duration,
  than b: duration.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.Duration,
  to b: duration.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.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.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.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.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"

new

</>

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

Creates a new duration from the value and unit provided.

Example

duration.new(100, duration.Millisecond)
|> duration.as_seconds_fractional
// -> 0.1

seconds

</>

pub fn seconds(seconds: Int) -> duration.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"

weeks

</>

pub fn weeks(weeks: Int) -> duration.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.Duration

Creates a new duration value of the specified number of whole years, assuming a year is exactly 364 days (52 weeks).

This is deliberately not a calendar year. Durations here are a fixed number of microseconds and carry no calendar context, so they cannot know whether a given Gregorian year is 365 or 366 days long. Use tempo/period or add days to a date if you need calendar-accurate year arithmetic.

Example

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