types

package
v1.20.1 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2024 License: Apache-2.0 Imports: 23 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 four representations in FerretDB:

  1. As they are used in "business logic" / handlers - `types` package.
  2. As they are used for logging - `fjson` package.
  3. As they are used in the wire protocol implementation - `bson` package.
  4. As they are used to store data in SQL based databases - `sjson` 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) 

Alias      types package    Description

object     *types.Document  Document
array      *types.Array     Array

Scalar types (passed by values) 

Alias      types package    Description

double     float64          64-bit binary floating point
string     string           UTF-8 string
binData    types.Binary     Binary data
objectId   types.ObjectID   Object ID
bool       bool             Boolean
date       time.Time        UTC datetime
null       types.NullType   Null
regex      types.Regex      Regular expression
int        int32            32-bit integer
timestamp  types.Timestamp  Timestamp
long       int64            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 = 16 * 1024 * 1024 // 16 MiB = 16777216 bytes

MaxDocumentLen is the maximum BSON object size.

View Source 
const MaxSafeDouble = float64(1<<53 - 1) // 52bit mantissa max value = 9007199254740991

MaxSafeDouble is the maximum double value that can be represented precisely.

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 FormatAnyValue added in v0.5.3 

func FormatAnyValue(value any) string

FormatAnyValue formats BSON value for error message output.

func Identical added in v0.9.0 

func Identical(a, b any) bool

Identical returns true if a and b are the same type and has the same value.

func IsConflictPath added in v1.5.0 

func IsConflictPath(paths []Path, path Path) error

IsConflictPath returns PathError error if adding a path creates conflict at any of paths. Returned PathError error codes:

  • ErrPathConflictOverwrite when path overwrites any paths: paths = []{{"a","b"}} path = {"a"};
  • ErrPathConflictCollision when path creates collision: paths = []{{"a"}} path = {"a","b"};

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: an ordered collection of BSON values, accessed by 0-based indexes.

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.

It panics if any of the values is not a valid BSON type.

func (*Array) Append added in v0.0.5 

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

Append appends given values to the array.

It panics if any of the values is not a valid BSON type.

func (*Array) Contains added in v0.5.1 

func (a *Array) Contains(filterValue any) bool

Contains checks if the Array contains the given value.

It panics if the filterValue is not a valid BSON type.

func (*Array) ContainsAll added in v0.5.1 

func (a *Array) ContainsAll(b *Array) bool

ContainsAll checks if Array a contains all the given values of Array b. Currently, this algorithm is O(n^2) without any performance tuning. This place can be significantly improved if a more performant algorithm is chosen.

func (*Array) DeepCopy added in v0.1.1 

func (a *Array) DeepCopy() *Array

DeepCopy returns an unfrozen deep copy of this Array.

func (*Array) FilterArrayByType added in v0.7.0 

func (a *Array) FilterArrayByType(ref any) *Array

FilterArrayByType returns a new array which contains only values of the same BSON type as ref. All numbers are treated as the same type.

func (*Array) Freeze added in v1.10.0 

func (a *Array) Freeze()

Freeze prevents array from further modifications. Any methods that would modify the array will panic.

It is safe to call Freeze multiple times.

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.

func (*Array) Iterator added in v0.8.0 

func (a *Array) Iterator() iterator.Interface[int, any]

Iterator returns an iterator for the array.

func (*Array) Len added in v0.0.5 

func (a *Array) Len() int

Len returns the number of values 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) Remove added in v0.5.3 

func (a *Array) Remove(index int)

Remove removes the value at the given index.

func (*Array) RemoveByPath added in v0.2.1 

func (a *Array) RemoveByPath(path Path)

RemoveByPath removes (cuts) value by path, doing nothing if path points to nothing.

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.

It panics if the value is not a valid BSON type.

type Binary 

type Binary struct {
	B       []byte
	Subtype BinarySubtype
}

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  // >
)

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 CompareForAggregation added in v0.9.4 

func CompareForAggregation(docValue, filterValue any) CompareResult

CompareForAggregation compares bson values. Unlike `Compare`, an array and non array would not result in Equal. This is specially used for aggregation grouping comparison.

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. This is used by update operator $max.

func CompareOrderForOperator added in v0.7.1 

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

CompareOrderForOperator detects the data type for two values and compares them. If a is an array, the array is filtered by the same type as b type. It is used by $gt, $gte, $lt and $lte comparison.

func CompareOrderForSort added in v0.7.1 

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

CompareOrderForSort detects the data type for two values and compares them. If a or b is array, the minimum element of each array is used for Ascending sort, and maximum element for Descending sort. Hence, an array is used for type comparison and value comparison. Empty Array is smaller than Null.

This is used by sort operation.

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.

type Document 

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

Document represents BSON document: an ordered collection of fields (key/value pairs where key is a string and value is any BSON value).

Data documents (that are stored in the backend) have a special RecordID property that is not a field and can't be accessed by most methods. It is used to locate the document in the backend.

func ConvertDocument 

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

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

Remove this function. TODO https://github.com/FerretDB/FerretDB/issues/260

func MakeDocument 

func MakeDocument(capacity int) *Document

MakeDocument creates an empty document with set capacity.

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 an unfrozen deep copy of this Document. RecordID is copied too.

func (*Document) FindDuplicateKey added in v0.6.2 

func (d *Document) FindDuplicateKey() (string, bool)

FindDuplicateKey returns the first duplicate key in the document and true if duplicate exists. If duplicate keys don't exist it returns empty string and false.

func (*Document) Freeze added in v1.10.0 

func (d *Document) Freeze()

Freeze prevents document from further field modifications. Any methods that would modify document fields will panic.

RecordID modification is not prevented.

It is safe to call Freeze multiple times.

func (*Document) Get added in v0.0.5 

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

Get returns a value at the given key. If the key is duplicated, it panics. It returns nil for nil Document.

The only possible error is returned for a missing key. In that case, Get returns nil for the value. The new code is encouraged to do this: 

v, _ := d.Get("key")
if v == nil { ... }

The error value will be removed in the future.

func (*Document) GetByPath added in v0.0.5 

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

GetByPath returns a value by path. If the Path has only one element, it returns the value for the given key.

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) HasByPath added in v0.5.2 

func (d *Document) HasByPath(path Path) bool

HasByPath returns true if the given path is present in the document.

func (*Document) Iterator added in v0.8.0 

func (d *Document) Iterator() iterator.Interface[string, any]

Iterator returns an iterator over the document fields.

It returns valid (done) iterator for nil Document.

func (*Document) Keys 

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

Keys returns a copy of document's keys.

If there are duplicate keys in the document, the result will have duplicate keys too.

If document or document's fields are not set (nil), it returns nil.

func (*Document) Len added in v0.0.6 

func (d *Document) Len() int

Len returns the number of fields 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.

If there are duplicate keys in the document, the last value is set in the corresponding field.

It returns nil for nil Document.

func (*Document) RecordID added in v1.12.0 

func (d *Document) RecordID() int64

RecordID returns the document's RecordID (that is 0 by default).

func (*Document) Remove 

func (d *Document) Remove(key string) any

Remove the given key and return its value, or nil if the key does not exist. If the key is duplicated, it panics.

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. If the Path has only one element, it removes the value for the given key.

func (*Document) Set 

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

Set sets the value for the given key, replacing any existing value. If the key is duplicated, it panics. If the key doesn't exist, it will be set.

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

func (*Document) SetByPath added in v0.5.2 

func (d *Document) SetByPath(path Path, value any) error

SetByPath sets value by given path. If the Path has only one element, it sets the value for the given key. If some parts of the path are missing, they will be created. The Document type will be used to create these parts. If multiple fields match the path it panics.

func (*Document) SetRecordID added in v1.12.0 

func (d *Document) SetRecordID(recordID int64)

SetRecordID sets the document's RecordID.

func (*Document) SortFieldsByKey added in v0.8.0 

func (d *Document) SortFieldsByKey()

SortFieldsByKey sorts the document fields by ascending order of the key.

func (*Document) ValidateData added in v0.6.0 

func (d *Document) ValidateData() error

ValidateData checks if the document represents a valid "data document". It places `_id` field into the fields slice 0 index. It replaces negative zero -0 with valid positive zero 0. If the document is not valid it returns *ValidationError.

func (*Document) Values added in v0.6.2 

func (d *Document) Values() []any

Values returns a copy of document's values in the same order as Keys().

If document or document's fields are not set (nil), it returns nil.

type DocumentsIterator added in v0.9.4 

type DocumentsIterator iterator.Interface[struct{}, *Document]

DocumentsIterator represents an iterator over documents (slice, query results, etc).

Key/index is not used there because it is unclear what it should be in the filter/sort/limit/skip chain, and it is not used anyway.

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 a parsed dot notation - a sequence of elements (document keys and array indexes) separated by dots.

Path's elements can't be empty, include dots or spaces.

Path should be stored and passed as a value. Its methods return new values, not modifying the receiver's state.

func NewPathFromString added in v0.3.0 

func NewPathFromString(s string) (Path, error)

NewPathFromString returns Path from a given dot notation.

It returns an error if the path is invalid.

func NewStaticPath added in v0.9.1 

func NewStaticPath(path ...string) Path

NewStaticPath returns Path from a strings slice.

It panics on invalid paths. For that reason, it should not be used with user-provided paths.

func (Path) Append added in v0.5.2 

func (p Path) Append(elem string) Path

Append returns new Path constructed from the current path and given element.

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 elements array.

func (Path) String added in v0.3.0 

func (p Path) String() string

String returns a dot notation for that path.

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 PathError added in v1.8.0 

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

PathError describes an error that could occur on path related operations.

func (*PathError) Code added in v1.8.0 

func (e *PathError) Code() PathErrorCode

Code returns the PathError code.

func (*PathError) Error added in v1.8.0 

func (e *PathError) Error() string

Error implements the error interface.

type PathErrorCode added in v1.8.0 

type PathErrorCode int

PathErrorCode represents PathError code. 

const (

	// ErrPathElementEmpty indicates that provided path contains an empty element.
	ErrPathElementEmpty PathErrorCode

	// ErrPathElementInvalid indicates that provided path contains an invalid element (other than empty).
	ErrPathElementInvalid

	// ErrPathKeyNotFound indicates that key was not found in document.
	ErrPathKeyNotFound

	// ErrPathIndexInvalid indicates that provided array index is invalid.
	ErrPathIndexInvalid

	// ErrPathIndexOutOfBound indicates that provided array index is out of bound.
	ErrPathIndexOutOfBound

	// ErrPathCannotAccess indicates that path couldn't be accessed.
	ErrPathCannotAccess

	// ErrPathCannotCreateField indicates that it's impossible to create a specific field.
	ErrPathCannotCreateField

	// ErrPathConflictOverwrite indicates a path overwrites another path.
	ErrPathConflictOverwrite

	// ErrPathConflictCollision indicates a path creates collision at another path.
	ErrPathConflictCollision
)

func (PathErrorCode) String added in v1.8.0 

func (i PathErrorCode) String() string

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 uint64

Timestamp represents BSON type Timestamp.

func NewTimestamp added in v0.4.0 

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

NewTimestamp returns the timestamp for the given time and counter values.

func NextTimestamp added in v0.4.0 

func NextTimestamp(t time.Time) Timestamp

NextTimestamp returns the next timestamp for the given time value.

func (Timestamp) Signed added in v1.12.0 

func (ts Timestamp) Signed() int64

Signed returns the timestamp as a signed value.

func (Timestamp) Time added in v0.4.0 

func (ts Timestamp) Time() time.Time

Time returns timestamp's time component.

type Type added in v0.0.6 

type Type interface {
	ScalarType | CompositeType
}

Type represents any BSON type (scalar or composite).

type ValidationError added in v0.6.0 

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

ValidationError describes an error that could occur when validating a document.

func (*ValidationError) Code added in v0.6.1 

func (e *ValidationError) Code() ValidationErrorCode

Code returns the ValidationError code.

func (*ValidationError) Error added in v0.6.0 

func (e *ValidationError) Error() string

Error implements the error interface.

type ValidationErrorCode added in v0.6.1 

type ValidationErrorCode int

ValidationErrorCode represents ValidationData error code. 

const (

	// ErrValidation indicates that document is invalid.
	ErrValidation ValidationErrorCode

	// ErrWrongIDType indicates that _id field is invalid.
	ErrWrongIDType

	// ErrIDNotFound indicates that _id field is not found.
	ErrIDNotFound
)

func (ValidationErrorCode) String added in v0.9.3 

func (i ValidationErrorCode) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package fjson provides converters to FJSON (JSON with some extensions) for built-in and `types` types.
 Package fjson provides converters to FJSON (JSON with some extensions) for built-in and `types` types.

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.