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 145bac4966e18cc71b6e92f46cfa73771593e09b..7aa543ae5d47eaccc2d227954febb33f171b9e50 100644 (file)
--- 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 dcab3679b200c6c8aa6b50488a73969a7de8ed2e..ba7c456aa21565a80407dfca07d9306808d759f7 100644 (file)
--- 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 9eb455a5cb1973fe8187a6c1a8d3be7a468eb09c..da162844e202a07d77f3f630837c33f0c1ba5ce0 100644 (file)
--- 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 0cb738b3a12ee4ce8dcb90975f49d1d5886d1ce7..e8c99257ec611e08095345b4f73c6924aad700d1 100644 (file)
--- 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 (file)
index 0000000..f169a46
--- /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 a2a2db29be343d8eaef3106fc36d0f97bfa665bb..b3429c5653c958fef772defa5e4f783dfae9c4b7 100644 (file)
--- 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},