From a8ee83af78dbe4415333a1021067b59745440a2f Mon Sep 17 00:00:00 2001 From: Mark McGranaghan Date: Tue, 15 Apr 2014 18:04:23 -0700 Subject: [PATCH] Emphasize time constants In most cases users will format and parse times using the constants provided in package time. Show these first before getting into custom example-based formats. --- .../time-formatting-parsing.go | 46 ++++----- .../time-formatting-parsing.hash | 4 +- .../time-formatting-parsing.sh | 16 ++-- public/time-formatting-parsing | 96 ++++++++----------- 4 files changed, 72 insertions(+), 90 deletions(-) diff --git a/examples/time-formatting-parsing/time-formatting-parsing.go b/examples/time-formatting-parsing/time-formatting-parsing.go index e840264..8851d73 100644 --- a/examples/time-formatting-parsing/time-formatting-parsing.go +++ b/examples/time-formatting-parsing/time-formatting-parsing.go @@ -10,21 +10,33 @@ func main() { p := fmt.Println // Here's a basic example of formatting a time - // according to RFC3339. + // according to RFC3339, using the corresponding format + // constant. t := time.Now() - p(t.Format("2006-01-02T15:04:05Z07:00")) + p(t.Format(time.RFC3339)) - // `Format` uses an example-based layout approach; it - // takes a formatted version of the reference time + // Time parsing uses the same format values as `Format` + // does. + t1, e := time.Parse( + time.RFC3339, + "2012-11-01T22:08:41+00:00") + p(t1) + + // `Format` and `Parse` uses example-based formats. They + // take a formatted version of the reference time // `Mon Jan 2 15:04:05 MST 2006` to determine the - // general pattern with which to format the given - // time. The example time must be exactly as shown: the - // year 2006, 15 for the hour, Monday for the day of the - // week, etc. Here are a few more examples of time - // formatting. + // general pattern with which to format/parse the given + // time/string. The example time must be exactly as shown: + // the year 2006, 15 for the hour, Monday for the day of + // the week, etc. Usually you'll use a constant from + // `time` for these formats, but you can also supply + // custom formats. p(t.Format("3:04PM")) p(t.Format("Mon Jan _2 15:04:05 2006")) p(t.Format("2006-01-02T15:04:05.999999-07:00")) + form := "3 04 PM" + t2, e := time.Parse(form, "8 41 PM") + p(t2) // For purely numeric representations you can also // use standard string formatting with the extracted @@ -33,25 +45,9 @@ func main() { t.Year(), t.Month(), t.Day(), t.Hour(), t.Minute(), t.Second()) - // Time parsing uses the same example-based approach - // as `Format`ing. These examples parse times rendered - // with some of the layouts used above. - withNanos := "2006-01-02T15:04:05.999999999-07:00" - t1, e := time.Parse( - withNanos, - "2012-11-01T22:08:41.117442+00:00") - p(t1) - kitchen := "3:04PM" - t2, e := time.Parse(kitchen, "8:41PM") - p(t2) - // `Parse` will return an error on malformed input // explaining the parsing problem. ansic := "Mon Jan _2 15:04:05 2006" _, e = time.Parse(ansic, "8:41PM") p(e) - - // There are several predefined formats that you can - // use for both formatting and parsing. - p(t.Format(time.Kitchen)) } diff --git a/examples/time-formatting-parsing/time-formatting-parsing.hash b/examples/time-formatting-parsing/time-formatting-parsing.hash index e5a2de7..4e645aa 100644 --- a/examples/time-formatting-parsing/time-formatting-parsing.hash +++ b/examples/time-formatting-parsing/time-formatting-parsing.hash @@ -1,2 +1,2 @@ -64395057e85c58a94c5298067a45216ba1682c9d -CevEHjELb6 +f036cc1b8d2c2f5c5630c323001fb96efddbc7a8 +siwR2J2ke0 diff --git a/examples/time-formatting-parsing/time-formatting-parsing.sh b/examples/time-formatting-parsing/time-formatting-parsing.sh index 5eb30c7..7aa2cca 100644 --- a/examples/time-formatting-parsing/time-formatting-parsing.sh +++ b/examples/time-formatting-parsing/time-formatting-parsing.sh @@ -1,10 +1,10 @@ $ go run time-formatting-parsing.go -2012-11-02T09:35:03-07:00 -9:35AM -Fri Nov 2 09:35:03 2012 -2012-11-02T09:35:03.982519-07:00 -2012-11-02T09:35:03-00:00 -2012-11-01 22:08:41.117442 +0000 UTC +2014-04-15T18:00:15-07:00 +2012-11-01 22:08:41 +0000 +0000 +6:00PM +Tue Apr 15 18:00:15 2014 +2014-04-15T18:00:15.161182-07:00 0000-01-01 20:41:00 +0000 UTC -parsing time "8:41PM" as "Mon Jan _2 15:04:05 2006": ... -9:35AM +2014-04-15T18:00:15-00:00 +parsing time "8:41PM" as "Mon Jan _2 15:04:05 2006": \ + cannot parse "8:41PM" as "Mon" diff --git a/public/time-formatting-parsing b/public/time-formatting-parsing index 2b002fc..e52e155 100644 --- a/public/time-formatting-parsing +++ b/public/time-formatting-parsing @@ -40,7 +40,7 @@ pattern-based layouts.

- + 
package main
@@ -76,13 +76,14 @@ pattern-based layouts.

Here’s a basic example of formatting a time -according to RFC3339.

+according to RFC3339, using the corresponding format +constant.

    t := time.Now()
-    p(t.Format("2006-01-02T15:04:05Z07:00"))
+    p(t.Format(time.RFC3339))
@@ -90,14 +91,32 @@ according to RFC3339.

-

Format uses an example-based layout approach; it -takes a formatted version of the reference time +

Time parsing uses the same format values as Format +does.

+ + + + + 
    t1, e := time.Parse(
+        time.RFC3339,
+        "2012-11-01T22:08:41+00:00")
+    p(t1)
+
+ + + + + + +

Format and Parse uses example-based formats. They +take a formatted version of the reference time Mon Jan 2 15:04:05 MST 2006 to determine the -general pattern with which to format the given -time. The example time must be exactly as shown: the -year 2006, 15 for the hour, Monday for the day of the -week, etc. Here are a few more examples of time -formatting.

+general pattern with which to format/parse the given +time/string. The example time must be exactly as shown: +the year 2006, 15 for the hour, Monday for the day of +the week, etc. Usually you’ll use a constant from +time for these formats, but you can also supply +custom formats.

@@ -105,6 +124,9 @@ formatting.

    p(t.Format("3:04PM"))
     p(t.Format("Mon Jan _2 15:04:05 2006"))
     p(t.Format("2006-01-02T15:04:05.999999-07:00"))
+    form := "3 04 PM"
+    t2, e := time.Parse(form, "8 41 PM")
+    p(t2)
@@ -127,53 +149,17 @@ components of the time value.

- - -

Time parsing uses the same example-based approach -as Formating. These examples parse times rendered -with some of the layouts used above.

- - - - - 
    withNanos := "2006-01-02T15:04:05.999999999-07:00"
-    t1, e := time.Parse(
-        withNanos,
-        "2012-11-01T22:08:41.117442+00:00")
-    p(t1)
-    kitchen := "3:04PM"
-    t2, e := time.Parse(kitchen, "8:41PM")
-    p(t2)
-
- - - -

Parse will return an error on malformed input explaining the parsing problem.

- + 
    ansic := "Mon Jan _2 15:04:05 2006"
     _, e = time.Parse(ansic, "8:41PM")
     p(e)
-
- - - - - - -

There are several predefined formats that you can -use for both formatting and parsing.

- - - - - 
    p(t.Format(time.Kitchen))
 }
@@ -191,15 +177,15 @@ use for both formatting and parsing.

$ go run time-formatting-parsing.go 
-2012-11-02T09:35:03-07:00
-9:35AM
-Fri Nov  2 09:35:03 2012
-2012-11-02T09:35:03.982519-07:00
-2012-11-02T09:35:03-00:00
-2012-11-01 22:08:41.117442 +0000 UTC
+2014-04-15T18:00:15-07:00
+2012-11-01 22:08:41 +0000 +0000
+6:00PM
+Tue Apr 15 18:00:15 2014
+2014-04-15T18:00:15.161182-07:00
 0000-01-01 20:41:00 +0000 UTC
-parsing time "8:41PM" as "Mon Jan _2 15:04:05 2006": ...
-9:35AM
+2014-04-15T18:00:15-00:00
+parsing time "8:41PM" as "Mon Jan _2 15:04:05 2006": \
+  cannot parse "8:41PM" as "Mon"