RFC: Deprecate Timex.compare and change Timex.diff to a signed integer result

[tallakt]

iex(25)> Timex.diff expiry, Timex.DateTime.now, :minutes
7
iex(26)> Timex.diff Timex.DateTime.now, expiry, :minutes
7

According to the docs, the result should be signed. Timex version 2.1.1

[bitwalker]

@tallakt I believe the reason I changed this was because a signed diff didn't seem useful to me when one could use compare to determine the past/future relation. It's easy enough to change back, but I suppose my question is: do you rely on the signed result? Is it a useful property of the function compared to returning the diff as a non-negative integer always, and using compare to determine how two dates/datetimes relate to each other?

Another question then becomes, if diff returns a signed value, is compare even useful as a function? Should it be deprecated/removed and just leave diff as the sole means of comparison?

[tallakt]

I would rather just use diff and then normal operators for comparing the results rather than the -1, 0, +1 result which feels alot like C++ to me. That's my opinion anyway. I don't feel very strongly about it, but as a minimum, we should update the docs.

[bitwalker]

Agreed on the docs. I'll think about these two functions in general and post back here with my decision. Chances are I will deprecate compare and just lean on diff for double duty moving forward, but I want to think it through before I decide.

[bitwalker]

I've updated the docs in the meantime

[tallakt]

After giving it a bit of thought, it is probably more intuitive that dates arithmetic with dates behave like with normal numbers, with signed results, eg:

iex> Timex.diff a, b
4
iex> Timex.diff b, a
-4

you could always just use abs if you need the absolute distance

[bitwalker]

@tallakt Agreed. I think I'll make that change sooner rather than later, because I don't want the current behaviour to become too entrenched.

[myronmarston]

FWIW, I'm working on upgrading to 2.0 and the fact that diff is no longer signed (compared to 0.x and 1.x) is giving me trouble. I've implemented our own diff function that delegates to Timex.diff and restores the sign based on compare but it feels like I shouldn't have to do that. It would be like if a math library defined - to always return the abs value, so that 5 - 10 returned 5 (requiring the user to compare the values to figure out if it should be negative).

Anyhow, sounds like you are already planning and restoring the signed behavior but I wanted to lend my voice to it as well :).

[myronmarston]

By the way, the signed behavior of diff in Timex 0.x and 1.x worked the opposite of how I expected. In my mind, I thought of diff as the equivalent of subtraction for date math -- so just as 10 - 15 is negative, I expected diff(may_10_2016, may_15_2016, :days) to return -5 and diff(may_15_2016, may_10_2016, :days) to return 5 -- but it does the opposite. Reading the old docs for diff (from when it returned a sign value), it says:

Calculate time interval between two dates.

...which helps explain the behavior. I think that it's easy to assume that diff(a, b) is the equivalent of a -b so if you want to preserve this behavior, I'd suggest calling the function interval instead of diff. Or, if you're willing to flip the sign from how it behaved before, diff would still be a good name, IMO.

[bitwalker]

@myronmarston This has been merged into master and the behaviour is exactly as you describe it, putting an older date before a newer one returns a negative value, and vice versa. The same behaviour as compare.

[bitwalker]

This RFC has been merged in 3.0, so the diff behaviour is again signed.