Commit 8537ccdd authored by Rob Pike's avatar Rob Pike Committed by Gerrit Code Review

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: 's avatarBrad Fitzpatrick <bradfitz@golang.org>
parent 28074d5b
...@@ -58,17 +58,127 @@ func ExampleDate() { ...@@ -58,17 +58,127 @@ func ExampleDate() {
} }
func ExampleTime_Format() { func ExampleTime_Format() {
// layout shows by example how the reference time should be represented. // Parse a time value from a string in the standard Unix format.
const layout = "Jan 2, 2006 at 3:04pm (MST)" t, err := time.Parse(time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
t := time.Date(2009, time.November, 10, 15, 0, 0, 0, time.Local) if err != nil { // Always check errors even if they should not happen.
fmt.Println(t.Format(layout)) panic(err)
fmt.Println(t.UTC().Format(layout)) }
// 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: // Output:
// Nov 10, 2009 at 3:00pm (PST) // default format: 2015-03-07 11:06:39 -0800 PST
// Nov 10, 2009 at 11:00pm (UTC) // 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() { 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 // longForm shows by example how the reference time would be represented in
// the desired layout. // the desired layout.
const longForm = "Jan 2, 2006 at 3:04pm (MST)" const longForm = "Jan 2, 2006 at 3:04pm (MST)"
......
...@@ -680,10 +680,13 @@ func skip(value, prefix string) (string, error) { ...@@ -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 // 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 // the input format. The same interpretation will then be made to the
// input string. // input string.
//
// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard // Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
// and convenient representations of the reference time. For more information // and convenient representations of the reference time. For more information
// about the formats and the definition of the reference time, see the // about the formats and the definition of the reference time, see the
// documentation for ANSIC and the other constants defined by this package. // 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 // Elements omitted from the value are assumed to be zero or, when
// zero is impossible, one, so parsing "3:04pm" returns the time // zero is impossible, one, so parsing "3:04pm" returns the time
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment