types

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jun 27, 2022 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package types provides Go types matching BSON types that don't have built-in Go equivalents.

All BSON types have three representations in FerretDB:

  1. As they are used in "business logic" / handlers - `types` package.
  2. As they are used in the wire protocol implementation - `bson` package.
  3. As they are used to store data in PostgreSQL - `fjson` package.

The reason for that is a separation of concerns: to avoid method names clashes, to simplify type asserts, to make refactorings and optimizations easier, etc.

Mapping

Composite types (passed by pointers) 

*types.Document  *bson.Document       *fjson.documentType   Document
*types.Array     *bson.arrayType      *fjson.arrayType      Array

Scalar types (passed by values) 

float64          *bson.doubleType     *fjson.doubleType     64-bit binary floating point
string           *bson.stringType     *fjson.stringType     UTF-8 string
types.Binary     *bson.binaryType     *fjson.binaryType     Binary data
types.ObjectID   *bson.objectIDType   *fjson.objectIDType   ObjectId
bool             *bson.boolType       *fjson.boolType       Boolean
time.Time        *bson.dateTimeType   *fjson.dateTimeType   UTC datetime
types.NullType   *bson.nullType       *fjson.nullType       Null
types.Regex      *bson.regexType      *fjson.regexType      Regular expression
int32            *bson.int32Type      *fjson.int32Type      32-bit integer
types.Timestamp  *bson.timestampType  *fjson.timestampType  Timestamp
int64            *bson.int64Type      *fjson.int64Type      64-bit integer

Index

Constants

View Source 
const (
	// BinaryGeneric represents a BSON generic binary subtype.
	BinaryGeneric = BinarySubtype(0x00) // generic

	// BinaryFunction represents a BSON function.
	BinaryFunction = BinarySubtype(0x01) // function

	// BinaryGenericOld represents a BSON generic-old.
	BinaryGenericOld = BinarySubtype(0x02) // generic-old

	// BinaryUUIDOld represents a BSON UUID old.
	BinaryUUIDOld = BinarySubtype(0x03) // uuid-old

	// BinaryUUID represents a BSON UUID.
	BinaryUUID = BinarySubtype(0x04) // uuid

	// BinaryMD5 represents a BSON md5.
	BinaryMD5 = BinarySubtype(0x05) // md5

	// BinaryEncrypted represents a Encrypted BSON value.
	BinaryEncrypted = BinarySubtype(0x06) // encrypted

	// BinaryUser represents a  User defined.
	BinaryUser = BinarySubtype(0x80) // user
)
View Source 
const MaxDocumentLen = 16777216

MaxDocumentLen is the maximum BSON object size.

View Source 
const ObjectIDLen = 12

ObjectIDLen is an ObjectID length in bytes.

Variables

View Source 
var (
	// ErrOptionNotImplemented indicates unimplemented regex option.
	ErrOptionNotImplemented = fmt.Errorf("regex: option not implemented")

	// ErrMissingParen indicates missing parentheses in regex expression.
	ErrMissingParen = fmt.Errorf("Regular expression is invalid: missing )")

	// ErrMissingBracket indicates missing terminating ] for character class.
	ErrMissingBracket = fmt.Errorf("Regular expression is invalid: missing terminating ] for character class")

	// ErrInvalidEscape indicates invalid escape errors.
	ErrInvalidEscape = fmt.Errorf("Regular expression is invalid: PCRE does not support \\L, \\l, \\N{name}, \\U, or \\u")

	// ErrMissingTerminator indicates syntax error in subpattern name (missing terminator).
	ErrMissingTerminator = fmt.Errorf("Regular expression is invalid: syntax error in subpattern name (missing terminator)")

	// ErrUnmatchedParentheses indicates unmatched parentheses.
	ErrUnmatchedParentheses = fmt.Errorf("Regular expression is invalid: unmatched parentheses")

	// ErrTrailingBackslash indicates \\ at end of the pattern.
	ErrTrailingBackslash = fmt.Errorf("Regular expression is invalid: \\ at end of pattern")

	// ErrNothingToRepeat indicates invalid regex: nothing to repeat.
	ErrNothingToRepeat = fmt.Errorf("Regular expression is invalid: nothing to repeat")

	// ErrInvalidClassRange indicates that range out of order in character class.
	ErrInvalidClassRange = fmt.Errorf("Regular expression is invalid: range out of order in character class")

	// ErrUnsupportedPerlOp indicates unrecognized character after the grouping sequence start.
	ErrUnsupportedPerlOp = fmt.Errorf("Regular expression is invalid: unrecognized character after (? or (?-")

	// ErrInvalidRepeatSize indicates that the regular expression is too large.
	ErrInvalidRepeatSize = fmt.Errorf("Regular expression is invalid: regular expression is too large")
)
View Source 
var Null = NullType{}

Null represents BSON value Null.

Functions

func RemoveByPath added in v0.2.1 

func RemoveByPath[T CompositeTypeInterface](comp T, path Path)

RemoveByPath removes document by path, doing nothing if the key does not exist.

Types

type Array 

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

Array represents BSON array.

Zero value is a valid empty array.

func MakeArray added in v0.0.5 

func MakeArray(capacity int) *Array

MakeArray creates an empty array with set capacity.

func NewArray added in v0.0.5 

func NewArray(values ...any) (*Array, error)

NewArray creates an array with the given values.

func (*Array) Append added in v0.0.5 

func (a *Array) Append(values ...any) error

Append appends given values to the array.

func (*Array) DeepCopy added in v0.1.1 

func (a *Array) DeepCopy() *Array

DeepCopy returns a deep copy of this Array.

func (*Array) Get added in v0.0.5 

func (a *Array) Get(index int) (any, error)

Get returns a value at the given index.

func (*Array) GetByPath added in v0.0.5 

func (a *Array) GetByPath(path Path) (any, error)

GetByPath returns a value by path - a sequence of indexes and keys.

func (*Array) Len added in v0.0.5 

func (a *Array) Len() int

Len returns the number of elements in the array.

It returns 0 for nil Array.

func (*Array) Max added in v0.4.0 

func (a *Array) Max() any

Max returns the maximum value from the array.

func (*Array) Min added in v0.4.0 

func (a *Array) Min() any

Min returns the minimum value from the array.

func (*Array) RemoveByPath added in v0.2.1 

func (a *Array) RemoveByPath(path Path)

RemoveByPath removes document by path, doing nothing if the key does not exist.

func (*Array) Set added in v0.0.5 

func (a *Array) Set(index int, value any) error

Set sets the value at the given index.

type Binary 

type Binary struct {
	Subtype BinarySubtype
	B       []byte
}

Binary represents BSON type Binary.

type BinarySubtype 

type BinarySubtype byte

BinarySubtype represents BSON Binary's subtype.

func (BinarySubtype) String 

func (i BinarySubtype) String() string

type CompareResult added in v0.2.0 

type CompareResult int8

CompareResult represents the result of a comparison. 

const (
	Equal        CompareResult = 0   // ==
	Less         CompareResult = -1  // <
	Greater      CompareResult = 1   // >
	Incomparable CompareResult = 127 // ≹
)

Values match results of comparison functions such as bytes.Compare. They do not match MongoDB SortType values where 1 means ascending order and -1 means descending.

func Compare added in v0.2.0 

func Compare(docValue, filterValue any) CompareResult

Compare compares any BSON values in the same way as MongoDB does it for filtering.

It converts types as needed; that may result in different types being equal. For that reason, it typically should not be used in tests.

Compare and contrast with test helpers in testutil package.

func CompareOrder added in v0.3.0 

func CompareOrder(a, b any, order SortType) CompareResult

CompareOrder detects the data type for two values and compares them. When the types are equal, it compares their values using Compare.

func (CompareResult) String added in v0.2.0 

func (i CompareResult) String() string

type CompositeType added in v0.0.5 

type CompositeType interface {
	*Document | *Array
}

CompositeType represents composite type - *Document or *Array.

type CompositeTypeInterface added in v0.0.6 

type CompositeTypeInterface interface {
	CompositeType
	GetByPath(path Path) (any, error)
	RemoveByPath(path Path)
	// contains filtered or unexported methods
}

CompositeTypeInterface consists of Document and Array. TODO remove once we have go-sumtype equivalent?

type Document 

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

Document represents BSON document.

Duplicate field names are not supported.

func ConvertDocument 

func ConvertDocument(d document) (*Document, error)

ConvertDocument converts bson.Document to *types.Document and validates it. It references the same data without copying it.

TODO Remove this function.

func NewDocument added in v0.0.6 

func NewDocument(pairs ...any) (*Document, error)

NewDocument creates a document with the given key/value pairs.

func (*Document) Command 

func (d *Document) Command() string

Command returns the first document's key. This is often used as a command name. It returns an empty string if document is nil or empty.

func (*Document) DeepCopy added in v0.1.1 

func (d *Document) DeepCopy() *Document

DeepCopy returns a deep copy of this Document.

func (*Document) Get added in v0.0.5 

func (d *Document) Get(key string) (any, error)

Get returns a value at the given key.

func (*Document) GetByPath added in v0.0.5 

func (d *Document) GetByPath(path Path) (any, error)

GetByPath returns a value by path - a sequence of indexes and keys.

func (*Document) Has added in v0.1.1 

func (d *Document) Has(key string) bool

Has returns true if the given key is present in the document.

func (*Document) Keys 

func (d *Document) Keys() []string

Keys returns document's keys. Do not modify it.

It returns nil for nil Document.

func (*Document) Len added in v0.0.6 

func (d *Document) Len() int

Len returns the number of elements in the document.

It returns 0 for nil Document.

func (*Document) Map 

func (d *Document) Map() map[string]any

Map returns this document as a map. Do not modify it.

It returns nil for nil Document.

func (*Document) Remove 

func (d *Document) Remove(key string)

Remove the given key, doing nothing if the key does not exist.

func (*Document) RemoveByPath added in v0.1.0 

func (d *Document) RemoveByPath(path Path)

RemoveByPath removes document by path, doing nothing if the key does not exist.

func (*Document) Set 

func (d *Document) Set(key string, value any) error

Set sets the value for the given key, replacing any existing value.

As a special case, _id always becomes the first key.

type NullType added in v0.0.6 

type NullType struct{}

NullType represents BSON type Null.

Most callers should use types.Null value instead.

type ObjectID 

type ObjectID [ObjectIDLen]byte

ObjectID represents BSON type ObjectID.

Normally, it is generated by the driver, but in some cases (like upserts) FerretDB has to do itself.

func NewObjectID added in v0.1.1 

func NewObjectID() ObjectID

NewObjectID returns a new ObjectID.

type Path added in v0.3.0 

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

Path represents the field path type. It should be used wherever we work with paths or dot notation. Path should be stored and passed as a value. Its methods return new values, not modifying the receiver's state.

func NewPath added in v0.3.0 

func NewPath(path []string) Path

NewPath returns Path from a strings slice.

func NewPathFromString added in v0.3.0 

func NewPathFromString(s string) Path

NewPathFromString returns Path from path string. Path string should contain fields separated with '.'.

func (Path) Len added in v0.3.0 

func (p Path) Len() int

Len returns path length.

func (Path) Prefix added in v0.3.0 

func (p Path) Prefix() string

Prefix returns the first path element.

func (Path) Slice added in v0.3.0 

func (p Path) Slice() []string

Slice returns path values array.

func (Path) String added in v0.3.0 

func (p Path) String() string

String returns dot-separated path value.

func (Path) Suffix added in v0.3.0 

func (p Path) Suffix() string

Suffix returns the last path element.

func (Path) TrimPrefix added in v0.3.0 

func (p Path) TrimPrefix() Path

TrimPrefix returns a copy of path without the first element.

func (Path) TrimSuffix added in v0.3.0 

func (p Path) TrimSuffix() Path

TrimSuffix returns a path without the last element.

type Regex 

type Regex struct {
	Pattern string
	Options string
}

Regex represents BSON type Regex.

func (Regex) Compile added in v0.1.0 

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

Compile returns Go Regexp object.

type ScalarType added in v0.0.6 

type ScalarType interface {
	float64 | string | Binary | ObjectID | bool | time.Time | NullType | Regex | int32 | Timestamp | int64
}

ScalarType represents scalar type.

type SortType added in v0.3.0 

type SortType int8

SortType represents sort type for $sort aggregation. 

const (
	// Ascending is used for sort in ascending order.
	Ascending SortType = 1

	// Descending is used for sort in descending order.
	Descending SortType = -1
)

func (SortType) String added in v0.3.0 

func (i SortType) String() string

type Timestamp 

type Timestamp int64

Timestamp represents BSON type Timestamp.

func NewTimestamp added in v0.4.0 

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

NewTimestamp returns a timestamp from time and an increment.

func NextTimestamp added in v0.4.0 

func NextTimestamp(t time.Time) Timestamp

NextTimestamp returns a timestamp from time and an internal ops counter.

func (Timestamp) Time added in v0.4.0 

func (t Timestamp) Time() time.Time

Time returns time.Time ignoring increment.

type Type added in v0.0.6 

type Type interface {
	ScalarType | CompositeType
}

Type represents any BSON type (scalar or composite).

Source Files

View all Source files

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.