Impose === as the operator in the Dict API

Author: José Valim

lib/elixir/lib/access.ex

@@ -20,6 +20,7 @@ end
 defimpl Access, for: List do
   @doc """
   Access the given key in a tuple list.
+  The key is found via the `===` operator.
 
   ## Examples
 
@@ -32,14 +33,10 @@ defimpl Access, for: List do
       "★☆"
 
   """
+  def access(dict, key)
+  def access([{ key, value }|_], key), do: value
+  def access([{ _, _ }|t], key), do: access(t, key)
   def access([], _key), do: nil
-
-  def access(list, key) do
-    case :lists.keyfind(key, 1, list) do
-      { ^key, value } -> value
-      false -> nil
-    end
-  end
 end
 
 defimpl Access, for: Atom do

lib/elixir/lib/dict.ex

@@ -31,6 +31,11 @@ defmodule Dict do
         IO.puts "#{k}: #{v}"
       end)
 
+  ## Match
+
+  Dictionaries are required to implement all operations
+  using the match (`===`) operator. Any deviation from
+  this behaviour should be avoided and explicitly documented.
   """
 
   use Behaviour
@@ -420,7 +425,7 @@ defmodule Dict do
 
   @doc """
   Returns a new dict where only the keys in `keys` from `dict` are
-  included. 
+  included.
   Any non-member keys are ignored.
 
   ## Examples
@@ -458,8 +463,8 @@ defmodule Dict do
   end
 
   @doc """
-  Check if two dicts are equal. If the dicts are of different types, they are
-  first converted to lists.
+  Check if two dicts are equal using `===`. If the dicts are
+  of different types, they are first converted to lists.
 
   ## Examples
 

lib/elixir/lib/keyword.ex

@@ -4,13 +4,23 @@ defmodule Keyword do
   of the tuple is an atom and the second element can be
   any value.
 
-  A keyword may have duplicated keys, so it is not strictly
+  A keyword may have duplicated keys so it is not strictly
   a dictionary. However most of the functions in this module
-  allows it to behave exactly as a dictionary. For example,
-  `Keyword.get` will get the first entry matching the given
-  key, regardless if duplicated entries exist. Similarly,
-  `Keyword.put` and `Keyword.delete` ensure all duplicated
-  entries for a given key are removed when invoked.
+  behaves exactly as a dictionary and mimic the API defined
+  by the `Dict` behaviour.
+
+  For example, `Keyword.get` will get the first entry matching
+  the given key, regardless if duplicated entries exist.
+  Similarly, `Keyword.put` and `Keyword.delete` ensure all
+  duplicated entries for a given key are removed when invoked.
+  A handful of functions exist to handle duplicated keys, in
+  particular, `from_enum` allows creating a new keywords without
+  removing duplicated keys, `get_values` returns all values for
+  a given key and `delete_first` deletes just one of the existing
+  entries.
+
+  Since a keyword list is simply a list, all the operations defined
+  in `Enum` and `List` can also be applied.
   """
 
   @type key :: atom
@@ -23,16 +33,12 @@ defmodule Keyword do
   duplicated entries.
   """
   @spec from_enum(Enum.t) :: t
-  def from_enum(enum) when is_list(enum) do
-    enum
-  end
-
   def from_enum(enum) do
-    Enum.map(enum, fn(x) -> x end)
+    Enum.to_list(enum)
   end
 
   @doc """
-  Checks if the given argument is a keywords list or not
+  Checks if the given argument is a keywords list or not.
   """
   @spec keyword?(term) :: boolean
   def keyword?([{ key, _value } | rest]) when is_atom(key) do
@@ -407,4 +413,129 @@ defmodule Keyword do
   def update([], key, initial, _fun) when is_atom(key) do
     [{key, initial}]
   end
+
+  @doc """
+  Splits the given keywords in two given the given keys.
+  Duplicated keys are preserved in the split keyword list.
+
+  ## Examples
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4]
+      iex> Keyword.split(d, [:a, :c, :e])
+      { [a: 1, c: 3], [b: 2, d: 4] }
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
+      iex> Keyword.split(d, [:a, :c, :e])
+      { [a: 1, c: 3, a: 5], [b: 2, d: 4] }
+
+  """
+  def split(dict, keys) do
+    acc = { [], [] }
+
+    {take, drop} = Enum.reduce dict, acc, fn({ k, v }, { take, drop }) ->
+      if :lists.member(k, keys) do
+        { [{k, v}|take], drop }
+      else
+        { take, [{k, v}|drop] }
+      end
+    end
+
+    {Enum.reverse(take), Enum.reverse(drop)}
+  end
+
+  @doc """
+  Takes the given keys from the dict.
+  Duplicated keys are preserved in the new keyword list.
+
+  ## Examples
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4]
+      iex> Keyword.take(d, [:a, :c, :e])
+      [a: 1, c: 3]
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
+      iex> Keyword.take(d, [:a, :c, :e])
+      [a: 1, c: 3, a: 5]
+
+  """
+  def take(dict, keys) do
+    lc { k, _ } = tuple inlist dict, :lists.member(k, keys), do: tuple
+  end
+
+  @doc """
+  Drops the given keys from the dict.
+  Duplicated keys are preserved in the new keyword list.
+
+  ## Examples
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4]
+      iex> Keyword.drop(d, [:b, :d])
+      [a: 1, c: 3]
+
+      iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
+      iex> Keyword.drop(d, [:b, :d])
+      [a: 1, c: 3, a: 5]
+
+  """
+  def drop(dict, keys) do
+    lc { k, _ } = tuple inlist dict, not :lists.member(k, keys), do: tuple
+  end
+
+  @doc """
+  Returns the first value associated with `key` in the keyword
+  list as well as the keyword list without `key`.
+
+  All duplicated entries are removed. See `pop_first/3` for
+  removing only the first entry.
+
+  ## Examples
+
+      iex> Keyword.pop [a: 1], :a
+      {1,[]}
+
+      iex> Keyword.pop [a: 1], :b
+      {nil,[a: 1]}
+
+      iex> Keyword.pop [a: 1], :b, 3
+      {3,[a: 1]}
+
+      iex> Keyword.pop [a: 1], :b, 3
+      {3,[a: 1]}
+
+      iex> Keyword.pop [a: 1, a: 2], :a
+      {1,[]}
+
+  """
+  def pop(dict, key, default // nil) do
+    { get(dict, key, default), delete(dict, key) }
+  end
+
+  @doc """
+  Returns the first value associated with `key` in the keyword
+  list as well as the keyword list without that particular ocurrence
+  of `key`.
+
+  Duplicated entries are not removed.
+
+  ## Examples
+
+      iex> Keyword.pop_first [a: 1], :a
+      {1,[]}
+
+      iex> Keyword.pop_first [a: 1], :b
+      {nil,[a: 1]}
+
+      iex> Keyword.pop_first [a: 1], :b, 3
+      {3,[a: 1]}
+
+      iex> Keyword.pop_first [a: 1], :b, 3
+      {3,[a: 1]}
+
+      iex> Keyword.pop_first [a: 1, a: 2], :a
+      {1,[a: 2]}
+
+  """
+  def pop_first(dict, key, default // nil) do
+    { get(dict, key, default), delete_first(dict, key) }
+  end
 end

lib/elixir/lib/list_dict.ex

@@ -2,6 +2,10 @@ defmodule ListDict do
   @moduledoc """
   A Dict implementation that works on lists of two-items tuples.
 
+  This dictionary is only recommended for keeping a small amount
+  of values. Other dict alternatives are more viable for keeping
+  any other amount than a handful.
+
   For more information about the functions and their APIs, please
   consult the `Dict` module.
   """
@@ -38,28 +42,25 @@ defmodule ListDict do
     length(dict)
   end
 
-  def has_key?(dict, key) do
-    :lists.keymember(key, 1, dict)
-  end
+  def has_key?(dict, key)
+  def has_key?([{ key, _ }|_], key), do: true
+  def has_key?([{ _, _ }|t], key), do: has_key?(t, key)
+  def has_key?([], _key), do: false
 
-  def get(dict, key, default // nil) do
-    case :lists.keyfind(key, 1, dict) do
-      { ^key, value } -> value
-      false -> default
-    end
-  end
+  def get(dict, key, default // nil)
+  def get([{ key, value }|_], key, _default), do: value
+  def get([{ _, _ }|t], key, default), do: get(t, key, default)
+  def get([], _key, default), do: default
 
-  def fetch(dict, key) do
-    case :lists.keyfind(key, 1, dict) do
-      { ^key, value } -> { :ok, value }
-      false -> :error
-    end
-  end
+  def fetch(dict, key)
+  def fetch([{ key, value }|_], key), do: { :ok, value }
+  def fetch([{ _, _ }|t], key), do: fetch(t, key)
+  def fetch([], _key), do: :error
 
   def fetch!(dict, key) do
-    case :lists.keyfind(key, 1, dict) do
-      { ^key, value } -> value
-      false -> raise(KeyError, key: key)
+    case fetch(dict, key) do
+      { :ok, value } -> value
+      :error -> raise(KeyError, key: key)
     end
   end
 
@@ -72,43 +73,43 @@ defmodule ListDict do
   end
 
   def put_new(dict, key, val) do
-    case :lists.keyfind(key, 1, dict) do
-      { ^key, _ } -> dict
+    case has_key?(dict, key) do
+      true  -> dict
       false -> [{key, val}|dict]
     end
   end
 
-  def delete(dict, key) do
-    lc { k, _ } = tuple inlist dict, key != k, do: tuple
-  end
-
-  def merge(dict, enum, callback // fn(_k, _v1, v2) -> v2 end)
+  def delete(dict, key)
+  def delete([{ key, _ }|t], key), do: t
+  def delete([{ _, _ } = h|t], key), do: [h|delete(t, key)]
+  def delete([], _key), do: []
 
-  def merge(dict1, dict2, fun) do
-    Enum.reduce dict2, dict1, fn { k, v2 }, acc ->
-      update(acc, k, v2, fn(v1) -> fun.(k, v1, v2) end)
+  def merge(dict, enum, callback // fn(_k, _v1, v2) -> v2 end) do
+    Enum.reduce enum, dict, fn { k, v2 }, acc ->
+      update(acc, k, v2, fn(v1) -> callback.(k, v1, v2) end)
     end
   end
 
   def split(dict, keys) do
-    acc = { new(), new() }
+    acc = { [], [] }
+
     {take, drop} = Enum.reduce dict, acc, fn({ k, v }, { take, drop }) ->
-      if :lists.member(k, keys) do
+      if any_key?(k, keys) do
         { [{k, v}|take], drop }
       else
         { take, [{k, v}|drop] }
       end
     end
-    
+
     {Enum.reverse(take), Enum.reverse(drop)}
   end
 
   def take(dict, keys) do
-    lc { k, _ } = tuple inlist dict, :lists.member(k, keys), do: tuple
+    lc { k, _ } = tuple inlist dict, any_key?(k, 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 any_key?(k, keys), do: tuple
   end
 
   def update!([{key, value}|dict], key, fun) do
@@ -138,8 +139,12 @@ defmodule ListDict do
   def empty(_dict), do: []
 
   def equal?(dict, other) do
-    :lists.keysort(1, dict) == :lists.keysort(1, other)
+    :lists.keysort(1, dict) === :lists.keysort(1, other)
   end
 
   def to_list(dict), do: dict
+
+  defp any_key?(k, [k|_]), do: true
+  defp any_key?(k, [_|t]), do: any_key?(k, t)
+  defp any_key?(_k, []),   do: false
 end