encoding

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

• 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
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) (err error)
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}) error
• type SiaMarshaler
• type SiaUnmarshaler

Functions

func DecInt64

func DecInt64(b []byte) int64

DecInt64 decodes a slice of 8 bytes into an int64. If len(b) < 8, the slice is padded with zeros.

func DecUint64

func DecUint64(b []byte) uint64

DecUint64 decodes a slice of 8 bytes into a uint64. If len(b) < 8, the slice is padded with zeros.

func EncInt64

func EncInt64(i int64) (b []byte)

EncInt64 encodes an int64 as a slice of 8 bytes.

func EncUint64

func EncUint64(i uint64) (b []byte)

EncUint64 encodes a uint64 as a slice of 8 bytes.

func Marshal

func Marshal(v interface{}) []byte

Marshal returns the encoding of v. For encoding details, see the package docstring. TODO: merge with MarshalAll?

func MarshalAll

func MarshalAll(v ...interface{}) []byte

MarshalAll encodes all of its inputs and returns their concatenation.

func ReadFile

func ReadFile(filename string, v interface{}) error

ReadFile reads the contents of a file and decodes them into v.

func ReadObject

func ReadObject(r io.Reader, obj interface{}, maxLen uint64) error

ReadObject reads and decodes a length-prefixed and marshalled object.

func ReadPrefix

func ReadPrefix(r io.Reader, maxLen uint64) ([]byte, error)

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

func Unmarshal(b []byte, v interface{}) error

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

func WriteFile(filename string, v interface{}) error

WriteFile writes v to a file. The file will be created if it does not exist.

func WriteObject

func WriteObject(w io.Writer, v interface{}) error

WriteObject writes a length-prefixed object to w.

func WritePrefix

func WritePrefix(w io.Writer, data []byte) error

WritePrefix writes a length-prefixed byte slice to w.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads and decodes values from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) (err error)

Decode reads the next encoded value from its input stream and stores it in v, which must be a pointer. The decoding rules are the inverse of those specified in the package docstring.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder writes objects to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode

func (e *Encoder) Encode(v interface{}) error

Encode writes the encoding of v to the stream. For encoding details, see the package docstring.

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.