From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Date: Mon, 4 Nov 2024 04:16:35 +0000 (+0100) Subject: [3.12] gh-126165: Improve docs of function `math.isclose` (GH-126215) (#126381) X-Git-Tag: v3.12.8~115 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d1b87189348eb4554fe7b468d1bd331f4f4345ea;p=thirdparty%2FPython%2Fcpython.git [3.12] gh-126165: Improve docs of function `math.isclose` (GH-126215) (#126381) gh-126165: Improve docs of function `math.isclose` (GH-126215) (cherry picked from commit 081706f873b7d1a10b27016a9ed350b20c719709) Co-authored-by: Zhikang Yan <2951256653@qq.com> Co-authored-by: Sergey B Kirpichev Co-authored-by: Carol Willing Co-authored-by: Terry Jan Reedy --- diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst index 381a8332f4b1..f122e3644ece 100644 --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -221,19 +221,21 @@ Classification functions ``False`` otherwise. Whether or not two values are considered close is determined according to - given absolute and relative tolerances. + given absolute and relative tolerances. If no errors occur, the result will + be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. *rel_tol* is the relative tolerance -- it is the maximum allowed difference between *a* and *b*, relative to the larger absolute value of *a* or *b*. For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default tolerance is ``1e-09``, which assures that the two values are the same - within about 9 decimal digits. *rel_tol* must be greater than zero. - - *abs_tol* is the minimum absolute tolerance -- useful for comparisons near - zero. *abs_tol* must be at least zero. - - If no errors occur, the result will be: - ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. + within about 9 decimal digits. *rel_tol* must be nonnegative and less + than ``1.0``. + + *abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be + nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed + as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and + rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument + to the call. The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be handled according to IEEE rules. Specifically, ``NaN`` is not considered diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 40742fdafeac..fb8527128a25 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -142,19 +142,21 @@ Number-theoretic and representation functions ``False`` otherwise. Whether or not two values are considered close is determined according to - given absolute and relative tolerances. + given absolute and relative tolerances. If no errors occur, the result will + be: ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. *rel_tol* is the relative tolerance -- it is the maximum allowed difference between *a* and *b*, relative to the larger absolute value of *a* or *b*. For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default tolerance is ``1e-09``, which assures that the two values are the same - within about 9 decimal digits. *rel_tol* must be greater than zero. - - *abs_tol* is the minimum absolute tolerance -- useful for comparisons near - zero. *abs_tol* must be at least zero. - - If no errors occur, the result will be: - ``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``. + within about 9 decimal digits. *rel_tol* must be nonnegative and less + than ``1.0``. + + *abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be + nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed + as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and + rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument + to the call. The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be handled according to IEEE rules. Specifically, ``NaN`` is not considered