From c2857890591eb1cd2b0fbd54deabd109330674c8 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 22 Apr 2013 11:36:17 -0700 Subject: [PATCH] time: improve the explanation of the working of Format and Parse Change the term 'standard time', which already means something, to 'reference time', and add a couple of sentences and clarifications. R=golang-dev, bradfitz CC=golang-dev https://golang.org/cl/8799047 --- src/pkg/time/example_test.go | 11 +++++++--- src/pkg/time/format.go | 41 +++++++++++++++++++++--------------- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/src/pkg/time/example_test.go b/src/pkg/time/example_test.go index 8928caabab..cfa5b38c5f 100644 --- a/src/pkg/time/example_test.go +++ b/src/pkg/time/example_test.go @@ -58,20 +58,25 @@ func ExampleDate() { } func ExampleTime_Format() { - const format = "Jan 2, 2006 at 3:04pm (MST)" + // 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(format)) - fmt.Println(t.UTC().Format(format)) + fmt.Println(t.Format(layout)) + fmt.Println(t.UTC().Format(layout)) // Output: // Nov 10, 2009 at 3:00pm (PST) // Nov 10, 2009 at 11:00pm (UTC) } func ExampleParse() { + // longForm shows by example how the reference time would be represented in + // the desired layout. const longForm = "Jan 2, 2006 at 3:04pm (MST)" t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)") fmt.Println(t) + // shortForm is another way the reference time would be represented + // in the desired layout; it has no time zone present. // Note: without explicit zone, returns time in UTC. const shortForm = "2006-Jan-02" t, _ = time.Parse(shortForm, "2013-Feb-03") diff --git a/src/pkg/time/format.go b/src/pkg/time/format.go index 817c79a801..f18ea62f60 100644 --- a/src/pkg/time/format.go +++ b/src/pkg/time/format.go @@ -6,15 +6,17 @@ package time import "errors" -// These are predefined layouts for use in Time.Format. -// The standard time used in the layouts is: +// These are predefined layouts for use in Time.Format and Time.Parse. +// The reference time used in the layouts is: // Mon Jan 2 15:04:05 MST 2006 // which is Unix time 1136239445. Since MST is GMT-0700, -// the standard time can be thought of as +// the reference time can be thought of as // 01/02 03:04:05PM '06 -0700 -// To define your own format, write down what the standard time would look +// To define your own format, write down what the reference time would look // like formatted your way; see the values of constants like ANSIC, -// StampMicro or Kitchen for examples. +// StampMicro or Kitchen for examples. The model is to demonstrate what the +// reference time looks like so that the Format and Parse methods can apply +// the same transformation to a general time value. // // Within the format string, an underscore _ represents a space that may be // replaced by a digit if the following number (a day) has two digits; for @@ -367,13 +369,16 @@ func (t Time) String() string { } // Format returns a textual representation of the time value formatted -// according to layout. The layout defines the format by showing the -// representation of the standard time, +// according to layout, which defines the format by showing how the reference +// time, // Mon Jan 2 15:04:05 -0700 MST 2006 -// which is then used to describe the time to be formatted. Predefined -// layouts ANSIC, UnixDate, RFC3339 and others describe standard -// representations. For more information about the formats and the -// definition of the standard time, see the documentation for ANSIC. +// would be displayed if it were the value; it serves as an example of the +// desired output. The same display rules will then be aplied to the time +// value. +// 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. func (t Time) Format(layout string) string { var ( name, offset, abs = t.locabs() @@ -627,13 +632,15 @@ func skip(value, prefix string) (string, error) { } // Parse parses a formatted string and returns the time value it represents. -// The layout defines the format by showing the representation of the -// standard time, +// The layout defines the format by showing how the reference time, // Mon Jan 2 15:04:05 -0700 MST 2006 -// which is then used to describe the string to be parsed. Predefined layouts -// ANSIC, UnixDate, RFC3339 and others describe standard representations. For -// more information about the formats and the definition of the standard -// time, see the documentation for ANSIC. +// would be interepreted 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. // // Elements omitted from the value are assumed to be zero or, when // zero is impossible, one, so parsing "3:04pm" returns the time -- 2.48.1