proposal: encoding: BinaryMarshaler should be an append API

[FiloSottile]

The BinaryMarshaler API returns a freshly allocated byte slice. This makes it unadvisable to implement for high performance APIs, or even APIs that could happen to be used in high performance scenarios.

If it had an append-like API (MarshalBinary([]byte) ([]byte, error)) then also a lot of high performance and internal parsing operations could be BinaryMarshaler implementations, allowing more standard interface reuse.

The usability is not much worse, as nil can be passed to get the exact same behavior, and there's precedent in hash.Hash.Sum.

[kevinburke]

I ran into the same problem when implementing github.com/kevinburke/nacl and for the most part I chose the user-friendly API over the one with the best performance. In fact I believe you commented somewhere when I debuted that library pointing out that exact problem.

Is this something that could be better implemented within the compiler? Or with some pattern that's invisible to the user?

[dsnet]

Also MarshalJSON and MarshalText for consistency (assuming they continue to exist).

[magical]

Regarding Hash.Sum, see also #21070, which proposes either renaming the Sum method to AppendSum or else changing it to just return a new slice and not append.

[bcmills]

It would probably be easier to migrate if the Append method has a different name (such as AppendBinary / AppendText / AppendJSON).

This is one case where default methods (#23185) are somewhat appealing, although of course the packages that check for Marshal methods could always check for both interfaces.

[ianlancetaylor]

This seems like a good thing to do. We have to decide whether to change MarshalBinary and friends, or simply add new methods.

[ianlancetaylor]

At this point we can't realistically change the encoding.BinaryMarshaler interface. We could introduce a new interface with an append API. Anybody want to make that proposal? In the meantime I'm going to close this one. Thanks.

[dsnet]

I filed #62384.