Documentation ¶
Overview ¶
Package encoding converts arbitrary objects into byte slices, and vis versa. It also contains helper functions for reading and writing length- prefixed data. The encoding rules are as follows:
Objects are encoded as binary data, without type information. The receiver uses context to determine the type to decode into.
Integers are little-endian, and are always encoded as 8 bytes, i.e. their int64 or uint64 equivalent.
Booleans are encoded as one byte, either zero (false) or one (true). No other values may be used.
Nil pointers are equivalent to "false," i.e. a single zero byte. Valid pointers are represented by a "true" byte (0x01) followed by the encoding of the dereferenced value.
Variable-length types, such as strings and slices, are represented by an 8-byte length-prefix followed by the encoded value.
Slices and structs are simply the concatenation of their encoded elements. Byte slices are not subject to the 8-byte integer rule; they are encoded as their literal representation, one byte per byte.
The ordering of struct fields is determined by their type definition. For example:
type foo struct { S string; I int } Marshal(foo{"bar", 3}) == append(Marshal("bar"), Marshal(3)...)
Finally, if a type implements the SiaMarshaler interface, its MarshalSia method will be used to encode the type. The resulting byte slice will be length-prefixed like any other variable-length type. During decoding, the type is decoded as a byte slice, and then passed to UnmarshalSia.
Index ¶
- Variables
- func DecInt64(b []byte) int64
- func DecUint64(b []byte) uint64
- func EncInt64(i int64) (b []byte)
- func EncUint64(i uint64) (b []byte)
- func Marshal(v interface{}) []byte
- func MarshalAll(v ...interface{}) []byte
- func ReadFile(filename string, v interface{}) error
- func ReadObject(r io.Reader, obj interface{}, maxLen uint64) error
- func ReadPrefix(r io.Reader, maxLen uint64) ([]byte, error)
- func Unmarshal(b []byte, v interface{}) error
- func WriteFile(filename string, v interface{}) error
- func WriteObject(w io.Writer, v interface{}) error
- func WritePrefix(w io.Writer, data []byte) error
- type Decoder
- type Encoder
- type ReadWriter
- type Reader
- type SiaMarshaler
- type SiaUnmarshaler
- type Writer
Constants ¶
This section is empty.
Variables ¶
var (
ErrNoData = errors.New("no data")
)
Functions ¶
func DecInt64 ¶
DecInt64 decodes a slice of 8 bytes into an int64. If len(b) < 8, the slice is padded with zeros.
func DecUint64 ¶
DecUint64 decodes a slice of 8 bytes into a uint64. If len(b) < 8, the slice is padded with zeros.
func Marshal ¶
func Marshal(v interface{}) []byte
Marshal returns the encoding of v. For encoding details, see the package docstring.
func MarshalAll ¶
func MarshalAll(v ...interface{}) []byte
MarshalAll encodes all of its inputs and returns their concatenation.
func ReadObject ¶
ReadObject reads and decodes a length-prefixed and marshalled object.
func ReadPrefix ¶
ReadPrefix reads an 8-byte length prefixes, followed by the number of bytes specified in the prefix. The operation is aborted if the prefix exceeds a specified maximum length.
func Unmarshal ¶
Unmarshal decodes the encoded value b and stores it in v, which must be a pointer. The decoding rules are the inverse of those specified in the package docstring.
func WriteFile ¶ added in v0.3.1
WriteFile writes v to a file. The file will be created if it does not exist.
func WriteObject ¶
WriteObject writes a length-prefixed object to w.
Types ¶
type Decoder ¶ added in v0.3.1
type Decoder struct {
// contains filtered or unexported fields
}
A Decoder reads and decodes values from an input stream.
func NewDecoder ¶ added in v0.3.1
NewDecoder returns a new decoder that reads from r.
type Encoder ¶ added in v0.3.1
type Encoder struct {
// contains filtered or unexported fields
}
An Encoder writes objects to an output stream.
func NewEncoder ¶ added in v0.3.1
NewEncoder returns a new encoder that writes to w.
type ReadWriter ¶ added in v0.3.0
A ReadWriter can both read and write objects.
type Reader ¶ added in v0.3.0
A Reader can decode an object from its input. maxLen specifies the maximum length of the object being decoded.
type SiaMarshaler ¶
type SiaMarshaler interface {
MarshalSia() []byte
}
A SiaMarshaler can encode itself as a byte slice.
type SiaUnmarshaler ¶
type SiaUnmarshaler interface {
UnmarshalSia([]byte)
}
A SiaUnmarshaler can decode itself from a byte slice. If a decoding error occurs, UnmarshalSia should panic.