// Author: simon (ynwdlxm@163.com)
// Date: 2025/9/15 17:00
// Desc: 字典数据结构接口定义

package dict

// Consumer 定义了用于遍历字典的消费者函数类型
// 参数 key 是字典的键
// 参数 value 是字典的值
// 返回值决定是否继续遍历，true表示继续，false表示停止
type Consumer func(key string, value any) bool

// Dict 定义了字典接口，提供了基本的键值对操作方法
type Dict interface {
	// Get 根据键获取值
	// 参数 key 要查找的键
	// 返回值 value 是与键关联的值，ok 表示键是否存在
	Get(key string) (value any, ok bool)

	// Len 返回字典中键值对的数量
	Len() int

	// Put 插入或更新键值对
	// 参数 key 键
	// 参数 value 值
	// 返回值 result 表示操作结果：1表示新增，0表示更新
	Put(key string, value any) (result int)

	// PutIfAbsent 当键不存在时才插入键值对
	// 参数 key 键
	// 参数 value 值
	// 返回值 result 表示操作结果：1表示插入成功，0表示键已存在未插入
	PutIfAbsent(key string, value any) (result int)

	// PutIfExists 当键存在时才更新键值对
	// 参数 key 键
	// 参数 value 值
	// 返回值 result 表示操作结果：1表示更新成功，0表示键不存在未更新
	PutIfExists(key string, value any) (result int)

	// Remove 根据键删除键值对
	// 参数 key 要删除的键
	// 返回值 result 表示操作结果：1表示删除成功，0表示键不存在未删除
	Remove(key string) (result int)

	// ForEach 遍历字典中的所有键值对
	// 参数 consumer 是处理每个键值对的函数，当consumer返回false时停止遍历
	ForEach(consumer Consumer)

	// Keys 返回字典中所有的键
	Keys() []string

	// RandomKeys 随机返回字典中的键，可能包含重复键
	// 参数 limit 限制返回键的数量
	RandomKeys(limit int) []string

	// RandomDistinctKeys 随机返回字典中的不重复键
	// 参数 limit 限制返回键的数量
	RandomDistinctKeys(limit int) []string

	// Clear 清空字典中的所有键值对
	Clear()
}