bsonx

package
v0.0.0-...-d5f3c33 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2019 License: Apache-2.0, Apache-2.0 Imports: 16 Imported by: 0

README 

==============================================
``bsonx`` -- Go Lang BSON Manipulation Package
==============================================

Overview
--------

The ``bsonx`` package provides an API for manipulating bson in Go programs
without needing to handle byte slices or maintain types for marshalling bson
into using reflection.

This code is an evolution from an earlier phase of development of the official
`MongoDB Go Driver's BSON library
<https://godoc.org/go.mongodb.org/mongo-driver/bson>`_, but both libraries have
diverged. For most application uses the official BSON library is a better choice
for interacting with BSON. 

The Document type in this library implements bson library's Marhsaler and
Unmarshaller interfaces, to support improved interoperation.

API and Documentation
---------------------

See the `godoc API documentation
<http://godoc.org/github.com/mongodb/ftdc/bsonx>` for more information
about amboy interfaces and internals.


Development
-----------

Please file all issues in the `MAKE project
<https://jira.mongodb.org/browse/MAKE>`_ in the `MongoDB Jira
<https://jira.mongodb.org/>`_ instance.

Future Work
-----------

- Benchmarks for lookups and iteration.

- Complete test coverage.

- Improved interfaces to more consistently avoid panics.

- Remove use of byte-constants for bsontype names throughout the package.

Documentation

Overview

Package bsonx is a bson library built on top of the legacy bson.Document type for building and interacting with bson documents. For most bson interaction use the github.com/mongodb/mongo-go-driver library.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Array 

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

Array represents an array in BSON. The methods of this type are more expensive than those on Document because they require potentially updating multiple keys to ensure the array stays valid at all times.

Example 
internalVersion := "1234567"

f := func(appName string) *Array {
	arr := NewArray()
	arr.Append(
		VC.DocumentFromElements(
			EC.String("name", "mongo-go-driver"),
			EC.String("version", internalVersion),
		),
		VC.DocumentFromElements(
			EC.String("type", "darwin"),
			EC.String("architecture", "amd64"),
		),
		VC.String("go1.9.2"),
	)
	if appName != "" {
		arr.Append(VC.DocumentFromElements(EC.String("name", appName)))
	}

	return arr
}
buf, err := f("hello-world").MarshalBSON()
if err != nil {
	fmt.Println(err)
}
fmt.Println(buf)

Output:

[154 0 0 0 3 48 0 52 0 0 0 2 110 97 109 101 0 16 0 0 0 109 111 110 103 111 45 103 111 45 100 114 105 118 101 114 0 2 118 101 114 115 105 111 110 0 8 0 0 0 49 50 51 52 53 54 55 0 0 3 49 0 46 0 0 0 2 116 121 112 101 0 7 0 0 0 100 97 114 119 105 110 0 2 97 114 99 104 105 116 101 99 116 117 114 101 0 6 0 0 0 97 109 100 54 52 0 0 2 50 0 8 0 0 0 103 111 49 46 57 46 50 0 3 51 0 27 0 0 0 2 110 97 109 101 0 12 0 0 0 104 101 108 108 111 45 119 111 114 108 100 0 0 0]

func ArrayFromDocument 

func ArrayFromDocument(doc *Document) *Array

ArrayFromDocument creates an array from a *Document. The returned array does not make a copy of the *Document, so any changes made to either will be present in both.

func MakeArray 

func MakeArray(size int) *Array

MakeArray creates a new array with the size hint (capacity) specified.

func NewArray 

func NewArray(values ...*Value) *Array

NewArray creates a new array with the specified value.

func (*Array) Append 

func (a *Array) Append(values ...*Value) *Array

Append adds the given values to the end of the array. It returns a reference to itself.

func (*Array) AppendInterface 

func (a *Array) AppendInterface(elem interface{}) *Array

AppendInterface uses the ElementConstructor's Interface to convert an arbitrary type to a BSON value (typically via typecasting, but is compatible with the Marshaler interface).

func (*Array) AppendInterfaceErr 

func (a *Array) AppendInterfaceErr(elem interface{}) error

AppendInterfaceErr uses the ElementConstructor's InterfaceErr to convert an arbitrary type to a BSON value (typically via typecasting, but is compatible with the Marshaler interface).

func (*Array) Concat 

func (a *Array) Concat(docs ...interface{}) error

Concat will append all the values from each of the arguments onto the array.

Each argument must be one of the following:

  • *Array
  • *Document
  • []byte
  • bson.Reader

Note that in the case of *Document, []byte, and bson.Reader, the keys will be ignored and only the values will be appended.

func (*Array) Delete 

func (a *Array) Delete(index uint) *Value

Delete removes the value at the given index from the array.

func (*Array) Equal 

func (a *Array) Equal(a2 *Array) bool

Equal compares this document to another, returning true if they are equal.

func (*Array) Interface 

func (a *Array) Interface() []interface{}

Interface returns a slice of interface{} typed values for every element in the array using the Value.Interface() method to export. the values.

func (*Array) Iterator 

func (a *Array) Iterator() Iterator

Iterator returns a ArrayIterator that can be used to iterate through the elements of this Array.

func (*Array) Len 

func (a *Array) Len() int

Len returns the number of elements in the array.

func (*Array) Lookup 

func (a *Array) Lookup(index uint) *Value

Lookup returns the value in the array at the given index or an error if it cannot be found.

TODO: We should fix this to align with the semantics of the *Document type, e.g. have Lookup return just a *Value or panic if it's out of bounds and have a LookupOK that returns a bool. Although if we want to align with the semantics of how Go arrays and slices work, we would not provide a LookupOK and force users to use the Len method before hand to avoid panics.

func (*Array) LookupElement 

func (a *Array) LookupElement(index uint) *Element

func (*Array) LookupElementErr 

func (a *Array) LookupElementErr(index uint) (*Element, error)

func (*Array) LookupErr 

func (a *Array) LookupErr(index uint) (*Value, error)

func (*Array) MarshalBSON 

func (a *Array) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Array) Prepend 

func (a *Array) Prepend(values ...*Value) *Array

Prepend adds the given values to the beginning of the array. It returns a reference to itself.

func (*Array) Reset 

func (a *Array) Reset()

Reset clears all elements from the array.

func (*Array) Set 

func (a *Array) Set(index uint, value *Value) *Array

Set replaces the value at the given index with the parameter value. It panics if the index is out of bounds.

func (*Array) String 

func (a *Array) String() string

String implements the fmt.Stringer interface.

func (*Array) Validate 

func (a *Array) Validate() (uint32, error)

Validate ensures that the array's underlying BSON is valid. It returns the the number of bytes in the underlying BSON if it is valid or an error if it isn't.

func (*Array) WriteArray 

func (a *Array) WriteArray(start uint, writer []byte) (int64, error)

WriteArray will serialize this array to the provided writer beginning at the provided start position.

func (*Array) WriteTo 

func (a *Array) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

type Document 

type Document struct {
	// The default behavior or Append, Prepend, and Replace is to panic on the
	// insertion of a nil element. Setting IgnoreNilInsert to true will instead
	// silently ignore any nil parameters to these methods.
	IgnoreNilInsert bool
	// contains filtered or unexported fields
}

Document is a mutable ordered map that compactly represents a BSON document.

Example 
internalVersion := "1234567"

f := func(appName string) *Document {
	doc := NewDocument(
		EC.SubDocumentFromElements("driver",
			EC.String("name", "mongo-go-driver"),
			EC.String("version", internalVersion),
		),
		EC.SubDocumentFromElements("os",
			EC.String("type", "darwin"),
			EC.String("architecture", "amd64"),
		),
		EC.String("platform", "go1.9.2"),
	)
	if appName != "" {
		doc.Append(EC.SubDocumentFromElements("application", EC.String("name", appName)))
	}

	return doc
}
buf, err := f("hello-world").MarshalBSON()
if err != nil {
	fmt.Println(err)
}
fmt.Println(buf)

Output:

[177 0 0 0 3 100 114 105 118 101 114 0 52 0 0 0 2 110 97 109 101 0 16 0 0 0 109 111 110 103 111 45 103 111 45 100 114 105 118 101 114 0 2 118 101 114 115 105 111 110 0 8 0 0 0 49 50 51 52 53 54 55 0 0 3 111 115 0 46 0 0 0 2 116 121 112 101 0 7 0 0 0 100 97 114 119 105 110 0 2 97 114 99 104 105 116 101 99 116 117 114 101 0 6 0 0 0 97 109 100 54 52 0 0 2 112 108 97 116 102 111 114 109 0 8 0 0 0 103 111 49 46 57 46 50 0 3 97 112 112 108 105 99 97 116 105 111 110 0 27 0 0 0 2 110 97 109 101 0 12 0 0 0 104 101 108 108 111 45 119 111 114 108 100 0 0 0]

func NewDocument 

func NewDocument(elems ...*Element) *Document

NewDocument creates an empty Document. The numberOfElems parameter will preallocate the underlying storage which can prevent extra allocations.

func ReadDocument 

func ReadDocument(b []byte) (*Document, error)

ReadDocument will create a Document using the provided slice of bytes. If the slice of bytes is not a valid BSON document, this method will return an error.

func (*Document) Append 

func (d *Document) Append(elems ...*Element) *Document

Append adds each element to the end of the document, in order. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

func (*Document) Concat 

func (d *Document) Concat(docs ...interface{}) error

Concat will take the keys from the provided document and concat them onto the end of this document.

doc must be one of the following:

  • *Document
  • []byte
  • io.Reader

func (*Document) Copy 

func (d *Document) Copy() *Document

Copy makes a shallow copy of this document.

func (*Document) Delete 

func (d *Document) Delete(key ...string) *Element

Delete removes the keys from the Document. The deleted element is returned. If the key does not exist, then nil is returned and the delete is a no-op. The same is true if something along the depth tree does not exist or is not a traversable type.

func (*Document) ElementAt 

func (d *Document) ElementAt(index uint) *Element

ElementAt retrieves the element at the given index in a Document. It panics if the index is out-of-bounds.

TODO(skriptble): This method could be variadic and return the element at the provided depth.

func (*Document) ElementAtOK 

func (d *Document) ElementAtOK(index uint) (*Element, bool)

ElementAtOK is the same as ElementAt, but returns a boolean instead of panicking.

func (*Document) Elements 

func (d *Document) Elements() Elements

func (*Document) Equal 

func (d *Document) Equal(d2 *Document) bool

Equal compares this document to another, returning true if they are equal.

func (*Document) ExportMap 

func (d *Document) ExportMap() map[string]interface{}

ExportMap converts the values of the document to a map of strings to interfaces, recursively, using the Value.Interface() method.

func (*Document) Iterator 

func (d *Document) Iterator() Iterator

Iterator creates an Iterator for this document and returns it.

func (*Document) Keys 

func (d *Document) Keys(recursive bool) (Keys, error)

Keys returns all of the element keys for this document. If recursive is true, this method will also return the keys of any subdocuments or arrays.

func (*Document) Len 

func (d *Document) Len() int

Len returns the number of elements in the document.

func (*Document) Lookup 

func (d *Document) Lookup(key ...string) *Value

Lookup searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

Lookup will return nil if it encounters an error.

func (*Document) LookupElement 

func (d *Document) LookupElement(key ...string) *Element

LookupElement searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

LookupElement will return nil if it encounters an error.

func (*Document) LookupElementErr 

func (d *Document) LookupElementErr(key ...string) (*Element, error)

LookupElementErr searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

func (*Document) LookupErr 

func (d *Document) LookupErr(key ...string) (*Value, error)

LookupErr searches the document and potentially subdocuments or arrays for the provided key. Each key provided to this method represents a layer of depth.

func (*Document) MarshalBSON 

func (d *Document) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Document) Prepend 

func (d *Document) Prepend(elems ...*Element) *Document

Prepend adds each element to the beginning of the document, in order. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

func (*Document) ReadFrom 

func (d *Document) ReadFrom(r io.Reader) (int64, error)

ReadFrom will read one BSON document from the given io.Reader.

func (*Document) Reset 

func (d *Document) Reset()

Reset clears a document so it can be reused. This method clears references to the underlying pointers to elements so they can be garbage collected.

func (*Document) Set 

func (d *Document) Set(elem *Element) *Document

Set replaces an element of a document. If an element with a matching key is found, the element will be replaced with the one provided. If the document does not have an element with that key, the element is appended to the document instead. If a nil element is passed as a parameter this method will panic. To change this behavior to silently ignore a nil element, set IgnoreNilInsert to true on the Document.

If a nil element is inserted and this method panics, it does not remove the previously added elements.

TODO(skriptble): Do we need to panic on a nil element? Semantically, if you ask to replace an element in the document with a nil element, you aren't asking for anything to be done.

func (*Document) Sorted 

func (d *Document) Sorted() *Document

func (*Document) String 

func (d *Document) String() string

String implements the fmt.Stringer interface.

func (*Document) UnmarshalBSON 

func (d *Document) UnmarshalBSON(b []byte) error

UnmarshalBSON implements the Unmarshaler interface.

func (*Document) Validate 

func (d *Document) Validate() (uint32, error)

Validate validates the document and returns its total size.

func (*Document) WriteDocument 

func (d *Document) WriteDocument(start uint, writer interface{}) (int64, error)

WriteDocument will serialize this document to the provided writer beginning at the provided start position.

func (*Document) WriteTo 

func (d *Document) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

TODO(skriptble): We can optimize this by having creating implementations of writeByteSlice that write directly to an io.Writer instead.

type DocumentConstructor 

type DocumentConstructor struct{}
var DC DocumentConstructor

func (DocumentConstructor) Elements 

func (DocumentConstructor) Elements(elems ...*Element) *Document

func (DocumentConstructor) Interface 

func (DocumentConstructor) Interface(value interface{}) *Document

func (DocumentConstructor) InterfaceErr 

func (DocumentConstructor) InterfaceErr(value interface{}) (*Document, error)

func (DocumentConstructor) Make 

func (DocumentConstructor) Make(n int) *Document

Make returns a document with the underlying storage allocated as specified. Provides some efficency when building larger documents iteratively.

func (DocumentConstructor) MapDuration 

func (DocumentConstructor) MapDuration(in map[string]time.Duration) *Document

func (DocumentConstructor) MapFloat32 

func (DocumentConstructor) MapFloat32(in map[string]float32) *Document

func (DocumentConstructor) MapFloat64 

func (DocumentConstructor) MapFloat64(in map[string]float64) *Document

func (DocumentConstructor) MapInt 

func (DocumentConstructor) MapInt(in map[string]int) *Document

func (DocumentConstructor) MapInt32 

func (DocumentConstructor) MapInt32(in map[string]int32) *Document

func (DocumentConstructor) MapInt64 

func (DocumentConstructor) MapInt64(in map[string]int64) *Document

func (DocumentConstructor) MapInterface 

func (DocumentConstructor) MapInterface(in map[string]interface{}) *Document

func (DocumentConstructor) MapInterfaceErr 

func (DocumentConstructor) MapInterfaceErr(in map[string]interface{}) (*Document, error)

func (DocumentConstructor) MapMarshaler 

func (DocumentConstructor) MapMarshaler(in map[string]Marshaler) *Document

func (DocumentConstructor) MapMarshalerErr 

func (DocumentConstructor) MapMarshalerErr(in map[string]Marshaler) (*Document, error)

func (DocumentConstructor) MapSliceDuration 

func (DocumentConstructor) MapSliceDuration(in map[string][]time.Duration) *Document

func (DocumentConstructor) MapSliceFloat32 

func (DocumentConstructor) MapSliceFloat32(in map[string][]float32) *Document

func (DocumentConstructor) MapSliceFloat64 

func (DocumentConstructor) MapSliceFloat64(in map[string][]float64) *Document

func (DocumentConstructor) MapSliceInt 

func (DocumentConstructor) MapSliceInt(in map[string][]int) *Document

func (DocumentConstructor) MapSliceInt32 

func (DocumentConstructor) MapSliceInt32(in map[string][]int32) *Document

func (DocumentConstructor) MapSliceInt64 

func (DocumentConstructor) MapSliceInt64(in map[string][]int64) *Document

func (DocumentConstructor) MapSliceInterface 

func (DocumentConstructor) MapSliceInterface(in map[string][]interface{}) *Document

func (DocumentConstructor) MapSliceInterfaceErr 

func (DocumentConstructor) MapSliceInterfaceErr(in map[string][]interface{}) (*Document, error)

func (DocumentConstructor) MapSliceMarshaler 

func (DocumentConstructor) MapSliceMarshaler(in map[string][]Marshaler) *Document

func (DocumentConstructor) MapSliceMarshalerErr 

func (DocumentConstructor) MapSliceMarshalerErr(in map[string][]Marshaler) (*Document, error)

func (DocumentConstructor) MapSliceString 

func (DocumentConstructor) MapSliceString(in map[string][]string) *Document

func (DocumentConstructor) MapSliceTime 

func (DocumentConstructor) MapSliceTime(in map[string][]time.Time) *Document

func (DocumentConstructor) MapString 

func (DocumentConstructor) MapString(in map[string]string) *Document

func (DocumentConstructor) MapTime 

func (DocumentConstructor) MapTime(in map[string]time.Time) *Document

func (DocumentConstructor) Marshaler 

func (DocumentConstructor) Marshaler(in Marshaler) *Document

func (DocumentConstructor) MarshalerErr 

func (DocumentConstructor) MarshalerErr(in Marshaler) (*Document, error)

func (DocumentConstructor) New 

func (DocumentConstructor) New() *Document

func (DocumentConstructor) Reader 

func (DocumentConstructor) Reader(r Reader) *Document

func (DocumentConstructor) ReaderErr 

func (DocumentConstructor) ReaderErr(r Reader) (*Document, error)

type Element 

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

Element represents a BSON element, i.e. key-value pair of a BSON document.

NOTE: Element cannot be the value of a map nor a property of a struct without special handling. The default encoders and decoders will not process Element correctly. To do so would require information loss since an Element contains a key, but the keys used when encoding a struct are the struct field names. Instead of using an Element, use a Value as the property of a struct field as that is the correct type in this circumstance.

func (*Element) Clone 

func (e *Element) Clone() *Element

Clone creates a shallow copy of the element/

func (*Element) Equal 

func (e *Element) Equal(e2 *Element) bool

Equal compares this element to element and returns true if they are equal.

func (*Element) Key 

func (e *Element) Key() string

Key returns the key for this element. It panics if e is uninitialized.

func (*Element) MarshalBSON 

func (e *Element) MarshalBSON() ([]byte, error)

MarshalBSON implements the Marshaler interface.

func (*Element) String 

func (e *Element) String() string

String implements the fmt.Stringer interface.

func (*Element) Validate 

func (e *Element) Validate() (uint32, error)

Validate validates the element and returns its total size.

func (*Element) Value 

func (e *Element) Value() *Value

Value returns the value associated with the BSON element.

func (*Element) WriteElement 

func (e *Element) WriteElement(start uint, writer interface{}) (int64, error)

WriteElement serializes this element to the provided writer starting at the provided start position.

func (*Element) WriteTo 

func (e *Element) WriteTo(w io.Writer) (int64, error)

WriteTo implements the io.WriterTo interface.

type ElementConstructor 

type ElementConstructor struct{}

ElementConstructor is used as a namespace for document element constructor functions. 

var EC ElementConstructor

EC is a convenience variable provided for access to the ElementConstructor methods.

func (ElementConstructor) Array 

func (ElementConstructor) Array(key string, a *Array) *Element

Array creates an array element with the given key and value.

func (ElementConstructor) ArrayFromElements 

func (ElementConstructor) ArrayFromElements(key string, values ...*Value) *Element

ArrayFromElements creates an element with the given key. The elements passed as arguments will be used to create a new array as the value.

func (ElementConstructor) Binary 

func (ElementConstructor) Binary(key string, b []byte) *Element

Binary creates a binary element with the given key and value.

func (ElementConstructor) BinaryWithSubtype 

func (ElementConstructor) BinaryWithSubtype(key string, b []byte, btype byte) *Element

BinaryWithSubtype creates a binary element with the given key. It will create a new BSON binary value with the given data and subtype.

func (ElementConstructor) Boolean 

func (ElementConstructor) Boolean(key string, b bool) *Element

Boolean creates a boolean element with the given key and value.

func (ElementConstructor) CodeWithScope 

func (ElementConstructor) CodeWithScope(key string, code string, scope *Document) *Element

CodeWithScope creates a JavaScript code with scope element with the given key and value.

func (ElementConstructor) DBPointer 

func (ElementConstructor) DBPointer(key string, ns string, oid types.ObjectID) *Element

DBPointer creates a dbpointer element with the given key and value.

func (ElementConstructor) DateTime 

func (ElementConstructor) DateTime(key string, dt int64) *Element

DateTime creates a datetime element with the given key and value. dt represents milliseconds since the Unix epoch

func (ElementConstructor) Decimal128 

func (ElementConstructor) Decimal128(key string, d decimal.Decimal128) *Element

Decimal128 creates a decimal element with the given key and value.

func (ElementConstructor) Double 

func (ElementConstructor) Double(key string, f float64) *Element

Double creates a double element with the given key and value.

func (ElementConstructor) Duration 

func (ElementConstructor) Duration(key string, t time.Duration) *Element

func (ElementConstructor) FromBytes 

func (ElementConstructor) FromBytes(src []byte) *Element

FromBytes constructs an element from the bytes provided. If the bytes are not a valid element, this method will panic.

func (ElementConstructor) FromBytesErr 

func (ElementConstructor) FromBytesErr(src []byte) (*Element, error)

FromBytesErr constructs an element from the bytes provided, but unlike FromBytes this method will return an error and not panic if the bytes are not a valid element.

func (ElementConstructor) FromValue 

func (ElementConstructor) FromValue(key string, value *Value) *Element

FromValue constructs an element using the underlying value.

func (ElementConstructor) FromValueErr 

func (ElementConstructor) FromValueErr(key string, value *Value) (*Element, error)

func (ElementConstructor) Int 

func (ElementConstructor) Int(key string, i int) *Element

func (ElementConstructor) Int32 

func (ElementConstructor) Int32(key string, i int32) *Element

Int32 creates a int32 element with the given key and value.

func (ElementConstructor) Int64 

func (ElementConstructor) Int64(key string, i int64) *Element

Int64 creates a int64 element with the given key and value.

func (ElementConstructor) Interface 

func (ElementConstructor) Interface(key string, value interface{}) *Element

Interface will attempt to turn the provided key and value into an Element. For common types, type casting is used, for all slices and all other complex types, this relies on the Marshaler interface.

If the value cannot be converted to bson, a null Element is constructed with the key. This method will never return a nil *Element. If an error turning the value into an Element is desired, use the InterfaceErr method.

func (ElementConstructor) InterfaceErr 

func (ElementConstructor) InterfaceErr(key string, value interface{}) (*Element, error)

InterfaceErr does what Interface does, but returns an error when it cannot properly convert a value into an *Element. See Interface for details.

func (ElementConstructor) JavaScript 

func (ElementConstructor) JavaScript(key string, code string) *Element

JavaScript creates a JavaScript code element with the given key and value.

func (ElementConstructor) Marshaler 

func (ElementConstructor) Marshaler(key string, val Marshaler) *Element

func (ElementConstructor) MarshalerErr 

func (ElementConstructor) MarshalerErr(key string, val Marshaler) (*Element, error)

func (ElementConstructor) MaxKey 

func (ElementConstructor) MaxKey(key string) *Element

MaxKey creates a maxkey element with the given key and value.

func (ElementConstructor) MinKey 

func (ElementConstructor) MinKey(key string) *Element

MinKey creates a minkey element with the given key and value.

func (ElementConstructor) Null 

func (ElementConstructor) Null(key string) *Element

Null creates a null element with the given key.

func (ElementConstructor) ObjectID 

func (ElementConstructor) ObjectID(key string, oid types.ObjectID) *Element

ObjectID creates a objectid element with the given key and value.

func (ElementConstructor) Regex 

func (ElementConstructor) Regex(key string, pattern, options string) *Element

Regex creates a regex element with the given key and value.

func (ElementConstructor) SliceDuration 

func (ElementConstructor) SliceDuration(key string, in []time.Duration) *Element

func (ElementConstructor) SliceFloat32 

func (ElementConstructor) SliceFloat32(key string, in []float32) *Element

func (ElementConstructor) SliceFloat64 

func (ElementConstructor) SliceFloat64(key string, in []float64) *Element

func (ElementConstructor) SliceInt 

func (ElementConstructor) SliceInt(key string, in []int) *Element

func (ElementConstructor) SliceInt32 

func (ElementConstructor) SliceInt32(key string, in []int32) *Element

func (ElementConstructor) SliceInt64 

func (ElementConstructor) SliceInt64(key string, in []int64) *Element

func (ElementConstructor) SliceInterface 

func (ElementConstructor) SliceInterface(key string, in []interface{}) *Element

func (ElementConstructor) SliceInterfaceErr 

func (ElementConstructor) SliceInterfaceErr(key string, in []interface{}) (*Element, error)

func (ElementConstructor) SliceMarshaler 

func (ElementConstructor) SliceMarshaler(key string, in []Marshaler) *Element

func (ElementConstructor) SliceMarshalerErr 

func (ElementConstructor) SliceMarshalerErr(key string, in []Marshaler) (*Element, error)

func (ElementConstructor) SliceString 

func (ElementConstructor) SliceString(key string, in []string) *Element

func (ElementConstructor) SliceTime 

func (ElementConstructor) SliceTime(key string, in []time.Time) *Element

func (ElementConstructor) String 

func (ElementConstructor) String(key string, val string) *Element

String creates a string element with the given key and value.

func (ElementConstructor) SubDocument 

func (ElementConstructor) SubDocument(key string, d *Document) *Element

SubDocument creates a subdocument element with the given key and value.

func (ElementConstructor) SubDocumentFromElements 

func (ElementConstructor) SubDocumentFromElements(key string, elems ...*Element) *Element

SubDocumentFromElements creates a subdocument element with the given key. The elements passed as arguments will be used to create a new document as the value.

func (ElementConstructor) SubDocumentFromReader 

func (ElementConstructor) SubDocumentFromReader(key string, r Reader) *Element

SubDocumentFromReader creates a subdocument element with the given key and value.

func (ElementConstructor) Symbol 

func (ElementConstructor) Symbol(key string, symbol string) *Element

Symbol creates a symbol element with the given key and value.

func (ElementConstructor) Time 

func (ElementConstructor) Time(key string, t time.Time) *Element

Time creates a datetime element with the given key and value.

func (ElementConstructor) Timestamp 

func (ElementConstructor) Timestamp(key string, t uint32, i uint32) *Element

Timestamp creates a timestamp element with the given key and value.

func (ElementConstructor) Undefined 

func (ElementConstructor) Undefined(key string) *Element

Undefined creates a undefined element with the given key.

type Elements 

type Elements []*Element

func (Elements) Len 

func (c Elements) Len() int

func (Elements) Less 

func (c Elements) Less(i, j int) bool

func (Elements) Swap 

func (c Elements) Swap(i, j int)

type Iterator 

type Iterator interface {
	Next() bool
	Element() *Element
	Value() *Value
	Err() error
}

Iterator describes the types used to iterate over a bson Document.

type Key 

type Key struct {
	Prefix []string
	Name   string
}

Key represents an individual key of a BSON document. The Prefix property is used to represent the depth of this key.

func (Key) String 

func (k Key) String() string

String implements the fmt.Stringer interface.

type Keys 

type Keys []Key

Keys represents the keys of a BSON document.

type Marshaler 

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

Marshaler describes types that know how to marshal a document representation of themselves into bson. Do not use this interface for types that would marshal themselves into values.

type Reader 

type Reader []byte

Reader is a wrapper around a byte slice. It will interpret the slice as a BSON document. Most of the methods on Reader are low cost and are meant for simple operations that are run a few times. Because there is no metadata stored all methods run in O(n) time. If a more efficient lookup method is necessary then the Document type should be used.

func NewFromIOReader 

func NewFromIOReader(r io.Reader) (Reader, error)

NewFromIOReader reads in a document from the given io.Reader and constructs a bson.Reader from it.

func (Reader) ElementAt 

func (r Reader) ElementAt(index uint) (*Element, error)

ElementAt searches for a retrieves the element at the given index. This method will validate all the elements up to and including the element at the given index.

func (Reader) Iterator 

func (r Reader) Iterator() (Iterator, error)

Iterator returns a ReaderIterator that can be used to iterate through the elements of this Reader.

func (Reader) Keys 

func (r Reader) Keys(recursive bool) (Keys, error)

Keys returns the keys for this document. If recursive is true then this method will also return the keys for subdocuments and arrays.

The keys will be return in order.

func (Reader) Lookup 

func (r Reader) Lookup(key ...string) (*Element, error)

Lookup search the document, potentially recursively, for the given key. If there are multiple keys provided, this method will recurse down, as long as the top and intermediate nodes are either documents or arrays. If any key except for the last is not a document or an array, an error will be returned.

TODO(skriptble): Implement better error messages.

TODO(skriptble): Determine if this should return an error on empty key and key not found.

func (Reader) MarshalBSON 

func (r Reader) MarshalBSON() ([]byte, error)

MarshalBSON implements the bsoncodec.Marshaler interface.

This method does not copy the bytes from r.

func (Reader) String 

func (r Reader) String() string

String implements the fmt.Stringer interface.

func (Reader) Validate 

func (r Reader) Validate() (size uint32, err error)

Validate validates the document. This method only validates the first document in the slice, to validate other documents, the slice must be resliced.

Example 
rdr := make(Reader, 500)
rdr[250], rdr[251], rdr[252], rdr[253], rdr[254] = '\x05', '\x00', '\x00', '\x00', '\x00'
n, err := rdr[250:].Validate()
fmt.Println(n, err)

Output:

5 <nil>

type Unmarshaler 

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

Unmarshaler describes types that can take a byte slice representation of bson and poulate themselves from this data.

type Value 

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

Value represents a BSON value. It can be obtained as part of a bson.Element or created for use in a bson.Array with the bson.VC constructors.

func (*Value) Add 

func (v *Value) Add(v2 *Value) error

Add will add this Value to another. This is currently only implemented for strings and numbers. If either value is a string, the other type is coerced into a string and added to the other.

func (*Value) Binary 

func (v *Value) Binary() (subtype byte, data []byte)

Binary returns the BSON binary value the Value represents. It panics if the value is a BSON type other than binary.

func (*Value) BinaryOK 

func (v *Value) BinaryOK() (subtype byte, data []byte, ok bool)

BinaryOK is the same as Binary, except it returns a boolean instead of panicking.

func (*Value) Boolean 

func (v *Value) Boolean() bool

Boolean returns the boolean value the Value represents. It panics if the value is a BSON type other than boolean.

func (*Value) BooleanOK 

func (v *Value) BooleanOK() (bool, bool)

BooleanOK is the same as Boolean, except it returns a boolean instead of panicking.

func (*Value) DBPointer 

func (v *Value) DBPointer() (string, types.ObjectID)

DBPointer returns the BSON dbpointer value the Value represents. It panics if the value is a BSON type other than DBPointer.

func (*Value) DBPointerOK 

func (v *Value) DBPointerOK() (string, types.ObjectID, bool)

DBPointerOK is the same as DBPoitner, except that it returns a boolean instead of panicking.

func (*Value) DateTime 

func (v *Value) DateTime() int64

DateTime returns the BSON datetime value the Value represents as a unix timestamp. It panics if the value is a BSON type other than datetime.

func (*Value) DateTimeOK 

func (v *Value) DateTimeOK() (int64, bool)

DateTimeOK is the same as DateTime, except it returns a boolean instead of panicking.

func (*Value) Decimal128 

func (v *Value) Decimal128() decimal.Decimal128

Decimal128 returns the decimal the Value represents. It panics if the value is a BSON type other than decimal.

func (*Value) Decimal128OK 

func (v *Value) Decimal128OK() (decimal.Decimal128, bool)

Decimal128OK is the same as Decimal128, except that it returns a boolean instead of panicking.

func (*Value) Double 

func (v *Value) Double() float64

Double returns the float64 value for this element. It panics if e's BSON type is not double ('\x01') or if e is uninitialized.

func (*Value) DoubleOK 

func (v *Value) DoubleOK() (float64, bool)

DoubleOK is the same as Double, but returns a boolean instead of panicking.

func (*Value) Equal 

func (v *Value) Equal(v2 *Value) bool

Equal compares v to v2 and returns true if they are equal. This method will ensure that the values are logically equal, even if their internal structure is different. This method should be used over reflect.DeepEqual which will not return true for Values that are logically the same but not internally the same.

func (*Value) Int32 

func (v *Value) Int32() int32

Int32 returns the int32 the Value represents. It panics if the value is a BSON type other than int32.

func (*Value) Int32OK 

func (v *Value) Int32OK() (int32, bool)

Int32OK is the same as Int32, except that it returns a boolean instead of panicking.

func (*Value) Int64 

func (v *Value) Int64() int64

Int64 returns the int64 the Value represents. It panics if the value is a BSON type other than int64.

func (*Value) Int64OK 

func (v *Value) Int64OK() (int64, bool)

Int64OK is the same as Int64, except that it returns a boolean instead of panicking.

func (*Value) Interface 

func (v *Value) Interface() interface{}

Interface returns the Go value of this Value as an empty interface.

For embedded documents and arrays, Interface will convert the elements to map[string]interface{} or []interface{} as possible.

The underlying types of the values returned by this method are their native corresponding type when possible.

func (*Value) IsNumber 

func (v *Value) IsNumber() bool

IsNumber returns true if the type of v is a numberic BSON type.

func (*Value) JavaScript 

func (v *Value) JavaScript() string

JavaScript returns the BSON JavaScript code value the Value represents. It panics if the value is a BSON type other than JavaScript code.

func (*Value) JavaScriptOK 

func (v *Value) JavaScriptOK() (string, bool)

JavaScriptOK is the same as Javascript, excepti that it returns a boolean instead of panicking.

func (*Value) MutableArray 

func (v *Value) MutableArray() *Array

MutableArray returns the array for this element.

func (*Value) MutableArrayOK 

func (v *Value) MutableArrayOK() (*Array, bool)

MutableArrayOK is the same as MutableArray, except it returns a boolean instead of panicking.

func (*Value) MutableDocument 

func (v *Value) MutableDocument() *Document

MutableDocument returns the subdocument for this element.

func (*Value) MutableDocumentOK 

func (v *Value) MutableDocumentOK() (*Document, bool)

MutableDocumentOK is the same as MutableDocument, except it returns a boolean instead of panicking.

func (*Value) MutableJavaScriptWithScope 

func (v *Value) MutableJavaScriptWithScope() (code string, d *Document)

MutableJavaScriptWithScope returns the javascript code and the scope document for this element.

func (*Value) MutableJavaScriptWithScopeOK 

func (v *Value) MutableJavaScriptWithScopeOK() (string, *Document, bool)

MutableJavaScriptWithScopeOK is the same as MutableJavascriptWithScope, except that it returns a boolean instead of panicking.

func (*Value) ObjectID 

func (v *Value) ObjectID() types.ObjectID

ObjectID returns the BSON objectid value the Value represents. It panics if the value is a BSON type other than objectid.

func (*Value) ObjectIDOK 

func (v *Value) ObjectIDOK() (types.ObjectID, bool)

ObjectIDOK is the same as ObjectID, except it returns a boolean instead of panicking.

func (*Value) Offset 

func (v *Value) Offset() uint32

Offset returns the offset to the beginning of the value in the underlying data. When called on a value obtained from a Reader, it can be used to find the value manually within the Reader's bytes.

func (*Value) ReaderArray 

func (v *Value) ReaderArray() Reader

ReaderArray returns the BSON document the Value represents as a bson.Reader. It panics if the value is a BSON type other than array.

func (*Value) ReaderArrayOK 

func (v *Value) ReaderArrayOK() (Reader, bool)

ReaderArrayOK is the same as ReaderArray, except it returns a boolean instead of panicking.

func (*Value) ReaderDocument 

func (v *Value) ReaderDocument() Reader

ReaderDocument returns the BSON document the Value represents as a bson.Reader. It panics if the value is a BSON type other than document.

func (*Value) ReaderDocumentOK 

func (v *Value) ReaderDocumentOK() (Reader, bool)

ReaderDocumentOK is the same as ReaderDocument, except it returns a boolean instead of panicking.

func (*Value) ReaderJavaScriptWithScope 

func (v *Value) ReaderJavaScriptWithScope() (string, Reader)

ReaderJavaScriptWithScope returns the BSON JavaScript code with scope the Value represents, with the scope being returned as a bson.Reader. It panics if the value is a BSON type other than JavaScript code with scope.

func (*Value) ReaderJavaScriptWithScopeOK 

func (v *Value) ReaderJavaScriptWithScopeOK() (string, Reader, bool)

ReaderJavaScriptWithScopeOK is the same as ReaderJavaScriptWithScope, except that it returns a boolean instead of panicking.

func (*Value) Regex 

func (v *Value) Regex() (pattern, options string)

Regex returns the BSON regex value the Value represents. It panics if the value is a BSON type other than regex.

func (*Value) StringValue 

func (v *Value) StringValue() string

StringValue returns the string balue for this element. It panics if e's BSON type is not StringValue ('\x02') or if e is uninitialized.

NOTE: This method is called StringValue to avoid it implementing the fmt.Stringer interface.

func (*Value) StringValueOK 

func (v *Value) StringValueOK() (string, bool)

StringValueOK is the same as StringValue, but returns a boolean instead of panicking.

func (*Value) Symbol 

func (v *Value) Symbol() string

Symbol returns the BSON symbol value the Value represents. It panics if the value is a BSON type other than symbol.

func (*Value) Time 

func (v *Value) Time() time.Time

Time returns the BSON datetime value the Value represents. It panics if the value is a BSON type other than datetime.

func (*Value) TimeOK 

func (v *Value) TimeOK() (time.Time, bool)

TimeOK is the same as Time, except it returns a boolean instead of panicking.

func (*Value) Timestamp 

func (v *Value) Timestamp() (uint32, uint32)

Timestamp returns the BSON timestamp value the Value represents. It panics if the value is a BSON type other than timestamp.

func (*Value) TimestampOK 

func (v *Value) TimestampOK() (uint32, uint32, bool)

TimestampOK is the same as Timestamp, except that it returns a boolean instead of panicking.

func (*Value) Type 

func (v *Value) Type() bsontype.Type

Type returns the identifying element byte for this element. It panics if e is uninitialized.

func (*Value) Validate 

func (v *Value) Validate() error

Validate validates the value.

type ValueConstructor 

type ValueConstructor struct{}

ValueConstructor is used as a namespace for document element constructor functions. 

var VC ValueConstructor

VC is a convenience variable provided for access to the ValueConstructor methods.

func (ValueConstructor) Array 

func (ValueConstructor) Array(a *Array) *Value

Array creates an array value from the argument.

func (ValueConstructor) ArrayFromValues 

func (ValueConstructor) ArrayFromValues(values ...*Value) *Value

ArrayFromValues creates an array element from the given the elements.

func (ValueConstructor) Binary 

func (ValueConstructor) Binary(b []byte) *Value

Binary creates a binary value from the argument.

func (ValueConstructor) BinaryWithSubtype 

func (ValueConstructor) BinaryWithSubtype(b []byte, btype byte) *Value

BinaryWithSubtype creates a new binary element with the given data and subtype.

func (ValueConstructor) Boolean 

func (ValueConstructor) Boolean(b bool) *Value

Boolean creates a boolean value from the argument.

func (ValueConstructor) CodeWithScope 

func (ValueConstructor) CodeWithScope(code string, scope *Document) *Value

CodeWithScope creates a JavaScript code with scope value from the arguments.

func (ValueConstructor) DBPointer 

func (ValueConstructor) DBPointer(ns string, oid types.ObjectID) *Value

DBPointer creates a dbpointer value from the arguments.

func (ValueConstructor) DateTime 

func (ValueConstructor) DateTime(dt int64) *Value

DateTime creates a datetime value from the argument.

func (ValueConstructor) Decimal128 

func (ValueConstructor) Decimal128(d decimal.Decimal128) *Value

Decimal128 creates a decimal value from the argument.

func (ValueConstructor) Document 

func (ValueConstructor) Document(d *Document) *Value

Document creates a subdocument value from the argument.

func (ValueConstructor) DocumentFromElements 

func (ValueConstructor) DocumentFromElements(elems ...*Element) *Value

DocumentFromElements creates a subdocument element from the given elements.

func (ValueConstructor) DocumentFromReader 

func (ValueConstructor) DocumentFromReader(r Reader) *Value

DocumentFromReader creates a subdocument element from the given value.

func (ValueConstructor) Double 

func (ValueConstructor) Double(f float64) *Value

Double creates a double element with the given value.

func (ValueConstructor) Duration 

func (ValueConstructor) Duration(t time.Duration) *Value

func (ValueConstructor) Int 

func (ValueConstructor) Int(in int) *Value

func (ValueConstructor) Int32 

func (ValueConstructor) Int32(i int32) *Value

Int32 creates a int32 value from the argument.

func (ValueConstructor) Int64 

func (ValueConstructor) Int64(i int64) *Value

Int64 creates a int64 value from the argument.

func (ValueConstructor) Interface 

func (ValueConstructor) Interface(in interface{}) *Value

func (ValueConstructor) InterfaceErr 

func (ValueConstructor) InterfaceErr(in interface{}) (*Value, error)

func (ValueConstructor) JavaScript 

func (ValueConstructor) JavaScript(code string) *Value

JavaScript creates a JavaScript code value from the argument.

func (ValueConstructor) MapDuration 

func (ValueConstructor) MapDuration(in map[string]time.Duration) *Value

func (ValueConstructor) MapFloat32 

func (ValueConstructor) MapFloat32(in map[string]float32) *Value

func (ValueConstructor) MapFloat64 

func (ValueConstructor) MapFloat64(in map[string]float64) *Value

func (ValueConstructor) MapInt 

func (ValueConstructor) MapInt(in map[string]int) *Value

func (ValueConstructor) MapInt32 

func (ValueConstructor) MapInt32(in map[string]int32) *Value

func (ValueConstructor) MapInt64 

func (ValueConstructor) MapInt64(in map[string]int64) *Value

func (ValueConstructor) MapInterface 

func (ValueConstructor) MapInterface(in map[string]interface{}) *Value

func (ValueConstructor) MapInterfaceErr 

func (ValueConstructor) MapInterfaceErr(in map[string]interface{}) (*Value, error)

func (ValueConstructor) MapMarshaler 

func (ValueConstructor) MapMarshaler(in map[string]Marshaler) *Value

func (ValueConstructor) MapMarshalerErr 

func (ValueConstructor) MapMarshalerErr(in map[string]Marshaler) (*Value, error)

func (ValueConstructor) MapSliceDuration 

func (ValueConstructor) MapSliceDuration(in map[string][]time.Duration) *Value

func (ValueConstructor) MapSliceFloat32 

func (ValueConstructor) MapSliceFloat32(in map[string][]float32) *Value

func (ValueConstructor) MapSliceFloat64 

func (ValueConstructor) MapSliceFloat64(in map[string][]float64) *Value

func (ValueConstructor) MapSliceInt 

func (ValueConstructor) MapSliceInt(in map[string][]int) *Value

func (ValueConstructor) MapSliceInt32 

func (ValueConstructor) MapSliceInt32(in map[string][]int32) *Value

func (ValueConstructor) MapSliceInt64 

func (ValueConstructor) MapSliceInt64(in map[string][]int64) *Value

func (ValueConstructor) MapSliceInterface 

func (ValueConstructor) MapSliceInterface(in map[string][]interface{}) *Value

func (ValueConstructor) MapSliceInterfaceErr 

func (ValueConstructor) MapSliceInterfaceErr(in map[string][]interface{}) (*Value, error)

func (ValueConstructor) MapSliceMarshaler 

func (ValueConstructor) MapSliceMarshaler(in map[string][]Marshaler) *Value

func (ValueConstructor) MapSliceMarshalerErr 

func (ValueConstructor) MapSliceMarshalerErr(in map[string][]Marshaler) (*Value, error)

func (ValueConstructor) MapSliceString 

func (ValueConstructor) MapSliceString(in map[string][]string) *Value

func (ValueConstructor) MapSliceTime 

func (ValueConstructor) MapSliceTime(in map[string][]time.Time) *Value

func (ValueConstructor) MapString 

func (ValueConstructor) MapString(in map[string]string) *Value

func (ValueConstructor) MapTime 

func (ValueConstructor) MapTime(in map[string]time.Time) *Value

func (ValueConstructor) Marshaler 

func (ValueConstructor) Marshaler(in Marshaler) *Value

func (ValueConstructor) MarshalerErr 

func (ValueConstructor) MarshalerErr(in Marshaler) (*Value, error)

func (ValueConstructor) MaxKey 

func (ValueConstructor) MaxKey() *Value

MaxKey creates a maxkey value from the argument.

func (ValueConstructor) MinKey 

func (ValueConstructor) MinKey() *Value

MinKey creates a minkey value from the argument.

func (ValueConstructor) Null 

func (ValueConstructor) Null() *Value

Null creates a null value from the argument.

func (ValueConstructor) ObjectID 

func (ValueConstructor) ObjectID(oid types.ObjectID) *Value

ObjectID creates a objectid value from the argument.

func (ValueConstructor) Regex 

func (ValueConstructor) Regex(pattern, options string) *Value

Regex creates a regex value from the arguments.

func (ValueConstructor) SliceDuration 

func (ValueConstructor) SliceDuration(in []time.Duration) *Value

func (ValueConstructor) SliceFloat32 

func (ValueConstructor) SliceFloat32(in []float32) *Value

func (ValueConstructor) SliceFloat64 

func (ValueConstructor) SliceFloat64(in []float64) *Value

func (ValueConstructor) SliceInt 

func (ValueConstructor) SliceInt(in []int) *Value

func (ValueConstructor) SliceInt32 

func (ValueConstructor) SliceInt32(in []int32) *Value

func (ValueConstructor) SliceInt64 

func (ValueConstructor) SliceInt64(in []int64) *Value

func (ValueConstructor) SliceInterface 

func (ValueConstructor) SliceInterface(in []interface{}) *Value

func (ValueConstructor) SliceInterfaceErr 

func (ValueConstructor) SliceInterfaceErr(in []interface{}) (*Value, error)

func (ValueConstructor) SliceMarshaler 

func (ValueConstructor) SliceMarshaler(in []Marshaler) *Value

func (ValueConstructor) SliceMarshalerErr 

func (ValueConstructor) SliceMarshalerErr(in []Marshaler) (*Value, error)

func (ValueConstructor) SliceString 

func (ValueConstructor) SliceString(in []string) *Value

func (ValueConstructor) SliceTime 

func (ValueConstructor) SliceTime(in []time.Time) *Value

func (ValueConstructor) String 

func (ValueConstructor) String(val string) *Value

String creates a string element with the given value.

func (ValueConstructor) Symbol 

func (ValueConstructor) Symbol(symbol string) *Value

Symbol creates a symbol value from the argument.

func (ValueConstructor) Time 

func (ValueConstructor) Time(t time.Time) *Value

Time creates a datetime value from the argument.

func (ValueConstructor) Timestamp 

func (ValueConstructor) Timestamp(t uint32, i uint32) *Value

Timestamp creates a timestamp value from the arguments.

func (ValueConstructor) Undefined 

func (ValueConstructor) Undefined() *Value

Undefined creates a undefined element.

Source Files

View all Source files

Directories

Path Synopsis
Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON.
 Package bsontype is a utility package that contains types for each BSON type and the a stringifier for the Type to enable easier debugging when working with BSON.
Package elements holds the logic to encode and decode the BSON element types from native Go to BSON binary and vice versa.
 Package elements holds the logic to encode and decode the BSON element types from native Go to BSON binary and vice versa.
ast

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.