clarify the difference between math:floor and math:trunc

[krader1961]

What happened, and what did you expect to happen?

I happened to need math:trunc for some tests I was writing but looked at the documentation to confirm I didn't want math:floor. The current documentation differs only in the following regard. For math:trunc it says:

Outputs the integer portion of $number.

For math:floor it says:

Computes the greatest integer less than or equal to $number.

Those statements accurately document the difference in behavior. However, I believe most users will not understand the distinction. To be fair, the equivalent Go language documentation for its math package is no more clear about the distinction regarding the behavior of the two functions. Still, I think we can do better. Starting with both commands having a "see also" reference to the other since they are closely related. Each should also include a sentence along these lines:

Note that math:trunc rounds negative numbers upwards, and positive numbers downwards; i.e., both towards zero. math:floor rounds all numbers downwards; i.e., negative values towards -infinity and positive values towards zero.

Also, an explicit comparison of an expression such as math:floor -2.1 versus math:trunc -2.1 would be useful to drive the point home. Both expressions should in the examples for each command.

Output of "elvish -version"

0.21.0-dev.0.20240324064227-21ad1088765f

Code of Conduct

• I agree to follow Elvish's Code of Conduct.