Deprecate Enum.chunks* in favor of Enum.chunk*

Author: José Valim

CHANGELOG.md

@@ -8,18 +8,19 @@
   * [Kernel] Implement `defmodule/2`, `@/1`, `def/2` and friends in Elixir itself. `case/2`, `try/2` and `receive/1` have been made special forms. `var!/1`, `var!/2` and `alias!/1` have also been implemented in Elixir and demoted from special forms
   * [Record] Support dynamic fields in `defrecordp`
   * [Stream] Add `Stream.resource/3`
-  * [Stream] Add `Stream.zip/2`, `Stream.filter_map/3`, `Stream.each/2`, `Stream.take_every/2`, `Stream.chunks/2`, `Stream.chunks/3`, `Stream.chunks/4`, `Stream.chunks_by/2`, `Stream.scan/2`, `Stream.scan/3`, `Stream.uniq/2`, `Stream.after/2` and `Stream.run/1`
+  * [Stream] Add `Stream.zip/2`, `Stream.filter_map/3`, `Stream.each/2`, `Stream.take_every/2`, `Stream.chunk/2`, `Stream.chunk/3`, `Stream.chunk/4`, `Stream.chunk_by/2`, `Stream.scan/2`, `Stream.scan/3`, `Stream.uniq/2`, `Stream.after/2` and `Stream.run/1`
   * [Stream] Support `Stream.take/2` and `Stream.drop/2` with negative counts
   * [Typespec] Support `is_var/1` in typespecs
 
 * Bug fixes
   * [HashDict] Ensure a `HashDict` stored in an attribute can be accessed via the attribute
-  * [Enum] Fix bug in `Enum.chunks/4` where you'd get an extra element when there enumerable was a multiple of the counter and a pad was given
+  * [Enum] Fix bug in `Enum.chunk/4` where you'd get an extra element when there enumerable was a multiple of the counter and a pad was given
   * [Kernel] `quote location: :keep` now only affects definitions in order to keep the proper trace in definition exceptions
   * [Mix] Also symlink `include` directories in _build dependencies
 
 * Deprecations
   * [Enum] `Enumerable.count/1` and `Enumerable.member?/2` should now return tagged tuples. Please see `Enumerable` docs for more info
+  * [Enum] Deprecate `Enum.chunks/2`, `Enum.chunks/4` and `Enum.chunks_by/2` in favor of `Enum.chunk/2`, `Enum.chunk/4` and `Enum.chunk_by/2`
   * [File] `File.binstream!/3` is deprecated. Simply use `File.stream!/3` which is able to figure out if `stream` or `binstream` operations should be used
   * [Macro] `Macro.extract_args/1` is deprecated in favor of `Macro.decompose_call/1`
   * [Typespec] `when` clauses in typespecs were moved to the outer part of the spec
@@ -146,7 +147,7 @@
 * Enhancements
   * [CLI] Add `--verbose` to elixirc, which now is non-verbose by default
   * [Dict] Add `Dict.Behaviour` as a convenience to create your own dictionaries
-  * [Enum] Add `Enum.split/2`, `Enum.reduce/2`, `Enum.flat_map/2`, `Enum.chunks/2`, `Enum.chunks/4`, `Enum.chunks_by/2`, `Enum.concat/1` and `Enum.concat/2`
+  * [Enum] Add `Enum.split/2`, `Enum.reduce/2`, `Enum.flat_map/2`, `Enum.chunk/2`, `Enum.chunk/4`, `Enum.chunk_by/2`, `Enum.concat/1` and `Enum.concat/2`
   * [Enum] Support negative indices in `Enum.at/fetch/fetch!`
   * [ExUnit] Show failures on CLIFormatter as soon as they pop up
   * [IEx] Allow for strings in `h` helper

lib/elixir/lib/enum.ex

@@ -282,11 +282,29 @@ defmodule Enum do
     end
   end
 
+  @doc false
+  def chunks(coll, n) do
+    IO.write "Enum.chunks/2 is deprecated, please use Enum.chunk/2 instead\n#{Exception.format_stacktrace}"
+    chunk(coll, n)
+  end
+
+  @doc false
+  def chunks(coll, n, step, pad) do
+    IO.write "Enum.chunks/4 is deprecated, please use Enum.chunk/4 instead\n#{Exception.format_stacktrace}"
+    chunk(coll, n, step, pad)
+  end
+
+  @doc false
+  def chunks_by(coll, fun) do
+    IO.write "Enum.chunks_by/2 is deprecated, please use Enum.chunk_by/2 instead\n#{Exception.format_stacktrace}"
+    chunk_by(coll, fun)
+  end
+
   @doc """
-  Shortcut to `chunks(coll, n, n)`.
+  Shortcut to `chunk(coll, n, n)`.
   """
-  @spec chunks(t, non_neg_integer) :: [list]
-  def chunks(coll, n), do: chunks(coll, n, n, nil)
+  @spec chunk(t, non_neg_integer) :: [list]
+  def chunk(coll, n), do: chunk(coll, n, n, nil)
 
   @doc """
   Returns a collection of lists containing `n` items each, where
@@ -303,23 +321,23 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.chunks([1, 2, 3, 4, 5, 6], 2)
+      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 2)
       [[1, 2], [3, 4], [5, 6]]
-      iex> Enum.chunks([1, 2, 3, 4, 5, 6], 3, 2)
+      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2)
       [[1, 2, 3], [3, 4, 5]]
-      iex> Enum.chunks([1, 2, 3, 4, 5, 6], 3, 2, [7])
+      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2, [7])
       [[1, 2, 3], [3, 4, 5], [5, 6, 7]]
-      iex> Enum.chunks([1, 2, 3, 4, 5, 6], 3, 3, [])
+      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 3, [])
       [[1, 2, 3], [4, 5, 6]]
 
   """
-  @spec chunks(t, non_neg_integer, non_neg_integer) :: [list]
-  @spec chunks(t, non_neg_integer, non_neg_integer, t | nil) :: [list]
-  def chunks(coll, n, step, pad // nil) when n > 0 and step > 0 do
+  @spec chunk(t, non_neg_integer, non_neg_integer) :: [list]
+  @spec chunk(t, non_neg_integer, non_neg_integer, t | nil) :: [list]
+  def chunk(coll, n, step, pad // nil) when n > 0 and step > 0 do
     limit = :erlang.max(n, step)
 
     { _, { acc, { buffer, i } } } =
-      Enumerable.reduce(coll, { :cont, { [], { [], 0 } } }, R.chunks(n, step, limit))
+      Enumerable.reduce(coll, { :cont, { [], { [], 0 } } }, R.chunk(n, step, limit))
 
     if nil?(pad) || i == 0 do
       :lists.reverse(acc)
@@ -334,14 +352,14 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.chunks_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
+      iex> Enum.chunk_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
       [[1], [2, 2], [3], [4, 4, 6], [7, 7]]
 
   """
-  @spec chunks_by(t, (element -> any)) :: [list]
-  def chunks_by(coll, fun) do
+  @spec chunk_by(t, (element -> any)) :: [list]
+  def chunk_by(coll, fun) do
     { _, { acc, res } } =
-      Enumerable.reduce(coll, { :cont, { [], nil } }, R.chunks_by(fun))
+      Enumerable.reduce(coll, { :cont, { [], nil } }, R.chunk_by(fun))
 
     case res do
       { buffer, _ } ->

lib/elixir/lib/stream.ex

@@ -180,10 +180,10 @@ defmodule Stream do
   def unquote(:after)(enum, fun), do: Lazy[enum: enum, after: [fun]]
 
   @doc """
-  Shortcut to `chunks(enum, n, n)`.
+  Shortcut to `chunk(enum, n, n)`.
   """
-  @spec chunks(Enumerable.t, non_neg_integer) :: Enumerable.t
-  def chunks(enum, n), do: chunks(enum, n, n, nil)
+  @spec chunk(Enumerable.t, non_neg_integer) :: Enumerable.t
+  def chunk(enum, n), do: chunk(enum, n, n, nil)
 
   @doc """
   Streams the enumerable in chunks, containing `n` items each, where
@@ -200,26 +200,26 @@ defmodule Stream do
 
   ## Examples
 
-      iex> Stream.chunks([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list
+      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list
       [[1, 2], [3, 4], [5, 6]]
-      iex> Stream.chunks([1, 2, 3, 4, 5, 6], 3, 2) |> Enum.to_list
+      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5]]
-      iex> Stream.chunks([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list
+      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5], [5, 6, 7]]
-      iex> Stream.chunks([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list
+      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list
       [[1, 2, 3], [4, 5, 6]]
 
   """
-  @spec chunks(Enumerable.t, non_neg_integer, non_neg_integer) :: Enumerable.t
-  @spec chunks(Enumerable.t, non_neg_integer, non_neg_integer, Enumerable.t | nil) :: Enumerable.t
-  def chunks(enum, n, step, pad // nil) when n > 0 and step > 0 do
+  @spec chunk(Enumerable.t, non_neg_integer, non_neg_integer) :: Enumerable.t
+  @spec chunk(Enumerable.t, non_neg_integer, non_neg_integer, Enumerable.t | nil) :: Enumerable.t
+  def chunk(enum, n, step, pad // nil) when n > 0 and step > 0 do
     limit = :erlang.max(n, step)
     lazy enum, { [], 0 },
-         fn(f1) -> R.chunks(n, step, limit, f1) end,
-         fn(f1) -> &do_chunks(&1, n, pad, f1) end
+         fn(f1) -> R.chunk(n, step, limit, f1) end,
+         fn(f1) -> &do_chunk(&1, n, pad, f1) end
   end
 
-  defp do_chunks(acc(h, { buffer, count } = old, t) = acc, n, pad, f1) do
+  defp do_chunk(acc(h, { buffer, count } = old, t) = acc, n, pad, f1) do
     if nil?(pad) || count == 0 do
       { :cont, acc }
     else
@@ -235,23 +235,23 @@ defmodule Stream do
 
   ## Examples
 
-      iex> stream = Stream.chunks_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
+      iex> stream = Stream.chunk_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
       iex> Enum.to_list(stream)
       [[1], [2, 2], [3], [4, 4, 6], [7, 7]]
 
   """
-  @spec chunks_by(Enumerable.t, (element -> any)) :: Enumerable.t
-  def chunks_by(enum, fun) do
+  @spec chunk_by(Enumerable.t, (element -> any)) :: Enumerable.t
+  def chunk_by(enum, fun) do
     lazy enum, nil,
-         fn(f1) -> R.chunks_by(fun, f1) end,
-         fn(f1) -> &do_chunks_by(&1, f1) end
+         fn(f1) -> R.chunk_by(fun, f1) end,
+         fn(f1) -> &do_chunk_by(&1, f1) end
   end
 
-  defp do_chunks_by(acc(_, nil, _) = acc, _f1) do
+  defp do_chunk_by(acc(_, nil, _) = acc, _f1) do
     { :cont, acc }
   end
 
-  defp do_chunks_by(acc(h, { buffer, _ }, t), f1) do
+  defp do_chunk_by(acc(h, { buffer, _ }, t), f1) do
     cont_with_acc(f1, :lists.reverse(buffer), h, nil, t)
   end
 

lib/elixir/lib/stream/reducers.ex

@@ -2,7 +2,7 @@ defmodule Stream.Reducers do
   # Collection of reducers shared by Enum and Stream.
   @moduledoc false
 
-  defmacro chunks(n, step, limit, f // nil) do
+  defmacro chunk(n, step, limit, f // nil) do
     quote do
       fn entry, acc(h, { buffer, count }, t) ->
         buffer = [entry|buffer]
@@ -25,7 +25,7 @@ defmodule Stream.Reducers do
     end
   end
 
-  defmacro chunks_by(callback, f // nil) do
+  defmacro chunk_by(callback, f // nil) do
     quote do
       fn
         entry, acc(h, { buffer, value }, t) ->

lib/elixir/test/elixir/enum_test.exs

@@ -354,21 +354,21 @@ defmodule EnumTest.List do
     end
   end
 
-  test :chunks do
-    assert Enum.chunks([1, 2, 3, 4, 5], 2) == [[1, 2], [3, 4]]
-    assert Enum.chunks([1, 2, 3, 4, 5], 2, 2, [6]) == [[1, 2], [3, 4], [5, 6]]
-    assert Enum.chunks([1, 2, 3, 4, 5, 6], 3, 2) == [[1, 2, 3], [3, 4, 5]]
-    assert Enum.chunks([1, 2, 3, 4, 5, 6], 2, 3) == [[1, 2], [4, 5]]
-    assert Enum.chunks([1, 2, 3, 4, 5, 6], 3, 2, []) == [[1, 2, 3], [3, 4, 5], [5, 6]]
-    assert Enum.chunks([1, 2, 3, 4, 5, 6], 3, 3, []) == [[1, 2, 3], [4, 5, 6]]
-    assert Enum.chunks([1, 2, 3, 4, 5], 4, 4, 6..10) == [[1, 2, 3, 4], [5, 6, 7, 8]]
+  test :chunk do
+    assert Enum.chunk([1, 2, 3, 4, 5], 2) == [[1, 2], [3, 4]]
+    assert Enum.chunk([1, 2, 3, 4, 5], 2, 2, [6]) == [[1, 2], [3, 4], [5, 6]]
+    assert Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2) == [[1, 2, 3], [3, 4, 5]]
+    assert Enum.chunk([1, 2, 3, 4, 5, 6], 2, 3) == [[1, 2], [4, 5]]
+    assert Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2, []) == [[1, 2, 3], [3, 4, 5], [5, 6]]
+    assert Enum.chunk([1, 2, 3, 4, 5, 6], 3, 3, []) == [[1, 2, 3], [4, 5, 6]]
+    assert Enum.chunk([1, 2, 3, 4, 5], 4, 4, 6..10) == [[1, 2, 3, 4], [5, 6, 7, 8]]
   end
 
-  test :chunks_by do
-    assert Enum.chunks_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1)) == [[1], [2, 2], [3], [4, 4, 6], [7, 7]]
-    assert Enum.chunks_by([1, 2, 3, 4], fn _ -> true end) == [[1, 2, 3, 4]]
-    assert Enum.chunks_by([], fn _ -> true end) == []
-    assert Enum.chunks_by([1], fn _ -> true end) == [[1]]
+  test :chunk_by do
+    assert Enum.chunk_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1)) == [[1], [2, 2], [3], [4, 4, 6], [7, 7]]
+    assert Enum.chunk_by([1, 2, 3, 4], fn _ -> true end) == [[1, 2, 3, 4]]
+    assert Enum.chunk_by([], fn _ -> true end) == []
+    assert Enum.chunk_by([1], fn _ -> true end) == [[1]]
   end
 
   test :slice do
@@ -767,18 +767,18 @@ defmodule EnumTest.Range do
     assert Enum.min_by(1..3, fn(x) -> :math.pow(-2, x) end) == 3
   end
 
-  test :chunks do
-    assert Enum.chunks(1..5, 2) == [[1, 2], [3, 4]]
-    assert Enum.chunks(1..5, 2, 2, [6]) == [[1, 2], [3, 4], [5, 6]]
-    assert Enum.chunks(1..6, 3, 2) == [[1, 2, 3], [3, 4, 5]]
-    assert Enum.chunks(1..6, 2, 3) == [[1, 2], [4, 5]]
-    assert Enum.chunks(1..6, 3, 2, []) == [[1, 2, 3], [3, 4, 5], [5, 6]]
-    assert Enum.chunks(1..5, 4, 4, 6..10) == [[1, 2, 3, 4], [5, 6, 7, 8]]
+  test :chunk do
+    assert Enum.chunk(1..5, 2) == [[1, 2], [3, 4]]
+    assert Enum.chunk(1..5, 2, 2, [6]) == [[1, 2], [3, 4], [5, 6]]
+    assert Enum.chunk(1..6, 3, 2) == [[1, 2, 3], [3, 4, 5]]
+    assert Enum.chunk(1..6, 2, 3) == [[1, 2], [4, 5]]
+    assert Enum.chunk(1..6, 3, 2, []) == [[1, 2, 3], [3, 4, 5], [5, 6]]
+    assert Enum.chunk(1..5, 4, 4, 6..10) == [[1, 2, 3, 4], [5, 6, 7, 8]]
   end
 
-  test :chunks_by do
-    assert Enum.chunks_by(1..4, fn _ -> true end) == [[1, 2, 3, 4]]
-    assert Enum.chunks_by(1..4, &(rem(&1, 2) == 1)) == [[1], [2], [3], [4]]
+  test :chunk_by do
+    assert Enum.chunk_by(1..4, fn _ -> true end) == [[1, 2, 3, 4]]
+    assert Enum.chunk_by(1..4, &(rem(&1, 2) == 1)) == [[1], [2], [3], [4]]
   end
 
   test :slice do

lib/elixir/test/elixir/stream_test.exs

@@ -39,31 +39,31 @@ defmodule StreamTest do
     assert Process.get(:after)
   end
 
-  test "chunks" do
-    assert Stream.chunks([1, 2, 3, 4, 5], 2) |> Enum.to_list ==
+  test "chunk" do
+    assert Stream.chunk([1, 2, 3, 4, 5], 2) |> Enum.to_list ==
            [[1, 2], [3, 4]]
-    assert Stream.chunks([1, 2, 3, 4, 5], 2, 2, [6]) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5], 2, 2, [6]) |> Enum.to_list ==
            [[1, 2], [3, 4], [5, 6]]
-    assert Stream.chunks([1, 2, 3, 4, 5, 6], 3, 2) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2) |> Enum.to_list ==
            [[1, 2, 3], [3, 4, 5]]
-    assert Stream.chunks([1, 2, 3, 4, 5, 6], 2, 3) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5, 6], 2, 3) |> Enum.to_list ==
            [[1, 2], [4, 5]]
-    assert Stream.chunks([1, 2, 3, 4, 5, 6], 3, 2, []) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2, []) |> Enum.to_list ==
            [[1, 2, 3], [3, 4, 5], [5, 6]]
-    assert Stream.chunks([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list ==
            [[1, 2, 3], [4, 5, 6]]
-    assert Stream.chunks([1, 2, 3, 4, 5], 4, 4, 6..10) |> Enum.to_list ==
+    assert Stream.chunk([1, 2, 3, 4, 5], 4, 4, 6..10) |> Enum.to_list ==
            [[1, 2, 3, 4], [5, 6, 7, 8]]
   end
 
-  test "chunks is zippable" do
-    stream = Stream.chunks([1, 2, 3, 4, 5, 6], 3, 2, [])
+  test "chunk is zippable" do
+    stream = Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2, [])
     list   = Enum.to_list(stream)
     assert Enum.zip(list, list) == Enum.zip(stream, stream)
   end
 
-  test "chunks_by" do
-    stream = Stream.chunks_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
+  test "chunk_by" do
+    stream = Stream.chunk_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
 
     assert is_lazy(stream)
     assert Enum.to_list(stream) ==
@@ -72,8 +72,8 @@ defmodule StreamTest do
            [[1], [2, 2], [3]]
   end
 
-  test "chunks_by is zippable" do
-    stream = Stream.chunks_by([1, 2, 2, 3], &(rem(&1, 2) == 1))
+  test "chunk_by is zippable" do
+    stream = Stream.chunk_by([1, 2, 2, 3], &(rem(&1, 2) == 1))
     list   = Enum.to_list(stream)
     assert Enum.zip(list, list) == Enum.zip(stream, stream)
   end