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.

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

time: comment to Time.Format() does not explain what nines (.999) mean #18330

Closed
timxzl opened this issue Dec 15, 2016 · 3 comments
Closed

time: comment to Time.Format() does not explain what nines (.999) mean #18330

timxzl opened this issue Dec 15, 2016 · 3 comments
Labels
FrozenDueToAge WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.

Comments

@timxzl
Copy link

timxzl commented Dec 15, 2016

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

1.7.4

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

linux/amd64

What did you do?

Try to figure out what the nines mean in the definition of Time.String() function
"2006-01-02 15:04:05.999999999 -0700 MST"
It says this layout string is passed to Time.Format(), but the comment of Time.Format() does not explain the "nines" style.

What did you expect to see?

A brief explanation of the "nines" style should be right after the explanation of the "zeros" style in the comment to Time.Format().

What did you see instead?

Only places that explain the "nines": Example of Time.Format(), which is lengthy and you have to navigate to the end of the example to see nines, and the comment to "Constants", which is far from Format() or String().

@bradfitz
Copy link
Contributor

The docs already say:

A decimal point followed by one or more zeros represents a fractional second, printed to the given number of decimal places. A decimal point followed by one or more nines represents a fractional second, printed to the given number of decimal places, with trailing zeros removed. When parsing (only), the input may contain a fractional second field immediately after the seconds field, even if the layout does not signify its presence. In that case a decimal point followed by a maximal series of digits is parsed as a fractional second.

Is that sufficient?

@bradfitz bradfitz added the WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided. label Dec 15, 2016
@timxzl
Copy link
Author

timxzl commented Dec 15, 2016

I meant that the above explanation was under the "Constants" section, which might be overlooked by new users (I admit that I haven't noticed it until recently). Wouldn't it be nice if some brief explanation, or a pointer to the "Constants" section, is present right under "Format"?

Of course, I won't object if you decide that the information is already sufficient.

@rsc
Copy link
Contributor

rsc commented Jan 4, 2017

The docs for time.Format also say:

For more information about the formats and the definition of the reference time, see the documentation for ANSIC and the other constants defined by this package.

I think this is enough.

@rsc rsc closed this as completed Jan 4, 2017
@golang golang locked and limited conversation to collaborators Jan 4, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.
Projects
None yet
Development

No branches or pull requests

4 participants