Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

math/big: SetMantExp doc comment unclear #47879

Closed
darkfeline opened this issue Aug 22, 2021 · 3 comments
Closed

math/big: SetMantExp doc comment unclear #47879

darkfeline opened this issue Aug 22, 2021 · 3 comments
Labels
FrozenDueToAge

Comments

@darkfeline
Copy link
Contributor

darkfeline commented Aug 22, 2021 •
edited
Loading

https://cs.opensource.google/go/go/+/master:src/math/big/float.go;l=309

Hopefully I'm not having a moment of stupidity, but the example for SetMantExp doesn't make sense to me:

// SetMantExp sets z to mant × 2**exp and returns z.
// The result z has the same precision and rounding mode
// as mant. SetMantExp is an inverse of MantExp but does
// not require 0.5 <= |mant| < 1.0. Specifically:
//
//	mant := new(Float)
//	new(Float).SetMantExp(mant, x.MantExp(mant)).Cmp(x) == 0

What is x here? I assume that it is an arbitrary *Float, although it would be good if that were stated explicitly.

This is saying that

mant := new(Float)
new(Float).SetMantExp(mant, x.MantExp(mant))

is equal to x (.Cmp(x) == 0).

new(Float).SetMantExp(mant, x.MantExp(mant)) looks like it should be a zero *Float since mant is a zero *Float. The exponent is set to the same as x (and mant is set to the mantissa of x although not used later) but that does not matter since the mantissa is zero. Based off my algebra skills from a long time ago, x should be a zero *Float then, to satisfy this example.

What exactly is this example supposed to demonstrate? If it is just demonstrating using a mantissa outside of [0.5, 1), I can think of many clearer examples.
@robpike
Copy link
Contributor

robpike commented Aug 22, 2021

What it's saying is that for any x, you can deconstruct it with MantExp and reconstruct it with SetMantExp. The call to MantExp will happen first, setting Mant to the mantissa of x and returning the exponent. The arguments to SetMantExp are therefore the mantissa and exponent of x, so the call recreates x, stores it in the new Float, and Cmp returns 0.

I didn't know this until I read the documentation. It's concise but accurate. It probably needs a phrase such as "given x".

@darkfeline
Copy link
Contributor Author

darkfeline commented Aug 22, 2021 •
edited
Loading

Ah right, because mant is a pointer. I don't encounter this pattern often (where a pointer argument in a call expression gets mutated by a succeeding expression argument). Ignoring my failure of code comprehension, I think adding some explanatory text would be helpful, e.g., "To reconstruct a Float from the results of a MantExp call, one could do:".

Actually, is this example useful? It isn't particularly difficult to see how one might pass in the results of MantExp to SetMantExp

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/344249 mentions this issue: math/big: clarified doc string for SetMantExp

@golang golang locked and limited conversation to collaborators Jun 23, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@darkfeline @robpike @griesemer @gopherbot