encoding/json: document and test overwrite of slice, map during Unmarshal

Fixes #8837.

Change-Id: Iaaecbb0b324004cb74b16b764126b01315e6a16e
Reviewed-on: https://go-review.googlesource.com/12209
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/src/encoding/json/decode.go b/src/encoding/json/decode.go
index 02deac4c9fe88a236287ae89eb7419c22ff51539..530e8521dc5e6eccecfd0cde8926edada7d793fe 100644 (file)
--- a/src/encoding/json/decode.go
+++ b/src/encoding/json/decode.go
@@ -48,6 +48,13 @@ import (
 //     map[string]interface{}, for JSON objects
 //     nil for JSON null
 //
+// To unmarshal a JSON array into a slice, Unmarshal resets the slice to nil
+// and then appends each element to the slice.
+//
+// To unmarshal a JSON object into a map, Unmarshal replaces the map
+// with an empty map and then adds key-value pairs from the object to
+// the map.
+//
 // If a JSON value is not appropriate for a given target type,
 // or if a JSON number overflows the target type, Unmarshal
 // skips that field and completes the unmarshalling as best it can.

diff --git a/src/encoding/json/decode_test.go b/src/encoding/json/decode_test.go
index 41fc9ba67326dc02e98aca08443c76692140cfee..8aa158f08cdade6f9fe7f2d3caa91382bb646a1a 100644 (file)
--- a/src/encoding/json/decode_test.go
+++ b/src/encoding/json/decode_test.go
@@ -217,6 +217,9 @@ type XYZ struct {
        Z interface{}
 }
 
+func sliceAddr(x []int) *[]int                 { return &x }
+func mapAddr(x map[string]int) *map[string]int { return &x }
+
 var unmarshalTests = []unmarshalTest{
        // basic types
        {in: `true`, ptr: new(bool), out: true},
@@ -303,6 +306,12 @@ var unmarshalTests = []unmarshalTest{
        {in: `["X"]`, ptr: &umslicepT, out: &umsliceT},
        {in: `{"M":"X"}`, ptr: &umstructT, out: umstructT},
 
+       // Overwriting of data.
+       // This is different from package xml, but it's what we've always done.
+       // Now documented and tested.
+       {in: `[2]`, ptr: sliceAddr([]int{1}), out: []int{2}},
+       {in: `{"key": 2}`, ptr: mapAddr(map[string]int{"old": 0, "key": 1}), out: map[string]int{"key": 2}},
+
        {
                in: `{
                        "Level0": 1,