Deprecate Enum.first/1 in favor of Enum.at/2 and List.first/1

The main reason for this change is because `Enum.first/1` does
not communicate that enumeration will happen, in contrast to
functions like Enum.at/2 and Enum.fetch/2 which are meant to
be used with non-indexed collections and the need for enumeration
is made a bit more obvious.

Closes #1983

Author: José Valim

lib/elixir/lib/enum.ex

@@ -741,22 +741,15 @@ defmodule Enum do
     end
   end
 
-  @doc """
-  Returns the first item in the collection or `nil` if the collection is empty.
-
-  ## Examples
-
-      iex> Enum.first([])
-      nil
-      iex> Enum.first([1, 2, 3])
-      1
-
-  """
+  @doc false
   @spec first(t) :: :nil | element
-  def first([]),    do: nil
-  def first([h|_]), do: h
+  def first(list) when is_list(list) do
+    IO.write "Enum.first/1 is deprecated, please use Enum.at/2 or List.first/1 instead\n#{Exception.format_stacktrace}"
+    List.first(list)
+  end
 
   def first(collection) do
+    IO.write "Enum.first/1 is deprecated, please use Enum.at/2 instead\n#{Exception.format_stacktrace}"
     Enumerable.reduce(collection, { :cont, nil }, fn(entry, _) ->
       { :halt, entry }
     end) |> elem(1)

lib/elixir/lib/list.ex

@@ -116,6 +116,23 @@ defmodule List do
     :lists.foldr(function, acc, list)
   end
 
+  @doc """
+  Returns the first element in `list` or `nil` if `list` is empty.
+
+  ## Examples
+
+      iex> List.first([])
+      nil
+      iex> List.first([1])
+      1
+      iex> List.first([1, 2, 3])
+      1
+
+  """
+  @spec first([elem]) :: nil | elem when elem: var
+  def first([]),    do: nil
+  def first([h|_]), do: h
+
   @doc """
   Returns the last element in `list` or `nil` if `list` is empty.
 
@@ -130,12 +147,9 @@ defmodule List do
 
   """
   @spec last([elem]) :: nil | elem when elem: var
-
-  def last([]), do: nil
-
-  def last(list) do
-    :lists.last(list)
-  end
+  def last([]),    do: nil
+  def last([h]),   do: h
+  def last([_|t]), do: last(t)
 
   @doc """
   Receives a list of tuples and returns the first tuple

lib/elixir/test/elixir/enum_test.exs

@@ -143,11 +143,6 @@ defmodule EnumTest.List do
     assert Enum.fetch([2, 4, 6], -4) == :error
   end
 
-  test :first do
-    assert Enum.first([]) == nil
-    assert Enum.first([1, 2, 3]) == 1
-  end
-
   test :filter do
     assert Enum.filter([1, 2, 3], fn(x) -> rem(x, 2) == 0 end) == [2]
     assert Enum.filter([2, 4, 6], fn(x) -> rem(x, 2) == 0 end) == [2, 4, 6]
@@ -530,14 +525,6 @@ defmodule EnumTest.Range do
     refute Enum.empty?(range)
   end
 
-  test :first do
-    range = 1..0
-    assert Enum.first(range) == 1
-
-    range = 1..2
-    assert Enum.first(range) == 1
-  end
-
   test :each do
     try do
       range = 1..0

lib/mix/lib/mix/tasks/local.install.ex

@@ -32,7 +32,7 @@ defmodule Mix.Tasks.Local.Install do
   def run(argv) do
     { opts, argv, _ } = OptionParser.parse(argv, switches: [force: :boolean])
 
-    unless path = Enum.first(argv) do
+    unless path = List.first(argv) do
       path = Mix.Archive.name(Mix.project[:app], Mix.project[:version])
 
       unless File.exists?(path) do
@@ -66,8 +66,8 @@ defmodule Mix.Tasks.Local.Install do
   end
 
   defp previous_version_filename(src) do
-    app = Mix.Archive.dir(src) |> String.split("-") |> Enum.first
-    Path.join(Mix.Local.archives_path, app <> "-*.ez") |> Path.wildcard |> Enum.first
+    app = Mix.Archive.dir(src) |> String.split("-") |> List.first
+    Path.join(Mix.Local.archives_path, app <> "-*.ez") |> Path.wildcard |> List.first
   end
 
   defp remove_previous_version(_previous=nil) do

lib/mix/lib/mix/tasks/local.uninstall.ex

@@ -19,7 +19,7 @@ defmodule Mix.Tasks.Local.Uninstall do
     archive = Mix.Local.archives_path
               |> Path.join(name <> "-*.ez")
               |> Path.wildcard
-              |> Enum.first
+              |> List.first
 
     unless archive do
       raise Mix.Error, message: "Could not find a local archive named #{inspect name} "<>