chunk/4 -> chunk_every/4 and chunk_by/4 -> chunk_while/4

Signed-off-by: José Valim <jose.valim@plataformatec.com.br>

Author: José Valim

lib/elixir/lib/enum.ex

@@ -314,11 +314,21 @@ defmodule Enum do
     end
   end
 
+  # Deprecate on v1.7
+  @doc false
+  def chunk(enumerable, count), do: chunk(enumerable, count, count, nil)
+
+  # Deprecate on v1.7
+  @doc false
+  def chunk(enumerable, count, step, leftover \\ nil) do
+    chunk_every(enumerable, count, step, leftover || :discard)
+  end
+
   @doc """
-  Shortcut to `chunk(enumerable, count, count)`.
+  Shortcut to `chunk_every(enumerable, count, count)`.
   """
-  @spec chunk(t, pos_integer) :: [list]
-  def chunk(enumerable, count), do: chunk(enumerable, count, count, nil)
+  @spec chunk_every(t, pos_integer) :: [list]
+  def chunk_every(enumerable, count), do: chunk_every(enumerable, count, count, [])
 
   @doc """
   Returns list of lists containing `count` items each, where
@@ -327,40 +337,36 @@ defmodule Enum do
   `step` is optional and, if not passed, defaults to `count`, i.e.
   chunks do not overlap.
 
-  If the final chunk does not have `count` elements to fill the chunk,
-  the final chunk is dropped unless `leftover` is given.
+  If the last chunk does not have `count` elements to fill the chunk,
+  elements are taken from `leftover` to fill in the chunk. If `leftover`
+  does not have enough elements to fill the chunk, then a partial chunk
+  is returned with less than `count` elements.
 
-  If `leftover` is given, elements are taken from `leftover` to fill in
-  the chunk. If `leftover` is passed and does not have enough elements
-  to fill the chunk, then a partial chunk is returned with less than
-  `count` elements. Therefore, an empty list can be given to `leftover`
-  when one simply desires for the last chunk to not be discarded.
+  If `:discard` is given in `leftover`, the last chunk is discarded
+  unless it has exactly `count` elements.
 
   ## Examples
 
-      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 2)
+      iex> Enum.chunk_every([1, 2, 3, 4, 5, 6], 2)
       [[1, 2], [3, 4], [5, 6]]
 
-      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2)
+      iex> Enum.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, :discard)
       [[1, 2, 3], [3, 4, 5]]
 
-      iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2, [7])
+      iex> Enum.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, [7])
       [[1, 2, 3], [3, 4, 5], [5, 6, 7]]
 
-      iex> Enum.chunk([1, 2, 3, 4], 3, 3, [])
+      iex> Enum.chunk_every([1, 2, 3, 4], 3, 3, [])
       [[1, 2, 3], [4]]
 
-      iex> Enum.chunk([1, 2, 3, 4], 10)
-      []
-
-      iex> Enum.chunk([1, 2, 3, 4], 10, 10, [])
+      iex> Enum.chunk_every([1, 2, 3, 4], 10)
       [[1, 2, 3, 4]]
 
   """
-  @spec chunk(t, pos_integer, pos_integer, t | nil) :: [list]
-  def chunk(enumerable, count, step, leftover \\ nil)
+  @spec chunk_every(t, pos_integer, pos_integer, t | :discard) :: [list]
+  def chunk_every(enumerable, count, step, leftover \\ [])
       when is_integer(count) and count > 0 and is_integer(step) and step > 0 do
-    R.chunk(&chunk_by/4, enumerable, count, step, leftover)
+    R.chunk_every(&chunk_while/4, enumerable, count, step, leftover)
   end
 
   @doc """
@@ -389,15 +395,22 @@ defmodule Enum do
       ...>   [] -> {:cont, []}
       ...>   acc -> {:cont, Enum.reverse(acc), []}
       ...> end
-      iex> Enum.chunk_by(1..10, [], chunk_fun, after_fun)
+      iex> Enum.chunk_while(1..10, [], chunk_fun, after_fun)
       [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
 
   """
-  @spec chunk_by(t, acc,
-                 (element, acc -> {:cont, chunk, acc} | {:cont, acc}),
-                 (acc -> {:cont, chunk, acc} | {:cont, acc})) :: Enumerable.t when chunk: any
-  def chunk_by(enum, acc, chunk_fun, after_fun) do
-    {res, acc} = reduce(enum, {[], acc}, R.chunk_by(chunk_fun))
+  @spec chunk_while(t, acc,
+                    (element, acc -> {:cont, chunk, acc} | {:cont, acc} | {:halt, acc}),
+                    (acc -> {:cont, chunk, acc} | {:cont, acc})) :: Enumerable.t when chunk: any
+  def chunk_while(enum, acc, chunk_fun, after_fun) do
+    {_, {res, acc}} =
+      Enumerable.reduce(enum, {:cont, {[], acc}}, fn entry, {buffer, acc} ->
+        case chunk_fun.(entry, acc) do
+          {:cont, emit, acc} -> {:cont, {[emit | buffer], acc}}
+          {:cont, acc} -> {:cont, {buffer, acc}}
+          {:halt, acc} -> {:halt, {buffer, acc}}
+        end
+      end)
 
     case after_fun.(acc) do
       {:cont, _acc} -> :lists.reverse(res)
@@ -419,7 +432,7 @@ defmodule Enum do
   """
   @spec chunk_by(t, (element -> any)) :: [list]
   def chunk_by(enumerable, fun) do
-    R.chunk_by(&chunk_by/4, enumerable, fun)
+    R.chunk_by(&chunk_while/4, enumerable, fun)
   end
 
   @doc """

lib/elixir/lib/stream.ex

@@ -121,47 +121,57 @@ defmodule Stream do
 
   ## Transformers
 
+  # Deprecate on v1.7
+  @doc false
+  def chunk(enum, n), do: chunk(enum, n, n, nil)
+
+  # Deprecate on v1.7
+  @doc false
+  def chunk(enum, n, step, leftover \\ nil)
+      when is_integer(n) and n > 0 and is_integer(step) and step > 0 do
+    R.chunk(&chunk_while/4, enum, n, step, leftover)
+  end
+
   @doc """
-  Shortcut to `chunk(enum, n, n)`.
+  Shortcut to `chunk_every(enum, count, count)`.
   """
-  @spec chunk(Enumerable.t, pos_integer) :: Enumerable.t
-  def chunk(enum, n), do: chunk(enum, n, n, nil)
+  @spec chunk_every(Enumerable.t, pos_integer) :: Enumerable.t
+  def chunk_every(enum, count), do: chunk_every(enum, count, count, [])
 
   @doc """
-  Streams the enumerable in chunks, containing `n` items each, where
-  each new chunk starts `step` elements into the enumerable.
+  Streams the enumerable in chunks, containing `count` items each,
+  where each new chunk starts `step` elements into the enumerable.
 
   `step` is optional and, if not passed, defaults to `count`, i.e.
   chunks do not overlap.
 
-  If the final chunk does not have `count` elements to fill the chunk,
-  the final chunk is dropped unless `leftover` is given.
+  If the last chunk does not have `count` elements to fill the chunk,
+  elements are taken from `leftover` to fill in the chunk. If `leftover`
+  does not have enough elements to fill the chunk, then a partial chunk
+  is returned with less than `count` elements.
 
-  If `leftover` is given, elements are taken from `leftover` to fill in
-  the chunk. If `leftover` is passed and does not have enough elements
-  to fill the chunk, then a partial chunk is returned with less than
-  `count` elements. Therefore, an empty list can be given to `leftover`
-  when one simply desires for the last chunk to not be discarded.
+  If `:discard` is given in `leftover`, the last chunk is discarded
+  unless it has exactly `count` elements.
 
   ## Examples
 
-      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 2) |> Enum.to_list
       [[1, 2], [3, 4], [5, 6]]
 
-      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2) |> Enum.to_list
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, :discard) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5]]
 
-      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 2, [7]) |> Enum.to_list
       [[1, 2, 3], [3, 4, 5], [5, 6, 7]]
 
-      iex> Stream.chunk([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list
+      iex> Stream.chunk_every([1, 2, 3, 4, 5, 6], 3, 3, []) |> Enum.to_list
       [[1, 2, 3], [4, 5, 6]]
 
   """
-  @spec chunk(Enumerable.t, pos_integer, pos_integer, Enumerable.t | nil) :: Enumerable.t
-  def chunk(enum, n, step, leftover \\ nil)
-      when is_integer(n) and n > 0 and is_integer(step) and step > 0 do
-    R.chunk(&chunk_by/4, enum, n, step, leftover)
+  @spec chunk_every(Enumerable.t, pos_integer, pos_integer, Enumerable.t | :discard) :: Enumerable.t
+  def chunk_every(enum, count, step, leftover \\ [])
+      when is_integer(count) and count > 0 and is_integer(step) and step > 0 do
+    R.chunk_every(&chunk_while/4, enum, count, step, leftover)
   end
 
   @doc """
@@ -178,7 +188,7 @@ defmodule Stream do
   """
   @spec chunk_by(Enumerable.t, (element -> any)) :: Enumerable.t
   def chunk_by(enum, fun) do
-    R.chunk_by(&chunk_by/4, enum, fun)
+    R.chunk_by(&chunk_while/4, enum, fun)
   end
 
   @doc """
@@ -205,21 +215,21 @@ defmodule Stream do
       ...>   [] -> {:cont, []}
       ...>   acc -> {:cont, Enum.reverse(acc), []}
       ...> end
-      iex> stream = Stream.chunk_by(1..10, [], chunk_fun, after_fun)
+      iex> stream = Stream.chunk_while(1..10, [], chunk_fun, after_fun)
       iex> Enum.to_list(stream)
       [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
 
   """
-  @spec chunk_by(Enumerable.t, acc,
-                 (element, acc -> {:cont, chunk, acc} | {:cont, acc}),
-                 (acc -> {:cont, chunk, acc} | {:cont, acc})) :: Enumerable.t when chunk: any
-  def chunk_by(enum, acc, chunk_fun, after_fun) do
+  @spec chunk_while(Enumerable.t, acc,
+                    (element, acc -> {:cont, chunk, acc} | {:cont, acc} | {:halt, acc}),
+                    (acc -> {:cont, chunk, acc} | {:cont, acc})) :: Enumerable.t when chunk: any
+  def chunk_while(enum, acc, chunk_fun, after_fun) do
     lazy enum, acc,
-         fn(f1) -> R.chunk_by(chunk_fun, f1) end,
-         &after_chunk_by(&1, &2, after_fun)
+         fn(f1) -> R.chunk_while(chunk_fun, f1) end,
+         &after_chunk_while(&1, &2, after_fun)
   end
 
-  defp after_chunk_by(acc(h, acc, t), f1, after_fun) do
+  defp after_chunk_while(acc(h, acc, t), f1, after_fun) do
     case after_fun.(acc) do
       {:cont, emit, acc} -> next_with_acc(f1, emit, h, acc, t)
       {:cont, acc} -> {:cont, acc(h, acc, t)}

lib/elixir/lib/stream/reducers.ex

@@ -2,7 +2,7 @@ defmodule Stream.Reducers do
   # Collection of reducers and utilities shared by Enum and Stream.
   @moduledoc false
 
-  def chunk(chunk_by, enumerable, count, step, leftover) do
+  def chunk_every(chunk_by, enumerable, count, step, leftover) do
     limit = :erlang.max(count, step)
     chunk_by.(enumerable, {[], 0}, fn entry, {acc_buffer, acc_count} ->
       acc_buffer = [entry | acc_buffer]
@@ -22,7 +22,7 @@ defmodule Stream.Reducers do
         {:cont, new_state}
       end
     end, fn {acc_buffer, acc_count} ->
-      if is_nil(leftover) || acc_count == 0 do
+      if leftover == :discard or acc_count == 0 do
         {:cont, []}
       else
         {:cont, :lists.reverse(acc_buffer, Enum.take(leftover, count - acc_count)), []}
@@ -45,12 +45,13 @@ defmodule Stream.Reducers do
     end)
   end
 
-  defmacro chunk_by(callback, fun \\ nil) do
+  defmacro chunk_while(callback, fun \\ nil) do
     quote do
       fn entry, acc(head, acc, tail) ->
         case unquote(callback).(entry, acc) do
           {:cont, emit, acc} -> next_with_acc(unquote(fun), emit, head, acc, tail)
           {:cont, acc} -> skip(acc(head, acc, tail))
+          {:halt, acc} -> {:halt, acc(head, acc, tail)}
         end
       end
     end

lib/elixir/test/elixir/enum_test.exs

@@ -66,12 +66,15 @@ defmodule EnumTest do
     assert Enum.chunk_by([1], fn _ -> true end) == [[1]]
   end
 
-  test "chunk_by/4" do
+  test "chunk_while/4" do
     chunk_fun = fn i, acc ->
-      if rem(i, 2) == 0 do
-        {:cont, Enum.reverse([i | acc]), []}
-      else
-        {:cont, [i | acc]}
+      cond do
+        i > 10 ->
+          {:halt, acc}
+        rem(i, 2) == 0 ->
+          {:cont, Enum.reverse([i | acc]), []}
+        true ->
+          {:cont, [i | acc]}
       end
     end
 
@@ -80,12 +83,16 @@ defmodule EnumTest do
       acc -> {:cont, Enum.reverse(acc), []}
     end
 
-    assert Enum.chunk_by([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [], chunk_fun, after_fun) ==
+    assert Enum.chunk_while([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [], chunk_fun, after_fun) ==
            [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
-    assert Enum.chunk_by(0..10, [], chunk_fun, after_fun) ==
+    assert Enum.chunk_while(0..9, [], chunk_fun, after_fun) ==
+           [[0], [1, 2], [3, 4], [5, 6], [7, 8], [9]]
+    assert Enum.chunk_while(0..10, [], chunk_fun, after_fun) ==
            [[0], [1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
-    assert Enum.chunk_by(0..11, [], chunk_fun, after_fun) ==
-           [[0], [1, 2], [3, 4], [5, 6], [7, 8], [9, 10], [11]]
+    assert Enum.chunk_while(0..11, [], chunk_fun, after_fun) ==
+           [[0], [1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
+    assert Enum.chunk_while([5, 7, 9, 11], [], chunk_fun, after_fun) ==
+           [[5, 7, 9]]
   end
 
   test "concat/1" do
@@ -821,16 +828,16 @@ defmodule EnumTest.Range do
     assert Enum.at(2..6, -8) == nil
   end
 
-  test "chunk/2" do
-    assert Enum.chunk(1..5, 2) == [[1, 2], [3, 4]]
+  test "chunk_every/2" do
+    assert Enum.chunk_every(1..5, 2) == [[1, 2], [3, 4], [5]]
   end
 
-  test "chunk/4" do
-    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]]
+  test "chunk_every/4" do
+    assert Enum.chunk_every(1..5, 2, 2) == [[1, 2], [3, 4], [5]]
+    assert Enum.chunk_every(1..6, 3, 2, :discard) == [[1, 2, 3], [3, 4, 5]]
+    assert Enum.chunk_every(1..6, 2, 3, :discard) == [[1, 2], [4, 5]]
+    assert Enum.chunk_every(1..6, 3, 2, []) == [[1, 2, 3], [3, 4, 5], [5, 6]]
+    assert Enum.chunk_every(1..5, 4, 4, 6..10) == [[1, 2, 3, 4], [5, 6, 7, 8]]
   end
 
   test "chunk_by/2" do