feat: ask whether a range holds a point or a range, or meets another (ash-project#2870)

Author: matt-beanland

lib/ash/query/function/range_overlaps.ex

@@ -22,34 +22,15 @@ defmodule Ash.Query.Function.RangeOverlaps do
   def evaluate(%{arguments: [nil, _]}), do: {:known, nil}
   def evaluate(%{arguments: [_, nil]}), do: {:known, nil}
 
+  # Overlap is a fact about two ranges, so `Ash.Range` answers it. Postgres `&&` is
+  # intersection, which is what `intersects?/2` is named for.
   def evaluate(%{arguments: [%Range{} = left, %Range{} = right]}) do
-    {:known, do_overlap?(left, right)}
+    {:known, Range.intersects?(left, right)}
   end
 
   def evaluate(_other), do: :unknown
 
   def can_return_nil?(%{arguments: arguments}) do
     Enum.any?(arguments, &Ash.Expr.can_return_nil?/1)
   end
-
-  # Two ranges overlap iff neither lies entirely on one side of the other, accounting for
-  # each bound's inclusivity (`[`/`]` inclusive, `(`/`)` exclusive) and treating a `nil`
-  # bound as ±∞. Empty ranges (e.g. `[5, 5)`) overlap nothing. Matches Postgres `&&`.
-  defp do_overlap?(left, right) do
-    not Range.empty?(left) and not Range.empty?(right) and
-      not separated?(left, right) and not separated?(right, left)
-  end
-
-  # `x` lies entirely at/below `y`, sharing no point at the `x.upper` / `y.lower` seam.
-  defp separated?(%Range{upper: nil}, _y), do: false
-  defp separated?(_x, %Range{lower: nil}), do: false
-
-  defp separated?(%Range{upper: xu, bounds: xb}, %Range{lower: yl, bounds: yb}) do
-    cond do
-      Comp.less_than?(xu, yl) -> true
-      # Touching boundary: a shared point only if BOTH sides include it.
-      Comp.equal?(xu, yl) -> not (Range.upper_inclusive?(xb) and Range.lower_inclusive?(yb))
-      true -> false
-    end
-  end
 end

lib/ash/range.ex

@@ -68,6 +68,78 @@ defmodule Ash.Range do
   @spec upper_inclusive?(bounds()) :: boolean()
   def upper_inclusive?(bounds), do: bounds in [:"(]", :"[]"]
 
+  @doc """
+  Whether the range holds `value`, which may be a point or another range.
+
+  An unbounded end holds everything beyond it, and an empty range holds no point.
+  Each bound is compared with `Comp`, so an inner type behaves inside a range as
+  it does outside one, and a bound that excludes its own value (`(` or `)`) is
+  not held.
+
+  A range holds another when the second lies within the first, sharing an endpoint
+  or being equal included. Every range holds the empty range, as Postgres `@>` does.
+  """
+  @spec contains?(t(), term()) :: boolean()
+  def contains?(%__MODULE__{} = range, %__MODULE__{} = value) do
+    empty?(value) or
+      (not empty?(range) and
+         relation(range, value) in [:contains, :started_by, :finished_by, :equals])
+  end
+
+  def contains?(%__MODULE__{} = range, value) do
+    not empty?(range) and above_lower?(range, value) and below_upper?(range, value)
+  end
+
+  defp above_lower?(%{lower: nil}, _value), do: true
+
+  defp above_lower?(range, value) do
+    case Comp.compare(value, range.lower) do
+      :gt -> true
+      :eq -> lower_inclusive?(range.bounds)
+      :lt -> false
+    end
+  end
+
+  defp below_upper?(%{upper: nil}, _value), do: true
+
+  defp below_upper?(range, value) do
+    case Comp.compare(value, range.upper) do
+      :lt -> true
+      :eq -> upper_inclusive?(range.bounds)
+      :gt -> false
+    end
+  end
+
+  @doc """
+  Whether two ranges share any point.
+
+  An empty range intersects nothing, not even itself. Each range must start at or
+  before the other ends, and a boundary the two ranges share counts only when both
+  sides include it — so `[1,3)` and `[3,5)` do not intersect, where `[1,3]` and
+  `[3,5)` do. Bounds are compared with `Comp`, as everywhere else here.
+
+  Named for what it answers rather than for the operator it backs. Postgres calls
+  `&&` "overlap" and `range_overlaps/2` keeps that name, but Allen's *overlaps* is
+  the narrower relation where two ranges cross with neither containing the other —
+  under which `[1,10)` and `[3,5)` do **not** overlap. This returns true for them.
+  """
+  @spec intersects?(t(), t()) :: boolean()
+  def intersects?(%__MODULE__{} = left, %__MODULE__{} = right) do
+    not empty?(left) and not empty?(right) and
+      starts_before_end?(left, right) and starts_before_end?(right, left)
+  end
+
+  defp starts_before_end?(%{lower: nil}, _other), do: true
+  defp starts_before_end?(_range, %{upper: nil}), do: true
+
+  defp starts_before_end?(range, other) do
+    case Comp.compare(range.lower, other.upper) do
+      :lt -> true
+      :eq -> lower_inclusive?(range.bounds) and upper_inclusive?(other.bounds)
+      :gt -> false
+    end
+  end
+
   @doc """
   Compares two ranges as Postgres orders them: empty first, then by lower bound, then
   by upper, an unbounded end as `-∞`/`+∞`, and the earlier boundary first where two

test/type/range_test.exs

@@ -530,4 +530,146 @@ defmodule Ash.Type.RangeTest do
       refute Range.empty?(%Range{lower: nil, upper: nil})
     end
   end
+
+  describe "contains?/2" do
+    test "a bounded range holds values between its bounds" do
+      range = %Ash.Range{lower: 1, upper: 5, bounds: :"[)"}
+
+      refute Ash.Range.contains?(range, 0)
+      assert Ash.Range.contains?(range, 1)
+      assert Ash.Range.contains?(range, 4)
+      refute Ash.Range.contains?(range, 5)
+    end
+
+    test "a bound holds its own value only when inclusive" do
+      assert Ash.Range.contains?(%Ash.Range{lower: 1, upper: 5, bounds: :"[]"}, 5)
+      refute Ash.Range.contains?(%Ash.Range{lower: 1, upper: 5, bounds: :"()"}, 1)
+      assert Ash.Range.contains?(%Ash.Range{lower: 1, upper: 5, bounds: :"(]"}, 5)
+      refute Ash.Range.contains?(%Ash.Range{lower: 1, upper: 5, bounds: :"(]"}, 1)
+    end
+
+    test "an unbounded end holds everything beyond it" do
+      assert Ash.Range.contains?(%Ash.Range{lower: nil, upper: 5}, -1_000)
+      assert Ash.Range.contains?(%Ash.Range{lower: 1, upper: nil}, 1_000)
+      assert Ash.Range.contains?(%Ash.Range{lower: nil, upper: nil}, 0)
+    end
+
+    test "an empty range holds nothing" do
+      refute Ash.Range.contains?(%Ash.Range{lower: 5, upper: 5, bounds: :"[)"}, 5)
+      refute Ash.Range.contains?(%Ash.Range{lower: 9, upper: 5}, 7)
+    end
+
+    test "holds datetimes by Comp, not by term order" do
+      range = %Ash.Range{
+        lower: ~U[2026-01-31 00:00:00Z],
+        upper: ~U[2026-03-01 00:00:00Z],
+        bounds: :"[)"
+      }
+
+      assert Ash.Range.contains?(range, ~U[2026-02-01 00:00:00Z])
+      refute Ash.Range.contains?(range, ~U[2026-03-02 00:00:00Z])
+    end
+  end
+
+  describe "contains?/2 with a range" do
+    # Cross-checked against Postgres 19: `@>` on int4range agrees case for case.
+    test "a range holds one that lies within it, sharing an endpoint or equal included" do
+      outer = %Range{lower: 1, upper: 10, bounds: :"[)"}
+
+      assert Range.contains?(outer, %Range{lower: 3, upper: 5, bounds: :"[)"})
+      assert Range.contains?(outer, %Range{lower: 1, upper: 5, bounds: :"[)"})
+      assert Range.contains?(outer, %Range{lower: 5, upper: 10, bounds: :"[)"})
+      assert Range.contains?(outer, outer)
+      refute Range.contains?(outer, %Range{lower: 5, upper: 20, bounds: :"[)"})
+    end
+
+    test "every range holds the empty range, and the empty range holds nothing else" do
+      empty = Range.empty()
+      range = %Range{lower: 1, upper: 10, bounds: :"[)"}
+
+      assert Range.contains?(range, empty)
+      assert Range.contains?(empty, empty)
+      refute Range.contains?(empty, range)
+      refute Range.contains?(empty, 5)
+    end
+
+    test "an unbounded end holds everything beyond it" do
+      assert Range.contains?(
+               %Range{lower: nil, upper: nil, bounds: :"[)"},
+               %Range{lower: 1, upper: 10, bounds: :"[)"}
+             )
+
+      refute Range.contains?(
+               %Range{lower: 1, upper: 10, bounds: :"[)"},
+               %Range{lower: nil, upper: 10, bounds: :"[)"}
+             )
+    end
+  end
+
+  describe "intersects?/2" do
+    test "two ranges sharing points intersect, in either order" do
+      left = %Range{lower: 1, upper: 5, bounds: :"[)"}
+      right = %Range{lower: 4, upper: 9, bounds: :"[)"}
+
+      assert Range.intersects?(left, right)
+      assert Range.intersects?(right, left)
+    end
+
+    test "a range contained in another intersects it" do
+      assert Range.intersects?(
+               %Range{lower: 1, upper: 9, bounds: :"[)"},
+               %Range{lower: 3, upper: 4, bounds: :"[)"}
+             )
+    end
+
+    test "adjacent ranges do not intersect, which is what lets them tile" do
+      refute Range.intersects?(
+               %Range{lower: 1, upper: 3, bounds: :"[)"},
+               %Range{lower: 3, upper: 5, bounds: :"[)"}
+             )
+    end
+
+    test "a shared boundary is a shared point only when both sides include it" do
+      assert Range.intersects?(
+               %Range{lower: 1, upper: 3, bounds: :"[]"},
+               %Range{lower: 3, upper: 5, bounds: :"[)"}
+             )
+
+      refute Range.intersects?(
+               %Range{lower: 1, upper: 3, bounds: :"[]"},
+               %Range{lower: 3, upper: 5, bounds: :"()"}
+             )
+    end
+
+    test "an unbounded end intersects everything beyond it" do
+      assert Range.intersects?(
+               %Range{lower: 1, upper: nil, bounds: :"[)"},
+               %Range{lower: 1_000, upper: nil, bounds: :"[)"}
+             )
+
+      assert Range.intersects?(
+               %Range{lower: nil, upper: nil, bounds: :"[)"},
+               %Range{lower: 3, upper: 4, bounds: :"[)"}
+             )
+    end
+
+    test "an empty range intersects nothing, not even itself" do
+      empty = %Range{lower: 5, upper: 5, bounds: :"[)"}
+
+      refute Range.intersects?(empty, empty)
+      refute Range.intersects?(empty, %Range{lower: nil, upper: nil, bounds: :"[)"})
+    end
+
+    test "compares datetimes by Comp, not by term order" do
+      assert Range.intersects?(
+               %Range{lower: ~U[2026-01-31 00:00:00Z], upper: nil, bounds: :"[)"},
+               %Range{lower: ~U[2026-02-01 00:00:00Z], upper: nil, bounds: :"[)"}
+             )
+
+      refute Range.intersects?(
+               %Range{lower: ~U[2026-01-31 00:00:00Z], upper: ~U[2026-02-01 00:00:00Z]},
+               %Range{lower: ~U[2026-02-01 00:00:00Z], upper: ~U[2026-03-01 00:00:00Z]}
+             )
+    end
+  end
 end