rset

Documentation

Overview

Package rset is a database-backed set repository. It provides methods to interact with sets in the database.

Index

• type DB
  • func New(rw *sql.DB, ro *sql.DB) *DB
  • func (d *DB) Add(key string, elems ...any) (int, error)
  • func (d *DB) Delete(key string, elems ...any) (int, error)
  • func (d *DB) Diff(keys ...string) ([]core.Value, error)
  • func (d *DB) DiffStore(dest string, keys ...string) (int, error)
  • func (d *DB) Exists(key, elem any) (bool, error)
  • func (d *DB) Inter(keys ...string) ([]core.Value, error)
  • func (d *DB) InterStore(dest string, keys ...string) (int, error)
  • func (d *DB) Items(key string) ([]core.Value, error)
  • func (d *DB) Len(key string) (int, error)
  • func (d *DB) Move(src, dest string, elem any) error
  • func (d *DB) Pop(key string) (core.Value, error)
  • func (d *DB) Random(key string) (core.Value, error)
  • func (d *DB) Scan(key string, cursor int, pattern string, count int) (ScanResult, error)
  • func (d *DB) Scanner(key, pattern string, pageSize int) *Scanner
  • func (d *DB) Union(keys ...string) ([]core.Value, error)
  • func (d *DB) UnionStore(dest string, keys ...string) (int, error)
• type ScanResult
• type Scanner
  • func (sc *Scanner) Err() error
  • func (sc *Scanner) Item() core.Value
  • func (sc *Scanner) Scan() bool
• type Tx
  • func NewTx(tx sqlx.Tx) *Tx
  • func (tx *Tx) Add(key string, elems ...any) (int, error)
  • func (tx *Tx) Delete(key string, elems ...any) (int, error)
  • func (tx *Tx) Diff(keys ...string) ([]core.Value, error)
  • func (tx *Tx) DiffStore(dest string, keys ...string) (int, error)
  • func (tx *Tx) Exists(key, elem any) (bool, error)
  • func (tx *Tx) Inter(keys ...string) ([]core.Value, error)
  • func (tx *Tx) InterStore(dest string, keys ...string) (int, error)
  • func (tx *Tx) Items(key string) ([]core.Value, error)
  • func (tx *Tx) Len(key string) (int, error)
  • func (tx *Tx) Move(src, dest string, elem any) error
  • func (tx *Tx) Pop(key string) (core.Value, error)
  • func (tx *Tx) Random(key string) (core.Value, error)
  • func (tx *Tx) Scan(key string, cursor int, pattern string, count int) (ScanResult, error)
  • func (tx *Tx) Scanner(key, pattern string, pageSize int) *Scanner
  • func (tx *Tx) Union(keys ...string) ([]core.Value, error)
  • func (tx *Tx) UnionStore(dest string, keys ...string) (int, error)

Types

type DB

type DB struct {
	*sqlx.DB[*Tx]
}

DB is a database-backed set repository. A set is an unordered collection of unique strings. Use the set repository to work with individual sets and their elements, and to perform set operations.

func New

func New(rw *sql.DB, ro *sql.DB) *DB

New connects to the set repository. Does not create the database schema.

func (*DB) Add

func (d *DB) Add(key string, elems ...any) (int, error)

Add adds or updates elements in a set. Returns the number of elements created (as opposed to updated). If the key does not exist, creates it. If the key exists but is not a set, returns ErrKeyType.

func (*DB) Delete

func (d *DB) Delete(key string, elems ...any) (int, error)

Delete removes elements from a set. Returns the number of elements removed. Ignores the elements that do not exist. Does nothing if the key does not exist or is not a set.

func (*DB) Diff

func (d *DB) Diff(keys ...string) ([]core.Value, error)

Diff returns the difference between the first set and the rest. The difference consists of elements that are present in the first set but not in any of the rest. If the first key does not exist or is not a set, returns an empty slice. If any of the remaining keys do not exist or are not sets, ignores them.

func (*DB) DiffStore

func (d *DB) DiffStore(dest string, keys ...string) (int, error)

DiffStore calculates the difference between the first source set and the rest, and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. If the first source key does not exist or is not a set, does nothing, except deleting the destination key if it exists. If any of the remaining source keys do not exist or are not sets, ignores them.

func (*DB) Exists

func (d *DB) Exists(key, elem any) (bool, error)

Exists reports whether the element belongs to a set. If the key does not exist or is not a set, returns false.

func (*DB) Inter

func (d *DB) Inter(keys ...string) ([]core.Value, error)

Inter returns the intersection of multiple sets. The intersection consists of elements that exist in all given sets. If any of the source keys do not exist or are not sets, returns an empty slice.

func (*DB) InterStore

func (d *DB) InterStore(dest string, keys ...string) (int, error)

InterStore intersects multiple sets and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. If any of the source keys do not exist or are not sets, does nothing, except deleting the destination key if it exists.

func (*DB) Items

func (d *DB) Items(key string) ([]core.Value, error)

Items returns all elements in a set. If the key does not exist or is not a set, returns an empty slice.

func (*DB) Len

func (d *DB) Len(key string) (int, error)

Len returns the number of elements in a set. Returns 0 if the key does not exist or is not a set.

func (*DB) Move

func (d *DB) Move(src, dest string, elem any) error

Move moves an element from one set to another. If the element does not exist in the source set, returns ErrNotFound. If the source key does not exist or is not a set, returns ErrNotFound. If the destination key does not exist, creates it. If the destination key exists but is not a set, returns ErrKeyType. If the element already exists in the destination set, only deletes it from the source set.

func (*DB) Pop

func (d *DB) Pop(key string) (core.Value, error)

Pop removes and returns a random element from a set. If the key does not exist or is not a set, returns ErrNotFound.

func (*DB) Random

func (d *DB) Random(key string) (core.Value, error)

Random returns a random element from a set. If the key does not exist or is not a set, returns ErrNotFound.

func (*DB) Scan

func (d *DB) Scan(key string, cursor int, pattern string, count int) (ScanResult, error)

Scan iterates over set elements matching pattern. Returns a slice of elements of size count based on the current state of the cursor. Returns an empty slice when there are no more items. If the key does not exist or is not a set, returns an empty slice. Supports glob-style patterns. Set count = 0 for default page size.

func (*DB) Scanner

func (d *DB) Scanner(key, pattern string, pageSize int) *Scanner

Scanner returns an iterator over set elements matching pattern. The scanner returns items one by one, fetching them from the database in pageSize batches when necessary. Stops when there are no more items or an error occurs. If the key does not exist or is not a set, stops immediately. Supports glob-style patterns. Set pageSize = 0 for default page size.

func (*DB) Union

func (d *DB) Union(keys ...string) ([]core.Value, error)

Union returns the union of multiple sets. The union consists of elements that exist in any of the given sets. Ignores the keys that do not exist or are not sets. If no keys exist, returns an empty slice.

func (*DB) UnionStore

func (d *DB) UnionStore(dest string, keys ...string) (int, error)

UnionStore unions multiple sets and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. Ignores the source keys that do not exist or are not sets. If all of the source keys do not exist or are not sets, does nothing, except deleting the destination key if it exists.

type ScanResult

type ScanResult struct {
	Cursor int
	Items  []core.Value
}

ScanResult is a result of the scan operation.

type Scanner

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

Scanner is the iterator for set items. Stops when there are no more items or an error occurs.

func (*Scanner) Err

func (sc *Scanner) Err() error

Err returns the first error encountered during iteration.

func (*Scanner) Item

func (sc *Scanner) Item() core.Value

Item returns the current set item.

func (*Scanner) Scan

func (sc *Scanner) Scan() bool

Scan advances to the next item, fetching items from db as necessary. Returns false when there are no more items or an error occurs. Returns false if the key does not exist or is not a set.

type Tx

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

Tx is a set repository transaction.

func NewTx

func NewTx(tx sqlx.Tx) *Tx

NewTx creates a set repository transaction from a generic database transaction.

func (*Tx) Add

func (tx *Tx) Add(key string, elems ...any) (int, error)

Add adds or updates elements in a set. Returns the number of elements created (as opposed to updated). If the key does not exist, creates it. If the key exists but is not a set, returns ErrKeyType.

func (*Tx) Delete

func (tx *Tx) Delete(key string, elems ...any) (int, error)

Delete removes elements from a set. Returns the number of elements removed. Ignores the elements that do not exist. Does nothing if the key does not exist or is not a set.

func (*Tx) Diff

func (tx *Tx) Diff(keys ...string) ([]core.Value, error)

Diff returns the difference between the first set and the rest. The difference consists of elements that are present in the first set but not in any of the rest. If the first key does not exist or is not a set, returns an empty slice. If any of the remaining keys do not exist or are not sets, ignores them.

func (*Tx) DiffStore

func (tx *Tx) DiffStore(dest string, keys ...string) (int, error)

DiffStore calculates the difference between the first source set and the rest, and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. If the first source key does not exist or is not a set, does nothing, except deleting the destination key if it exists. If any of the remaining source keys do not exist or are not sets, ignores them.

func (*Tx) Exists

func (tx *Tx) Exists(key, elem any) (bool, error)

Exists reports whether the element belongs to a set. If the key does not exist or is not a set, returns false.

func (*Tx) Inter

func (tx *Tx) Inter(keys ...string) ([]core.Value, error)

Inter returns the intersection of multiple sets. The intersection consists of elements that exist in all given sets. If any of the source keys do not exist or are not sets, returns an empty slice.

func (*Tx) InterStore

func (tx *Tx) InterStore(dest string, keys ...string) (int, error)

InterStore intersects multiple sets and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. If any of the source keys do not exist or are not sets, does nothing, except deleting the destination key if it exists.

func (*Tx) Items

func (tx *Tx) Items(key string) ([]core.Value, error)

Items returns all elements in a set. If the key does not exist or is not a set, returns an empty slice.

func (*Tx) Len

func (tx *Tx) Len(key string) (int, error)

Len returns the number of elements in a set. Returns 0 if the key does not exist or is not a set.

func (*Tx) Move

func (tx *Tx) Move(src, dest string, elem any) error

Move moves an element from one set to another. If the element does not exist in the source set, returns ErrNotFound. If the source key does not exist or is not a set, returns ErrNotFound. If the destination key does not exist, creates it. If the destination key exists but is not a set, returns ErrKeyType. If the element already exists in the destination set, only deletes it from the source set.

func (*Tx) Pop

func (tx *Tx) Pop(key string) (core.Value, error)

Pop removes and returns a random element from a set. If the key does not exist or is not a set, returns ErrNotFound.

func (*Tx) Random

func (tx *Tx) Random(key string) (core.Value, error)

Random returns a random element from a set. If the key does not exist or is not a set, returns ErrNotFound.

func (*Tx) Scan

func (tx *Tx) Scan(key string, cursor int, pattern string, count int) (ScanResult, error)

Scan iterates over set elements matching pattern. Returns a slice of elements of size count based on the current state of the cursor. Returns an empty slice when there are no more items. If the key does not exist or is not a set, returns an empty slice. Supports glob-style patterns. Set count = 0 for default page size.

func (*Tx) Scanner

func (tx *Tx) Scanner(key, pattern string, pageSize int) *Scanner

Scanner returns an iterator over set elements matching pattern. The scanner returns items one by one, fetching them from the database in pageSize batches when necessary. Stops when there are no more items or an error occurs. If the key does not exist or is not a set, stops immediately. Supports glob-style patterns. Set pageSize = 0 for default page size.

func (*Tx) Union

func (tx *Tx) Union(keys ...string) ([]core.Value, error)

Union returns the union of multiple sets. The union consists of elements that exist in any of the given sets. Ignores the keys that do not exist or are not sets. If no keys exist, returns an empty slice.

func (*Tx) UnionStore

func (tx *Tx) UnionStore(dest string, keys ...string) (int, error)

UnionStore unions multiple sets and stores the result in a destination set. Returns the number of elements in the destination set. If the destination key already exists, it is fully overwritten (all old elements are removed and the new ones are inserted). If the destination key already exists and is not a set, returns ErrKeyType. Ignores the source keys that do not exist or are not sets. If all of the source keys do not exist or are not sets, does nothing, except deleting the destination key if it exists.