Deprecate =~

Use String.contains?/2 when the right side is a string or
String.match?/2 when the right side is a regex.

The goal of this deprecation is to make space for the upcoming
`~` and `~=` operators.

Author: José Valim

CHANGELOG.md

@@ -16,6 +16,7 @@
 * Deprecations
   * [Kernel] `binary_to_term/1`, `binary_to_term/2`, `term_to_binary/1` and `term_to_binary/2` are deprecated in favor of their counterparts in the `:erlang` module
   * [Kernel] `//` for default arguments is deprecated in favor of `\\`. This is a soft deprecation, no warnings will be emitted for it in this release
+  * [Kernel] Deprecate `=~` in favor of `String.contains?/2` (for strings) and `String.match?/2` (for regexes)
   * [Kernel] Deprecate `@behavior` in favor of `@behaviour`
   * [Record] Deprecate `to_keywords`, `getter` and `list getter` functionalities in `defrecordp`
 

lib/elixir/lib/kernel.ex

@@ -1789,32 +1789,15 @@ defmodule Kernel do
     end
   end
 
-  @doc """
-  Matches the term on the left against the regular expression or string on the
-  right. Returns true if `left` matches `right` (if it's a regular expression)
-  or contains `right` (if it's a string).
-
-  ## Examples
-
-      iex> "abcd" =~ %r/c(d)/
-      true
-
-      iex> "abcd" =~ %r/e/
-      false
-
-      iex> "abcd" =~ "bc"
-      true
-
-      iex> "abcd" =~ "ad"
-      false
-
-  """
+  @doc false
   def left =~ right when is_binary(left) and is_binary(right) do
+    IO.write :stderr, "left =~ right is deprecated, please use String.match?/2 (for regexes) or String.contains?/2 (for strings) instead\n#{Exception.format_stacktrace}"
     :binary.match(left, right) != :nomatch
   end
 
   def left =~ right when is_binary(left) and is_tuple(right) and
       tuple_size(right) > 0 and elem(right, 0) == Regex do
+    IO.write :stderr, "left =~ right is deprecated, please use String.match?/2 (for regexes) or String.contains?/2 (for strings) instead\n#{Exception.format_stacktrace}"
     Regex.match?(right, left)
   end
 

lib/elixir/lib/string.ex

@@ -974,7 +974,7 @@ defmodule String do
   end
 
   defp do_starts_with(string, prefix) when is_binary(prefix) do
-    match?({0, _}, :binary.match(string, prefix))
+    Kernel.match?({0, _}, :binary.match(string, prefix))
   end
 
   defp do_starts_with(_, _) do
@@ -1021,7 +1021,24 @@ defmodule String do
   end
 
   @doc """
-  Returns `true` if `string` contains match, otherwise `false`.
+  Check if `string` matches the given regular expression.
+
+  ## Examples
+
+      iex> String.match?("foo", %r/foo/)
+      true
+      iex> String.match?("bar", %r/foo/)
+      false
+
+  """
+  @spec match?(t, Regex.t) :: boolean
+  def match?(string, regex) do
+    Regex.match?(regex, string)
+  end
+
+  @doc """
+  Check if `string` contains any of the given `contents`.
+
   `matches` can be either a single string or a list of strings.
 
   ## Examples
@@ -1036,12 +1053,12 @@ defmodule String do
   """
   @spec contains?(t, t | [t]) :: boolean
 
-  def contains?(string, matches) when is_list(matches) do
-    Enum.any?(matches, &do_contains(string, &1))
+  def contains?(string, contents) when is_list(contents) do
+    Enum.any?(contents, &do_contains(string, &1))
   end
 
-  def contains?(string, match) do
-    do_contains(string, match)
+  def contains?(string, content) do
+    do_contains(string, content)
   end
 
   defp do_contains(string, "") when is_binary(string) do

lib/elixir/lib/version.ex

@@ -353,7 +353,7 @@ defmodule Version do
     @doc false
     def parse_pre(pre) do
       String.split(pre, ".") |> Enum.map fn piece ->
-        if piece =~ %r/^(0|[1-9][0-9]*)$/ do
+        if Regex.match?(%r/^(0|[1-9][0-9]*)$/, piece) do
           binary_to_integer(piece)
         else
           piece

lib/elixir/test/elixir/exception_test.exs

@@ -47,8 +47,8 @@ defmodule Kernel.ExceptionTest do
     assert Exception.format_stacktrace_entry({:lists, :bar, [1, 2, 3], []}) == "(stdlib) :lists.bar(1, 2, 3)"  end
 
   test "format_stacktrace_entry with fun" do
-    assert Exception.format_stacktrace_entry({fn(x) -> x end, [1], []}) =~ %r/#Function<.+>\(1\)/
-    assert Exception.format_stacktrace_entry({fn(x, y) -> { x, y } end, 2, []}) =~ %r"#Function<.+>/2"
+    assert String.match? Exception.format_stacktrace_entry({fn(x) -> x end, [1], []}), %r/#Function<.+>\(1\)/
+    assert String.match? Exception.format_stacktrace_entry({fn(x, y) -> { x, y } end, 2, []}), %r"#Function<.+>/2"
   end
 
   test "format_mfa" do
@@ -61,7 +61,7 @@ defmodule Kernel.ExceptionTest do
   end
 
   test "format_fa" do
-    assert Exception.format_fa(fn -> end, 1) =~
+    assert String.match? Exception.format_fa(fn -> end, 1),
            %r"#Function<\d\.\d+/0 in Kernel\.ExceptionTest\.test format_fa/1>/1"
   end
 

lib/elixir/test/elixir/hash_dict_test.exs

@@ -49,7 +49,7 @@ defmodule HashDictTest do
   end
 
   test "inspect" do
-    assert inspect(filled_dict(8)) =~ "#HashDict<"
+    assert String.starts_with? inspect(filled_dict(8)), "#HashDict<"
   end
 
   defp smoke_test(range) do

lib/elixir/test/elixir/kernel/cli_test.exs

@@ -87,18 +87,18 @@ defmodule Kernel.CLI.ParallelCompilerTest do
 
   test "compiles files solving dependencies" do
     fixtures = [fixture_path("parallel_compiler/bar.ex"), fixture_path("parallel_compiler/foo.ex")]
-    assert capture_io(fn ->
+    assert String.contains? capture_io(fn ->
       assert [Bar, Foo] = Kernel.ParallelCompiler.files fixtures
-    end) =~ "message_from_foo"
+    end), "message_from_foo"
   end
 
   test "does not hang on missing dependencies" do
     fixtures = [fixture_path("parallel_compiler/bat.ex")]
-    assert capture_io(fn ->
+    assert String.contains? capture_io(fn ->
       assert_raise CompileError, fn ->
         Kernel.ParallelCompiler.files fixtures
       end
-    end) =~ "Compilation error"
+    end), "Compilation error"
   end
 
   test "handles possible deadlocks" do
@@ -110,8 +110,8 @@ defmodule Kernel.CLI.ParallelCompilerTest do
       end
     end)
 
-    assert msg =~ "* #{fixture_path "parallel_deadlock/foo.ex"} is missing module Bar"
-    assert msg =~ "* #{fixture_path "parallel_deadlock/bar.ex"} is missing module Foo"
+    assert String.contains? msg, "* #{fixture_path "parallel_deadlock/foo.ex"} is missing module Bar"
+    assert String.contains? msg, "* #{fixture_path "parallel_deadlock/bar.ex"} is missing module Foo"
   end
 
   test "warnings_as_errors" do

lib/elixir/test/elixir/kernel/expansion_test.exs

@@ -153,8 +153,8 @@ defmodule Kernel.ExpansionTest do
   ## Locals
 
   test "locals: expands to remote calls" do
-    assert { {:., _, [Kernel, :=~] }, _, [{:a, _, []}, {:b, _, []}] } =
-          expand(quote do: a =~ b)
+    assert { {:., _, [Kernel, :function_exported?] }, _, [{:a, _, []}, {:b, _, []}, {:c, _, []}] } =
+          expand(quote do: function_exported?(a, b, c))
   end
 
   test "locals: expands to configured local" do