net,net/netip: implement the encoding.(Binary|Text)Appender

Implement the encoding.TextAppender for "net.IP".

Implament the encoding.(Binary|Text)Appender interfaces for
"netip.Addr", "netip.AddrPort" and "netip.Prefix".

All exported types in the standard library that implement the
"encoding.(Binary|Text)Marshaler" now also implement the
"encoding.(Binary|Text)Appender".

Fixes golang#62384

api/next/62384.txt

@@ -15,3 +15,10 @@ pkg math/rand/v2, method (*ChaCha8) AppendBinary([]uint8) ([]uint8, error) #6238
 pkg math/rand/v2, method (*PCG) AppendBinary([]uint8) ([]uint8, error) #62384
 pkg crypto/x509, method (OID) AppendBinary([]uint8) ([]uint8, error) #62384
 pkg crypto/x509, method (OID) AppendText([]uint8) ([]uint8, error) #62384
+pkg net, method (IP) AppendText([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (Addr) AppendBinary([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (Addr) AppendText([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (AddrPort) AppendBinary([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (AddrPort) AppendText([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (Prefix) AppendBinary([]uint8) ([]uint8, error) #62384
+pkg net/netip, method (Prefix) AppendText([]uint8) ([]uint8, error) #62384

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

@@ -0,0 +1 @@
+[IP] now implements the [encoding.TextAppender] interface.

doc/next/6-stdlib/99-minor/net/netip/62384.md

@@ -0,0 +1,2 @@
+[Addr], [AddrPort] and [Prefix] now implement the [encoding.BinaryAppender] and
+[encoding.TextAppender] interfaces.

src/net/ip.go

@@ -325,17 +325,28 @@ func ipEmptyString(ip IP) string {
 	return ip.String()
 }
 
-// MarshalText implements the [encoding.TextMarshaler] interface.
+// AppendText implements the [encoding.TextAppender] interface.
 // The encoding is the same as returned by [IP.String], with one exception:
-// When len(ip) is zero, it returns an empty slice.
-func (ip IP) MarshalText() ([]byte, error) {
+// When len(ip) is zero, it does nothing.
+func (ip IP) AppendText(b []byte) ([]byte, error) {
 	if len(ip) == 0 {
-		return []byte(""), nil
+		return b, nil
 	}
 	if len(ip) != IPv4len && len(ip) != IPv6len {
-		return nil, &AddrError{Err: "invalid IP address", Addr: hexString(ip)}
+		return b, &AddrError{Err: "invalid IP address", Addr: hexString(ip)}
+	}
+	return append(b, ip.String()...), nil
+}
+
+// MarshalText implements the [encoding.TextMarshaler] interface.
+// The encoding is the same as returned by [IP.String], with one exception:
+// When len(ip) is zero, it returns an empty slice.
+func (ip IP) MarshalText() ([]byte, error) {
+	b, err := ip.AppendText([]byte(""))
+	if err != nil {
+		return nil, err
 	}
-	return []byte(ip.String()), nil
+	return b, nil
 }
 
 // UnmarshalText implements the [encoding.TextUnmarshaler] interface.

src/net/ip_test.go

@@ -149,6 +149,15 @@ func TestMarshalEmptyIP(t *testing.T) {
 	if !reflect.DeepEqual(got, []byte("")) {
 		t.Errorf(`got %#v, want []byte("")`, got)
 	}
+
+	buf := make([]byte, 4)
+	got, err = ip.AppendText(buf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got, []byte("\x00\x00\x00\x00")) {
+		t.Errorf(`got %#v, want []byte("\x00\x00\x00\x00")`, got)
+	}
 }
 
 var ipStringTests = []*struct {
@@ -266,6 +275,10 @@ func TestIPString(t *testing.T) {
 		if out, err := tt.in.MarshalText(); !bytes.Equal(out, tt.byt) || !reflect.DeepEqual(err, tt.error) {
 			t.Errorf("IP.MarshalText(%v) = %v, %v, want %v, %v", tt.in, out, err, tt.byt, tt.error)
 		}
+		buf := make([]byte, 4, 32)
+		if out, err := tt.in.AppendText(buf); !bytes.Equal(out[4:], tt.byt) || !reflect.DeepEqual(err, tt.error) {
+			t.Errorf("IP.AppendText(%v) = %v, %v, want %v, %v", tt.in, out[4:], err, tt.byt, tt.error)
+		}
 	}
 }
 

src/net/netip/netip.go

@@ -966,27 +966,28 @@ func (ip Addr) StringExpanded() string {
 	return string(ret)
 }
 
+// AppendText implements the [encoding.TextAppender] interface,
+// It is the same as [Addr.AppendTo].
+func (ip Addr) AppendText(b []byte) ([]byte, error) {
+	return ip.AppendTo(b), nil
+}
+
 // MarshalText implements the [encoding.TextMarshaler] interface,
 // The encoding is the same as returned by [Addr.String], with one exception:
 // If ip is the zero [Addr], the encoding is the empty string.
 func (ip Addr) MarshalText() ([]byte, error) {
+	var maxCap int
 	switch ip.z {
 	case z0:
-		return []byte(""), nil
 	case z4:
-		max := len("255.255.255.255")
-		b := make([]byte, 0, max)
-		return ip.appendTo4(b), nil
+		maxCap = len("255.255.255.255")
 	default:
+		maxCap = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0")
 		if ip.Is4In6() {
-			max := len("::ffff:255.255.255.255%enp5s0")
-			b := make([]byte, 0, max)
-			return ip.appendTo4In6(b), nil
+			maxCap = len("::ffff:255.255.255.255%enp5s0")
 		}
-		max := len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0")
-		b := make([]byte, 0, max)
-		return ip.appendTo6(b), nil
 	}
+	return ip.AppendText(make([]byte, 0, maxCap))
 }
 
 // UnmarshalText implements the encoding.TextUnmarshaler interface.
@@ -1004,30 +1005,37 @@ func (ip *Addr) UnmarshalText(text []byte) error {
 	return err
 }
 
-func (ip Addr) marshalBinaryWithTrailingBytes(trailingBytes int) []byte {
-	var b []byte
+// AppendBinary implements the [encoding.BinaryAppender] interface.
+func (ip Addr) AppendBinary(b []byte) ([]byte, error) {
 	switch ip.z {
 	case z0:
-		b = make([]byte, trailingBytes)
 	case z4:
-		b = make([]byte, 4+trailingBytes)
-		byteorder.BePutUint32(b, uint32(ip.addr.lo))
+		b = byteorder.BeAppendUint32(b, uint32(ip.addr.lo))
 	default:
-		z := ip.Zone()
-		b = make([]byte, 16+len(z)+trailingBytes)
-		byteorder.BePutUint64(b[:8], ip.addr.hi)
-		byteorder.BePutUint64(b[8:], ip.addr.lo)
-		copy(b[16:], z)
+		b = byteorder.BeAppendUint64(b, ip.addr.hi)
+		b = byteorder.BeAppendUint64(b, ip.addr.lo)
+		b = append(b, ip.Zone()...)
+	}
+	return b, nil
+}
+
+func (ip Addr) marshalBinarySize() int {
+	switch ip.z {
+	case z0:
+		return 0
+	case z4:
+		return 4
+	default:
+		return 16 + len(ip.Zone())
 	}
-	return b
 }
 
 // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
 // It returns a zero-length slice for the zero [Addr],
 // the 4-byte form for an IPv4 address,
 // and the 16-byte form with zone appended for an IPv6 address.
 func (ip Addr) MarshalBinary() ([]byte, error) {
-	return ip.marshalBinaryWithTrailingBytes(0), nil
+	return ip.AppendBinary(make([]byte, 0, ip.marshalBinarySize()))
 }
 
 // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
@@ -1198,21 +1206,25 @@ func (p AddrPort) AppendTo(b []byte) []byte {
 	return b
 }
 
+// AppendText implements the [encoding.TextAppender] interface. The
+// encoding is the same as returned by [AddrPort.AppendTo].
+func (p AddrPort) AppendText(b []byte) ([]byte, error) {
+	return p.AppendTo(b), nil
+}
+
 // MarshalText implements the [encoding.TextMarshaler] interface. The
 // encoding is the same as returned by [AddrPort.String], with one exception: if
 // p.Addr() is the zero [Addr], the encoding is the empty string.
 func (p AddrPort) MarshalText() ([]byte, error) {
-	var max int
+	var maxCap int
 	switch p.ip.z {
 	case z0:
 	case z4:
-		max = len("255.255.255.255:65535")
+		maxCap = len("255.255.255.255:65535")
 	default:
-		max = len("[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0]:65535")
+		maxCap = len("[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0]:65535")
 	}
-	b := make([]byte, 0, max)
-	b = p.AppendTo(b)
-	return b, nil
+	return p.AppendText(make([]byte, 0, maxCap))
 }
 
 // UnmarshalText implements the encoding.TextUnmarshaler
@@ -1228,13 +1240,22 @@ func (p *AddrPort) UnmarshalText(text []byte) error {
 	return err
 }
 
+// AppendBinary implements the [encoding.BinaryAppendler] interface.
+// It returns [Addr.AppendBinary] with an additional two bytes appended
+// containing the port in little-endian.
+func (p AddrPort) AppendBinary(b []byte) ([]byte, error) {
+	b, err := p.Addr().AppendBinary(b)
+	if err != nil {
+		return nil, err
+	}
+	return byteorder.LeAppendUint16(b, p.Port()), nil
+}
+
 // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
 // It returns [Addr.MarshalBinary] with an additional two bytes appended
 // containing the port in little-endian.
 func (p AddrPort) MarshalBinary() ([]byte, error) {
-	b := p.Addr().marshalBinaryWithTrailingBytes(2)
-	byteorder.LePutUint16(b[len(b)-2:], p.Port())
-	return b, nil
+	return p.AppendBinary(make([]byte, 0, p.Addr().marshalBinarySize()+2))
 }
 
 // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
@@ -1487,21 +1508,25 @@ func (p Prefix) AppendTo(b []byte) []byte {
 	return b
 }
 
+// AppendText implements the [encoding.TextAppender] interface.
+// It is the same as [Prefix.AppendTo].
+func (p Prefix) AppendText(b []byte) ([]byte, error) {
+	return p.AppendTo(b), nil
+}
+
 // MarshalText implements the [encoding.TextMarshaler] interface,
 // The encoding is the same as returned by [Prefix.String], with one exception:
 // If p is the zero value, the encoding is the empty string.
 func (p Prefix) MarshalText() ([]byte, error) {
-	var max int
+	var maxCap int
 	switch p.ip.z {
 	case z0:
 	case z4:
-		max = len("255.255.255.255/32")
+		maxCap = len("255.255.255.255/32")
 	default:
-		max = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0/128")
+		maxCap = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0/128")
 	}
-	b := make([]byte, 0, max)
-	b = p.AppendTo(b)
-	return b, nil
+	return p.AppendText(make([]byte, 0, maxCap))
 }
 
 // UnmarshalText implements the encoding.TextUnmarshaler interface.
@@ -1517,13 +1542,23 @@ func (p *Prefix) UnmarshalText(text []byte) error {
 	return err
 }
 
+// AppendBinary implements the [encoding.AppendMarshaler] interface.
+// It returns [Addr.AppendBinary] with an additional byte appended
+// containing the prefix bits.
+func (p Prefix) AppendBinary(b []byte) ([]byte, error) {
+	b, err := p.Addr().withoutZone().AppendBinary(b)
+	if err != nil {
+		return nil, err
+	}
+	return append(b, uint8(p.Bits())), nil
+}
+
 // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
 // It returns [Addr.MarshalBinary] with an additional byte appended
 // containing the prefix bits.
 func (p Prefix) MarshalBinary() ([]byte, error) {
-	b := p.Addr().withoutZone().marshalBinaryWithTrailingBytes(1)
-	b[len(b)-1] = uint8(p.Bits())
-	return b, nil
+	// without the zone the max length is 16, plus an additional byte is 17
+	return p.AppendBinary(make([]byte, 0, p.Addr().withoutZone().marshalBinarySize()+1))
 }
 
 // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.