Documentation
¶
Overview ¶
Package encodable provides low-level methods for seralising golang data structures. It aims to be fast, modular and comprehensive, valuing runtime speed over creation overhead.
Encodable is an encoder/decoder for a specific type.
The pointers passed to Encode and Decode *must* be pointers to an allocated instance of the Encodable's type, accessible by Type(). If not, expect arbritrary memory addresses to be modified, and unhelpful runtime errors. Reference types will point themselves to newly allocated types, but the reference type itself must be allocated beforehand.
Encodables typically contain static buffers, used by calls to Encode and Decode. Concurrent usage will certainly fail. If a concurrent-safe Encodable is needed, NewConcurrent is a drop-in, concurrent safe replacement.
NewEncodable creates an Encodable for a type. It takes a *Config, which is used to configure the Encodable.
Type is an encoder/decoder for type information; an encoder for reflect.Type. The primary implementation, RegisterType
Index ¶
- Variables
- func Name(t reflect.Type) string
- type Array
- type BinaryMarshaler
- type Bool
- type Complex128
- type Complex64
- type Concurrent
- type Config
- type Encodable
- type Float32
- type Float64
- type Int
- type Int16
- type Int32
- type Int64
- type Int8
- type Interface
- type Map
- type Memory
- type Pointer
- type RegisterResolver
- type Resolver
- type Slice
- type Source
- type String
- type Struct
- type Uint
- type Uint16
- type Uint32
- type Uint64
- type Uint8
- type Uintptr
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAlreadyRegistered is returned if a type is already registered. ErrAlreadyRegistered = errors.New("already registered") // ErrNotRegistered is returned if a type has not been registered. ErrNotRegistered = errors.New("not registered") )
Functions ¶
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
Array is an Encodable for arrays
type BinaryMarshaler ¶
type BinaryMarshaler struct {
// contains filtered or unexported fields
}
BinaryMarshaler is an Encodable for types which implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler.
func NewBinaryMarshaler ¶
func NewBinaryMarshaler(t reflect.Type) *BinaryMarshaler
NewBinaryMarshaler returns a new BinaryMarshaler Encodable. It can internally handle a reference; i.e. time.Time's unmarshal function requires a reference, but both A type of time.Time and *time.Time will function here, as long as ptr in Encode() and Decode() is *time.Time or **time.Time respectively.
func (*BinaryMarshaler) String ¶
func (e *BinaryMarshaler) String() string
String implements Encodable
func (*BinaryMarshaler) Type ¶
func (e *BinaryMarshaler) Type() reflect.Type
Type implements Encodable
type Bool ¶
type Bool struct {
// contains filtered or unexported fields
}
Bool is an Encodable for bools
type Complex128 ¶
type Complex128 struct {
// contains filtered or unexported fields
}
Complex128 is an Encodable for complex128s
func NewComplex128 ¶
func NewComplex128() *Complex128
NewComplex128 returns a new complex128 Encodable
type Complex64 ¶
type Complex64 struct {
// contains filtered or unexported fields
}
Complex64 is an Encodable for complex64s
type Concurrent ¶
type Concurrent struct {
// contains filtered or unexported fields
}
Concurrent is a thread safe encodable. It functions as a drop in replacement for Encodables, keeping a cache of Encodables, only allowing a single call at a time on any one Encodable. If all cached Encodables are busy in a call, it creates a new Encodable, and calls it; It never blocks.
func NewConcurrent ¶
func NewConcurrent(new func() Encodable) *Concurrent
NewConcurrent wraps an Encodable with Concurrent, implementing Encodable with thread safety.
type Config ¶
type Config struct {
// Resolver is used by, and must be non-nil for, types which require type-resolution at Encode-Decode time.
// That is, types which can reference new or unknown types (read: interface types).
// This could conceivably differ from Encoder and Decoder, as long as the decoding Resolver can decode the encoding Resolvers output.
// Feel free to experiment.
Resolver Resolver
// IncludeUnexported will include unexported struct fields in the encoded data.
IncludeUnexported bool
// If StructTag is set, only struct fields with the given tag will be encoded
StructTag string
}
Config contains settings and information for the generation of a new Encodable. Some Encodables do nothing with Config, and some require information from it.
Config *must* be the same for Encoder and Decoder.
type Encodable ¶
type Encodable interface {
// Type returns the type that the Encodable encodes.
// ptr in Encode() and Decode() *must* be a pointer to an object of this type.
// It is thread safe.
Type() reflect.Type
// Encode writes the encoded form of the object at ptr to w.
Encode(ptr unsafe.Pointer, w io.Writer) error
// Decode reads the encoded form from r into the object at ptr.
// Decodes will only read what Encode wrote.
Decode(ptr unsafe.Pointer, r io.Reader) error
// Size returns the maximum encoded size of the Encodable.
// If Size returns <0, size is undefined.
// It is thread safe.
Size() int
// String returns a string showing the Encodable's structure.
// () shows a little information about the encoder, such as the type it encodes or relavent settings.
// {} denotes sub-Encoders; encoders that encode parts of a larger Encodable.
// Comparing results from String is an effecive way of equality checking.
// It is thread safe.
fmt.Stringer // String() string
}
Encodable is an Encoder/Decoder for a specific type.
Encoders are not assumed to be thread safe. Encode() and Decode() often share static buffers for the sake of performance, but this comes at the cost of thread safety. Concurrent calls to either Encode() or Decode() will almost certainly result in complete failure. Use NewConcurrent if concurrency is needed.
Encodables should return two kinds of error. encio.IOError and encio.Error for io and corrupted data errors, and Error for encoding errors. See encs/encio
func New ¶
New returns a new Encodable for encoding the type t. config contains settings and information for the generation of the Encodable. In many cases, it can be nil for sane defaults, however some Enodable types require information from the config.
func NewInterface ¶
NewInterface returns a new interface Encodable
type Float32 ¶
type Float32 struct {
// contains filtered or unexported fields
}
Float32 is an Encodable for float32s
type Float64 ¶
type Float64 struct {
// contains filtered or unexported fields
}
Float64 is an Encodable for float64s
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int is an Encodable for intss
type Int16 ¶
type Int16 struct {
// contains filtered or unexported fields
}
Int16 is an Encodable for int16s
type Int32 ¶
type Int32 struct {
// contains filtered or unexported fields
}
Int32 is an Encodable for int32s
type Int64 ¶
type Int64 struct {
// contains filtered or unexported fields
}
Int64 is an Encodable for int64s
type Int8 ¶
type Int8 struct {
// contains filtered or unexported fields
}
Int8 is an Encodable for int8s
type Interface ¶
type Interface struct {
// contains filtered or unexported fields
}
Interface is an Encodable for interfaces
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is an Encodable for maps
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory is an encoder that throws type-safety out the window (as if the rest of this library wasn't enough). Initialised with NewMemory(size), it reads/writes directly to the memory at the given address with no internal buffering. Extreme care must be taken, errors from Memory can be difficult to read, let alone helpful in debugging, and are often in the form of panics, or worse still, the silent destruction of the universe.
type Pointer ¶
type Pointer struct {
// contains filtered or unexported fields
}
Pointer encodes pointers to concrete types.
type RegisterResolver ¶
type RegisterResolver struct {
// contains filtered or unexported fields
}
RegisterResolver is a registration-based TypeResolver. All types to be encoded and decoded must be registered with Register(), with the exception of int*, uint*, float*, complex*, string, bool, time.Time, and time.Duration, which are pre-registered. It is thread safe.
func NewRegisterResolver ¶
func NewRegisterResolver(hasher hash.Hash64) *RegisterResolver
NewRegisterResolver returns a new RegisterResolver TypeResolver
func (*RegisterResolver) Register ¶
func (rr *RegisterResolver) Register(T interface{}) error
Register registers T, &T, []T, and *T if T is a pointer.
type Resolver ¶
type Resolver interface {
// Encode encodes the type t, writing to w.
Encode(t reflect.Type, w io.Writer) error
// Decode reads an encoded type, returning it.
// Decode must only read the same number of bytes written by Encode().
//
// In the case of decoding into interfaces, it might be expected that the received type is the same as the existing type in the interface.
// in this case, it might be sufficent to simply check if the types are equal, relying on the expected type as an existing reflect.Type instance.
// In this case, bool or (bool, error) would be sufficent return values.
//
// Other implementations might attempt to completely resolve a reflect.Type value from encoded data,
// in which case expected is an uneccecary argument.
//
// In the case of registration-based Resolvers, if the interface contains the type that's being sent,
// it can be fortuitus to register the expected type, as it might not have been registered before.
//
// I belive this function format is a good happy medium to allow for these different implementations,
// however, Resolvers should always be certain that the type returned from decode is either the same as what was given to Encode, or nil.
// Incorrect types will cause panics, or worse, incorrect memory manipulation.
Decode(expected reflect.Type, r io.Reader) (reflect.Type, error)
// Size returns the number of bytes the Resolver will read and write to the buffer.
// It can write less, but never more. If length is undefined, Size should return a negative.
Size() int
}
Resolver is a method for encoding types.
type Slice ¶
type Slice struct {
// contains filtered or unexported fields
}
Slice is an Encodable for slices
func (*Slice) Decode ¶
Decode implemenets Encodable. Encoded 0-len and nil slices both have the effect of setting the decoded slice's len and cap to 0. nil-ness of the slice being decoded into is retained.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is a cache of Encodables. Encodables are only created once, with subsequent calls to GetEncodable returning the previously created encodable.
type String ¶
type String struct {
// contains filtered or unexported fields
}
String is an Encodable for strings
type Struct ¶
type Struct struct {
// contains filtered or unexported fields
}
Struct is an Encodable for structs
type Uint ¶
type Uint struct {
// contains filtered or unexported fields
}
Uint is an Encodable for uints
type Uint16 ¶
type Uint16 struct {
// contains filtered or unexported fields
}
Uint16 is an Encodable for uint16s
type Uint32 ¶
type Uint32 struct {
// contains filtered or unexported fields
}
Uint32 is an Encodable for uint32s
type Uint64 ¶
type Uint64 struct {
// contains filtered or unexported fields
}
Uint64 is an Encodable for uint64s
type Uint8 ¶
type Uint8 struct {
// contains filtered or unexported fields
}
Uint8 is an Encodable for uint8s
Source Files