From: Ajith Ramachandran <ajithar204@gmail.com>
Date: Thu, 10 Jun 2021 16:42:09 +0000 (+0530)
Subject: bpo-44357:Add `math.cbrt()` function: Cube Root (GH-26622)
X-Git-Tag: v3.11.0a1~891
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ac867f10b49322e25f34d2d8abd8e63c86834750;p=thirdparty%2FPython%2Fcpython.git

bpo-44357:Add `math.cbrt()` function: Cube Root (GH-26622)

* Add math.cbrt() function: Cube Root

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Mark Dickinson <dickinsm@gmail.com>
---

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 145bac4966e1..7aa543ae5d47 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -342,6 +342,13 @@ necessarily has no fractional bits.
 Power and logarithmic functions
 -------------------------------
 
+.. function:: cbrt(x)
+
+   Return the cube root of *x*.
+
+   .. versionadded:: 3.11
+
+
 .. function:: exp(x)
 
    Return *e* raised to the power *x*, where *e* = 2.718281... is the base
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index dcab3679b200..ba7c456aa215 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -93,6 +93,13 @@ Support :PEP:`515`-style initialization of :class:`~fractions.Fraction` from
 string.  (Contributed by Sergey B Kirpichev in :issue:`44258`.)
 
 
+math
+----
+
+Add :func:`math.cbrt()`: return the cube root of x.
+(Contributed by Ajith Ramachandran in :issue:`44357`.)
+
+
 Removed
 =======
 * :class:`smtpd.MailmanProxy` is now removed as it is unusable without
diff --git a/Lib/test/test_math.py b/Lib/test/test_math.py
index 9eb455a5cb19..da162844e202 100644
--- a/Lib/test/test_math.py
+++ b/Lib/test/test_math.py
@@ -377,6 +377,22 @@ class MathTests(unittest.TestCase):
         self.assertTrue(math.isnan(math.atan2(NAN, INF)))
         self.assertTrue(math.isnan(math.atan2(NAN, NAN)))
 
+    def testCbrt(self):
+        self.assertRaises(TypeError, math.cbrt)
+        self.ftest('cbrt(0)', math.cbrt(0), 0)
+        self.ftest('cbrt(1)', math.cbrt(1), 1)
+        self.ftest('cbrt(8)', math.cbrt(8), 2)
+        self.ftest('cbrt(0.0)', math.cbrt(0.0), 0.0)
+        self.ftest('cbrt(-0.0)', math.cbrt(-0.0), -0.0)
+        self.ftest('cbrt(1.2)', math.cbrt(1.2), 1.062658569182611)
+        self.ftest('cbrt(-2.6)', math.cbrt(-2.6), -1.375068867074141)
+        self.ftest('cbrt(27)', math.cbrt(27), 3)
+        self.ftest('cbrt(-1)', math.cbrt(-1), -1)
+        self.ftest('cbrt(-27)', math.cbrt(-27), -3)
+        self.assertEqual(math.cbrt(INF), INF)
+        self.assertEqual(math.cbrt(NINF), NINF)
+        self.assertTrue(math.isnan(math.cbrt(NAN)))
+
     def testCeil(self):
         self.assertRaises(TypeError, math.ceil)
         self.assertEqual(int, type(math.ceil(0.5)))
diff --git a/Misc/ACKS b/Misc/ACKS
index 0cb738b3a12e..e8c99257ec61 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1415,6 +1415,7 @@ Jérôme Radix
 Burton Radons
 Abhilash Raj
 Shorya Raj
+Ajith Ramachandran
 Dhushyanth Ramasamy
 Ashwin Ramaswami
 Jeff Ramnani
diff --git a/Misc/NEWS.d/next/Library/2021-06-09-08-32-39.bpo-44357.70Futb.rst b/Misc/NEWS.d/next/Library/2021-06-09-08-32-39.bpo-44357.70Futb.rst
new file mode 100644
index 000000000000..f169a464f9fe
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-06-09-08-32-39.bpo-44357.70Futb.rst
@@ -0,0 +1 @@
+Added a function that returns cube root of the given number :func:`math.cbrt`
\ No newline at end of file
diff --git a/Modules/mathmodule.c b/Modules/mathmodule.c
index a2a2db29be34..b3429c5653c9 100644
--- a/Modules/mathmodule.c
+++ b/Modules/mathmodule.c
@@ -1182,6 +1182,9 @@ FUNC2(atan2, m_atan2,
 FUNC1(atanh, m_atanh, 0,
       "atanh($module, x, /)\n--\n\n"
       "Return the inverse hyperbolic tangent of x.")
+FUNC1(cbrt, cbrt, 0,
+      "cbrt($module, x, /)\n--\n\n"
+      "Return the cube root of x.")
 
 /*[clinic input]
 math.ceil
@@ -3550,6 +3553,7 @@ static PyMethodDef math_methods[] = {
     {"atan",            math_atan,      METH_O,         math_atan_doc},
     {"atan2",           (PyCFunction)(void(*)(void))math_atan2,     METH_FASTCALL,  math_atan2_doc},
     {"atanh",           math_atanh,     METH_O,         math_atanh_doc},
+    {"cbrt",            math_cbrt,      METH_O,         math_cbrt_doc},
     MATH_CEIL_METHODDEF
     {"copysign",        (PyCFunction)(void(*)(void))math_copysign,  METH_FASTCALL,  math_copysign_doc},
     {"cos",             math_cos,       METH_O,         math_cos_doc},