[Python-checkins] bpo-45584: Clarify `math.trunc` documentation (GH-29183)
JelleZijlstra
webhook-mailer at python.org
Sat Apr 2 18:11:28 EDT 2022
https://github.com/python/cpython/commit/ebbdbbff5d6840807e46ec61b8a323e94ee88de2
commit: ebbdbbff5d6840807e46ec61b8a323e94ee88de2
branch: main
author: Arthur Milchior <arthur at milchior.fr>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-04-02T15:11:20-07:00
summary:
bpo-45584: Clarify `math.trunc` documentation (GH-29183)
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)
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
Co-authored-by: Éric Araujo <merwok at netwok.org>
Co-authored-by: Terry Jan Reedy <tjreedy at udel.edu>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
files:
M Doc/library/math.rst
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index c0f9614231912..48030fae189ba 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__ <object.__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.__floor__ <object.__floor__>`, which
+ should return an :class:`~numbers.Integral` value.
.. function:: fmod(x, y)
@@ -298,9 +298,11 @@ 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__() <object.__trunc__>`.
+ 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__
+ <object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
.. function:: ulp(x)
More information about the Python-checkins
mailing list