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/7859
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
diff --git a/src/time/example_test.go b/src/time/example_test.go
index a37e8b8..f76fdcd 100644
--- a/src/time/example_test.go
+++ b/src/time/example_test.go
@@ -58,17 +58,127 @@
}
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)"
diff --git a/src/time/format.go b/src/time/format.go
index 3d2ff37..5716108 100644
--- a/src/time/format.go
+++ b/src/time/format.go
@@ -680,10 +680,13 @@
// 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
