with_default.go

package enum

import "github.com/yylego/must"

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

// SetDefault sets the default Enum value to return when lookups miss
// Allows dynamic configuration of the fallback value post creation
// Panics if defaultEnum is nil, use UnsetDefault to remove the default value
//
// 设置查找失败时返回的默认 Enum 值
// 允许在创建后动态配置回退值
// 如果 defaultEnum 为 nil 则会 panic，使用 UnsetDefault 清除默认值
func (c *Enums[C, M]) SetDefault(enum *Enum[C, M]) {
	must.Null(c.defaultValue)
	// Note: use SetDefaultCode to validate against map
	// 注意：使用 SetDefaultCode 可确保值在集合中存在
	c.defaultValue = must.Full(enum)
	// Default is often treated as non-active to distinguish set from unset
	// 默认值通常无效，以区分已设置和未设置的情况
	c.defaultValid = nil
}

// SetDefaultCode sets the default using a code value
// Panics if the specified code is not found in the collection
//
// 使用 code 值设置默认值
// 如果指定的 code 不存在则会 panic
func (c *Enums[C, M]) SetDefaultCode(code C) {
	c.SetDefault(c.MustGet(code))
}

// SetDefaultValid marks the default value as active when true
// When active, Valid() includes the default
// Panics if no default value exists, panics if defaultValid has been set
//
// 标记默认值是否应被视为有效
// 当 valid 为 true 时，Valid() 包含默认值
// 如果无默认值或 defaultValid 已设置则会 panic
func (c *Enums[C, M]) SetDefaultValid(valid bool) {
	must.Full(c.defaultValue)
	must.Null(c.defaultValid)
	c.defaultValid = &valid
}

// UnsetDefault unsets the default Enum value
// Once invoked, Get() lookups panic if not found
// Panics if no default value exists at the moment
//
// 取消设置默认 Enum 值
// 调用此方法后，Get() 查找失败时会 panic
// 如果当前无默认值则会 panic
func (c *Enums[C, M]) UnsetDefault() {
	must.Full(c.defaultValue)
	c.defaultValue = nil
	c.defaultValid = nil
}

// WithDefault sets the default Enum value and returns the Enums instance
// Enables fluent chain-style configuration during initialization
// Convenient when setting defaults in package-scope variable declarations
//
// 设置默认 Enum 值并返回 Enums 实例
// 支持初始化时的流式链式配置
// 适用于在全局变量声明中设置默认值
func (c *Enums[C, M]) WithDefault(enum *Enum[C, M]) *Enums[C, M] {
	c.SetDefault(enum)
	return c
}

// WithDefaultCode sets the default using a code value and returns the Enums instance
// Convenient chain method when you know the default code value
// Panics if the specified code is not found in the collection
//
// 使用 code 值设置默认值并返回 Enums 实例
// 当你知道默认 code 值时的便捷链式方法
// 如果指定的 code 不存在则会 panic
func (c *Enums[C, M]) WithDefaultCode(code C) *Enums[C, M] {
	c.SetDefaultCode(code)
	return c
}

// WithDefaultValid marks the default as active and returns the Enums instance
// When active, Valid() includes the default
// Convenient chain method to configure default active state at initialization
//
// 标记默认值为有效并返回 Enums 实例
// 当 valid 为 true 时，Valid() 包含默认值
// 用于初始化时配置默认值有效性的便捷链式方法
func (c *Enums[C, M]) WithDefaultValid(valid bool) *Enums[C, M] {
	c.SetDefaultValid(valid)
	return c
}

// WithUnsetDefault unsets the default Enum value and returns the Enums instance
// Enables fluent chain-style configuration to remove default value
// Once invoked, Get() lookups panic if not found
//
// 取消设置默认 Enum 值并返回 Enums 实例
// 支持流式链式配置以移除默认值
// 之后 Get() 查找失败时会 panic
func (c *Enums[C, M]) WithUnsetDefault() *Enums[C, M] {
	c.UnsetDefault()
	return c
}