From e0a173dad8fb195549a55fa8f5364d7db20f0845 Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Sat, 23 Oct 2021 03:27:34 +0200 Subject: [PATCH 1/8] bpo-45584: Clarify the meaning of `truncate` in documentation While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) I assume that I won't be the only user having this trouble, especially for people whose mother tongue is not English. So I suggest adding a clarification to help make what should be obvious to most actually explicit --- Doc/library/math.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 71186788a652af..b10520c2a731b3 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -299,8 +299,10 @@ Number-theoretic and representation functions .. function:: trunc(x) Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Delegates to - :meth:`x.__trunc__() `. + :class:`~numbers.Integral` (usually an integer). Truncating *x* means + removing the digits after the decimal separator, hence rounding toward 0. It + is equivalent to floor and ceil for positive and negative numbers + respectively. Delegates to :meth:`x.__trunc__() `. .. function:: ulp(x) From afaa3a2488cb2b54e6b75ea7d87455f2e785eb5d Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Tue, 2 Nov 2021 05:21:58 +0100 Subject: [PATCH 2/8] Improved version of trunc documentation by Terry Reedy Source is https://bugs.python.org/issue45584#msg405481 --- Doc/library/math.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index b10520c2a731b3..ba49c95a386aed 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -298,11 +298,10 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Truncating *x* means - removing the digits after the decimal separator, hence rounding toward 0. It - is equivalent to floor and ceil for positive and negative numbers - respectively. Delegates to :meth:`x.__trunc__() `. + Return *x* with the fractional part removed, leaving the integer part. This + rounds toward 0 and is equivalent to floor and ceil for positive and negative + *x* respectively. If *x* is not a float, delegates to :meth:`x.__trunc__() + `, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x) From 02ca5d3248122ee0da4e8f0ac734b93d8b0156f9 Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Tue, 2 Nov 2021 14:36:49 +0100 Subject: [PATCH 3/8] Update Doc/library/math.rst Co-authored-by: Alex Waygood --- Doc/library/math.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index ba49c95a386aed..72ddbffedc628d 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -298,10 +298,12 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return *x* with the fractional part removed, leaving the integer part. This - rounds toward 0 and is equivalent to floor and ceil for positive and negative - *x* respectively. If *x* is not a float, delegates to :meth:`x.__trunc__() - `, which should return an :class:`~numbers.Integral` value. + Given a :class:`~numbers.Real` value *x*, return *x* with the fractional part + removed, leaving the integer part. This rounds toward 0: ``trunc()`` is + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` for + negative *x*. If *x* is not a float, ``trunc()`` delegates to + :meth:`x.__trunc__()`, which should return an + :class:`~numbers.Integral` value if properly defined. .. function:: ulp(x) From 2b0dc772a95e6c73dc33ce1fea8cae5055a7cbf1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Tue, 2 Nov 2021 11:14:46 -0400 Subject: [PATCH 4/8] add space --- Doc/library/math.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 72ddbffedc628d..1f8cd90f34dfe7 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -302,7 +302,7 @@ Number-theoretic and representation functions removed, leaving the integer part. This rounds toward 0: ``trunc()`` is equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` for negative *x*. If *x* is not a float, ``trunc()`` delegates to - :meth:`x.__trunc__()`, which should return an + :meth:`x.__trunc__ `, which should return an :class:`~numbers.Integral` value if properly defined. .. function:: ulp(x) From cbf5c61538399ae8494ca1eb30d654d1a0100fc9 Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Wed, 3 Nov 2021 03:55:27 +0100 Subject: [PATCH 5/8] Update Doc/library/math.rst Co-authored-by: Terry Jan Reedy --- Doc/library/math.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 1f8cd90f34dfe7..dddab9e2bd1cf5 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -301,9 +301,9 @@ Number-theoretic and representation functions Given a :class:`~numbers.Real` value *x*, return *x* with the fractional part removed, leaving the integer part. This rounds toward 0: ``trunc()`` is equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` for - negative *x*. If *x* is not a float, ``trunc()`` delegates to + negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ `, which should return an - :class:`~numbers.Integral` value if properly defined. + :class:`~numbers.Integral` value. .. function:: ulp(x) From af253eeaf16c22f4e8d6b8c1c11e1cfcf2ff96d0 Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Sat, 27 Nov 2021 03:23:58 +0100 Subject: [PATCH 6/8] ceil and floor documentation uses :meth: --- Doc/library/math.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index dddab9e2bd1cf5..b354652c8e7321 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -32,8 +32,8 @@ Number-theoretic and representation functions .. function:: ceil(x) Return the ceiling of *x*, the smallest integer greater than or equal to *x*. - If *x* is not a float, delegates to ``x.__ceil__()``, which should return an - :class:`~numbers.Integral` value. + If *x* is not a float, delegates to :meth:`x.__ceil__ `, + which should return an :class:`~numbers.Integral` value. .. function:: comb(n, k) @@ -77,9 +77,9 @@ Number-theoretic and representation functions .. function:: floor(x) - Return the floor of *x*, the largest integer less than or equal to *x*. - If *x* is not a float, delegates to ``x.__floor__()``, which should return an - :class:`~numbers.Integral` value. + Return the floor of *x*, the largest integer less than or equal to *x*. If + *x* is not a float, delegates to :meth:`x.__ceil__ `, which + should return an :class:`~numbers.Integral` value. .. function:: fmod(x, y) From 569cff7c739df527724cb7260f13d424f6f19f6d Mon Sep 17 00:00:00 2001 From: Arthur Milchior Date: Sat, 27 Nov 2021 03:27:15 +0100 Subject: [PATCH 7/8] correct --- Doc/library/math.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index b354652c8e7321..95d4b582fcdc59 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -78,7 +78,7 @@ Number-theoretic and representation functions .. function:: floor(x) Return the floor of *x*, the largest integer less than or equal to *x*. If - *x* is not a float, delegates to :meth:`x.__ceil__ `, which + *x* is not a float, delegates to :meth:`x.__floor__ `, which should return an :class:`~numbers.Integral` value. @@ -300,10 +300,9 @@ Number-theoretic and representation functions Given a :class:`~numbers.Real` value *x*, return *x* with the fractional part removed, leaving the integer part. This rounds toward 0: ``trunc()`` is - equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` for - negative *x*. If *x* is not a float, delegates to - :meth:`x.__trunc__ `, which should return an - :class:`~numbers.Integral` value. + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` + for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ + `, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x) From a00f4341149d4ca4c3efcbc8a9c53d3b5ab4ba23 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sat, 2 Apr 2022 14:25:08 -0700 Subject: [PATCH 8/8] Update Doc/library/math.rst Co-authored-by: Terry Jan Reedy --- Doc/library/math.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 95d4b582fcdc59..62c38863fad12a 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -298,7 +298,7 @@ Number-theoretic and representation functions .. function:: trunc(x) - Given a :class:`~numbers.Real` value *x*, return *x* with the fractional part + Return *x* with the fractional part removed, leaving the integer part. This rounds toward 0: ``trunc()`` is equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__