math: docs omit mention of IEEE 754 endianness

[seebs]

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

1.11 (but N/A)

Does this issue reproduce with the latest release?

yes

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

amd64 (but N/A)

What did you do?

Read pkg/math's documentation.

What did you expect to see?

Enough information to determine what bits to expect from Float64bits and/or Float32bits (and the bits going the other way, too).

What did you see instead?

Just enough information to guess that it's almost certainly either little-endian or big-endian, and may or may not depend on the host architecture.

What I'd like to know is, to a first approximation: Will the sign bit be 0x80, 0x1, or 0x8000000? Probably! My default guess would be that byte order would be the same as it is for ints, thus, 0x80000000. But it'd be nice to have that explicit. If I weren't used to Intel, I'd expect the sign bit to be the first bit "in memory", meaning that out of a 64-bit float, it would be the bit in the byte with the same address as the whole float, which would be 0x80. It's not, apparently, according to go playground. And that makes sense for Intel CPUs, but I don't know whether it's portable to non-x86 (don't have a go arm64 handy to test on), and I don't know whether it's actually specified or just happens to work out that way.

[ianlancetaylor]

The sign bit of the floating point number should be the high bit of the integer. This playground program shows that it is: https://play.golang.org/p/znPKas85NPk . What program are you running that suggests that it isn't?

[seebs]

Sorry, I don't think I explained my confusion well. I haven't seen anything suggesting that we don't get the sign bit in the high bit of the integer; that seems to be what happens on the system I can test on. But I don't see anything specifying that, and I believe there have existed been machines where the sign bit of a float was the highest bit of the lowest-addressed byte, but where integers were little-endian. (And possibly the other way around, for that matter.) So if go were implemented on such a machine, I don't know whether I would have to watch out for that.

Basically: If I had a 64-bit hunk of memory, and the first bit were the sign bit of a float, and I memcpyd the bits over an int64, the sign bit would be 0x80. That isn't what happens on x86 with go, luckily for me. :)

[ianlancetaylor]

The intent is that the sign bit of the floating point number should correspond to the most significant bit of the integer. I agree that this should be documented.

[gopherbot]

Change https://golang.org/cl/145205 mentions this issue: math: document Float*bits and Float*frombits to specify the order of bits

[gopherbot]

Change https://golang.org/cl/153057 mentions this issue: math: document sign bit correspondence for floating-point/bits conversions