document

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 24, 2021 License: MIT Imports: 13 Imported by: 2

Documentation

Overview

Package document defines types to manipulate and compare documents and values.

Index

Constants

View Source 
const (
	// ArrayValueDelim is a separator used when encoding document.Array in
	// binary reprsentation
	ArrayValueDelim = 0x1f
	// ArrayEnd is the final separator used when encoding document.Array in
	// binary reprsentation.
	ArrayEnd = 0x1e
)

Variables

View Source 
var ErrFieldNotFound = errors.New("field not found")

ErrFieldNotFound must be returned by Document implementations, when calling the GetByField method and the field wasn't found in the document.

View Source 
var (
	ErrValueNotFound = errors.New("value not found")
)

ErrValueNotFound must be returned by Array implementations, when calling the GetByIndex method and the index wasn't found in the array.

Functions

func ArrayContains 

func ArrayContains(a Array, v Value) (bool, error)

ArrayContains iterates over a and returns whether v is equal to one of its values.

func ArrayLength 

func ArrayLength(a Array) (int, error)

ArrayLength returns the length of an array.

func Fields 

func Fields(d Document) ([]string, error)

Fields returns a list of all the fields at the root of the document sorted lexicographically.

func Foobar added in v0.2.0 

func Foobar(d Document) int

func Length 

func Length(d Document) (int, error)

Length returns the length of a document.

func MapScan 

func MapScan(d Document, t interface{}) error

MapScan decodes the document into a map.

func MarshalJSON 

func MarshalJSON(d Document) ([]byte, error)

MarshalJSON encodes a document to json.

func MarshalJSONArray 

func MarshalJSONArray(a Array) ([]byte, error)

MarshalJSONArray encodes an array to json.

func Scan 

func Scan(d Document, targets ...interface{}) error

Scan each field of the document into the given variables.

func ScanDocument 

func ScanDocument(d Document, t interface{}) error

ScanDocument scans a document into dest which must be either a struct pointer, a map or a map pointer.

func ScanIterator 

func ScanIterator(it Iterator, t interface{}) error

ScanIterator scans a document iterator into a slice or fixed size array. t must be a pointer to a valid slice or array.

It t is a slice pointer and its capacity is too low, a new slice will be allocated. Otherwise, its length is set to 0 so that its content is overwritten.

If t is an array pointer, its capacity must be bigger than the length of a, otherwise an error is returned.

func ScanValue 

func ScanValue(v Value, t interface{}) error

ScanValue scans v into t.

func SliceScan 

func SliceScan(a Array, t interface{}) error

SliceScan scans a document array into a slice or fixed size array. t must be a pointer to a valid slice or array.

It t is a slice pointer and its capacity is too low, a new slice will be allocated. Otherwise, its length is set to 0 so that its content is overwritten.

If t is an array pointer, its capacity must be bigger than the length of a, otherwise an error is returned.

func StructScan 

func StructScan(d Document, t interface{}) error

StructScan scans d into t. t is expected to be a pointer to a struct.

By default, each struct field name is lowercased and the document's GetByField method is called with that name. If there is a match, the value is converted to the struct field type when possible, otherwise an error is returned. The decoding of each struct field can be customized by the format string stored under the "genji" key stored in the struct field's tag. The content of the format string is used instead of the struct field name and passed to the GetByField method.

Types

type Array 

type Array interface {
	// Iterate goes through all the values of the array and calls the given function by passing each one of them.
	// If the given function returns an error, the iteration stops.
	Iterate(fn func(i int, value Value) error) error
	// GetByIndex returns a value by index of the array.
	GetByIndex(i int) (Value, error)
}

An Array contains a set of values.

type Document 

type Document interface {
	// Iterate goes through all the fields of the document and calls the given function by passing each one of them.
	// If the given function returns an error, the iteration stops.
	Iterate(fn func(field string, value Value) error) error
	// GetByField returns a value by field name.
	// Must return ErrFieldNotFound if the field doesnt exist.
	GetByField(field string) (Value, error)
}

A Document represents a group of key value pairs.

func NewFromCSV 

func NewFromCSV(headers, columns []string) Document

NewFromCSV takes a list of headers and columns and returns a document. Each header will be assigned as the key and each corresponding column as a text value. The length of headers and columns must be the same.

func NewFromJSON 

func NewFromJSON(data []byte) Document

NewFromJSON creates a document from raw JSON data. The returned document will lazily decode the data. If data is not a valid json object, calls to Iterate or GetByField will return an error.

func NewFromMap 

func NewFromMap(m interface{}) (Document, error)

NewFromMap creates a document from a map. Due to the way maps are designed, iteration order is not guaranteed.

func NewFromStruct 

func NewFromStruct(s interface{}) (Document, error)

NewFromStruct creates a document from a struct using reflection.

type ErrUnsupportedType 

type ErrUnsupportedType struct {
	Value interface{}
	Msg   string
}

ErrUnsupportedType is used to skip struct or array fields that are not supported.

func (*ErrUnsupportedType) Error 

func (e *ErrUnsupportedType) Error() string

type FieldBuffer 

type FieldBuffer struct {
	EncodedKey []byte
	DecodedKey Value
	// contains filtered or unexported fields
}

FieldBuffer stores a group of fields in memory. It implements the Document interface.

func NewFieldBuffer 

func NewFieldBuffer() *FieldBuffer

NewFieldBuffer creates a FieldBuffer.

func (*FieldBuffer) Add 

func (fb *FieldBuffer) Add(field string, v Value) *FieldBuffer

Add a field to the buffer.

func (*FieldBuffer) Apply 

func (fb *FieldBuffer) Apply(fn func(p Path, v Value) (Value, error)) error

Apply a function to all the values of the buffer.

func (*FieldBuffer) Clone 

func (fb *FieldBuffer) Clone() *FieldBuffer

Clone the buffer.

func (*FieldBuffer) Copy 

func (fb *FieldBuffer) Copy(d Document) error

Copy deep copies every value of the document to the buffer. If a value is a document or an array, it will be stored as a FieldBuffer or ValueBuffer respectively.

func (*FieldBuffer) Delete 

func (fb *FieldBuffer) Delete(path Path) error

Delete a field from the buffer.

func (*FieldBuffer) Fields 

func (fb *FieldBuffer) Fields() []string

Fields returns a sorted list of root field names.

func (FieldBuffer) GetByField 

func (fb FieldBuffer) GetByField(field string) (Value, error)

GetByField returns a value by field. Returns an error if the field doesn't exists.

func (FieldBuffer) Iterate 

func (fb FieldBuffer) Iterate(fn func(field string, value Value) error) error

Iterate goes through all the fields of the document and calls the given function by passing each one of them. If the given function returns an error, the iteration stops.

func (*FieldBuffer) Key 

func (fb *FieldBuffer) Key() (Value, error)

Key of the document, if any.

func (FieldBuffer) Len 

func (fb FieldBuffer) Len() int

Len of the buffer.

func (*FieldBuffer) MarshalJSON 

func (fb *FieldBuffer) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*FieldBuffer) RawKey 

func (fb *FieldBuffer) RawKey() []byte

RawKey returns the encoded key of the document, if any.

func (*FieldBuffer) Replace 

func (fb *FieldBuffer) Replace(field string, v Value) error

Replace the value of the field by v.

func (*FieldBuffer) Reset 

func (fb *FieldBuffer) Reset()

Reset the buffer.

func (*FieldBuffer) ScanDocument 

func (fb *FieldBuffer) ScanDocument(d Document) error

ScanDocument copies all the fields of d to the buffer.

func (*FieldBuffer) Set 

func (fb *FieldBuffer) Set(path Path, v Value) error

Set replaces a field if it already exists or creates one if not.

func (*FieldBuffer) String 

func (fb *FieldBuffer) String() string

func (*FieldBuffer) UnmarshalJSON 

func (fb *FieldBuffer) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type Iterator 

type Iterator interface {
	// Iterate goes through all the documents and calls the given function by passing each one of them.
	// If the given function returns an error, the iteration stops.
	Iterate(fn func(d Document) error) error
}

An Iterator can iterate over documents.

type Keyer 

type Keyer interface {
	RawKey() []byte
	Key() (Value, error)
}

A Keyer returns the key identifying documents in their storage. This is usually implemented by documents read from storages.

type Path 

type Path []PathFragment

A Path represents the path to a particular value within a document.

func NewPath 

func NewPath(fragments ...string) Path

NewPath creates a path from a list of strings representing either a field name or an array index in string form.

func (Path) Clone 

func (p Path) Clone() Path

func (Path) GetValueFromArray 

func (p Path) GetValueFromArray(a Array) (Value, error)

GetValueFromArray returns the value at path p from a.

func (Path) GetValueFromDocument 

func (p Path) GetValueFromDocument(d Document) (Value, error)

GetValueFromDocument returns the value at path p from d.

func (Path) IsEqual 

func (p Path) IsEqual(other Path) bool

IsEqual returns whether other is equal to p.

func (Path) String 

func (p Path) String() string

String representation of all the fragments of the path. It implements the Stringer interface.

type PathFragment 

type PathFragment struct {
	FieldName  string
	ArrayIndex int
}

PathFragment is a fragment of a path representing either a field name or the index of an array.

type Scanner 

type Scanner interface {
	ScanDocument(Document) error
}

A Scanner can iterate over a document and scan all the fields.

type Value 

type Value struct {
	Type ValueType
	V    interface{}
}

A Value stores encoded data alongside its type.

func NewArrayValue 

func NewArrayValue(a Array) Value

NewArrayValue returns a value of type Array.

func NewBlobValue 

func NewBlobValue(x []byte) Value

NewBlobValue encodes x and returns a value.

func NewBoolValue 

func NewBoolValue(x bool) Value

NewBoolValue encodes x and returns a value.

func NewDocumentValue 

func NewDocumentValue(d Document) Value

NewDocumentValue returns a value of type Document.

func NewDoubleValue 

func NewDoubleValue(x float64) Value

NewDoubleValue encodes x and returns a value.

func NewIntegerValue 

func NewIntegerValue(x int64) Value

NewIntegerValue encodes x and returns a value whose type depends on the magnitude of x.

func NewNullValue 

func NewNullValue() Value

NewNullValue returns a Null value.

func NewTextValue 

func NewTextValue(x string) Value

NewTextValue encodes x and returns a value.

func NewValue 

func NewValue(x interface{}) (Value, error)

NewValue creates a value whose type is infered from x.

func (Value) Add 

func (v Value) Add(u Value) (res Value, err error)

Add u to v and return the result. Only numeric values and booleans can be added together.

func (Value) Append 

func (v Value) Append(buf []byte) ([]byte, error)

Append appends to buf a binary representation of v. The encoded value doesn't include type information.

func (Value) BitwiseAnd 

func (v Value) BitwiseAnd(u Value) (res Value, err error)

BitwiseAnd calculates v & u and returns the result. Only numeric values and booleans can be calculated together. If both v and u are integers, the result will be an integer.

func (Value) BitwiseOr 

func (v Value) BitwiseOr(u Value) (res Value, err error)

BitwiseOr calculates v | u and returns the result. Only numeric values and booleans can be calculated together. If both v and u are integers, the result will be an integer.

func (Value) BitwiseXor 

func (v Value) BitwiseXor(u Value) (res Value, err error)

BitwiseXor calculates v ^ u and returns the result. Only numeric values and booleans can be calculated together. If both v and u are integers, the result will be an integer.

func (Value) CastAs 

func (v Value) CastAs(t ValueType) (Value, error)

CastAs casts v as the selected type when possible.

func (Value) CastAsArray 

func (v Value) CastAsArray() (Value, error)

CastAsArray casts according to the following rules: Text: decodes a JSON array, otherwise fails. Any other type is considered an invalid cast.

func (Value) CastAsBlob 

func (v Value) CastAsBlob() (Value, error)

CastAsBlob casts according to the following rules: Text: decodes a base64 string, otherwise fails. Any other type is considered an invalid cast.

func (Value) CastAsBool 

func (v Value) CastAsBool() (Value, error)

CastAsBool casts according to the following rules: Integer: true if truthy, otherwise false. Text: uses strconv.Parsebool to determine the boolean value, it fails if the text doesn't contain a valid boolean. Any other type is considered an invalid cast.

func (Value) CastAsDocument 

func (v Value) CastAsDocument() (Value, error)

CastAsDocument casts according to the following rules: Text: decodes a JSON object, otherwise fails. Any other type is considered an invalid cast.

func (Value) CastAsDouble 

func (v Value) CastAsDouble() (Value, error)

CastAsDouble casts according to the following rules: Integer: returns a double version of the integer. Text: uses strconv.ParseFloat to determine the double value, it fails if the text doesn't contain a valid float value. Any other type is considered an invalid cast.

func (Value) CastAsInteger 

func (v Value) CastAsInteger() (Value, error)

CastAsInteger casts according to the following rules: Bool: returns 1 if true, 0 if false. Double: cuts off the decimal and remaining numbers. Text: uses strconv.ParseInt to determine the integer value, then casts it to an integer. If it fails uses strconv.ParseFloat to determine the double value, then casts it to an integer It fails if the text doesn't contain a valid float value. Any other type is considered an invalid cast.

func (Value) CastAsText 

func (v Value) CastAsText() (Value, error)

CastAsText returns a JSON representation of v. If the representation is a string, it gets unquoted.

func (Value) Div 

func (v Value) Div(u Value) (res Value, err error)

Div calculates v / u and returns the result. Only numeric values and booleans can be calculated together. If both v and u are integers, the result will be an integer.

func (Value) IsEqual 

func (v Value) IsEqual(other Value) (bool, error)

IsEqual returns true if v is equal to the given value.

func (Value) IsGreaterThan 

func (v Value) IsGreaterThan(other Value) (bool, error)

IsGreaterThan returns true if v is greather than the given value.

func (Value) IsGreaterThanOrEqual 

func (v Value) IsGreaterThanOrEqual(other Value) (bool, error)

IsGreaterThanOrEqual returns true if v is greather than or equal to the given value.

func (Value) IsLesserThan 

func (v Value) IsLesserThan(other Value) (bool, error)

IsLesserThan returns true if v is lesser than the given value.

func (Value) IsLesserThanOrEqual 

func (v Value) IsLesserThanOrEqual(other Value) (bool, error)

IsLesserThanOrEqual returns true if v is lesser than or equal to the given value.

func (Value) IsNotEqual 

func (v Value) IsNotEqual(other Value) (bool, error)

IsNotEqual returns true if v is not equal to the given value.

func (Value) IsTruthy 

func (v Value) IsTruthy() (bool, error)

IsTruthy returns whether v is not equal to the zero value of its type.

func (Value) IsZeroValue 

func (v Value) IsZeroValue() (bool, error)

IsZeroValue indicates if the value data is the zero value for the value type. This function doesn't perform any allocation.

func (Value) MarshalBinary 

func (v Value) MarshalBinary() ([]byte, error)

MarshalBinary returns a binary representation of v. The encoded value doesn't include type information.

func (Value) MarshalJSON 

func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Value) Mod 

func (v Value) Mod(u Value) (res Value, err error)

Mod calculates v / u and returns the result. Only numeric values and booleans can be calculated together. If both v and u are integers, the result will be an integer.

func (Value) Mul 

func (v Value) Mul(u Value) (res Value, err error)

Mul calculates v * u and returns the result. Only numeric values and booleans can be calculated together.

func (Value) Scan 

func (v Value) Scan(t interface{}) error

Scan v into t.

func (Value) String 

func (v Value) String() string

String returns a string representation of the value. It implements the fmt.Stringer interface.

func (Value) Sub 

func (v Value) Sub(u Value) (res Value, err error)

Sub calculates v - u and returns the result. Only numeric values and booleans can be calculated together.

type ValueBuffer 

type ValueBuffer struct {
	Values []Value
}

ValueBuffer is an array that holds values in memory.

func NewValueBuffer 

func NewValueBuffer(values ...Value) *ValueBuffer

NewValueBuffer creates a buffer of values.

func SortArray 

func SortArray(a Array) (*ValueBuffer, error)

SortArray creates a new sorted array. Types are sorted in the following ascending order:

  • NULL
  • Booleans
  • Numbers
  • Text
  • Blob
  • Arrays
  • Documents

It doesn't sort nested arrays.

func (*ValueBuffer) Append 

func (vb *ValueBuffer) Append(v Value) *ValueBuffer

Append a value to the buffer and return a new buffer.

func (*ValueBuffer) Apply 

func (vb *ValueBuffer) Apply(fn func(p Path, v Value) (Value, error)) error

Apply a function to all the values of the buffer.

func (*ValueBuffer) Copy 

func (vb *ValueBuffer) Copy(a Array) error

Copy deep copies all the values from the given array. If a value is a document or an array, it will be stored as a *FieldBuffer or *ValueBuffer respectively.

func (*ValueBuffer) GetByIndex 

func (vb *ValueBuffer) GetByIndex(i int) (Value, error)

GetByIndex returns a value set at the given index. If the index is out of range it returns an error.

func (*ValueBuffer) IsEqual 

func (vb *ValueBuffer) IsEqual(other *ValueBuffer) bool

IsEqual compares two ValueBuffer and returns true if and only if both each values and types are respectively equal.

func (*ValueBuffer) Iterate 

func (vb *ValueBuffer) Iterate(fn func(i int, value Value) error) error

Iterate over all the values of the buffer. It implements the Array interface.

func (*ValueBuffer) Len 

func (vb *ValueBuffer) Len() int

Len returns the length the of array

func (ValueBuffer) MarshalJSON 

func (vb ValueBuffer) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ValueBuffer) Replace 

func (vb *ValueBuffer) Replace(index int, v Value) error

Replace the value of the index by v.

func (*ValueBuffer) ScanArray 

func (vb *ValueBuffer) ScanArray(a Array) error

ScanArray copies all the values of a to the buffer.

func (*ValueBuffer) Types 

func (vb *ValueBuffer) Types() []ValueType

func (*ValueBuffer) UnmarshalJSON 

func (vb *ValueBuffer) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type ValueEncoder 

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

ValueEncoder encodes natural sort-ordered representations of values. Type information is encoded alongside each value.

func NewValueEncoder 

func NewValueEncoder(w io.Writer) *ValueEncoder

NewValueEncoder creates a ValueEncoder that writes to w.

func (*ValueEncoder) Encode 

func (ve *ValueEncoder) Encode(v Value) error

Encode v to the writer.

type ValueType 

type ValueType uint8

ValueType represents a value type supported by the database. 

const (
	// denote the absence of type
	AnyType ValueType = 0x0

	NullValue ValueType = 0x80

	BoolValue ValueType = 0x81

	// integer family: 0x90 to 0x9F
	IntegerValue ValueType = 0x90

	// double family: 0xA0 to 0xAF
	DoubleValue ValueType = 0xA0

	// string family: 0xC0 to 0xCF
	TextValue ValueType = 0xC0

	// blob family: 0xD0 to 0xDF
	BlobValue ValueType = 0xD0

	// array family: 0xE0 to 0xEF
	ArrayValue ValueType = 0xE0

	// document family: 0xF0 to 0xFF
	DocumentValue ValueType = 0xF0
)

List of supported value types. These types are separated by family so that when new types are introduced we don't need to modify them.

func (ValueType) IsAny 

func (t ValueType) IsAny() bool

IsAny returns whether this is type is Any or a real type

func (ValueType) IsNumber 

func (t ValueType) IsNumber() bool

IsNumber returns true if t is either an integer of a float.

func (ValueType) String 

func (t ValueType) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package encoding defines types that deal with document encoding.
 Package encoding defines types that deal with document encoding.
custom
encodingtest
Package encodingtest provides a test suite for testing codec implementations.
 Package encodingtest provides a test suite for testing codec implementations.
msgpack

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.