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

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

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

"net.IP.MarshalText" gets some performance improvements:

                     │     old      │                 new                 │
                     │    sec/op    │   sec/op     vs base                │
IPMarshalText/IPv4-8    68.35n ± 1%   14.64n ± 1%  -78.57% (p=0.000 n=10)
IPMarshalText/IPv6-8   124.35n ± 2%   62.73n ± 1%  -49.55% (p=0.000 n=10)
geomean                 92.19n        30.31n       -67.12%

                     │    old     │                  new                   │
                     │    B/op    │   B/op     vs base                     │
IPMarshalText/IPv4-8   32.00 ± 0%   0.00 ± 0%  -100.00% (p=0.000 n=10)
IPMarshalText/IPv6-8   48.00 ± 0%   0.00 ± 0%  -100.00% (p=0.000 n=10)

                     │    old     │                   new                   │
                     │ allocs/op  │ allocs/op   vs base                     │
IPMarshalText/IPv4-8   2.000 ± 0%   0.000 ± 0%  -100.00% (p=0.000 n=10)
IPMarshalText/IPv6-8   2.000 ± 0%   0.000 ± 0%  -100.00% (p=0.000 n=10)

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

@@ -301,11 +301,11 @@ func (ip IP) String() string {
 	if len(ip) != IPv4len && len(ip) != IPv6len {
 		return "?" + hexString(ip)
 	}
-	// If IPv4, use dotted notation.
-	if p4 := ip.To4(); len(p4) == IPv4len {
-		return netip.AddrFrom4([4]byte(p4)).String()
-	}
-	return netip.AddrFrom16([16]byte(ip)).String()
+
+	// the longest form is "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
+	buf := make([]byte, 0, len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"))
+	buf = ip.appendTo(buf)
+	return string(buf)
 }
 
 func hexString(b []byte) string {
@@ -325,17 +325,40 @@ func ipEmptyString(ip IP) string {
 	return ip.String()
 }
 
-// MarshalText implements the [encoding.TextMarshaler] interface.
+// appendTo appends the string representation of ip to b and returns the expanded b
+// If len(ip) != IPv4len or IPv6len, it appends nothing.
+func (ip IP) appendTo(b []byte) []byte {
+	// If IPv4, use dotted notation.
+	if p4 := ip.To4(); len(p4) == IPv4len {
+		ip = p4
+	}
+	addr, _ := netip.AddrFromSlice(ip)
+	return addr.AppendTo(b)
+}
+
+// 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 appends 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 ip.appendTo(b), 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(make([]byte, 0, len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")))
+	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,9 +275,45 @@ 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)
+		}
+	}
+}
+
+func TestIPAppendTextNoAllocs(t *testing.T) {
+	// except the invalid IP
+	for _, tt := range ipStringTests[:len(ipStringTests)-1] {
+		allocs := int(testing.AllocsPerRun(1000, func() {
+			buf := make([]byte, 0, 64)
+			_, _ = tt.in.AppendText(buf)
+		}))
+		if allocs != 0 {
+			t.Errorf("IP(%q) AppendText allocs: %d times, want 0", tt.in, allocs)
+		}
 	}
 }
 
+func BenchmarkIPMarshalText(b *testing.B) {
+	b.Run("IPv4", func(b *testing.B) {
+		b.ReportAllocs()
+		b.ResetTimer()
+		ip := IP{192, 0, 2, 1}
+		for range b.N {
+			_, _ = ip.MarshalText()
+		}
+	})
+	b.Run("IPv6", func(b *testing.B) {
+		b.ReportAllocs()
+		b.ResetTimer()
+		ip := IP{0x20, 0x1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0xa, 0, 0xb, 0, 0xc, 0, 0xd}
+		for range b.N {
+			_, _ = ip.MarshalText()
+		}
+	})
+}
+
 var sink string
 
 func BenchmarkIPString(b *testing.B) {

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.