Documentation ¶
Index ¶
- Variables
- type AfterReadHandler
- type AfterWriteHandler
- type AnyComplex
- type AnyFloat
- type AnyInt
- type BeforeReadHandler
- type BeforeWriteHandler
- type EventHandler
- type FieldMapper
- type KeyMapper
- type Mapper
- func Any(read ReadFunc, write WriteFunc) Mapper
- func Bool(b *bool) Mapper
- func Byte(b *byte) Mapper
- func Complex[T AnyComplex](target *T) Mapper
- func DataTable(length *uint32, mappers ...FieldMapper) Mapper
- func DynamicSlice[E any](target *[]E, mapVal func(*E) Mapper) Mapper
- func FixedBytes[S SizeType](buf *[]byte, length S) Mapper
- func FixedString(s *string, length int) Mapper
- func Float[T AnyFloat](f *T) Mapper
- func Int[T AnyInt](i *T) Mapper
- func LenBytes[S SizeType](buf *[]byte, length *S) Mapper
- func LenSlice[E any, S SizeType](target *[]E, count *S, mapVal func(*E) Mapper) Mapper
- func Lock(mapper Mapper, mux *sync.Mutex) Mapper
- func Map[K comparable, V any](target *map[K]V, keyMapper KeyMapper[K], valMapper ValMapper[V]) Mapper
- func MapSequence(mappings ...Mapper) Mapper
- func NewEventHandler(mapper Mapper, handler EventHandler) Mapper
- func NormalizeWrite(mapper Mapper, normalizer BeforeWriteHandler) Mapper
- func NullTermString(s *string) Mapper
- func OnPanic(mapper Mapper, panicHandler func(any) error) Mapper
- func OverrideEndian(m Mapper, endian binary.ByteOrder) Mapper
- func RWLock(mapper Mapper, mux *sync.RWMutex) Mapper
- func Size[S SizeType](size *S) Mapper
- func Slice[E any, S SizeType](target *[]E, count S, mapVal func(*E) Mapper) Mapper
- func Uni16FixedString(s *string, wcharlen int) Mapper
- func Uni16NullTermString(s *string) Mapper
- func Uvarint(target *uint64) Mapper
- func ValidateRead(mapper Mapper, validator AfterReadHandler) Mapper
- func Varint(target *int64) Mapper
- type ReadFunc
- type SizeType
- type ValMapper
- type WriteFunc
Constants ¶
This section is empty.
Variables ¶
var ( ErrNilReadWrite = errors.New("nil read source or write target") ErrPanic = errors.New("panic during Read or Write") )
var (
ErrUnbalancedTable = errors.New("unbalanced data table")
)
Functions ¶
This section is empty.
Types ¶
type AfterReadHandler ¶ added in v0.4.0
type AfterWriteHandler ¶ added in v0.4.0
type AnyComplex ¶ added in v0.3.0
type AnyComplex interface { complex64 | complex128 }
type BeforeReadHandler ¶ added in v0.4.0
type BeforeReadHandler = func() error
type BeforeWriteHandler ¶ added in v0.4.0
type BeforeWriteHandler = func() error
type EventHandler ¶ added in v0.4.0
type EventHandler struct { BeforeRead BeforeReadHandler AfterRead AfterReadHandler BeforeWrite BeforeWriteHandler AfterWrite AfterWriteHandler // contains filtered or unexported fields }
type FieldMapper ¶ added in v0.3.0
type FieldMapper interface {
// contains filtered or unexported methods
}
FieldMapper provides the logic necessary to read and write DataTable fields. Created with MapField.
func MapField ¶ added in v0.3.0
func MapField[T any](target *[]T, mapFn func(*T) Mapper) FieldMapper
MapField will associate a Mapper to each element in a target slice within a FieldMapper.
type KeyMapper ¶ added in v0.3.0
type KeyMapper[K comparable] func(key *K) Mapper
type Mapper ¶
type Mapper interface { // Read data from a binary source. Read(r io.Reader, endian binary.ByteOrder) error // Write data to a binary target. Write(w io.Writer, endian binary.ByteOrder) error }
Mapper is any procedure that knows how to read from and write to binary data, given an endianness policy.
func Complex ¶ added in v0.3.0
func Complex[T AnyComplex](target *T) Mapper
Complex will map a complex64/128 number.
func DataTable ¶ added in v0.3.0
func DataTable(length *uint32, mappers ...FieldMapper) Mapper
DataTable will construct a Mapper that orchestrates reading and writing a data table. This is very helpful for situations where the caller is using the array of structs to struct of arrays optimization, and wants to persist this table. Each FieldMapper will be used to read a single field element, making up a DataTable row, before returning to the first FieldMapper to start the next row. The length parameter will set during read, and read during write to ensure that all mapped fields are of the same length.
func DynamicSlice ¶
DynamicSlice tries to accomplish a happy medium between LenSlice and Slice. A uint32 will be used to store the size of the given slice, but it's not necessary to read this from a field, rather it will be discovered at write time. This means that the size will be available at read time by first reading the uint32 with LenSlice, without requiring a caller provided field. In a scenario where a slice in a struct is used, this makes it easier to read and write because the struct doesn't need to store the size in a field.
func FixedBytes ¶
FixedBytes maps a byte slice of a known length.
func FixedString ¶
FixedString will map a string with a max length that is known ahead of time. The target string will not contain any trailing zero bytes if the encoded string is less than the space allowed.
func LenBytes ¶
LenBytes is used for situations where an arbitrarily sized byte slice is encoded after its length. This mapper will read the length, and then length number of bytes into a byte slice. The mapper will write the length and bytes in the same order.
func LenSlice ¶
LenSlice is for situations where a slice is encoded with its length prepended. Otherwise, this behaves exactly like Slice.
func Lock ¶ added in v0.4.0
Lock will manage locking and unlocking a sync.Mutex before/after a read/write.
func Map ¶ added in v0.3.0
func Map[K comparable, V any](target *map[K]V, keyMapper KeyMapper[K], valMapper ValMapper[V]) Mapper
func MapSequence ¶
MapSequence creates a Mapper that uses each given Mapper in order.
func NewEventHandler ¶ added in v0.4.0
func NewEventHandler(mapper Mapper, handler EventHandler) Mapper
func NormalizeWrite ¶ added in v0.4.0
func NormalizeWrite(mapper Mapper, normalizer BeforeWriteHandler) Mapper
NormalizeWrite will run the normalizer before writing with the mapper.
func NullTermString ¶
NullTermString will read and write null-byte terminated string. The string should not contain a null terminator, one will be added on write.
func OnPanic ¶ added in v0.4.0
OnPanic will recover a panic from a Read or Write operation, and return the error returned from panicHandler wrapped with ErrPanic. If no error is returned from panicHandler, then a plain ErrPanic error will be returned.
func OverrideEndian ¶ added in v0.3.0
OverrideEndian will override the endian settings for a single operation. This is useful for UTF-16 strings which are often read/written little-endian.
func RWLock ¶ added in v0.4.0
RWLock will manage locking and unlocking a sync.RWMutex before/after a read/write. Writing the mapper only requires read locking, while reading with the mapper requires write locking since state is being mutated.
func Slice ¶
Slice will produce a mapper informed from the given function to use a slice of values. The slice length must be known ahead of time. The mapVal function will be used to create a Mapper that relates to the type returned from allocNext. The returned Mapper will orchestrate the array construction according to the given function.
func Uni16FixedString ¶ added in v0.3.0
Uni16FixedString is the same as FixedString, except that it works with UTF-16 strings.
func Uni16NullTermString ¶ added in v0.3.0
Uni16NullTermString is the same as NullTermString, except that it works with UTF-16 strings.
func Uvarint ¶ added in v0.3.0
Uvarint encodes 16, 32, or 64-bit unsigned integers as a variable length integer. This is generally more efficient than reading/writing the full byte length.
func ValidateRead ¶ added in v0.4.0
func ValidateRead(mapper Mapper, validator AfterReadHandler) Mapper
ValidateRead will run the validator function after reading with the mapper.