Extend Enums with default accessors and valid list methods

- Add GetDefaultEnum() and GetDefaultPure() methods
- Add ListValidEnums() and ListValidPures() methods (excluding default)
- Fix English/Chinese comment wording in test and demo files
- Update demo1x/demo2x/demo3x with new function examples
- Update English/Chinese README with API documentation
- Add tests covering new methods and edge cases

Author: yyle88

README.md

@@ -82,6 +82,10 @@ func main() {
 	if base == protoenumstatus.StatusEnum_SUCCESS {
 		zaplog.LOG.Debug("done")
 	}
+
+	// Get default plain enum value (first item becomes default)
+	defaultPure := enums.GetDefaultPure()
+	zaplog.LOG.Debug("default", zap.String("msg", string(defaultPure)))
 }
 ```
 
@@ -137,6 +141,12 @@ func main() {
 	miss := enums.GetByName("MISS")
 	zaplog.LOG.Debug("pure", zap.String("msg", string(miss.Pure())))
 	zaplog.LOG.Debug("desc", zap.String("msg", miss.Meta().Desc()))
+
+	// List each plain enum value in defined sequence
+	pures := enums.ListPures()
+	for _, pure := range pures {
+		zaplog.LOG.Debug("list", zap.String("pure", string(pure)))
+	}
 }
 ```
 
@@ -171,9 +181,13 @@ func main() {
 | `enums.MustGetByCode(code)` | Strict lookup by code (panics if not found) | `*Enum[P, E, M]` |
 | `enums.MustGetByName(name)` | Strict lookup by name (panics if not found) | `*Enum[P, E, M]` |
 | `enums.MustGetByPure(pure)` | Strict lookup by Go native enum (panics if not found) | `*Enum[P, E, M]` |
-| `enums.ListEnums()` | Returns a slice of all protoEnum values | `[]P` |
-| `enums.ListPures()` | Returns a slice of all plainEnum values | `[]E` |
+| `enums.ListEnums()` | Returns a slice of each protoEnum value | `[]P` |
+| `enums.ListPures()` | Returns a slice of each plainEnum value | `[]E` |
+| `enums.ListValidEnums()` | Returns protoEnum values excluding default | `[]P` |
+| `enums.ListValidPures()` | Returns plainEnum values excluding default | `[]E` |
 | `enums.GetDefault()` | Get current default value (panics if unset) | `*Enum[P, E, M]` |
+| `enums.GetDefaultEnum()` | Get default protoEnum value (panics if unset) | `P` |
+| `enums.GetDefaultPure()` | Get default plainEnum value (panics if unset) | `E` |
 | `enums.SetDefault(enum)` | Set default (requires no existing default) | `void` |
 | `enums.UnsetDefault()` | Remove default (requires existing default) | `void` |
 | `enums.WithDefaultEnum(enum)` | Chain: set default by enum instance | `*Enums[P, E, M]` |
@@ -240,15 +254,22 @@ enum = statusEnums.MustGetByCode(1)
 fmt.Printf("Strict: %s\n", enum.Meta().Desc())
 ```
 
-**Listing all values:**
+**Listing values:**
 ```go
-// Get a slice of all registered proto enums
-allProtoEnums := statusEnums.ListEnums()
+// Get a slice of each registered proto enum
+protoEnums := statusEnums.ListEnums()
 // > [UNKNOWN, SUCCESS, FAILURE]
 
-// Get a slice of all registered plain Go enums
-allPlainEnums := statusEnums.ListPures()
+// Get a slice of each registered plain Go enum
+plainEnums := statusEnums.ListPures()
 // > ["unknown", "success", "failure"]
+
+// Get valid values (excluding default)
+validEnums := statusEnums.ListValidEnums()
+// > [SUCCESS, FAILURE] (UNKNOWN is default, excluded)
+
+validPures := statusEnums.ListValidPures()
+// > ["success", "failure"]
 ```
 
 ### Advanced Usage

README.zh.md

@@ -82,6 +82,10 @@ func main() {
 	if base == protoenumstatus.StatusEnum_SUCCESS {
 		zaplog.LOG.Debug("done")
 	}
+
+	// 获取默认朴素枚举值（第一个元素成为默认值）
+	defaultPure := enums.GetDefaultPure()
+	zaplog.LOG.Debug("default", zap.String("msg", string(defaultPure)))
 }
 ```
 
@@ -137,6 +141,12 @@ func main() {
 	miss := enums.GetByName("MISS")
 	zaplog.LOG.Debug("pure", zap.String("msg", string(miss.Pure())))
 	zaplog.LOG.Debug("desc", zap.String("msg", miss.Meta().Desc()))
+
+	// 按定义次序列出各朴素枚举值
+	pures := enums.ListPures()
+	for _, pure := range pures {
+		zaplog.LOG.Debug("list", zap.String("pure", string(pure)))
+	}
 }
 ```
 
@@ -171,9 +181,13 @@ func main() {
 | `enums.MustGetByCode(code)` | 严格按代码查找（找不到则 panic） | `*Enum[P, E, M]` |
 | `enums.MustGetByName(name)` | 严格按名称查找（找不到则 panic） | `*Enum[P, E, M]` |
 | `enums.MustGetByPure(pure)` | 严格按 Go 原生枚举查找（找不到则 panic） | `*Enum[P, E, M]` |
-| `enums.ListEnums()` | 返回所有 protoEnum 值的切片 | `[]P` |
-| `enums.ListPures()` | 返回所有 plainEnum 值的切片 | `[]E` |
+| `enums.ListEnums()` | 返回各 protoEnum 值的切片 | `[]P` |
+| `enums.ListPures()` | 返回各 plainEnum 值的切片 | `[]E` |
+| `enums.ListValidEnums()` | 返回排除默认值的 protoEnum 切片 | `[]P` |
+| `enums.ListValidPures()` | 返回排除默认值的 plainEnum 切片 | `[]E` |
 | `enums.GetDefault()` | 获取当前默认值（未设置则 panic） | `*Enum[P, E, M]` |
+| `enums.GetDefaultEnum()` | 获取默认 protoEnum 值（未设置则 panic） | `P` |
+| `enums.GetDefaultPure()` | 获取默认 plainEnum 值（未设置则 panic） | `E` |
 | `enums.SetDefault(enum)` | 设置默认值（要求当前无默认值） | `void` |
 | `enums.UnsetDefault()` | 移除默认值（要求当前有默认值） | `void` |
 | `enums.WithDefaultEnum(enum)` | 链式：通过枚举实例设置默认值 | `*Enums[P, E, M]` |
@@ -240,15 +254,22 @@ enum = statusEnums.MustGetByCode(1)
 fmt.Printf("严格: %s\n", enum.Meta().Desc())
 ```
 
-**列出所有值:**
+**列出枚举值:**
 ```go
-// 获取所有已注册的 proto 枚举切片
-allProtoEnums := statusEnums.ListEnums()
+// 获取各已注册 proto 枚举的切片
+protoEnums := statusEnums.ListEnums()
 // > [UNKNOWN, SUCCESS, FAILURE]
 
-// 获取所有已注册的 Go 原生枚举切片
-allPlainEnums := statusEnums.ListPures()
+// 获取各已注册 Go 原生枚举的切片
+plainEnums := statusEnums.ListPures()
 // > ["unknown", "success", "failure"]
+
+// 获取有效值（排除默认值）
+validEnums := statusEnums.ListValidEnums()
+// > [SUCCESS, FAILURE]（UNKNOWN 是默认值，被排除）
+
+validPures := statusEnums.ListValidPures()
+// > ["success", "failure"]
 ```
 
 ### 高级用法

internal/demos/demo1x/main.go

@@ -42,4 +42,9 @@ func main() {
 	if base == protoenumstatus.StatusEnum_SUCCESS {
 		zaplog.LOG.Debug("done")
 	}
+
+	// Get default plain enum value (first item becomes default)
+	// 获取默认朴素枚举值（第一个元素成为默认值）
+	defaultPure := enums.GetDefaultPure()
+	zaplog.LOG.Debug("default", zap.String("msg", string(defaultPure)))
 }

internal/demos/demo2x/main.go

@@ -51,4 +51,11 @@ func main() {
 	miss := enums.GetByName("MISS")
 	zaplog.LOG.Debug("pure", zap.String("msg", string(miss.Pure())))
 	zaplog.LOG.Debug("desc", zap.String("msg", miss.Meta().Desc()))
+
+	// List each plain enum value in defined sequence
+	// 按定义次序列出各朴素枚举值
+	pures := enums.ListPures()
+	for _, pure := range pures {
+		zaplog.LOG.Debug("list", zap.String("pure", string(pure)))
+	}
 }

internal/demos/demo3x/main.go

@@ -17,8 +17,8 @@ const (
 	StatusTypeFailure StatusType = "failure"
 )
 
-// MetaI18n represents a custom metadata type with dual-language descriptions
-// MetaI18n 代表带有双语描述的自定义元数据类型
+// MetaI18n represents a custom metadata type with English/Chinese descriptions
+// MetaI18n 代表带有中英文描述的自定义元数据类型
 type MetaI18n struct {
 	zhCN string // Chinese description // 中文描述
 	enUS string // English description // 英文描述
@@ -27,8 +27,8 @@ type MetaI18n struct {
 func (c *MetaI18n) Chinese() string { return c.zhCN }
 func (c *MetaI18n) English() string { return c.enUS }
 
-// Build enum collection with custom dual-language metadata
-// 构建带有自定义双语元数据的枚举集合
+// Build enum collection with custom English/Chinese metadata
+// 构建带有自定义中英文元数据的枚举集合
 var enums = protoenum.NewEnums(
 	protoenum.NewEnumWithMeta(protoenumstatus.StatusEnum_UNKNOWN, StatusTypeUnknown, &MetaI18n{zhCN: "未知", enUS: "Unknown"}),
 	protoenum.NewEnumWithMeta(protoenumstatus.StatusEnum_SUCCESS, StatusTypeSuccess, &MetaI18n{zhCN: "成功", enUS: "Success"}),
@@ -55,4 +55,11 @@ func main() {
 	if success.Pure() == StatusTypeSuccess {
 		zaplog.LOG.Debug("done")
 	}
+
+	// List valid plain enum values (excluding default)
+	// 列出有效的朴素枚举值（排除默认值）
+	validPures := enums.ListValidPures()
+	for _, pure := range validPures {
+		zaplog.LOG.Debug("valid", zap.String("pure", string(pure)))
+	}
 }

protoenum_test.go

@@ -103,15 +103,15 @@ func TestNewEnumWithMeta(t *testing.T) {
 		StatusTypeFailure StatusType = "failure"
 	)
 
-	// MetaI18n represents a custom metadata type with dual-language descriptions
-	// MetaI18n 代表带有双语描述的自定义元数据类型
+	// MetaI18n represents a custom metadata type with English/Chinese descriptions
+	// MetaI18n 代表带有中英文描述的自定义元数据类型
 	type MetaI18n struct {
 		zh string // Chinese description // 中文描述
 		en string // English description // 英文描述
 	}
 
-	// Create enums with custom dual-language metadata
-	// 使用自定义双语元数据创建枚举
+	// Create enums with custom English/Chinese metadata
+	// 使用自定义中英文元数据创建枚举
 	enumUnknown := protoenum.NewEnumWithMeta(protoenumstatus.StatusEnum_UNKNOWN, StatusTypeUnknown, &MetaI18n{zh: "未知", en: "Unknown"})
 	enumSuccess := protoenum.NewEnumWithMeta(protoenumstatus.StatusEnum_SUCCESS, StatusTypeSuccess, &MetaI18n{zh: "成功", en: "Success"})
 	enumFailure := protoenum.NewEnumWithMeta(protoenumstatus.StatusEnum_FAILURE, StatusTypeFailure, &MetaI18n{zh: "失败", en: "Failure"})

protoenums.go

@@ -42,7 +42,7 @@ type Enums[P ProtoEnum, E comparable, M any] struct {
 // 返回创建的 Enums 集合指针，可用于各种查找操作
 func NewEnums[P ProtoEnum, E comparable, M any](params ...*Enum[P, E, M]) *Enums[P, E, M] {
 	res := &Enums[P, E, M]{
-		enumElements: slices.Clone(params), // Create a distinct copy to maintain the sequence of all enum elements // 创建一个独立的副本以保持所有枚举元素的次序
+		enumElements: slices.Clone(params), // Clone the slice to preserve the defined sequence of enum elements // 克隆切片以保持枚举元素的定义次序
 		mapCode2Enum: make(map[int32]*Enum[P, E, M], len(params)),
 		mapName2Enum: make(map[string]*Enum[P, E, M], len(params)),
 		mapPure2Enum: make(map[E]*Enum[P, E, M], len(params)),
@@ -173,6 +173,24 @@ func (c *Enums[P, E, M]) GetDefault() *Enum[P, E, M] {
 	return must.Full(c.defaultValue)
 }
 
+// GetDefaultEnum returns the protoEnum value of the default Enum
+// Panics if no default value has been configured
+//
+// 返回默认 Enum 的 protoEnum 值
+// 如果未配置默认值则会 panic
+func (c *Enums[P, E, M]) GetDefaultEnum() P {
+	return must.Full(c.GetDefault()).Base()
+}
+
+// GetDefaultPure returns the plainEnum value of the default Enum
+// Panics if no default value has been configured
+//
+// 返回默认 Enum 的 plainEnum 值
+// 如果未配置默认值则会 panic
+func (c *Enums[P, E, M]) GetDefaultPure() E {
+	return must.Full(c.GetDefault()).Pure()
+}
+
 // 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
@@ -243,8 +261,8 @@ func (c *Enums[P, E, M]) WithUnsetDefault() *Enums[P, E, M] {
 	return c
 }
 
-// ListEnums returns a slice containing all protoEnum values in the sequence they were defined.
-// ListEnums 返回一个包含所有 protoEnum 值的切片，次序与定义时一致。
+// ListEnums returns a slice containing each protoEnum value in the defined sequence.
+// ListEnums 返回一个包含各 protoEnum 值的切片，次序与定义时一致。
 func (c *Enums[P, E, M]) ListEnums() []P {
 	var enums = make([]P, 0, len(c.enumElements))
 	for _, item := range c.enumElements {
@@ -253,12 +271,48 @@ func (c *Enums[P, E, M]) ListEnums() []P {
 	return enums
 }
 
-// ListPures returns a slice containing all plainEnum values in the sequence they were defined.
-// ListPures 返回一个包含所有 plainEnum 值的切片，次序与定义时一致。
+// ListPures returns a slice containing each plainEnum value in the defined sequence.
+// ListPures 返回一个包含各 plainEnum 值的切片，次序与定义时一致。
 func (c *Enums[P, E, M]) ListPures() []E {
 	var pures = make([]E, 0, len(c.enumElements))
 	for _, item := range c.enumElements {
 		pures = append(pures, item.Pure())
 	}
 	return pures
 }
+
+// ListValidEnums returns a slice excluding the default protoEnum value.
+// If no default value is configured, returns each protoEnum value.
+//
+// 返回一个切片，排除默认 protoEnum 值，其余按定义次序排列。
+// 如果未配置默认值，则返回所有 protoEnum 值。
+func (c *Enums[P, E, M]) ListValidEnums() []P {
+	if c.defaultValue != nil {
+		var enums []P
+		for _, item := range c.enumElements {
+			if item != c.defaultValue {
+				enums = append(enums, item.Base())
+			}
+		}
+		return enums
+	}
+	return c.ListEnums()
+}
+
+// ListValidPures returns a slice excluding the default plainEnum value.
+// If no default value is configured, returns each plainEnum value.
+//
+// 返回一个切片，排除默认 plainEnum 值，其余按定义次序排列。
+// 如果未配置默认值，则返回所有 plainEnum 值。
+func (c *Enums[P, E, M]) ListValidPures() []E {
+	if c.defaultValue != nil {
+		var pures []E
+		for _, item := range c.enumElements {
+			if item != c.defaultValue {
+				pures = append(pures, item.Pure())
+			}
+		}
+		return pures
+	}
+	return c.ListPures()
+}