Add specs and improve guards to Calendar.ISO.parse_*/2 functions (#11329)

Author: eksperimental

lib/elixir/lib/calendar/iso.ex

@@ -131,6 +131,8 @@ defmodule Calendar.ISO do
   unix_end = 315_569_519_999_999_999 - @unix_epoch * 1_000_000
   @unix_range_microseconds unix_start..unix_end
 
+  defguardp is_format(term) when term in [:basic, :extended]
+
   @typedoc """
   "Before the Current Era" or "Before the Common Era" (BCE), for those years less than `1`.
   """
@@ -157,6 +159,7 @@ defmodule Calendar.ISO do
   @type second :: 0..59
   @type weekday :: :monday | :tuesday | :wednesday | :thursday | :friday | :saturday | :sunday
   @type utc_offset :: integer
+  @type format :: :basic | :extended
 
   @typedoc """
   Microseconds with stored precision.
@@ -286,11 +289,15 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_time("T" <> string, format),
-    do: do_parse_time(string, format)
-
-  def parse_time(string, format) when is_binary(string),
-    do: do_parse_time(string, format)
+  @spec parse_time(String.t(), format) ::
+          {:ok, {hour, minute, second, microsecond}}
+          | {:error, atom}
+  def parse_time(string, format) when is_binary(string) and is_format(format) do
+    case string do
+      "T" <> rest -> do_parse_time(rest, format)
+      _ -> do_parse_time(string, format)
+    end
+  end
 
   defp do_parse_time(<<unquote(match_basic_time), rest::binary>>, :basic)
        when unquote(guard_time) do
@@ -363,13 +370,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_date("-" <> string, format),
+  @spec parse_date(String.t(), format) ::
+          {:ok, {year, month, day}}
+          | {:error, atom}
+  def parse_date(string, format) when is_binary(string) and is_format(format),
+    do: parse_date_guarded(string, format)
+
+  defp parse_date_guarded("-" <> string, format),
     do: do_parse_date(string, -1, format)
 
-  def parse_date("+" <> string, format),
+  defp parse_date_guarded("+" <> string, format),
     do: do_parse_date(string, 1, format)
 
-  def parse_date(string, format) when is_binary(string),
+  defp parse_date_guarded(string, format),
     do: do_parse_date(string, 1, format)
 
   defp do_parse_date(unquote(match_basic_date), multiplier, :basic) when unquote(guard_date) do
@@ -442,13 +455,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_naive_datetime("-" <> string, format),
+  @spec parse_naive_datetime(String.t(), format) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}}
+          | {:error, atom}
+  def parse_naive_datetime(string, format) when is_binary(string) and is_format(format),
+    do: parse_naive_datetime_guarded(string, format)
+
+  defp parse_naive_datetime_guarded("-" <> string, format),
     do: do_parse_naive_datetime(string, -1, format)
 
-  def parse_naive_datetime("+" <> string, format),
+  defp parse_naive_datetime_guarded("+" <> string, format),
     do: do_parse_naive_datetime(string, 1, format)
 
-  def parse_naive_datetime(string, format) when is_binary(string),
+  defp parse_naive_datetime_guarded(string, format),
     do: do_parse_naive_datetime(string, 1, format)
 
   defp do_parse_naive_datetime(
@@ -540,13 +559,19 @@ defmodule Calendar.ISO do
 
   """
   @doc since: "1.12.0"
-  def parse_utc_datetime("-" <> string, format),
+  @spec parse_utc_datetime(String.t(), format) ::
+          {:ok, {year, month, day, hour, minute, second, microsecond}, utc_offset}
+          | {:error, atom}
+  def parse_utc_datetime(string, format) when is_binary(string) and is_format(format),
+    do: parse_utc_datetime_guarded(string, format)
+
+  defp parse_utc_datetime_guarded("-" <> string, format),
     do: do_parse_utc_datetime(string, -1, format)
 
-  def parse_utc_datetime("+" <> string, format),
+  defp parse_utc_datetime_guarded("+" <> string, format),
     do: do_parse_utc_datetime(string, 1, format)
 
-  def parse_utc_datetime(string, format) when is_binary(string),
+  defp parse_utc_datetime_guarded(string, format),
     do: do_parse_utc_datetime(string, 1, format)
 
   defp do_parse_utc_datetime(

lib/elixir/test/elixir/calendar/iso_test.exs

@@ -148,8 +148,13 @@ defmodule Calendar.ISOTest do
     end
 
     test "errors on other format names" do
-      assert Calendar.ISO.parse_date("20150123", :other) == {:error, :invalid_format}
-      assert Calendar.ISO.parse_date("2015-01-23", :other) == {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_date("20150123", :other)
+      end
+
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_date("2015-01-23", :other)
+      end
     end
   end
 
@@ -226,8 +231,13 @@ defmodule Calendar.ISOTest do
     end
 
     test "errors on other format names" do
-      assert Calendar.ISO.parse_time("235007", :other) == {:error, :invalid_format}
-      assert Calendar.ISO.parse_time("23:50:07", :other) == {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_time("235007", :other)
+      end
+
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_time("23:50:07", :other)
+      end
     end
   end
 
@@ -308,11 +318,13 @@ defmodule Calendar.ISOTest do
     end
 
     test "errors on other format names" do
-      assert Calendar.ISO.parse_naive_datetime("20150123 235007.123", :other) ==
-               {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_naive_datetime("20150123 235007.123", :other)
+      end
 
-      assert Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.123", :other) ==
-               {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.123", :other)
+      end
     end
   end
 
@@ -393,11 +405,13 @@ defmodule Calendar.ISOTest do
     end
 
     test "errors on other format names" do
-      assert Calendar.ISO.parse_naive_datetime("20150123 235007.123Z", :other) ==
-               {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_naive_datetime("20150123 235007.123Z", :other)
+      end
 
-      assert Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.123Z", :other) ==
-               {:error, :invalid_format}
+      assert_raise FunctionClauseError, fn ->
+        Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.123Z", :other)
+      end
     end
 
     test "errors on mixed basic and extended formats" do