Add List.first!/1 and List.last!/1 (#15082)

Author: pierrelegall

lib/elixir/lib/list.ex

@@ -298,6 +298,33 @@ defmodule List do
   def first([], default), do: default
   def first([head | _], _default), do: head
 
+  @doc """
+  Returns the first element in `list`.
+
+  If `list` is empty, an error is raised.
+
+  ## Examples
+
+      iex> List.first!([1])
+      1
+
+      iex> List.first!([1, 2, 3])
+      1
+
+      iex> List.first!([])
+      ** (ArgumentError) attempted to get the first element of an empty list
+
+  """
+  @doc since: "1.20.0"
+  @spec first!([elem, ...]) :: elem when elem: var
+  def first!(list)
+
+  def first!([head | _]), do: head
+
+  def first!([]) do
+    raise ArgumentError, "attempted to get the first element of an empty list"
+  end
+
   @doc """
   Returns the last element in `list` or `default` if `list` is empty.
 
@@ -326,6 +353,34 @@ defmodule List do
   def last([head], _default), do: head
   def last([_ | tail], default), do: last(tail, default)
 
+  @doc """
+  Returns the last element in `list`.
+
+  If `list` is empty, an error is raised.
+
+  ## Examples
+
+      iex> List.last!([1])
+      1
+
+      iex> List.last!([1, 2, 3])
+      3
+
+      iex> List.last!([])
+      ** (ArgumentError) attempted to get the last element of an empty list
+
+  """
+  @doc since: "1.20.0"
+  @spec last!([elem, ...]) :: elem when elem: var
+  def last!(list)
+
+  def last!([head]), do: head
+  def last!([_ | tail]), do: last!(tail)
+
+  def last!([]) do
+    raise ArgumentError, "attempted to get the last element of an empty list"
+  end
+
   @doc """
   Receives a list of tuples and returns the first tuple
   where the element at `position` in the tuple matches the

lib/elixir/test/elixir/list_test.exs

@@ -76,18 +76,46 @@ defmodule ListTest do
 
   test "first/1" do
     assert List.first([]) == nil
-    assert List.first([], 1) == 1
     assert List.first([1]) == 1
     assert List.first([1, 2, 3]) == 1
   end
 
+  test "first/2" do
+    assert List.first([], 1) == 1
+    assert List.first([2], 1) == 2
+    assert List.first([1, 2, 3], 1) == 1
+  end
+
+  test "first!/1" do
+    assert List.first!([1]) == 1
+    assert List.first!([1, 2, 3]) == 1
+
+    assert_raise ArgumentError, "attempted to get the first element of an empty list", fn ->
+      List.first!([])
+    end
+  end
+
   test "last/1" do
     assert List.last([]) == nil
-    assert List.last([], 1) == 1
     assert List.last([1]) == 1
     assert List.last([1, 2, 3]) == 3
   end
 
+  test "last/2" do
+    assert List.last([], 1) == 1
+    assert List.last([2], 1) == 2
+    assert List.last([1, 2, 3], 1) == 3
+  end
+
+  test "last!/1" do
+    assert List.last!([1]) == 1
+    assert List.last!([1, 2, 3]) == 3
+
+    assert_raise ArgumentError, "attempted to get the last element of an empty list", fn ->
+      List.last!([])
+    end
+  end
+
   test "keyfind/4" do
     assert List.keyfind([a: 1, b: 2], :a, 0) == {:a, 1}
     assert List.keyfind([a: 1, b: 2], 2, 1) == {:b, 2}