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 "-" (the smallest Int included: its magnitude is formatted without negating it).

Types

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

Functions

fnaddadd(a, b)#

Add two durations.

march> Duration.add(Duration.seconds(30), Duration.seconds(30))  -- 1 minute
Duration(60000)

fncomparecompare(a, b)#

Compare two durations.

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

march> Duration.compare(Duration.seconds(10), Duration.minutes(1))
-1
march> Duration.compare(Duration.hours(1), Duration.hours(1))
0
march> 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, n * 86400000 milliseconds).

Examples

march> Duration.format(Duration.days(3))
"3 days"

fnformatformat(d)#

Format a Duration as a human-readable string.

march> Duration.format(Duration.seconds(90))
"1 minute, 30 seconds"
march> Duration.format(Duration.hours(2))
"2 hours"
march> Duration.format(Duration.milliseconds(500))
"500 milliseconds"
march> Duration.format(Duration.new(0, :ms))
"0 milliseconds"
march> 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. A negative duration is - followed by its magnitude; this holds for every Int, the smallest included.

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

Create a Duration of n hours (stored as n * 3600000 milliseconds).

Examples

march> Duration.to_milliseconds(Duration.hours(1))
3600000

fnmillisecondsmilliseconds(n) do Duration(n) end#

Create a Duration of n milliseconds. n may be negative.

Examples

march> Duration.milliseconds(1500)
Duration(1500)
march> Duration.format(Duration.milliseconds(-250))
"-250 milliseconds"

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

Create a Duration of n minutes (stored as n * 60000 milliseconds).

Examples

march> Duration.minutes(90) == Duration.add(Duration.hours(1), Duration.minutes(30))
true

fnmultiplymultiply(d, factor)#

Multiply a duration by an integer factor.

march> Duration.multiply(Duration.seconds(10), 6)
Duration(60000)
march> Duration.multiply(Duration.hours(1), 24) == Duration.days(1)
true

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). Any other atom is a match failure at runtime.

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

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

Create a Duration of n seconds (stored as n * 1000 milliseconds).

Examples

march> Duration.seconds(2)
Duration(2000)
march> Duration.seconds(-1)
Duration(-1000)

fnsubtractsubtract(a, b)#

Subtract duration b from duration a.

march> Duration.subtract(Duration.hours(2), Duration.minutes(30))  -- 1 hour 30 minutes
Duration(5400000)

fnto_millisecondsto_milliseconds(d)#

Return the duration as a whole number of milliseconds.

march> Duration.to_milliseconds(Duration.seconds(2))
2000
march> Duration.to_milliseconds(Duration.minutes(1))
60000

fnto_secondsto_seconds(d)#

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

march> Duration.to_seconds(Duration.milliseconds(1500))
1.5
march> Duration.to_seconds(Duration.minutes(1)) == 60.0
true

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

Create a Duration of n weeks (7 days each, n * 604800000 milliseconds).

Examples

march> Duration.weeks(1) == Duration.days(7)
true