CompareChain Release: v0.6.0 (2025-01-09)

• Docs: CompareChain — compare_chain v0.6.0
• GitHub: GitHub - CargoSense/compare_chain: Chained semantic comparisons for Elixir. · GitHub

This release is largely to fix a warning: Elixir 1.17+ warned about the code a < b in one of the doctests.

It also shifts version support: it’s now Elixir 1.15 to 1.18 officially. Older versions of Elixir should still work, but they’re no longer “officially” supported.

Changelog

v0.6.0 (2025-01-09)

• Drop official support for Elixir 1.13 and 1.14 (though they should still work)
• Currently support Elixir 1.15 to 1.18
• Change docs so they no longer warn about a doctest
• Miscellanea: renamed LISENCE file, added CODEOWNERS file, etc.

As always, issues and PRs welcome

CompareChain Release: v0.5.0 (2024-05-22)

• Docs: CompareChain
• Git: CargoSense/compare_chain

Hi! Another release. There’s a bugfix and a few changes including one breaking change:

• Allow === and !=== in expressions
• Improve documentation
• Fix bug with certain operation chains:

  compare?(1 < 2 != 3 < 4) #=> true
  compare?(1 < 2 != 3 > 4) #=> true (wrong!)
  

• Improve error message and documentation for invalid expressions
• [BREAKING] all branches of and, or and not must now contain comparisons
  • Example: compare?(1 < 2 and true) used to be ok but is no longer allowed because the right argument to and doesn’t contain a comparison.

As always, issues and PRs are welcome!

A new section I added to the docs that I want to callout:

One last selling point

As a happy accident, CompareChain.compare?/2 always uses fewer characters than its compare/2 counterpart:

compare?(a <= b, Date)
# vs.
Date.compare(a, b) != :gt

(Assuming you’ve already included import CompareChain, of course!)

Because it’s shorter and more readable, these days I always use CompareChain for any semantic comparison, chained or not.

CompareChain Release: v0.4.0 (2023-09-10)

• Docs: CompareChain
• Git: CargoSense/compare_chain

Hi, there’s been another (tiny) release of CompareChain.

This is the only change:

• Using a struct with compare?/1 results in a warning

  Running:

  iex> compare?(~D[2023-01-02] < ~D[2023-01-02]) #=> false
  

  Now yields:

  [warning] Performing structural comparison on matching structs.
  
  Did you mean to use `compare?/2`?
  
    compare?(~D[2022-01-02] ??? ~D[2022-02-01], Date)
  

We decided that’s preferable to silently giving you the wrong answer and making you chase down a weird bug. Not speaking from experience or anything…

As always, issues and PRs are welcome!

CompareChain Release: v0.3.0 (2023-01-28)

• Docs: CompareChain
• Git: CargoSense/compare_chain

Hi (upwards of) tens of users! I’ve just released a new version of CompareChain.

There are two main changes:

• You can now use == and != as well

  compare?(~T[00:00:00] == ~T[11:11:11], Time) #=> false
  compare?(~T[00:00:00] != ~T[11:11:11], Time) #=> true
  

  (No idea why I didn’t do this in the first place..)

• You can now use Elixir >= 1.13.0 instead of being restricted to 1.14
  I could probably go much lower if I stopped using Macro.prewalker/1.

As always, issues and PRs are welcome!

For the Range types, pretty much this. I’ve basically wrapped %Postgrex.Range{} into type specific versions (e.g. DateRange, DecimalRange, etc.) which can be used with Ecto. Then I’ve defined a Range protocol and a more general database type protocol that defines functions for comparison handing; I need two protocols since some comparisons aren’t range related and the range related types have things like the overlapping conditions to consider.

The Range protocol functions deal with things like upper bounds compare and lower bounds compare. The more general comparison function is modelled on the existing Elixir modules such as DateTime.compare/2 except that there is an expanded set of return values that it can return due to the complexity of range handling.

In deciding what the range type comparisons would return, the range types in the application are largely just a reflection of the PostgreSQL range type implementations. When looking at the various operators that PostgreSQL implements to compare ranges, I figured I could create an extended set of return values from my DbTypes.compare/2 function that more or less mirrored the PostgreSQL comparison functions. So, whereas DateTime.compare/2 can return :eq, :lt, or :gt, my DbTypes.compare/2 can return (from my docs):

• :gt - left is greater than right.
• :lt - left is less than right.
• :eq - the values are equal.
• :lcr - left contains right.
• :rcl - right contains left.
• :gto - greater than overlapping.
• :lto - less than overlapping.

Naturally, what of those can be returned in practice depends on what is being compared. So, for example, comparing a simple DateTime value to a DateTimeRange value cannot result in the overlapping return values though the “contains” values are possible. Anyway, I figure this keeps me in sync with what I can expect to do with the database directly using the PostgreSQL operators and keeps me reasonably aligned with how more complex comparisons are implemented elsewhere in the Elixir ecosystem.

It gets even more fun when you compare ranges to ranges since you may have overlapping ranges (e.g. Less Than, Not Overlapping vs. Less Than, Overlapping).

Exactly!

Speaking of “fun”, that DateTimeWithInfinity example is (almost) real. We often deal with ranges of time which have “started but not yet stopped”. E.g. a plane that took off at 11am but hasn’t landed yet. Even though the plane’s flight time doesn’t have a definite end, it should still overlap with any other range that starts after 11am.

The moral of the story is that you end up doing a bunch of bespoke logic all over the place because it never quite seems to generalize nicely. (Or at least, we couldn’t get it to.)

For my project these range types originate in the database so I put similar functionality to what you’ve done here in the library I use close to where the database custom types are defined.

I’m curious what you mean by that. Like, custom handling of %Postgrex.Range{}?

I know about the DeMorgan’s law. I just didn’t understand why the example shows duplicated logic and was wondering if it was a mistake.

It gets even more fun when you compare ranges to ranges since you may have overlapping ranges (e.g. Less Than, Not Overlapping vs. Less Than, Overlapping). For my project these range types originate in the database so I put similar functionality to what you’ve done here in the library I use close to where the database custom types are defined.

Nice to see a this kind of problem being looked at in a public library.

We do a ton of datetime range comparisons at CargoSense

You got that right!

Some additional context for this release: Like Ben said, at CargoSense we do stuff like this all. the. time. I have become an unwilling expert in the art of comparing datetime ranges.

Even for simple things, datetime comparisons can be cumbersome. For example, suppose you want to compare a datetime dt to some range {left, right}. What do you do?

The obvious answer is to check if dt is between left and right. But which “between” do you mean? There are actually 4 cases to cover:

• left <= dt <= right
• left <= dt < right
• left < dt <= right
• left < dt < right

We’ve had occasion to need all 4 in one circumstance or another. And given the difficulties in reading the native datetime comparisons, we found ourselves writing a bunch of defps all over the place. So we’re unreasonably excited by the prospect of in-lining a bunch of functions with names like between_inclusive?.

not basically lets you pivot between logically equivalent renderings of the same thing. DeMorgan’s law says that:

a > b == not(a <= b)

and this extends to compound propositions like:

(a > b or a <= c) == not (a <= b and a > c)

Depending on what your function is doing, it might be easier to think of the logic in terms of or and having a choice between two things, or it might be easier to think of it in terms of and where several things all have to be true.

By supporting not you can turn an and into an or by pulling out a not to the front and vice versa.