encoding/binary: add AppendByteOrder

AppendByteOrder specifies new methods for LittleEndian and BigEndian
for appending an unsigned integer to a byte slice.

The performance of AppendXXX methods are slower than PutXXX methods
since the former needs to do a few slice operations,
while the latter is essentially a single integer store.
In practice, existing usages of PutXXX performed slicing operations
around the call such that this cost was present, regardless.

name                           time/op
PutUint16-24                   0.48ns ± 2%
AppendUint16-24                1.54ns ± 1%
PutUint32-24                   0.46ns ± 2%
AppendUint32-24                0.89ns ± 1%
PutUint64-24                   0.46ns ± 2%
AppendUint64-24                0.89ns ± 1%
LittleEndianPutUint16-24       0.47ns ± 2%
LittleEndianAppendUint16-24    1.54ns ± 1%
LittleEndianPutUint32-24       0.45ns ± 3%
LittleEndianAppendUint32-24    0.92ns ± 2%
LittleEndianPutUint64-24       0.46ns ± 3%
LittleEndianAppendUint64-24    0.95ns ± 4%

Fixes #50601

Change-Id: I33d2bbc93a3ce01a9269feac33a2432bc1166ead
Reviewed-on: https://go-review.googlesource.com/c/go/+/386017
Trust: Joseph Tsai <joetsai@digital-static.net>
Trust: Josh Bleecher Snyder <josharian@gmail.com>
Reviewed-by: Josh Bleecher Snyder <josharian@gmail.com>
Run-TryBot: Joseph Tsai <joetsai@digital-static.net>
TryBot-Result: Gopher Robot <gobot@golang.org>

1 files changed, 70 insertions, 3 deletions

diff --git a/src/encoding/binary/binary.go b/src/encoding/binary/binary.go
index ee933461ee..0681511fbb 100644
--- a/src/encoding/binary/binary.go
+++ b/src/encoding/binary/binary.go
@@ -29,7 +29,7 @@ import (
 	"sync"
 )
 
-// A ByteOrder specifies how to convert byte sequences into
+// A ByteOrder specifies how to convert byte slices into
 // 16-, 32-, or 64-bit unsigned integers.
 type ByteOrder interface {
 	Uint16([]byte) uint16
@@ -41,10 +41,19 @@ type ByteOrder interface {
 	String() string
 }
 
-// LittleEndian is the little-endian implementation of ByteOrder.
+// AppendByteOrder specifies how to append 16-, 32-, or 64-bit unsigned integers
+// into a byte slice.
+type AppendByteOrder interface {
+	AppendUint16([]byte, uint16) []byte
+	AppendUint32([]byte, uint32) []byte
+	AppendUint64([]byte, uint64) []byte
+	String() string
+}
+
+// LittleEndian is the little-endian implementation of ByteOrder and AppendByteOrder.
 var LittleEndian littleEndian
 
-// BigEndian is the big-endian implementation of ByteOrder.
+// BigEndian is the big-endian implementation of ByteOrder and AppendByteOrder.
 var BigEndian bigEndian
 
 type littleEndian struct{}
@@ -60,6 +69,13 @@ func (littleEndian) PutUint16(b []byte, v uint16) {
 	b[1] = byte(v >> 8)
 }
 
+func (littleEndian) AppendUint16(b []byte, v uint16) []byte {
+	return append(b,
+		byte(v),
+		byte(v>>8),
+	)
+}
+
 func (littleEndian) Uint32(b []byte) uint32 {
 	_ = b[3] // bounds check hint to compiler; see golang.org/issue/14808
 	return uint32(b[0]) | uint32(b[1])<<8 | uint32(b[2])<<16 | uint32(b[3])<<24
@@ -73,6 +89,15 @@ func (littleEndian) PutUint32(b []byte, v uint32) {
 	b[3] = byte(v >> 24)
 }
 
+func (littleEndian) AppendUint32(b []byte, v uint32) []byte {
+	return append(b,
+		byte(v),
+		byte(v>>8),
+		byte(v>>16),
+		byte(v>>24),
+	)
+}
+
 func (littleEndian) Uint64(b []byte) uint64 {
 	_ = b[7] // bounds check hint to compiler; see golang.org/issue/14808
 	return uint64(b[0]) | uint64(b[1])<<8 | uint64(b[2])<<16 | uint64(b[3])<<24 |
@@ -91,6 +116,19 @@ func (littleEndian) PutUint64(b []byte, v uint64) {
 	b[7] = byte(v >> 56)
 }
 
+func (littleEndian) AppendUint64(b []byte, v uint64) []byte {
+	return append(b,
+		byte(v),
+		byte(v>>8),
+		byte(v>>16),
+		byte(v>>24),
+		byte(v>>32),
+		byte(v>>40),
+		byte(v>>48),
+		byte(v>>56),
+	)
+}
+
 func (littleEndian) String() string { return "LittleEndian" }
 
 func (littleEndian) GoString() string { return "binary.LittleEndian" }
@@ -108,6 +146,13 @@ func (bigEndian) PutUint16(b []byte, v uint16) {
 	b[1] = byte(v)
 }
 
+func (bigEndian) AppendUint16(b []byte, v uint16) []byte {
+	return append(b,
+		byte(v>>8),
+		byte(v),
+	)
+}
+
 func (bigEndian) Uint32(b []byte) uint32 {
 	_ = b[3] // bounds check hint to compiler; see golang.org/issue/14808
 	return uint32(b[3]) | uint32(b[2])<<8 | uint32(b[1])<<16 | uint32(b[0])<<24
@@ -121,6 +166,15 @@ func (bigEndian) PutUint32(b []byte, v uint32) {
 	b[3] = byte(v)
 }
 
+func (bigEndian) AppendUint32(b []byte, v uint32) []byte {
+	return append(b,
+		byte(v>>24),
+		byte(v>>16),
+		byte(v>>8),
+		byte(v),
+	)
+}
+
 func (bigEndian) Uint64(b []byte) uint64 {
 	_ = b[7] // bounds check hint to compiler; see golang.org/issue/14808
 	return uint64(b[7]) | uint64(b[6])<<8 | uint64(b[5])<<16 | uint64(b[4])<<24 |
@@ -139,6 +193,19 @@ func (bigEndian) PutUint64(b []byte, v uint64) {
 	b[7] = byte(v)
 }
 
+func (bigEndian) AppendUint64(b []byte, v uint64) []byte {
+	return append(b,
+		byte(v>>56),
+		byte(v>>48),
+		byte(v>>40),
+		byte(v>>32),
+		byte(v>>24),
+		byte(v>>16),
+		byte(v>>8),
+		byte(v),
+	)
+}
+
 func (bigEndian) String() string { return "BigEndian" }
 
 func (bigEndian) GoString() string { return "binary.BigEndian" }