Module

JS.Temporal.Duration

Package: purescript-js-temporal
Repository: pete-murphy/purescript-js-temporal

A duration representing the difference between two time points. Can be used in date/time arithmetic. Represented as years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds.

Calendar durations (years, months, weeks) require a reference date for arithmetic; use PlainDate.add, PlainDate.subtract, PlainDateTime.add, or PlainDateTime.subtract for those. Non-calendar durations can be added/subtracted directly.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration

#new Source

new :: forall provided rest. Union provided rest DurationComponents => Record provided -> Effect Duration

Creates a Duration from component fields. At least one component must be provided. Mixed signs are invalid.

locale <- JS.Intl.Locale.new_ "en-US"
twoHours <- Duration.new { hours: 2 }
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log (JS.Intl.DurationFormat.format formatter twoHours)

2 hours

#from Source

from :: String -> Effect Duration

Parses an ISO 8601 duration string (e.g. "PT1H30M"). Throws on invalid input. Corresponds to Temporal.Duration.from().

locale <- JS.Intl.Locale.new_ "en-US"
duration <- Duration.from "PT2H30M"
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log (JS.Intl.DurationFormat.format formatter duration)

2 hours, 30 minutes

#years Source

years :: Duration -> Int

Year component of the duration.

#months Source

months :: Duration -> Int

Month component of the duration.

#weeks Source

weeks :: Duration -> Int

Week component of the duration.

#days Source

days :: Duration -> Int

Day component of the duration.

#hours Source

hours :: Duration -> Int

Hour component of the duration.

#minutes Source

minutes :: Duration -> Int

Minute component of the duration.

#seconds Source

seconds :: Duration -> Int

Second component of the duration.

#milliseconds Source

milliseconds :: Duration -> Int

Millisecond component of the duration.

#microseconds Source

microseconds :: Duration -> Int

Microsecond component of the duration.

#nanoseconds Source

nanoseconds :: Duration -> Int

Nanosecond component of the duration.

#sign Source

sign :: Duration -> Int

Returns 1 if positive, -1 if negative, 0 if zero.

#blank Source

blank :: Duration -> Boolean

True if all components are zero.

#add Source

add :: Duration -> Duration -> Effect Duration

Adds two durations. Result is balanced to the largest unit of the inputs. Throws if either duration contains calendar units (years, months, weeks). Corresponds to Temporal.Duration.prototype.add().

locale <- JS.Intl.Locale.new_ "en-US"
twoHours <- Duration.new { hours: 2 }
thirtyMinutes <- Duration.new { minutes: 30 }
combined <- Duration.add twoHours thirtyMinutes
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log (JS.Intl.DurationFormat.format formatter combined)

2 hours, 30 minutes

#subtract Source

subtract :: Duration -> Duration -> Effect Duration

Subtracts the second duration from the first. Same balancing/constraints as add. Corresponds to Temporal.Duration.prototype.subtract().

locale <- JS.Intl.Locale.new_ "en-US"
threeHours <- Duration.new { hours: 3 }
oneHour <- Duration.new { hours: 1 }
remainder <- Duration.subtract threeHours oneHour
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log (JS.Intl.DurationFormat.format formatter remainder)

-2 hours

#negated Source

negated :: Duration -> Duration

Reverses the sign of the duration. Pure, does not throw.

#abs Source

abs :: Duration -> Duration

Returns the duration with positive sign. Pure, does not throw.

#with Source

with :: forall provided rest. Union provided rest DurationComponents => Record provided -> Duration -> Effect Duration

Returns a new duration with specified fields replaced. Mixed signs invalid. Corresponds to Temporal.Duration.prototype.with().

locale <- JS.Intl.Locale.new_ "en-US"
duration <- Duration.new { hours: 2, minutes: 30 }
updated <- Duration.with { minutes: 45 } duration
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log (JS.Intl.DurationFormat.format formatter updated)

2 hours, 45 minutes

#compare Source

compare :: Duration -> Duration -> Effect Ordering

Compares two durations. Returns LT if first is shorter, GT if longer, EQ if equal. Throws for calendar durations without relativeTo. Corresponds to Temporal.Duration.compare().

shorter <- Duration.new { hours: 1 }
longer <- Duration.new { hours: 2 }
ordering <- Duration.compare longer shorter
Console.log ("Comparison result: " <> show ordering)

Comparison result: GT

#round Source

round :: forall provided. ConvertOptionsWithDefaults ToDurationRoundOptions (Record DurationRoundOptions) (Record provided) (Record DurationRoundOptions) => Record provided -> Duration -> Effect Duration

Rounds the duration to the given smallest/largest units. Use relativeTo for calendar durations. Corresponds to Temporal.Duration.prototype.round().

roundedSource <- Duration.new { hours: 1, minutes: 30, seconds: 45 }
rounded <- Duration.round { smallestUnit: TemporalUnit.Minute } roundedSource
Console.log (Duration.toString_ rounded)

PT1H31M

#total Source

total :: forall provided. ConvertOptionsWithDefaults ToDurationTotalOptions (Record DurationTotalOptions) (Record provided) (Record DurationTotalOptions) => Record provided -> Duration -> Effect Number

Returns the total length of the duration in the given unit. Use relativeTo for calendar durations. Corresponds to Temporal.Duration.prototype.total().

locale <- JS.Intl.Locale.new_ "en-US"
duration <- Duration.new { hours: 2, minutes: 30 }
totalHours <- Duration.total { unit: TemporalUnit.Hour } duration
numberFormatter <- JS.Intl.NumberFormat.new [ locale ] { minimumFractionDigits: 1, maximumFractionDigits: 1 }
Console.log ("Total hours: " <> JS.Intl.NumberFormat.format numberFormatter totalHours)

Total hours: 2.5

#DurationRoundOptions Source

type DurationRoundOptions :: Row Typetype DurationRoundOptions = (largestUnit :: String, relativeTo :: Foreign, roundingIncrement :: Int, roundingMode :: String, smallestUnit :: String)

Options for round: largestUnit, smallestUnit, roundingIncrement, roundingMode, relativeTo (PlainDate, PlainDateTime, or ZonedDateTime for calendar units).

#ToDurationRoundOptions Source

data ToDurationRoundOptions

Instances

ConvertOption ToDurationRoundOptions "largestUnit" TemporalUnit String
ConvertOption ToDurationRoundOptions "largestUnit" String String
ConvertOption ToDurationRoundOptions "smallestUnit" TemporalUnit String
ConvertOption ToDurationRoundOptions "smallestUnit" String String
ConvertOption ToDurationRoundOptions "roundingIncrement" Int Int
ConvertOption ToDurationRoundOptions "roundingMode" RoundingMode String
ConvertOption ToDurationRoundOptions "roundingMode" String String
ConvertOption ToDurationRoundOptions "relativeTo" Foreign Foreign
ConvertOption ToDurationRoundOptions "relativeTo" String Foreign

#DurationTotalOptions Source

type DurationTotalOptions :: Row Typetype DurationTotalOptions = (relativeTo :: Foreign, unit :: String)

Options for total: unit (required), relativeTo for calendar units.

#ToDurationTotalOptions Source

data ToDurationTotalOptions

Instances

ConvertOption ToDurationTotalOptions "unit" TemporalUnit String
ConvertOption ToDurationTotalOptions "unit" String String
ConvertOption ToDurationTotalOptions "relativeTo" Foreign Foreign
ConvertOption ToDurationTotalOptions "relativeTo" String Foreign

#DurationToStringOptions Source

type DurationToStringOptions :: Row Typetype DurationToStringOptions = (fractionalSecondDigits :: Foreign, smallestUnit :: String)

Options: fractionalSecondDigits, smallestUnit.

#ToDurationToStringOptions Source

data ToDurationToStringOptions

Instances

ConvertOption ToDurationToStringOptions "fractionalSecondDigits" Int Foreign
ConvertOption ToDurationToStringOptions "fractionalSecondDigits" String Foreign
ConvertOption ToDurationToStringOptions "smallestUnit" TemporalUnit String
ConvertOption ToDurationToStringOptions "smallestUnit" String String

#toString Source

toString :: forall provided. ConvertOptionsWithDefaults ToDurationToStringOptions (Record DurationToStringOptions) (Record provided) (Record DurationToStringOptions) => Record provided -> Duration -> String

Serializes the duration to ISO 8601 format (e.g. "PT1H30M").

duration <- Duration.new { hours: 2, minutes: 30, seconds: 15, milliseconds: 400 }
Console.log (Duration.toString { smallestUnit: TemporalUnit.Second } duration)

PT2H30M15S

#toString_ Source

toString_ :: Duration -> String

Same as toString with default options.

#fromMilliseconds Source

fromMilliseconds :: Milliseconds -> Effect Duration

Creates a Temporal Duration from purescript-datetime Milliseconds. See ./docs/purescript-datetime-interop.md.

#toMilliseconds Source

toMilliseconds :: Duration -> Maybe Milliseconds

Converts a Temporal Duration to purescript-datetime Milliseconds. Returns Nothing if the duration contains calendar units (years, months, weeks). Microseconds and nanoseconds are dropped. See ./docs/purescript-datetime-interop.md.

Re-exports from JS.Temporal.Duration.Internal

#Duration Source

data Duration

A Temporal duration (opaque type).