This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author terry.reedy
Recipients Arthur-Milchior, docs@python, mark.dickinson, python-dev, rhettinger, terry.reedy
Date 2021-11-02.03:18:09
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1635823089.55.0.100996189687.issue45584@roundup.psfhosted.org>
In-reply-to
Content
Current docs:

math.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 Integral value.


math.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 Integral value.


math.trunc(x)
    Return the Real value x truncated to an Integral (usually an integer). Delegates to x.__trunc__().

Problems.
0. First sentence not parallel.
1. What does truncated mean?
2. What does 'Real' mean?
3. Delegation sentence not quite parallel.  Copy the ceil/floor version.

Current Proposal:

 Return the Real value *x* truncated to an 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__() <object.__trunc__>`.

We can't say "Return the truncation (which refers to the action, not the result).  "Return the truncated remains of x" would be accurate but begs the question about truncate.

I suggest instead:

"Return x with the fractional part removed, leaving the integer part.  This rounds toward 0.0 and is equivalent to floor and ceil for positive and negative x respectively.  If x is not a float, delegates to x.__trunc__(), which should return an Integral value."
History
Date User Action Args
2021-11-02 03:18:09terry.reedysetrecipients: + terry.reedy, rhettinger, mark.dickinson, docs@python, python-dev, Arthur-Milchior
2021-11-02 03:18:09terry.reedysetmessageid: <1635823089.55.0.100996189687.issue45584@roundup.psfhosted.org>
2021-11-02 03:18:09terry.reedylinkissue45584 messages
2021-11-02 03:18:09terry.reedycreate