From 4978f5e6ea0ba74264b562a3c9ee62dcb63aae45 Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Sat, 29 Feb 2020 17:35:51 -0700 Subject: [PATCH] time: use values larger than 24 for day for time.Format examples 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 TryBot-Result: Gobot Gobot Reviewed-by: Ian Lance Taylor Reviewed-by: Rob Pike --- src/time/example_test.go | 112 +++++++++++++++++++++++---------------- 1 file changed, 66 insertions(+), 46 deletions(-) diff --git a/src/time/example_test.go b/src/time/example_test.go index fe8e042d69..f272ee44df 100644 --- a/src/time/example_test.go +++ b/src/time/example_test.go @@ -206,7 +206,7 @@ func ExampleNewTicker() { func ExampleTime_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. panic(err) } @@ -252,8 +252,70 @@ func ExampleTime_Format() { fmt.Printf("\nFormats:\n\n") // 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 short date", "2006/01/02", "2015/03/07") + 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/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 // 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. 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: - // default format: 2015-03-07 11:06:39 -0800 PST - // 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" + // Unix "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015" // No pad "<2>" gives "<7>" // Spaces "<_2>" gives "< 7>" // Zeros "<02>" gives "<07>" // 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" }