qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-23 12:20:12 -07:00
Code Releases Activity

time: use values larger than 24 for day for time.Format examples

Browse Source 
Currently, the time.Format docs use 7 Mar 2015 as the day/month/year. In numeric
form, that is either 7/3/2015 or 3/7/2015 depending on which part of the world
you're from. This is extremely confusing.

In fact, the reference time being defined in a very US-centric way is quite
confusing for the rest of the world, too [1].

We can't change that, but we can make the time.Format docs more comprehendable
to the rest of the world without sacrificing by simply choosing a day that is
not ambiguous (a value greater than 24 for day). This CL does makes the
necessary change.

Note: this CL moves some of the padding examples into their own example, since
those examples do need a <10 day to demonstrate padding.

1: Additional context: a very old golang-nuts thread in which Rob expresses some
regret about the format being the USA standard, rather than the alternative:
https://groups.google.com/forum/m/#!msg/golang-nuts/0nQbfyNzk9E/LWbMgpRQNOgJ.

Change-Id: If0a07c5e0dab86f8420cbf59543405eb857aa7f2
Reviewed-on: https://go-review.googlesource.com/c/go/+/221612
Run-TryBot: Jean de Klerk <deklerk@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
This commit is contained in:
Jean de Klerk 2020-02-29 17:35:51 -07:00 committed by Rob Pike
parent 529988d62c
commit 4978f5e6ea
1 changed files with 66 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
src/time/example_test.go
View File

@ -206,7 +206,7 @@ func ExampleNewTicker() {
func ExampleTime_Format() { func ExampleTime_Format() {
// Parse a time value from a string in the standard Unix format. // Parse a time value from a string in the standard Unix format.
t, err := time.Parse(time.UnixDate, "Sat Mar 7 11:06:39 PST 2015") t, err := time.Parse(time.UnixDate, "Wed Feb 25 11:06:39 PST 2015")
if err != nil { // Always check errors even if they should not happen. if err != nil { // Always check errors even if they should not happen.
panic(err) panic(err)
} }
@ -252,8 +252,70 @@ func ExampleTime_Format() {
fmt.Printf("\nFormats:\n\n") fmt.Printf("\nFormats:\n\n")
// Simple starter examples. // Simple starter examples.
do("Basic full date", "Mon Jan 2 15:04:05 MST 2006", "Sat Mar 7 11:06:39 PST 2015") do("Basic full date", "Mon Jan 2 15:04:05 MST 2006", "Wed Feb 25 11:06:39 PST 2015")
do("Basic short date", "2006/01/02", "2015/03/07") do("Basic short date", "2006/01/02", "2015/02/25")
// The hour of the reference time is 15, or 3PM. The layout can express
// it either way, and since our value is the morning we should see it as
// an AM time. We show both in one format string. Lower case too.
do("AM/PM", "3PM==3pm==15h", "11AM==11am==11h")
// When parsing, if the seconds value is followed by a decimal point
// and some digits, that is taken as a fraction of a second even if
// the layout string does not represent the fractional second.
// Here we add a fractional second to our time value used above.
t, err = time.Parse(time.UnixDate, "Wed Feb 25 11:06:39.1234 PST 2015")
if err != nil {
panic(err)
}
// It does not appear in the output if the layout string does not contain
// a representation of the fractional second.
do("No fraction", time.UnixDate, "Wed Feb 25 11:06:39 PST 2015")
// Fractional seconds can be printed by adding a run of 0s or 9s after
// a decimal point in the seconds value in the layout string.
// If the layout digits are 0s, the fractional second is of the specified
// width. Note that the output has a trailing zero.
do("0s for fraction", "15:04:05.00000", "11:06:39.12340")
// If the fraction in the layout is 9s, trailing zeros are dropped.
do("9s for fraction", "15:04:05.99999999", "11:06:39.1234")
// Output:
// default format: 2015-02-25 11:06:39 -0800 PST
// Unix format: Wed Feb 25 11:06:39 PST 2015
// Same, in UTC: Wed Feb 25 19:06:39 UTC 2015
//
// Formats:
//
// Basic full date "Mon Jan 2 15:04:05 MST 2006" gives "Wed Feb 25 11:06:39 PST 2015"
// Basic short date "2006/01/02" gives "2015/02/25"
// AM/PM "3PM==3pm==15h" gives "11AM==11am==11h"
// No fraction "Mon Jan _2 15:04:05 MST 2006" gives "Wed Feb 25 11:06:39 PST 2015"
// 0s for fraction "15:04:05.00000" gives "11:06:39.12340"
// 9s for fraction "15:04:05.99999999" gives "11:06:39.1234"
}
func ExampleTime_Format_pad() {
// Parse a time value from a string in the standard Unix format.
t, err := time.Parse(time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
if err != nil { // Always check errors even if they should not happen.
panic(err)
}
// Define a helper function to make the examples' output look nice.
do := func(name, layout, want string) {
got := t.Format(layout)
if want != got {
fmt.Printf("error: for %q got %q; expected %q\n", layout, got, want)
return
}
fmt.Printf("%-16s %q gives %q\n", name, layout, got)
}
// The predefined constant Unix uses an underscore to pad the day.
do("Unix", time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
// For fixed-width printing of values, such as the date, that may be one or // For fixed-width printing of values, such as the date, that may be one or
// two characters (7 vs. 07), use an _ instead of a space in the layout string. // two characters (7 vs. 07), use an _ instead of a space in the layout string.
@ -272,54 +334,12 @@ func ExampleTime_Format() {
// so it doesn't need padding, but the minutes (04, 06) does. // so it doesn't need padding, but the minutes (04, 06) does.
do("Suppressed pad", "04:05", "06:39") do("Suppressed pad", "04:05", "06:39")
// The predefined constant Unix uses an underscore to pad the day.
// Compare with our simple starter example.
do("Unix", time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
// The hour of the reference time is 15, or 3PM. The layout can express
// it either way, and since our value is the morning we should see it as
// an AM time. We show both in one format string. Lower case too.
do("AM/PM", "3PM==3pm==15h", "11AM==11am==11h")
// When parsing, if the seconds value is followed by a decimal point
// and some digits, that is taken as a fraction of a second even if
// the layout string does not represent the fractional second.
// Here we add a fractional second to our time value used above.
t, err = time.Parse(time.UnixDate, "Sat Mar 7 11:06:39.1234 PST 2015")
if err != nil {
panic(err)
}
// It does not appear in the output if the layout string does not contain
// a representation of the fractional second.
do("No fraction", time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
// Fractional seconds can be printed by adding a run of 0s or 9s after
// a decimal point in the seconds value in the layout string.
// If the layout digits are 0s, the fractional second is of the specified
// width. Note that the output has a trailing zero.
do("0s for fraction", "15:04:05.00000", "11:06:39.12340")
// If the fraction in the layout is 9s, trailing zeros are dropped.
do("9s for fraction", "15:04:05.99999999", "11:06:39.1234")
// Output: // Output:
// default format: 2015-03-07 11:06:39 -0800 PST // Unix "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015"
// Unix format: Sat Mar 7 11:06:39 PST 2015
// Same, in UTC: Sat Mar 7 19:06:39 UTC 2015
//
// Formats:
//
// Basic full date "Mon Jan 2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015"
// Basic short date "2006/01/02" gives "2015/03/07"
// No pad "<2>" gives "<7>" // No pad "<2>" gives "<7>"
// Spaces "<_2>" gives "< 7>" // Spaces "<_2>" gives "< 7>"
// Zeros "<02>" gives "<07>" // Zeros "<02>" gives "<07>"
// Suppressed pad "04:05" gives "06:39" // Suppressed pad "04:05" gives "06:39"
// Unix "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015"
// AM/PM "3PM==3pm==15h" gives "11AM==11am==11h"
// No fraction "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015"
// 0s for fraction "15:04:05.00000" gives "11:06:39.12340"
// 9s for fraction "15:04:05.99999999" gives "11:06:39.1234"
} }