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 |
QuickStart
package main
import (
"fmt"
"github.com/bytedance/gopkg/collection/zset"
)
func main() {
z := zset.NewFloat64()
values := []string{"Alice", "Bob", "Zhang"}
scores := []float64{90, 89, 59.9}
for i := range values {
z.Add(scores[i], values[i])
}
s, ok := z.Score("Alice")
if ok {
fmt.Println("Alice's score is", s)
}
n := z.Count(0, 60)
fmt.Println("There are", n, "people below 60 points")
for _, n := range z.Range(0, -1) {
fmt.Println("zset range found", n.Value, n.Score)
}
}
Documentation
¶
Overview ¶
Copyright 2021 ByteDance Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
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 Float64Node
- type Float64Set
- func (z *Float64Set) Add(score float64, value string) bool
- func (z *Float64Set) Contains(value string) bool
- func (z *Float64Set) Count(min, max float64) int
- func (z *Float64Set) CountWithOpt(min, max float64, opt RangeOpt) int
- func (z *Float64Set) IncrBy(incr float64, value string) (float64, bool)
- func (z *Float64Set) Len() int
- func (z *Float64Set) Range(start, stop int) []Float64Node
- func (z *Float64Set) RangeByScore(min, max float64) []Float64Node
- func (z *Float64Set) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Float64Node
- func (z *Float64Set) Rank(value string) int
- func (z *Float64Set) Remove(value string) (float64, bool)
- func (z *Float64Set) RemoveRangeByRank(start, stop int) []Float64Node
- func (z *Float64Set) RemoveRangeByScore(min, max float64) []Float64Node
- func (z *Float64Set) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Float64Node
- func (z *Float64Set) RevRange(start, stop int) []Float64Node
- func (z *Float64Set) RevRangeByScore(max, min float64) []Float64Node
- func (z *Float64Set) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Float64Node
- func (z *Float64Set) RevRank(value string) int
- func (z *Float64Set) Score(value string) (float64, bool)
- type RangeOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Float64Node ¶
Float64Node represents an element of Float64Set.
type Float64Set ¶
type Float64Set struct {
// contains filtered or unexported fields
}
Float64Set is a sorted set implementation with string value and float64 score.
func InterFloat64 ¶
func InterFloat64(zs ...*Float64Set) *Float64Set
InterFloat64 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.
InterFloat64 is the replacement of INTERSTORE command of redis.
func NewFloat64 ¶
func NewFloat64() *Float64Set
NewFloat64 returns an empty string sorted set with int score. strings are sorted in ascending order.
func UnionFloat64 ¶
func UnionFloat64(zs ...*Float64Set) *Float64Set
UnionFloat64 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.
UnionFloat64 is the replacement of UNIONSTORE command of redis.
func (*Float64Set) Add ¶
func (z *Float64Set) Add(score float64, value string) 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 (*Float64Set) Contains ¶
func (z *Float64Set) Contains(value string) bool
Contains returns whether the value exists in sorted set.
func (*Float64Set) Count ¶
func (z *Float64Set) 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 (*Float64Set) CountWithOpt ¶
func (z *Float64Set) CountWithOpt(min, max float64, opt RangeOpt) int
func (*Float64Set) IncrBy ¶
func (z *Float64Set) IncrBy(incr float64, value string) (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 (*Float64Set) Len ¶
func (z *Float64Set) Len() int
Len returns the length of Float64Set.
Len is the replacement of ZCARD command of redis.
func (*Float64Set) Range ¶
func (z *Float64Set) Range(start, stop int) []Float64Node
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 (*Float64Set) RangeByScore ¶
func (z *Float64Set) RangeByScore(min, max float64) []Float64Node
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 (*Float64Set) RangeByScoreWithOpt ¶
func (z *Float64Set) RangeByScoreWithOpt(min, max float64, opt RangeOpt) []Float64Node
func (*Float64Set) Rank ¶
func (z *Float64Set) Rank(value string) 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 (*Float64Set) Remove ¶
func (z *Float64Set) Remove(value string) (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 (*Float64Set) RemoveRangeByRank ¶
func (z *Float64Set) RemoveRangeByRank(start, stop int) []Float64Node
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 (*Float64Set) RemoveRangeByScore ¶
func (z *Float64Set) RemoveRangeByScore(min, max float64) []Float64Node
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 (*Float64Set) RemoveRangeByScoreWithOpt ¶
func (z *Float64Set) RemoveRangeByScoreWithOpt(min, max float64, opt RangeOpt) []Float64Node
func (*Float64Set) RevRange ¶
func (z *Float64Set) RevRange(start, stop int) []Float64Node
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 (*Float64Set) RevRangeByScore ¶
func (z *Float64Set) RevRangeByScore(max, min float64) []Float64Node
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 (*Float64Set) RevRangeByScoreWithOpt ¶
func (z *Float64Set) RevRangeByScoreWithOpt(max, min float64, opt RangeOpt) []Float64Node
func (*Float64Set) RevRank ¶
func (z *Float64Set) RevRank(value string) 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.
Source Files