encoding: add TextAppender and BinaryAppender

For #62384

Change-Id: I54707a29653df72ad9cd5633f434b87e0f630b94
GitHub-Last-Rev: 4f78947ac563d78f862c5c8de1c2e1578a8d6e08
GitHub-Pull-Request: golang/go#68620
Reviewed-on: https://go-review.googlesource.com/c/go/+/601595


LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>

api/next/62384.txt

+pkg encoding, type BinaryAppender interface { AppendBinary } #62384
+pkg encoding, type BinaryAppender interface, AppendBinary([]uint8) ([]uint8, error) #62384
+pkg encoding, type TextAppender interface { AppendText } #62384
+pkg encoding, type TextAppender interface, AppendText([]uint8) ([]uint8, error) #62384

doc/next/6-stdlib/99-minor/encoding/62384.md

+Two new interfaces, [TextAppender] and [BinaryAppender], have been
+introduced to append the textual or binary representation of an object
+to a byte slice. These interfaces provide the same functionality as
+[TextMarshaler] and [BinaryMarshaler], but instead of allocating a new slice
+each time, they append the data directly to an existing slice.

src/encoding/encoding.go

@@ -35,6 +35,18 @@ type BinaryUnmarshaler interface {
 	UnmarshalBinary(data []byte) error
 }
 
+// BinaryAppender is the interface implemented by an object
+// that can append the binary representation of itself.
+// If a type implements both [BinaryAppender] and [BinaryMarshaler],
+// then v.MarshalBinary() must be semantically identical to v.AppendBinary(nil).
+type BinaryAppender interface {
+	// AppendBinary appends the binary representation of itself to the end of b
+	// (allocating a larger slice if necessary) and returns the updated slice.
+	//
+	// Implementations must not retain b, nor mutate any bytes within b[:len(b)].
+	AppendBinary(b []byte) ([]byte, error)
+}
+
 // TextMarshaler is the interface implemented by an object that can
 // marshal itself into a textual form.
 //
@@ -52,3 +64,15 @@ type TextMarshaler interface {
 type TextUnmarshaler interface {
 	UnmarshalText(text []byte) error
 }
+
+// TextAppender is the interface implemented by an object
+// that can append the textual representation of itself.
+// If a type implements both [TextAppender] and [TextMarshaler],
+// then v.MarshalText() must be semantically identical to v.AppendText(nil).
+type TextAppender interface {
+	// AppendText appends the textual representation of itself to the end of b
+	// (allocating a larger slice if necessary) and returns the updated slice.
+	//
+	// Implementations must not retain b, nor mutate any bytes within b[:len(b)].
+	AppendText(b []byte) ([]byte, error)
+}