Documentation

Overview

Package codec implements the general-purpose part of an encoder for Go values. It relies on code generation rather than reflection so it is significantly faster than reflection-based encoders like gob. It also preserves sharing among struct pointers (but not other forms of sharing, like other pointer types or sub-slices). These features are sufficient for encoding the structures of the go/ast package, which is its sole purpose.

Encoding Scheme

Every encoded value begins with a single byte that describes what (if anything) follows. There is enough information to skip over the value, since the decoder must be able to do that if it encounters a struct field it doesn't know.

Most of the values of that initial byte can be devoted to small unsigned integers. For example, the number 17 is represented by the single byte 17. Only a few byte values have special meaning.

The nil code indicates that the value is nil. We don't absolutely need this: we could always represent the nil value for a type as something that couldn't be mistaken for an encoded value of that type. For instance, we could use 0 for nil in the case of slices (which always begin with the nValues code), and for pointers to numbers like *int, we could use something like "nBytes 0". But it is simpler to have a reserved value for nil.

The nBytes code indicates that an unsigned integer N is encoded next, followed by N bytes of data. This is used to represent strings and byte slices, as well numbers bigger than can fit into the initial byte. For example, the string "hi" is represented as:

nBytes 2 'h' 'i'

Unsigned integers that can't fit into the initial byte are encoded as byte sequences of length 4 or 8, holding little-endian uint32 or uint64 values. We use uint32s where possible to save space. We could have saved more space by also considering 16-byte numbers, or using a variable-length encoding like varints or gob's representation, but it didn't seem worth the additional complexity.

The nValues code is for sequences of values whose size is known beforehand, like a Go slice or array. The slice []string{"hi", "bye"} is encoded as

nValues 2 nBytes 2 'h' 'i' nBytes 3 'b' 'y' 'e'

The ref code is used to refer to an earlier encoded value. It is followed by a uint denoting the index data of the value to use.

The start and end codes delimit a value whose length is unknown beforehand. It is used for structs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateFile

func GenerateFile(filename, packageName string, values ...interface{}) error

    GenerateFile writes encoders and decoders to filename. It generates code for the type of each given value, as well as any types they depend on. packageName is the name following the file's package declaration.

    func Register

    func Register(x interface{}, enc encodeFunc, dec decodeFunc)

      Register records the type of x for use by Encoders and Decoders.

      Types

      type Decoder

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

        A Decoder decodes a Go value encoded by an Encoder. To use a Decoder: - Pass NewDecoder the return value of Encoder.Bytes. - Call the Decode method once for each call to Encoder.Encode.

        func NewDecoder

        func NewDecoder(data []byte) *Decoder

          NewDecoder returns a Decoder for the given bytes.

          func (*Decoder) Decode

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

            Decode decodes a value encoded with Encoder.Encode.

            func (*Decoder) DecodeAny

            func (d *Decoder) DecodeAny() interface{}

              DecodeAny decodes a value encoded by EncodeAny.

              func (*Decoder) DecodeBool

              func (d *Decoder) DecodeBool() bool

                DecodeBool decodes a bool.

                func (*Decoder) DecodeBytes

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

                  DecodeBytes decodes a byte slice. It does no copying.

                  func (*Decoder) DecodeFloat

                  func (d *Decoder) DecodeFloat() float64

                    DecodeFloat decodes a float64.

                    func (*Decoder) DecodeInt

                    func (d *Decoder) DecodeInt() int64

                      DecodeInt decodes a signed integer.

                      func (*Decoder) DecodeString

                      func (d *Decoder) DecodeString() string

                        DecodeString decodes a string.

                        func (*Decoder) DecodeUint

                        func (d *Decoder) DecodeUint() uint64

                          DecodeUint decodes a uint64.

                          func (*Decoder) NextStructField

                          func (d *Decoder) NextStructField() int

                            NextStructField should be called by a struct decoder in a loop. It returns the field number of the next encoded field, or -1 if there are no more fields.

                            func (*Decoder) StartList

                            func (d *Decoder) StartList() int

                              StartList should be called before decoding any sequence of variable-length values. It returns -1 if the encoded list was nil. Otherwise, it returns the length of the sequence.

                              func (*Decoder) StartStruct

                              func (d *Decoder) StartStruct() (bool, interface{})

                                StartStruct should be called before decoding a struct pointer. If it returns false, decoding should not proceed. If it returns true and the second return value is non-nil, it is a reference to a previous value and should be used instead of proceeding with decoding.

                                func (*Decoder) StoreRef

                                func (d *Decoder) StoreRef(p interface{})

                                  StoreRef should be called by a struct decoder immediately after it allocates a struct pointer.

                                  func (*Decoder) UnknownField

                                  func (d *Decoder) UnknownField(typeName string, num int)

                                    UnknownField should be called by a struct decoder when it sees a field number that it doesn't know.

                                    type Encoder

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

                                      An Encoder encodes Go values into a sequence of bytes. To use an Encoder: - Create one with NewEncoder. - Call the Encode method one or more times. - Retrieve the resulting bytes by calling Bytes.

                                      func NewEncoder

                                      func NewEncoder() *Encoder

                                        NewEncoder returns an Encoder.

                                        func (*Encoder) Bytes

                                        func (e *Encoder) Bytes() []byte

                                          Bytes returns the encoded byte slice.

                                          func (*Encoder) Encode

                                          func (e *Encoder) Encode(x interface{}) (err error)

                                            Encode encodes x.

                                            func (*Encoder) EncodeAny

                                            func (e *Encoder) EncodeAny(x interface{})

                                              EncodeAny encodes a Go type. The type must have been registered with Register.

                                              func (*Encoder) EncodeBool

                                              func (e *Encoder) EncodeBool(b bool)

                                                EncodeBool encodes a bool.

                                                func (*Encoder) EncodeBytes

                                                func (e *Encoder) EncodeBytes(b []byte)

                                                  EncodeBytes encodes a byte slice.

                                                  func (*Encoder) EncodeFloat

                                                  func (e *Encoder) EncodeFloat(f float64)

                                                    EncodeFloat encodes a float64.

                                                    func (*Encoder) EncodeInt

                                                    func (e *Encoder) EncodeInt(i int64)

                                                      EncodeInt encodes a signed integer.

                                                      func (*Encoder) EncodeNil

                                                      func (e *Encoder) EncodeNil()

                                                      func (*Encoder) EncodeString

                                                      func (e *Encoder) EncodeString(s string)

                                                        EncodeString encodes a string.

                                                        func (*Encoder) EncodeUint

                                                        func (e *Encoder) EncodeUint(u uint64)

                                                          EncodeUint encodes a uint64.

                                                          func (*Encoder) EndStruct

                                                          func (e *Encoder) EndStruct()

                                                            EndStruct should be called after encoding a struct.

                                                            func (*Encoder) StartList

                                                            func (e *Encoder) StartList(len int)

                                                              StartList should be called before encoding any sequence of variable-length values.

                                                              func (*Encoder) StartStruct

                                                              func (e *Encoder) StartStruct(isNil bool, p interface{}) bool

                                                                StartStruct should be called before encoding a struct pointer. The isNil argument says whether the pointer is nil. The p argument is the struct pointer. If StartStruct returns false, encoding should not proceed.