time: add a thorough example for time.Format

People will still not look at it, but at least we will have a stronger defense.

Change-Id: Ieea6a3d42d06e1067e424e35b87dbcb01c9523cb
Reviewed-on: https://go-review.googlesource.com/7859Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/time/example_test.go

@@ -58,17 +58,127 @@ func ExampleDate() {
 }
 
 func ExampleTime_Format() {
-	// layout shows by example how the reference time should be represented.
-	const layout = "Jan 2, 2006 at 3:04pm (MST)"
-	t := time.Date(2009, time.November, 10, 15, 0, 0, 0, time.Local)
-	fmt.Println(t.Format(layout))
-	fmt.Println(t.UTC().Format(layout))
+	// 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)
+	}
+
+	// time.Time's Stringer method is useful without any format.
+	fmt.Println("default format:", t)
+
+	// Predefined constants in the package implement common layouts.
+	fmt.Println("Unix format:", t.Format(time.UnixDate))
+
+	// The time zone attached to the time value affects its output.
+	fmt.Println("Same, in UTC:", t.UTC().Format(time.UnixDate))
+
+	// The rest of this function demonstrates the properties of the
+	// layout string used in the format.
+
+	// The layout string used by the Parse function and Format method
+	// shows by example how the reference time should be represented.
+	// We stress that one must show how the reference time is formatted,
+	// not a time of the user's choosing. Thus each layout string is a
+	// representation of the time stamp,
+	//	Jan 2 15:04:05 2006 MST
+	// An easy way to remember this value is that it holds, when presented
+	// in this order, the values (lined up with the elements above):
+	//	  1 2  3  4  5    6  -7
+	// There are some wrinkles illustrated below.
+
+	// Most uses of Format and Parse use constant layout strings such as
+	// the ones defined in this package, but the interface is flexible,
+	// as these examples show.
+
+	// 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("%-15s %q gives %q\n", name, layout, got)
+	}
+
+	// Print a header in our output.
+	fmt.Printf("\nFormats:\n\n")
+
+	// A simple starter example.
+	do("Basic", "Mon Jan 2 15:04:05 MST 2006", "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 zero pad, if required.
+	do("Spaces", "<_2>", "< 7>")
+
+	// Similarly, a 0 indicates zero padding.
+	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")
+
+	// 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:
-	// Nov 10, 2009 at 3:00pm (PST)
-	// Nov 10, 2009 at 11:00pm (UTC)
+	// 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           "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"
+
 }
 
 func ExampleParse() {
+	// See the example for time.Format for a thorough description of how
+	// to define the layout string to parse a time.Time value; Parse and
+	// Format use the same model to describe their input and output.
+
 	// longForm shows by example how the reference time would be represented in
 	// the desired layout.
 	const longForm = "Jan 2, 2006 at 3:04pm (MST)"

src/time/format.go

@@ -680,10 +680,13 @@ func skip(value, prefix string) (string, error) {
 // would be interpreted if it were the value; it serves as an example of
 // the input format. The same interpretation will then be made to the
 // input string.
+//
 // Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
 // and convenient representations of the reference time. 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.
+// Also, the executable Example for time.Format demonstrates the working
+// of the layout string in detail and is a good reference.
 //
 // Elements omitted from the value are assumed to be zero or, when
 // zero is impossible, one, so parsing "3:04pm" returns the time