# Duration¶

The following functions operate on the built-in type Duration for durations.

## Duration::betweenInstants : Instant -> Instant -> Duration¶

The function Duration::betweenInstants returns a Duration which is the absolute amount of time from the first to the second argument. The result is a negative duration if the first argument comes after the second.

### Examples¶

val a = Duration::betweenInstants #2018-02-01# #2018-03-01#
//    = #PT672H#
val b = Duration::betweenInstants #2018-02-01# #2018-01-01#
//    = #-PT744H#


## Duration::betweenTimes : Time -> Time -> Duration¶

The function Duration::betweenTimes returns a Duration which is the absolute amount of time from the first to the second argument. The result is a negative duration if the first argument comes after the second.

### Examples¶

val a = Duration::betweenTimes (Time::from 13 0 0 0) (Time::from 17 30 15 355)
//    = #PT4H30M15.355S#
val b = Duration::betweenTimes (Time::from 17 30 15 355) (Time::from 13 0 0 0)
//    = #-PT4H30M15.355S#


## Duration::add : Duration -> Duration -> Duration¶

The function Duration::add adds two durations together. The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

### Examples¶

val a = Duration::add #PT1H2M3S# #PT60S#
//    = #PT1H3M3S#


## Duration::negate : Duration -> Duration -> Duration¶

The function Duration::negated negates a Duration. The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

### Examples¶

val a = Duration::negated #P1DT2S#
//    = #-PT24H2S#


## Duration::components : Duration -> Duration::Components¶

The function Duration::components returns a value of the type Duration::Components which represents the given duration as the number of whole seconds (positive or negative) plus a number of milliseconds. Note that the millisecond adjustment is always in the range [0 .. 999], also for negative durations. A duration of -1.5 seconds is thus represented as -2 seconds plus an adjustment of 500 milliseconds.

### Examples¶

val a = Duration::components #P1DT2H62M3.333S#
//    = Duration::Components {
//        milliseconds = 333,
//        seconds = 97323
//      }

val a = Duration::components #-PT1.5S#
//    = Duration::Components {
//        milliseconds = 500,
//        seconds = -2
//      }


## Duration::fromComponents : Duration::Components -> Duration¶

The function Duration::fromComponents constructs a Duration from a number of seconds and a milliseconds adjustment. There are no range constraints on the components, specifically the millisecond adjustment is allowed to be outside the range [0 .. 999]. The components are normalized internally to bring the millisecond adjustment into the normal range.

The function is partial and fails if the normalization of the millisecond adjustment causes the number of seconds to overflow.

### Examples¶

val a = Duration::fromComponents Duration::Components { milliseconds = 500, seconds = -2 }
//    = #-PT1.5S#

// Tip: Construction of negative durations using negative millisecond adjustments is sometimes more intuitive.
val a = Duration::fromComponents Duration::Components { milliseconds = -500, seconds = -1 }
//    = #-PT1.5S#


## Duration::from : Int -> Int -> Duration¶

The function Duration::from is a convenience wrapper of Duration::fromComponents which takes the individual components as positional arguments. The order of arguments is

1. seconds

The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

val a = Duration::from 3625 456
//    = #PT1H25.456S#


## Duration::fromMinutes : Int -> Duration¶

The function Duration::fromMinutes creates a Duration from an Int representing whole minutes.

The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

### Examples¶

val a = Duration::fromMinutes 62
//    = #PT1H2M#


## Duration::fromHours : Int -> Duration¶

The function Duration::fromHours creates a Duration from an Int reoresenting whole hours.

The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

### Examples¶

val a = Duration::fromHours 4
//    = #PT4H#


## Duration::fromDays : Float -> Duration¶

The function Duration::fromDays creates a Duration from an Int representing whole days.

The function is partial and fails if the components of the result cannot be represented; see Duration::fromComponents.

### Examples¶

val a = Duration::fromDays 2
//    = #PT48H#