add DecompressInto for decompression of payloads with known sizes

In some systems, compressed payloads are prefixed or tagged with the size of
the original payload. This allows allocation of a perfectly-sized buffer to
hold the decompressed payload. The current Decompress interface prohibits this
type of usage, because Decompress allocates if the destination buffer is
smaller than the worst-case bound. In practice, a perfectly-sized buffer will
always be smaller than what's required for the worst-case payload.

This commit introduces an additional DecompressInto entrypoint. DecompressInto
accepts a destination buffer and requires that the decompressed payload fit
into the buffer. If it does not, it returns the original error returned by zstd.

zstd.go

@@ -143,12 +143,7 @@ func Decompress(dst, src []byte) ([]byte, error) {
  dst = make([]byte, bound)
  }
 
- written := int(C.ZSTD_decompress(
- unsafe.Pointer(&dst[0]),
- C.size_t(len(dst)),
- unsafe.Pointer(&src[0]),
- C.size_t(len(src))))
- err := getError(written)
+ written, err := DecompressInto(dst, src)
  if err == nil {
  return dst[:written], nil
  }
@@ -161,3 +156,19 @@ func Decompress(dst, src []byte) ([]byte, error) {
  defer r.Close()
  return ioutil.ReadAll(r)
 }
+
+// DecompressInto decompresses src into dst. Unlike Decompress, DecompressInto
+// requires that dst be sufficiently large to hold the decompressed payload.
+// DecompressInto may be used when the caller knows the size of the decompressed
+// payload before attempting decompression.
+//
+// It returns the number of bytes copied and an error if any is encountered. If
+// dst is too small, DecompressInto errors.
+func DecompressInto(dst, src []byte) (int, error) {
+ written := int(C.ZSTD_decompress(
+ unsafe.Pointer(&dst[0]),
+ C.size_t(len(dst)),
+ unsafe.Pointer(&src[0]),
+ C.size_t(len(src))))
+ return written, getError(written)
+}

zstd_test.go

@@ -87,6 +87,35 @@ func TestCompressDecompress(t *testing.T) {
  }
 }
 
+func TestCompressDecompressInto(t *testing.T) {
+ payload := []byte("Hello World!")
+ compressed, err := Compress(make([]byte, CompressBound(len(payload))), payload)
+ if err != nil {
+ t.Fatalf("Error while compressing: %v", err)
+ }
+ t.Logf("Compressed: %v", compressed)
+
+ // We know the size of the payload; construct a buffer that perfectly fits
+ // the payload and use DecompressInto.
+ decompressed := make([]byte, len(payload))
+ if n, err := DecompressInto(decompressed, compressed); err != nil {
+ t.Fatalf("error while decompressing into buffer of size %d: %v",
+ len(decompressed), err)
+ } else if n != len(decompressed) {
+ t.Errorf("DecompressedInto = (%d, nil), want (%d, nil)", n, len(decompressed))
+ }
+ if !bytes.Equal(payload, decompressed) {
+ t.Fatalf("DecompressInto(_, Compress(_, %q)) yielded %q, want %q", payload, decompressed, payload)
+ }
+
+ // Ensure that decompressing into a buffer too small errors appropriately.
+ smallBuffer := make([]byte, len(payload)-1)
+ if _, err := DecompressInto(smallBuffer, compressed); !IsDstSizeTooSmallError(err) {
+ t.Fatalf("DecompressInto(<%d-sized buffer>, Compress(_, %q)) = %v, want 'Destination buffer is too small'",
+ len(smallBuffer), payload, err)
+ }
+}
+
 func TestCompressLevel(t *testing.T) {
  inputs := [][]byte{
  nil, {}, {0}, []byte("Hello World!"),