Improve contracts for Dict

1. Functions like merge/2 and equal?/2 are only polymorphic in the
Dict module. Implementations of the Dict module only need to
care about equality and merging of the same types.

2. take/2, drop/2 and split/2 accept any Enum as argument.

Author: José Valim

lib/elixir/lib/dict.ex

@@ -34,8 +34,7 @@ defmodule Dict do
   ## Match
 
   Dictionaries are required to implement all operations
-  using the match (`===`) operator. Any deviation from
-  this behaviour should be avoided and explicitly documented.
+  using the match (`===`) operator.
   """
 
   use Behaviour
@@ -48,7 +47,7 @@ defmodule Dict do
   defcallback new(Enum.t) :: t
   defcallback new(Enum.t, (any -> { key, value })) :: t
   defcallback delete(t, key) :: t
-  defcallback drop(t, [key]) :: t
+  defcallback drop(t, Enum.t) :: t
   defcallback empty(t) :: t
   defcallback equal?(t, t) :: boolean
   defcallback get(t, key) :: value
@@ -63,9 +62,10 @@ defmodule Dict do
   defcallback pop(t, key, value) :: {value, t}
   defcallback put(t, key, value) :: t
   defcallback put_new(t, key, value) :: t
+  defcallback reduce(t, Enumerable.acc, Enumerable.reducer) :: Enumerable.result
   defcallback size(t) :: non_neg_integer()
-  defcallback split(t, [key]) :: {t, t}
-  defcallback take(t, [key]) :: t
+  defcallback split(t, Enum.t) :: {t, t}
+  defcallback take(t, Enum.t) :: t
   defcallback to_list(t) :: list()
   defcallback update(t, key, value, (value -> value)) :: t
   defcallback update!(t, key, (value -> value)) :: t | no_return
@@ -258,12 +258,15 @@ defmodule Dict do
   end
 
   @doc """
-  Merges the given `enum` into `dict`. If one of the `enum` keys
-  already exists in `dict`, the `dict` value is replaced by the `enum`
-  value.
+  Merges the dict `b` into dict `a`.
+
+  If one of the dict `b` entries already exists in the `dict`,
+  the functions in entries in `b` have higher precedence unless a
+  function is given to resolve conflicts.
 
-  The `enum` must yield tuples with two elements on enumeration,
-  where the first element represents the key and the second the value.
+  Notice this function is polymorphic as it can merge dicts of any
+  type. Each dict implementation also provides a `merge` function,
+  but they can only merge dicts of the same type.
 
   ## Examples
 
@@ -273,22 +276,6 @@ defmodule Dict do
       ...> [a: Dict.get(d, :a), b: Dict.get(d, :b), d: Dict.get(d, :d)]
       [a: 3, b: 2, d: 4]
 
-  """
-  @spec merge(t, t) :: t
-  def merge(dict, enum) do
-    merge(dict, enum, fn(_k, _v1, v2) -> v2 end)
-  end
-
-  @doc """
-  Merges the given `enum` into `dict`. If one of the `enum` entries
-  already exists in `dict`, the given function is invoked to resolve
-  the conflict.
-
-  The `enum` must yield tuples with two elements on enumeration,
-  where the first element represents the key and the second the value.
-
-  ## Examples
-
       iex> d1 = dict_impl.new([a: 1, b: 2])
       ...> d2 = dict_impl.new([a: 3, d: 4])
       ...> d = Dict.merge(d1, d2, fn(_k, v1, v2) ->
@@ -299,8 +286,17 @@ defmodule Dict do
 
   """
   @spec merge(t, t, (key, value, value -> value)) :: t
-  def merge(dict, enum, fun) do
-    target(dict).merge(dict, enum, fun)
+  def merge(a, b, fun // fn(_k, _v1, v2) -> v2 end) do
+    a_target = target(a)
+    b_target = target(b)
+
+    if a_target == b_target do
+      a_target.merge(a, b, fun)
+    else
+      b_target.reduce(b, { :cont, a }, fn({ k, v }, acc) ->
+        { :cont, a_target.update(acc, k, v, fn(other) -> fun.(k, other, v) end) }
+      end) |> elem(1)
+    end
   end
 
   @doc """
@@ -347,11 +343,6 @@ defmodule Dict do
     target(dict).update!(dict, key, fun)
   end
 
-  @doc false
-  def update(dict, key, fun) do
-    target(dict).update(dict, key, fun)
-  end
-
   @doc """
   Update a value in `dict` by calling `fun` on the value to get a new value. If
   `key` is not present in `dict` then `initial` will be stored as the first
@@ -423,8 +414,8 @@ defmodule Dict do
   end
 
   @doc """
-  Returns a new dict where only the keys in `keys` from `dict` are
-  included.
+  Returns a new dict where only the keys in `keys` from `dict` are included.
+
   Any non-member keys are ignored.
 
   ## Examples
@@ -462,13 +453,16 @@ defmodule Dict do
   end
 
   @doc """
-  Check if two dicts are equal using `===`. If the dicts are
-  of different types, they are first converted to lists.
+  Check if two dicts are equal using `===`.
+
+  Notice this function is polymorphic as it can merge dicts of any
+  type. Each dict implementation also provides an `equal?` function,
+  but they can only compare dicts of the same type.
 
   ## Examples
 
       iex> a = dict_impl.new(a: 2, b: 3, f: 5, c: 123)
-      ...> b = ListDict.new(a: 2, b: 3, f: 5, c: 123)
+      ...> b = [a: 2, b: 3, f: 5, c: 123]
       ...> Dict.equal?(a, b)
       true
 
@@ -488,7 +482,12 @@ defmodule Dict do
         a_target.equal?(a, b)
 
       a_target.size(a) == b_target.size(b) ->
-        ListDict.equal?(a_target.to_list(a), b_target.to_list(b))
+        a_target.reduce(a, { :cont, true }, fn({ k, v }, _acc) ->
+          case b_target.fetch(b, k) do
+            { :ok, ^v } -> { :cont, true }
+            _           -> { :halt, false }
+          end
+        end) |> elem(1)
 
       true ->
         false

lib/elixir/lib/dict/behaviour.ex

@@ -88,21 +88,16 @@ defmodule Dict.Behaviour do
         update(dict, key, value, fn(v) -> v end)
       end
 
-      def drop(dict, []), do: dict
-
-      def drop(dict, [key|keys]) do
-        drop(delete(dict, key), keys)
+      def drop(dict, keys) do
+        Enum.reduce keys, dict, &delete(&2, &1)
       end
 
       def take(dict, keys) do
-        take(dict, keys, new)
-      end
-
-      defp take(_dict, [], acc), do: acc
-      defp take(dict, [key|keys], acc) do
-        case fetch(dict, key) do
-          { :ok, value } -> take(dict, keys, put(acc, key, value))
-          :error -> take(dict, keys, acc)
+        Enum.reduce keys, new, fn key, acc ->
+          case fetch(dict, key) do
+            { :ok, value } -> put(acc, key, value)
+            :error -> acc
+          end
         end
       end
 
@@ -130,19 +125,18 @@ defmodule Dict.Behaviour do
           false -> false
           true  ->
             reduce(dict1, { :cont, true }, fn({ k, v }, _acc) ->
-              unless fetch(dict2, k) == { :ok, v } do
-                { :halt, false }
-              else
-                { :cont, true }
+              case fetch(dict2, k) do
+                { :ok, ^v } -> { :cont, true }
+                _ -> { :halt, false }
               end
             end) |> elem(1)
         end
       end
 
-      def merge(dict, enumerable, callback // fn(_k, _v1, v2) -> v2 end) do
-        Enum.reduce(enumerable, dict, fn({key, value}, acc) ->
-          update(acc, key, value, fn(v1) -> callback.(key, v1, value) end)
-        end)
+      def merge(dict1, dict2, fun // fn(_k, _v1, v2) -> v2 end) do
+        reduce(dict1, { :cont, dict2 }, fn { k, v1 }, acc ->
+          { :cont, update(acc, k, v1, &fun.(k, v1, &1)) }
+        end) |> elem(1)
       end
 
       defoverridable merge: 2, merge: 3, equal?: 2, to_list: 1, keys: 1,

lib/elixir/lib/hash_dict.ex

@@ -115,17 +115,11 @@ defmodule HashDict do
   end
 
   def split(dict, keys) do
-    split(keys, new, dict)
-  end
-
-  defp split([], including, excluding) do
-    { including, excluding }
-  end
-
-  defp split([key|keys], including, excluding) do
-    case dict_delete(excluding, key) do
-      { excluding, value } -> split(keys, put(including, key, value), excluding)
-      :error -> split(keys, including, excluding)
+    Enum.reduce keys, { new, dict }, fn key, { inc, exc } = acc ->
+      case dict_delete(exc, key) do
+        { exc, value } -> { put(inc, key, value), exc }
+        :error -> acc
+      end
     end
   end
 
@@ -141,10 +135,6 @@ defmodule HashDict do
     end) |> elem(1)
   end
 
-  def merge(trie() = dict, enumerable, callback) do
-    super(dict, enumerable, callback)
-  end
-
   ## General helpers
 
   defp dict_delete(trie(root: root, size: size), key) do

lib/elixir/lib/keyword.ex

@@ -324,7 +324,7 @@ defmodule Keyword do
 
   """
   @spec equal?(t, t) :: boolean
-  def equal?(left, right) do
+  def equal?(left, right) when is_list(left) and is_list(right) do
     :lists.sort(left) == :lists.sort(right)
   end
 
@@ -339,7 +339,7 @@ defmodule Keyword do
 
   """
   @spec merge(t, t) :: t
-  def merge(d1, d2) do
+  def merge(d1, d2) when is_list(d1) and is_list(d2) do
     d2 ++ lc({ k, _ } = tuple inlist d1, not has_key?(d2, k), do: tuple)
   end
 
@@ -356,7 +356,7 @@ defmodule Keyword do
 
   """
   @spec merge(t, t, (key, value, value -> value)) :: t
-  def merge(d1, d2, fun) do
+  def merge(d1, d2, fun) when is_list(d1) and is_list(d2) do
     do_merge(d2, d1, fun)
   end
 
@@ -456,7 +456,7 @@ defmodule Keyword do
     acc = { [], [] }
 
     { take, drop } = Enum.reduce dict, acc, fn({ k, v }, { take, drop }) ->
-      case :lists.member(k, keys) do
+      case k in keys do
         true  -> { [{k, v}|take], drop }
         false -> { take, [{k, v}|drop] }
       end
@@ -481,7 +481,7 @@ defmodule Keyword do
 
   """
   def take(dict, keys) do
-    lc { k, _ } = tuple inlist dict, :lists.member(k, keys), do: tuple
+    lc { k, _ } = tuple inlist dict, k in keys, do: tuple
   end
 
   @doc """
@@ -500,7 +500,7 @@ defmodule Keyword do
 
   """
   def drop(dict, keys) do
-    lc { k, _ } = tuple inlist dict, not :lists.member(k, keys), do: tuple
+    lc { k, _ } = tuple inlist dict, not k in keys, do: tuple
   end
 
   @doc """

lib/elixir/lib/list_dict.ex

@@ -94,7 +94,7 @@ defmodule ListDict do
     acc = { [], [] }
 
     {take, drop} = Enum.reduce dict, acc, fn({ k, v }, { take, drop }) ->
-      if :lists.member(k, keys) do
+      if k in keys do
         { [{k, v}|take], drop }
       else
         { take, [{k, v}|drop] }
@@ -105,11 +105,11 @@ defmodule ListDict do
   end
 
   def take(dict, keys) do
-    lc { k, _ } = tuple inlist dict, :lists.member(k, keys), do: tuple
+    lc { k, _ } = tuple inlist dict, k in keys, do: tuple
   end
 
   def drop(dict, keys) do
-    lc { k, _ } = tuple inlist dict, not :lists.member(k, keys), do: tuple
+    lc { k, _ } = tuple inlist dict, not k in keys, do: tuple
   end
 
   def update!([{key, value}|dict], key, fun) do
@@ -142,5 +142,10 @@ defmodule ListDict do
     :lists.keysort(1, dict) === :lists.keysort(1, other)
   end
 
+  def reduce(_,           { :halt, acc }, _fun),   do: { :halted, acc }
+  def reduce(list,        { :suspend, acc }, fun), do: { :suspended, acc, &reduce(list, &1, fun) }
+  def reduce([],          { :cont, acc }, _fun),   do: { :done, acc }
+  def reduce([{_,_}=h|t], { :cont, acc }, fun),    do: reduce(t, fun.(h, acc), fun)
+
   def to_list(dict), do: dict
 end

lib/elixir/test/elixir/dict_test.exs

@@ -263,6 +263,13 @@ defmodule DictTest.Common do
         assert drop == dict
       end
 
+      test "split/2 with enum" do
+        dict = int_dict()
+        { take, drop } = Dict.split(dict, 1..3)
+        assert take == dict
+        assert drop == new_dict([])
+      end
+
       test "take/2" do
         dict = new_dict()
         take = Dict.take(dict, ["unknown_key"])
@@ -278,6 +285,11 @@ defmodule DictTest.Common do
         assert Dict.take(dict, [1.0]) == new_dict([])
       end
 
+      test "take/2 with enum" do
+        dict = int_dict()
+        assert Dict.take(dict, 1..3) == dict
+      end
+
       test "drop/2" do
         dict = new_dict()
         drop = Dict.drop(dict, ["unknown_key"])
@@ -293,6 +305,11 @@ defmodule DictTest.Common do
         assert Dict.drop(dict, [1.0]) == dict
       end
 
+      test "drop/2 with enum" do
+        dict = int_dict()
+        assert Dict.drop(dict, 1..3) == new_dict([])
+      end
+
       test "empty" do
         assert Dict.empty(new_dict) == new_dict([])
       end