csort

README

csort

English | 中文

---

English

A high-precision, in-memory sorted set component for Go — Redis ZSet API compatible, powered by math/big.Rat for arbitrary-precision rational number scores.

✨ Features

• Arbitrary Precision — Uses big.Rat to store scores, eliminating the floating-point precision loss inherent in Redis ZSet's double (64-bit IEEE 754)
• Redis API Compatible — Drop-in replacement API mirroring Redis ZSet commands (ZADD, ZRANGE, ZRANK, ZSCORE, etc.)
• High Performance — Built on a Skip List with O(log N) insert, delete, and rank queries
• Multi-Key Support — Manages multiple independent sorted sets within a single instance
• Zero Dependencies — Only uses the Go standard library
• Thread Safe — All operations are fully concurrent-safe with fine-grained locking

📦 Installation

go get github.com/atlaschan0010/csort

Requirements: Go 1.22+

🚀 Quick Start

package main

import (
    "fmt"
    "math/big"

    csort "github.com/atlaschan0010/csort"
)

func main() {
    cache := csort.New()

    // Add members with arbitrary-precision scores
    score := new(big.Rat)
    score.SetString("12345678901234567890.12345678901234567890")
    cache.ZAdd("leaderboard", "player1", score)

    // Convenience methods for common types
    cache.ZAddString("leaderboard", "player2", "3.14159265358979323846")
    cache.ZAddFloat64("leaderboard", "player3", 100.5)
    cache.ZAddInt64("leaderboard", "player4", 42)

    // Query score (exact precision preserved)
    got, _ := cache.ZScoreString("leaderboard", "player1")
    fmt.Println("Score:", got)

    // Query rank (0-based)
    rank, _ := cache.ZRank("leaderboard", "player1")
    fmt.Println("Rank:", rank)

    // Range query with scores
    members := cache.ZRange("leaderboard", 0, -1, true)
    fmt.Println("Members:", members)
}

📖 API Reference

Add Operations

Method	Description
ZAdd(key, member string, score *big.Rat) bool	Add a member with a *big.Rat score
ZAddString(key, member, score string) (bool, error)	Add a member with a string-format score
ZAddFloat64(key, member string, score float64) bool	Add a member with a float64 score
ZAddInt64(key, member string, score int64) bool	Add a member with an int64 score
ZAddMultiple(key string, members map[string]*big.Rat) int	Batch add multiple members
ZIncrBy(key, member string, increment *big.Rat) (string, bool)	Increment a member's score

Remove Operations

Method	Description
ZRem(key, member string) bool	Remove a single member
ZRemMultiple(key string, members []string) int	Remove multiple members
ZRemRangeByRank(key string, start, stop int) int	Remove members by rank range
ZRemRangeByScore(key string, min, max *big.Rat) int	Remove members by score range
Del(keys ...string) int	Delete entire sorted set(s)
ZPopMin(key string, count int) []ScoreMember	Pop members with the lowest scores
ZPopMax(key string, count int) []ScoreMember	Pop members with the highest scores

Query Operations

Method	Description
ZScore(key, member string) (*big.Rat, bool)	Get member score as *big.Rat
ZScoreString(key, member string) (string, bool)	Get member score as string
ZRank(key, member string) (int, bool)	Get forward rank (0-based)
ZRevRank(key, member string) (int, bool)	Get reverse rank (0-based)
GetMemberRank(key, member string) (int, bool)	Get forward rank (1-based)
ZCard(key string) (int, bool)	Get number of members
ZCount(key string, min, max *big.Rat) int	Count members within score range

Neighbor Queries

Method	Description
GetPrevMember(key, member string) (string, *big.Rat, bool)	Get the previous member (lower score)
GetNextMember(key, member string) (string, *big.Rat, bool)	Get the next member (higher score)
GetPrevMemberString(key, member string) (string, string, bool)	Get previous member (score as string)
GetNextMemberString(key, member string) (string, string, bool)	Get next member (score as string)

Range Queries

Method	Description
ZRange(key string, start, stop int, withScores bool) []interface{}	Query by rank range (ascending)
ZRevRange(key string, start, stop int, withScores bool) []interface{}	Query by rank range (descending)
ZRangeByScore(key string, min, max *big.Rat, withScores bool, offset, count int) []interface{}	Query by score range (ascending)
ZRevRangeByScore(key string, max, min *big.Rat, withScores bool, offset, count int) []interface{}	Query by score range (descending)

Management Operations

Method	Description
Exists(key string) bool	Check if a key exists
Keys() []string	Get all keys
Flush()	Clear all data

📊 Use Cases

Leaderboard

cache := csort.New()

cache.ZAddFloat64("leaderboard", "alice", 100)
cache.ZAddFloat64("leaderboard", "bob", 200)
cache.ZAddFloat64("leaderboard", "charlie", 150)
cache.ZAddFloat64("leaderboard", "david", 300)
cache.ZAddFloat64("leaderboard", "eve", 250)

// Top 3 players (descending)
top3 := cache.ZRevRange("leaderboard", 0, 2, true)
for i := 0; i < len(top3); i += 2 {
    fmt.Printf("%d. %s — %s\n", i/2+1, top3[i], top3[i+1])
}

High-Precision Financial Data

cache := csort.New()

// Store prices with full decimal precision
cache.ZAddString("prices", "BTC", "67432.12345678901234567890")
cache.ZAddString("prices", "ETH", "3521.98765432109876543210")

score, _ := cache.ZScore("prices", "BTC")
// score retains all 20+ decimal places — no precision loss!

Neighbor Lookup

cache := csort.New()

cache.ZAddFloat64("ranking", "alice", 100)
cache.ZAddFloat64("ranking", "bob", 200)
cache.ZAddFloat64("ranking", "charlie", 300)

prev, prevScore, _ := cache.GetPrevMember("ranking", "bob")
next, nextScore, _ := cache.GetNextMember("ranking", "bob")
fmt.Printf("Before bob: %s (%s)\n", prev, prevScore.FloatString(0))
fmt.Printf("After bob: %s (%s)\n", next, nextScore.FloatString(0))

⚡ Benchmarks

Benchmarked on Apple M3 Max (Go 1.25, arm64):

goos: darwin
goarch: arm64
cpu: Apple M3 Max

BenchmarkZAdd-16       1,247,178       951.3 ns/op     1,945 B/op     34 allocs/op
BenchmarkZRange-16       160,768     7,450   ns/op    14,168 B/op    405 allocs/op
BenchmarkZScore-16    22,037,368        53.66 ns/op       80 B/op      3 allocs/op

Operation	Throughput	Time Complexity
ZAdd	~1,050,000 ops/sec	O(log N)
ZRange	~134,000 ops/sec	O(log N + M)
ZScore	~18,600,000 ops/sec	O(1)

🏗️ Architecture

Data Structures

• Skip List — Core sorted structure providing O(log N) insert, delete, and rank operations with span-based rank calculation
• big.Rat — Go's standard library arbitrary-precision rational number type for exact score representation
• memberMap — Hash map for O(1) member-to-node lookups (ZScore, ZRem)

Concurrency Model

CacheZSort (global RWMutex)
├── sets map[string]*ZSet
│   ├── "key1" → ZSet (per-key RWMutex)
│   │             └── SkipList (internal RWMutex)
│   ├── "key2" → ZSet (per-key RWMutex)
│   │             └── SkipList (internal RWMutex)
│   └── ...

• Two-tier locking: A global RWMutex guards the key map; each ZSet has its own RWMutex to minimize contention across keys
• Read-heavy optimization: Read operations acquire read locks, allowing concurrent reads on the same key

⚠️ Notes

1. Memory — Data is stored entirely in memory; capacity is bounded by available RAM
2. Persistence — No built-in persistence; data is lost on process restart
3. Score Output — ZScoreString / FloatString() output is formatted with a fixed number of decimal places (20 by default)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

中文

一个基于 Go 实现的高精度内存排序组件 —— 兼容 Redis ZSet API，使用 math/big.Rat 支持任意精度有理数分数。

✨ 特性

• 任意精度 — 使用 big.Rat 存储分数，解决 Redis ZSet 中 double（64 位 IEEE 754 浮点数）固有的精度丢失问题
• Redis API 兼容 — 提供与 Redis ZSet 命令一致的 API 接口（ZADD、ZRANGE、ZRANK、ZSCORE 等）
• 高性能 — 基于跳表（Skip List）实现，插入、删除、排名查询均为 O(log N)
• 多 Key 支持 — 单实例内管理多个独立的有序集合
• 零依赖 — 仅使用 Go 标准库
• 线程安全 — 所有操作均为并发安全，采用细粒度锁策略

📦 安装

go get github.com/atlaschan0010/csort

要求： Go 1.22+

🚀 快速开始

package main

import (
    "fmt"
    "math/big"

    csort "github.com/atlaschan0010/csort"
)

func main() {
    cache := csort.New()

    // 添加成员（支持任意精度小数）
    score := new(big.Rat)
    score.SetString("12345678901234567890.12345678901234567890")
    cache.ZAdd("leaderboard", "player1", score)

    // 便捷方法：字符串、float64、int64
    cache.ZAddString("leaderboard", "player2", "3.14159265358979323846")
    cache.ZAddFloat64("leaderboard", "player3", 100.5)
    cache.ZAddInt64("leaderboard", "player4", 42)

    // 查询分数（精度完全保留）
    got, _ := cache.ZScoreString("leaderboard", "player1")
    fmt.Println("分数:", got)

    // 查询排名（从 0 开始）
    rank, _ := cache.ZRank("leaderboard", "player1")
    fmt.Println("排名:", rank)

    // 范围查询（带分数）
    members := cache.ZRange("leaderboard", 0, -1, true)
    fmt.Println("成员:", members)
}

📖 API 参考

添加操作

方法	说明
ZAdd(key, member string, score *big.Rat) bool	添加成员（*big.Rat 分数）
ZAddString(key, member, score string) (bool, error)	添加成员（字符串格式分数）
ZAddFloat64(key, member string, score float64) bool	添加成员（float64 分数）
ZAddInt64(key, member string, score int64) bool	添加成员（int64 分数）
ZAddMultiple(key string, members map[string]*big.Rat) int	批量添加成员
ZIncrBy(key, member string, increment *big.Rat) (string, bool)	增加成员分数

删除操作

方法	说明
ZRem(key, member string) bool	删除单个成员
ZRemMultiple(key string, members []string) int	删除多个成员
ZRemRangeByRank(key string, start, stop int) int	按排名范围删除
ZRemRangeByScore(key string, min, max *big.Rat) int	按分数范围删除
Del(keys ...string) int	删除整个有序集合
ZPopMin(key string, count int) []ScoreMember	弹出分数最低的成员
ZPopMax(key string, count int) []ScoreMember	弹出分数最高的成员

查询操作

方法	说明
ZScore(key, member string) (*big.Rat, bool)	获取成员分数（*big.Rat）
ZScoreString(key, member string) (string, bool)	获取成员分数（字符串）
ZRank(key, member string) (int, bool)	获取正序排名（从 0 开始）
ZRevRank(key, member string) (int, bool)	获取倒序排名（从 0 开始）
GetMemberRank(key, member string) (int, bool)	获取正序排名（从 1 开始）
ZCard(key string) (int, bool)	获取成员数量
ZCount(key string, min, max *big.Rat) int	统计分数范围内成员数量

邻居查询

方法	说明
GetPrevMember(key, member string) (string, *big.Rat, bool)	获取前一位成员（分数更小）
GetNextMember(key, member string) (string, *big.Rat, bool)	获取后一位成员（分数更大）
GetPrevMemberString(key, member string) (string, string, bool)	获取前一位成员（分数为字符串）
GetNextMemberString(key, member string) (string, string, bool)	获取后一位成员（分数为字符串）

范围查询

方法	说明
ZRange(key string, start, stop int, withScores bool) []interface{}	按排名范围查询（正序）
ZRevRange(key string, start, stop int, withScores bool) []interface{}	按排名范围查询（倒序）
ZRangeByScore(key string, min, max *big.Rat, withScores bool, offset, count int) []interface{}	按分数范围查询（正序）
ZRevRangeByScore(key string, max, min *big.Rat, withScores bool, offset, count int) []interface{}	按分数范围查询（倒序）

管理操作

方法	说明
Exists(key string) bool	检查 Key 是否存在
Keys() []string	获取所有 Key
Flush()	清空所有数据

📊 使用场景

排行榜

cache := csort.New()

cache.ZAddFloat64("leaderboard", "alice", 100)
cache.ZAddFloat64("leaderboard", "bob", 200)
cache.ZAddFloat64("leaderboard", "charlie", 150)
cache.ZAddFloat64("leaderboard", "david", 300)
cache.ZAddFloat64("leaderboard", "eve", 250)

// 获取前 3 名（倒序，分数高的在前）
top3 := cache.ZRevRange("leaderboard", 0, 2, true)
for i := 0; i < len(top3); i += 2 {
    fmt.Printf("%d. %s — %s\n", i/2+1, top3[i], top3[i+1])
}

高精度金融数据

cache := csort.New()

// 存储完整小数精度的价格
cache.ZAddString("prices", "BTC", "67432.12345678901234567890")
cache.ZAddString("prices", "ETH", "3521.98765432109876543210")

score, _ := cache.ZScore("prices", "BTC")
// score 保留所有 20+ 位小数 —— 无精度丢失！

邻居查询

cache := csort.New()

cache.ZAddFloat64("ranking", "alice", 100)
cache.ZAddFloat64("ranking", "bob", 200)
cache.ZAddFloat64("ranking", "charlie", 300)

prev, prevScore, _ := cache.GetPrevMember("ranking", "bob")
next, nextScore, _ := cache.GetNextMember("ranking", "bob")
fmt.Printf("bob 前一位: %s (%s)\n", prev, prevScore.FloatString(0))
fmt.Printf("bob 后一位: %s (%s)\n", next, nextScore.FloatString(0))

⚡ 性能基准

在 Apple M3 Max 上的基准测试（Go 1.25，arm64）：

goos: darwin
goarch: arm64
cpu: Apple M3 Max

BenchmarkZAdd-16       1,247,178       951.3 ns/op     1,945 B/op     34 allocs/op
BenchmarkZRange-16       160,768     7,450   ns/op    14,168 B/op    405 allocs/op
BenchmarkZScore-16    22,037,368        53.66 ns/op       80 B/op      3 allocs/op

操作	吞吐量	时间复杂度
ZAdd	~1,050,000 次/秒	O(log N)
ZRange	~134,000 次/秒	O(log N + M)
ZScore	~18,600,000 次/秒	O(1)

🏗️ 架构设计

数据结构

• 跳表（Skip List） — 核心排序结构，提供 O(log N) 的插入、删除、排名操作，基于 span 实现排名计算
• big.Rat — Go 标准库的任意精度有理数类型，精确表示分数
• memberMap — 哈希表，O(1) 的成员到节点查找（ZScore、ZRem）

并发模型

CacheZSort（全局 RWMutex）
├── sets map[string]*ZSet
│   ├── "key1" → ZSet（独立 RWMutex）
│   │             └── SkipList（内部 RWMutex）
│   ├── "key2" → ZSet（独立 RWMutex）
│   │             └── SkipList（内部 RWMutex）
│   └── ...

• 两级锁机制：全局 RWMutex 守护 key 映射表；每个 ZSet 拥有独立的 RWMutex，最大程度减少跨 key 的锁竞争
• 读优化：读操作获取读锁，允许同一 key 上的并发读取

⚠️ 注意事项

1. 内存使用 — 数据完全存储在内存中，容量受限于可用内存
2. 持久化 — 当前版本不支持持久化，进程重启后数据丢失
3. 分数输出 — ZScoreString / FloatString() 输出时默认保留 20 位小数

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

---

License

Apache License 2.0

Documentation

Index

• Variables
• type CacheZSort
  • func New() *CacheZSort
  • func (c *CacheZSort) Del(keys ...string) int
  • func (c *CacheZSort) Exists(key string) bool
  • func (c *CacheZSort) Flush()
  • func (c *CacheZSort) GetMemberRank(key, member string) (int, bool)
  • func (c *CacheZSort) GetNextMember(key, member string) (string, *big.Rat, bool)
  • func (c *CacheZSort) GetNextMemberString(key, member string) (string, string, bool)
  • func (c *CacheZSort) GetPrevMember(key, member string) (string, *big.Rat, bool)
  • func (c *CacheZSort) GetPrevMemberString(key, member string) (string, string, bool)
  • func (c *CacheZSort) Keys() []string
  • func (c *CacheZSort) ZAdd(key, member string, score *big.Rat) bool
  • func (c *CacheZSort) ZAddFloat64(key, member string, score float64) bool
  • func (c *CacheZSort) ZAddInt64(key, member string, score int64) bool
  • func (c *CacheZSort) ZAddMultiple(key string, members map[string]*big.Rat) int
  • func (c *CacheZSort) ZAddString(key, member, scoreStr string) (bool, error)
  • func (c *CacheZSort) ZCard(key string) (int, bool)
  • func (c *CacheZSort) ZCount(key string, min, max *big.Rat) int
  • func (c *CacheZSort) ZIncrBy(key, member string, increment *big.Rat) (string, bool)
  • func (c *CacheZSort) ZPopMax(key string, count int) []ScoreMember
  • func (c *CacheZSort) ZPopMin(key string, count int) []ScoreMember
  • func (c *CacheZSort) ZRange(key string, start, stop int, withScores bool) []interface{}
  • func (c *CacheZSort) ZRangeByScore(key string, min, max *big.Rat, withScores bool, offset, count int) []interface{}
  • func (c *CacheZSort) ZRank(key, member string) (int, bool)
  • func (c *CacheZSort) ZRem(key, member string) bool
  • func (c *CacheZSort) ZRemMultiple(key string, members []string) int
  • func (c *CacheZSort) ZRemRangeByRank(key string, start, stop int) int
  • func (c *CacheZSort) ZRemRangeByScore(key string, min, max *big.Rat) int
  • func (c *CacheZSort) ZRevRange(key string, start, stop int, withScores bool) []interface{}
  • func (c *CacheZSort) ZRevRangeByScore(key string, max, min *big.Rat, withScores bool, offset, count int) []interface{}
  • func (c *CacheZSort) ZRevRank(key, member string) (int, bool)
  • func (c *CacheZSort) ZScore(key, member string) (*big.Rat, bool)
  • func (c *CacheZSort) ZScoreString(key, member string) (string, bool)
• type ScoreMember
• type SkipList
  • func NewSkipList() *SkipList
  • func (sl *SkipList) All() []ScoreMember
  • func (sl *SkipList) Clear()
  • func (sl *SkipList) CountByScore(min, max *big.Rat) int
  • func (sl *SkipList) Delete(member string, score *big.Rat) bool
  • func (sl *SkipList) DeleteByMember(member string) bool
  • func (sl *SkipList) GetByRank(rank int) (string, *big.Rat, bool)
  • func (sl *SkipList) GetNextMember(member string) (string, *big.Rat, bool)
  • func (sl *SkipList) GetPrevMember(member string) (string, *big.Rat, bool)
  • func (sl *SkipList) GetRank(member string, score *big.Rat) int
  • func (sl *SkipList) GetScore(member string) (*big.Rat, bool)
  • func (sl *SkipList) InRankRange(member string, score *big.Rat, start, stop int) bool
  • func (sl *SkipList) IncrementBy(member string, increment *big.Rat) (*big.Rat, bool)
  • func (sl *SkipList) Insert(member string, score *big.Rat)
  • func (sl *SkipList) Len() int
  • func (sl *SkipList) Range(start, stop int, reverse bool) []ScoreMember
  • func (sl *SkipList) RangeByScore(min, max *big.Rat, reverse bool) []ScoreMember
  • func (sl *SkipList) RemoveByRank(start, stop int) int
  • func (sl *SkipList) RemoveByScore(min, max *big.Rat) int
• type ZSet

Examples

• CacheZSort
• CacheZSort (HighPrecision)
• CacheZSort (Increment)
• CacheZSort (Neighbor)
• CacheZSort (RangeQuery)
• CacheZSort (ScoreRange)

Variables

var (
	ErrInvalidScore   = errors.New("invalid score format")
	ErrKeyNotFound    = errors.New("key not found")
	ErrMemberNotFound = errors.New("member not found")
)

错误定义

Types

type CacheZSort

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

CacheZSort 内存排序组件主结构

Example

package main

import (
	"fmt"
	"math/big"

	"github.com/atlaschan0010/csort"
)

func main() {
	// 创建实例
	cache := csort.New()

	// 示例 1: 添加成员（高精度小数）
	score := new(big.Rat)
	score.SetString("12345678901234567890.12345678901234567890")
	cache.ZAdd("myzset", "member1", score)

	// 示例 2: 使用字符串添加
	cache.ZAddString("myzset", "member2", "3.14159265358979323846")

	// 示例 3: 使用 float64/int64 添加
	cache.ZAddFloat64("myzset", "member3", 100.5)
	cache.ZAddInt64("myzset", "member4", 42)

	// 获取分数
	got, _ := cache.ZScoreString("myzset", "member1")
	fmt.Println("member1 score:", got[:20]+"...") // 只显示前20位

	// 获取排名（从0开始）
	rank, _ := cache.ZRank("myzset", "member1")
	fmt.Println("member1 rank:", rank)

	// 获取成员数量
	card, _ := cache.ZCard("myzset")
	fmt.Println("total members:", card)

}

Output:
member1 score: 12345678901234567890...
member1 rank: 3
total members: 4

Example (HighPrecision)

package main

import (
	"fmt"
	"math/big"

	"github.com/atlaschan0010/csort"
)

func main() {
	cache := csort.New()

	// Redis 无法精确存储的分数
	highPrecision := "0.1234567890123456789012345678901234567890"

	// CacheZSort 可以精确存储
	cache.ZAddString("test", "member", highPrecision)

	score, _ := cache.ZScore("test", "member")

	// 验证精度
	expected := new(big.Rat)
	expected.SetString(highPrecision)

	if score.Cmp(expected) == 0 {
		fmt.Println("High precision match!")
	}

}

Output:
High precision match!

Example (Increment)

package main

import (
	"fmt"
	"math/big"

	"github.com/atlaschan0010/csort"
)

func main() {
	cache := csort.New()

	// 初始化玩家分数
	cache.ZAddFloat64("game", "player1", 100)

	// 增加分数
	increment := new(big.Rat)
	increment.SetString("50")
	newScore, _ := cache.ZIncrBy("game", "player1", increment)
	fmt.Println("New score:", newScore)

	// 对不存在的成员增加（相当于添加）
	newScore2, _ := cache.ZIncrBy("game", "player2", big.NewRat(25, 1))
	fmt.Println("Player2 score:", newScore2)

}

Output:
New score: 150.00000000000000000000
Player2 score: 25.00000000000000000000

Example (Neighbor)

package main

import (
	"fmt"

	"github.com/atlaschan0010/csort"
)

func main() {
	cache := csort.New()

	// 添加排行榜数据
	cache.ZAddFloat64("ranking", "alice", 100)
	cache.ZAddFloat64("ranking", "bob", 200)
	cache.ZAddFloat64("ranking", "charlie", 300)

	// 查询 bob 的前一位
	prevMember, prevScore, _ := cache.GetPrevMember("ranking", "bob")
	fmt.Printf("Before bob: %s (score: %s)\n", prevMember, prevScore.FloatString(0))

	// 查询 bob 的后一位
	nextMember, nextScore, _ := cache.GetNextMember("ranking", "bob")
	fmt.Printf("After bob: %s (score: %s)\n", nextMember, nextScore.FloatString(0))

	// 查询 alice 的前一位（不存在）
	_, _, ok := cache.GetPrevMember("ranking", "alice")
	fmt.Printf("Before alice exists: %v\n", ok)

	// 查询 charlie 的后一位（不存在）
	_, _, ok = cache.GetNextMember("ranking", "charlie")
	fmt.Printf("After charlie exists: %v\n", ok)

}

Output:
Before bob: alice (score: 100)
After bob: charlie (score: 300)
Before alice exists: false
After charlie exists: false

Example (RangeQuery)

package main

import (
	"fmt"

	"github.com/atlaschan0010/csort"
)

func main() {
	cache := csort.New()

	// 添加一些数据
	cache.ZAddFloat64("leaderboard", "alice", 100)
	cache.ZAddFloat64("leaderboard", "bob", 200)
	cache.ZAddFloat64("leaderboard", "charlie", 150)
	cache.ZAddFloat64("leaderboard", "david", 300)
	cache.ZAddFloat64("leaderboard", "eve", 250)

	// 获取前3名（倒序，分数高的在前）
	top3 := cache.ZRevRange("leaderboard", 0, 2, true)
	fmt.Println("Top 3:")
	for i := 0; i < len(top3); i += 2 {
		member := top3[i].(string)
		score := top3[i+1].(string)
		fmt.Printf("  %d. %s: %s\n", i/2+1, member, score)
	}

	// 获取排名在 1-3 的成员（正序）
	midRange := cache.ZRange("leaderboard", 1, 3, false)
	fmt.Println("Rank 1-3:", midRange)

}

Output:
Top 3:
  1. david: 300.00000000000000000000
  2. eve: 250.00000000000000000000
  3. bob: 200.00000000000000000000
Rank 1-3: [charlie bob eve]

Example (ScoreRange)

package main

import (
	"fmt"
	"math/big"

	"github.com/atlaschan0010/csort"
)

func main() {
	cache := csort.New()

	// 添加价格数据
	cache.ZAddString("prices", "item1", "10.99")
	cache.ZAddString("prices", "item2", "25.50")
	cache.ZAddString("prices", "item3", "5.00")
	cache.ZAddString("prices", "item4", "100.00")
	cache.ZAddString("prices", "item5", "15.00")

	// 查询价格在 10-30 之间的商品
	min := new(big.Rat)
	min.SetString("10")
	max := new(big.Rat)
	max.SetString("30")

	items := cache.ZRangeByScore("prices", min, max, true, 0, -1)
	fmt.Println("Items between 10-30:")
	for i := 0; i < len(items); i += 2 {
		member := items[i].(string)
		score := items[i+1].(string)
		fmt.Printf("  %s: $%s\n", member, score)
	}

	// 统计价格在 10-30 之间的商品数量
	count := cache.ZCount("prices", min, max)
	fmt.Println("Count:", count)

}

Output:
Items between 10-30:
  item1: $10.99000000000000000000
  item5: $15.00000000000000000000
  item2: $25.50000000000000000000
Count: 3

func New

func New() *CacheZSort

New 创建新的 CacheZSort 实例

func (*CacheZSort) Del

func (c *CacheZSort) Del(keys ...string) int

Del 删除整个有序集合

func (*CacheZSort) Exists

func (c *CacheZSort) Exists(key string) bool

Exists 检查有序集合是否存在

func (*CacheZSort) Flush

func (c *CacheZSort) Flush()

Flush 清空所有有序集合

func (*CacheZSort) GetMemberRank

func (c *CacheZSort) GetMemberRank(key, member string) (int, bool)

GetMemberRank 根据 member 查询排名（从1开始） 这是 ZRank 的别名，返回 1-based 排名

func (*CacheZSort) GetNextMember

func (c *CacheZSort) GetNextMember(key, member string) (string, *big.Rat, bool)

GetNextMember 根据 member 查询后一位成员 返回: nextMember, nextScore, exists

func (*CacheZSort) GetNextMemberString

func (c *CacheZSort) GetNextMemberString(key, member string) (string, string, bool)

GetNextMemberString 根据 member 查询后一位成员（分数为字符串格式） 返回: nextMember, nextScoreStr, exists

func (*CacheZSort) GetPrevMember

func (c *CacheZSort) GetPrevMember(key, member string) (string, *big.Rat, bool)

GetPrevMember 根据 member 查询前一位成员 返回: prevMember, prevScore, exists

func (*CacheZSort) GetPrevMemberString

func (c *CacheZSort) GetPrevMemberString(key, member string) (string, string, bool)

GetPrevMemberString 根据 member 查询前一位成员（分数为字符串格式） 返回: prevMember, prevScoreStr, exists

func (*CacheZSort) Keys

func (c *CacheZSort) Keys() []string

Keys 获取所有有序集合的 key

func (*CacheZSort) ZAdd

func (c *CacheZSort) ZAdd(key, member string, score *big.Rat) bool

ZAdd 添加成员到有序集合

func (*CacheZSort) ZAddFloat64

func (c *CacheZSort) ZAddFloat64(key, member string, score float64) bool

ZAddFloat64 添加成员（分数为 float64）

func (*CacheZSort) ZAddInt64

func (c *CacheZSort) ZAddInt64(key, member string, score int64) bool

ZAddInt64 添加成员（分数为 int64）

func (*CacheZSort) ZAddMultiple

func (c *CacheZSort) ZAddMultiple(key string, members map[string]*big.Rat) int

ZAddMultiple 添加多个成员

func (*CacheZSort) ZAddString

func (c *CacheZSort) ZAddString(key, member, scoreStr string) (bool, error)

ZAddString 添加成员（分数为字符串格式）

func (*CacheZSort) ZCard

func (c *CacheZSort) ZCard(key string) (int, bool)

ZCard 获取有序集合的成员数量

func (*CacheZSort) ZCount

func (c *CacheZSort) ZCount(key string, min, max *big.Rat) int

ZCount 统计分数范围内的成员数量

func (*CacheZSort) ZIncrBy

func (c *CacheZSort) ZIncrBy(key, member string, increment *big.Rat) (string, bool)

ZIncrBy 增加成员的分数

func (*CacheZSort) ZPopMax

func (c *CacheZSort) ZPopMax(key string, count int) []ScoreMember

ZPopMax 弹出分数最高的成员

func (*CacheZSort) ZPopMin

func (c *CacheZSort) ZPopMin(key string, count int) []ScoreMember

ZPopMin 弹出分数最低的成员

func (*CacheZSort) ZRange

func (c *CacheZSort) ZRange(key string, start, stop int, withScores bool) []interface{}

ZRange 获取指定排名范围的成员（正序，从0开始，闭区间）

func (*CacheZSort) ZRangeByScore

func (c *CacheZSort) ZRangeByScore(key string, min, max *big.Rat, withScores bool, offset, count int) []interface{}

ZRangeByScore 根据分数范围获取成员（正序，闭区间）

func (*CacheZSort) ZRank

func (c *CacheZSort) ZRank(key, member string) (int, bool)

ZRank 获取成员的正序排名（从0开始）

func (*CacheZSort) ZRem

func (c *CacheZSort) ZRem(key, member string) bool

ZRem 删除成员

func (*CacheZSort) ZRemMultiple

func (c *CacheZSort) ZRemMultiple(key string, members []string) int

ZRemMultiple 删除多个成员

func (*CacheZSort) ZRemRangeByRank

func (c *CacheZSort) ZRemRangeByRank(key string, start, stop int) int

ZRemRangeByRank 删除指定排名范围的成员

func (*CacheZSort) ZRemRangeByScore

func (c *CacheZSort) ZRemRangeByScore(key string, min, max *big.Rat) int

ZRemRangeByScore 删除指定分数范围的成员

func (*CacheZSort) ZRevRange

func (c *CacheZSort) ZRevRange(key string, start, stop int, withScores bool) []interface{}

ZRevRange 获取指定排名范围的成员（倒序，从0开始，闭区间）

func (*CacheZSort) ZRevRangeByScore

func (c *CacheZSort) ZRevRangeByScore(key string, max, min *big.Rat, withScores bool, offset, count int) []interface{}

ZRevRangeByScore 根据分数范围获取成员（倒序，闭区间）

func (*CacheZSort) ZRevRank

func (c *CacheZSort) ZRevRank(key, member string) (int, bool)

ZRevRank 获取成员的倒序排名（从0开始）

func (*CacheZSort) ZScore

func (c *CacheZSort) ZScore(key, member string) (*big.Rat, bool)

ZScore 获取成员的分数

func (*CacheZSort) ZScoreString

func (c *CacheZSort) ZScoreString(key, member string) (string, bool)

ZScoreString 获取成员的分数（字符串格式）

type ScoreMember

type ScoreMember struct {
	Score  *big.Rat // 使用 big.Rat 支持任意精度小数
	Member string
}

ScoreMember 表示一个分数-成员对

type SkipList

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

SkipList 跳表实现

func NewSkipList

func NewSkipList() *SkipList

NewSkipList 创建新的跳表

func (*SkipList) All

func (sl *SkipList) All() []ScoreMember

All 获取所有成员（按分数排序）

func (*SkipList) Clear

func (sl *SkipList) Clear()

Clear 清空跳表

func (*SkipList) CountByScore

func (sl *SkipList) CountByScore(min, max *big.Rat) int

CountByScore 统计分数范围内的成员数量

func (*SkipList) Delete

func (sl *SkipList) Delete(member string, score *big.Rat) bool

Delete 删除指定成员

func (*SkipList) DeleteByMember

func (sl *SkipList) DeleteByMember(member string) bool

DeleteByMember 仅根据 member 名称删除（不需要 score）

func (*SkipList) GetByRank

func (sl *SkipList) GetByRank(rank int) (string, *big.Rat, bool)

GetByRank 根据排名获取成员 — O(log n) 通过 span 定位

func (*SkipList) GetNextMember

func (sl *SkipList) GetNextMember(member string) (string, *big.Rat, bool)

GetNextMember 获取后一位成员（分数更大，或分数相同但 member 字典序更大）

func (*SkipList) GetPrevMember

func (sl *SkipList) GetPrevMember(member string) (string, *big.Rat, bool)

GetPrevMember 获取前一位成员（分数更小，或分数相同但 member 字典序更小）

func (*SkipList) GetRank

func (sl *SkipList) GetRank(member string, score *big.Rat) int

GetRank 获取成员的排名（从1开始）— O(log n) 通过 span 计算

func (*SkipList) GetScore

func (sl *SkipList) GetScore(member string) (*big.Rat, bool)

GetScore 获取成员的分数 — O(1) 通过 memberMap

func (*SkipList) InRankRange

func (sl *SkipList) InRankRange(member string, score *big.Rat, start, stop int) bool

InRankRange 检查成员是否在指定排名范围内

func (*SkipList) IncrementBy

func (sl *SkipList) IncrementBy(member string, increment *big.Rat) (*big.Rat, bool)

IncrementBy 增加成员的分数

func (*SkipList) Insert

func (sl *SkipList) Insert(member string, score *big.Rat)

Insert 插入或更新元素

func (*SkipList) Len

func (sl *SkipList) Len() int

Len 返回元素数量

func (*SkipList) Range

func (sl *SkipList) Range(start, stop int, reverse bool) []ScoreMember

Range 获取排名范围内的成员 [start, stop] 闭区间（1-based）

func (*SkipList) RangeByScore

func (sl *SkipList) RangeByScore(min, max *big.Rat, reverse bool) []ScoreMember

RangeByScore 根据分数范围获取成员

func (*SkipList) RemoveByRank

func (sl *SkipList) RemoveByRank(start, stop int) int

RemoveByRank 删除排名范围内的所有成员 [start, stop] 1-based

func (*SkipList) RemoveByScore

func (sl *SkipList) RemoveByScore(min, max *big.Rat) int

RemoveByScore 删除分数范围内的所有成员

type ZSet

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

ZSet 表示一个有序集合