Terry J. Reedy added the comment:
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__() `.
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."
----------
nosy: +mark.dickinson, rhettinger, terry.reedy
versions: -Python 3.6, Python 3.7, Python 3.8
_______________________________________
Python tracker
https://bugs.python.org/issue45584
_______________________________________
Arthur Milchior