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 <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>

1 files changed, 56 insertions, 36 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,29 +252,8 @@ 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")
-
-	// 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.
-	// Here we print just the day, which is 2 in our layout string and 7 in our
-	// value.
-	do("No pad", "<2>", "<7>")
-
-	// An underscore represents a space pad, if the date only has one digit.
-	do("Spaces", "<_2>", "< 7>")
-
-	// A "0" indicates zero padding for single-digit values.
-	do("Zeros", "<02>", "<07>")
-
-	// If the value is already the right width, padding is not used.
-	// For instance, the second (05 in the reference time) in our value is 39,
-	// 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")
+	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
@@ -285,13 +264,13 @@ func ExampleTime_Format() {
 	// 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")
+	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, "Sat Mar  7 11:06:39 PST 2015")
+	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.
@@ -303,23 +282,64 @@ func ExampleTime_Format() {
 	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
+	// 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 "Sat Mar 7 11:06:39 PST 2015"
-	// Basic short date "2006/01/02" gives "2015/03/07"
+	// 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.
+	// Here we print just the day, which is 2 in our layout string and 7 in our
+	// value.
+	do("No pad", "<2>", "<7>")
+
+	// An underscore represents a space pad, if the date only has one digit.
+	do("Spaces", "<_2>", "< 7>")
+
+	// A "0" indicates zero padding for single-digit values.
+	do("Zeros", "<02>", "<07>")
+
+	// If the value is already the right width, padding is not used.
+	// For instance, the second (05 in the reference time) in our value is 39,
+	// so it doesn't need padding, but the minutes (04, 06) does.
+	do("Suppressed pad", "04:05", "06:39")
+
+	// Output:
+	// 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"
 
 }