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

#from Source

from :: 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.

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

2 hours

#fromString Source

fromString :: String -> Effect Duration

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

exampleFromString :: Effect Unit
exampleFromString = do
  locale <- JS.Intl.Locale.new_ "en-US"
  duration <- Duration.fromString "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.

exampleYears :: Effect Unit
exampleYears = do
  duration <- Duration.from { years: 3, months: 6 }
  Console.log ("Years: " <> show (Duration.years duration))

Years: 3

#months Source

months :: Duration -> Int

Month component of the duration.

exampleMonths :: Effect Unit
exampleMonths = do
  duration <- Duration.from { years: 3, months: 6 }
  Console.log ("Months: " <> show (Duration.months duration))

Months: 6

#weeks Source

weeks :: Duration -> Int

Week component of the duration.

exampleWeeks :: Effect Unit
exampleWeeks = do
  duration <- Duration.from { weeks: 2 }
  Console.log ("Weeks: " <> show (Duration.weeks duration))

Weeks: 2

#days Source

days :: Duration -> Int

Day component of the duration.

exampleDays :: Effect Unit
exampleDays = do
  duration <- Duration.from { days: 10 }
  Console.log ("Days: " <> show (Duration.days duration))

Days: 10

#hours Source

hours :: Duration -> Int

Hour component of the duration.

exampleHours :: Effect Unit
exampleHours = do
  duration <- Duration.from { hours: 5 }
  Console.log ("Hours: " <> show (Duration.hours duration))

Hours: 5

#minutes Source

minutes :: Duration -> Int

Minute component of the duration.

exampleMinutes :: Effect Unit
exampleMinutes = do
  duration <- Duration.from { minutes: 45 }
  Console.log ("Minutes: " <> show (Duration.minutes duration))

Minutes: 45

#seconds Source

seconds :: Duration -> Int

Second component of the duration.

exampleSeconds :: Effect Unit
exampleSeconds = do
  duration <- Duration.from { seconds: 30 }
  Console.log ("Seconds: " <> show (Duration.seconds duration))

Seconds: 30

#milliseconds Source

milliseconds :: Duration -> Int

Millisecond component of the duration.

exampleMilliseconds :: Effect Unit
exampleMilliseconds = do
  duration <- Duration.from { milliseconds: 500 }
  Console.log ("Milliseconds: " <> show (Duration.milliseconds duration))

Milliseconds: 500

#microseconds Source

microseconds :: Duration -> Int

Microsecond component of the duration.

exampleMicroseconds :: Effect Unit
exampleMicroseconds = do
  duration <- Duration.from { microseconds: 250 }
  Console.log ("Microseconds: " <> show (Duration.microseconds duration))

Microseconds: 250

#nanoseconds Source

nanoseconds :: Duration -> Int

Nanosecond component of the duration.

exampleNanoseconds :: Effect Unit
exampleNanoseconds = do
  duration <- Duration.from { nanoseconds: 100 }
  Console.log ("Nanoseconds: " <> show (Duration.nanoseconds duration))

Nanoseconds: 100

#sign Source

sign :: Duration -> Int

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

exampleSign :: Effect Unit
exampleSign = do
  positive <- Duration.from { hours: 2 }
  Console.log ("Sign of 2h: " <> show (Duration.sign positive))
  negated <- pure (Duration.negated positive)
  Console.log ("Sign of -2h: " <> show (Duration.sign negated))

Sign of 2h: 1
Sign of -2h: -1

#blank Source

blank :: Duration -> Boolean

True if all components are zero.

exampleBlank :: Effect Unit
exampleBlank = do
  zero <- Duration.from { hours: 0 }
  nonZero <- Duration.from { hours: 1 }
  Console.log ("Zero is blank: " <> show (Duration.blank zero))
  Console.log ("1h is blank: " <> show (Duration.blank nonZero))

Zero is blank: true
1h is blank: false

#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().

exampleAdd :: Effect Unit
exampleAdd = do
  locale <- JS.Intl.Locale.new_ "en-US"
  twoHours <- Duration.from { hours: 2 }
  thirtyMinutes <- Duration.from { 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().

exampleSubtract :: Effect Unit
exampleSubtract = do
  locale <- JS.Intl.Locale.new_ "en-US"
  threeHours <- Duration.from { hours: 3 }
  oneHour <- Duration.from { 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.

exampleNegated :: Effect Unit
exampleNegated = do
  locale <- JS.Intl.Locale.new_ "en-US"
  duration <- Duration.from { hours: 2, minutes: 30 }
  let neg = Duration.negated duration
  formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
  Console.log (JS.Intl.DurationFormat.format formatter neg)

-2 hours, 30 minutes

#abs Source

abs :: Duration -> Duration

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

exampleAbs :: Effect Unit
exampleAbs = do
  locale <- JS.Intl.Locale.new_ "en-US"
  duration <- Duration.from { hours: 2 }
  let neg = Duration.negated duration
  let positive = Duration.abs neg
  formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
  Console.log (JS.Intl.DurationFormat.format formatter positive)

2 hours

#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().

exampleWith :: Effect Unit
exampleWith = do
  locale <- JS.Intl.Locale.new_ "en-US"
  duration <- Duration.from { 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().

exampleCompare :: Effect Unit
exampleCompare = do
  shorter <- Duration.from { hours: 1 }
  longer <- Duration.from { 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().

exampleRound :: Effect Unit
exampleRound = do
  roundedSource <- Duration.from { hours: 1, minutes: 30, seconds: 45 }
  rounded <- Duration.round { largestUnit: TemporalUnit.Hour, smallestUnit: TemporalUnit.Second } roundedSource
  Console.log (Duration.toString rounded)

PT1H30M45S

#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().

exampleTotal :: Effect Unit
exampleTotal = do
  locale <- JS.Intl.Locale.new_ "en-US"
  duration <- Duration.from { 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 :: Duration -> String

Same as toStringWithOptions with default options.

exampleToString :: Effect Unit
exampleToString = do
  duration <- Duration.from { hours: 2, minutes: 30, seconds: 15, milliseconds: 400 }
  Console.log (Duration.toString duration)

PT2H30M15.4S

#toStringWithOptions Source

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

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

exampleToStringWithOptions :: Effect Unit
exampleToStringWithOptions = do
  duration <- Duration.from { hours: 2, minutes: 30, seconds: 15, milliseconds: 400 }
  Console.log (Duration.toStringWithOptions { smallestUnit: TemporalUnit.Second } duration)

PT2H30M15S

#fromMilliseconds Source

fromMilliseconds :: Milliseconds -> Effect Duration

Creates a Temporal Duration from purescript-datetime Milliseconds.

exampleFromMilliseconds :: Effect Unit
exampleFromMilliseconds = do
  duration <- Duration.fromMilliseconds (Milliseconds 5000.0)
  Console.log (Duration.toString duration)

PT5S

#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.

exampleToMilliseconds :: Effect Unit
exampleToMilliseconds = do
  duration <- Duration.from { seconds: 5 }
  case Duration.toMilliseconds duration of
    Just (Milliseconds ms) -> Console.log ("Milliseconds: " <> show ms)
    Nothing -> Console.log "Cannot convert (has calendar units)"

Milliseconds: 5000.0

Re-exports from JS.Temporal.Duration.Internal

#Duration Source

data Duration

A Temporal duration (opaque type).