bytes: export Cap method for buffer

Obtaining the actual size of the underlying storage of the buffer can
be very useful in various scenarios. Long running programs which write
and read large amounts of data to buffers might have to recycle
buffers in order to avoid holding onto potentially huge buffers.

For example, a piece of code which buffers a lot of data in a buffer
might need to release the big buffer and start again with a smaller
buffer after it finished processing the huge amount of data.

In cases where pools of bytes.Buffer are used, being able to check the
size of the allocated data can be very useful.

Instead of forking bytes.Buffer or writing new code, we can export the
Cap() method.

Change-Id: I79d4f0a3cff53b9419d82c8122964761e9e38566
Reviewed-on: https://go-review.googlesource.com/8342
Reviewed-by: Rob Pike <r@golang.org>

src/bytes/buffer.go

@@ -56,6 +56,10 @@ func (b *Buffer) String() string {
 // b.Len() == len(b.Bytes()).
 func (b *Buffer) Len() int { return len(b.buf) - b.off }
 
+// Cap returns the capacity of the buffer's underlying byte slice, that is, the
+// total space allocated for the the buffer's data.
+func (b *Buffer) Cap() int { return cap(b.buf) }
+
 // Truncate discards all but the first n unread bytes from the buffer.
 // It panics if n is negative or greater than the length of the buffer.
 func (b *Buffer) Truncate(n int) {

src/bytes/buffer_test.go

@@ -231,6 +231,23 @@ func TestMixedReadsAndWrites(t *testing.T) {
 	empty(t, "TestMixedReadsAndWrites (2)", &buf, s, make([]byte, buf.Len()))
 }
 
+func TestCapWithPreallocatedSlice(t *testing.T) {
+	buf := NewBuffer(make([]byte, 10))
+	n := buf.Cap()
+	if n != 10 {
+		t.Errorf("expected 10, got %d", n)
+	}
+}
+
+func TestCapWithSliceAndWrittenData(t *testing.T) {
+	buf := NewBuffer(make([]byte, 0, 10))
+	buf.Write([]byte("test"))
+	n := buf.Cap()
+	if n != 10 {
+		t.Errorf("expected 10, got %d", n)
+	}
+}
+
 func TestNil(t *testing.T) {
 	var b *Buffer
 	if b.String() != "<nil>" {

src/bytes/export_test.go

@@ -7,7 +7,3 @@ package bytes
 // Export func for testing
 var IndexBytePortable = indexBytePortable
 var EqualPortable = equalPortable
-
-func (b *Buffer) Cap() int {
-	return cap(b.buf)
-}