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

Comments

Projects
None yet
4 participants
@timxzl
Copy link

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

This comment has been minimized.

Copy link
Member

commented Dec 15, 2016

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?

@timxzl

This comment has been minimized.

Copy link
Author

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

This comment has been minimized.

Copy link
Contributor

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 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.
You can’t perform that action at this time.