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.
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
strconv: Atoi documentation is slightly misleading #29461
Comments
Genuine question: Why do you care? |
@josharian What's the point of having documentation if it's outdated? I don't see why it would be a problem to update it to reflect the current state of the code, or make it more "high level" so it doesn't end up getting outdated like this the next time it's changed. |
Please note that the point of the documentation is not to describe the way the function is implemented under the hood. The only purpose of the documentation associated with the function signature is to explain what the function does (in the sense: what will it return when you call it). So, in this case, the following sentence
is not telling you that the IMO the documentation appears "outdated" to you because you're reading it too literally. |
Anyway, here's a proposal for a slightly more high-level doc:
|
I'm sorry if I was a bit unclear. I never meant that I expected the comment to explain in great details what it did under the hood. I was just a bit surprised when the comment didn't match up with the reality. Afaik the "short path" is a lot faster than the ParseInt path, so there's a performance difference between Atoi and simply running ParseInt directly. |
Your honour, my client's statement never claimed that Atoi necessarily calls ParseInt, merely that it returns the same result as ParseInt. I move for a dismissal on the grounds that the defendant has no case to answer. |
@bitfield I didn't come here to argue. If no one else thinks it's an issue then fine, simply don't change it and close this issue. The documentation does claim that it returns the result of ParseInt, not the same result as ParseInt though. Which led me to believe that it simply called ParseInt (as it once did). Right now the documentation does try to explain what happens under the hood, but the documentation got outdated when the commit I linked to was introduced. |
Change https://golang.org/cl/155924 mentions this issue: |
It's been fixed! |
What version of Go are you using (
go version
)?Does this issue reproduce with the latest release?
Yes.
What operating system and processor architecture are you using (
go env
)?Irrelevant.
go env
OutputWhat did you do?
Look at the documentation here: https://golang.org/src/strconv/atoi.go?s=5013:5045#L192
What did you expect to see?
An explanation of
strconv.Atoi
that matched what it actually did.What did you see instead?
An explanation that is only half true.
Atoi returns the result of ParseInt(s, 10, 0) converted to type int.
It appears that
Atoi
doesn't just return the value ofParseInt(s, 10, 0)
, it only callsParseInt
as a last alternative, the "slow path". Without checking the code I was under the belief that I could just replaceAtoi
withParseInt
and it would basically run the exact same code.It appears that the documentation was correct up until this commit:
46aa9f5#diff-cbef0f4cdbfb7c355433bb342a5ef463
The text was updated successfully, but these errors were encountered: