blist

README

blist

Blist is an in-memory time series binary list package for Golang.

Features

• In-memory binary list
• Store values by version number
• Delete values by version number
• Find the initial and the latest version
• Ability to insert items at any position in the list
• Find exact versions or seek to the closest version
• Select items by version number or retrieve latest value
• Sams efficiency as a btree when seeking for a specific version: O(log n) worst case
• Not as efficient as a tlist when majority of selects are for the initial or latest version: O(log n) worst case

Installation

go get github.com/surrealdb/blist

Documentation

Index

• type Find
• type Item
  • func (i *Item) Del() *Item
  • func (i *Item) Less(than btree.Item) bool
  • func (i *Item) Next() *Item
  • func (i *Item) Prev() *Item
  • func (i *Item) Set(val []byte) *Item
  • func (i *Item) Val() []byte
  • func (i *Item) Ver() uint64
• type List
  • func New() *List
  • func (l *List) Clr()
  • func (l *List) Del(ver uint64, meth Find) *Item
  • func (l *List) Exp(ver uint64, meth Find) *Item
  • func (l *List) Get(ver uint64, meth Find) *Item
  • func (l *List) Len() int
  • func (l *List) Max() *Item
  • func (l *List) Min() *Item
  • func (l *List) Put(ver uint64, val []byte) *Item
  • func (l *List) Rng(beg, end uint64, fn func(*Item) bool)
  • func (l *List) Walk(fn func(*Item) bool)

Types

type Find

type Find int8

Find determines which method is used to seek items in the list.

const (
	// Exact returns an item at a specific version from the list. If the exact
	// item does not exist in the list, then a nil value is returned.
	Exact Find = iota
	// Prev returns the nearest item in the list, where the version number is
	// less than the given version. In a time-series list, this can be used
	// to get the version that was valid before a specified time.
	Prev
	// Next returns the nearest item in the list, where the version number is
	// greater than the given version. In a time-series list, this can be used
	// to get the version that was changed after a specified time.
	Next
	// Upto returns the nearest item in the list, where the version number is
	// less than or equal to the given version. In a time-series list, this can
	// be used to get the version that was current at the specified time.
	Upto
	// Nearest returns an item nearest a specific version in the list. If there
	// is a previous version to the given version, then it will be returned,
	// otherwise it will return the next available version.
	Nearest
)

type Item

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

Item represents an item in an in-memory btree.

func (*Item) Del

func (i *Item) Del() *Item

Del deletes the item from any containing list and returns it.

func (*Item) Less

func (i *Item) Less(than btree.Item) bool

Less determines whether an item precedes another item in the list.

func (*Item) Next

func (i *Item) Next() *Item

Next returns the next item to this item in the list.

func (*Item) Prev

func (i *Item) Prev() *Item

Prev returns the previous item to this item in the list.

func (*Item) Set

func (i *Item) Set(val []byte) *Item

Set updates the value of this item in the containing list.

func (*Item) Val

func (i *Item) Val() []byte

Val returns the value of this item in the containing list.

func (*Item) Ver

func (i *Item) Ver() uint64

Ver returns the version of this item in the containing list.

type List

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

List represents an in-memory binary list.

func New

func New() *List

New creates a new list

func (*List) Clr

func (l *List) Clr()

Clr clears all of the items from the list.

func (*List) Del

func (l *List) Del(ver uint64, meth Find) *Item

Del deletes a specific item from the list, returning the previous item if it existed. If it did not exist, a nil value is returned.

func (*List) Exp

func (l *List) Exp(ver uint64, meth Find) *Item

Exp expunges all items in the list, upto and including the specified version, returning the latest version, or a nil value if not found.

func (*List) Get

func (l *List) Get(ver uint64, meth Find) *Item

Get gets a specific item from the list. If the exact item does not exist in the list, then a nil value is returned.

func (*List) Len

func (l *List) Len() int

Len returns the total number of items in the list.

func (*List) Max

func (l *List) Max() *Item

Max returns the last item in the list. In a time-series list this can be used to get the latest version.

func (*List) Min

func (l *List) Min() *Item

Min returns the first item in the list. In a time-series list this can be used to get the initial version.

func (*List) Put

func (l *List) Put(ver uint64, val []byte) *Item

Put inserts a new item into the list, ensuring that the list is sorted after insertion. If an item with the same version already exists in the list, then the value is updated.

func (*List) Rng

func (l *List) Rng(beg, end uint64, fn func(*Item) bool)

Rng iterates over the list starting at the first version, and continuing until the walk function returns true.

func (*List) Walk

func (l *List) Walk(fn func(*Item) bool)

Walk iterates over the list starting at the first version, and continuing until the walk function returns true.