enums.go

// Package enum: Collection management to handle Go native enum metadata
// Provides indexed collections of enum descriptors with lookup methods
// Enables fast lookup using code value with efficient enum handling
//
// enum: Go 原生枚举元数据集合管理
// 提供带有查找方法的枚举描述符索引集合
// 支持按 code 枚举值快速检索，实现高效枚举处理
package enum

import (
	"slices"

	"github.com/yylego/enum/utils"
	"github.com/yylego/must"
	"github.com/yylego/tern/slicetern"
)

// Enums manages a collection of Enum instances with indexed lookups
// Maintains map enabling efficient lookup using code value
// Provides O(1) lookup when searching code value
// Includes a configurable default value returned when lookups miss
//
// Enums 管理 Enum 实例集合并提供索引查找
// 维护映射表以通过 code 值高效检索
// 为 code 枚举值搜索提供 O(1) 查找
// 支持在查找失败时返回可选的默认值
type Enums[C comparable, M any] struct {
	enumElements  []*Enum[C, M]     // Holds complete Enum instances in defined sequence // 存放所有 Enum 实例，并维持其定义的次序
	mapCodeToEnum map[C]*Enum[C, M] // Map from code to Enum // 从 code 到 Enum 的映射
	defaultValue  *Enum[C, M]       // Configurable default value when lookup misses // 查找失败时的可选默认值
	defaultValid  *bool             // When true, default is treated as valid in Valid() // 为 true 时，Valid() 将默认值视为有效
}

// NewEnums creates a new Enums collection from the given Enum instances
// Builds indexed map enabling efficient lookup using code value
// The first item becomes the default value if provided
// Returns a reference to the created Enums collection
//
// 从给定的 Enum 实例创建新的 Enums 集合
// 构建索引映射以通过 code 值高效查找
// 如果提供了参数，第一个项成为默认值
// 返回创建的 Enums 集合指针
func NewEnums[C comparable, M any](params ...*Enum[C, M]) *Enums[C, M] {
	res := &Enums[C, M]{
		enumElements:  slices.Clone(params), // Clone the slice to preserve the defined sequence // 克隆切片以保持枚举元素的定义次序
		mapCodeToEnum: make(map[C]*Enum[C, M], len(params)),
		defaultValue:  slicetern.V0(params), // Set first item as default if available // 如果有参数，将第一个设置为默认值
		defaultValid:  nil,
	}
	for _, one := range params {
		must.Full(one)

		// Check code collision // 检查 code 冲突
		must.Null(res.mapCodeToEnum[one.Code()])
		res.mapCodeToEnum[one.Code()] = one
	}
	return res
}

// Lookup finds an Enum using its code value
// Returns the Enum and true if found, nil and false otherwise
// Use this when you need to check existence before accessing the value
//
// 通过 code 值查找 Enum
// 找到时返回 Enum 和 true，否则返回 nil 和 false
// 当需要在访问值之前检查是否存在时使用此方法
func (c *Enums[C, M]) Lookup(code C) (*Enum[C, M], bool) {
	if res, ok := c.mapCodeToEnum[code]; ok {
		return must.Full(res), true
	}
	return nil, false
}

// Get finds an Enum using its code value
// Returns default value if no enum with the given code exists
// Panics if no default value has been configured
//
// 通过 code 值检索 Enum
// 如果不存在具有给定 code 的枚举则返回默认值
// 如果未配置默认值则会 panic
func (c *Enums[C, M]) Get(code C) *Enum[C, M] {
	if res, ok := c.mapCodeToEnum[code]; ok {
		return must.Full(res)
	}
	return c.GetDefault()
}

// MustGet finds an Enum using its code value
// Panics if no enum with the given code exists
//
// 通过 code 值检索 Enum
// 如果不存在具有给定 code 的枚举则会 panic
func (c *Enums[C, M]) MustGet(code C) *Enum[C, M] {
	return must.Nice(c.mapCodeToEnum[code])
}

// GetDefault returns the current default Enum value
// Panics if no default value has been configured
//
// 返回当前的默认 Enum 值
// 如果未配置默认值则会 panic
func (c *Enums[C, M]) GetDefault() *Enum[C, M] {
	return must.Full(c.defaultValue)
}

// List returns a slice containing each code value in the defined sequence
// Maintains the same sequence as enum values were registered
//
// 返回一个包含各 code 值的切片，次序与定义时一致
// 保持枚举值注册时的顺序
func (c *Enums[C, M]) List() []C {
	var results = make([]C, 0, len(c.enumElements))
	for _, item := range c.enumElements {
		results = append(results, item.Code())
	}
	return results
}

// ListValid returns a slice excluding the default code value
// If no default value is configured, returns each code value
//
// 返回一个切片，排除默认 code 值，其余按定义次序排列
// 如果未配置默认值，则返回所有 code 值
func (c *Enums[C, M]) ListValid() []C {
	if c.defaultValue != nil && !utils.GetPointerValue(c.defaultValid) {
		var results []C
		for _, item := range c.enumElements {
			if item.Code() != c.defaultValue.Code() {
				results = append(results, item.Code())
			}
		}
		return results
	}
	return c.List()
}