so/bytes: zero-copy NewBuffer

Author: nalgeon

so/bytes/buffer.go

@@ -32,6 +32,9 @@ const maxInt = int(math.MaxInt64)
 
 // A Buffer is a variable-sized buffer of bytes with [Buffer.Read] and [Buffer.Write] methods.
 // The zero value for Buffer is an empty buffer ready to use (with default allocator).
+// A Buffer grows as needed when writing data, using the provided allocator.
+// The caller is responsible for freeing the buffer's resources
+// with [Buffer.Free] when done using it.
 type Buffer struct {
 	a   mem.Allocator // memory allocator; nil falls back to default one.
 	buf []byte        // contents are the bytes buf[off : len(buf)]
@@ -384,29 +387,38 @@ func (b *Buffer) ReadString(delim byte) (string, error) {
 	return String(b.a, slice), err
 }
 
-// NewBuffer creates and initializes a new [Buffer] using a copy of buf as its
-// initial contents. It is intended to prepare a buffer to read existing data.
+// NewBuffer creates and initializes a new [Buffer] using buf as its
+// initial contents. The new Buffer takes ownership of buf, and the
+// caller should not use buf after this call. NewBuffer is intended to
+// prepare a Buffer to read existing data. It can also be used to set
+// the initial size of the internal buffer for writing. To do that,
+// buf should have the desired capacity but a length of zero.
+//
+// If buf was allocated with an allocator, the same allocator must be
+// passed to NewBuffer so that [Buffer.Free] can release it correctly.
+// Do not call [Buffer.Free] if buf was not heap-allocated.
+//
+// Do not provide a stack-allocated buf if you intend to write to the buffer,
+// as the buffer may need to grow and reallocate, which would cause free()
+// on a stack pointer. Only use heap-allocated slices in this case.
 //
 // If the allocator is nil, uses the system allocator.
-// The caller is responsible for freeing the buffer's resources
-// with [Buffer.Free] when done using it.
 func NewBuffer(a mem.Allocator, buf []byte) Buffer {
-	if buf == nil {
-		return Buffer{a: a}
-	}
-	b := mem.AllocSlice[byte](a, len(buf), cap(buf))
-	copy(b, buf)
-	return Buffer{a: a, buf: b}
+	return Buffer{a: a, buf: buf}
 }
 
 // NewBufferString creates and initializes a new [Buffer] using string s as its
 // initial contents. It is intended to prepare a buffer to read an existing string.
 //
+// If s was allocated with an allocator, the same allocator must be
+// passed to NewBuffer so that [Buffer.Free] can release it correctly.
+// Do not call [Buffer.Free] if s was not heap-allocated.
+//
+// Do not provide a stack-allocated s if you intend to write to the buffer,
+// as the buffer may need to grow and reallocate, which would cause free()
+// on a stack pointer. Only use heap-allocated strings in this case.
+//
 // If the allocator is nil, uses the system allocator.
-// The caller is responsible for freeing the buffer's resources
-// with [Buffer.Free] when done using it.
 func NewBufferString(a mem.Allocator, s string) Buffer {
-	buf := mem.AllocSlice[byte](a, len(s), len(s))
-	copy(buf, s)
-	return Buffer{a: a, buf: buf}
+	return Buffer{a: a, buf: []byte(s)}
 }

testdata/std/bytes/dst/main.c

@@ -218,9 +218,27 @@ int main(void) {
         mem_FreeSlice(so_byte, (mem_Allocator){0}, uppered);
     }
     {
-        // Buffer.
-        bytes_Buffer buf = bytes_NewBuffer((mem_Allocator){0}, so_string_bytes(so_str("hello")));
-        bytes_Buffer_Write(&buf, so_string_bytes(so_str(" world")));
+        // Buffer (stack-allocated).
+        bytes_Buffer buf = bytes_NewBuffer((mem_Allocator){0}, so_string_bytes(so_str("hello world")));
+        if (so_string_ne(bytes_Buffer_String(&buf), so_str("hello world"))) {
+            so_panic("Buffer Write failed");
+        }
+        so_Slice rdbuf = so_make_slice(so_byte, 5, 5);
+        so_R_int_err _res1 = bytes_Buffer_Read(&buf, rdbuf);
+        so_int n = _res1.val;
+        so_Error err = _res1.err;
+        if (n != 5 || so_string_ne(so_bytes_string(rdbuf), so_str("hello")) || err != NULL) {
+            so_panic("Buffer Read failed");
+        }
+        if (so_string_ne(bytes_Buffer_String(&buf), so_str(" world"))) {
+            so_panic("Buffer Read did not advance the buffer");
+        }
+    }
+    {
+        // Buffer (heap-allocated).
+        bytes_Buffer buf = bytes_NewBuffer((mem_Allocator){0}, (so_Slice){0});
+        bytes_Buffer_WriteString(&buf, so_str("hello"));
+        bytes_Buffer_WriteString(&buf, so_str(" world"));
         if (so_string_ne(bytes_Buffer_String(&buf), so_str("hello world"))) {
             so_panic("Buffer Write failed");
         }
@@ -229,9 +247,9 @@ int main(void) {
             so_panic("Buffer Grow failed");
         }
         so_Slice rdbuf = so_make_slice(so_byte, 5, 5);
-        so_R_int_err _res1 = bytes_Buffer_Read(&buf, rdbuf);
-        so_int n = _res1.val;
-        so_Error err = _res1.err;
+        so_R_int_err _res2 = bytes_Buffer_Read(&buf, rdbuf);
+        so_int n = _res2.val;
+        so_Error err = _res2.err;
         if (n != 5 || so_string_ne(so_bytes_string(rdbuf), so_str("hello")) || err != NULL) {
             so_panic("Buffer Read failed");
         }
@@ -247,9 +265,9 @@ int main(void) {
         if (bytes_Reader_Len(&r) != so_len(s)) {
             so_panic("Reader Len failed");
         }
-        so_R_slice_err _res2 = io_ReadAll((mem_Allocator){0}, (io_Reader){.self = &r, .Read = bytes_Reader_Read});
-        so_Slice b = _res2.val;
-        so_Error err = _res2.err;
+        so_R_slice_err _res3 = io_ReadAll((mem_Allocator){0}, (io_Reader){.self = &r, .Read = bytes_Reader_Read});
+        so_Slice b = _res3.val;
+        so_Error err = _res3.err;
         if (err != NULL) {
             so_panic(err->msg);
         }

testdata/std/bytes/src/main.go

@@ -219,9 +219,25 @@ func main() {
 		mem.FreeSlice(nil, uppered)
 	}
 	{
-		// Buffer.
-		buf := bytes.NewBuffer(nil, []byte("hello"))
-		buf.Write([]byte(" world"))
+		// Buffer (stack-allocated).
+		buf := bytes.NewBuffer(nil, []byte("hello world"))
+		if buf.String() != "hello world" {
+			panic("Buffer Write failed")
+		}
+		rdbuf := make([]byte, 5)
+		n, err := buf.Read(rdbuf)
+		if n != 5 || string(rdbuf) != "hello" || err != nil {
+			panic("Buffer Read failed")
+		}
+		if buf.String() != " world" {
+			panic("Buffer Read did not advance the buffer")
+		}
+	}
+	{
+		// Buffer (heap-allocated).
+		buf := bytes.NewBuffer(nil, nil)
+		buf.WriteString("hello")
+		buf.WriteString(" world")
 		if buf.String() != "hello world" {
 			panic("Buffer Write failed")
 		}