Rename duration to diff for Instant (#100)

* Rename `duration` to `diff` for `Instant`

* Update CHANGELOG.md

CHANGELOG.md

@@ -12,6 +12,17 @@ Bugfixes:
 
 Other improvements:
 
+## [v6.1.0](https://github.com/purescript/purescript-datetime/releases/tag/v6.1.0) - 2022-07-13
+
+Breaking changes:
+
+New features:
+- Added `diff` for `Instant` (#99 by @i-am-the-slime, #100 by @garyb)
+
+Bugfixes:
+
+Other improvements:
+
 ## [v6.0.0](https://github.com/purescript/purescript-datetime/releases/tag/v6.0.0) - 2022-04-27
 
 Breaking changes:

src/Data/DateTime/Instant.purs

@@ -1,12 +1,11 @@
 module Data.DateTime.Instant
-  ( duration
-  , durationMillis
-  , Instant
+  ( Instant
   , instant
   , unInstant
   , fromDateTime
   , fromDate
   , toDateTime
+  , diff
   ) where
 
 import Prelude
@@ -76,31 +75,17 @@ toDateTime = toDateTimeImpl mkDateTime
 foreign import fromDateTimeImpl :: Fn7 Year Int Day Hour Minute Second Millisecond Instant
 foreign import toDateTimeImpl :: (Year -> Int -> Day -> Hour -> Minute -> Second -> Millisecond -> DateTime) -> Instant -> DateTime
 
--- | Get the amount of milliseconds between start and end
--- | for example:
+-- | Calculates the difference between two instants, returning the result as a duration.
+-- | For example:
 -- | ```
 -- | do
--- |   start <- Instant.now
--- |   aLongRunningEffect
--- |   end <- Instant.now
--- |   let millis = duration end start
--- |   log ("A long running effect took " <> show millis)
--- | ```
-durationMillis :: { start :: Instant, end :: Instant } → Milliseconds
-durationMillis { start, end } =
-  unInstant end <> negateDuration (unInstant start)
-
--- | Get the duration between start and end
--- | for example:
--- | ```
--- | do
--- |   start <- Instant.now # liftEffect
+-- |   start <- liftEffect Now.now
 -- |   aLongRunningAff
--- |   end <- Instant.now # liftEffect
+-- |   end <- liftEffect Now.now
 -- |   let
--- |     hours :: Hours
--- |     hours = duration end start
+-- |     hours :: Duration.Hours
+-- |     hours = Instant.diff end start
 -- |   log ("A long running Aff took " <> show hours)
 -- | ```
-duration :: forall d. Duration d => { start :: Instant, end :: Instant } → d
-duration = durationMillis >>> toDuration
+diff :: forall d. Duration d => Instant → Instant → d
+diff dt1 dt2 = toDuration (unInstant dt1 <> negateDuration (unInstant dt2))

test/Test/Main.purs

@@ -163,11 +163,16 @@ main = do
   assert $ DateTime.diff dt5 dt3 == Duration.Days 29.0
   assert $ DateTime.diff dt1 dt3 == Duration.Days (-31.0)
   assert $ DateTime.diff dt4 dt1 == Duration.fromDuration (Duration.Days 31.0) <> Duration.fromDuration (Duration.Minutes 40.0)
-  assert $ over Duration.Days floor (DateTime.diff dt1 epochDateTime)
-           == Duration.Days 735963.0
+  assert $ over Duration.Days floor (DateTime.diff dt1 epochDateTime) == Duration.Days 735963.0
 
   -- instant -----------------------------------------------------------------
 
+  let i1 = Instant.fromDateTime dt1
+  let i2 = Instant.fromDateTime dt2
+  let i3 = Instant.fromDateTime dt3
+  let i4 = Instant.fromDateTime dt4
+  let i5 = Instant.fromDateTime dt5
+
   log "Check that the earliest date is a valid Instant"
   let bottomInstant = Instant.fromDateTime bottom
   assert $ Just bottomInstant == Instant.instant (Instant.unInstant bottomInstant)
@@ -182,10 +187,19 @@ main = do
   log "Check that instant/datetime conversion is bijective"
   assert $ Instant.toDateTime (Instant.fromDateTime bottom) == bottom
   assert $ Instant.toDateTime (Instant.fromDateTime top) == top
-  assert $ Instant.toDateTime (Instant.fromDateTime dt1) == dt1
-  assert $ Instant.toDateTime (Instant.fromDateTime dt2) == dt2
-  assert $ Instant.toDateTime (Instant.fromDateTime dt3) == dt3
-  assert $ Instant.toDateTime (Instant.fromDateTime dt4) == dt4
+  assert $ Instant.toDateTime i1 == dt1
+  assert $ Instant.toDateTime i2 == dt2
+  assert $ Instant.toDateTime i3 == dt3
+  assert $ Instant.toDateTime i4 == dt4
+  assert $ Instant.toDateTime i5 == dt5
+
+  log "Check that diff behaves as expected"
+  assert $ Instant.diff i2 i1 == Duration.Minutes 40.0
+  assert $ Instant.diff i1 i2 == Duration.Minutes (-40.0)
+  assert $ Instant.diff i3 i1 == Duration.Days 31.0
+  assert $ Instant.diff i5 i3 == Duration.Days 29.0
+  assert $ Instant.diff i1 i3 == Duration.Days (-31.0)
+  assert $ Instant.diff i4 i1 == Duration.fromDuration (Duration.Days 31.0) <> Duration.fromDuration (Duration.Minutes 40.0)
 
   log "All tests done"