Skip to content

Commit

Permalink
README: re-generate, some manual fixes, add doc reference badge
Browse files Browse the repository at this point in the history 
The godoc2md tool has been deprecated, and is no longer maintained; it
has some bugs which prevent it from generating correct links (so I removed
those).

Added a badge to the documentation on pkg.go.dev, which perhaps should be
used as replacement for the docs in the README itself.

Signed-off-by: Sebastiaan van Stijn <[email protected]>
  • Loading branch information
@thaJeztah @philhofer
thaJeztah authored and philhofer committed Dec 11, 2022
1 parent 7706de0 commit ead0d75
Showing 1 changed file with 82 additions and 38 deletions.
120 changes: 82 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,25 @@

# fwd
import "github.com/philhofer/fwd"

The `fwd` package provides a buffered reader
[![Go Reference](https://pkg.go.dev/badge/github.com/philhofer/fwd.svg)](https://pkg.go.dev/github.com/philhofer/fwd)


`import "github.com/philhofer/fwd"`

* [Overview](#pkg-overview)
* [Index](#pkg-index)

## <a name="pkg-overview">Overview</a>
Package fwd provides a buffered reader
and writer. Each has methods that help improve
the encoding/decoding performance of some binary
protocols.

The `fwd.Writer` and `fwd.Reader` type provide similar
The `Writer` and `Reader` type provide similar
functionality to their counterparts in `bufio`, plus
a few extra utility methods that simplify read-ahead
and write-ahead. I wrote this package to improve serialization
performance for <a href="http://github.com/tinylib/msgp">http://github.com/tinylib/msgp</a>,
performance for [github.com/tinylib/msgp](https://github.com/tinylib/msgp),
where it provided about a 2x speedup over `bufio` for certain
workloads. However, care must be taken to understand the semantics of the
extra methods provided by this package, as they allow
Expand Down Expand Up @@ -39,7 +47,37 @@ to write directly to the end of the buffer.



## Constants
## <a name="pkg-index">Index</a>
* [Constants](#pkg-constants)
* [type Reader](#Reader)
* [func NewReader(r io.Reader) *Reader](#NewReader)
* [func NewReaderBuf(r io.Reader, buf []byte) *Reader](#NewReaderBuf)
* [func NewReaderSize(r io.Reader, n int) *Reader](#NewReaderSize)
* [func (r *Reader) BufferSize() int](#Reader.BufferSize)
* [func (r *Reader) Buffered() int](#Reader.Buffered)
* [func (r *Reader) Next(n int) ([]byte, error)](#Reader.Next)
* [func (r *Reader) Peek(n int) ([]byte, error)](#Reader.Peek)
* [func (r *Reader) Read(b []byte) (int, error)](#Reader.Read)
* [func (r *Reader) ReadByte() (byte, error)](#Reader.ReadByte)
* [func (r *Reader) ReadFull(b []byte) (int, error)](#Reader.ReadFull)
* [func (r *Reader) Reset(rd io.Reader)](#Reader.Reset)
* [func (r *Reader) Skip(n int) (int, error)](#Reader.Skip)
* [func (r *Reader) WriteTo(w io.Writer) (int64, error)](#Reader.WriteTo)
* [type Writer](#Writer)
* [func NewWriter(w io.Writer) *Writer](#NewWriter)
* [func NewWriterBuf(w io.Writer, buf []byte) *Writer](#NewWriterBuf)
* [func NewWriterSize(w io.Writer, n int) *Writer](#NewWriterSize)
* [func (w *Writer) BufferSize() int](#Writer.BufferSize)
* [func (w *Writer) Buffered() int](#Writer.Buffered)
* [func (w *Writer) Flush() error](#Writer.Flush)
* [func (w *Writer) Next(n int) ([]byte, error)](#Writer.Next)
* [func (w *Writer) ReadFrom(r io.Reader) (int64, error)](#Writer.ReadFrom)
* [func (w *Writer) Write(p []byte) (int, error)](#Writer.Write)
* [func (w *Writer) WriteByte(b byte) error](#Writer.WriteByte)
* [func (w *Writer) WriteString(s string) (int, error)](#Writer.WriteString)


## <a name="pkg-constants">Constants</a>
``` go
const (
// DefaultReaderSize is the default size of the read buffer
Expand Down Expand Up @@ -121,7 +159,7 @@ and the reader position will not be incremented.



### func (\*Reader) Peek
### <a name="Reader.Peek">func</a> (\*Reader) Peek
``` go
func (r *Reader) Peek(n int) ([]byte, error)
```
Expand All @@ -134,23 +172,23 @@ io.ErrUnexpectedEOF.



### func (\*Reader) Read
### <a name="Reader.Read">func</a> (\*Reader) Read
``` go
func (r *Reader) Read(b []byte) (int, error)
```
Read implements `io.Reader`
Read implements `io.Reader`.



### func (\*Reader) ReadByte
### <a name="Reader.ReadByte">func</a> (\*Reader) ReadByte
``` go
func (r *Reader) ReadByte() (byte, error)
```
ReadByte implements `io.ByteReader`
ReadByte implements `io.ByteReader`.



### func (\*Reader) ReadFull
### <a name="Reader.ReadFull">func</a> (\*Reader) ReadFull
``` go
func (r *Reader) ReadFull(b []byte) (int, error)
```
Expand All @@ -161,7 +199,7 @@ EOF is considered an unexpected error.



### func (\*Reader) Reset
### <a name="Reader.Reset">func</a> (\*Reader) Reset
``` go
func (r *Reader) Reset(rd io.Reader)
```
Expand All @@ -170,7 +208,7 @@ and the read buffer.



### func (\*Reader) Skip
### <a name="Reader.Skip">func</a> (\*Reader) Skip
``` go
func (r *Reader) Skip(n int) (int, error)
```
Expand All @@ -182,27 +220,30 @@ that method will be used to skip forward.

If the reader encounters
an EOF before skipping 'n' bytes, it
returns io.ErrUnexpectedEOF. If the
underlying reader implements io.Seeker, then
returns `io.ErrUnexpectedEOF`. If the
underlying reader implements `io.Seeker`, then
those rules apply instead. (Many implementations
will not return `io.EOF` until the next call
to Read.)
to Read).



### func (\*Reader) WriteTo

### <a name="Reader.WriteTo">func</a> (\*Reader) WriteTo
``` go
func (r *Reader) WriteTo(w io.Writer) (int64, error)
```
WriteTo implements `io.WriterTo`
WriteTo implements `io.WriterTo`.




## type Writer
## <a name="Writer">type</a> Writer
``` go
type Writer struct {
// contains filtered or unexported fields
}

```
Writer is a buffered writer

Expand All @@ -212,9 +253,7 @@ Writer is a buffered writer





### func NewWriter
### <a name="NewWriter">func</a> NewWriter
``` go
func NewWriter(w io.Writer) *Writer
```
Expand All @@ -223,26 +262,32 @@ that writes to 'w' and has a buffer
that is `DefaultWriterSize` bytes.


### func NewWriterSize
### <a name="NewWriterBuf">func</a> NewWriterBuf
``` go
func NewWriterSize(w io.Writer, size int) *Writer
func NewWriterBuf(w io.Writer, buf []byte) *Writer
```
NewWriterSize returns a new writer
that writes to 'w' and has a buffer
that is 'size' bytes.

NewWriterBuf returns a new writer
that writes to 'w' and has 'buf' as a buffer.
'buf' is not used when has smaller capacity than 18,
custom buffer is allocated instead.


### <a name="NewWriterSize">func</a> NewWriterSize
``` go
func NewWriterSize(w io.Writer, n int) *Writer
```
NewWriterSize returns a new writer that
writes to 'w' and has a buffer size 'n'.

### func (\*Writer) BufferSize
### <a name="Writer.BufferSize">func</a> (\*Writer) BufferSize
``` go
func (w *Writer) BufferSize() int
```
BufferSize returns the maximum size of the buffer.



### func (\*Writer) Buffered
### <a name="Writer.Buffered">func</a> (\*Writer) Buffered
``` go
func (w *Writer) Buffered() int
```
Expand All @@ -251,7 +296,7 @@ in the reader.



### func (\*Writer) Flush
### <a name="Writer.Flush">func</a> (\*Writer) Flush
``` go
func (w *Writer) Flush() error
```
Expand All @@ -260,7 +305,7 @@ to the underlying writer.



### func (\*Writer) Next
### <a name="Writer.Next">func</a> (\*Writer) Next
``` go
func (w *Writer) Next(n int) ([]byte, error)
```
Expand All @@ -273,31 +318,31 @@ the size of the returned buffer.



### func (\*Writer) ReadFrom
### <a name="Writer.ReadFrom">func</a> (\*Writer) ReadFrom
``` go
func (w *Writer) ReadFrom(r io.Reader) (int64, error)
```
ReadFrom implements `io.ReaderFrom`



### func (\*Writer) Write
### <a name="Writer.Write">func</a> (\*Writer) Write
``` go
func (w *Writer) Write(p []byte) (int, error)
```
Write implements `io.Writer`



### func (\*Writer) WriteByte
### <a name="Writer.WriteByte">func</a> (\*Writer) WriteByte
``` go
func (w *Writer) WriteByte(b byte) error
```
WriteByte implements `io.ByteWriter`



### func (\*Writer) WriteString
### <a name="Writer.WriteString">func</a> (\*Writer) WriteString
``` go
func (w *Writer) WriteString(s string) (int, error)
```
Expand All @@ -310,6 +355,5 @@ WriteString is analogous to Write, but it takes a string.




- - -
Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)
Generated by [godoc2md](https://github.com/davecheney/godoc2md)

0 comments on commit ead0d75

Please sign in to comment.