Duration

Duration module: time span representation and arithmetic.

Duration is stored internally as a whole number of milliseconds (Int). This makes arithmetic exact and interoperable with timestamps.

Construction helpers: Duration.milliseconds(n) Duration.seconds(n) Duration.minutes(n) Duration.hours(n) Duration.days(n) Duration.weeks(n)

Or use Duration.new/2 with a unit atom: :ms :s :m :h :d :w

Negative durations are supported (e.g. for countdown timers). Duration.format/1 handles negatives by prepending "-".

Types

typeDurationDuration = Duration(Int) -- internal: milliseconds#

Functions

fnaddadd(a, b)#

Add two durations.

    Duration.add(Duration.seconds(30), Duration.seconds(30))
    -- Duration(60000)  i.e. 1 minute

fncomparecompare(a, b)#

Compare two durations.

Returns -1 if a < b, 0 if a == b, 1 if a > b.

    Duration.compare(Duration.seconds(10), Duration.minutes(1))  -- -1
    Duration.compare(Duration.hours(1), Duration.hours(1))       -- 0
    Duration.compare(Duration.days(1), Duration.hours(12))       -- 1

fndaysdays(n) do Duration(n * 86400000) end#

Create a Duration of n days (24-hour days).

fnformatformat(d)#

Format a Duration as a human-readable string.

    Duration.format(Duration.seconds(90))          -- "1 minute, 30 seconds"
    Duration.format(Duration.hours(2))             -- "2 hours"
    Duration.format(Duration.milliseconds(500))    -- "500 milliseconds"
    Duration.format(Duration.new(0, :ms))          -- "0 milliseconds"
    Duration.format(Duration.seconds(-70))         -- "-1 minute, 10 seconds"

Units shown (from largest to smallest): weeks, days, hours, minutes,
seconds, milliseconds.  Zero-valued units are omitted.  Singular forms
are used when the count is 1.

fnhourshours(n) do Duration(n * 3600000) end#

Create a Duration of n hours.

fnmillisecondsmilliseconds(n) do Duration(n) end#

Create a Duration of n milliseconds.

fnminutesminutes(n) do Duration(n * 60000) end#

Create a Duration of n minutes.

fnmultiplymultiply(d, factor)#

Multiply a duration by an integer factor.

    Duration.multiply(Duration.seconds(10), 6)  -- Duration(60000)
    Duration.multiply(Duration.hours(1), 24)    -- Duration for 1 day

fnnewnew(amount, unit)#

Create a Duration from an amount and a unit atom.

Supported units: `:ms` (milliseconds), `:s` (seconds), `:m` (minutes),
`:h` (hours), `:d` (days), `:w` (weeks).

    Duration.new(30, :s)   -- 30 seconds
    Duration.new(2, :h)    -- 2 hours
    Duration.new(500, :ms) -- 500 milliseconds

fnsecondsseconds(n) do Duration(n * 1000) end#

Create a Duration of n seconds.

fnsubtractsubtract(a, b)#

Subtract duration b from duration a.

    Duration.subtract(Duration.hours(2), Duration.minutes(30))
    -- Duration(5400000)  i.e. 1 hour 30 minutes

fnto_millisecondsto_milliseconds(d)#

Return the duration as a whole number of milliseconds.

    Duration.to_milliseconds(Duration.seconds(2))  -- 2000
    Duration.to_milliseconds(Duration.minutes(1))  -- 60000

fnto_secondsto_seconds(d)#

Return the duration as a floating-point number of seconds.

    Duration.to_seconds(Duration.milliseconds(1500))  -- 1.5
    Duration.to_seconds(Duration.minutes(1))          -- 60.

fnweeksweeks(n) do Duration(n * 604800000) end#

Create a Duration of n weeks (7 days each).