strings: add Builder.Cap

To report the capacity of the underlying buffer. The method mirrors
bytes.Buffer.Cap.

The method can be useful to know whether or not calling write or grow
methods will result in an allocation, or to know how much memory has
been allocated so far.

Fixes #26269.

Change-Id: I391db45ae825011566b594836991e28135369a78
Reviewed-on: https://go-review.googlesource.com/122835
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/strings/builder.go b/src/strings/builder.go
index ac58f34e1dec25048761a3047ee87a2c7941a441..3f33a87508764fabc08c929a6a45c68f4eb90f7a 100644 (file)
--- a/src/strings/builder.go
+++ b/src/strings/builder.go
@@ -50,6 +50,11 @@ func (b *Builder) String() string {
 // Len returns the number of accumulated bytes; b.Len() == len(b.String()).
 func (b *Builder) Len() int { return len(b.buf) }
 
+// Cap returns the capacity of the builder's underlying byte slice. It is the
+// total space allocated for the string being built and includes any bytes
+// already written.
+func (b *Builder) Cap() int { return cap(b.buf) }
+
 // Reset resets the Builder to be empty.
 func (b *Builder) Reset() {
        b.addr = nil

diff --git a/src/strings/builder_test.go b/src/strings/builder_test.go
index 949f214619d5e4a9d2d63d709e0c873d47421f38..9e597015d88f44cbfb516c425f929e28c4aa8618 100644 (file)
--- a/src/strings/builder_test.go
+++ b/src/strings/builder_test.go
@@ -20,6 +20,9 @@ func check(t *testing.T, b *Builder, want string) {
        if n := b.Len(); n != len(got) {
                t.Errorf("Len: got %d; but len(String()) is %d", n, len(got))
        }
+       if n := b.Cap(); n < len(got) {
+               t.Errorf("Cap: got %d; but len(String()) is %d", n, len(got))
+       }
 }
 
 func TestBuilder(t *testing.T) {
@@ -89,6 +92,9 @@ func TestBuilderGrow(t *testing.T) {
                allocs := testing.AllocsPerRun(100, func() {
                        var b Builder
                        b.Grow(growLen) // should be only alloc, when growLen > 0
+                       if b.Cap() < growLen {
+                               t.Fatalf("growLen=%d: Cap() is lower than growLen", growLen)
+                       }
                        b.Write(p)
                        if b.String() != string(p) {
                                t.Fatalf("growLen=%d: bad data written after Grow", growLen)
@@ -226,6 +232,16 @@ func TestBuilderCopyPanic(t *testing.T) {
                                b.Len()
                        },
                },
+               {
+                       name:      "Cap",
+                       wantPanic: false,
+                       fn: func() {
+                               var a Builder
+                               a.WriteByte('x')
+                               b := a
+                               b.Cap()
+                       },
+               },
                {
                        name:      "Reset",
                        wantPanic: false,