buffer.go 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413
  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.
  4. package bufio
  5. // Simple byte buffer for marshaling data.
  6. import (
  7. "bytes"
  8. "errors"
  9. "io"
  10. "unicode/utf8"
  11. )
  12. // A Buffer is a variable-sized buffer of bytes with Read and Write methods.
  13. // The zero value for Buffer is an empty buffer ready to use.
  14. type Buffer struct {
  15. buf []byte // contents are the bytes buf[off : len(buf)]
  16. off int // read at &buf[off], write at &buf[len(buf)]
  17. runeBytes [utf8.UTFMax]byte // avoid allocation of slice on each WriteByte or Rune
  18. bootstrap [64]byte // memory to hold first slice; helps small buffers (Printf) avoid allocation.
  19. lastRead readOp // last read operation, so that Unread* can work correctly.
  20. }
  21. // The readOp constants describe the last action performed on
  22. // the buffer, so that UnreadRune and UnreadByte can
  23. // check for invalid usage.
  24. type readOp int
  25. const (
  26. opInvalid readOp = iota // Non-read operation.
  27. opReadRune // Read rune.
  28. opRead // Any other read operation.
  29. )
  30. // ErrTooLarge is passed to panic if memory cannot be allocated to store data in a buffer.
  31. var ErrTooLarge = errors.New("bytes.Buffer: too large")
  32. // Bytes returns a slice of the contents of the unread portion of the buffer;
  33. // len(b.Bytes()) == b.Len(). If the caller changes the contents of the
  34. // returned slice, the contents of the buffer will change provided there
  35. // are no intervening method calls on the Buffer.
  36. func (b *Buffer) Bytes() []byte { return b.buf[b.off:] }
  37. // String returns the contents of the unread portion of the buffer
  38. // as a string. If the Buffer is a nil pointer, it returns "<nil>".
  39. func (b *Buffer) String() string {
  40. if b == nil {
  41. // Special case, useful in debugging.
  42. return "<nil>"
  43. }
  44. return string(b.buf[b.off:])
  45. }
  46. // Len returns the number of bytes of the unread portion of the buffer;
  47. // b.Len() == len(b.Bytes()).
  48. func (b *Buffer) Len() int { return len(b.buf) - b.off }
  49. // Truncate discards all but the first n unread bytes from the buffer.
  50. // It panics if n is negative or greater than the length of the buffer.
  51. func (b *Buffer) Truncate(n int) {
  52. b.lastRead = opInvalid
  53. switch {
  54. case n < 0 || n > b.Len():
  55. panic("bytes.Buffer: truncation out of range")
  56. case n == 0:
  57. // Reuse buffer space.
  58. b.off = 0
  59. }
  60. b.buf = b.buf[0 : b.off+n]
  61. }
  62. // Reset resets the buffer so it has no content.
  63. // b.Reset() is the same as b.Truncate(0).
  64. func (b *Buffer) Reset() { b.Truncate(0) }
  65. // grow grows the buffer to guarantee space for n more bytes.
  66. // It returns the index where bytes should be written.
  67. // If the buffer can't grow it will panic with ErrTooLarge.
  68. func (b *Buffer) grow(n int) int {
  69. m := b.Len()
  70. // If buffer is empty, reset to recover space.
  71. if m == 0 && b.off != 0 {
  72. b.Truncate(0)
  73. }
  74. if len(b.buf)+n > cap(b.buf) {
  75. var buf []byte
  76. if b.buf == nil && n <= len(b.bootstrap) {
  77. buf = b.bootstrap[0:]
  78. } else if m+n <= cap(b.buf)/2 {
  79. // We can slide things down instead of allocating a new
  80. // slice. We only need m+n <= cap(b.buf) to slide, but
  81. // we instead let capacity get twice as large so we
  82. // don't spend all our time copying.
  83. copy(b.buf[:], b.buf[b.off:])
  84. buf = b.buf[:m]
  85. } else {
  86. // not enough space anywhere
  87. buf = makeSlice(2*cap(b.buf) + n)
  88. copy(buf, b.buf[b.off:])
  89. }
  90. b.buf = buf
  91. b.off = 0
  92. }
  93. b.buf = b.buf[0 : b.off+m+n]
  94. return b.off + m
  95. }
  96. // Grow grows the buffer's capacity, if necessary, to guarantee space for
  97. // another n bytes. After Grow(n), at least n bytes can be written to the
  98. // buffer without another allocation.
  99. // If n is negative, Grow will panic.
  100. // If the buffer can't grow it will panic with ErrTooLarge.
  101. func (b *Buffer) Grow(n int) {
  102. if n < 0 {
  103. panic("bytes.Buffer.Grow: negative count")
  104. }
  105. m := b.grow(n)
  106. b.buf = b.buf[0:m]
  107. }
  108. // Write appends the contents of p to the buffer, growing the buffer as
  109. // needed. The return value n is the length of p; err is always nil. If the
  110. // buffer becomes too large, Write will panic with ErrTooLarge.
  111. func (b *Buffer) Write(p []byte) (n int, err error) {
  112. b.lastRead = opInvalid
  113. m := b.grow(len(p))
  114. return copy(b.buf[m:], p), nil
  115. }
  116. // WriteString appends the contents of s to the buffer, growing the buffer as
  117. // needed. The return value n is the length of s; err is always nil. If the
  118. // buffer becomes too large, WriteString will panic with ErrTooLarge.
  119. func (b *Buffer) WriteString(s string) (n int, err error) {
  120. b.lastRead = opInvalid
  121. m := b.grow(len(s))
  122. return copy(b.buf[m:], s), nil
  123. }
  124. // MinRead is the minimum slice size passed to a Read call by
  125. // Buffer.ReadFrom. As long as the Buffer has at least MinRead bytes beyond
  126. // what is required to hold the contents of r, ReadFrom will not grow the
  127. // underlying buffer.
  128. const MinRead = 512
  129. // ReadFrom reads data from r until EOF and appends it to the buffer, growing
  130. // the buffer as needed. The return value n is the number of bytes read. Any
  131. // error except io.EOF encountered during the read is also returned. If the
  132. // buffer becomes too large, ReadFrom will panic with ErrTooLarge.
  133. func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) {
  134. b.lastRead = opInvalid
  135. // If buffer is empty, reset to recover space.
  136. if b.off >= len(b.buf) {
  137. b.Truncate(0)
  138. }
  139. for {
  140. if free := cap(b.buf) - len(b.buf); free < MinRead {
  141. // not enough space at end
  142. newBuf := b.buf
  143. if b.off+free < MinRead {
  144. // not enough space using beginning of buffer;
  145. // double buffer capacity
  146. newBuf = makeSlice(2*cap(b.buf) + MinRead)
  147. }
  148. copy(newBuf, b.buf[b.off:])
  149. b.buf = newBuf[:len(b.buf)-b.off]
  150. b.off = 0
  151. }
  152. m, e := r.Read(b.buf[len(b.buf):cap(b.buf)])
  153. b.buf = b.buf[0 : len(b.buf)+m]
  154. n += int64(m)
  155. if e == io.EOF {
  156. break
  157. }
  158. if e != nil {
  159. return n, e
  160. }
  161. }
  162. return n, nil // err is EOF, so return nil explicitly
  163. }
  164. // makeSlice allocates a slice of size n. If the allocation fails, it panics
  165. // with ErrTooLarge.
  166. func makeSlice(n int) []byte {
  167. // If the make fails, give a known error.
  168. defer func() {
  169. if recover() != nil {
  170. panic(ErrTooLarge)
  171. }
  172. }()
  173. return make([]byte, n)
  174. }
  175. // WriteTo writes data to w until the buffer is drained or an error occurs.
  176. // The return value n is the number of bytes written; it always fits into an
  177. // int, but it is int64 to match the io.WriterTo interface. Any error
  178. // encountered during the write is also returned.
  179. func (b *Buffer) WriteTo(w io.Writer) (n int64, err error) {
  180. b.lastRead = opInvalid
  181. if b.off < len(b.buf) {
  182. nBytes := b.Len()
  183. m, e := w.Write(b.buf[b.off:])
  184. if m > nBytes {
  185. panic("bytes.Buffer.WriteTo: invalid Write count")
  186. }
  187. b.off += m
  188. n = int64(m)
  189. if e != nil {
  190. return n, e
  191. }
  192. // all bytes should have been written, by definition of
  193. // Write method in io.Writer
  194. if m != nBytes {
  195. return n, io.ErrShortWrite
  196. }
  197. }
  198. // Buffer is now empty; reset.
  199. b.Truncate(0)
  200. return
  201. }
  202. // WriteByte appends the byte c to the buffer, growing the buffer as needed.
  203. // The returned error is always nil, but is included to match bufio.Writer's
  204. // WriteByte. If the buffer becomes too large, WriteByte will panic with
  205. // ErrTooLarge.
  206. func (b *Buffer) WriteByte(c byte) error {
  207. b.lastRead = opInvalid
  208. m := b.grow(1)
  209. b.buf[m] = c
  210. return nil
  211. }
  212. // WriteRune appends the UTF-8 encoding of Unicode code point r to the
  213. // buffer, returning its length and an error, which is always nil but is
  214. // included to match bufio.Writer's WriteRune. The buffer is grown as needed;
  215. // if it becomes too large, WriteRune will panic with ErrTooLarge.
  216. func (b *Buffer) WriteRune(r rune) (n int, err error) {
  217. if r < utf8.RuneSelf {
  218. b.WriteByte(byte(r))
  219. return 1, nil
  220. }
  221. n = utf8.EncodeRune(b.runeBytes[0:], r)
  222. b.Write(b.runeBytes[0:n])
  223. return n, nil
  224. }
  225. // Read reads the next len(p) bytes from the buffer or until the buffer
  226. // is drained. The return value n is the number of bytes read. If the
  227. // buffer has no data to return, err is io.EOF (unless len(p) is zero);
  228. // otherwise it is nil.
  229. func (b *Buffer) Read(p []byte) (n int, err error) {
  230. b.lastRead = opInvalid
  231. if b.off >= len(b.buf) {
  232. // Buffer is empty, reset to recover space.
  233. b.Truncate(0)
  234. if len(p) == 0 {
  235. return
  236. }
  237. return 0, io.EOF
  238. }
  239. n = copy(p, b.buf[b.off:])
  240. b.off += n
  241. if n > 0 {
  242. b.lastRead = opRead
  243. }
  244. return
  245. }
  246. // Next returns a slice containing the next n bytes from the buffer,
  247. // advancing the buffer as if the bytes had been returned by Read.
  248. // If there are fewer than n bytes in the buffer, Next returns the entire buffer.
  249. // The slice is only valid until the next call to a read or write method.
  250. func (b *Buffer) Next(n int) []byte {
  251. b.lastRead = opInvalid
  252. m := b.Len()
  253. if n > m {
  254. n = m
  255. }
  256. data := b.buf[b.off : b.off+n]
  257. b.off += n
  258. if n > 0 {
  259. b.lastRead = opRead
  260. }
  261. return data
  262. }
  263. // ReadByte reads and returns the next byte from the buffer.
  264. // If no byte is available, it returns error io.EOF.
  265. func (b *Buffer) ReadByte() (c byte, err error) {
  266. b.lastRead = opInvalid
  267. if b.off >= len(b.buf) {
  268. // Buffer is empty, reset to recover space.
  269. b.Truncate(0)
  270. return 0, io.EOF
  271. }
  272. c = b.buf[b.off]
  273. b.off++
  274. b.lastRead = opRead
  275. return c, nil
  276. }
  277. // ReadRune reads and returns the next UTF-8-encoded
  278. // Unicode code point from the buffer.
  279. // If no bytes are available, the error returned is io.EOF.
  280. // If the bytes are an erroneous UTF-8 encoding, it
  281. // consumes one byte and returns U+FFFD, 1.
  282. func (b *Buffer) ReadRune() (r rune, size int, err error) {
  283. b.lastRead = opInvalid
  284. if b.off >= len(b.buf) {
  285. // Buffer is empty, reset to recover space.
  286. b.Truncate(0)
  287. return 0, 0, io.EOF
  288. }
  289. b.lastRead = opReadRune
  290. c := b.buf[b.off]
  291. if c < utf8.RuneSelf {
  292. b.off++
  293. return rune(c), 1, nil
  294. }
  295. r, n := utf8.DecodeRune(b.buf[b.off:])
  296. b.off += n
  297. return r, n, nil
  298. }
  299. // UnreadRune unreads the last rune returned by ReadRune.
  300. // If the most recent read or write operation on the buffer was
  301. // not a ReadRune, UnreadRune returns an error. (In this regard
  302. // it is stricter than UnreadByte, which will unread the last byte
  303. // from any read operation.)
  304. func (b *Buffer) UnreadRune() error {
  305. if b.lastRead != opReadRune {
  306. return errors.New("bytes.Buffer: UnreadRune: previous operation was not ReadRune")
  307. }
  308. b.lastRead = opInvalid
  309. if b.off > 0 {
  310. _, n := utf8.DecodeLastRune(b.buf[0:b.off])
  311. b.off -= n
  312. }
  313. return nil
  314. }
  315. // UnreadByte unreads the last byte returned by the most recent
  316. // read operation. If write has happened since the last read, UnreadByte
  317. // returns an error.
  318. func (b *Buffer) UnreadByte() error {
  319. if b.lastRead != opReadRune && b.lastRead != opRead {
  320. return errors.New("bytes.Buffer: UnreadByte: previous operation was not a read")
  321. }
  322. b.lastRead = opInvalid
  323. if b.off > 0 {
  324. b.off--
  325. }
  326. return nil
  327. }
  328. // ReadBytes reads until the first occurrence of delim in the input,
  329. // returning a slice containing the data up to and including the delimiter.
  330. // If ReadBytes encounters an error before finding a delimiter,
  331. // it returns the data read before the error and the error itself (often io.EOF).
  332. // ReadBytes returns err != nil if and only if the returned data does not end in
  333. // delim.
  334. func (b *Buffer) ReadBytes(delim byte) (line []byte, err error) {
  335. slice, err := b.readSlice(delim)
  336. // return a copy of slice. The buffer's backing array may
  337. // be overwritten by later calls.
  338. line = append(line, slice...)
  339. return
  340. }
  341. // readSlice is like ReadBytes but returns a reference to internal buffer data.
  342. func (b *Buffer) readSlice(delim byte) (line []byte, err error) {
  343. i := bytes.IndexByte(b.buf[b.off:], delim)
  344. end := b.off + i + 1
  345. if i < 0 {
  346. end = len(b.buf)
  347. err = io.EOF
  348. }
  349. line = b.buf[b.off:end]
  350. b.off = end
  351. b.lastRead = opRead
  352. return line, err
  353. }
  354. // ReadString reads until the first occurrence of delim in the input,
  355. // returning a string containing the data up to and including the delimiter.
  356. // If ReadString encounters an error before finding a delimiter,
  357. // it returns the data read before the error and the error itself (often io.EOF).
  358. // ReadString returns err != nil if and only if the returned data does not end
  359. // in delim.
  360. func (b *Buffer) ReadString(delim byte) (line string, err error) {
  361. slice, err := b.readSlice(delim)
  362. return string(slice), err
  363. }
  364. // NewBuffer creates and initializes a new Buffer using buf as its initial
  365. // contents. It is intended to prepare a Buffer to read existing data. It
  366. // can also be used to size the internal buffer for writing. To do that,
  367. // buf should have the desired capacity but a length of zero.
  368. //
  369. // In most cases, new(Buffer) (or just declaring a Buffer variable) is
  370. // sufficient to initialize a Buffer.
  371. func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }
  372. // NewBufferString creates and initializes a new Buffer using string s as its
  373. // initial contents. It is intended to prepare a buffer to read an existing
  374. // string.
  375. //
  376. // In most cases, new(Buffer) (or just declaring a Buffer variable) is
  377. // sufficient to initialize a Buffer.
  378. func NewBufferString(s string) *Buffer {
  379. return &Buffer{buf: []byte(s)}
  380. }