zset

README

zset

Introduction

zset provides a concurrent-safety sorted set, can be used as a local replacement of Redis' zset.

The main difference to other sets is, every Value of set is associated with a score, that is used to take the sorted set ordered, from the smallest to the greatest score.

The zset has O(log(N)) time complexity when doing Add(ZADD) and Remove(ZREM) operations and O(1) time complexity when doing Contains operations.

Features

• Concurrent safe API
• Values are sorted with score
• Implementation equivalent to redis
• Fast skiplist level randomization

Comparison

Redis command	Go function
ZADD	Add
ZINCRBY	IncrBy
ZREM	Remove
ZREMRANGEBYSCORE	RemoveRangeByScore
ZREMRANGEBYRANK	RemoveRangeByRank
ZUNION	Union
ZINTER	Inter
ZINTERCARD	TODO
ZDIFF	TODO
ZRANGE	Range
ZRANGEBYSCORE	IncrBy
ZREVRANGEBYSCORE	RevRangeByScore
ZCOUNT	Count
ZREVRANGE	RevRange
ZCARD	Len
ZSCORE	Score
ZRANK	Rank
ZREVRANK	RevRank
ZPOPMIN	TODO
ZPOPMAX	TODO
ZRANDMEMBER	TODO

List of redis commands are generated from the following command:

cat redis/src/server.c | grep -o '"z.*",z.*Command' | grep -o '".*"' | cut -d '"' -f2

You may find that not all redis commands have corresponding go implementations, the reason is as follows:

Unsupported Commands

Redis' zset can operates elements in lexicographic order, which is not commonly used function, so zset does not support commands like ZREMRANGEBYLEX, ZLEXCOUNT and so on.

Redis command
ZREMRANGEBYLEX
ZRANGEBYLEX
ZREVRANGEBYLEX
ZLEXCOUNT

In redis, user accesses zset via a string key. We do not need such string key because we have variable. so the following commands are not implemented:

Redis command
ZUNIONSTORE
ZINTERSTORE
ZDIFFSTORE
ZRANGESTORE
ZMSCORE
ZSCAN

Documentation

Overview

Package zset provides a concurrent-safety sorted set, can be used as a local replacement of Redis' zset (https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/).

The main different to other sets is, every value of set is associated with a score, that is used in order to take the sorted set ordered, from the smallest to the greatest score.

The sorted set has O(log(N)) time complexity when doing Add(ZADD) and Remove(ZREM) operations and O(1) time complexity when doing Contains operations.

Index

• type Node
• type RangeOpt
• type Set
  • func Inter[K comparable](comparator bcomparator.Comparator[K], zs ...*Set[K]) *Set[K]
  • func New[K comparable](comparator bcomparator.Comparator[K]) *Set[K]
  • func Union[K comparable](comparator bcomparator.Comparator[K], zs ...*Set[K]) *Set[K]
  • func (z *Set[K]) Add(elements ...K)
  • func (z *Set[K]) AddB(score float64, value K) bool
  • func (z *Set[K]) Clear()
  • func (z *Set[K]) Contains(elements ...K) bool
  • func (z *Set[K]) ContainsB(value K) bool
  • func (z *Set[K]) Count(min, max float64) int
  • func (z *Set[K]) CountWithOpt(min, max float64, opt RangeOpt) int
  • func (z *Set[K]) Empty() bool
  • func (z *Set[K]) IncrBy(incr float64, value K) (float64, bool)
  • func (z *Set[K]) Len() int
  • func (z *Set[K]) Range(start, stop int) []Node[K]
  • func (z *Set[K]) RangeByScore(min, max float64) []Node[K]
  • func (z *Set[K]) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]
  • func (z *Set[K]) Rank(value K) int
  • func (z *Set[K]) Remove(elements ...K)
  • func (z *Set[K]) RemoveB(value K) (float64, bool)
  • func (z *Set[K]) RemoveRangeByRank(start, stop int) []Node[K]
  • func (z *Set[K]) RemoveRangeByScore(min, max float64) []Node[K]
  • func (z *Set[K]) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]
  • func (z *Set[K]) RevRange(start, stop int) []Node[K]
  • func (z *Set[K]) RevRangeByScore(max, min float64) []Node[K]
  • func (z *Set[K]) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Node[K]
  • func (z *Set[K]) RevRank(value K) int
  • func (z *Set[K]) Score(value K) (float64, bool)
  • func (z *Set[K]) Size() int
  • func (z *Set[K]) String() string
  • func (z *Set[K]) Values() []K
• type SetSafe
  • func NewSafe[K comparable](comparator bcomparator.Comparator[K]) *SetSafe[K]
  • func (s *SetSafe[K]) Add(elements ...K)
  • func (s *SetSafe[K]) AddB(score float64, value K) bool
  • func (s *SetSafe[K]) Clear()
  • func (s *SetSafe[K]) Contains(elements ...K) bool
  • func (s *SetSafe[K]) ContainsB(value K) bool
  • func (s *SetSafe[K]) Count(min, max float64) int
  • func (s *SetSafe[K]) CountWithOpt(min, max float64, opt RangeOpt) int
  • func (s *SetSafe[K]) Empty() bool
  • func (s *SetSafe[K]) IncrBy(incr float64, value K) (float64, bool)
  • func (s *SetSafe[K]) Len() int
  • func (s *SetSafe[K]) Range(start, stop int) []Node[K]
  • func (s *SetSafe[K]) RangeByScore(min, max float64) []Node[K]
  • func (s *SetSafe[K]) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]
  • func (s *SetSafe[K]) Rank(value K) int
  • func (s *SetSafe[K]) Remove(elements ...K)
  • func (s *SetSafe[K]) RemoveB(value K) (float64, bool)
  • func (s *SetSafe[K]) RemoveRangeByRank(start, stop int) []Node[K]
  • func (s *SetSafe[K]) RemoveRangeByScore(min, max float64) []Node[K]
  • func (s *SetSafe[K]) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]
  • func (s *SetSafe[K]) RevRange(start, stop int) []Node[K]
  • func (s *SetSafe[K]) RevRangeByScore(max, min float64) []Node[K]
  • func (s *SetSafe[K]) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Node[K]
  • func (s *SetSafe[K]) RevRank(value K) int
  • func (s *SetSafe[K]) Score(value K) (float64, bool)
  • func (s *SetSafe[K]) Size() int
  • func (s *SetSafe[K]) String() string
  • func (s *SetSafe[K]) Values() []K

Types

type Node

type Node[K comparable] struct {
	Value K
	Score float64
}

Node represents an element of Set.

type RangeOpt

type RangeOpt struct {
	ExcludeMin bool
	ExcludeMax bool
}

RangeOpt describes the whether the min/max is exclusive in score range.

type Set

type Set[K comparable] struct {
	// contains filtered or unexported fields
}

Set is a sorted set implementation with string value and float64 score.

func Inter

func Inter[K comparable](comparator bcomparator.Comparator[K], zs ...*Set[K]) *Set[K]

Inter returns the intersection of given sorted sets, the resulting score of a value is the sum of its scores in the sorted sets where it exists.

Inter is the replacement of INTERSTORE command of redis.

func New

func New[K comparable](comparator bcomparator.Comparator[K]) *Set[K]

New returns an empty string sorted set with int score. strings are sorted in ascending order.

func Union

func Union[K comparable](comparator bcomparator.Comparator[K], zs ...*Set[K]) *Set[K]

Union returns the union of given sorted sets, the resulting score of a value is the sum of its scores in the sorted sets where it exists.

Union is the replacement of UNIONSTORE command of redis.

func (*Set[K]) Add

func (z *Set[K]) Add(elements ...K)

func (*Set[K]) AddB

func (z *Set[K]) AddB(score float64, value K) bool

Add adds a new value or update the score of an existing value. Returns true if the value is newly created.

Add is the replacement of ZADD command of redis.

func (*Set[K]) Clear

func (z *Set[K]) Clear()

func (*Set[K]) Contains

func (z *Set[K]) Contains(elements ...K) bool

func (*Set[K]) ContainsB

func (z *Set[K]) ContainsB(value K) bool

Contains returns whether the value exists in sorted set.

func (*Set[K]) Count

func (z *Set[K]) Count(min, max float64) int

Count returns the number of elements in the sorted set at element with a score between min and max (including elements with score equal to min or max).

Count is the replacement of ZCOUNT command of redis.

func (*Set[K]) CountWithOpt

func (z *Set[K]) CountWithOpt(min, max float64, opt RangeOpt) int

func (*Set[K]) Empty

func (z *Set[K]) Empty() bool

func (*Set[K]) IncrBy

func (z *Set[K]) IncrBy(incr float64, value K) (float64, bool)

IncrBy increments the score of value in the sorted set by incr. If value does not exist in the sorted set, it is added with incr as its score (as if its previous score was zero).

IncrBy is the replacement of ZINCRBY command of redis.

func (*Set[K]) Len

func (z *Set[K]) Len() int

Len returns the length of Set.

Len is the replacement of ZCARD command of redis.

func (*Set[K]) Range

func (z *Set[K]) Range(start, stop int) []Node[K]

Range returns the specified inclusive range of elements in the sorted set by rank(index). Both start and stop are 0-based, they can also be negative numbers indicating offsets from the end of the sorted set, with -1 being the last element of the sorted set, and so on.

The returned elements are ordered by score, from lowest to highest. Elements with the same score are ordered lexicographically.

This function won't panic even when the given rank out of range.

NOTE: Please always use z.Range(0, -1) for iterating the whole sorted set. z.Range(0, z.Len()-1) has 2 method calls, the sorted set may changes during the gap of calls.

Range is the replacement of ZRANGE command of redis.

func (*Set[K]) RangeByScore

func (z *Set[K]) RangeByScore(min, max float64) []Node[K]

RangeByScore returns all the elements in the sorted set with a score between min and max (including elements with score equal to min or max). The elements are considered to be ordered from low to high scores.

RangeByScore is the replacement of ZRANGEBYSCORE command of redis.

func (*Set[K]) RangeByScoreWithOpt

func (z *Set[K]) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]

func (*Set[K]) Rank

func (z *Set[K]) Rank(value K) int

Rank returns the rank of element in the sorted set, with the scores ordered from low to high. The rank (or index) is 0-based, which means that the member with the lowest score has rank 0. -1 is returned when value is not found.

Rank is the replacement of ZRANK command of redis.

func (*Set[K]) Remove

func (z *Set[K]) Remove(elements ...K)

func (*Set[K]) RemoveB

func (z *Set[K]) RemoveB(value K) (float64, bool)

Remove removes a value from the sorted set. Returns score of the removed value and true if the node was found and deleted, otherwise returns (0.0, false).

Remove is the replacement of ZREM command of redis.

func (*Set[K]) RemoveRangeByRank

func (z *Set[K]) RemoveRangeByRank(start, stop int) []Node[K]

RemoveRangeByRank removes all elements in the sorted set stored with rank between start and stop. Both start and stop are 0-based, they can also be negative numbers indicating offsets from the end of the sorted set, with -1 being the last element of the sorted set, and so on.

RemoveRangeByRank is the replacement of ZREMRANGEBYRANK command of redis.

func (*Set[K]) RemoveRangeByScore

func (z *Set[K]) RemoveRangeByScore(min, max float64) []Node[K]

RemoveRangeByScore removes all elements in the sorted set stored with a score between min and max (including elements with score equal to min or max).

RemoveRangeByScore is the replacement of ZREMRANGEBYSCORE command of redis.

func (*Set[K]) RemoveRangeByScoreWithOpt

func (z *Set[K]) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]

func (*Set[K]) RevRange

func (z *Set[K]) RevRange(start, stop int) []Node[K]

RevRange returns the specified inclusive range of elements in the sorted set by rank(index). Both start and stop are 0-based, they can also be negative numbers indicating offsets from the end of the sorted set, with -1 being the first element of the sorted set, and so on.

The returned elements are ordered by score, from highest to lowest. Elements with the same score are ordered in reverse lexicographical ordering.

This function won't panic even when the given rank out of range.

NOTE: Please always use z.RevRange(0, -1) for iterating the whole sorted set. z.RevRange(0, z.Len()-1) has 2 method calls, the sorted set may changes during the gap of calls.

RevRange is the replacement of ZREVRANGE command of redis.

func (*Set[K]) RevRangeByScore

func (z *Set[K]) RevRangeByScore(max, min float64) []Node[K]

RevRangeByScore returns all the elements in the sorted set with a score between max and min (including elements with score equal to max or min). The elements are considered to be ordered from high to low scores.

RevRangeByScore is the replacement of ZREVRANGEBYSCORE command of redis.

func (*Set[K]) RevRangeByScoreWithOpt

func (z *Set[K]) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Node[K]

func (*Set[K]) RevRank

func (z *Set[K]) RevRank(value K) int

RevRank returns the rank of element in the sorted set, with the scores ordered from high to low. The rank (or index) is 0-based, which means that the member with the highest score has rank 0. -1 is returned when value is not found.

RevRank is the replacement of ZREVRANK command of redis.

func (*Set[K]) Score

func (z *Set[K]) Score(value K) (float64, bool)

Score returns the score of the value in the sorted set.

Score is the replacement of ZSCORE command of redis.

func (*Set[K]) Size

func (z *Set[K]) Size() int

func (*Set[K]) String

func (z *Set[K]) String() string

func (*Set[K]) Values

func (z *Set[K]) Values() []K

type SetSafe

type SetSafe[K comparable] struct {
	// contains filtered or unexported fields
}

func NewSafe

func NewSafe[K comparable](comparator bcomparator.Comparator[K]) *SetSafe[K]

func (*SetSafe[K]) Add

func (s *SetSafe[K]) Add(elements ...K)

func (*SetSafe[K]) AddB

func (s *SetSafe[K]) AddB(score float64, value K) bool

func (*SetSafe[K]) Clear

func (s *SetSafe[K]) Clear()

func (*SetSafe[K]) Contains

func (s *SetSafe[K]) Contains(elements ...K) bool

func (*SetSafe[K]) ContainsB

func (s *SetSafe[K]) ContainsB(value K) bool

func (*SetSafe[K]) Count

func (s *SetSafe[K]) Count(min, max float64) int

func (*SetSafe[K]) CountWithOpt

func (s *SetSafe[K]) CountWithOpt(min, max float64, opt RangeOpt) int

func (*SetSafe[K]) Empty

func (s *SetSafe[K]) Empty() bool

func (*SetSafe[K]) IncrBy

func (s *SetSafe[K]) IncrBy(incr float64, value K) (float64, bool)

func (*SetSafe[K]) Len

func (s *SetSafe[K]) Len() int

func (*SetSafe[K]) Range

func (s *SetSafe[K]) Range(start, stop int) []Node[K]

func (*SetSafe[K]) RangeByScore

func (s *SetSafe[K]) RangeByScore(min, max float64) []Node[K]

func (*SetSafe[K]) RangeByScoreWithOpt

func (s *SetSafe[K]) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]

func (*SetSafe[K]) Rank

func (s *SetSafe[K]) Rank(value K) int

func (*SetSafe[K]) Remove

func (s *SetSafe[K]) Remove(elements ...K)

func (*SetSafe[K]) RemoveB

func (s *SetSafe[K]) RemoveB(value K) (float64, bool)

func (*SetSafe[K]) RemoveRangeByRank

func (s *SetSafe[K]) RemoveRangeByRank(start, stop int) []Node[K]

func (*SetSafe[K]) RemoveRangeByScore

func (s *SetSafe[K]) RemoveRangeByScore(min, max float64) []Node[K]

func (*SetSafe[K]) RemoveRangeByScoreWithOpt

func (s *SetSafe[K]) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Node[K]

func (*SetSafe[K]) RevRange

func (s *SetSafe[K]) RevRange(start, stop int) []Node[K]

func (*SetSafe[K]) RevRangeByScore

func (s *SetSafe[K]) RevRangeByScore(max, min float64) []Node[K]

func (*SetSafe[K]) RevRangeByScoreWithOpt

func (s *SetSafe[K]) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Node[K]

func (*SetSafe[K]) RevRank

func (s *SetSafe[K]) RevRank(value K) int

func (*SetSafe[K]) Score

func (s *SetSafe[K]) Score(value K) (float64, bool)

func (*SetSafe[K]) Size

func (s *SetSafe[K]) Size() int

func (*SetSafe[K]) String

func (s *SetSafe[K]) String() string

func (*SetSafe[K]) Values

func (s *SetSafe[K]) Values() []K