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. See doc/Encoding.md for the full encoding specification.

Index

• Constants
• 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(vs ...interface{}) []byte
• func ReadFile(filename string, v interface{}) error
• func ReadObject(r io.Reader, obj interface{}, maxLen uint64) error
• func ReadPrefixedBytes(r io.Reader, maxLen uint64) ([]byte, error)
• func Unmarshal(b []byte, v interface{}) error
• func UnmarshalAll(b []byte, vs ...interface{}) error
• func WriteFile(filename string, v interface{}) error
• func WriteInt(w io.Writer, i int) error
• func WriteObject(w io.Writer, v interface{}) error
• func WritePrefixedBytes(w io.Writer, data []byte) error
• func WriteUint64(w io.Writer, u uint64) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) (err error)
  • func (d *Decoder) DecodeAll(vs ...interface{}) error
  • func (d *Decoder) Err() error
  • func (d *Decoder) NextBool() bool
  • func (d *Decoder) NextPrefix(elemSize uintptr) uint64
  • func (d *Decoder) NextUint64() uint64
  • func (d *Decoder) Read(p []byte) (int, error)
  • func (d *Decoder) ReadFull(p []byte)
  • func (d *Decoder) ReadPrefixedBytes() []byte
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}) error
  • func (e *Encoder) EncodeAll(vs ...interface{}) error
  • func (e *Encoder) Err() error
  • func (e *Encoder) Write(p []byte) (int, error)
  • func (e *Encoder) WriteBool(b bool) error
  • func (e *Encoder) WriteByte(b byte) error
  • func (e *Encoder) WriteInt(i int) error
  • func (e *Encoder) WritePrefixedBytes(p []byte) error
  • func (e *Encoder) WriteUint64(u uint64) error
• type ErrObjectTooLarge
  • func (e ErrObjectTooLarge) Error() string
• type ErrSliceTooLarge
  • func (e ErrSliceTooLarge) Error() string
• type SiaMarshaler
• type SiaUnmarshaler

Constants

const (
	// MaxObjectSize refers to the maximum size an object could have.
	// Limited to 12 MB.
	MaxObjectSize = 12e6

	// MaxSliceSize refers to the maximum size slice could have. Limited
	// to 5 MB.
	MaxSliceSize = 5e6 // 5 MB
)

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.

func MarshalAll

func MarshalAll(vs ...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 ReadPrefixedBytes

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

ReadPrefixedBytes 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 for marshaling.

func UnmarshalAll

func UnmarshalAll(b []byte, vs ...interface{}) error

UnmarshalAll decodes the encoded values in b and stores them in vs, which must be pointers.

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 WriteInt

func WriteInt(w io.Writer, i int) error

WriteInt writes i to w.

func WriteObject

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

WriteObject writes a length-prefixed object to w.

func WritePrefixedBytes

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

WritePrefixedBytes writes a length-prefixed byte slice to w.

func WriteUint64

func WriteUint64(w io.Writer, u uint64) error

WriteUint64 writes u to w.

Types

type Decoder

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

A Decoder reads and decodes values from an input stream. It also provides helper methods for writing custom SiaUnmarshaler implementations. These methods do not return errors, but instead set the value of d.Err(). Once d.Err() is set, future operations become no-ops.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder converts r to a Decoder.

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.

func (*Decoder) DecodeAll

func (d *Decoder) DecodeAll(vs ...interface{}) error

DecodeAll decodes a variable number of arguments.

func (*Decoder) Err

func (d *Decoder) Err() error

Err returns the first non-nil error encountered by d.

func (*Decoder) NextBool

func (d *Decoder) NextBool() bool

NextBool reads the next byte and returns it as a bool.

func (*Decoder) NextPrefix

func (d *Decoder) NextPrefix(elemSize uintptr) uint64

NextPrefix is like NextUint64, but performs sanity checks on the prefix. Specifically, if the prefix multiplied by elemSize exceeds MaxSliceSize, NextPrefix returns 0 and sets d.Err().

func (*Decoder) NextUint64

func (d *Decoder) NextUint64() uint64

NextUint64 reads the next 8 bytes and returns them as a uint64.

func (*Decoder) Read

func (d *Decoder) Read(p []byte) (int, error)

Read implements the io.Reader interface.

func (*Decoder) ReadFull

func (d *Decoder) ReadFull(p []byte)

ReadFull is shorthand for io.ReadFull(d, p).

func (*Decoder) ReadPrefixedBytes

func (d *Decoder) ReadPrefixedBytes() []byte

ReadPrefixedBytes reads a length-prefix, allocates a byte slice with that length, reads into the byte slice, and returns it. If the length prefix exceeds encoding.MaxSliceSize, ReadPrefixedBytes returns nil and sets d.Err().

type Encoder

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

An Encoder writes objects to an output stream. It also provides helper methods for writing custom SiaMarshaler implementations. All of its methods become no-ops after the Encoder encounters a Write error.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder converts w to an Encoder.

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.

func (*Encoder) EncodeAll

func (e *Encoder) EncodeAll(vs ...interface{}) error

EncodeAll encodes a variable number of arguments.

func (*Encoder) Err

func (e *Encoder) Err() error

Err returns the first non-nil error encountered by e.

func (*Encoder) Write

func (e *Encoder) Write(p []byte) (int, error)

Write implements the io.Writer interface.

func (*Encoder) WriteBool

func (e *Encoder) WriteBool(b bool) error

WriteBool writes b to the underlying io.Writer.

func (*Encoder) WriteByte

func (e *Encoder) WriteByte(b byte) error

WriteByte implements the io.ByteWriter interface.

func (*Encoder) WriteInt

func (e *Encoder) WriteInt(i int) error

WriteInt writes an int value to the underlying io.Writer.

func (*Encoder) WritePrefixedBytes

func (e *Encoder) WritePrefixedBytes(p []byte) error

WritePrefixedBytes writes p to the underlying io.Writer, prefixed by its length.

func (*Encoder) WriteUint64

func (e *Encoder) WriteUint64(u uint64) error

WriteUint64 writes a uint64 value to the underlying io.Writer.

type ErrObjectTooLarge

type ErrObjectTooLarge uint64

ErrObjectTooLarge is an error when encoded object exceeds size limit.

func (ErrObjectTooLarge) Error

func (e ErrObjectTooLarge) Error() string

Error implements the error interface.

type ErrSliceTooLarge

type ErrSliceTooLarge struct {
	Len      uint64
	ElemSize uint64
}

ErrSliceTooLarge is an error when encoded slice is too large.

func (ErrSliceTooLarge) Error

func (e ErrSliceTooLarge) Error() string

Error implements the error interface.

type SiaMarshaler

type SiaMarshaler interface {
	MarshalSia(io.Writer) error
}

A SiaMarshaler can encode and write itself to a stream.

type SiaUnmarshaler

type SiaUnmarshaler interface {
	UnmarshalSia(io.Reader) error
}

A SiaUnmarshaler can read and decode itself from a stream.