README
¶
Flexible bytes buffer
Package flexbuf provides bytes buffer implementing many data access and
manipulation interfaces.
io.Writer
io.WriterAt
io.ByteWriter
io.WriterTo
io.StringWriter
io.Reader
io.ByteReader
io.ReaderAt
io.ReaderFrom
io.Seeker
io.Closer
fmt.Stringer
Additionally, flexbuf provides Truncate(size int64) error method to make
it almost a drop in replacement for os.File.
Installation
go get github.com/rzajac/flexbuf
Examples
buf := &flexbuf.Buffer{}
_, _ = buf.Write([]byte{0, 1, 2, 3})
_, _ = buf.Seek(-2, io.SeekEnd)
_, _ = buf.Write([]byte{4, 5})
_, _ = buf.Seek(0, io.SeekStart)
data, _ := ioutil.ReadAll(buf)
fmt.Println(data)
// Output: [0 1 4 5]
How is it different from bytes.Buffer?
The bytes.Buffer always reads from current offset and writes to the end of
the buffer, flexbuf behaves more like a file it reads and writes at current
offset. Also bytes.Buffer doesn't implement interfaces:
io.WriterAtio.ReaderAtio.Seekerio.Closer
or methods:
Truncate
Can I use flexbuf.Buffer as a replacement for os.File?
It depends. Even though flexbuf.Buffer probably implements all the methods
you need to use it as a replacement for os.File there are some minor
differences:
Truncatemethod does not returnos.PathErrorinstances.WriteAtwill not return error when used on an instance created withflexbuf.New(flexbuf.Append)orflexbuf.With(myBuf, flexbuf.Append).
Benchmarks
Some benchmarks between flexbuf.Buffer and bytes.Buffer:
BenchmarkWrite/flexbuf-12 124060 11014 ns/op 32768 B/op 1 allocs/op
BenchmarkWrite/bytes-12 101112 11767 ns/op 32768 B/op 1 allocs/op
BenchmarkWriteByte/flexbuf-12 38088462 31.2 ns/op 1 B/op 1 allocs/op
BenchmarkWriteByte/bytes-12 15355932 76.9 ns/op 64 B/op 1 allocs/op
BenchmarkWriteString/flexbuf-12 18013146 63.8 ns/op 16 B/op 1 allocs/op
BenchmarkWriteString/bytes-12 12852244 88.3 ns/op 64 B/op 1 allocs/op
BenchmarkReadFrom/flexbuf-12 27813 43573 ns/op 129024 B/op 7 allocs/op
BenchmarkReadFrom/bytes-12 27439 43440 ns/op 129024 B/op 7 allocs/op
License
BSD-2-Clause
Documentation
¶
Index ¶
- Variables
- func Append(buf *Buffer)
- func Offset(off int) func(*Buffer)
- type Buffer
- func (b *Buffer) Cap() int
- func (b *Buffer) Close() error
- func (b *Buffer) Grow(n int)
- func (b *Buffer) Len() int
- func (b *Buffer) Offset() int
- func (b *Buffer) Read(p []byte) (int, error)
- func (b *Buffer) ReadAt(p []byte, off int64) (int, error)
- func (b *Buffer) ReadByte() (byte, error)
- func (b *Buffer) ReadFrom(r io.Reader) (int64, error)
- func (b *Buffer) Release() []byte
- func (b *Buffer) Seek(offset int64, whence int) (int64, error)
- func (b *Buffer) SeekEnd() int64
- func (b *Buffer) SeekStart() int64
- func (b *Buffer) String() string
- func (b *Buffer) Truncate(size int64) error
- func (b *Buffer) Write(p []byte) (int, error)
- func (b *Buffer) WriteAt(p []byte, off int64) (int, error)
- func (b *Buffer) WriteByte(c byte) error
- func (b *Buffer) WriteString(s string) (int, error)
- func (b *Buffer) WriteTo(w io.Writer) (int64, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrOutOfBounds = errors.New("offset out of bounds")
ErrOutOfBounds is returned for invalid offsets.
Functions ¶
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
A Buffer is a variable-sized buffer of bytes. The zero value for Buffer is an empty buffer ready to use.
Example ¶
package main
import (
"fmt"
"io"
"github.com/rzajac/flexbuf"
)
func main() {
buf := &flexbuf.Buffer{}
_, _ = buf.Write([]byte{0, 1, 2, 3})
_, _ = buf.Seek(-2, io.SeekEnd)
_, _ = buf.Write([]byte{4, 5})
_, _ = buf.Seek(0, io.SeekStart)
data, _ := io.ReadAll(buf)
fmt.Println(data)
}
Output: [0 1 4 5]
func New ¶
New returns new instance of the Buffer. The difference between New and using zero value buffer is that New will initialize buffer with capacity of bytes.MinRead. It will panic with ErrOutOfBounds if option sets offset as negative number or greater then bytes.MinRead.
func With ¶
With creates new instance of Buffer initialized with data. 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. It will panic with ErrOutOfBounds if option sets offset as negative number or beyond buffer length.
func (*Buffer) Cap ¶
Cap returns the capacity of the buffer's underlying byte slice, that is, the total space allocated for the buffer's data.
func (*Buffer) Close ¶
Close sets offset to zero and zero put the buffer. It always returns nil error.
func (*Buffer) Grow ¶ added in v0.7.0
Grow grows the buffer's capacity, if necessary, to guarantee space for another n bytes. After Grow(n), at least n bytes can be written to the buffer without another allocation. If n is negative, Grow will panic. If the buffer can't grow it will panic with ErrTooLarge.
func (*Buffer) Read ¶
Read reads the next len(p) bytes from the buffer or until the buffer is drained. The return value is the number of bytes read. If the buffer has no data to return, err is io.EOF (unless len(p) is zero); otherwise it is nil.
func (*Buffer) ReadAt ¶
ReadAt reads len(p) bytes from the buffer starting at byte offset off. It returns the number of bytes read and the error, if any. ReadAt always returns a non-nil error when n < len(p). It does not change the offset.
func (*Buffer) ReadByte ¶ added in v0.3.0
ReadByte reads and returns the next byte from the buffer or any error encountered. If ReadByte returns an error, no input byte was consumed, and the returned byte value is undefined.
func (*Buffer) ReadFrom ¶
ReadFrom reads data from r until EOF and appends it to the buffer at b.off, growing the buffer as needed. The return value is the number of bytes read. Any error except io.EOF encountered during the read is also returned. If the buffer becomes too large, ReadFrom will panic with ErrTooLarge.
func (*Buffer) Release ¶ added in v0.11.0
Release releases ownership of the underlying buffer, the caller should not use the instance of Buffer after this call.
func (*Buffer) Seek ¶
Seek sets the offset for the next Read or Write on the buffer to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end. It returns the new offset and an error (only if calculated offset < 0).
func (*Buffer) SeekEnd ¶ added in v0.14.0
SeekEnd is a convenience method setting the buffer's offset to the buffer length and returning the value it had before the method was called.
func (*Buffer) SeekStart ¶ added in v0.6.0
SeekStart is a convenience method setting the buffer's offset to zero and returning the value it had before the method was called.
func (*Buffer) String ¶ added in v0.4.0
String returns string representation of the buffer starting at current offset. Calling this method is considered as reading the buffer and advances offset to the end of the buffer.
func (*Buffer) Truncate ¶
Truncate changes the size of the buffer discarding bytes at offsets greater then size. It does not change the offset unless Append option was used then it sets offset to the end of the buffer. It returns error os.ErrInvalid only when when size is negative.
func (*Buffer) Write ¶
Write writes the contents of p to the buffer at current offset, growing the buffer as needed. The return value n is the length of p; err is always nil.
func (*Buffer) WriteAt ¶
WriteAt writes len(p) bytes to the buffer starting at byte offset off. It returns the number of bytes written; err is always nil. It does not change the offset.
func (*Buffer) WriteString ¶ added in v0.4.0
WriteString writes string s to the buffer at the current offset.
Source Files