Deprecate String.capitalize/2 in favor of :string.titlecase/1

When capitalize/2 was written, Erlang did not provide titlecase
functions. capitalize/2 also downcases the rest of the string
while Erlang doesn't, which is a common contention point.

Given our titlecase implementation requires 40kb of additional
code in .beam files, it makes sense to unify it with Erlang's
(which we have already done for most non-critical functionality
in unicode).

Author: josevalim

CHANGELOG.md

@@ -22,6 +22,7 @@
   * [Date] Deprecate inferring a range with negative step, call `Date.range/3` with a negative step instead
   * [Enum] Deprecate passing a range with negative step on `Enum.slice/2`, give `first..last//1` instead
   * [String] Deprecate passing a range with negative step on `String.slice/2`, give `first..last//1` instead
+  * [String] Deprecate `capitalize` in favor of Erlang's `:string.titlecase/1`
 
 #### ExUnit
 

lib/elixir/lib/string.ex

@@ -823,6 +823,7 @@ defmodule String do
       iex> String.upcase("ıi", :turkic)
       "Iİ"
 
+  Also see `String.downcase/2` and Erlang's `:string.titlecase/1` for other conversions.
   """
   @spec upcase(t, :default | :ascii | :greek | :turkic) :: t
   def upcase(string, mode \\ :default)
@@ -857,6 +858,8 @@ defmodule String do
   lowercases only the letters A to Z. `:greek` includes the context sensitive
   mappings found in Greek. `:turkic` properly handles the letter i with the dotless variant.
 
+  Also see `String.upcase/2` and Erlang's `:string.titlecase/1` for other conversions.
+
   ## Examples
 
       iex> String.downcase("ABCD")
@@ -917,28 +920,8 @@ defmodule String do
   defp downcase_ascii(<<char, rest::bits>>), do: [char | downcase_ascii(rest)]
   defp downcase_ascii(<<>>), do: []
 
-  @doc """
-  Converts the first character in the given string to
-  uppercase and the remainder to lowercase according to `mode`.
-
-  `mode` may be `:default`, `:ascii`, `:greek` or `:turkic`. The `:default` mode considers
-  all non-conditional transformations outlined in the Unicode standard. `:ascii`
-  capitalizes only the letters A to Z. `:greek` includes the context sensitive
-  mappings found in Greek. `:turkic` properly handles the letter i with the dotless variant.
-
-  ## Examples
-
-      iex> String.capitalize("abcd")
-      "Abcd"
-
-      iex> String.capitalize("fin")
-      "Fin"
-
-      iex> String.capitalize("olá")
-      "Olá"
-
-  """
-  @spec capitalize(t, :default | :ascii | :greek | :turkic) :: t
+  @doc false
+  @deprecated "Use :string.titlecase instead"
   def capitalize(string, mode \\ :default)
 
   def capitalize(<<char, rest::binary>>, :ascii) do
@@ -947,8 +930,10 @@ defmodule String do
   end
 
   def capitalize(string, mode) when is_binary(string) do
-    {char, rest} = String.Unicode.titlecase_once(string, mode)
-    char <> downcase(rest, mode)
+    case next_grapheme(string) do
+      {left, right} -> :string.titlecase(left) <> downcase(right, mode)
+      nil -> string
+    end
   end
 
   @doc false

lib/elixir/pages/references/compatibility-and-deprecations.md

@@ -80,6 +80,9 @@ The first column is the version the feature was hard deprecated. The second colu
 
 Version | Deprecated feature                                  | Replaced by (available since)
 :-------| :-------------------------------------------------- | :---------------------------------------------------------------
+[v1.16] | Ranges with negative steps in `Enum.slice/2`        | Explicit steps in ranges (v1.11)
+[v1.16] | Ranges with negative steps in `String.slice/2`      | Explicit steps in ranges (v1.11)
+[v1.16] | `String.capitalize/2`                               | `:string.titlecase/1` (v1.8)
 [v1.15] | `Calendar.ISO.day_of_week/3`                        | `Calendar.ISO.day_of_week/4` (v1.11)
 [v1.15] | `Exception.exception?/1`                            | `Kernel.is_exception/1` (v1.11)
 [v1.15] | `Regex.regex?/1`                                    | `Kernel.is_struct/2` (`Kernel.is_struct(term, Regex)`) (v1.11)
@@ -204,3 +207,4 @@ Version | Deprecated feature                                  | Replaced by (ava
 [v1.13]: https://github.com/elixir-lang/elixir/blob/v1.13/CHANGELOG.md#4-hard-deprecations
 [v1.14]: https://github.com/elixir-lang/elixir/blob/v1.14/CHANGELOG.md#4-hard-deprecations
 [v1.15]: https://github.com/elixir-lang/elixir/blob/v1.15/CHANGELOG.md#4-hard-deprecations
+[v1.16]: https://github.com/elixir-lang/elixir/blob/main/CHANGELOG.md#4-hard-deprecations

lib/elixir/test/elixir/string_test.exs

@@ -253,35 +253,23 @@ defmodule StringTest do
   end
 
   test "capitalize/1" do
-    assert String.capitalize("") == ""
-    assert String.capitalize("abc") == "Abc"
-    assert String.capitalize("ABC") == "Abc"
-    assert String.capitalize("c b a") == "C b a"
-    assert String.capitalize("1ABC") == "1abc"
-    assert String.capitalize("_aBc1") == "_abc1"
-    assert String.capitalize(" aBc1") == " abc1"
-  end
-
-  test "capitalize/1 with UTF-8" do
-    assert String.capitalize("àáâ") == "Àáâ"
-    assert String.capitalize("ÀÁÂ") == "Àáâ"
-    assert String.capitalize("âáà") == "Âáà"
-    assert String.capitalize("ÂÁÀ") == "Âáà"
-    assert String.capitalize("òóôõö") == "Òóôõö"
-    assert String.capitalize("ÒÓÔÕÖ") == "Òóôõö"
-    assert String.capitalize("fin") == "Fin"
-  end
-
-  test "capitalize/1 with ascii" do
-    assert String.capitalize("àáâ", :ascii) == "àáâ"
-    assert String.capitalize("aáA", :ascii) == "Aáa"
-  end
-
-  test "capitalize/1 with turkic" do
-    assert String.capitalize("iii", :turkic) == "İii"
-    assert String.capitalize("ııı", :turkic) == "Iıı"
-    assert String.capitalize("İii", :turkic) == "İii"
-    assert String.capitalize("Iıı", :turkic) == "Iıı"
+    mod = String
+    assert mod.capitalize("") == ""
+    assert mod.capitalize("abc") == "Abc"
+    assert mod.capitalize("ABC") == "Abc"
+    assert mod.capitalize("c b a") == "C b a"
+    assert mod.capitalize("1ABC") == "1abc"
+    assert mod.capitalize("_aBc1") == "_abc1"
+    assert mod.capitalize(" aBc1") == " abc1"
+    assert mod.capitalize("àáâ") == "Àáâ"
+    assert mod.capitalize("ÀÁÂ") == "Àáâ"
+    assert mod.capitalize("âáà") == "Âáà"
+    assert mod.capitalize("ÂÁÀ") == "Âáà"
+    assert mod.capitalize("òóôõö") == "Òóôõö"
+    assert mod.capitalize("ÒÓÔÕÖ") == "Òóôõö"
+    assert mod.capitalize("fin") == "Fin"
+    assert mod.capitalize("àáâ", :ascii) == "àáâ"
+    assert mod.capitalize("aáA", :ascii) == "Aáa"
   end
 
   test "replace_leading/3" do

lib/elixir/unicode/unicode.ex

@@ -93,12 +93,12 @@ case_ignorable_categories = :binary.compile_pattern(["Mn", "Me", "Cf", "Lm", "Sk
       _iso,
       upper,
       lower,
-      title
+      _title
     ] = :binary.split(line, ";", [:global])
 
     cacc =
-      if upper != "" or lower != "" or title != "" do
-        [{to_binary.(codepoint), to_binary.(upper), to_binary.(lower), to_binary.(title)} | cacc]
+      if upper != "" or lower != "" do
+        [{to_binary.(codepoint), to_binary.(upper), to_binary.(lower)} | cacc]
       else
         cacc
       end
@@ -168,14 +168,14 @@ defmodule String.Unicode do
         acc
 
       line, acc ->
-        [codepoint, lower, title, upper, _] = :binary.split(line, "; ", [:global])
+        [codepoint, lower, _title, upper, _] = :binary.split(line, "; ", [:global])
         key = to_binary.(codepoint)
 
         :lists.keystore(
           key,
           1,
           acc,
-          {key, to_binary.(upper), to_binary.(lower), to_binary.(title)}
+          {key, to_binary.(upper), to_binary.(lower)}
         )
     end)
 
@@ -265,7 +265,7 @@ defmodule String.Unicode do
 
   {singles, tables} =
     compute_lookup.(
-      for {codepoint, _upper, lower, _title} <- codes,
+      for {codepoint, _upper, lower} <- codes,
           lower && lower != codepoint,
           codepoint not in conditional_downcase,
           do: {codepoint, lower}
@@ -352,7 +352,7 @@ defmodule String.Unicode do
 
   {singles, tables} =
     compute_lookup.(
-      for {codepoint, upper, _lower, _title} <- codes,
+      for {codepoint, upper, _lower} <- codes,
           upper && upper != codepoint,
           codepoint not in conditional_upcase,
           do: {codepoint, upper}
@@ -380,51 +380,6 @@ defmodule String.Unicode do
   end
 
   def upcase("", acc, _mode), do: IO.iodata_to_binary(:lists.reverse(acc))
-
-  # Titlecase once
-
-  def titlecase_once("", _mode), do: {"", ""}
-
-  # Turkic i -> İ
-  def titlecase_once(<<@letter_i, rest::binary>>, mode) do
-    char = if mode == :turkic, do: @letter_I_dot_above, else: @letter_I
-    {char, rest}
-  end
-
-  conditional_titlecase = [@letter_i]
-
-  {singles, tables} =
-    compute_lookup.(
-      for {codepoint, _upper, _lower, title} <- codes,
-          title && title != codepoint,
-          codepoint not in conditional_titlecase,
-          do: {codepoint, title}
-    )
-
-  for {codepoint, title} <- singles do
-    def titlecase_once(<<unquote(codepoint), rest::bits>>, _mode) do
-      {unquote(title), rest}
-    end
-  end
-
-  for {prefix, clauses} <- tables do
-    def titlecase_once(<<unquote(prefix), byte, rest::bits>>, _mode) do
-      value = case byte, do: unquote(clauses)
-      {value, rest}
-    end
-  end
-
-  def titlecase_once(<<char::utf8, rest::binary>>, _mode) do
-    if char >= ?a and char <= ?z do
-      {<<char - 32::utf8>>, rest}
-    else
-      {<<char::utf8>>, rest}
-    end
-  end
-
-  def titlecase_once(<<char, rest::binary>>, _mode) do
-    {<<char>>, rest}
-  end
 end
 
 defmodule String.Break do