feat: add cbrt/1 (#23)

* feat: add cbrt/1

* docs: typos

* docs: arity

Author: polvalente

lib/complex.ex

@@ -740,7 +740,7 @@ defmodule Complex do
   @spec conjugate(t | number | non_finite_number) :: t | number | non_finite_number
   def conjugate(z)
 
-  def conjugate(n) when is_number(n), do: n
+  def conjugate(n) when is_number(n) or is_non_finite_number(n), do: n
 
   def conjugate(%Complex{re: r, im: :neg_infinity}), do: new(r, :infinity)
   def conjugate(%Complex{re: r, im: :infinity}), do: new(r, :neg_infinity)
@@ -756,7 +756,7 @@ defmodule Complex do
 
   ### See also
 
-  `abs/2`, `phase/1`
+  `abs/1`, `cbrt/1`, `phase/1`
 
   ### Examples
 
@@ -767,7 +767,7 @@ defmodule Complex do
   @spec sqrt(t | number | non_finite_number) :: t | number | non_finite_number
   def sqrt(z)
   def sqrt(:infinity), do: :infinity
-  def sqrt(:neg_infinity), do: Complex.new(0, :infinity)
+  def sqrt(:neg_infinity), do: :nan
   def sqrt(:nan), do: :nan
   def sqrt(n) when is_number(n), do: :math.sqrt(n)
 
@@ -807,6 +807,51 @@ defmodule Complex do
     end
   end
 
+  @doc """
+  Returns a new number that is the complex cube root of the provided
+  number.
+
+  Returns the principal branch of the cube root for complex inputs.
+
+  ### See also
+
+  `abs/1`, `phase/1`, `sqrt/1`
+
+  ### Examples
+
+      iex> Complex.cbrt(-8)
+      -2.0
+
+  When a negative number is given as a complex input,
+  the output now changes. Instead of still giving a
+  negative number, we now get a number with phase
+  $\\frac{\\pi}{3}$
+
+      iex> z = Complex.cbrt(Complex.new(-8, 0))
+      %Complex{re: 1.0000000000000002, im: 1.7320508075688772}
+      iex> Complex.abs(z)
+      2.0
+      iex> Complex.phase(z)
+      1.0471975511965976
+      iex> :math.pi() / 3
+      1.0471975511965976
+
+  """
+  @spec cbrt(t | number | non_finite_number) :: t | float() | non_finite_number
+  def cbrt(z)
+  def cbrt(:infinity), do: :infinity
+  def cbrt(:neg_infinity), do: :neg_infinity
+  def cbrt(:nan), do: :nan
+  def cbrt(n) when is_number(n) and n >= 0, do: :math.pow(n, 1 / 3)
+  def cbrt(n) when is_number(n), do: -1 * cbrt(abs(n))
+
+  def cbrt(z) do
+    r = abs(z)
+    theta = phase(z)
+
+    from_polar(cbrt(r), theta / 3)
+  end
+
   @doc """
   Returns a new complex that is the complex exponential of the provided
   complex number: $exp(z) = e^z$.

test/complex_test.exs

@@ -555,7 +555,7 @@ defmodule ComplexTest do
 
   test "sqrt (non-finite)" do
     assert Complex.sqrt(:infinity) == :infinity
-    assert Complex.sqrt(:neg_infinity) == Complex.new(0, :infinity)
+    assert Complex.sqrt(:neg_infinity) == :nan
     assert Complex.sqrt(:nan) == :nan
 
     assert Complex.sqrt(Complex.new(:infinity, 1)) == Complex.new(:infinity)