bson

package module
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2024 License: MIT Imports: 19 Imported by: 0

README

bson

build-img pkg-img version-img

Package implements BSON encoding and decoding in Go. See https://bsonspec.org/spec.html

Features

  • Simple API.
  • Dependency-free.
  • Optimized for speed.
  • Clean and tested code.

See docs for more details.

Install

Go version 1.18+

go get github.com/cristalhq/bson

Example

TODO

See examples: example_test.go.

License

MIT License.

Documentation

Overview

Example (Types) 
package main

import (
	"fmt"

	"github.com/cristalhq/bson"
)

func main() {
	arr := bson.A{"a", "b", "c", 12345}
	doc := bson.D{{"hello", "world"}, {"answer", 42}}
	doo := bson.M{"hello": "world", "pi": 3.14159}

	fmt.Println(arr)
	fmt.Println(arr.AsD())
	fmt.Println()

	fmt.Println(doc)
	fmt.Println(doc.AsM())
	fmt.Println()

	fmt.Println(doo)
	fmt.Println(doo.AsD())

	_, _, _ = arr, doc, doo

}

Output:

[a b c 12345]
[{0 a} {1 b} {2 c} {3 12345}]

[{hello world} {answer 42}]
map[answer:42 hello:world]

map[hello:world pi:3.14159]
[{hello world} {pi 3.14159}]

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrBadObjectID = errors.New("not a valid ObjectID")

Functions

func Marshal 

func Marshal(v any) ([]byte, error)

Marshal returns BSON encoding of v.

Example 
package main

import (
	"encoding/hex"
	"fmt"

	"github.com/cristalhq/bson"
)

func main() {
	arr := bson.A{"a", "b", "c"}

	b, err := bson.Marshal(arr)
	if err != nil {
		panic(err)
	}

	fmt.Println(hex.EncodeToString(b))

}

Output:

2000000002300002000000610002310002000000620002320002000000630000

func MarshalTo 

func MarshalTo(dst []byte, v any) ([]byte, error)

MarshalTo returns BSON encoding of v written to dst.

Example 
package main

import (
	"encoding/hex"
	"fmt"

	"github.com/cristalhq/bson"
)

func main() {
	arr := bson.A{"a", "b", "c"}

	buf := make([]byte, 0, 128)

	buf, err := bson.MarshalTo(buf, arr)
	if err != nil {
		panic(err)
	}

	fmt.Println(hex.EncodeToString(buf))

}

Output:

2000000002300002000000610002310002000000620002320002000000630000

func Unmarshal added in v0.0.6 

func Unmarshal(data []byte, v any) error

Unmarshal parses the BSON data and stores the result in the value pointed to by v.

Types

type A 

type A []any

A is a BSON array.

Example: 

bson.A{"hello", "world", 3.14159, bson.D{{"foo", 12345}}}

func (A) AsD added in v0.0.7 

func (a A) AsD() D

type Appender added in v0.0.7 

type Appender interface {
	AppendBSON([]byte) ([]byte, error)
}

Appender is the interface implemented by types that can append marshaled BSON representation of itself.

type D 

type D []e

D is an ordered representation of a BSON document.

Example usage: 

bson.D{{"hello", "world"}, {"foo", "bar"}, {"pi", 3.14159}}

func (D) AsM added in v0.0.7 

func (d D) AsM() M

func (D) Len added in v0.0.5 

func (d D) Len() int

func (D) Less added in v0.0.5 

func (d D) Less(i, j int) bool

func (D) Swap added in v0.0.5 

func (d D) Swap(i, j int)

type Decoder added in v0.0.5 

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

Decoder reads and decodes BSON values from an input stream.

func NewDecodeBytes added in v0.0.5 

func NewDecodeBytes(buf []byte) *Decoder

func (*Decoder) Decode added in v0.0.5 

func (dec *Decoder) Decode(v any) error

type Encoder 

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

Encoder writes BSON values 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 (enc *Encoder) Encode(v any) error

Encode writes the BSON encoding of v to the stream.

type M 

type M map[string]any

M is an unordered representation of a BSON document.

Example usage: 

bson.M{"hello": "world", "foo": "bar", "pi": 3.14159}

func (M) AsD 

func (m M) AsD() D

type Marshaler 

type Marshaler interface {
	MarshalBSON() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid BSON.

type ObjectID 

type ObjectID [12]byte

ObjectID represents BSON object ID.

func NewObjectID 

func NewObjectID() ObjectID

NewObjectID returns a new ObjectID.

func NewObjectIDWithTime 

func NewObjectIDWithTime(t time.Time) ObjectID

NewObjectIDWithTime returns a new ObjectID.

func (*ObjectID) MarshalBSON 

func (oid *ObjectID) MarshalBSON() ([]byte, error)

MarshalBSON implements bson.Marshaler.

func (ObjectID) MarshalBinary added in v0.0.7 

func (oid ObjectID) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler.

func (ObjectID) MarshalJSON added in v0.0.7 

func (oid ObjectID) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (ObjectID) MarshalText added in v0.0.7 

func (oid ObjectID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (ObjectID) String 

func (oid ObjectID) String() string

String returns a hex string representation of the id. Example: ObjectID('64d526fa37931c1e97eea90f').

func (*ObjectID) UnmarshalBSON 

func (oid *ObjectID) UnmarshalBSON(b []byte) error

UnmarshalBSON implements bson.Unmarshaler.

func (*ObjectID) UnmarshalBinary added in v0.0.7 

func (oid *ObjectID) UnmarshalBinary(b []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*ObjectID) UnmarshalJSON added in v0.0.7 

func (oid *ObjectID) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*ObjectID) UnmarshalText added in v0.0.7 

func (oid *ObjectID) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type RawArray added in v0.0.7 

type RawArray []byte

RawArray represents a raw array which will be encoded or decoded as is.

type RawObject added in v0.0.7 

type RawObject []byte

RawObject represents a raw object which will be encoded or decoded as is.

type Regex added in v0.0.4 

type Regex struct {
	Pattern string
	Options string
}

Regex represents BSON regular expression.

func (Regex) Compile added in v0.0.4 

func (r Regex) Compile() (*regexp.Regexp, error)

Compile returns regexp.Regexp.

func (*Regex) MarshalBSON added in v0.0.4 

func (re *Regex) MarshalBSON() ([]byte, error)

MarshalBSON implements bson.Marshaler.

func (Regex) String added in v0.0.4 

func (re Regex) String() string

String returns a hex string representation of the id.

func (*Regex) UnmarshalBSON added in v0.0.4 

func (re *Regex) UnmarshalBSON(b []byte) error

UnmarshalBSON implements bson.Unmarshaler.

type Timestamp 

type Timestamp int64

Timestamp represents BSON type Timestamp.

func NewTimestamp 

func NewTimestamp(t time.Time) Timestamp

NewTimestamp returns a timestamp with a given time.

func NewTimestampWithCounter 

func NewTimestampWithCounter(t time.Time, c uint32) Timestamp

NewTimestampWithCounter returns a timestamp with a given time and counter.

func NowTimestamp 

func NowTimestamp() Timestamp

NowTimestamp returns a timestamp with current UTC time.

func (Timestamp) Counter 

func (ts Timestamp) Counter() uint32

Counter returns timestamp counter.

func (Timestamp) MarshalBSON 

func (ts Timestamp) MarshalBSON() ([]byte, error)

MarshalBSON implements Marshaler.

func (Timestamp) MarshalBinary added in v0.0.6 

func (ts Timestamp) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler.

func (Timestamp) MarshalJSON added in v0.0.6 

func (ts Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Timestamp) MarshalText added in v0.0.6 

func (ts Timestamp) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Timestamp) String 

func (ts Timestamp) String() string

String returns a hex string representation of the id. Example: Timestamp('4398046513152, 1024').

func (Timestamp) Time 

func (ts Timestamp) Time() time.Time

Time returns time.Time ignoring increment.

func (*Timestamp) UnmarshalBSON 

func (ts *Timestamp) UnmarshalBSON(b []byte) error

UnmarshalBSON implements Unmarshaler.

func (*Timestamp) UnmarshalBinary added in v0.0.6 

func (ts *Timestamp) UnmarshalBinary(b []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler.

func (*Timestamp) UnmarshalJSON added in v0.0.6 

func (ts *Timestamp) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Timestamp) UnmarshalText added in v0.0.6 

func (ts *Timestamp) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Type 

type Type byte

Type represents a BSON type. 

const (
	TypeDouble          Type = 0x01
	TypeString          Type = 0x02
	TypeDocument        Type = 0x03
	TypeArray           Type = 0x04
	TypeBinary          Type = 0x05
	TypeUndefined       Type = 0x06
	TypeObjectID        Type = 0x07
	TypeBool            Type = 0x08
	TypeDateTime        Type = 0x09
	TypeNull            Type = 0x0a
	TypeRegex           Type = 0x0b
	TypeDBPointer       Type = 0x0c
	TypeCodeWithScope   Type = 0x0d
	TypeSymbol          Type = 0x0e
	TypeJavaScriptScope Type = 0x0f
	TypeInt32           Type = 0x10
	TypeTimestamp       Type = 0x11
	TypeInt64           Type = 0x12
	TypeDecimal         Type = 0x13
	TypeMinKey          Type = 0xff
	TypeMaxKey          Type = 0x7f
)

BSON element types as described in https://bsonspec.org/spec.html.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalBSON([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a BSON representation of themselves.

The input can be assumed to be a valid encoding of a BSON. UnmarshalBSON must copy the BSON data if it wishes to retain the data after returning.

Source Files

View all Source files

Directories

Path Synopsis
Package bsonproto provides primitives for encoding and decoding of BSON.
 Package bsonproto provides primitives for encoding and decoding of BSON.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.