encoding/json: add an example for RawMessage

RawMessage is useful and mildly non-obvious.
Given the frequency with which RawMessage questions
show up on golang-nuts, and get answered with an example,
I suspect adding an example to the docs might help.

R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/14190044

1 files changed, 46 insertions, 0 deletions

diff --git a/src/pkg/encoding/json/example_test.go b/src/pkg/encoding/json/example_test.go
index b8d150eda5..ea0bc149c3 100644
--- a/src/pkg/encoding/json/example_test.go
+++ b/src/pkg/encoding/json/example_test.go
@@ -81,3 +81,49 @@ func ExampleDecoder() {
 	// Sam: Go fmt who?
 	// Ed: Go fmt yourself!
 }
+
+// This example uses RawMessage to delay parsing part of a JSON message.
+func ExampleRawMessage() {
+	type Color struct {
+		Space string
+		Point json.RawMessage // delay parsing until we know the color space
+	}
+	type RGB struct {
+		R uint8
+		G uint8
+		B uint8
+	}
+	type YCbCr struct {
+		Y  uint8
+		Cb int8
+		Cr int8
+	}
+
+	var j = []byte(`[
+		{"Space": "YCbCr", "Point": {"Y": 255, "Cb": 0, "Cr": -10}},
+		{"Space": "RGB",   "Point": {"R": 98, "G": 218, "B": 255}}
+	]`)
+	var colors []Color
+	err := json.Unmarshal(j, &colors)
+	if err != nil {
+		log.Fatalln("error:", err)
+	}
+
+	for _, c := range colors {
+		var dst interface{}
+		switch c.Space {
+		case "RGB":
+			dst = new(RGB)
+		case "YCbCr":
+			dst = new(YCbCr)
+		}
+		err := json.Unmarshal(c.Point, dst)
+		if err != nil {
+			log.Fatalln("error:", err)
+		}
+		fmt.Println(c.Space, dst)
+	}
+	// Output:
+	// YCbCr &{255 0 -10}
+	// RGB &{98 218 255}
+}