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>

diff --git a/src/time/example_test.go b/src/time/example_test.go
index fe8e042d694774a6c460c306446a9df453c51a30..f272ee44dfff7fe467b7f0838ec29c4e57ac91fe 100644 (file)
--- 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"
 
 }