Add Map.intersect/2 and Map.intersect/3 (#12336)

Author: ed-flanagan

lib/elixir/lib/map.ex

@@ -1149,6 +1149,44 @@ defmodule Map do
     end
   end
 
+  @doc """
+  Intersects two maps, returning a map with the common keys.
+
+  The values in the returned map are the values of the intersected keys in `map2`.
+
+  Inlined by the compiler.
+
+  ## Examples
+
+      iex> Map.intersect(%{a: 1, b: 2}, %{b: "b", c: "c"})
+      %{b: "b"}
+
+  """
+  @doc since: "1.15.0"
+  @spec intersect(map, map) :: map
+  defdelegate intersect(map1, map2), to: :maps
+
+  @doc """
+  Intersects two maps, returning a map with the common keys and resolving conflicts through a function.
+
+  The given function will be invoked when there are duplicate keys; its
+  arguments are `key` (the duplicate key), `value1` (the value of `key` in
+  `map1`), and `value2` (the value of `key` in `map2`). The value returned by
+  `fun` is used as the value under `key` in the resulting map.
+
+  ## Examples
+
+      iex> Map.intersect(%{a: 1, b: 2}, %{b: 2, c: 3}, fn _k, v1, v2 ->
+      ...>   v1 + v2
+      ...> end)
+      %{b: 4}
+  """
+  @doc since: "1.15.0"
+  @spec intersect(map, map, (key, value, value -> value)) :: map
+  def intersect(map1, map2, fun) when is_function(fun, 3) do
+    :maps.intersect_with(fun, map1, map2)
+  end
+
   @doc false
   @deprecated "Use Map.new/2 instead (invoke Map.from_struct/1 before if you have a struct)"
   def map(map, fun) when is_map(map) do

lib/elixir/test/elixir/keyword_test.exs

@@ -21,7 +21,11 @@ defmodule KeywordTest do
   end
 
   test "implements (almost) all functions in Map" do
-    assert Map.__info__(:functions) -- Keyword.__info__(:functions) == [from_struct: 1]
+    assert Map.__info__(:functions) -- Keyword.__info__(:functions) == [
+             from_struct: 1,
+             intersect: 2,
+             intersect: 3
+           ]
   end
 
   test "get_and_update/3 raises on bad return value from the argument function" do

lib/elixir/test/elixir/map_test.exs

@@ -231,6 +231,29 @@ defmodule MapTest do
     end
   end
 
+  test "intersect/2" do
+    map = %{a: 1, b: 2}
+
+    assert Map.intersect(map, %{a: 2}) == %{a: 2}
+    assert Map.intersect(map, %{c: 3}) == %{}
+    assert Map.intersect(%{a: 2}, map) == %{a: 1}
+    assert Map.intersect(%{c: 3}, map) == %{}
+
+    assert Map.intersect(map, %{a: 2}) |> Map.intersect(%{a: 3, c: 3}) == %{a: 3}
+    assert Map.intersect(map, %{c: 3}) |> Map.intersect(%{c: 4}) == %{}
+    assert Map.intersect(map, %{a: 3, c: 3}) |> Map.intersect(%{a: 2}) == %{a: 2}
+  end
+
+  test "intersect/3" do
+    # When first map is bigger
+    assert Map.intersect(%{a: 1, b: 2, c: 3}, %{c: 4, d: 5}, fn :c, 3, 4 -> :x end) ==
+             %{c: :x}
+
+    # When second map is bigger
+    assert Map.intersect(%{b: 2, c: 3}, %{a: 1, c: 4, d: 5}, fn :c, 3, 4 -> :x end) ==
+             %{c: :x}
+  end
+
   test "implements (almost) all functions in Keyword" do
     assert Keyword.__info__(:functions) -- Map.__info__(:functions) == [
              delete: 3,