encoding/gob: document behavior of zero-valued arrays, slices, and maps

The documentation was inconsistent. It said zero values were not sent, but
that zero-valued elements of arrays and arrays were sent. But which rule
applies if the array is all zero elements, and is therefore itself a zero value?

The answer is: the array is transmitted. In principle the other choice could
be made, but there would be considerable expense and complexity required
to implement this behavior now, not to mention worries about changes of
behavior.

Therefore we just document the situation: Arrays, slices, and maps are
always encoded. It would perhaps be nice to have sorted this out earlier,
but it was a missed opportunity.

Fixes #13378

Change-Id: I8fae345edfa707fcfa7a3e0160d87ff1ac5cc5a2
Reviewed-on: https://go-review.googlesource.com/17394
Reviewed-by: Russ Cox <rsc@golang.org>

diff --git a/src/encoding/gob/doc.go b/src/encoding/gob/doc.go
index 18a91bd7add759f9176cfcc90e6637cb12d5a3dc..cf878f450295f4d3ff8c62ed869ee32adbc576bb 100644 (file)
--- a/src/encoding/gob/doc.go
+++ b/src/encoding/gob/doc.go
@@ -140,26 +140,28 @@ Strings and slices of bytes are sent as an unsigned count followed by that many
 uninterpreted bytes of the value.
 
 All other slices and arrays are sent as an unsigned count followed by that many
-elements using the standard gob encoding for their type, recursively. In slices
-and arrays, elements with the zero value are transmitted.
+elements using the standard gob encoding for their type, recursively.
 
 Maps are sent as an unsigned count followed by that many key, element
 pairs. Empty but non-nil maps are sent, so if the receiver has not allocated
 one already, one will always be allocated on receipt unless the transmitted map
 is nil and not at the top level.
 
+In slices and arrays, as well as maps, all elements, even zero-valued elements,
+are transmitted, even if all the elements are zero.
+
 Structs are sent as a sequence of (field number, field value) pairs.  The field
 value is sent using the standard gob encoding for its type, recursively.  If a
-field has the zero value for its type, it is omitted from the transmission.  The
-field number is defined by the type of the encoded struct: the first field of the
-encoded type is field 0, the second is field 1, etc.  When encoding a value, the
-field numbers are delta encoded for efficiency and the fields are always sent in
-order of increasing field number; the deltas are therefore unsigned.  The
-initialization for the delta encoding sets the field number to -1, so an unsigned
-integer field 0 with value 7 is transmitted as unsigned delta = 1, unsigned value
-= 7 or (01 07).  Finally, after all the fields have been sent a terminating mark
-denotes the end of the struct.  That mark is a delta=0 value, which has
-representation (00).
+field has the zero value for its type (except for arrays; see above), it is omitted
+from the transmission.  The field number is defined by the type of the encoded
+struct: the first field of the encoded type is field 0, the second is field 1,
+etc.  When encoding a value, the field numbers are delta encoded for efficiency
+and the fields are always sent in order of increasing field number; the deltas are
+therefore unsigned.  The initialization for the delta encoding sets the field
+number to -1, so an unsigned integer field 0 with value 7 is transmitted as unsigned
+delta = 1, unsigned value = 7 or (01 07).  Finally, after all the fields have been
+sent a terminating mark denotes the end of the struct.  That mark is a delta=0
+value, which has representation (00).
 
 Interface types are not checked for compatibility; all interface types are
 treated, for transmission, as members of a single "interface" type, analogous to