bson

Documentation

Overview

Package bson implements encoding and decoding of BSON objects.

Index

• Constants
• Variables
• func DecodeArray(buf *bytes.Buffer, kind byte) []interface{}
• func DecodeBinary(buf *bytes.Buffer, kind byte) []byte
• func DecodeBool(buf *bytes.Buffer, kind byte) bool
• func DecodeFloat64(buf *bytes.Buffer, kind byte) float64
• func DecodeInt(buf *bytes.Buffer, kind byte) int
• func DecodeInt32(buf *bytes.Buffer, kind byte) int32
• func DecodeInt64(buf *bytes.Buffer, kind byte) int64
• func DecodeInterface(buf *bytes.Buffer, kind byte) interface{}
• func DecodeMap(buf *bytes.Buffer, kind byte) map[string]interface{}
• func DecodeString(buf *bytes.Buffer, kind byte) string
• func DecodeStringArray(buf *bytes.Buffer, kind byte) []string
• func DecodeTime(buf *bytes.Buffer, kind byte) time.Time
• func DecodeUint(buf *bytes.Buffer, kind byte) uint
• func DecodeUint32(buf *bytes.Buffer, kind byte) uint32
• func DecodeUint64(buf *bytes.Buffer, kind byte) uint64
• func EncodeBinary(buf *bytes2.ChunkedWriter, key string, val []byte)
• func EncodeBool(buf *bytes2.ChunkedWriter, key string, val bool)
• func EncodeField(buf *bytes2.ChunkedWriter, key string, val interface{})
• func EncodeFloat64(buf *bytes2.ChunkedWriter, key string, val float64)
• func EncodeInt(buf *bytes2.ChunkedWriter, key string, val int)
• func EncodeInt32(buf *bytes2.ChunkedWriter, key string, val int32)
• func EncodeInt64(buf *bytes2.ChunkedWriter, key string, val int64)
• func EncodeInterface(buf *bytes2.ChunkedWriter, key string, val interface{})
• func EncodeOptionalPrefix(buf *bytes2.ChunkedWriter, etype byte, key string)
• func EncodePrefix(buf *bytes2.ChunkedWriter, etype byte, key string)
• func EncodeSimple(buf *bytes2.ChunkedWriter, val interface{})
• func EncodeString(buf *bytes2.ChunkedWriter, key string, val string)
• func EncodeStringArray(buf *bytes2.ChunkedWriter, name string, values []string)
• func EncodeTime(buf *bytes2.ChunkedWriter, key string, val time.Time)
• func EncodeUint(buf *bytes2.ChunkedWriter, key string, val uint)
• func EncodeUint32(buf *bytes2.ChunkedWriter, key string, val uint32)
• func EncodeUint64(buf *bytes2.ChunkedWriter, key string, val uint64)
• func Itoa(i int) string
• func Marshal(val interface{}) (encoded []byte, err error)
• func MarshalToBuffer(buf *bytes2.ChunkedWriter, val interface{}) (err error)
• func MarshalToStream(writer io.Writer, val interface{}) (err error)
• func Next(buf *bytes.Buffer, n int) []byte
• func NextByte(buf *bytes.Buffer) byte
• func ReadCString(buf *bytes.Buffer) string
• func Skip(buf *bytes.Buffer, kind byte)
• func SkipIndex(buf *bytes.Buffer)
• func Unmarshal(b []byte, val interface{}) (err error)
• func UnmarshalFromBuffer(buf *bytes.Buffer, val interface{}) (err error)
• func UnmarshalFromStream(reader io.Reader, val interface{}) (err error)
• func VerifyObject(kind byte)
• type BsonError
  • func NewBsonError(format string, args ...interface{}) BsonError
  • func (err BsonError) Error() string
• type LenWriter
  • func NewLenWriter(buf *bytes2.ChunkedWriter) LenWriter
  • func (lw LenWriter) Close()
• type Marshaler
• type Unmarshaler

Constants

const (
	WORD32 = 4
	WORD64 = 8
)

Words size in bytes.

const (
	EOO           = 0x00
	Number        = 0x01
	String        = 0x02
	Object        = 0x03
	Array         = 0x04
	Binary        = 0x05
	Undefined     = 0x06 // deprecated
	OID           = 0x07 // unsupported
	Boolean       = 0x08
	Datetime      = 0x09
	Null          = 0x0A
	Regex         = 0x0B // unsupported
	Ref           = 0x0C // deprecated
	Code          = 0x0D // unsupported
	Symbol        = 0x0E // unsupported
	CodeWithScope = 0x0F // unsupported
	Int           = 0x10
	Timestamp     = 0x11 // unsupported
	Long          = 0x12
	Ulong         = 0x3F // nonstandard extension
	MinKey        = 0xFF // unsupported
	MaxKey        = 0x7F // unsupported
)

const DefaultBufferSize = 1024

DefaultBufferSize is the default allocation size for ChunkedWriter.

const (
	// MAGICTAG is the tag used to embed simple types inside
	// a bson document.
	MAGICTAG = "_Val_"
)

Variables

var Pack = binary.LittleEndian

Pack is the BSON binary packing protocol. It's little endian.

Functions

func DecodeArray

func DecodeArray(buf *bytes.Buffer, kind byte) []interface{}

DecodeMap decodes a []interface{} from buf. Allowed types: Array, Null.

func DecodeBinary

func DecodeBinary(buf *bytes.Buffer, kind byte) []byte

DecodeBinary decodes a []byte from buf. Allowed types: String, Binary, Null.

func DecodeBool

func DecodeBool(buf *bytes.Buffer, kind byte) bool

DecodeBool decodes a bool from buf. Allowed types: Boolean, Int, Long, Ulong, Null.

func DecodeFloat64

func DecodeFloat64(buf *bytes.Buffer, kind byte) float64

DecodeFloat64 decodes a float64 from buf. Allowed types: Number, Null.

func DecodeInt

func DecodeInt(buf *bytes.Buffer, kind byte) int

DecodeInt decodes a int64 from buf. Allowed types: Int, Long, Ulong, Null.

func DecodeInt32

func DecodeInt32(buf *bytes.Buffer, kind byte) int32

DecodeInt32 decodes a int32 from buf. Allowed types: Int, Null.

func DecodeInt64

func DecodeInt64(buf *bytes.Buffer, kind byte) int64

DecodeInt64 decodes a int64 from buf. Allowed types: Int, Long, Ulong, Null.

func DecodeInterface

func DecodeInterface(buf *bytes.Buffer, kind byte) interface{}

DecodeInterface decodes the next object into an interface. Object is decoded as map[string]interface{}. Array is decoded as []interface{}

func DecodeMap

func DecodeMap(buf *bytes.Buffer, kind byte) map[string]interface{}

DecodeMap decodes a map[string]interface{} from buf. Allowed types: Object, Null.

func DecodeString

func DecodeString(buf *bytes.Buffer, kind byte) string

DecodeString decodes a string from buf. Allowed types: String, Binary, Null,

func DecodeStringArray

func DecodeStringArray(buf *bytes.Buffer, kind byte) []string

DecodeMap decodes a []string from buf. Allowed types: Array, Null.

func DecodeTime

func DecodeTime(buf *bytes.Buffer, kind byte) time.Time

DecodeBinary decodes a time.Time from buf. Allowed types: Datetime, Null.

func DecodeUint

func DecodeUint(buf *bytes.Buffer, kind byte) uint

DecodeUint decodes a uint64 from buf. Allowed types: Int, Long, Ulong, Null.

func DecodeUint32

func DecodeUint32(buf *bytes.Buffer, kind byte) uint32

DecodeUint32 decodes a uint32 from buf. Allowed types: Int, Long, Null.

func DecodeUint64

func DecodeUint64(buf *bytes.Buffer, kind byte) uint64

DecodeUint64 decodes a uint64 from buf. Allowed types: Int, Long, Ulong, Null.

func EncodeBinary

func EncodeBinary(buf *bytes2.ChunkedWriter, key string, val []byte)

EncodeBinary encodes a []byte as binary.

func EncodeBool

func EncodeBool(buf *bytes2.ChunkedWriter, key string, val bool)

EncodeBool encodes a bool.

func EncodeField

func EncodeField(buf *bytes2.ChunkedWriter, key string, val interface{})

EncodeField encodes val using the supplied key as embedded tag. Unlike EncodeInterface, EncodeField can handle complex objects like structs, pointers, etc. But it is slower.

func EncodeFloat64

func EncodeFloat64(buf *bytes2.ChunkedWriter, key string, val float64)

EncodeFloat64 encodes a float64.

func EncodeInt

func EncodeInt(buf *bytes2.ChunkedWriter, key string, val int)

EncodeInt encodes an int.

func EncodeInt32

func EncodeInt32(buf *bytes2.ChunkedWriter, key string, val int32)

EncodeInt32 encodes an int32.

func EncodeInt64

func EncodeInt64(buf *bytes2.ChunkedWriter, key string, val int64)

EncodeInt64 encodes an int64.

func EncodeInterface

func EncodeInterface(buf *bytes2.ChunkedWriter, key string, val interface{})

EncodeInterface bson encodes an interface{}. Elements can be basic bson encodable types, or []interface{}, or map[string]interface{}, whose elements have to in turn be bson encodable.

func EncodeOptionalPrefix

func EncodeOptionalPrefix(buf *bytes2.ChunkedWriter, etype byte, key string)

EncodeOptionalPrefix encodes the key as prefix if it's not empty. If it is empty, then it's a no-op, with the assumption that it's a top level object.

func EncodePrefix

func EncodePrefix(buf *bytes2.ChunkedWriter, etype byte, key string)

EncodePrefix encodes key as prefix for the next object or value.

func EncodeSimple

func EncodeSimple(buf *bytes2.ChunkedWriter, val interface{})

EncodeSimple marshals simple objects that cannot be encoded as a top level bson document.

func EncodeString

func EncodeString(buf *bytes2.ChunkedWriter, key string, val string)

EncodeString encodes a string.

func EncodeStringArray

func EncodeStringArray(buf *bytes2.ChunkedWriter, name string, values []string)

EncodeStringArray bson encodes a []string

func EncodeTime

func EncodeTime(buf *bytes2.ChunkedWriter, key string, val time.Time)

EncodeTime encodes a time.Time.

func EncodeUint

func EncodeUint(buf *bytes2.ChunkedWriter, key string, val uint)

EncodeUint encodes an uint.

func EncodeUint32

func EncodeUint32(buf *bytes2.ChunkedWriter, key string, val uint32)

EncodeUint32 encodes an uint32.

func EncodeUint64

func EncodeUint64(buf *bytes2.ChunkedWriter, key string, val uint64)

EncodeUint64 encodes an uint64.

func Itoa

func Itoa(i int) string

func Marshal

func Marshal(val interface{}) (encoded []byte, err error)

Marshal marshals val into encoded.

func MarshalToBuffer

func MarshalToBuffer(buf *bytes2.ChunkedWriter, val interface{}) (err error)

MarshalToBuffer marshals val into buf. This is the most efficient function to use, especially when marshaling large nested objects.

func MarshalToStream

func MarshalToStream(writer io.Writer, val interface{}) (err error)

MarshalToStream marshals val into writer.

func Next

func Next(buf *bytes.Buffer, n int) []byte

Next returns the next n bytes from buf.

func NextByte

func NextByte(buf *bytes.Buffer) byte

NextByte returns the next byte from buf.

func ReadCString

func ReadCString(buf *bytes.Buffer) string

ReadCString reads the the bson document tag.

func Skip

func Skip(buf *bytes.Buffer, kind byte)

Skip will skip the next field we don't want to read.

func SkipIndex

func SkipIndex(buf *bytes.Buffer)

SkipIndex must be used to skip indexes in arrays.

func Unmarshal

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

Unmarshal unmarshals b into val.

func UnmarshalFromBuffer

func UnmarshalFromBuffer(buf *bytes.Buffer, val interface{}) (err error)

UnmarshalFromBuffer unmarshals from buf into val.

func UnmarshalFromStream

func UnmarshalFromStream(reader io.Reader, val interface{}) (err error)

UnmarshalFromStream unmarshals from reader into val.

func VerifyObject

func VerifyObject(kind byte)

VerifyObject verifies kind to make sure it's either a top level document (EOO) or an Object. TODO(sougou): deprecate this function.

Types

type BsonError

type BsonError struct {
	Message string
}

func NewBsonError

func NewBsonError(format string, args ...interface{}) BsonError

func (BsonError) Error

func (err BsonError) Error() string

type LenWriter

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

LenWriter records the current write position on the buffer and can later be used to record the number of bytes written in conformance to BSON spec

func NewLenWriter

func NewLenWriter(buf *bytes2.ChunkedWriter) LenWriter

NewLenWriter returns a LenWriter that reserves the bytes buf so they can store the length later.

func (LenWriter) Close

func (lw LenWriter) Close()

Close closes the current object being encoded by writing bson's EOO byte and recording the length.

type Marshaler

type Marshaler interface {
	MarshalBson(buf *bytes2.ChunkedWriter, key string)
}

Marshaler is the interface that needs to be satisfied by types that want to implement a custom marshaler. When being invoked as a top level object, key will be "". In such cases, MarshalBson must not encode any prefix.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalBson(buf *bytes.Buffer, kind byte)
}

Unmarshaler is the interface that needs to be satisfied by types that want to perform custom unmarshaling. If kind is EOO, then the type is being unmarshalled as a top level object. Otherwise, it's an embedded object, and kind will need to be type-checked before unmarshaling.