1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
7 // Simple byte buffer for marshaling data.
15 // A Buffer is a variable-sized buffer of bytes with Read and Write methods.
16 // The zero value for Buffer is an empty buffer ready to use.
18 buf
[]byte // contents are the bytes buf[off : len(buf)]
19 off
int // read at &buf[off], write at &buf[len(buf)]
20 bootstrap
[64]byte // memory to hold first slice; helps small buffers avoid allocation.
21 lastRead readOp
// last read operation, so that Unread* can work correctly.
24 // The readOp constants describe the last action performed on
25 // the buffer, so that UnreadRune and UnreadByte can check for
26 // invalid usage. opReadRuneX constants are chosen such that
27 // converted to int they correspond to the rune size that was read.
31 opRead readOp
= -1 // Any other read operation.
32 opInvalid
= 0 // Non-read operation.
33 opReadRune1
= 1 // Read rune of size 1.
34 opReadRune2
= 2 // Read rune of size 2.
35 opReadRune3
= 3 // Read rune of size 3.
36 opReadRune4
= 4 // Read rune of size 4.
39 // ErrTooLarge is passed to panic if memory cannot be allocated to store data in a buffer.
40 var ErrTooLarge
= errors
.New("bytes.Buffer: too large")
42 // Bytes returns a slice of length b.Len() holding the unread portion of the buffer.
43 // The slice is valid for use only until the next buffer modification (that is,
44 // only until the next call to a method like Read, Write, Reset, or Truncate).
45 // The slice aliases the buffer content at least until the next buffer modification,
46 // so immediate changes to the slice will affect the result of future reads.
47 func (b
*Buffer
) Bytes() []byte { return b
.buf
[b
.off
:] }
49 // String returns the contents of the unread portion of the buffer
50 // as a string. If the Buffer is a nil pointer, it returns "<nil>".
51 func (b
*Buffer
) String() string {
53 // Special case, useful in debugging.
56 return string(b
.buf
[b
.off
:])
59 // Len returns the number of bytes of the unread portion of the buffer;
60 // b.Len() == len(b.Bytes()).
61 func (b
*Buffer
) Len() int { return len(b
.buf
) - b
.off
}
63 // Cap returns the capacity of the buffer's underlying byte slice, that is, the
64 // total space allocated for the buffer's data.
65 func (b
*Buffer
) Cap() int { return cap(b
.buf
) }
67 // Truncate discards all but the first n unread bytes from the buffer
68 // but continues to use the same allocated storage.
69 // It panics if n is negative or greater than the length of the buffer.
70 func (b
*Buffer
) Truncate(n
int) {
71 b
.lastRead
= opInvalid
73 case n
< 0 || n
> b
.Len():
74 panic("bytes.Buffer: truncation out of range")
76 // Reuse buffer space.
79 b
.buf
= b
.buf
[0 : b
.off
+n
]
82 // Reset resets the buffer to be empty,
83 // but it retains the underlying storage for use by future writes.
84 // Reset is the same as Truncate(0).
85 func (b
*Buffer
) Reset() { b
.Truncate(0) }
87 // grow grows the buffer to guarantee space for n more bytes.
88 // It returns the index where bytes should be written.
89 // If the buffer can't grow it will panic with ErrTooLarge.
90 func (b
*Buffer
) grow(n
int) int {
92 // If buffer is empty, reset to recover space.
93 if m
== 0 && b
.off
!= 0 {
96 if len(b
.buf
)+n
> cap(b
.buf
) {
98 if b
.buf
== nil && n
<= len(b
.bootstrap
) {
100 } else if m
+n
<= cap(b
.buf
)/2 {
101 // We can slide things down instead of allocating a new
102 // slice. We only need m+n <= cap(b.buf) to slide, but
103 // we instead let capacity get twice as large so we
104 // don't spend all our time copying.
105 copy(b
.buf
[:], b
.buf
[b
.off
:])
108 // not enough space anywhere
109 buf
= makeSlice(2*cap(b
.buf
) + n
)
110 copy(buf
, b
.buf
[b
.off
:])
115 b
.buf
= b
.buf
[0 : b
.off
+m
+n
]
119 // Grow grows the buffer's capacity, if necessary, to guarantee space for
120 // another n bytes. After Grow(n), at least n bytes can be written to the
121 // buffer without another allocation.
122 // If n is negative, Grow will panic.
123 // If the buffer can't grow it will panic with ErrTooLarge.
124 func (b
*Buffer
) Grow(n
int) {
126 panic("bytes.Buffer.Grow: negative count")
132 // Write appends the contents of p to the buffer, growing the buffer as
133 // needed. The return value n is the length of p; err is always nil. If the
134 // buffer becomes too large, Write will panic with ErrTooLarge.
135 func (b
*Buffer
) Write(p
[]byte) (n
int, err error
) {
136 b
.lastRead
= opInvalid
138 return copy(b
.buf
[m
:], p
), nil
141 // WriteString appends the contents of s to the buffer, growing the buffer as
142 // needed. The return value n is the length of s; err is always nil. If the
143 // buffer becomes too large, WriteString will panic with ErrTooLarge.
144 func (b
*Buffer
) WriteString(s
string) (n
int, err error
) {
145 b
.lastRead
= opInvalid
147 return copy(b
.buf
[m
:], s
), nil
150 // MinRead is the minimum slice size passed to a Read call by
151 // Buffer.ReadFrom. As long as the Buffer has at least MinRead bytes beyond
152 // what is required to hold the contents of r, ReadFrom will not grow the
153 // underlying buffer.
156 // ReadFrom reads data from r until EOF and appends it to the buffer, growing
157 // the buffer as needed. The return value n is the number of bytes read. Any
158 // error except io.EOF encountered during the read is also returned. If the
159 // buffer becomes too large, ReadFrom will panic with ErrTooLarge.
160 func (b
*Buffer
) ReadFrom(r io
.Reader
) (n
int64, err error
) {
161 b
.lastRead
= opInvalid
162 // If buffer is empty, reset to recover space.
163 if b
.off
>= len(b
.buf
) {
167 if free
:= cap(b
.buf
) - len(b
.buf
); free
< MinRead
{
168 // not enough space at end
170 if b
.off
+free
< MinRead
{
171 // not enough space using beginning of buffer;
172 // double buffer capacity
173 newBuf
= makeSlice(2*cap(b
.buf
) + MinRead
)
175 copy(newBuf
, b
.buf
[b
.off
:])
176 b
.buf
= newBuf
[:len(b
.buf
)-b
.off
]
179 m
, e
:= r
.Read(b
.buf
[len(b
.buf
):cap(b
.buf
)])
180 b
.buf
= b
.buf
[0 : len(b
.buf
)+m
]
189 return n
, nil // err is EOF, so return nil explicitly
192 // makeSlice allocates a slice of size n. If the allocation fails, it panics
194 func makeSlice(n
int) []byte {
195 // If the make fails, give a known error.
197 if recover() != nil {
201 return make([]byte, n
)
204 // WriteTo writes data to w until the buffer is drained or an error occurs.
205 // The return value n is the number of bytes written; it always fits into an
206 // int, but it is int64 to match the io.WriterTo interface. Any error
207 // encountered during the write is also returned.
208 func (b
*Buffer
) WriteTo(w io
.Writer
) (n
int64, err error
) {
209 b
.lastRead
= opInvalid
210 if b
.off
< len(b
.buf
) {
212 m
, e
:= w
.Write(b
.buf
[b
.off
:])
214 panic("bytes.Buffer.WriteTo: invalid Write count")
221 // all bytes should have been written, by definition of
222 // Write method in io.Writer
224 return n
, io
.ErrShortWrite
227 // Buffer is now empty; reset.
232 // WriteByte appends the byte c to the buffer, growing the buffer as needed.
233 // The returned error is always nil, but is included to match bufio.Writer's
234 // WriteByte. If the buffer becomes too large, WriteByte will panic with
236 func (b
*Buffer
) WriteByte(c
byte) error
{
237 b
.lastRead
= opInvalid
243 // WriteRune appends the UTF-8 encoding of Unicode code point r to the
244 // buffer, returning its length and an error, which is always nil but is
245 // included to match bufio.Writer's WriteRune. The buffer is grown as needed;
246 // if it becomes too large, WriteRune will panic with ErrTooLarge.
247 func (b
*Buffer
) WriteRune(r rune
) (n
int, err error
) {
248 if r
< utf8
.RuneSelf
{
252 b
.lastRead
= opInvalid
253 m
:= b
.grow(utf8
.UTFMax
)
254 n
= utf8
.EncodeRune(b
.buf
[m
:m
+utf8
.UTFMax
], r
)
259 // Read reads the next len(p) bytes from the buffer or until the buffer
260 // is drained. The return value n is the number of bytes read. If the
261 // buffer has no data to return, err is io.EOF (unless len(p) is zero);
262 // otherwise it is nil.
263 func (b
*Buffer
) Read(p
[]byte) (n
int, err error
) {
264 b
.lastRead
= opInvalid
265 if b
.off
>= len(b
.buf
) {
266 // Buffer is empty, reset to recover space.
273 n
= copy(p
, b
.buf
[b
.off
:])
281 // Next returns a slice containing the next n bytes from the buffer,
282 // advancing the buffer as if the bytes had been returned by Read.
283 // If there are fewer than n bytes in the buffer, Next returns the entire buffer.
284 // The slice is only valid until the next call to a read or write method.
285 func (b
*Buffer
) Next(n
int) []byte {
286 b
.lastRead
= opInvalid
291 data
:= b
.buf
[b
.off
: b
.off
+n
]
299 // ReadByte reads and returns the next byte from the buffer.
300 // If no byte is available, it returns error io.EOF.
301 func (b
*Buffer
) ReadByte() (byte, error
) {
302 b
.lastRead
= opInvalid
303 if b
.off
>= len(b
.buf
) {
304 // Buffer is empty, reset to recover space.
314 // ReadRune reads and returns the next UTF-8-encoded
315 // Unicode code point from the buffer.
316 // If no bytes are available, the error returned is io.EOF.
317 // If the bytes are an erroneous UTF-8 encoding, it
318 // consumes one byte and returns U+FFFD, 1.
319 func (b
*Buffer
) ReadRune() (r rune
, size
int, err error
) {
320 b
.lastRead
= opInvalid
321 if b
.off
>= len(b
.buf
) {
322 // Buffer is empty, reset to recover space.
327 if c
< utf8
.RuneSelf
{
329 b
.lastRead
= opReadRune1
330 return rune(c
), 1, nil
332 r
, n
:= utf8
.DecodeRune(b
.buf
[b
.off
:])
334 b
.lastRead
= readOp(n
)
338 // UnreadRune unreads the last rune returned by ReadRune.
339 // If the most recent read or write operation on the buffer was
340 // not a ReadRune, UnreadRune returns an error. (In this regard
341 // it is stricter than UnreadByte, which will unread the last byte
342 // from any read operation.)
343 func (b
*Buffer
) UnreadRune() error
{
344 if b
.lastRead
<= opInvalid
{
345 return errors
.New("bytes.Buffer: UnreadRune: previous operation was not ReadRune")
347 if b
.off
>= int(b
.lastRead
) {
348 b
.off
-= int(b
.lastRead
)
350 b
.lastRead
= opInvalid
354 // UnreadByte unreads the last byte returned by the most recent
355 // read operation. If write has happened since the last read, UnreadByte
357 func (b
*Buffer
) UnreadByte() error
{
358 if b
.lastRead
== opInvalid
{
359 return errors
.New("bytes.Buffer: UnreadByte: previous operation was not a read")
361 b
.lastRead
= opInvalid
368 // ReadBytes reads until the first occurrence of delim in the input,
369 // returning a slice containing the data up to and including the delimiter.
370 // If ReadBytes encounters an error before finding a delimiter,
371 // it returns the data read before the error and the error itself (often io.EOF).
372 // ReadBytes returns err != nil if and only if the returned data does not end in
374 func (b
*Buffer
) ReadBytes(delim
byte) (line
[]byte, err error
) {
375 slice
, err
:= b
.readSlice(delim
)
376 // return a copy of slice. The buffer's backing array may
377 // be overwritten by later calls.
378 line
= append(line
, slice
...)
382 // readSlice is like ReadBytes but returns a reference to internal buffer data.
383 func (b
*Buffer
) readSlice(delim
byte) (line
[]byte, err error
) {
384 i
:= IndexByte(b
.buf
[b
.off
:], delim
)
390 line
= b
.buf
[b
.off
:end
]
396 // ReadString reads until the first occurrence of delim in the input,
397 // returning a string containing the data up to and including the delimiter.
398 // If ReadString encounters an error before finding a delimiter,
399 // it returns the data read before the error and the error itself (often io.EOF).
400 // ReadString returns err != nil if and only if the returned data does not end
402 func (b
*Buffer
) ReadString(delim
byte) (line
string, err error
) {
403 slice
, err
:= b
.readSlice(delim
)
404 return string(slice
), err
407 // NewBuffer creates and initializes a new Buffer using buf as its initial
408 // contents. It is intended to prepare a Buffer to read existing data. It
409 // can also be used to size the internal buffer for writing. To do that,
410 // buf should have the desired capacity but a length of zero.
412 // In most cases, new(Buffer) (or just declaring a Buffer variable) is
413 // sufficient to initialize a Buffer.
414 func NewBuffer(buf
[]byte) *Buffer
{ return &Buffer
{buf
: buf
} }
416 // NewBufferString creates and initializes a new Buffer using string s as its
417 // initial contents. It is intended to prepare a buffer to read an existing
420 // In most cases, new(Buffer) (or just declaring a Buffer variable) is
421 // sufficient to initialize a Buffer.
422 func NewBufferString(s
string) *Buffer
{
423 return &Buffer
{buf
: []byte(s
)}