math: Document behavior of math.Ceil

[kevinburkeshyp]

Please answer these questions before submitting your issue. Thanks!

1. What version of Go are you using (go version)?

Tip

1. What operating system and processor architecture are you using (go env)?

Doesn't matter

1. What did you do?

The documentation for math.Ceil states:

Ceil returns the least integer value greater than or equal to x.

As far as I know, float representations of numbers can approximate integers but may not be land on them exactly. Also, as far as I know, casting a float to an integer always rounds down, e.g. int64(5.999999999) == 5.

I am worried there could be a situation where math.Ceil(N) could return a float like floor(N).999999999999999999, and this gets cast to an integer and returns a number lower than N. It would be nice if this was explicitly documented.

I'm also confused about why math.Ceil doesn't return an int64, though I'm sure there's a good reason for it. It would be nice if there was information about how to convert this value to an integer. (I am aware there are edge cases around large or small numbers, in this case I'm mostly worried about the values between 2^-30 and 2^30).

[kostya-sh]

All integers that can be represented as float64 (up to math.MaxFloat64) are represented exactly. 0.999999999 is not an integer. Such value cannot be returned from math.Ceil. 1.0 is an integer.

Note however not all integers can be represented as float64 value.

All integers with an absolute value <= 2^53 are ok. Greater than that only some integers are representable. E.g. 2^53+1 cannot be represened as float64. This has nothing to do with math.Ceil though.

[adg]

What @kostya-sh is accurate. I don't think there's anything to document here, so I'll close the issue.

I'm also confused about why math.Ceil doesn't return an int64

Because all the math functions operate on float64 values.