time: add a time.Read method which does not allocate

The following benchmark marshals a struct with 100 time.Time objects.
Old uses MarshalBinary where new uses Read.

```
goos: darwin
goarch: arm64
pkg: utils/nats
cpu: Apple M2
                   │    old.txt    │              new5.txt               │
                   │    sec/op     │   sec/op     vs base                │
Encoders/mus/raw-8   15.259µ ± 91%   6.268µ ± 0%  -58.92% (p=0.000 n=10)

                   │   old.txt    │             new5.txt             │
                   │    bytes     │    bytes      vs base            │
Encoders/mus/raw-8   4.001Ki ± 0%   4.001Ki ± 0%  ~ (p=1.000 n=10) ¹
¹ all samples are equal

                   │   old.txt    │               new5.txt                │
                   │     B/op     │     B/op      vs base                 │
Encoders/mus/raw-8   1.562Ki ± 0%   0.000Ki ± 0%  -100.00% (p=0.000 n=10)

                   │  old.txt   │              new5.txt              │
                   │ allocs/op  │ allocs/op  vs base                 │
Encoders/mus/raw-8   100.0 ± 0%    0.0 ± 0%  -100.00% (p=0.000 n=10)
```

Signed-off-by: Sylvain Rabot <[email protected]>

Author: sylr

src/time/time.go

@@ -1248,8 +1248,8 @@ const (
 	timeBinaryVersionV2                 // For LMT only
 )
 
-// MarshalBinary implements the encoding.BinaryMarshaler interface.
-func (t Time) MarshalBinary() ([]byte, error) {
+// read reads the binary representation of a Time value from the b byte slice.
+func (t Time) read(b []byte) (int, error) {
 	var offsetMin int16 // minutes east of UTC. -1 is UTC.
 	var offsetSec int8
 	version := timeBinaryVersionV1
@@ -1265,35 +1265,66 @@ func (t Time) MarshalBinary() ([]byte, error) {
 
 		offset /= 60
 		if offset < -32768 || offset == -1 || offset > 32767 {
-			return nil, errors.New("Time.MarshalBinary: unexpected zone offset")
+			return 0, errors.New("unexpected zone offset")
 		}
 		offsetMin = int16(offset)
 	}
 
+	if version == timeBinaryVersionV1 && len(b) < 15 {
+		return 0, errors.New("insufficient buffer size")
+	} else if version == timeBinaryVersionV2 && len(b) < 16 {
+		return 0, errors.New("insufficient buffer size")
+	}
+
 	sec := t.sec()
 	nsec := t.nsec()
-	enc := []byte{
-		version,         // byte 0 : version
-		byte(sec >> 56), // bytes 1-8: seconds
-		byte(sec >> 48),
-		byte(sec >> 40),
-		byte(sec >> 32),
-		byte(sec >> 24),
-		byte(sec >> 16),
-		byte(sec >> 8),
-		byte(sec),
-		byte(nsec >> 24), // bytes 9-12: nanoseconds
-		byte(nsec >> 16),
-		byte(nsec >> 8),
-		byte(nsec),
-		byte(offsetMin >> 8), // bytes 13-14: zone offset in minutes
-		byte(offsetMin),
-	}
+	_ = b[14]
+	b[0] = version         // byte 0 : version
+	b[1] = byte(sec >> 56) // bytes 1-8: seconds
+	b[2] = byte(sec >> 48)
+	b[3] = byte(sec >> 40)
+	b[4] = byte(sec >> 32)
+	b[5] = byte(sec >> 24)
+	b[6] = byte(sec >> 16)
+	b[7] = byte(sec >> 8)
+	b[8] = byte(sec)
+	b[9] = byte(nsec >> 24) // bytes 9-12: nanoseconds
+	b[10] = byte(nsec >> 16)
+	b[11] = byte(nsec >> 8)
+	b[12] = byte(nsec)
+	b[13] = byte(offsetMin >> 8) // bytes 13-14: zone offset in minutes
+	b[14] = byte(offsetMin)
+
 	if version == timeBinaryVersionV2 {
-		enc = append(enc, byte(offsetSec))
+		b[15] = byte(offsetSec)
+		return 16, nil
+	}
+
+	return 15, nil
+}
+
+// Read implements the io.Reader interface.
+// It reads the binary representation of a Time value into the p byte slice.
+// In most cases it needs p to have a length of at least 15 bytes.
+// However, if the time value is in the Local location and the zone offset
+// minutes modulo 60 is not zero, it needs the p to have a length of at least 16
+// bytes.
+func (t Time) Read(p []byte) (int, error) {
+	if l, err := t.read(p); err != nil {
+		return l, errors.New("Time.Read: " + err.Error())
+	} else {
+		return l, nil
 	}
+}
 
-	return enc, nil
+// MarshalBinary implements the encoding.BinaryMarshaler interface.
+func (t Time) MarshalBinary() ([]byte, error) {
+	p := make([]byte, 16)
+	if l, err := t.read(p); err != nil {
+		return nil, errors.New("Time.MarshalBinary: " + err.Error())
+	} else {
+		return p[:l], nil
+	}
 }
 
 // UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.