time: document that valid layouts are not valid Parse values

For #9346 #22135 explicitly state under layout constants
that they are not valid time values for Parse. Also add
examples of parsing valid RFC3339 values and the layout
to the example for time.Parse.

Fix capitalisation of time.Parse and Time.Format.

For #20869 include RFC3339 in the list of layouts that do
not accept all the time formats allowed by RFCs (lowercase z).
This does not fully address #20869.

Fixes #9346
Fixes #22135

Change-Id: Ia4c13e5745de583db5ef7d5b1688d7768bc42c1b
Reviewed-on: https://go-review.googlesource.com/74231
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 17 insertions, 1 deletions

diff --git a/src/time/example_test.go b/src/time/example_test.go
index 12c61813e1..134aef3594 100644
--- a/src/time/example_test.go
+++ b/src/time/example_test.go
@@ -300,7 +300,7 @@ func ExampleTime_Format() {
 }
 
 func ExampleParse() {
-	// See the example for time.Format for a thorough description of how
+	// 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.
 
@@ -317,9 +317,25 @@ func ExampleParse() {
 	t, _ = time.Parse(shortForm, "2013-Feb-03")
 	fmt.Println(t)
 
+	// Valid layouts may not be a valid time value, due to format specifiers
+	// like _ for zero padding or Z for zone information.
+	// For example the RFC3339 layout 2006-01-02T15:04:05Z07:00
+	// contains both Z and a time zone offset in order to handle both valid options:
+	// 2006-01-02T15:04:05Z
+	// 2006-01-02T15:04:05+07:00
+	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05Z")
+	fmt.Println(t)
+	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05+07:00")
+	fmt.Println(t)
+	_, err := time.Parse(time.RFC3339, time.RFC3339)
+	fmt.Println("error", err) // Returns an error as the layout is not a valid time value
+
 	// Output:
 	// 2013-02-03 19:54:00 -0800 PST
 	// 2013-02-03 00:00:00 +0000 UTC
+	// 2006-01-02 15:04:05 +0000 UTC
+	// 2006-01-02 15:04:05 +0700 +0700
+	// error parsing time "2006-01-02T15:04:05Z07:00": extra text: 07:00
 }
 
 func ExampleParseInLocation() {