diff --git a/.github/images/pod.png b/.github/images/pod.png new file mode 100644 index 0000000..30a16c7 Binary files /dev/null and b/.github/images/pod.png differ diff --git a/.github/images/yc-cpu.png b/.github/images/yc-cpu.png new file mode 100644 index 0000000..65a32e1 Binary files /dev/null and b/.github/images/yc-cpu.png differ diff --git a/.github/images/yc-event.png b/.github/images/yc-event.png new file mode 100644 index 0000000..ddfa322 Binary files /dev/null and b/.github/images/yc-event.png differ diff --git a/.github/images/yc-memory.png b/.github/images/yc-memory.png new file mode 100644 index 0000000..bf73cfa Binary files /dev/null and b/.github/images/yc-memory.png differ diff --git a/.github/images/yc1.png b/.github/images/yc1.png new file mode 100644 index 0000000..30a6f35 Binary files /dev/null and b/.github/images/yc1.png differ diff --git a/.github/images/yc2.png b/.github/images/yc2.png new file mode 100644 index 0000000..aac82d9 Binary files /dev/null and b/.github/images/yc2.png differ diff --git a/README.md b/README.md index 6befa61..7d63835 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,53 @@ # Minotaur +Minotaur 是一个用于服务端开发的支持库，其中采用了大量泛型设计，主要被用于游戏服务器开发，但由于拥有大量通用的功能，也常被用于 WEB 开发。 +*** + [![Go doc](https://img.shields.io/badge/go.dev-reference-brightgreen?logo=go&logoColor=white&style=flat)](https://pkg.go.dev/github.com/kercylan98/minotaur) -![](https://img.shields.io/badge/Email-kercylan@gmail.com-green.svg?style=flat) -![](https://komarev.com/ghpvc/?username=kercylan98) +![license](https://img.shields.io/github/license/kercylan98/minotaur) -Minotaur 是一个基于 Golang 1.20 编写的服务端开发支持库，其中采用了大量泛型设计，主要被用于游戏服务器开发，但由于拥有大量通用的功能，也常被用于 WEB 开发。 +![go version](https://img.shields.io/github/go-mod/go-version/kercylan98/minotaur?logo=go&style=flat) +![tag](https://img.shields.io/github/v/tag/kercylan98/minotaur?logo=github&style=flat) +![views](https://komarev.com/ghpvc/?username=kercylan98&color=blue&style=flat) + +![email](https://img.shields.io/badge/Email-kercylan@gmail.com-green.svg?style=flat&logo=gmail&link=mailto:kercylan@gmail.com) +![qq-group](https://img.shields.io/badge/QQ%20Group-758219443-green.svg?style=flat&logo=tencent-qq&link=https://qm.qq.com/cgi-bin/qm/qr?k=WzRWJIDLzuJbH6-VjdFiTCd1_qA_Ug-D&jump_from=webapi&authKey=ktLEw3XyY9yO+i9rPbI6Fk0UA0uEhACcUidOFdblaiToZtbHcXyU7sFb31FEc9JJ&noverify=0) +![telegram](https://img.shields.io/badge/Telegram-ziv__siren-green.svg?style=flat&logo=telegram&link=https://telegram.me/ziv_siren) + +> - 这是支持快速搭建多功能游戏服务器及 HTTP 服务器的 `Golang` 服务端框架； +> - 网络传输基于 [`gorilla/websocket`](https://github.com/gorilla/websocket)、[`gin-gonic/gin`](https://github.com/gin-gonic/gin)、[`grpc/grpc-go`](https://github.com/grpc/grpc-go)、[`panjf2000/gnet`](https://github.com/panjf2000/gnet)、[`xtaci/kcp-go`](https://github.com/xtaci/kcp-go) 构建； +> - 该项目的目标是提供一个简单、高效、可扩展的游戏服务器框架，让开发者可以专注于游戏逻辑的开发，而不用花费大量时间在网络传输、配置导表、日志、监控等基础功能的开发上； + +*** +在 Minotaur 中不包括任何跨服实现，但支持基于多级路由器快速实现跨服功能。推荐使用 [`NATS.io`](https://nats.io/) 作为跨服消息中间件。 + - 目前已实践的弹幕游戏项目以 `NATS.io` 作为消息队列，实现了跨服、埋点日志收集等功能，部署在 `Kubernetes` 集群中； + - 该项目客户端与服务端采用 `WebSocket` 进行通讯，服务端暴露 `HTTP` 接口接收互动数据消息回调，通过负载均衡器进入 `Kubernetes` 集群中的 `Minotaur` 服务，最终通过 `NATS.io` 消息队列转发至对应所在的 `Pod` 中进行处理； + +
+关于 Pod 配置参数及非极限压测数据 + +> 本次压测 `Pod` 扩容数量为 1，但由于压测连接是最开始就建立好的，所以该扩容的 `Pod` 并没有接受到压力。 +> 理论上来说该 `Pod` 也应该接受 `HTTP` 回调压力，实测过程中，这个扩容的 `Pod` 没有接受到任何压力 + +**Pod 配置参数** + +![pod](.github/images/pod.png) + +**压测结果** + +![压测数据](.github/images/yc1.png) +![压测数据](.github/images/yc2.png) + +**监控数据** + +![事件](./.github/images/yc-event.png) +![CPU](./.github/images/yc-cpu.png) +![内存](./.github/images/yc-memory.png) + +
+ +*** ## 特色内容 ```mermaid diff --git a/configuration/README.md b/configuration/README.md index d3c23cc..a913c41 100644 --- a/configuration/README.md +++ b/configuration/README.md @@ -29,8 +29,8 @@ configuration 基于配置导表功能实现的配置加载及刷新功能 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[RefreshEventHandle](#refresheventhandle)|配置刷新事件处理函数 -|`INTERFACE`|[Loader](#loader)|配置加载器 +|`STRUCT`|[RefreshEventHandle](#struct_RefreshEventHandle)|配置刷新事件处理函数 +|`INTERFACE`|[Loader](#struct_Loader)|配置加载器 @@ -75,11 +75,13 @@ configuration 基于配置导表功能实现的配置加载及刷新功能 *** + ### RefreshEventHandle `STRUCT` 配置刷新事件处理函数 ```go type RefreshEventHandle func() ``` + ### Loader `INTERFACE` 配置加载器 ```go diff --git a/game/activity/README.md b/game/activity/README.md index ec9848b..3156ecc 100644 --- a/game/activity/README.md +++ b/game/activity/README.md @@ -43,17 +43,17 @@ activity 活动状态管理 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Activity](#activity)|活动描述 -|`STRUCT`|[Controller](#controller)|活动控制器 -|`INTERFACE`|[BasicActivityController](#basicactivitycontroller)|暂无描述... -|`INTERFACE`|[NoneDataActivityController](#nonedataactivitycontroller)|无数据活动控制器 -|`INTERFACE`|[GlobalDataActivityController](#globaldataactivitycontroller)|全局数据活动控制器 -|`INTERFACE`|[EntityDataActivityController](#entitydataactivitycontroller)|实体数据活动控制器 -|`INTERFACE`|[GlobalAndEntityDataActivityController](#globalandentitydataactivitycontroller)|全局数据和实体数据活动控制器 -|`STRUCT`|[DataMeta](#datameta)|全局活动数据 -|`STRUCT`|[EntityDataMeta](#entitydatameta)|活动实体数据 -|`STRUCT`|[UpcomingEventHandler](#upcomingeventhandler)|暂无描述... -|`STRUCT`|[Options](#options)|活动选项 +|`STRUCT`|[Activity](#struct_Activity)|活动描述 +|`STRUCT`|[Controller](#struct_Controller)|活动控制器 +|`INTERFACE`|[BasicActivityController](#struct_BasicActivityController)|暂无描述... +|`INTERFACE`|[NoneDataActivityController](#struct_NoneDataActivityController)|无数据活动控制器 +|`INTERFACE`|[GlobalDataActivityController](#struct_GlobalDataActivityController)|全局数据活动控制器 +|`INTERFACE`|[EntityDataActivityController](#struct_EntityDataActivityController)|实体数据活动控制器 +|`INTERFACE`|[GlobalAndEntityDataActivityController](#struct_GlobalAndEntityDataActivityController)|全局数据和实体数据活动控制器 +|`STRUCT`|[DataMeta](#struct_DataMeta)|全局活动数据 +|`STRUCT`|[EntityDataMeta](#struct_EntityDataMeta)|活动实体数据 +|`STRUCT`|[UpcomingEventHandler](#struct_UpcomingEventHandler)|暂无描述... +|`STRUCT`|[Options](#struct_Options)|活动选项 @@ -75,97 +75,98 @@ activity 活动状态管理 > 加载所有活动实体数据 *** -#### func LoadOrRefreshActivity(activityType Type, activityId ID, options ...*Options) error +#### func LoadOrRefreshActivity\[Type generic.Basic, ID generic.Basic\](activityType Type, activityId ID, options ...*Options) error > 加载或刷新活动 > - 通常在活动配置刷新时候将活动通过该方法注册或刷新 *** -#### func DefineNoneDataActivity(activityType Type) NoneDataActivityController[Type, ID, *none, none, *none] +#### func DefineNoneDataActivity\[Type generic.Basic, ID generic.Basic\](activityType Type) NoneDataActivityController[Type, ID, *none, none, *none] > 声明无数据的活动类型 *** -#### func DefineGlobalDataActivity(activityType Type) GlobalDataActivityController[Type, ID, Data, none, *none] +#### func DefineGlobalDataActivity\[Type generic.Basic, ID generic.Basic, Data any\](activityType Type) GlobalDataActivityController[Type, ID, Data, none, *none] > 声明拥有全局数据的活动类型 *** -#### func DefineEntityDataActivity(activityType Type) EntityDataActivityController[Type, ID, *none, EntityID, EntityData] +#### func DefineEntityDataActivity\[Type generic.Basic, ID generic.Basic, EntityID generic.Basic, EntityData any\](activityType Type) EntityDataActivityController[Type, ID, *none, EntityID, EntityData] > 声明拥有实体数据的活动类型 *** -#### func DefineGlobalAndEntityDataActivity(activityType Type) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData] +#### func DefineGlobalAndEntityDataActivity\[Type generic.Basic, ID generic.Basic, Data any, EntityID generic.Basic, EntityData any\](activityType Type) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData] > 声明拥有全局数据和实体数据的活动类型 *** -#### func RegUpcomingEvent(activityType Type, handler UpcomingEventHandler[ID], priority ...int) +#### func RegUpcomingEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler UpcomingEventHandler[ID], priority ...int) > 注册即将开始的活动事件处理器 *** -#### func OnUpcomingEvent(activity *Activity[Type, ID]) +#### func OnUpcomingEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 即将开始的活动事件 *** -#### func RegStartedEvent(activityType Type, handler StartedEventHandler[ID], priority ...int) +#### func RegStartedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler StartedEventHandler[ID], priority ...int) > 注册活动开始事件处理器 *** -#### func OnStartedEvent(activity *Activity[Type, ID]) +#### func OnStartedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 活动开始事件 *** -#### func RegEndedEvent(activityType Type, handler EndedEventHandler[ID], priority ...int) +#### func RegEndedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler EndedEventHandler[ID], priority ...int) > 注册活动结束事件处理器 *** -#### func OnEndedEvent(activity *Activity[Type, ID]) +#### func OnEndedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 活动结束事件 *** -#### func RegExtendedShowStartedEvent(activityType Type, handler ExtendedShowStartedEventHandler[ID], priority ...int) +#### func RegExtendedShowStartedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler ExtendedShowStartedEventHandler[ID], priority ...int) > 注册活动结束后延长展示开始事件处理器 *** -#### func OnExtendedShowStartedEvent(activity *Activity[Type, ID]) +#### func OnExtendedShowStartedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 活动结束后延长展示开始事件 *** -#### func RegExtendedShowEndedEvent(activityType Type, handler ExtendedShowEndedEventHandler[ID], priority ...int) +#### func RegExtendedShowEndedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler ExtendedShowEndedEventHandler[ID], priority ...int) > 注册活动结束后延长展示结束事件处理器 *** -#### func OnExtendedShowEndedEvent(activity *Activity[Type, ID]) +#### func OnExtendedShowEndedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 活动结束后延长展示结束事件 *** -#### func RegNewDayEvent(activityType Type, handler NewDayEventHandler[ID], priority ...int) +#### func RegNewDayEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler NewDayEventHandler[ID], priority ...int) > 注册新的一天事件处理器 *** -#### func OnNewDayEvent(activity *Activity[Type, ID]) +#### func OnNewDayEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID]) > 新的一天事件 *** -#### func NewOptions() *Options +#### func NewOptions() *Options > 创建活动选项 *** + ### Activity `STRUCT` 活动描述 ```go @@ -185,6 +186,7 @@ type Activity[Type generic.Basic, ID generic.Basic] struct { initializeData func() } ``` + ### Controller `STRUCT` 活动控制器 ```go @@ -199,6 +201,63 @@ type Controller[Type generic.Basic, ID generic.Basic, Data any, EntityID generic mutex sync.RWMutex } ``` + + +#### func (*Controller) GetGlobalData(activityId ID) Data +> 获取特定活动全局数据 + +*** + + +#### func (*Controller) GetEntityData(activityId ID, entityId EntityID) EntityData +> 获取特定活动实体数据 + +*** + + +#### func (*Controller) IsOpen(activityId ID) bool +> 活动是否开启 + +*** + + +#### func (*Controller) IsShow(activityId ID) bool +> 活动是否展示 + +*** + + +#### func (*Controller) IsOpenOrShow(activityId ID) bool +> 活动是否开启或展示 + +*** + + +#### func (*Controller) Refresh(activityId ID) +> 刷新活动 + +*** + + +#### func (*Controller) InitializeNoneData(handler func (activityId ID, data *DataMeta[Data])) NoneDataActivityController[Type, ID, Data, EntityID, EntityData] + +*** + + +#### func (*Controller) InitializeGlobalData(handler func (activityId ID, data *DataMeta[Data])) GlobalDataActivityController[Type, ID, Data, EntityID, EntityData] + +*** + + +#### func (*Controller) InitializeEntityData(handler func (activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) EntityDataActivityController[Type, ID, Data, EntityID, EntityData] + +*** + + +#### func (*Controller) InitializeGlobalAndEntityData(handler func (activityId ID, data *DataMeta[Data]), entityHandler func (activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData] + +*** + ### BasicActivityController `INTERFACE` ```go @@ -209,6 +268,7 @@ type BasicActivityController[Type generic.Basic, ID generic.Basic, Data any, Ent Refresh(activityId ID) } ``` + ### NoneDataActivityController `INTERFACE` 无数据活动控制器 ```go @@ -217,6 +277,7 @@ type NoneDataActivityController[Type generic.Basic, ID generic.Basic, Data any, InitializeNoneData(handler func(activityId ID, data *DataMeta[Data])) NoneDataActivityController[Type, ID, Data, EntityID, EntityData] } ``` + ### GlobalDataActivityController `INTERFACE` 全局数据活动控制器 ```go @@ -226,6 +287,7 @@ type GlobalDataActivityController[Type generic.Basic, ID generic.Basic, Data any InitializeGlobalData(handler func(activityId ID, data *DataMeta[Data])) GlobalDataActivityController[Type, ID, Data, EntityID, EntityData] } ``` + ### EntityDataActivityController `INTERFACE` 实体数据活动控制器 ```go @@ -235,6 +297,7 @@ type EntityDataActivityController[Type generic.Basic, ID generic.Basic, Data any InitializeEntityData(handler func(activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) EntityDataActivityController[Type, ID, Data, EntityID, EntityData] } ``` + ### GlobalAndEntityDataActivityController `INTERFACE` 全局数据和实体数据活动控制器 ```go @@ -245,6 +308,7 @@ type GlobalAndEntityDataActivityController[Type generic.Basic, ID generic.Basic, InitializeGlobalAndEntityData(handler func(activityId ID, data *DataMeta[Data]), entityHandler func(activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData] } ``` + ### DataMeta `STRUCT` 全局活动数据 ```go @@ -254,6 +318,7 @@ type DataMeta[Data any] struct { LastNewDay time.Time } ``` + ### EntityDataMeta `STRUCT` 活动实体数据 ```go @@ -263,11 +328,13 @@ type EntityDataMeta[Data any] struct { LastNewDay time.Time } ``` + ### UpcomingEventHandler `STRUCT` ```go type UpcomingEventHandler[ID generic.Basic] func(activityId ID) ``` + ### Options `STRUCT` 活动选项 ```go @@ -276,19 +343,34 @@ type Options struct { Loop time.Duration } ``` + + #### func (*Options) WithUpcomingTime(t time.Time) *Options > 设置活动预告时间 + *** + + #### func (*Options) WithStartTime(t time.Time) *Options > 设置活动开始时间 + *** + + #### func (*Options) WithEndTime(t time.Time) *Options > 设置活动结束时间 + *** + + #### func (*Options) WithExtendedShowTime(t time.Time) *Options > 设置延长展示时间 + *** + + #### func (*Options) WithLoop(interval time.Duration) *Options > 设置活动循环，时间间隔小于等于 0 表示不循环 > - 当活动状态展示结束后，会根据该选项设置的时间间隔重新开始 + *** diff --git a/game/activity/internal/example/types/README.md b/game/activity/internal/example/types/README.md index a7d0d51..28267bf 100644 --- a/game/activity/internal/example/types/README.md +++ b/game/activity/internal/example/types/README.md @@ -16,13 +16,14 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[DemoActivityData](#demoactivitydata)|暂无描述... +|`STRUCT`|[DemoActivityData](#struct_DemoActivityData)|暂无描述... *** ## 详情信息 + ### DemoActivityData `STRUCT` ```go diff --git a/game/fight/README.md b/game/fight/README.md index 2b977fc..f052730 100644 --- a/game/fight/README.md +++ b/game/fight/README.md @@ -23,23 +23,24 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[TurnBased](#turnbased)|回合制 -|`INTERFACE`|[TurnBasedControllerInfo](#turnbasedcontrollerinfo)|暂无描述... -|`INTERFACE`|[TurnBasedControllerAction](#turnbasedcontrolleraction)|暂无描述... -|`STRUCT`|[TurnBasedController](#turnbasedcontroller)|回合制控制器 -|`STRUCT`|[TurnBasedEntitySwitchEventHandler](#turnbasedentityswitcheventhandler)|暂无描述... +|`STRUCT`|[TurnBased](#struct_TurnBased)|回合制 +|`INTERFACE`|[TurnBasedControllerInfo](#struct_TurnBasedControllerInfo)|暂无描述... +|`INTERFACE`|[TurnBasedControllerAction](#struct_TurnBasedControllerAction)|暂无描述... +|`STRUCT`|[TurnBasedController](#struct_TurnBasedController)|回合制控制器 +|`STRUCT`|[TurnBasedEntitySwitchEventHandler](#struct_TurnBasedEntitySwitchEventHandler)|暂无描述... *** ## 详情信息 -#### func NewTurnBased(calcNextTurnDuration func ( Camp, Entity) time.Duration) *TurnBased[CampID, EntityID, Camp, Entity] +#### func NewTurnBased\[CampID comparable, EntityID comparable, Camp generic.IdR[CampID], Entity generic.IdR[EntityID]\](calcNextTurnDuration func ( Camp, Entity) time.Duration) *TurnBased[CampID, EntityID, Camp, Entity] > 创建一个新的回合制 > - calcNextTurnDuration 将返回下一次行动时间间隔，适用于按照速度计算下一次行动时间间隔的情况。当返回 0 时，将使用默认的行动超时时间 *** + ### TurnBased `STRUCT` 回合制 ```go @@ -64,6 +65,76 @@ type TurnBased[CampID comparable, EntityID comparable, Camp generic.IdR[CampID], closed bool } ``` + + +#### func (*TurnBased) Close() +> 关闭回合制 + +*** + + +#### func (*TurnBased) AddCamp(camp Camp, entity Entity, entities ...Entity) +> 添加阵营 + +*** + + +#### func (*TurnBased) SetActionTimeout(actionTimeoutHandler func ( Camp, Entity) time.Duration) +> 设置行动超时时间处理函数 +> - 默认情况下行动超时时间函数将始终返回 0 + +*** + + +#### func (*TurnBased) Run() +> 运行 + +
+查看 / 收起单元测试 + + +```go + +func TestTurnBased_Run(t *testing.T) { + tbi := fight.NewTurnBased[string, string, *Camp, *Entity](func(camp *Camp, entity *Entity) time.Duration { + return time.Duration(float64(time.Second) / entity.speed) + }) + tbi.SetActionTimeout(func(camp *Camp, entity *Entity) time.Duration { + return time.Second * 5 + }) + tbi.RegTurnBasedEntityActionTimeoutEvent(func(controller fight.TurnBasedControllerInfo[string, string, *Camp, *Entity]) { + t.Log("时间", time.Now().Unix(), "回合", controller.GetRound(), "阵营", controller.GetCamp().GetId(), "实体", controller.GetEntity().GetId(), "超时") + }) + tbi.RegTurnBasedRoundChangeEvent(func(controller fight.TurnBasedControllerInfo[string, string, *Camp, *Entity]) { + t.Log("时间", time.Now().Unix(), "回合", controller.GetRound(), "回合切换") + }) + tbi.RegTurnBasedEntitySwitchEvent(func(controller fight.TurnBasedControllerAction[string, string, *Camp, *Entity]) { + switch controller.GetEntity().GetId() { + case "1": + go func() { + time.Sleep(time.Second * 2) + controller.Finish() + }() + case "2": + controller.Refresh(time.Second) + case "4": + controller.Stop() + } + t.Log("时间", time.Now().Unix(), "回合", controller.GetRound(), "阵营", controller.GetCamp().GetId(), "实体", controller.GetEntity().GetId(), "开始行动") + }) + tbi.AddCamp(&Camp{id: "1"}, &Entity{id: "1", speed: 1}, &Entity{id: "2", speed: 1}) + tbi.AddCamp(&Camp{id: "2"}, &Entity{id: "3", speed: 1}, &Entity{id: "4", speed: 1}) + tbi.Run() +} + +``` + + +
+ + +*** + ### TurnBasedControllerInfo `INTERFACE` ```go @@ -77,6 +148,7 @@ type TurnBasedControllerInfo[CampID comparable, EntityID comparable, Camp generi Stop() } ``` + ### TurnBasedControllerAction `INTERFACE` ```go @@ -86,6 +158,7 @@ type TurnBasedControllerAction[CampID comparable, EntityID comparable, Camp gene Refresh(duration time.Duration) time.Time } ``` + ### TurnBasedController `STRUCT` 回合制控制器 ```go @@ -93,6 +166,62 @@ type TurnBasedController[CampID comparable, EntityID comparable, Camp generic.Id tb *TurnBased[CampID, EntityID, Camp, Entity] } ``` + + +#### func (*TurnBasedController) GetRound() int +> 获取当前回合数 + +*** + + +#### func (*TurnBasedController) GetCamp() Camp +> 获取当前操作阵营 + +*** + + +#### func (*TurnBasedController) GetEntity() Entity +> 获取当前操作实体 + +*** + + +#### func (*TurnBasedController) GetActionTimeoutDuration() time.Duration +> 获取当前行动超时时长 + +*** + + +#### func (*TurnBasedController) GetActionStartTime() time.Time +> 获取当前行动开始时间 + +*** + + +#### func (*TurnBasedController) GetActionEndTime() time.Time +> 获取当前行动结束时间 + +*** + + +#### func (*TurnBasedController) Finish() +> 结束当前操作，将立即切换到下一个操作实体 + +*** + + +#### func (*TurnBasedController) Stop() +> 在当前回合执行完毕后停止回合进程 + +*** + + +#### func (*TurnBasedController) Refresh(duration time.Duration) time.Time +> 刷新当前操作实体的行动超时时间 +> - 当不在行动阶段时，将返回 time.Time 零值 + +*** + ### TurnBasedEntitySwitchEventHandler `STRUCT` ```go diff --git a/game/space/README.md b/game/space/README.md index 58e3d32..84f0f65 100644 --- a/game/space/README.md +++ b/game/space/README.md @@ -24,21 +24,22 @@ space 游戏中常见的空间设计，例如房间、地图等 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[RoomController](#roomcontroller)|对房间进行操作的控制器，由 RoomManager 接管后返回 -|`STRUCT`|[RoomManager](#roommanager)|房间管理器是用于对房间进行管理的基本单元，通过该实例可以对房间进行增删改查等操作 -|`STRUCT`|[RoomAssumeControlEventHandle](#roomassumecontroleventhandle)|暂无描述... -|`STRUCT`|[RoomControllerOptions](#roomcontrolleroptions)|暂无描述... +|`STRUCT`|[RoomController](#struct_RoomController)|对房间进行操作的控制器，由 RoomManager 接管后返回 +|`STRUCT`|[RoomManager](#struct_RoomManager)|房间管理器是用于对房间进行管理的基本单元，通过该实例可以对房间进行增删改查等操作 +|`STRUCT`|[RoomAssumeControlEventHandle](#struct_RoomAssumeControlEventHandle)|暂无描述... +|`STRUCT`|[RoomControllerOptions](#struct_RoomControllerOptions)|暂无描述... *** ## 详情信息 -#### func NewRoomManager() *RoomManager[EntityID, RoomID, Entity, Room] +#### func NewRoomManager\[EntityID comparable, RoomID comparable, Entity generic.IdR[EntityID], Room generic.IdR[RoomID]\]() *RoomManager[EntityID, RoomID, Entity, Room] > 创建房间管理器 RoomManager 的实例 -示例代码： +**示例代码：** + ```go func ExampleNewRoomManager() { @@ -49,11 +50,12 @@ func ExampleNewRoomManager() { ``` *** -#### func NewRoomControllerOptions() *RoomControllerOptions[EntityID, RoomID, Entity, Room] +#### func NewRoomControllerOptions\[EntityID comparable, RoomID comparable, Entity generic.IdR[EntityID], Room generic.IdR[RoomID]\]() *RoomControllerOptions[EntityID, RoomID, Entity, Room] > 创建房间控制器选项 *** + ### RoomController `STRUCT` 对房间进行操作的控制器，由 RoomManager 接管后返回 ```go @@ -68,6 +70,247 @@ type RoomController[EntityID comparable, RoomID comparable, Entity generic.IdR[E owner *EntityID } ``` + + +#### func (*RoomController) HasOwner() bool +> 判断是否有房主 + +*** + + +#### func (*RoomController) IsOwner(entityId EntityID) bool +> 判断是否为房主 + +*** + + +#### func (*RoomController) GetOwner() Entity +> 获取房主 + +*** + + +#### func (*RoomController) GetOwnerID() EntityID +> 获取房主 ID + +*** + + +#### func (*RoomController) GetOwnerExist() ( Entity, bool) +> 获取房间，并返回房主是否存在的状态 + +*** + + +#### func (*RoomController) SetOwner(entityId EntityID) +> 设置房主 + +*** + + +#### func (*RoomController) DelOwner() +> 删除房主，将房间设置为无主的状态 + +*** + + +#### func (*RoomController) JoinSeat(entityId EntityID, seat ...int) error +> 设置特定对象加入座位，当具体的座位不存在的时候，将会自动分配座位 +> - 当目标座位存在玩家或未添加到房间中的时候，将会返回错误 + +*** + + +#### func (*RoomController) LeaveSeat(entityId EntityID) +> 离开座位 + +*** + + +#### func (*RoomController) GetSeat(entityId EntityID) int +> 获取座位 + +*** + + +#### func (*RoomController) GetFirstNotEmptySeat() int +> 获取第一个非空座位号，如果没有非空座位，将返回 UnknownSeat + +*** + + +#### func (*RoomController) GetFirstEmptySeatEntity() (entity Entity) +> 获取第一个空座位上的实体，如果没有空座位，将返回空实体 + +*** + + +#### func (*RoomController) GetRandomEntity() (entity Entity) +> 获取随机实体，如果房间中没有实体，将返回空实体 + +*** + + +#### func (*RoomController) GetNotEmptySeat() []int +> 获取非空座位 + +*** + + +#### func (*RoomController) GetEmptySeat() []int +> 获取空座位 +> - 空座位需要在有对象离开座位后才可能出现 + +*** + + +#### func (*RoomController) HasSeat(entityId EntityID) bool +> 判断是否有座位 + +*** + + +#### func (*RoomController) GetSeatEntityCount() int +> 获取座位上的实体数量 + +*** + + +#### func (*RoomController) GetSeatEntities() map[EntityID]Entity +> 获取座位上的实体 + +*** + + +#### func (*RoomController) GetSeatEntitiesByOrdered() []Entity +> 有序的获取座位上的实体 + +*** + + +#### func (*RoomController) GetSeatEntitiesByOrderedAndContainsEmpty() []Entity +> 获取有序的座位上的实体，包含空座位 + +*** + + +#### func (*RoomController) GetSeatEntity(seat int) (entity Entity) +> 获取座位上的实体 + +*** + + +#### func (*RoomController) ContainEntity(id EntityID) bool +> 房间内是否包含实体 + +*** + + +#### func (*RoomController) GetRoom() Room +> 获取原始房间实例，该实例为被接管的房间的原始实例 + +*** + + +#### func (*RoomController) GetEntities() map[EntityID]Entity +> 获取所有实体 + +*** + + +#### func (*RoomController) HasEntity(id EntityID) bool +> 判断是否有实体 + +*** + + +#### func (*RoomController) GetEntity(id EntityID) Entity +> 获取实体 + +*** + + +#### func (*RoomController) GetEntityExist(id EntityID) ( Entity, bool) +> 获取实体，并返回实体是否存在的状态 + +*** + + +#### func (*RoomController) GetEntityIDs() []EntityID +> 获取所有实体ID + +*** + + +#### func (*RoomController) GetEntityCount() int +> 获取实体数量 + +*** + + +#### func (*RoomController) ChangePassword(password *string) +> 修改房间密码 +> - 当房间密码为 nil 时，将会取消密码 + +*** + + +#### func (*RoomController) AddEntity(entity Entity) error +> 添加实体，如果房间存在密码，应使用 AddEntityByPassword 函数进行添加，否则将始终返回 ErrRoomPasswordNotMatch 错误 +> - 当房间已满时，将会返回 ErrRoomFull 错误 + +*** + + +#### func (*RoomController) AddEntityByPassword(entity Entity, password string) error +> 通过房间密码添加实体到该房间中 +> - 当未设置房间密码时，password 参数将会被忽略 +> - 当房间密码不匹配时，将会返回 ErrRoomPasswordNotMatch 错误 +> - 当房间已满时，将会返回 ErrRoomFull 错误 + +*** + + +#### func (*RoomController) RemoveEntity(id EntityID) +> 移除实体 +> - 当实体被移除时如果实体在座位上，将会自动离开座位 +> - 如果实体为房主，将会根据 RoomControllerOptions.WithOwnerInherit 函数的设置进行继承 + +*** + + +#### func (*RoomController) RemoveAllEntities() +> 移除该房间中的所有实体 +> - 当实体被移除时如果实体在座位上，将会自动离开座位 +> - 如果实体为房主，将会根据 RoomControllerOptions.WithOwnerInherit 函数的设置进行继承 + +*** + + +#### func (*RoomController) Destroy() +> 销毁房间，房间会从 RoomManager 中移除，同时所有房间的实体、座位等数据都会被清空 +> - 该函数与 RoomManager.DestroyRoom 相同，RoomManager.DestroyRoom 函数为该函数的快捷方式 + +*** + + +#### func (*RoomController) GetRoomManager() *RoomManager[EntityID, RoomID, Entity, Room] +> 获取该房间控制器所属的房间管理器 + +*** + + +#### func (*RoomController) GetRoomID() RoomID +> 获取房间 ID + +*** + + +#### func (*RoomController) Broadcast(handler func ( Entity), conditions ...func ( Entity) bool) +> 广播，该函数会将所有房间中满足 conditions 的对象传入 handler 中进行处理 + +*** + ### RoomManager `STRUCT` 房间管理器是用于对房间进行管理的基本单元，通过该实例可以对房间进行增删改查等操作 - 该实例是线程安全的 @@ -78,11 +321,87 @@ type RoomManager[EntityID comparable, RoomID comparable, Entity generic.IdR[Enti rooms map[RoomID]*RoomController[EntityID, RoomID, Entity, Room] } ``` + + +#### func (*RoomManager) AssumeControl(room Room, options ...*RoomControllerOptions[EntityID, RoomID, Entity, Room]) *RoomController[EntityID, RoomID, Entity, Room] +> 将房间控制权交由 RoomManager 接管，返回 RoomController 实例 +> - 当任何房间需要被 RoomManager 管理时，都应该调用该方法获取到 RoomController 实例后进行操作 +> - 房间被接管后需要在释放房间控制权时调用 RoomController.Destroy 方法，否则将会导致 RoomManager 一直持有房间资源 + +**示例代码：** + +```go + +func ExampleRoomManager_AssumeControl() { + var rm = space.NewRoomManager[string, int64, *Player, *Room]() + var room = &Room{Id: 1} + var controller = rm.AssumeControl(room) + if err := controller.AddEntity(&Player{Id: "1"}); err != nil { + panic(err) + } + fmt.Println(controller.GetEntityCount()) +} + +``` + +*** + + +#### func (*RoomManager) DestroyRoom(id RoomID) +> 销毁房间，该函数为 RoomController.Destroy 的快捷方式 + +*** + + +#### func (*RoomManager) GetRoom(id RoomID) *RoomController[EntityID, RoomID, Entity, Room] +> 通过房间 ID 获取对应房间的控制器 RoomController，当房间不存在时将返回 nil + +*** + + +#### func (*RoomManager) GetRooms() map[RoomID]*RoomController[EntityID, RoomID, Entity, Room] +> 获取包含所有房间 ID 到对应控制器 RoomController 的映射 +> - 返回值的 map 为拷贝对象，可安全的对其进行增删等操作 + +*** + + +#### func (*RoomManager) GetRoomCount() int +> 获取房间管理器接管的房间数量 + +*** + + +#### func (*RoomManager) GetRoomIDs() []RoomID +> 获取房间管理器接管的所有房间 ID + +*** + + +#### func (*RoomManager) HasEntity(entityId EntityID) bool +> 判断特定对象是否在任一房间中，当对象不在任一房间中时将返回 false + +*** + + +#### func (*RoomManager) GetEntityRooms(entityId EntityID) map[RoomID]*RoomController[EntityID, RoomID, Entity, Room] +> 获取特定对象所在的房间，返回值为房间 ID 到对应控制器 RoomController 的映射 +> - 由于一个对象可能在多个房间中，因此返回值为 map 类型 + +*** + + +#### func (*RoomManager) Broadcast(handler func ( Entity), conditions ...func ( Entity) bool) +> 向所有房间对象广播消息，该方法将会遍历所有房间控制器并调用 RoomController.Broadcast 方法 + +*** + ### RoomAssumeControlEventHandle `STRUCT` ```go type RoomAssumeControlEventHandle[EntityID comparable, RoomID comparable, Entity generic.IdR[EntityID], Room generic.IdR[RoomID]] func(controller *RoomController[EntityID, RoomID, Entity, Room]) ``` + ### RoomControllerOptions `STRUCT` ```go @@ -93,3 +412,23 @@ type RoomControllerOptions[EntityID comparable, RoomID comparable, Entity generi ownerInheritHandler func(controller *RoomController[EntityID, RoomID, Entity, Room]) *EntityID } ``` + + +#### func (*RoomControllerOptions) WithOwnerInherit(inherit bool, inheritHandler ...func (controller *RoomController[EntityID, RoomID, Entity, Room]) *EntityID) *RoomControllerOptions[EntityID, RoomID, Entity, Room] +> 设置房间所有者是否继承，默认为 false +> - inherit: 是否继承，当未设置 inheritHandler 且 inherit 为 true 时，将会按照随机或根据座位号顺序继承房间所有者 +> - inheritHandler: 继承处理函数，当 inherit 为 true 时，该函数将会被调用，传入当前房间中的所有实体，返回值为新的房间所有者 + +*** + + +#### func (*RoomControllerOptions) WithMaxEntityCount(maxEntityCount int) *RoomControllerOptions[EntityID, RoomID, Entity, Room] +> 设置房间最大实体数量 + +*** + + +#### func (*RoomControllerOptions) WithPassword(password string) *RoomControllerOptions[EntityID, RoomID, Entity, Room] +> 设置房间密码 + +*** diff --git a/game/task/README.md b/game/task/README.md index 3d5d02f..fe0196e 100644 --- a/game/task/README.md +++ b/game/task/README.md @@ -34,18 +34,18 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Condition](#condition)|任务条件 -|`STRUCT`|[RefreshTaskCounterEventHandler](#refreshtaskcountereventhandler)|暂无描述... -|`STRUCT`|[Option](#option)|任务选项 -|`STRUCT`|[Status](#status)|暂无描述... -|`STRUCT`|[Task](#task)|是对任务信息进行描述和处理的结构体 +|`STRUCT`|[Condition](#struct_Condition)|任务条件 +|`STRUCT`|[RefreshTaskCounterEventHandler](#struct_RefreshTaskCounterEventHandler)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|任务选项 +|`STRUCT`|[Status](#struct_Status)|暂无描述... +|`STRUCT`|[Task](#struct_Task)|是对任务信息进行描述和处理的结构体 *** ## 详情信息 -#### func Cond(k any, v any) Condition +#### func Cond(k any, v any) Condition > 创建任务条件 @@ -88,7 +88,7 @@ func TestCond(t *testing.T) { *** -#### func RegisterRefreshTaskCounterEvent(taskType string, handler RefreshTaskCounterEventHandler[Trigger]) +#### func RegisterRefreshTaskCounterEvent\[Trigger any\](taskType string, handler RefreshTaskCounterEventHandler[Trigger]) > 注册特定任务类型的刷新任务计数器事件处理函数 @@ -98,7 +98,7 @@ func TestCond(t *testing.T) { > 触发特定任务类型的刷新任务计数器事件 *** -#### func RegisterRefreshTaskConditionEvent(taskType string, handler RefreshTaskConditionEventHandler[Trigger]) +#### func RegisterRefreshTaskConditionEvent\[Trigger any\](taskType string, handler RefreshTaskConditionEventHandler[Trigger]) > 注册特定任务类型的刷新任务条件事件处理函数 @@ -108,19 +108,19 @@ func TestCond(t *testing.T) { > 触发特定任务类型的刷新任务条件事件 *** -#### func WithType(taskType string) Option +#### func WithType(taskType string) Option > 设置任务类型 *** -#### func WithCondition(condition Condition) Option +#### func WithCondition(condition Condition) Option > 设置任务完成条件，当满足条件时，任务状态为完成 > - 任务条件值需要变更时可通过 Task.AssignConditionValueAndRefresh 方法变更 > - 当多次设置该选项时，后面的设置会覆盖之前的设置 *** -#### func WithCounter(counter int64, initCount ...int64) Option +#### func WithCounter(counter int64, initCount ...int64) Option > 设置任务计数器，当计数器达到要求时，任务状态为完成 > - 一些场景下，任务计数器可能会溢出，此时可通过 WithOverflowCounter 设置可溢出的任务计数器 @@ -128,116 +128,190 @@ func TestCond(t *testing.T) { > - 如果需要初始化计数器的值，可通过 initCount 参数设置 *** -#### func WithOverflowCounter(counter int64, initCount ...int64) Option +#### func WithOverflowCounter(counter int64, initCount ...int64) Option > 设置可溢出的任务计数器，当计数器达到要求时，任务状态为完成 > - 当多次设置该选项时，后面的设置会覆盖之前的设置 > - 如果需要初始化计数器的值，可通过 initCount 参数设置 *** -#### func WithDeadline(deadline time.Time) Option +#### func WithDeadline(deadline time.Time) Option > 设置任务截止时间，超过截至时间并且任务未完成时，任务状态为失败 *** -#### func WithLimitedDuration(start time.Time, duration time.Duration) Option +#### func WithLimitedDuration(start time.Time, duration time.Duration) Option > 设置任务限时，超过限时时间并且任务未完成时，任务状态为失败 *** -#### func NewTask(options ...Option) *Task +#### func NewTask(options ...Option) *Task > 生成任务 *** + ### Condition `STRUCT` 任务条件 ```go type Condition map[any]any ``` + + #### func (Condition) Cond(k any, v any) Condition > 创建任务条件 + *** + + #### func (Condition) GetString(key any) string > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetInt(key any) int > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetInt8(key any) int8 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetInt16(key any) int16 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetInt32(key any) int32 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetInt64(key any) int64 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetUint(key any) uint > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetUint8(key any) uint8 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetUint16(key any) uint16 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetUint32(key any) uint32 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetUint64(key any) uint64 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetFloat32(key any) float32 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetFloat64(key any) float64 > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetBool(key any) bool > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetTime(key any) time.Time > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetDuration(key any) time.Duration > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetByte(key any) byte > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetBytes(key any) []byte > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetRune(key any) rune > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetRunes(key any) []rune > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + + #### func (Condition) GetAny(key any) any > 获取特定类型的任务条件值，该值必须与预期类型一致，否则返回零值 + *** + ### RefreshTaskCounterEventHandler `STRUCT` ```go type RefreshTaskCounterEventHandler[Trigger any] func(taskType string, trigger Trigger, count int64) ``` + ### Option `STRUCT` 任务选项 ```go type Option func(task *Task) ``` + ### Status `STRUCT` ```go type Status byte ``` + + #### func (Status) String() string + *** + ### Task `STRUCT` 是对任务信息进行描述和处理的结构体 ```go @@ -254,33 +328,60 @@ type Task struct { LimitedDuration time.Duration } ``` + + #### func (*Task) IsComplete() bool > 判断任务是否已完成 + *** + + #### func (*Task) IsFailed() bool > 判断任务是否已失败 + *** + + #### func (*Task) IsReward() bool > 判断任务是否已领取奖励 + *** + + #### func (*Task) ReceiveReward() bool > 领取任务奖励，当任务状态为已完成时，才能领取奖励，此时返回 true，并且任务状态变更为已领取奖励 + *** + + #### func (*Task) IncrementCounter(incr int64) *Task > 增加计数器的值，当 incr 为负数时，计数器的值不会发生变化 > - 如果需要溢出计数器，可通过 WithOverflowCounter 设置可溢出的任务计数器 + *** + + #### func (*Task) DecrementCounter(decr int64) *Task > 减少计数器的值，当 decr 为负数时，计数器的值不会发生变化 + *** + + #### func (*Task) AssignConditionValueAndRefresh(key any, value any) *Task > 分配条件值并刷新任务状态 + *** + + #### func (*Task) AssignConditionValueAndRefreshByCondition(condition Condition) *Task > 分配条件值并刷新任务状态 + *** + + #### func (*Task) ResetStatus() *Task > 重置任务状态 > - 该函数会将任务状态重置为已接受状态后，再刷新任务状态 > - 当任务条件变更，例如任务计数要求为 10，已经完成的情况下，将任务计数要求变更为 5 或 20，此时任务状态由于是已完成或已领取状态，不会自动刷新，需要调用该函数刷新任务状态 + *** diff --git a/go.mod b/go.mod index c7855df..8533405 100644 --- a/go.mod +++ b/go.mod @@ -4,26 +4,26 @@ go 1.21 require ( github.com/RussellLuo/timingwheel v0.0.0-20220218152713-54845bda3108 - github.com/alphadose/haxmap v1.3.0 + github.com/alphadose/haxmap v1.3.1 github.com/gin-contrib/pprof v1.4.0 github.com/gin-gonic/gin v1.9.1 - github.com/go-resty/resty/v2 v2.7.0 + github.com/go-resty/resty/v2 v2.11.0 github.com/gorhill/cronexpr v0.0.0-20180427100037-88b0669f7d75 - github.com/gorilla/websocket v1.5.0 + github.com/gorilla/websocket v1.5.1 github.com/json-iterator/go v1.1.12 - github.com/panjf2000/ants/v2 v2.8.1 + github.com/panjf2000/ants/v2 v2.9.0 github.com/panjf2000/gnet v1.6.7 github.com/pkg/errors v0.9.1 github.com/smartystreets/goconvey v1.8.1 github.com/sony/sonyflake v1.2.0 - github.com/spf13/cobra v1.7.0 - github.com/stretchr/testify v1.8.3 + github.com/spf13/cobra v1.8.0 + github.com/stretchr/testify v1.8.4 github.com/tealeg/xlsx v1.0.5 - github.com/tidwall/gjson v1.16.0 - github.com/xtaci/kcp-go/v5 v5.6.3 - go.uber.org/atomic v1.10.0 - golang.org/x/crypto v0.17.0 - google.golang.org/grpc v1.59.0 + github.com/tidwall/gjson v1.17.0 + github.com/xtaci/kcp-go/v5 v5.6.7 + go.uber.org/atomic v1.11.0 + golang.org/x/crypto v0.18.0 + google.golang.org/grpc v1.60.1 ) require ( @@ -40,11 +40,10 @@ require ( github.com/gopherjs/gopherjs v1.17.2 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/jtolds/gls v4.20.0+incompatible // indirect - github.com/klauspost/cpuid/v2 v2.2.5 // indirect - github.com/klauspost/reedsolomon v1.11.8 // indirect - github.com/kr/pretty v0.3.1 // indirect + github.com/klauspost/cpuid/v2 v2.2.6 // indirect + github.com/klauspost/reedsolomon v1.12.0 // indirect github.com/leodido/go-urn v1.2.4 // indirect - github.com/mattn/go-isatty v0.0.20 // indirect + github.com/mattn/go-isatty v0.0.19 // indirect github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect github.com/modern-go/reflect2 v1.0.2 // indirect github.com/pelletier/go-toml/v2 v2.0.8 // indirect @@ -59,16 +58,16 @@ require ( github.com/twitchyliquid64/golang-asm v0.15.1 // indirect github.com/ugorji/go/codec v1.2.11 // indirect github.com/valyala/bytebufferpool v1.0.0 // indirect - go.uber.org/multierr v1.11.0 // indirect - go.uber.org/zap v1.25.0 // indirect + go.uber.org/multierr v1.7.0 // indirect + go.uber.org/zap v1.19.1 // indirect golang.org/x/arch v0.3.0 // indirect - golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect - golang.org/x/net v0.17.0 // indirect - golang.org/x/sys v0.15.0 // indirect - golang.org/x/term v0.15.0 // indirect + golang.org/x/exp v0.0.0-20221031165847-c99f073a8326 // indirect + golang.org/x/net v0.19.0 // indirect + golang.org/x/sys v0.16.0 // indirect + golang.org/x/term v0.16.0 // indirect golang.org/x/text v0.14.0 // indirect - google.golang.org/genproto/googleapis/rpc v0.0.0-20231016165738-49dd2c1f3d0b // indirect + google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 // indirect google.golang.org/protobuf v1.31.0 // indirect - gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect + gopkg.in/natefinch/lumberjack.v2 v2.0.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/go.sum b/go.sum index a26711f..9260a51 100644 --- a/go.sum +++ b/go.sum @@ -1,12 +1,12 @@ cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw= +github.com/BurntSushi/toml v0.3.1 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ= github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU= github.com/RussellLuo/timingwheel v0.0.0-20220218152713-54845bda3108 h1:iPugyBI7oFtbDZXC4dnY093M1kZx6k/95sen92gafbY= github.com/RussellLuo/timingwheel v0.0.0-20220218152713-54845bda3108/go.mod h1:WAMLHwunr1hi3u7OjGV6/VWG9QbdMhGpEKjROiSFd10= -github.com/alphadose/haxmap v1.3.0 h1:C/2LboOnPCZP27GmmSXOcwx360st0P8N0fTJ3voefKc= -github.com/alphadose/haxmap v1.3.0/go.mod h1:rjHw1IAqbxm0S3U5tD16GoKsiAd8FWx5BJ2IYqXwgmM= +github.com/alphadose/haxmap v1.3.1 h1:KmZh75duO1tC8pt3LmUwoTYiZ9sh4K52FX8p7/yrlqU= +github.com/alphadose/haxmap v1.3.1/go.mod h1:rjHw1IAqbxm0S3U5tD16GoKsiAd8FWx5BJ2IYqXwgmM= +github.com/benbjohnson/clock v1.1.0 h1:Q92kusRqC1XV2MjkWETPvjJVqKetz1OzxZB7mHJLju8= github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA= -github.com/benbjohnson/clock v1.3.0 h1:ip6w0uFQkncKQ979AypyG0ER7mqUSBdKLOgAle/AT8A= -github.com/benbjohnson/clock v1.3.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA= github.com/bytedance/sonic v1.5.0/go.mod h1:ED5hyg4y6t3/9Ku1R6dU/4KyJ48DZ4jPhfY1O2AihPM= github.com/bytedance/sonic v1.9.1 h1:6iJ6NqdoxCDr6mbY8h18oSO+cShGSMRGCEo7F2h0x8s= github.com/bytedance/sonic v1.9.1/go.mod h1:i736AoUSYt75HyZLoJW9ERYxcy6eaN6h4BZXU064P/U= @@ -16,7 +16,7 @@ github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 h1:qSGYFH7+jGhD github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311/go.mod h1:b583jCggY9gE99b6G5LEC39OIiVsWj+R97kbl5odCEk= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc= -github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= @@ -45,8 +45,8 @@ github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91 github.com/go-playground/validator/v10 v10.10.0/go.mod h1:74x4gJWsvQexRdW8Pn3dXSGrTK4nAUsbPlLADvpJkos= github.com/go-playground/validator/v10 v10.14.0 h1:vgvQWe3XCz3gIeFDm/HnTIbj6UGmg/+t63MyGU2n5js= github.com/go-playground/validator/v10 v10.14.0/go.mod h1:9iXMNT7sEkjXb0I+enO7QXmzG6QCsPWY4zveKFVRSyU= -github.com/go-resty/resty/v2 v2.7.0 h1:me+K9p3uhSmXtrBZ4k9jcEAfJmuC8IivWHwaLZwPrFY= -github.com/go-resty/resty/v2 v2.7.0/go.mod h1:9PWDzw47qPphMRFfhsyk0NnSgvluHcljSMVIq3w7q0I= +github.com/go-resty/resty/v2 v2.11.0 h1:i7jMfNOJYMp69lq7qozJP+bjgzfAzeOhuGlyDrqxT/8= +github.com/go-resty/resty/v2 v2.11.0/go.mod h1:iiP/OpA0CkcL3IGt1O0+/SIItFUbkkyw5BGXiVdTu+A= github.com/goccy/go-json v0.9.7/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I= github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU= github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I= @@ -76,8 +76,8 @@ github.com/gopherjs/gopherjs v1.17.2 h1:fQnZVsXk8uxXIStYb0N4bGk7jeyTalG/wsZjQ25d github.com/gopherjs/gopherjs v1.17.2/go.mod h1:pRRIvn/QzFLrKfvEz3qUuEhtE/zLCWfreZ6J5gM2i+k= github.com/gorhill/cronexpr v0.0.0-20180427100037-88b0669f7d75 h1:f0n1xnMSmBLzVfsMMvriDyA75NB/oBgILX2GcHXIQzY= github.com/gorhill/cronexpr v0.0.0-20180427100037-88b0669f7d75/go.mod h1:g2644b03hfBX9Ov0ZBDgXXens4rxSxmqFBbhvKv2yVA= -github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc= -github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE= +github.com/gorilla/websocket v1.5.1 h1:gmztn0JnHVt9JZquRuzLw3g4wouNVzKL15iLr/zn/QY= +github.com/gorilla/websocket v1.5.1/go.mod h1:x3kM2JMyaluk02fnUJpQuwD2dCS5NDG2ZHL0uE0tcaY= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM= @@ -85,15 +85,14 @@ github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHm github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo= github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU= github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg= -github.com/klauspost/cpuid/v2 v2.2.5 h1:0E5MSMDEoAulmXNFquVs//DdoomxaoTY1kUhbc/qbZg= -github.com/klauspost/cpuid/v2 v2.2.5/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws= -github.com/klauspost/reedsolomon v1.11.8 h1:s8RpUW5TK4hjr+djiOpbZJB4ksx+TdYbRH7vHQpwPOY= -github.com/klauspost/reedsolomon v1.11.8/go.mod h1:4bXRN+cVzMdml6ti7qLouuYi32KHJ5MGv0Qd8a47h6A= +github.com/klauspost/cpuid/v2 v2.2.6 h1:ndNyv040zDGIDh8thGkXYjnFtiN02M1PVVF+JE/48xc= +github.com/klauspost/cpuid/v2 v2.2.6/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws= +github.com/klauspost/reedsolomon v1.12.0 h1:I5FEp3xSwVCcEh3F5A7dofEfhXdF/bWhQWPH+XwBFno= +github.com/klauspost/reedsolomon v1.12.0/go.mod h1:EPLZJeh4l27pUGC3aXOjheaoh1I9yut7xTURiW3LQ9Y= github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= +github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk= -github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= -github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= @@ -102,16 +101,16 @@ github.com/leodido/go-urn v1.2.1/go.mod h1:zt4jvISO2HfUBqxjfIshjdMTYS56ZS/qv49ic github.com/leodido/go-urn v1.2.4 h1:XlAE/cm/ms7TE/VMVoduSpNBoyc2dOxHs5MZSwAN63Q= github.com/leodido/go-urn v1.2.4/go.mod h1:7ZrI8mTSeBSHl/UaRyKQW1qZeMgak41ANeCNaVckg+4= github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94= -github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= -github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= +github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA= +github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M= github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk= github.com/panjf2000/ants/v2 v2.4.7/go.mod h1:f6F0NZVFsGCp5A7QW/Zj/m92atWwOkY0OIhFxRNFr4A= -github.com/panjf2000/ants/v2 v2.8.1 h1:C+n/f++aiW8kHCExKlpX6X+okmxKXP7DWLutxuAPuwQ= -github.com/panjf2000/ants/v2 v2.8.1/go.mod h1:KIBmYG9QQX5U2qzFP/yQJaq/nSb6rahS9iEHkrCMgM8= +github.com/panjf2000/ants/v2 v2.9.0 h1:SztCLkVxBRigbg+vt0S5QvF5vxAbxbKt09/YfAJ0tEo= +github.com/panjf2000/ants/v2 v2.9.0/go.mod h1:7ZxyxsqE4vvW0M7LSD8aI3cKwgFhBHbxnlN8mDqHa1I= github.com/panjf2000/gnet v1.6.7 h1:zv1k6kw80sG5ZQrLpbbFDheNCm50zm3z2e3ck5GwMOM= github.com/panjf2000/gnet v1.6.7/go.mod h1:KcOU7QsCaCBjeD5kyshBIamG3d9kAQtlob4Y0v0E+sc= github.com/pelletier/go-toml/v2 v2.0.1/go.mod h1:r9LEWfGN8R5k0VXJ+0BkIe7MYkRdwZOjgMj2KwnJFUo= @@ -125,9 +124,8 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA= github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc= +github.com/rogpeppe/go-internal v1.8.0 h1:FCbCCtXNOY3UtUuHUYaghJg4y7Fd14rXifAYUAtL9R8= github.com/rogpeppe/go-internal v1.8.0/go.mod h1:WmiCO8CzOY8rg0OYDC4/i/2WRWAB6poM+XZ2dLUbcbE= -github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= -github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/smarty/assertions v1.15.0 h1:cR//PqUBUiQRakZWqBiFFQ9wb8emQGDb0HeGdqGByCY= github.com/smarty/assertions v1.15.0/go.mod h1:yABtdzeQs6l1brC900WlRNwj6ZR55d7B+E8C6HtKdec= @@ -135,8 +133,8 @@ github.com/smartystreets/goconvey v1.8.1 h1:qGjIddxOk4grTu9JPOU31tVfq3cNdBlNa5sS github.com/smartystreets/goconvey v1.8.1/go.mod h1:+/u4qLyY6x1jReYOp7GOM2FSt8aP9CzCZL03bI28W60= github.com/sony/sonyflake v1.2.0 h1:Pfr3A+ejSg+0SPqpoAmQgEtNDAhc2G1SUYk205qVMLQ= github.com/sony/sonyflake v1.2.0/go.mod h1:LORtCywH/cq10ZbyfhKrHYgAUGH7mOBa76enV9txy/Y= -github.com/spf13/cobra v1.7.0 h1:hyqWnYt1ZQShIddO5kBpj3vu05/++x6tJ6dg8EC572I= -github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRMrb0= +github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0= +github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= @@ -150,16 +148,17 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= -github.com/stretchr/testify v1.8.3 h1:RP3t2pwF7cMEbC1dqtB6poj3niw/9gnV4Cjg5oW5gtY= github.com/stretchr/testify v1.8.3/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= +github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= +github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= github.com/tealeg/xlsx v1.0.5 h1:+f8oFmvY8Gw1iUXzPk+kz+4GpbDZPK1FhPiQRd+ypgE= github.com/tealeg/xlsx v1.0.5/go.mod h1:btRS8dz54TDnvKNosuAqxrM1QgN1udgk9O34bDCnORM= github.com/templexxx/cpu v0.1.0 h1:wVM+WIJP2nYaxVxqgHPD4wGA2aJ9rvrQRV8CvFzNb40= github.com/templexxx/cpu v0.1.0/go.mod h1:w7Tb+7qgcAlIyX4NhLuDKt78AHA5SzPmq0Wj6HiEnnk= github.com/templexxx/xorsimd v0.4.2 h1:ocZZ+Nvu65LGHmCLZ7OoCtg8Fx8jnHKK37SjvngUoVI= github.com/templexxx/xorsimd v0.4.2/go.mod h1:HgwaPoDREdi6OnULpSfxhzaiiSUY4Fi3JPn1wpt28NI= -github.com/tidwall/gjson v1.16.0 h1:SyXa+dsSPpUlcwEDuKuEBJEz5vzTvOea+9rjyYodQFg= -github.com/tidwall/gjson v1.16.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk= +github.com/tidwall/gjson v1.17.0 h1:/Jocvlh98kcTfpN2+JzGQWQcqrPQwDrVEMApx/M5ZwM= +github.com/tidwall/gjson v1.17.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk= github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA= github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM= github.com/tidwall/pretty v1.2.0 h1:RWIZEg2iJ8/g6fDDYzMpobmaoGh5OLl4AXtGUGPcqCs= @@ -174,25 +173,23 @@ github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4d github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg= github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= -github.com/xtaci/kcp-go/v5 v5.6.3 h1:yd59SKXdJ0PBxeMBy3apalxFCEmBLGgQmL6nP46tU0g= -github.com/xtaci/kcp-go/v5 v5.6.3/go.mod h1:uIuw2KEg3FcmEdS4PeXHaGty9Ui7NYb1WKIrSDwpMg4= +github.com/xtaci/kcp-go/v5 v5.6.7 h1:7+rnxNFIsjEwTXQk4cSZpXM4pO0hqtpwE1UFFoJBffA= +github.com/xtaci/kcp-go/v5 v5.6.7/go.mod h1:oE9j2NVqAkuKO5o8ByKGch3vgVX3BNf8zqP8JiGq0bM= github.com/xtaci/lossyconn v0.0.0-20190602105132-8df528c0c9ae h1:J0GxkO96kL4WF+AIT3M4mfUVinOCPgf2uUWYFUzN0sM= github.com/xtaci/lossyconn v0.0.0-20190602105132-8df528c0c9ae/go.mod h1:gXtu8J62kEgmN++bm9BVICuT/e8yiLI2KFobd/TRFsE= github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k= +github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= go.uber.org/atomic v1.7.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc= go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc= -go.uber.org/atomic v1.10.0 h1:9qC72Qh0+3MqyJbAn8YU5xVq1frD8bn3JtD2oXtafVQ= -go.uber.org/atomic v1.10.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0= +go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE= +go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0= +go.uber.org/goleak v1.1.11-0.20210813005559-691160354723 h1:sHOAIxRGBp443oHZIPB+HsUGaksVCXVQENPxwTfQdH4= go.uber.org/goleak v1.1.11-0.20210813005559-691160354723/go.mod h1:cwTWslyiVhfpKIDGSZEM2HlOvcqm+tG4zioyIeLoqMQ= -go.uber.org/goleak v1.2.0 h1:xqgm/S+aQvhWFTtR0XK3Jvg7z8kGV8P4X14IzwN3Eqk= -go.uber.org/goleak v1.2.0/go.mod h1:XJYK+MuIchqpmGmUSAzotztawfKvYLUIgg7guXrwVUo= go.uber.org/multierr v1.6.0/go.mod h1:cdWPpRnG4AhwMwsgIHip0KRBQjJy5kYEpYjJxpXp9iU= +go.uber.org/multierr v1.7.0 h1:zaiO/rmgFjbmCXdSYJWQcdvOCsthmdaHfr3Gm2Kx4Ec= go.uber.org/multierr v1.7.0/go.mod h1:7EAYxJLBy9rStEaz58O2t4Uvip6FSURkq8/ppBp95ak= -go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= -go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= +go.uber.org/zap v1.19.1 h1:ue41HOKd1vGURxrmeKIgELGb3jPW9DMUDGtsinblHwI= go.uber.org/zap v1.19.1/go.mod h1:j3DNczoxDZroyBnOT1L/Q79cfUMGZxlv/9dzN7SM1rI= -go.uber.org/zap v1.25.0 h1:4Hvk6GtkucQ790dqmj7l1eEnRdKm3k3ZUrUMS2d5+5c= -go.uber.org/zap v1.25.0/go.mod h1:JIAUzQIH94IC4fOJQm7gMmBJP5k7wQfdcnYdPoEXJYk= golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8= golang.org/x/arch v0.3.0 h1:02VY4/ZcO/gBOH6PUaoiptASxtXU10jazRCP865E97k= golang.org/x/arch v0.3.0/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8= @@ -201,16 +198,20 @@ golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8U golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= golang.org/x/crypto v0.0.0-20201012173705-84dcc777aaee/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= golang.org/x/crypto v0.0.0-20210711020723-a769d52b0f97/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= -golang.org/x/crypto v0.17.0 h1:r8bRNjWL3GshPW3gkd+RpvzWrZAwPS49OmTGZ/uhM4k= -golang.org/x/crypto v0.17.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4= +golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= +golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4= +golang.org/x/crypto v0.18.0 h1:PGVlW0xEltQnzFZ55hkuX5+KLyrMYhHld1YHO4AKcdc= +golang.org/x/crypto v0.18.0/go.mod h1:R0j02AL6hcrfOiy9T4ZYp/rcWeMxM3L6QYxlOuEG1mg= golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA= -golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g= -golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k= +golang.org/x/exp v0.0.0-20221031165847-c99f073a8326 h1:QfTh0HpN6hlw6D3vu8DAwC8pBIwikq0AI1evdm+FksE= +golang.org/x/exp v0.0.0-20221031165847-c99f073a8326/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc= golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE= golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU= golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc= golang.org/x/lint v0.0.0-20190930215403-16217165b5de/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc= golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= +golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= +golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs= golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= @@ -220,41 +221,59 @@ golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLL golang.org/x/net v0.0.0-20201010224723-4f7140c49acb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU= golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM= -golang.org/x/net v0.0.0-20211029224645-99673261e6eb/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y= -golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM= +golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= +golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= +golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg= golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE= +golang.org/x/net v0.19.0 h1:zTwKpTd2XuCqf8huc7Fo2iSy+4RHPd10s4KzeTnVr1c= +golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U= golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E= golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= +golang.org/x/sync v0.4.0 h1:zxkM55ReGkDlKSM+Fu41A+zmbZuaPVbGMzvvdUPznYQ= +golang.org/x/sync v0.4.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210806184541-e5e7981a1069/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20211204120058-94396e421777/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc= -golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.16.0 h1:xWw16ngr6ZMtmxDyKyIgsE93KNKz5HKmMa3b8ALHidU= +golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= -golang.org/x/term v0.15.0 h1:y/Oo/a/q3IXu26lQgl04j/gjuBDOBlx7X6Om1j2CPW4= -golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0= +golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= +golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= +golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo= +golang.org/x/term v0.13.0/go.mod h1:LTmsnFJwVN6bCy1rVCoS+qHT1HhALEFxKncY3WNNh4U= +golang.org/x/term v0.16.0 h1:m+B6fahuftsE9qjo0VWp2FW0mB3MTJvR0BaMQrq0pmE= +golang.org/x/term v0.16.0/go.mod h1:yn7UURbUtPyrVJPGPq404EukNFxcm/foM+bV/bfcDsY= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= +golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= +golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= +golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= +golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4= +golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY= @@ -262,6 +281,8 @@ golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3 golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.1.5/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk= +golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= +golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -270,14 +291,14 @@ google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9Ywl google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4= google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc= google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc= -google.golang.org/genproto/googleapis/rpc v0.0.0-20231016165738-49dd2c1f3d0b h1:ZlWIi1wSK56/8hn4QcBp/j9M7Gt3U/3hZw3mC7vDICo= -google.golang.org/genproto/googleapis/rpc v0.0.0-20231016165738-49dd2c1f3d0b/go.mod h1:swOH3j0KzcDDgGUWr+SNpyTen5YrXjS3eyPzFYKc6lc= +google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 h1:6GQBEOdGkX6MMTLT9V+TjtIRZCw9VPD5Z+yHY9wMgS0= +google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97/go.mod h1:v7nGkzlmW8P3n/bKmWBn2WpBjpOEx8Q6gMueudAmKfY= google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c= google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg= google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY= google.golang.org/grpc v1.31.0/go.mod h1:N36X2cJ7JwdamYAgDz+s+rVMFjt3numwzf/HckM8pak= -google.golang.org/grpc v1.59.0 h1:Z5Iec2pjwb+LEOqzpB2MR12/eKFhDPhuqW91O+4bwUk= -google.golang.org/grpc v1.59.0/go.mod h1:aUPDwccQo6OTjy7Hct4AfBPD1GptF4fyUjIkQ9YtF98= +google.golang.org/grpc v1.60.1 h1:26+wFr+cNqSGFcOXcabYC0lUVJVRa2Sb2ortSK7VrEU= +google.golang.org/grpc v1.60.1/go.mod h1:OlCHIeLYqSSsLi6i49B5QGdzaMZK9+M7LXN2FKz4eGM= google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8= google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0= google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM= @@ -295,12 +316,12 @@ gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI= +gopkg.in/natefinch/lumberjack.v2 v2.0.0 h1:1Lc07Kr7qY4U2YPouBjpCLxpiyxIVoxqXgkXLknAOE8= gopkg.in/natefinch/lumberjack.v2 v2.0.0/go.mod h1:l0ndWWf7gzL7RNwBG7wST/UCcT4T24xpD6X8LsfU/+k= -gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc= -gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.7/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/notify/README.md b/notify/README.md index 284040b..91b960f 100644 --- a/notify/README.md +++ b/notify/README.md @@ -23,20 +23,21 @@ notify 包含了对外部第三方通知的实现，如机器人消息等 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Manager](#manager)|通知管理器，可用于将通知同时发送至多个渠道 -|`INTERFACE`|[Notify](#notify)|通用通知接口定义 -|`INTERFACE`|[Sender](#sender)|通知发送器接口声明 +|`STRUCT`|[Manager](#struct_Manager)|通知管理器，可用于将通知同时发送至多个渠道 +|`INTERFACE`|[Notify](#struct_Notify)|通用通知接口定义 +|`INTERFACE`|[Sender](#struct_Sender)|通知发送器接口声明 *** ## 详情信息 -#### func NewManager(senders ...Sender) *Manager +#### func NewManager(senders ...Sender) *Manager > 通过指定的 Sender 创建一个通知管理器， senders 包中提供了一些内置的 Sender *** + ### Manager `STRUCT` 通知管理器，可用于将通知同时发送至多个渠道 ```go @@ -46,12 +47,19 @@ type Manager struct { closeChannel chan struct{} } ``` + + #### func (*Manager) PushNotify(notify Notify) > 推送通知 + *** + + #### func (*Manager) Release() > 释放通知管理器 + *** + ### Notify `INTERFACE` 通用通知接口定义 ```go @@ -59,6 +67,7 @@ type Notify interface { Format() (string, error) } ``` + ### Sender `INTERFACE` 通知发送器接口声明 ```go diff --git a/notify/notifies/README.md b/notify/notifies/README.md index 7b99d6e..eb15f92 100644 --- a/notify/notifies/README.md +++ b/notify/notifies/README.md @@ -35,22 +35,22 @@ notifies 包含了内置通知内容的实现 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[FeiShu](#feishu)|飞书通知消息 -|`STRUCT`|[FeiShuMessage](#feishumessage)|暂无描述... -|`STRUCT`|[FeiShuRichText](#feishurichtext)|飞书富文本结构 -|`STRUCT`|[FeiShuRichTextContent](#feishurichtextcontent)|飞书富文本内容体 +|`STRUCT`|[FeiShu](#struct_FeiShu)|飞书通知消息 +|`STRUCT`|[FeiShuMessage](#struct_FeiShuMessage)|暂无描述... +|`STRUCT`|[FeiShuRichText](#struct_FeiShuRichText)|飞书富文本结构 +|`STRUCT`|[FeiShuRichTextContent](#struct_FeiShuRichTextContent)|飞书富文本内容体 *** ## 详情信息 -#### func NewFeiShu(message FeiShuMessage) *FeiShu +#### func NewFeiShu(message FeiShuMessage) *FeiShu > 创建飞书通知消息 *** -#### func FeiShuMessageWithText(text string) FeiShuMessage +#### func FeiShuMessageWithText(text string) FeiShuMessage > 飞书文本消息 > - 支持通过换行符进行消息换行 @@ -68,24 +68,24 @@ notifies 包含了内置通知内容的实现 > - 请确保链接是合法的，否则会以原始内容发送消息。 *** -#### func FeiShuMessageWithRichText(richText *FeiShuRichText) FeiShuMessage +#### func FeiShuMessageWithRichText(richText *FeiShuRichText) FeiShuMessage > 飞书富文本消息 *** -#### func FeiShuMessageWithImage(imageKey string) FeiShuMessage +#### func FeiShuMessageWithImage(imageKey string) FeiShuMessage > 飞书图片消息 > - imageKey 可通过上传图片接口获取 *** -#### func FeiShuMessageWithInteractive(json string) FeiShuMessage +#### func FeiShuMessageWithInteractive(json string) FeiShuMessage > 飞书卡片消息 > - json 表示卡片的 json 数据或者消息模板的 json 数据 *** -#### func FeiShuMessageWithShareChat(chatId string) FeiShuMessage +#### func FeiShuMessageWithShareChat(chatId string) FeiShuMessage > 飞书分享群名片 > - chatId 群ID获取方式请参见群ID说明 @@ -93,7 +93,7 @@ notifies 包含了内置通知内容的实现 > 群ID说明：https://open.feishu.cn/document/server-docs/group/chat/chat-id-description *** -#### func FeiShuMessageWithShareUser(userId string) FeiShuMessage +#### func FeiShuMessageWithShareUser(userId string) FeiShuMessage > 飞书分享个人名片 > - userId 表示用户的 OpenID 获取方式请参见了解更多：如何获取 Open ID @@ -101,7 +101,7 @@ notifies 包含了内置通知内容的实现 > 如何获取 Open ID：https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-openid *** -#### func FeiShuMessageWithAudio(fileKey string) FeiShuMessage +#### func FeiShuMessageWithAudio(fileKey string) FeiShuMessage > 飞书语音消息 > - fileKey 语音文件Key，可通过上传文件接口获取 @@ -109,7 +109,7 @@ notifies 包含了内置通知内容的实现 > 上传文件：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create *** -#### func FeiShuMessageWithMedia(fileKey string) FeiShuMessage +#### func FeiShuMessageWithMedia(fileKey string) FeiShuMessage > 飞书视频消息 > - fileKey 视频文件Key，可通过上传文件接口获取 @@ -117,7 +117,7 @@ notifies 包含了内置通知内容的实现 > 上传文件：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create *** -#### func FeiShuMessageWithMediaAndCover(fileKey string, imageKey string) FeiShuMessage +#### func FeiShuMessageWithMediaAndCover(fileKey string, imageKey string) FeiShuMessage > 飞书带封面的视频消息 > - fileKey 视频文件Key，可通过上传文件接口获取 @@ -126,7 +126,7 @@ notifies 包含了内置通知内容的实现 > 上传文件：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create *** -#### func FeiShuMessageWithFile(fileKey string) FeiShuMessage +#### func FeiShuMessageWithFile(fileKey string) FeiShuMessage > 飞书文件消息 > - fileKey 文件Key，可通过上传文件接口获取 @@ -134,7 +134,7 @@ notifies 包含了内置通知内容的实现 > 上传文件：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create *** -#### func FeiShuMessageWithSticker(fileKey string) FeiShuMessage +#### func FeiShuMessageWithSticker(fileKey string) FeiShuMessage > 飞书表情包消息 > - fileKey 表情包文件Key，目前仅支持发送机器人收到的表情包，可通过接收消息事件的推送获取表情包 file_key。 @@ -142,11 +142,12 @@ notifies 包含了内置通知内容的实现 > 接收消息事件：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/events/receive *** -#### func NewFeiShuRichText() *FeiShuRichText +#### func NewFeiShuRichText() *FeiShuRichText > 创建一个飞书富文本 *** + ### FeiShu `STRUCT` 飞书通知消息 ```go @@ -155,14 +156,19 @@ type FeiShu struct { MsgType string } ``` -#### func (*FeiShu) Format() string, error + + +#### func (*FeiShu) Format() ( string, error) > 格式化通知内容 + *** + ### FeiShuMessage `STRUCT` ```go type FeiShuMessage func(feishu *FeiShu) ``` + ### FeiShuRichText `STRUCT` 飞书富文本结构 ```go @@ -170,9 +176,13 @@ type FeiShuRichText struct { content map[string]*FeiShuRichTextContent } ``` + + #### func (*FeiShuRichText) Create(lang string, title string) *FeiShuRichTextContent > 创建一个特定语言和标题的富文本内容 + *** + ### FeiShuRichTextContent `STRUCT` 飞书富文本内容体 ```go @@ -182,45 +192,75 @@ type FeiShuRichTextContent struct { Content [][]map[string]any } ``` + + #### func (*FeiShuRichTextContent) AddText(text string, styles ...string) *FeiShuRichTextContent > 添加文本 + *** + + #### func (*FeiShuRichTextContent) AddUnescapeText(text string, styles ...string) *FeiShuRichTextContent > 添加 unescape 解码的文本 + *** + + #### func (*FeiShuRichTextContent) AddLink(text string, href string, styles ...string) *FeiShuRichTextContent > 添加超链接文本 > - 请确保链接地址的合法性，否则消息会发送失败 + *** + + #### func (*FeiShuRichTextContent) AddAt(userId string, styles ...string) *FeiShuRichTextContent > 添加@的用户 > - @单个用户时，userId 字段必须是有效值 > - @所有人填"all"。 + *** + + #### func (*FeiShuRichTextContent) AddAtWithUsername(userId string, username string, styles ...string) *FeiShuRichTextContent > 添加包含用户名的@用户 > - @单个用户时，userId 字段必须是有效值 > - @所有人填"all"。 + *** + + #### func (*FeiShuRichTextContent) AddImg(imageKey string) *FeiShuRichTextContent > 添加图片 > - imageKey 表示图片的唯一标识，可通过上传图片接口获取 + *** + + #### func (*FeiShuRichTextContent) AddMedia(fileKey string) *FeiShuRichTextContent > 添加视频 > - fileKey 表示视频文件的唯一标识，可通过上传文件接口获取 + *** + + #### func (*FeiShuRichTextContent) AddMediaWithCover(fileKey string, imageKey string) *FeiShuRichTextContent > 添加包含封面的视频 > - fileKey 表示视频文件的唯一标识，可通过上传文件接口获取 > - imageKey 表示图片的唯一标识，可通过上传图片接口获取 + *** + + #### func (*FeiShuRichTextContent) AddEmotion(emojiType string) *FeiShuRichTextContent > 添加表情 > - emojiType 表示表情类型，部分可选值请参见表情文案。 > > 表情文案：https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce + *** + + #### func (*FeiShuRichTextContent) Ok() *FeiShuRichText > 确认完成，将返回 FeiShuRichText 可继续创建多语言富文本 + *** diff --git a/notify/senders/README.md b/notify/senders/README.md index a446930..3045153 100644 --- a/notify/senders/README.md +++ b/notify/senders/README.md @@ -23,18 +23,19 @@ senders Package 包含了内置通知发送器的实现 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[FeiShu](#feishu)|飞书发送器 +|`STRUCT`|[FeiShu](#struct_FeiShu)|飞书发送器 *** ## 详情信息 -#### func NewFeiShu(webhook string) *FeiShu +#### func NewFeiShu(webhook string) *FeiShu > 根据特定的 webhook 地址创建飞书发送器 *** + ### FeiShu `STRUCT` 飞书发送器 ```go @@ -43,8 +44,11 @@ type FeiShu struct { webhook string } ``` + + #### func (*FeiShu) Push(notify notify.Notify) error > 推送通知 +
查看 / 收起单元测试 @@ -52,7 +56,7 @@ type FeiShu struct { ```go func TestFeiShu_Push(t *testing.T) { - fs := NewFeiShu("https://open.feishu.cn/open-apis/bot/v2/hook/d886f30f-814c-47b1-aeb0-b508da0f7f22") + fs := NewFeiShu("https://open.feishu.cn/open-apis/bot/v2/hook/bid") rt := notifies.NewFeiShu(notifies.FeiShuMessageWithRichText(notifies.NewFeiShuRichText().Create("zh_cn", "标题咯").AddText("哈哈哈").Ok())) if err := fs.Push(rt); err != nil { panic(err) diff --git a/notify/senders/feishu_test.go b/notify/senders/feishu_test.go index 7272c17..9d46120 100644 --- a/notify/senders/feishu_test.go +++ b/notify/senders/feishu_test.go @@ -6,7 +6,7 @@ import ( ) func TestFeiShu_Push(t *testing.T) { - fs := NewFeiShu("https://open.feishu.cn/open-apis/bot/v2/hook/d886f30f-814c-47b1-aeb0-b508da0f7f22") + fs := NewFeiShu("https://open.feishu.cn/open-apis/bot/v2/hook/bid") rt := notifies.NewFeiShu(notifies.FeiShuMessageWithRichText(notifies.NewFeiShuRichText().Create("zh_cn", "标题咯").AddText("哈哈哈").Ok())) if err := fs.Push(rt); err != nil { diff --git a/planner/pce/README.md b/planner/pce/README.md index dd10bdd..cf4d54b 100644 --- a/planner/pce/README.md +++ b/planner/pce/README.md @@ -26,55 +26,55 @@ |类型|名称|描述 |:--|:--|:-- -|`INTERFACE`|[Config](#config)|配置解析接口 -|`INTERFACE`|[DataTmpl](#datatmpl)|数据导出模板 -|`STRUCT`|[Exporter](#exporter)|导出器 -|`INTERFACE`|[Field](#field)|基本字段类型接口 -|`STRUCT`|[Int](#int)|暂无描述... -|`STRUCT`|[Int8](#int8)|暂无描述... -|`STRUCT`|[Int16](#int16)|暂无描述... -|`STRUCT`|[Int32](#int32)|暂无描述... -|`STRUCT`|[Int64](#int64)|暂无描述... -|`STRUCT`|[Uint](#uint)|暂无描述... -|`STRUCT`|[Uint8](#uint8)|暂无描述... -|`STRUCT`|[Uint16](#uint16)|暂无描述... -|`STRUCT`|[Uint32](#uint32)|暂无描述... -|`STRUCT`|[Uint64](#uint64)|暂无描述... -|`STRUCT`|[Float32](#float32)|暂无描述... -|`STRUCT`|[Float64](#float64)|暂无描述... -|`STRUCT`|[String](#string)|暂无描述... -|`STRUCT`|[Bool](#bool)|暂无描述... -|`STRUCT`|[Byte](#byte)|暂无描述... -|`STRUCT`|[Rune](#rune)|暂无描述... -|`STRUCT`|[Complex64](#complex64)|暂无描述... -|`STRUCT`|[Complex128](#complex128)|暂无描述... -|`STRUCT`|[Uintptr](#uintptr)|暂无描述... -|`STRUCT`|[Double](#double)|暂无描述... -|`STRUCT`|[Float](#float)|暂无描述... -|`STRUCT`|[Long](#long)|暂无描述... -|`STRUCT`|[Short](#short)|暂无描述... -|`STRUCT`|[Char](#char)|暂无描述... -|`STRUCT`|[Number](#number)|暂无描述... -|`STRUCT`|[Integer](#integer)|暂无描述... -|`STRUCT`|[Boolean](#boolean)|暂无描述... -|`STRUCT`|[Loader](#loader)|配置加载器 -|`STRUCT`|[DataInfo](#datainfo)|配置数据 -|`STRUCT`|[DataField](#datafield)|配置数据字段 -|`INTERFACE`|[Tmpl](#tmpl)|配置结构模板接口 -|`STRUCT`|[TmplField](#tmplfield)|模板字段 -|`STRUCT`|[TmplStruct](#tmplstruct)|模板结构 +|`INTERFACE`|[Config](#struct_Config)|配置解析接口 +|`INTERFACE`|[DataTmpl](#struct_DataTmpl)|数据导出模板 +|`STRUCT`|[Exporter](#struct_Exporter)|导出器 +|`INTERFACE`|[Field](#struct_Field)|基本字段类型接口 +|`STRUCT`|[Int](#struct_Int)|暂无描述... +|`STRUCT`|[Int8](#struct_Int8)|暂无描述... +|`STRUCT`|[Int16](#struct_Int16)|暂无描述... +|`STRUCT`|[Int32](#struct_Int32)|暂无描述... +|`STRUCT`|[Int64](#struct_Int64)|暂无描述... +|`STRUCT`|[Uint](#struct_Uint)|暂无描述... +|`STRUCT`|[Uint8](#struct_Uint8)|暂无描述... +|`STRUCT`|[Uint16](#struct_Uint16)|暂无描述... +|`STRUCT`|[Uint32](#struct_Uint32)|暂无描述... +|`STRUCT`|[Uint64](#struct_Uint64)|暂无描述... +|`STRUCT`|[Float32](#struct_Float32)|暂无描述... +|`STRUCT`|[Float64](#struct_Float64)|暂无描述... +|`STRUCT`|[String](#struct_String)|暂无描述... +|`STRUCT`|[Bool](#struct_Bool)|暂无描述... +|`STRUCT`|[Byte](#struct_Byte)|暂无描述... +|`STRUCT`|[Rune](#struct_Rune)|暂无描述... +|`STRUCT`|[Complex64](#struct_Complex64)|暂无描述... +|`STRUCT`|[Complex128](#struct_Complex128)|暂无描述... +|`STRUCT`|[Uintptr](#struct_Uintptr)|暂无描述... +|`STRUCT`|[Double](#struct_Double)|暂无描述... +|`STRUCT`|[Float](#struct_Float)|暂无描述... +|`STRUCT`|[Long](#struct_Long)|暂无描述... +|`STRUCT`|[Short](#struct_Short)|暂无描述... +|`STRUCT`|[Char](#struct_Char)|暂无描述... +|`STRUCT`|[Number](#struct_Number)|暂无描述... +|`STRUCT`|[Integer](#struct_Integer)|暂无描述... +|`STRUCT`|[Boolean](#struct_Boolean)|暂无描述... +|`STRUCT`|[Loader](#struct_Loader)|配置加载器 +|`STRUCT`|[DataInfo](#struct_DataInfo)|配置数据 +|`STRUCT`|[DataField](#struct_DataField)|配置数据字段 +|`INTERFACE`|[Tmpl](#struct_Tmpl)|配置结构模板接口 +|`STRUCT`|[TmplField](#struct_TmplField)|模板字段 +|`STRUCT`|[TmplStruct](#struct_TmplStruct)|模板结构
*** ## 详情信息 -#### func NewExporter() *Exporter +#### func NewExporter() *Exporter > 创建导出器 *** -#### func GetFieldGolangType(field Field) string +#### func GetFieldGolangType(field Field) string > 获取字段的 Golang 类型 @@ -95,17 +95,18 @@ func TestGetFieldGolangType(t *testing.T) { *** -#### func GetFields() []Field +#### func GetFields() []Field > 获取所有内置支持的字段 *** -#### func NewLoader(fields []Field) *Loader +#### func NewLoader(fields []Field) *Loader > 创建加载器 > - 加载器被用于加载配置表的数据和结构信息 *** + ### Config `INTERFACE` 配置解析接口 - 用于将配置文件解析为可供分析的数据结构 @@ -120,6 +121,7 @@ type Config interface { GetData() [][]DataInfo } ``` + ### DataTmpl `INTERFACE` 数据导出模板 ```go @@ -127,17 +129,25 @@ type DataTmpl interface { Render(data map[any]any) (string, error) } ``` + ### Exporter `STRUCT` 导出器 ```go type Exporter struct{} ``` -#### func (*Exporter) ExportStruct(tmpl Tmpl, tmplStruct ...*TmplStruct) []byte, error + + +#### func (*Exporter) ExportStruct(tmpl Tmpl, tmplStruct ...*TmplStruct) ( []byte, error) > 导出结构 + *** -#### func (*Exporter) ExportData(tmpl DataTmpl, data map[any]any) []byte, error + + +#### func (*Exporter) ExportData(tmpl DataTmpl, data map[any]any) ( []byte, error) > 导出数据 + *** + ### Field `INTERFACE` 基本字段类型接口 ```go @@ -147,303 +157,574 @@ type Field interface { Parse(value string) any } ``` + ### Int `STRUCT` ```go type Int int ``` + + #### func (Int) TypeName() string + *** + + #### func (Int) Zero() any + *** + + #### func (Int) Parse(value string) any + *** + ### Int8 `STRUCT` ```go type Int8 int8 ``` + + #### func (Int8) TypeName() string + *** + + #### func (Int8) Zero() any + *** + + #### func (Int8) Parse(value string) any + *** + ### Int16 `STRUCT` ```go type Int16 int16 ``` + + #### func (Int16) TypeName() string + *** + + #### func (Int16) Zero() any + *** + + #### func (Int16) Parse(value string) any + *** + ### Int32 `STRUCT` ```go type Int32 int32 ``` + + #### func (Int32) TypeName() string + *** + + #### func (Int32) Zero() any + *** + + #### func (Int32) Parse(value string) any + *** + ### Int64 `STRUCT` ```go type Int64 int64 ``` + + #### func (Int64) TypeName() string + *** + + #### func (Int64) Zero() any + *** + + #### func (Int64) Parse(value string) any + *** + ### Uint `STRUCT` ```go type Uint uint ``` + + #### func (Uint) TypeName() string + *** + + #### func (Uint) Zero() any + *** + + #### func (Uint) Parse(value string) any + *** + ### Uint8 `STRUCT` ```go type Uint8 uint8 ``` + + #### func (Uint8) TypeName() string + *** + + #### func (Uint8) Zero() any + *** + + #### func (Uint8) Parse(value string) any + *** + ### Uint16 `STRUCT` ```go type Uint16 uint16 ``` + + #### func (Uint16) TypeName() string + *** + + #### func (Uint16) Zero() any + *** + + #### func (Uint16) Parse(value string) any + *** + ### Uint32 `STRUCT` ```go type Uint32 uint32 ``` + + #### func (Uint32) TypeName() string + *** + + #### func (Uint32) Zero() any + *** + + #### func (Uint32) Parse(value string) any + *** + ### Uint64 `STRUCT` ```go type Uint64 uint64 ``` + + #### func (Uint64) TypeName() string + *** + + #### func (Uint64) Zero() any + *** + + #### func (Uint64) Parse(value string) any + *** + ### Float32 `STRUCT` ```go type Float32 float32 ``` + + #### func (Float32) TypeName() string + *** + + #### func (Float32) Zero() any + *** + + #### func (Float32) Parse(value string) any + *** + ### Float64 `STRUCT` ```go type Float64 float64 ``` + + #### func (Float64) TypeName() string + *** + + #### func (Float64) Zero() any + *** + + #### func (Float64) Parse(value string) any + *** + ### String `STRUCT` ```go type String string ``` + + #### func (String) TypeName() string + *** + + #### func (String) Zero() any + *** + + #### func (String) Parse(value string) any + *** + ### Bool `STRUCT` ```go type Bool bool ``` + + #### func (Bool) TypeName() string + *** + + #### func (Bool) Zero() any + *** + + #### func (Bool) Parse(value string) any + *** + ### Byte `STRUCT` ```go type Byte byte ``` + + #### func (Byte) TypeName() string + *** + + #### func (Byte) Zero() any + *** + + #### func (Byte) Parse(value string) any + *** + ### Rune `STRUCT` ```go type Rune rune ``` + + #### func (Rune) TypeName() string + *** + + #### func (Rune) Zero() any + *** + + #### func (Rune) Parse(value string) any + *** + ### Complex64 `STRUCT` ```go type Complex64 complex64 ``` + + #### func (Complex64) TypeName() string + *** + + #### func (Complex64) Zero() any + *** + + #### func (Complex64) Parse(value string) any + *** + ### Complex128 `STRUCT` ```go type Complex128 complex128 ``` + + #### func (Complex128) TypeName() string + *** + + #### func (Complex128) Zero() any + *** + + #### func (Complex128) Parse(value string) any + *** + ### Uintptr `STRUCT` ```go type Uintptr uintptr ``` + + #### func (Uintptr) TypeName() string + *** + + #### func (Uintptr) Zero() any + *** + + #### func (Uintptr) Parse(value string) any + *** + ### Double `STRUCT` ```go type Double float64 ``` + + #### func (Double) TypeName() string + *** + + #### func (Double) Zero() any + *** + + #### func (Double) Parse(value string) any + *** + ### Float `STRUCT` ```go type Float float32 ``` + + #### func (Float) TypeName() string + *** + + #### func (Float) Zero() any + *** + + #### func (Float) Parse(value string) any + *** + ### Long `STRUCT` ```go type Long int64 ``` + + #### func (Long) TypeName() string + *** + + #### func (Long) Zero() any + *** + + #### func (Long) Parse(value string) any + *** + ### Short `STRUCT` ```go type Short int16 ``` + + #### func (Short) TypeName() string + *** + + #### func (Short) Zero() any + *** + + #### func (Short) Parse(value string) any + *** + ### Char `STRUCT` ```go type Char int8 ``` + + #### func (Char) TypeName() string + *** + + #### func (Char) Zero() any + *** + + #### func (Char) Parse(value string) any + *** + ### Number `STRUCT` ```go type Number float64 ``` + + #### func (Number) TypeName() string + *** + + #### func (Number) Zero() any + *** + + #### func (Number) Parse(value string) any + *** + ### Integer `STRUCT` ```go type Integer int64 ``` + + #### func (Integer) TypeName() string + *** + + #### func (Integer) Zero() any + *** + + #### func (Integer) Parse(value string) any + *** + ### Boolean `STRUCT` ```go type Boolean bool ``` + + #### func (Boolean) TypeName() string + *** + + #### func (Boolean) Zero() any + *** + + #### func (Boolean) Parse(value string) any + *** + ### Loader `STRUCT` 配置加载器 ```go @@ -451,12 +732,19 @@ type Loader struct { fields map[string]Field } ``` + + #### func (*Loader) LoadStruct(config Config) *TmplStruct > 加载结构 + *** + + #### func (*Loader) LoadData(config Config) map[any]any > 加载配置并得到配置数据 + *** + ### DataInfo `STRUCT` 配置数据 ```go @@ -465,6 +753,7 @@ type DataInfo struct { Value string } ``` + ### DataField `STRUCT` 配置数据字段 ```go @@ -476,6 +765,7 @@ type DataField struct { ExportType string } ``` + ### Tmpl `INTERFACE` 配置结构模板接口 ```go @@ -483,6 +773,7 @@ type Tmpl interface { Render(templates ...*TmplStruct) (string, error) } ``` + ### TmplField `STRUCT` 模板字段 ```go @@ -496,15 +787,25 @@ type TmplField struct { isIndex bool } ``` + + #### func (*TmplField) IsIndex() bool > 是否是索引字段 + *** + + #### func (*TmplField) IsStruct() bool > 是否是结构类型 + *** + + #### func (*TmplField) IsSlice() bool > 是否是切片类型 + *** + ### TmplStruct `STRUCT` 模板结构 ```go @@ -515,6 +816,9 @@ type TmplStruct struct { IndexCount int } ``` + + #### func (*TmplStruct) AllChildren() []*TmplStruct > 获取所有子结构 + *** diff --git a/planner/pce/cs/README.md b/planner/pce/cs/README.md index 87e0cde..1af49eb 100644 --- a/planner/pce/cs/README.md +++ b/planner/pce/cs/README.md @@ -23,23 +23,25 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[XlsxExportType](#xlsxexporttype)|暂无描述... -|`STRUCT`|[Xlsx](#xlsx)|内置的 Xlsx 配置 +|`STRUCT`|[XlsxExportType](#struct_XlsxExportType)|暂无描述... +|`STRUCT`|[Xlsx](#struct_Xlsx)|内置的 Xlsx 配置 *** ## 详情信息 -#### func NewXlsx(sheet *xlsx.Sheet, exportType XlsxExportType) *Xlsx +#### func NewXlsx(sheet *xlsx.Sheet, exportType XlsxExportType) *Xlsx *** + ### XlsxExportType `STRUCT` ```go type XlsxExportType int ``` + ### Xlsx `STRUCT` 内置的 Xlsx 配置 ```go @@ -48,15 +50,33 @@ type Xlsx struct { exportType XlsxExportType } ``` + + #### func (*Xlsx) GetConfigName() string + *** + + #### func (*Xlsx) GetDisplayName() string + *** + + #### func (*Xlsx) GetDescription() string + *** + + #### func (*Xlsx) GetIndexCount() int + *** + + #### func (*Xlsx) GetFields() []pce.DataField + *** + + #### func (*Xlsx) GetData() [][]pce.DataInfo + *** diff --git a/planner/pce/tmpls/README.md b/planner/pce/tmpls/README.md index e0b1bb7..cd38f58 100644 --- a/planner/pce/tmpls/README.md +++ b/planner/pce/tmpls/README.md @@ -24,23 +24,24 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Golang](#golang)|配置导出模板 -|`STRUCT`|[JSON](#json)|暂无描述... +|`STRUCT`|[Golang](#struct_Golang)|配置导出模板 +|`STRUCT`|[JSON](#struct_JSON)|暂无描述... *** ## 详情信息 -#### func NewGolang(packageName string) *Golang +#### func NewGolang(packageName string) *Golang > 创建一个 Golang 配置导出模板 *** -#### func NewJSON() *JSON +#### func NewJSON() *JSON *** + ### Golang `STRUCT` 配置导出模板 ```go @@ -49,14 +50,27 @@ type Golang struct { Templates []*pce.TmplStruct } ``` -#### func (*Golang) Render(templates ...*pce.TmplStruct) string, error + + +#### func (*Golang) Render(templates ...*pce.TmplStruct) ( string, error) + *** + + #### func (*Golang) GetVariable(config *pce.TmplStruct) string + *** + + #### func (*Golang) GetConfigName(config *pce.TmplStruct) string + *** + + #### func (*Golang) HasIndex(config *pce.TmplStruct) bool + *** + ### JSON `STRUCT` ```go @@ -64,5 +78,8 @@ type JSON struct { jsonIter.API } ``` -#### func (*JSON) Render(data map[any]any) string, error + + +#### func (*JSON) Render(data map[any]any) ( string, error) + *** diff --git a/server/README.md b/server/README.md index a79cad6..25df78f 100644 --- a/server/README.md +++ b/server/README.md @@ -47,6 +47,8 @@ server 提供了包含多种网络类型的服务器实现 |[WithWebsocketMessageType](#WithWebsocketMessageType)|设置仅支持特定类型的Websocket消息 |[WithPProf](#WithPProf)|通过性能分析工具PProf创建服务器 |[New](#New)|根据特定网络类型创建一个服务器 +|[LoadData](#LoadData)|加载绑定的服务器数据 +|[BindData](#BindData)|绑定数据到特定服务器 |[BindService](#BindService)|绑定服务到特定 Server，被绑定的服务将会在 Server 初始化时执行 Service.OnInit 方法 @@ -54,33 +56,33 @@ server 提供了包含多种网络类型的服务器实现 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Bot](#bot)|暂无描述... -|`STRUCT`|[BotOption](#botoption)|暂无描述... -|`STRUCT`|[Conn](#conn)|服务器连接单次消息的包装 -|`STRUCT`|[ConsoleParams](#consoleparams)|控制台参数 -|`STRUCT`|[MessageReadyEventHandler](#messagereadyeventhandler)|暂无描述... -|`STRUCT`|[Http](#http)|基于 gin.Engine 包装的 http 服务器 -|`STRUCT`|[HttpContext](#httpcontext)|基于 gin.Context 的 http 请求上下文 -|`STRUCT`|[HandlerFunc](#handlerfunc)|暂无描述... -|`STRUCT`|[ContextPacker](#contextpacker)|暂无描述... -|`STRUCT`|[HttpRouter](#httprouter)|暂无描述... -|`STRUCT`|[HttpWrapperHandleFunc](#httpwrapperhandlefunc)|暂无描述... -|`STRUCT`|[HttpWrapper](#httpwrapper)|http 包装器 -|`STRUCT`|[HttpWrapperGroup](#httpwrappergroup)|http 包装器 -|`STRUCT`|[MessageType](#messagetype)|暂无描述... -|`STRUCT`|[Message](#message)|服务器消息 -|`STRUCT`|[MultipleServer](#multipleserver)|暂无描述... -|`STRUCT`|[Network](#network)|暂无描述... -|`STRUCT`|[Option](#option)|暂无描述... -|`STRUCT`|[Server](#server)|网络服务器 -|`INTERFACE`|[Service](#service)|兼容传统 service 设计模式的接口 +|`STRUCT`|[Bot](#struct_Bot)|暂无描述... +|`STRUCT`|[BotOption](#struct_BotOption)|暂无描述... +|`STRUCT`|[Conn](#struct_Conn)|服务器连接单次消息的包装 +|`STRUCT`|[ConsoleParams](#struct_ConsoleParams)|控制台参数 +|`STRUCT`|[MessageReadyEventHandler](#struct_MessageReadyEventHandler)|暂无描述... +|`STRUCT`|[Http](#struct_Http)|基于 gin.Engine 包装的 http 服务器 +|`STRUCT`|[HttpContext](#struct_HttpContext)|基于 gin.Context 的 http 请求上下文 +|`STRUCT`|[HandlerFunc](#struct_HandlerFunc)|暂无描述... +|`STRUCT`|[ContextPacker](#struct_ContextPacker)|暂无描述... +|`STRUCT`|[HttpRouter](#struct_HttpRouter)|暂无描述... +|`STRUCT`|[HttpWrapperHandleFunc](#struct_HttpWrapperHandleFunc)|暂无描述... +|`STRUCT`|[HttpWrapper](#struct_HttpWrapper)|http 包装器 +|`STRUCT`|[HttpWrapperGroup](#struct_HttpWrapperGroup)|http 包装器 +|`STRUCT`|[MessageType](#struct_MessageType)|暂无描述... +|`STRUCT`|[Message](#struct_Message)|服务器消息 +|`STRUCT`|[MultipleServer](#struct_MultipleServer)|暂无描述... +|`STRUCT`|[Network](#struct_Network)|服务器运行的网络模式 +|`STRUCT`|[Option](#struct_Option)|暂无描述... +|`STRUCT`|[Server](#struct_Server)|网络服务器 +|`INTERFACE`|[Service](#struct_Service)|兼容传统 service 设计模式的接口，通过该接口可以实现更简洁、更具有可读性的服务绑定 *** ## 详情信息 -#### func NewBot(srv *Server, options ...BotOption) *Bot +#### func NewBot(srv *Server, options ...BotOption) *Bot > 创建一个机器人，目前仅支持 Socket 服务器 @@ -122,193 +124,76 @@ func TestNewBot(t *testing.T) { *** -#### func WithBotNetworkDelay(delay time.Duration, fluctuation time.Duration) BotOption +#### func WithBotNetworkDelay(delay time.Duration, fluctuation time.Duration) BotOption > 设置机器人网络延迟及波动范围 > - delay 延迟 > - fluctuation 波动范围 *** -#### func WithBotWriter(construction func (bot *Bot) io.Writer) BotOption +#### func WithBotWriter(construction func (bot *Bot) io.Writer) BotOption > 设置机器人写入器，默认为 os.Stdout *** -#### func DefaultWebsocketUpgrader() *websocket.Upgrader +#### func DefaultWebsocketUpgrader() *websocket.Upgrader *** -#### func NewHttpHandleWrapper(srv *Server, packer ContextPacker[Context]) *Http[Context] +#### func NewHttpHandleWrapper\[Context any\](srv *Server, packer ContextPacker[Context]) *Http[Context] > 创建一个新的 http 处理程序包装器 > - 默认使用 server.HttpContext 作为上下文，如果需要依赖其作为新的上下文，可以通过 NewHttpContext 创建 *** -#### func NewHttpContext(ctx *gin.Context) *HttpContext +#### func NewHttpContext(ctx *gin.Context) *HttpContext > 基于 gin.Context 创建一个新的 HttpContext *** -#### func NewGinWrapper(server *gin.Engine, pack func (ctx *gin.Context) CTX) *HttpWrapper[CTX] +#### func NewGinWrapper\[CTX any\](server *gin.Engine, pack func (ctx *gin.Context) CTX) *HttpWrapper[CTX] > 创建 gin 包装器，用于对 NewHttpWrapper 函数的替代 *** -#### func HasMessageType(mt MessageType) bool +#### func HasMessageType(mt MessageType) bool > 检查是否存在指定的消息类型 *** -#### func NewMultipleServer(serverHandle ...func () ((addr string, srv *Server))) *MultipleServer +#### func NewMultipleServer(serverHandle ...func () ((addr string, srv *Server))) *MultipleServer *** -#### func GetNetworks() []Network +#### func GetNetworks() []Network > 获取所有支持的网络模式 *** -#### func WithLowMessageDuration(duration time.Duration) Option +#### func WithLowMessageDuration(duration time.Duration) Option > 通过指定慢消息时长的方式创建服务器，当消息处理时间超过指定时长时，将会输出 WARN 类型的日志 > - 默认值为 DefaultLowMessageDuration > - 当 duration <= 0 时，表示关闭慢消息检测 -*** -#### func WithAsyncLowMessageDuration(duration time.Duration) Option - -> 通过指定异步消息的慢消息时长的方式创建服务器，当消息处理时间超过指定时长时，将会输出 WARN 类型的日志 -> - 默认值为 DefaultAsyncLowMessageDuration -> - 当 duration <= 0 时，表示关闭慢消息检测 +**示例代码：** -*** -#### func WithWebsocketConnInitializer(initializer func (writer http.ResponseWriter, request *http.Request, conn *websocket.Conn) error) Option - -> 通过 websocket 连接初始化的方式创建服务器，当 initializer 返回错误时，服务器将不会处理该连接的后续逻辑 -> - 该选项仅在创建 NetworkWebsocket 服务器时有效 +服务器在启动时将阻塞 1s，模拟了慢消息的过程，这时候如果通过 RegMessageLowExecEvent 函数注册过慢消息事件，将会收到该事件的消息 + - 该示例中，将在收到慢消息时关闭服务器 -*** -#### func WithWebsocketUpgrade(upgrader *websocket.Upgrader) Option - -> 通过指定 websocket.Upgrader 的方式创建服务器 -> - 默认值为 DefaultWebsocketUpgrader -> - 该选项仅在创建 NetworkWebsocket 服务器时有效 -*** -#### func WithConnWriteBufferSize(size int) Option - -> 通过连接写入缓冲区大小的方式创建服务器 -> - 默认值为 DefaultConnWriteBufferSize -> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存 - -*** -#### func WithDispatcherBufferSize(size int) Option - -> 通过消息分发器缓冲区大小的方式创建服务器 -> - 默认值为 DefaultDispatcherBufferSize -> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存 - -*** -#### func WithMessageStatistics(duration time.Duration, limit int) Option - -> 通过消息统计的方式创建服务器 -> - 默认不开启，当 duration 和 limit 均大于 0 的时候，服务器将记录每 duration 期间的消息数量，并保留最多 limit 条 - -*** -#### func WithPacketWarnSize(size int) Option - -> 通过数据包大小警告的方式创建服务器，当数据包大小超过指定大小时，将会输出 WARN 类型的日志 -> - 默认值为 DefaultPacketWarnSize -> - 当 size <= 0 时，表示不设置警告 - -*** -#### func WithLimitLife(t time.Duration) Option - -> 通过限制最大生命周期的方式创建服务器 -> - 通常用于测试服务器，服务器将在到达最大生命周期时自动关闭 - -*** -#### func WithWebsocketWriteCompression() Option - -> 通过数据写入压缩的方式创建Websocket服务器 -> - 默认不开启数据压缩 - -*** -#### func WithWebsocketCompression(level int) Option - -> 通过数据压缩的方式创建Websocket服务器 -> - 默认不开启数据压缩 - -*** -#### func WithDeadlockDetect(t time.Duration) Option - -> 通过死锁、死循环、永久阻塞检测的方式创建服务器 -> - 当检测到死锁、死循环、永久阻塞时，服务器将会生成 WARN 类型的日志，关键字为 "SuspectedDeadlock" -> - 默认不开启死锁检测 - -*** -#### func WithDisableAsyncMessage() Option - -> 通过禁用异步消息的方式创建服务器 - -*** -#### func WithAsyncPoolSize(size int) Option - -> 通过指定异步消息池大小的方式创建服务器 -> - 当通过 WithDisableAsyncMessage 禁用异步消息时，此选项无效 -> - 默认值为 DefaultAsyncPoolSize - -*** -#### func WithWebsocketReadDeadline(t time.Duration) Option - -> 设置 Websocket 读取超时时间 -> - 默认： DefaultWebsocketReadDeadline -> - 当 t <= 0 时，表示不设置超时时间 - -*** -#### func WithTicker(poolSize int, size int, connSize int, autonomy bool) Option - -> 通过定时器创建服务器，为服务器添加定时器功能 -> - poolSize：指定服务器定时器池大小，当池子内的定时器数量超出该值后，多余的定时器在释放时将被回收，该值小于等于 0 时将使用 timer.DefaultTickerPoolSize -> - size：服务器定时器时间轮大小 -> - connSize：服务器连接定时器时间轮大小，当该值小于等于 0 的时候，在新连接建立时将不再为其创建定时器 -> - autonomy：定时器是否独立运行（独立运行的情况下不会作为服务器消息运行，会导致并发问题） - -*** -#### func WithTLS(certFile string, keyFile string) Option - -> 通过安全传输层协议TLS创建服务器 -> - 支持：Http、Websocket - -*** -#### func WithGRPCServerOptions(options ...grpc.ServerOption) Option - -> 通过GRPC的可选项创建GRPC服务器 - -*** -#### func WithWebsocketMessageType(messageTypes ...int) Option - -> 设置仅支持特定类型的Websocket消息 - -*** -#### func WithPProf(pattern ...string) Option - -> 通过性能分析工具PProf创建服务器 - -*** -#### func New(network Network, options ...Option) *Server - -> 根据特定网络类型创建一个服务器 - -示例代码： ```go -func ExampleNew() { - srv := server.New(server.NetworkWebsocket, server.WithLimitLife(time.Millisecond)) - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) +func ExampleWithLowMessageDuration() { + srv := server.New(server.NetworkNone, server.WithLowMessageDuration(time.Second)) + srv.RegStartFinishEvent(func(srv *server.Server) { + time.Sleep(time.Second) }) - if err := srv.Run(":9999"); err != nil { + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + srv.Shutdown() + fmt.Println(times.GetSecond(cost)) + }) + if err := srv.RunNone(); err != nil { panic(err) } } @@ -321,22 +206,45 @@ func ExampleNew() { ```go -func TestNew(t *testing.T) { - srv := server.New(server.NetworkWebsocket, server.WithPProf()) - srv.RegStartBeforeEvent(func(srv *server.Server) { - fmt.Println("启动前") - }) - srv.RegStartFinishEvent(func(srv *server.Server) { - fmt.Println("启动完成") - }) - srv.RegConnectionClosedEvent(func(srv *server.Server, conn *server.Conn, err any) { - fmt.Println("关闭", conn.GetID(), err, "IncrCount", srv.GetOnlineCount()) - }) - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) - if err := srv.Run(":9999"); err != nil { - panic(err) +func TestWithLowMessageDuration(t *testing.T) { + var cases = []struct { + name string + duration time.Duration + }{{name: "TestWithLowMessageDuration", duration: server.DefaultLowMessageDuration}, {name: "TestWithLowMessageDuration_Zero", duration: 0}, {name: "TestWithLowMessageDuration_Negative", duration: -server.DefaultAsyncLowMessageDuration}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + networks := server.GetNetworks() + for i := 0; i < len(networks); i++ { + low := false + network := networks[i] + srv := server.New(network, server.WithLowMessageDuration(c.duration)) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + low = true + srv.Shutdown() + }) + srv.RegStartFinishEvent(func(srv *server.Server) { + if c.duration <= 0 { + srv.Shutdown() + return + } + time.Sleep(server.DefaultLowMessageDuration) + }) + var lis string + switch network { + case server.NetworkNone, server.NetworkUnix: + lis = "addr" + default: + lis = fmt.Sprintf(":%d", random.UsablePort()) + } + if err := srv.Run(lis); err != nil { + t.Fatalf("%s run error: %s", network, err) + } + if !low && c.duration > 0 { + t.Fatalf("%s low message not exec", network) + } + } + }) } } @@ -346,12 +254,314 @@ func TestNew(t *testing.T) { +*** +#### func WithAsyncLowMessageDuration(duration time.Duration) Option + +> 通过指定异步消息的慢消息时长的方式创建服务器，当消息处理时间超过指定时长时，将会输出 WARN 类型的日志 +> - 默认值为 DefaultAsyncLowMessageDuration +> - 当 duration <= 0 时，表示关闭慢消息检测 + +**示例代码：** + +服务器在启动时将发布一条阻塞 1s 的异步消息，模拟了慢消息的过程，这时候如果通过 RegMessageLowExecEvent 函数注册过慢消息事件，将会收到该事件的消息 + - 该示例中，将在收到慢消息时关闭服务器 + + +```go + +func ExampleWithAsyncLowMessageDuration() { + srv := server.New(server.NetworkNone, server.WithAsyncLowMessageDuration(time.Second)) + srv.RegStartFinishEvent(func(srv *server.Server) { + srv.PushAsyncMessage(func() error { + time.Sleep(time.Second) + return nil + }, nil) + }) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + srv.Shutdown() + fmt.Println(times.GetSecond(cost)) + }) + if err := srv.RunNone(); err != nil { + panic(err) + } +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestWithAsyncLowMessageDuration(t *testing.T) { + var cases = []struct { + name string + duration time.Duration + }{{name: "TestWithAsyncLowMessageDuration", duration: time.Millisecond * 100}, {name: "TestWithAsyncLowMessageDuration_Zero", duration: 0}, {name: "TestWithAsyncLowMessageDuration_Negative", duration: -server.DefaultAsyncLowMessageDuration}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + networks := server.GetNetworks() + for i := 0; i < len(networks); i++ { + low := false + network := networks[i] + srv := server.New(network, server.WithAsyncLowMessageDuration(c.duration)) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + low = true + srv.Shutdown() + }) + srv.RegStartFinishEvent(func(srv *server.Server) { + if c.duration <= 0 { + srv.Shutdown() + return + } + srv.PushAsyncMessage(func() error { + time.Sleep(c.duration) + return nil + }, nil) + }) + var lis string + switch network { + case server.NetworkNone, server.NetworkUnix: + lis = fmt.Sprintf("%s%d", "addr", random.Int(0, 9999)) + default: + lis = fmt.Sprintf(":%d", random.UsablePort()) + } + if err := srv.Run(lis); err != nil { + t.Fatalf("%s run error: %s", network, err) + } + if !low && c.duration > 0 { + t.Fatalf("%s low message not exec", network) + } + } + }) + } +} + +``` + + +
+ + +*** +#### func WithWebsocketConnInitializer(initializer func (writer http.ResponseWriter, request *http.Request, conn *websocket.Conn) error) Option + +> 通过 websocket 连接初始化的方式创建服务器，当 initializer 返回错误时，服务器将不会处理该连接的后续逻辑 +> - 该选项仅在创建 NetworkWebsocket 服务器时有效 + +*** +#### func WithWebsocketUpgrade(upgrader *websocket.Upgrader) Option + +> 通过指定 websocket.Upgrader 的方式创建服务器 +> - 默认值为 DefaultWebsocketUpgrader +> - 该选项仅在创建 NetworkWebsocket 服务器时有效 + +*** +#### func WithConnWriteBufferSize(size int) Option + +> 通过连接写入缓冲区大小的方式创建服务器 +> - 默认值为 DefaultConnWriteBufferSize +> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存 + +*** +#### func WithDispatcherBufferSize(size int) Option + +> 通过消息分发器缓冲区大小的方式创建服务器 +> - 默认值为 DefaultDispatcherBufferSize +> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存 + +*** +#### func WithMessageStatistics(duration time.Duration, limit int) Option + +> 通过消息统计的方式创建服务器 +> - 默认不开启，当 duration 和 limit 均大于 0 的时候，服务器将记录每 duration 期间的消息数量，并保留最多 limit 条 + +*** +#### func WithPacketWarnSize(size int) Option + +> 通过数据包大小警告的方式创建服务器，当数据包大小超过指定大小时，将会输出 WARN 类型的日志 +> - 默认值为 DefaultPacketWarnSize +> - 当 size <= 0 时，表示不设置警告 + +*** +#### func WithLimitLife(t time.Duration) Option + +> 通过限制最大生命周期的方式创建服务器 +> - 通常用于测试服务器，服务器将在到达最大生命周期时自动关闭 + +*** +#### func WithWebsocketWriteCompression() Option + +> 通过数据写入压缩的方式创建Websocket服务器 +> - 默认不开启数据压缩 + +*** +#### func WithWebsocketCompression(level int) Option + +> 通过数据压缩的方式创建Websocket服务器 +> - 默认不开启数据压缩 + +*** +#### func WithDeadlockDetect(t time.Duration) Option + +> 通过死锁、死循环、永久阻塞检测的方式创建服务器 +> - 当检测到死锁、死循环、永久阻塞时，服务器将会生成 WARN 类型的日志，关键字为 "SuspectedDeadlock" +> - 默认不开启死锁检测 + +*** +#### func WithDisableAsyncMessage() Option + +> 通过禁用异步消息的方式创建服务器 + +*** +#### func WithAsyncPoolSize(size int) Option + +> 通过指定异步消息池大小的方式创建服务器 +> - 当通过 WithDisableAsyncMessage 禁用异步消息时，此选项无效 +> - 默认值为 DefaultAsyncPoolSize + +*** +#### func WithWebsocketReadDeadline(t time.Duration) Option + +> 设置 Websocket 读取超时时间 +> - 默认： DefaultWebsocketReadDeadline +> - 当 t <= 0 时，表示不设置超时时间 + +*** +#### func WithTicker(poolSize int, size int, connSize int, autonomy bool) Option + +> 通过定时器创建服务器，为服务器添加定时器功能 +> - poolSize：指定服务器定时器池大小，当池子内的定时器数量超出该值后，多余的定时器在释放时将被回收，该值小于等于 0 时将使用 timer.DefaultTickerPoolSize +> - size：服务器定时器时间轮大小 +> - connSize：服务器连接定时器时间轮大小，当该值小于等于 0 的时候，在新连接建立时将不再为其创建定时器 +> - autonomy：定时器是否独立运行（独立运行的情况下不会作为服务器消息运行，会导致并发问题） + +*** +#### func WithTLS(certFile string, keyFile string) Option + +> 通过安全传输层协议TLS创建服务器 +> - 支持：Http、Websocket + +*** +#### func WithGRPCServerOptions(options ...grpc.ServerOption) Option + +> 通过GRPC的可选项创建GRPC服务器 + +*** +#### func WithWebsocketMessageType(messageTypes ...int) Option + +> 设置仅支持特定类型的Websocket消息 + +*** +#### func WithPProf(pattern ...string) Option + +> 通过性能分析工具PProf创建服务器 + +*** +#### func New(network Network, options ...Option) *Server + +> 根据特定网络类型创建一个服务器 + +**示例代码：** + +该案例将创建一个简单的 WebSocket 服务器，如果需要更多的服务器类型可参考 [` Network `](#struct_Network) 部分 + - server.WithLimitLife(time.Millisecond) 通常不是在正常开发应该使用的，在这里只是为了让服务器在启动完成后的 1 毫秒后自动关闭 + +该案例的输出结果为 true + + +```go + +func ExampleNew() { + srv := server.New(server.NetworkWebsocket, server.WithLimitLife(time.Millisecond)) + fmt.Println(srv != nil) +} + +``` + +
+查看 / 收起单元测试 + + +该单元测试用于测试以不同的基本参数创建服务器是否存在异常 + + +```go + +func TestNew(t *testing.T) { + var cases = []struct { + name string + network server.Network + addr string + shouldPanic bool + }{{name: "TestNew_Unknown", addr: "", network: "Unknown", shouldPanic: true}, {name: "TestNew_None", addr: "", network: server.NetworkNone, shouldPanic: false}, {name: "TestNew_None_Addr", addr: "addr", network: server.NetworkNone, shouldPanic: false}, {name: "TestNew_Tcp_AddrEmpty", addr: "", network: server.NetworkTcp, shouldPanic: true}, {name: "TestNew_Tcp_AddrIllegal", addr: "addr", network: server.NetworkTcp, shouldPanic: true}, {name: "TestNew_Tcp_Addr", addr: ":9999", network: server.NetworkTcp, shouldPanic: false}, {name: "TestNew_Tcp4_AddrEmpty", addr: "", network: server.NetworkTcp4, shouldPanic: true}, {name: "TestNew_Tcp4_AddrIllegal", addr: "addr", network: server.NetworkTcp4, shouldPanic: true}, {name: "TestNew_Tcp4_Addr", addr: ":9999", network: server.NetworkTcp4, shouldPanic: false}, {name: "TestNew_Tcp6_AddrEmpty", addr: "", network: server.NetworkTcp6, shouldPanic: true}, {name: "TestNew_Tcp6_AddrIllegal", addr: "addr", network: server.NetworkTcp6, shouldPanic: true}, {name: "TestNew_Tcp6_Addr", addr: ":9999", network: server.NetworkTcp6, shouldPanic: false}, {name: "TestNew_Udp_AddrEmpty", addr: "", network: server.NetworkUdp, shouldPanic: true}, {name: "TestNew_Udp_AddrIllegal", addr: "addr", network: server.NetworkUdp, shouldPanic: true}, {name: "TestNew_Udp_Addr", addr: ":9999", network: server.NetworkUdp, shouldPanic: false}, {name: "TestNew_Udp4_AddrEmpty", addr: "", network: server.NetworkUdp4, shouldPanic: true}, {name: "TestNew_Udp4_AddrIllegal", addr: "addr", network: server.NetworkUdp4, shouldPanic: true}, {name: "TestNew_Udp4_Addr", addr: ":9999", network: server.NetworkUdp4, shouldPanic: false}, {name: "TestNew_Udp6_AddrEmpty", addr: "", network: server.NetworkUdp6, shouldPanic: true}, {name: "TestNew_Udp6_AddrIllegal", addr: "addr", network: server.NetworkUdp6, shouldPanic: true}, {name: "TestNew_Udp6_Addr", addr: ":9999", network: server.NetworkUdp6, shouldPanic: false}, {name: "TestNew_Unix_AddrEmpty", addr: "", network: server.NetworkUnix, shouldPanic: true}, {name: "TestNew_Unix_AddrIllegal", addr: "addr", network: server.NetworkUnix, shouldPanic: true}, {name: "TestNew_Unix_Addr", addr: "addr", network: server.NetworkUnix, shouldPanic: false}, {name: "TestNew_Websocket_AddrEmpty", addr: "", network: server.NetworkWebsocket, shouldPanic: true}, {name: "TestNew_Websocket_AddrIllegal", addr: "addr", network: server.NetworkWebsocket, shouldPanic: true}, {name: "TestNew_Websocket_Addr", addr: ":9999/ws", network: server.NetworkWebsocket, shouldPanic: false}, {name: "TestNew_Http_AddrEmpty", addr: "", network: server.NetworkHttp, shouldPanic: true}, {name: "TestNew_Http_AddrIllegal", addr: "addr", network: server.NetworkHttp, shouldPanic: true}, {name: "TestNew_Http_Addr", addr: ":9999", network: server.NetworkHttp, shouldPanic: false}, {name: "TestNew_Kcp_AddrEmpty", addr: "", network: server.NetworkKcp, shouldPanic: true}, {name: "TestNew_Kcp_AddrIllegal", addr: "addr", network: server.NetworkKcp, shouldPanic: true}, {name: "TestNew_Kcp_Addr", addr: ":9999", network: server.NetworkKcp, shouldPanic: false}, {name: "TestNew_GRPC_AddrEmpty", addr: "", network: server.NetworkGRPC, shouldPanic: true}, {name: "TestNew_GRPC_AddrIllegal", addr: "addr", network: server.NetworkGRPC, shouldPanic: true}, {name: "TestNew_GRPC_Addr", addr: ":9999", network: server.NetworkGRPC, shouldPanic: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if err := super.RecoverTransform(recover()); err != nil && !c.shouldPanic { + debug.PrintStack() + t.Fatal("not should panic, err:", err) + } + }() + if err := server.New(c.network, server.WithLimitLife(time.Millisecond*10)).Run(""); err != nil { + panic(err) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoadData\[T any\](srv *Server, name string, data any) T + +> 加载绑定的服务器数据 + +*** +#### func BindData(srv *Server, name string, data any) + +> 绑定数据到特定服务器 + *** #### func BindService(srv *Server, services ...Service) > 绑定服务到特定 Server，被绑定的服务将会在 Server 初始化时执行 Service.OnInit 方法 -示例代码： +**示例代码：** + +这个案例中我们将 `TestService` 绑定到了 `srv` 服务器中，当服务器启动时，将会对 `TestService` 进行初始化 + +其中 `TestService` 的定义如下： +```go + + type TestService struct{} + + func (ts *TestService) OnInit(srv *server.Server) { + srv.RegStartFinishEvent(onStartFinish) + + srv.RegStopEvent(func(srv *server.Server) { + fmt.Println("server stop") + }) + } + + func (ts *TestService) onStartFinish(srv *server.Server) { + fmt.Println("server start finish") + } + +``` + +可以看出，在服务初始化时，该服务向服务器注册了启动完成事件及停止事件。这是我们推荐的编码方式，这样编码有以下好处： + - 具备可控制的初始化顺序，避免 init 产生的各种顺序导致的问题，如配置还未加载完成，即开始进行数据库连接等操作 + - 可以方便的将不同的服务拆分到不同的包中进行管理 + - 当不需要某个服务时，可以直接删除该服务的绑定，而不需要修改其他代码 + - ... + + ```go func ExampleBindService() { @@ -371,10 +581,15 @@ func ExampleBindService() { ```go func TestBindService(t *testing.T) { - srv := server.New(server.NetworkNone, server.WithLimitLife(time.Second)) - server.BindService(srv, new(TestService)) - if err := srv.RunNone(); err != nil { - t.Fatal(err) + var cases = []struct{ name string }{{name: "TestBindService"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + srv := server.New(server.NetworkNone, server.WithLimitLife(time.Millisecond)) + server.BindService(srv, new(TestService)) + if err := srv.RunNone(); err != nil { + t.Fatal(err) + } + }) } } @@ -385,6 +600,7 @@ func TestBindService(t *testing.T) { *** + ### Bot `STRUCT` ```go @@ -393,31 +609,51 @@ type Bot struct { joined atomic.Bool } ``` + + #### func (*Bot) JoinServer() > 加入服务器 + *** + + #### func (*Bot) LeaveServer() > 离开服务器 + *** + + #### func (*Bot) SetNetworkDelay(delay time.Duration, fluctuation time.Duration) > 设置网络延迟和波动范围 > - delay 延迟 > - fluctuation 波动范围 + *** + + #### func (*Bot) SetWriter(writer io.Writer) > 设置写入器 + *** + + #### func (*Bot) SendPacket(packet []byte) > 发送数据包到服务器 + *** + + #### func (*Bot) SendWSPacket(wst int, packet []byte) > 发送 WebSocket 数据包到服务器 + *** + ### BotOption `STRUCT` ```go type BotOption func(bot *Bot) ``` + ### Conn `STRUCT` 服务器连接单次消息的包装 ```go @@ -427,111 +663,204 @@ type Conn struct { ctx context.Context } ``` + + #### func (*Conn) Ticker() *timer.Ticker > 获取定时器 + *** + + #### func (*Conn) GetServer() *Server > 获取服务器 + *** + + #### func (*Conn) GetOpenTime() time.Time > 获取连接打开时间 + *** + + #### func (*Conn) GetOnlineTime() time.Duration > 获取连接在线时长 + *** + + #### func (*Conn) GetWebsocketRequest() *http.Request > 获取websocket请求 + *** + + #### func (*Conn) IsBot() bool > 是否是机器人连接 + *** + + #### func (*Conn) RemoteAddr() net.Addr > 获取远程地址 + *** + + #### func (*Conn) GetID() string > 获取连接ID > - 为远程地址的字符串形式 + *** + + #### func (*Conn) GetIP() string > 获取连接IP + *** + + #### func (*Conn) IsClosed() bool > 是否已经关闭 + *** + + #### func (*Conn) SetData(key any, value any) *Conn > 设置连接数据，该数据将在连接关闭前始终存在 + *** + + #### func (*Conn) GetData(key any) any > 获取连接数据 + *** + + #### func (*Conn) ViewData() map[any]any > 查看只读的连接数据 + *** + + #### func (*Conn) SetMessageData(key any, value any) *Conn > 设置消息数据，该数据将在消息处理完成后释放 + *** + + #### func (*Conn) GetMessageData(key any) any > 获取消息数据 + *** + + #### func (*Conn) ReleaseData() *Conn > 释放数据 + *** + + #### func (*Conn) IsWebsocket() bool > 是否是websocket连接 + *** + + #### func (*Conn) GetWST() int > 获取本次 websocket 消息类型 > - 默认将与发送类型相同 + *** + + #### func (*Conn) SetWST(wst int) *Conn > 设置本次 websocket 消息类型 + *** + + #### func (*Conn) PushAsyncMessage(caller func () error, callback func (err error), mark ...log.Field) > 推送异步消息，该消息将通过 Server.PushShuntAsyncMessage 函数推送 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Conn) PushUniqueAsyncMessage(name string, caller func () error, callback func (err error), mark ...log.Field) > 推送唯一异步消息，该消息将通过 Server.PushUniqueShuntAsyncMessage 函数推送 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 > - 不同的是当上一个相同的 unique 消息未执行完成时，将会忽略该消息 + *** + + #### func (*Conn) Write(packet []byte, callback ...func (err error)) > 向连接中写入数据 + *** + + #### func (*Conn) Close(err ...error) > 关闭连接 + *** + ### ConsoleParams `STRUCT` 控制台参数 ```go type ConsoleParams map[string][]string ``` + + #### func (ConsoleParams) Get(key string) string > 获取参数值 + *** + + #### func (ConsoleParams) GetValues(key string) []string > 获取参数值 + *** + + #### func (ConsoleParams) GetValueNum(key string) int > 获取参数值数量 + *** + + #### func (ConsoleParams) Has(key string) bool > 是否存在参数 + *** + + #### func (ConsoleParams) Add(key string, value string) > 添加参数 + *** + + #### func (ConsoleParams) Del(key string) > 删除参数 + *** + + #### func (ConsoleParams) Clear() > 清空参数 + *** + ### MessageReadyEventHandler `STRUCT` ```go type MessageReadyEventHandler func(srv *Server) ``` + ### Http `STRUCT` 基于 gin.Engine 包装的 http 服务器 ```go @@ -541,8 +870,12 @@ type Http[Context any] struct { *HttpRouter[Context] } ``` + + #### func (*Http) Gin() *gin.Engine + *** + ### HttpContext `STRUCT` 基于 gin.Context 的 http 请求上下文 ```go @@ -550,22 +883,31 @@ type HttpContext struct { *gin.Context } ``` + + #### func (*HttpContext) Gin() *gin.Context > 获取 gin.Context + *** + + #### func (*HttpContext) ReadTo(dest any) error > 读取请求数据到指定结构体，如果失败则返回错误 + *** + ### HandlerFunc `STRUCT` ```go type HandlerFunc[Context any] func(ctx Context) ``` + ### ContextPacker `STRUCT` ```go type ContextPacker[Context any] func(ctx *gin.Context) Context ``` + ### HttpRouter `STRUCT` ```go @@ -575,75 +917,131 @@ type HttpRouter[Context any] struct { packer ContextPacker[Context] } ``` + + #### func (*HttpRouter) Handle(httpMethod string, relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 使用给定的路径和方法注册新的请求句柄和中间件 > - 最后一个处理程序应该是真正的处理程序，其他处理程序应该是可以而且应该在不同路由之间共享的中间件。 + *** + + #### func (*HttpRouter) POST(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("POST", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) GET(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("GET", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) DELETE(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("DELETE", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) PATCH(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("PATCH", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) PUT(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("PUT", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) OPTIONS(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("OPTIONS", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) HEAD(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("HEAD", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) CONNECT(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("CONNECT", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) TRACE(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 是 Handle("TRACE", path, handlers) 的快捷方式 + *** + + #### func (*HttpRouter) Any(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 注册一个匹配所有 HTTP 方法的路由 > - GET, POST, PUT, PATCH, HEAD, OPTIONS, DELETE, CONNECT, TRACE. + *** + + #### func (*HttpRouter) Match(methods []string, relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 注册一个匹配指定 HTTP 方法的路由 > - GET, POST, PUT, PATCH, HEAD, OPTIONS, DELETE, CONNECT, TRACE. + *** + + #### func (*HttpRouter) StaticFile(relativePath string, filepath string) *HttpRouter[Context] > 注册单个路由以便为本地文件系统的单个文件提供服务。 > - 例如: StaticFile("favicon.ico", "./resources/favicon.ico") + *** + + #### func (*HttpRouter) StaticFileFS(relativePath string, filepath string, fs http.FileSystem) *HttpRouter[Context] > 与 `StaticFile` 类似，但可以使用自定义的 `http.FileSystem` 代替。 > - 例如: StaticFileFS("favicon.ico", "./resources/favicon.ico", Dir{".", false}) > - 由于依赖于 gin.Engine 默认情况下使用：gin.Dir + *** + + #### func (*HttpRouter) Static(relativePath string, root string) *HttpRouter[Context] > 提供来自给定文件系统根目录的文件。 > - 例如: Static("/static", "/var/www") + *** + + #### func (*HttpRouter) StaticFS(relativePath string, fs http.FileSystem) *HttpRouter[Context] > 与 `Static` 类似，但可以使用自定义的 `http.FileSystem` 代替。 > - 例如: StaticFS("/static", Dir{"/var/www", false}) > - 由于依赖于 gin.Engine 默认情况下使用：gin.Dir + *** + + #### func (*HttpRouter) Group(relativePath string, handlers ...HandlerFunc[Context]) *HttpRouter[Context] > 创建一个新的路由组。您应该添加所有具有共同中间件的路由。 > - 例如: v1 := slf.Group("/v1") + *** + + #### func (*HttpRouter) Use(middleware ...HandlerFunc[Context]) *HttpRouter[Context] > 将中间件附加到路由组。 + *** + ### HttpWrapperHandleFunc `STRUCT` ```go type HttpWrapperHandleFunc[CTX any] func(ctx CTX) ``` + ### HttpWrapper `STRUCT` http 包装器 ```go @@ -652,57 +1050,109 @@ type HttpWrapper[CTX any] struct { packHandle func(ctx *gin.Context) CTX } ``` + + #### func (*HttpWrapper) Handle(httpMethod string, relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 处理请求 + *** + + #### func (*HttpWrapper) Use(middleware ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 使用中间件 + *** + + #### func (*HttpWrapper) GET(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 GET 请求 + *** + + #### func (*HttpWrapper) POST(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 POST 请求 + *** + + #### func (*HttpWrapper) DELETE(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 DELETE 请求 + *** + + #### func (*HttpWrapper) PATCH(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 PATCH 请求 + *** + + #### func (*HttpWrapper) PUT(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 PUT 请求 + *** + + #### func (*HttpWrapper) OPTIONS(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 OPTIONS 请求 + *** + + #### func (*HttpWrapper) HEAD(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 HEAD 请求 + *** + + #### func (*HttpWrapper) Trace(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 Trace 请求 + *** + + #### func (*HttpWrapper) Connect(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 Connect 请求 + *** + + #### func (*HttpWrapper) Any(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册 Any 请求 + *** + + #### func (*HttpWrapper) Match(methods []string, relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapper[CTX] > 注册与您声明的指定方法相匹配的路由。 + *** + + #### func (*HttpWrapper) StaticFile(relativePath string, filepath string) *HttpWrapper[CTX] > 注册 StaticFile 请求 + *** + + #### func (*HttpWrapper) Static(relativePath string, root string) *HttpWrapper[CTX] > 注册 Static 请求 + *** + + #### func (*HttpWrapper) StaticFS(relativePath string, fs http.FileSystem) *HttpWrapper[CTX] > 注册 StaticFS 请求 + *** + + #### func (*HttpWrapper) Group(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 创建一个新的路由组。您应该添加所有具有共同中间件的路由。 + *** + ### HttpWrapperGroup `STRUCT` http 包装器 ```go @@ -711,41 +1161,73 @@ type HttpWrapperGroup[CTX any] struct { group *gin.RouterGroup } ``` + + #### func (*HttpWrapperGroup) Handle(httpMethod string, relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 处理请求 + *** + + #### func (*HttpWrapperGroup) Use(middleware ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 使用中间件 + *** + + #### func (*HttpWrapperGroup) GET(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 GET 请求 + *** + + #### func (*HttpWrapperGroup) POST(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 POST 请求 + *** + + #### func (*HttpWrapperGroup) DELETE(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 DELETE 请求 + *** + + #### func (*HttpWrapperGroup) PATCH(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 PATCH 请求 + *** + + #### func (*HttpWrapperGroup) PUT(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 PUT 请求 + *** + + #### func (*HttpWrapperGroup) OPTIONS(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 注册 OPTIONS 请求 + *** + + #### func (*HttpWrapperGroup) Group(relativePath string, handlers ...HttpWrapperHandleFunc[CTX]) *HttpWrapperGroup[CTX] > 创建分组 + *** + ### MessageType `STRUCT` ```go type MessageType byte ``` + + #### func (MessageType) String() string > 返回消息类型的字符串表示 + *** + ### Message `STRUCT` 服务器消息 ```go @@ -763,14 +1245,24 @@ type Message struct { t MessageType } ``` + + #### func (*Message) GetProducer() string + *** + + #### func (*Message) MessageType() MessageType > 返回消息类型 + *** + + #### func (*Message) String() string > 返回消息的字符串表示 + *** + ### MultipleServer `STRUCT` ```go @@ -780,26 +1272,65 @@ type MultipleServer struct { exitEventHandles []func() } ``` + + #### func (*MultipleServer) Run() + *** + + #### func (*MultipleServer) RegExitEvent(handle func ()) > 注册退出事件 -*** -#### func (*MultipleServer) OnExitEvent() -*** -### Network `STRUCT` +*** + + +#### func (*MultipleServer) OnExitEvent() + +*** + +### Network `STRUCT` +服务器运行的网络模式 + - 根据不同的网络模式，服务器将会产生不同的行为，该类型将在服务器创建时候指定 + +服务器支持的网络模式如下： + - NetworkNone 该模式下不监听任何网络端口，仅开启消息队列，适用于纯粹的跨服服务器等情况 + - NetworkTcp 该模式下将会监听 TCP 协议的所有地址，包括 IPv4 和 IPv6 + - NetworkTcp4 该模式下将会监听 TCP 协议的 IPv4 地址 + - NetworkTcp6 该模式下将会监听 TCP 协议的 IPv6 地址 + - NetworkUdp 该模式下将会监听 UDP 协议的所有地址，包括 IPv4 和 IPv6 + - NetworkUdp4 该模式下将会监听 UDP 协议的 IPv4 地址 + - NetworkUdp6 该模式下将会监听 UDP 协议的 IPv6 地址 + - NetworkUnix 该模式下将会监听 Unix 协议的地址 + - NetworkHttp 该模式下将会监听 HTTP 协议的地址 + - NetworkWebsocket 该模式下将会监听 Websocket 协议的地址 + - NetworkKcp 该模式下将会监听 KCP 协议的地址 + - NetworkGRPC 该模式下将会监听 GRPC 协议的地址 ```go type Network string ``` + + #### func (Network) IsSocket() bool -> 返回当前服务器的网络模式是否为 Socket 模式 +> 返回当前服务器的网络模式是否为 Socket 模式，目前为止仅有如下几种模式为 Socket 模式： +> - NetworkTcp +> - NetworkTcp4 +> - NetworkTcp6 +> - NetworkUdp +> - NetworkUdp4 +> - NetworkUdp6 +> - NetworkUnix +> - NetworkKcp +> - NetworkWebsocket + *** + ### Option `STRUCT` ```go type Option func(srv *Server) ``` + ### Server `STRUCT` 网络服务器 ```go @@ -821,6 +1352,7 @@ type Server struct { systemSignal chan os.Signal closeChannel chan struct{} multipleRuntimeErrorChan chan error + data map[string]any messageCounter atomic.Int64 addr string network Network @@ -828,6 +1360,20 @@ type Server struct { services []func() } ``` + + +#### func (*Server) LoadData(name string, data any) any +> 加载绑定的服务器数据 + +*** + + +#### func (*Server) BindData(name string, data any) +> 绑定数据到特定服务器 + +*** + + #### func (*Server) Run(addr string) (err error) > 使用特定地址运行服务器 > - server.NetworkTcp (addr:":8888") @@ -841,14 +1387,18 @@ type Server struct { > - server.NetworkWebsocket (addr:":8888/ws") > - server.NetworkKcp (addr:":8888") > - server.NetworkNone (addr:"") -示例代码： + +**示例代码：** + +该案例将创建一个简单的 WebSocket 服务器并启动监听 `:9999/` 作为 WebSocket 监听地址，如果需要更多的服务器类型可参考 [` Network `](#struct_Network) 部分 + - 当服务器启动失败后，将会返回错误信息并触发 panic + - server.WithLimitLife(time.Millisecond) 通常不是在正常开发应该使用的，在这里只是为了让服务器在启动完成后的 1 毫秒后自动关闭 + + ```go func ExampleServer_Run() { srv := server.New(server.NetworkWebsocket, server.WithLimitLife(time.Millisecond)) - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) if err := srv.Run(":9999"); err != nil { panic(err) } @@ -857,76 +1407,199 @@ func ExampleServer_Run() { ``` *** + + #### func (*Server) IsSocket() bool -> 是否是 Socket 模式 +> 通过执行 Network.IsSocket 函数检查该服务器是否是 Socket 模式 + +**示例代码：** + +该案例将创建两个不同类型的服务器，其中 WebSocket 是一个 Socket 服务器，而 Http 是一个非 Socket 服务器 + +可知案例输出结果为： + - true + - false + + +```go + +func ExampleServer_IsSocket() { + srv1 := server.New(server.NetworkWebsocket) + fmt.Println(srv1.IsSocket()) + srv2 := server.New(server.NetworkHttp) + fmt.Println(srv2.IsSocket()) +} + +``` + +
+查看 / 收起单元测试 + + +这个测试检查了各个类型的服务器是否为 Socket 模式。如需查看为 Socket 模式的网络类型，请参考 [` Network.IsSocket` ](#struct_Network_IsSocket) + + +```go + +func TestServer_IsSocket(t *testing.T) { + var cases = []struct { + name string + network server.Network + expect bool + }{{name: "TestServer_IsSocket_None", network: server.NetworkNone, expect: false}, {name: "TestServer_IsSocket_Tcp", network: server.NetworkTcp, expect: true}, {name: "TestServer_IsSocket_Tcp4", network: server.NetworkTcp4, expect: true}, {name: "TestServer_IsSocket_Tcp6", network: server.NetworkTcp6, expect: true}, {name: "TestServer_IsSocket_Udp", network: server.NetworkUdp, expect: true}, {name: "TestServer_IsSocket_Udp4", network: server.NetworkUdp4, expect: true}, {name: "TestServer_IsSocket_Udp6", network: server.NetworkUdp6, expect: true}, {name: "TestServer_IsSocket_Unix", network: server.NetworkUnix, expect: true}, {name: "TestServer_IsSocket_Http", network: server.NetworkHttp, expect: false}, {name: "TestServer_IsSocket_Websocket", network: server.NetworkWebsocket, expect: true}, {name: "TestServer_IsSocket_Kcp", network: server.NetworkKcp, expect: true}, {name: "TestServer_IsSocket_GRPC", network: server.NetworkGRPC, expect: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + s := server.New(c.network) + if s.IsSocket() != c.expect { + t.Fatalf("expect: %v, got: %v", c.expect, s.IsSocket()) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Server) RunNone() error > 是 Run("") 的简写，仅适用于运行 NetworkNone 服务器 + +**示例代码：** + +RunNone 函数并没有特殊的意义，该函数内部调用了 `srv.Run("")` 函数，仅是一个语法糖，用来表示服务器不需要监听任何地址 + + +```go + +func ExampleServer_RunNone() { + srv := server.New(server.NetworkNone) + if err := srv.RunNone(); err != nil { + panic(err) + } +} + +``` + *** + + #### func (*Server) Context() context.Context > 获取服务器上下文 + *** -#### func (*Server) TimeoutContext(timeout time.Duration) context.Context, context.CancelFunc + + +#### func (*Server) TimeoutContext(timeout time.Duration) ( context.Context, context.CancelFunc) > 获取服务器超时上下文，context.WithTimeout 的简写 + *** + + #### func (*Server) Ticker() *timer.Ticker > 获取服务器定时器 + *** + + #### func (*Server) Shutdown() > 主动停止运行服务器 + *** + + #### func (*Server) GRPCServer() *grpc.Server > 当网络类型为 NetworkGRPC 时将被允许获取 grpc 服务器，否则将会发生 panic + *** + + #### func (*Server) HttpRouter() gin.IRouter > 当网络类型为 NetworkHttp 时将被允许获取路由器进行路由注册，否则将会发生 panic > - 通过该函数注册的路由将无法在服务器关闭时正常等待请求结束 > > Deprecated: 从 Minotaur 0.0.29 开始，由于设计原因已弃用，该函数将直接返回 *gin.Server 对象，导致无法正常的对请求结束时进行处理 + *** + + #### func (*Server) HttpServer() *Http[*HttpContext] > 替代 HttpRouter 的函数，返回一个 *Http[*HttpContext] 对象 > - 通过该函数注册的路由将在服务器关闭时正常等待请求结束 > - 如果需要自行包装 Context 对象，可以使用 NewHttpHandleWrapper 方法 + *** + + #### func (*Server) GetMessageCount() int64 > 获取当前服务器中消息的数量 + *** + + #### func (*Server) UseShunt(conn *Conn, name string) > 切换连接所使用的消息分流渠道，当分流渠道 name 不存在时将会创建一个新的分流渠道，否则将会加入已存在的分流渠道 > - 默认情况下，所有连接都使用系统通道进行消息分发，当指定消息分流渠道且为分流消息类型时，将会使用指定的消息分流渠道进行消息分发 > - 分流渠道会在连接断开时标记为驱逐状态，当分流渠道中的所有消息处理完毕且没有新连接使用时，将会被清除 + *** + + #### func (*Server) HasShunt(name string) bool > 检查特定消息分流渠道是否存在 + *** + + #### func (*Server) GetConnCurrShunt(conn *Conn) string > 获取连接当前所使用的消息分流渠道 + *** + + #### func (*Server) GetShuntNum() int > 获取消息分流渠道数量 + *** + + #### func (*Server) PushSystemMessage(handler func (), mark ...log.Field) > 向服务器中推送 MessageTypeSystem 消息 > - 系统消息仅包含一个可执行函数，将在系统分发器中执行 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Server) PushAsyncMessage(caller func () error, callback func (err error), mark ...log.Field) > 向服务器中推送 MessageTypeAsync 消息 > - 异步消息将在服务器的异步消息队列中进行处理，处理完成 caller 的阻塞操作后，将会通过系统消息执行 callback 函数 > - callback 函数将在异步消息处理完成后进行调用，无论过程是否产生 err，都将被执行，允许为 nil > - 需要注意的是，为了避免并发问题，caller 函数请仅处理阻塞操作，其他操作应该在 callback 函数中进行 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Server) PushShuntAsyncMessage(conn *Conn, caller func () error, callback func (err error), mark ...log.Field) > 向特定分发器中推送 MessageTypeAsync 消息，消息执行与 MessageTypeAsync 一致 > - 需要注意的是，当未指定 UseShunt 时，将会通过 PushAsyncMessage 进行转发 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Server) PushPacketMessage(conn *Conn, wst int, packet []byte, mark ...log.Field) > 向服务器中推送 MessageTypePacket 消息 > - 当存在 UseShunt 的选项时，将会根据选项中的 shuntMatcher 进行分发，否则将在系统分发器中处理消息 + *** + + #### func (*Server) PushTickerMessage(name string, caller func (), mark ...log.Field) > 向服务器中推送 MessageTypeTicker 消息 > - 通过该函数推送定时消息，当消息触发时将在系统分发器中处理消息 @@ -935,39 +1608,66 @@ func ExampleServer_Run() { > > 定时消息执行不会有特殊的处理，仅标记为定时任务，也就是允许将各类函数通过该消息发送处理，但是并不建议 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Server) PushShuntTickerMessage(conn *Conn, name string, caller func (), mark ...log.Field) > 向特定分发器中推送 MessageTypeTicker 消息，消息执行与 MessageTypeTicker 一致 > - 需要注意的是，当未指定 UseShunt 时，将会通过 PushTickerMessage 进行转发 > - mark 为可选的日志标记，当发生异常时，将会在日志中进行体现 + *** + + #### func (*Server) PushUniqueAsyncMessage(unique string, caller func () error, callback func (err error), mark ...log.Field) > 向服务器中推送 MessageTypeAsync 消息，消息执行与 MessageTypeAsync 一致 > - 不同的是当上一个相同的 unique 消息未执行完成时，将会忽略该消息 + *** + + #### func (*Server) PushUniqueShuntAsyncMessage(conn *Conn, unique string, caller func () error, callback func (err error), mark ...log.Field) > 向特定分发器中推送 MessageTypeAsync 消息，消息执行与 MessageTypeAsync 一致 > - 需要注意的是，当未指定 UseShunt 时，将会通过系统分流渠道进行转发 > - 不同的是当上一个相同的 unique 消息未执行完成时，将会忽略该消息 + *** + + #### func (*Server) PushShuntMessage(conn *Conn, caller func (), mark ...log.Field) > 向特定分发器中推送 MessageTypeShunt 消息，消息执行与 MessageTypeSystem 一致，不同的是将会在特定分发器中执行 + *** + + #### func (*Server) GetDurationMessageCount() int64 > 获取当前 WithMessageStatistics 设置的 duration 期间的消息量 + *** + + #### func (*Server) GetDurationMessageCountByOffset(offset int) int64 > 获取特定偏移次数的 WithMessageStatistics 设置的 duration 期间的消息量 > - 该值小于 0 时，将与 GetDurationMessageCount 无异，否则将返回 +n 个期间的消息量，例如 duration 为 1 分钟，limit 为 10，那么 offset 为 1 的情况下，获取的则是上一分钟消息量 + *** + + #### func (*Server) GetAllDurationMessageCount() []int64 > 获取所有 WithMessageStatistics 设置的 duration 期间的消息量 + *** + + #### func (*Server) HasMessageStatistics() bool > 是否了开启消息统计 + *** + ### Service `INTERFACE` -兼容传统 service 设计模式的接口 +兼容传统 service 设计模式的接口，通过该接口可以实现更简洁、更具有可读性的服务绑定 + - 在这之前，我们在实现功能上会将 Server 进行全局存储，之后通过 init 函数进行初始化，这样的顺序是不可控的。 ```go type Service interface { OnInit(srv *Server) diff --git a/server/client/README.md b/server/client/README.md index ad20045..25293ce 100644 --- a/server/client/README.md +++ b/server/client/README.md @@ -27,42 +27,43 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Client](#client)|客户端 -|`INTERFACE`|[Core](#core)|暂无描述... -|`STRUCT`|[ConnectionClosedEventHandle](#connectionclosedeventhandle)|暂无描述... -|`STRUCT`|[Packet](#packet)|暂无描述... -|`STRUCT`|[TCP](#tcp)|暂无描述... -|`STRUCT`|[UnixDomainSocket](#unixdomainsocket)|暂无描述... -|`STRUCT`|[Websocket](#websocket)|websocket 客户端 +|`STRUCT`|[Client](#struct_Client)|客户端 +|`INTERFACE`|[Core](#struct_Core)|暂无描述... +|`STRUCT`|[ConnectionClosedEventHandle](#struct_ConnectionClosedEventHandle)|暂无描述... +|`STRUCT`|[Packet](#struct_Packet)|暂无描述... +|`STRUCT`|[TCP](#struct_TCP)|暂无描述... +|`STRUCT`|[UnixDomainSocket](#struct_UnixDomainSocket)|暂无描述... +|`STRUCT`|[Websocket](#struct_Websocket)|websocket 客户端 *** ## 详情信息 -#### func NewClient(core Core) *Client +#### func NewClient(core Core) *Client > 创建客户端 *** -#### func CloneClient(client *Client) *Client +#### func CloneClient(client *Client) *Client > 克隆客户端 *** -#### func NewTCP(addr string) *Client +#### func NewTCP(addr string) *Client *** -#### func NewUnixDomainSocket(addr string) *Client +#### func NewUnixDomainSocket(addr string) *Client *** -#### func NewWebsocket(addr string) *Client +#### func NewWebsocket(addr string) *Client > 创建 websocket 客户端 *** + ### Client `STRUCT` 客户端 ```go @@ -77,23 +78,38 @@ type Client struct { block chan struct{} } ``` + + #### func (*Client) Run(block ...bool) error > 运行客户端，当客户端已运行时，会先关闭客户端再重新运行 > - block 以阻塞方式运行 + *** + + #### func (*Client) RunByBufferSize(size int, block ...bool) error > 指定写入循环缓冲区大小运行客户端，当客户端已运行时，会先关闭客户端再重新运行 > - block 以阻塞方式运行 + *** + + #### func (*Client) IsConnected() bool > 是否已连接 + *** + + #### func (*Client) Close(err ...error) > 关闭 + *** + + #### func (*Client) WriteWS(wst int, packet []byte, callback ...func (err error)) > 向连接中写入指定 websocket 数据类型 > - wst: websocket模式中指定消息类型 +
查看 / 收起单元测试 @@ -132,12 +148,19 @@ func TestClient_WriteWS(t *testing.T) { *** + + #### func (*Client) Write(packet []byte, callback ...func (err error)) > 向连接中写入数据 + *** + + #### func (*Client) GetServerAddr() string > 获取服务器地址 + *** + ### Core `INTERFACE` ```go @@ -149,11 +172,13 @@ type Core interface { Clone() Core } ``` + ### ConnectionClosedEventHandle `STRUCT` ```go type ConnectionClosedEventHandle func(conn *Client, err any) ``` + ### Packet `STRUCT` ```go @@ -163,6 +188,7 @@ type Packet struct { callback func(err error) } ``` + ### TCP `STRUCT` ```go @@ -172,16 +198,32 @@ type TCP struct { closed bool } ``` + + #### func (*TCP) Run(runState chan error, receive func (wst int, packet []byte)) + *** + + #### func (*TCP) Write(packet *Packet) error + *** + + #### func (*TCP) Close() + *** + + #### func (*TCP) GetServerAddr() string + *** + + #### func (*TCP) Clone() Core + *** + ### UnixDomainSocket `STRUCT` ```go @@ -191,9 +233,15 @@ type UnixDomainSocket struct { closed bool } ``` + + #### func (*UnixDomainSocket) Run(runState chan error, receive func (wst int, packet []byte)) + *** + + #### func (*UnixDomainSocket) Write(packet *Packet) error +
查看 / 收起单元测试 @@ -237,12 +285,22 @@ func TestUnixDomainSocket_Write(t *testing.T) { *** + + #### func (*UnixDomainSocket) Close() + *** + + #### func (*UnixDomainSocket) GetServerAddr() string + *** + + #### func (*UnixDomainSocket) Clone() Core + *** + ### Websocket `STRUCT` websocket 客户端 ```go @@ -253,13 +311,28 @@ type Websocket struct { mu sync.Mutex } ``` + + #### func (*Websocket) Run(runState chan error, receive func (wst int, packet []byte)) + *** + + #### func (*Websocket) Write(packet *Packet) error + *** + + #### func (*Websocket) Close() + *** + + #### func (*Websocket) GetServerAddr() string + *** + + #### func (*Websocket) Clone() Core + *** diff --git a/server/gateway/README.md b/server/gateway/README.md index 831a22f..a0b776b 100644 --- a/server/gateway/README.md +++ b/server/gateway/README.md @@ -32,30 +32,30 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Endpoint](#endpoint)|网关端点 -|`STRUCT`|[EndpointOption](#endpointoption)|网关端点选项 -|`STRUCT`|[ConnectionOpenedEventHandle](#connectionopenedeventhandle)|暂无描述... -|`STRUCT`|[EndpointSelector](#endpointselector)|暂无描述... -|`STRUCT`|[Gateway](#gateway)|基于 server.Server 实现的网关服务器 -|`STRUCT`|[Option](#option)|网关选项 -|`INTERFACE`|[Scanner](#scanner)|端点扫描器 +|`STRUCT`|[Endpoint](#struct_Endpoint)|网关端点 +|`STRUCT`|[EndpointOption](#struct_EndpointOption)|网关端点选项 +|`STRUCT`|[ConnectionOpenedEventHandle](#struct_ConnectionOpenedEventHandle)|暂无描述... +|`STRUCT`|[EndpointSelector](#struct_EndpointSelector)|暂无描述... +|`STRUCT`|[Gateway](#struct_Gateway)|基于 server.Server 实现的网关服务器 +|`STRUCT`|[Option](#struct_Option)|网关选项 +|`INTERFACE`|[Scanner](#struct_Scanner)|端点扫描器
*** ## 详情信息 -#### func NewEndpoint(name string, cli *client.Client, options ...EndpointOption) *Endpoint +#### func NewEndpoint(name string, cli *client.Client, options ...EndpointOption) *Endpoint > 创建网关端点 *** -#### func WithEndpointStateEvaluator(evaluator func (costUnixNano float64) float64) EndpointOption +#### func WithEndpointStateEvaluator(evaluator func (costUnixNano float64) float64) EndpointOption > 设置端点健康值评估函数 *** -#### func WithEndpointConnectionPoolSize(size int) EndpointOption +#### func WithEndpointConnectionPoolSize(size int) EndpointOption > 设置端点连接池大小 > - 默认为 DefaultEndpointConnectionPoolSize @@ -63,25 +63,25 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消 > - 在网关服务器中，多个客户端在发送消息到端点服务器时，会共用一个连接，适当的增大连接池大小可以提高网关服务器的承载能力 *** -#### func WithEndpointReconnectInterval(interval time.Duration) EndpointOption +#### func WithEndpointReconnectInterval(interval time.Duration) EndpointOption > 设置端点重连间隔 > - 默认为 DefaultEndpointReconnectInterval > - 端点在连接失败后会在该间隔后重连，如果 <= 0 则不会重连 *** -#### func NewGateway(srv *server.Server, scanner Scanner, options ...Option) *Gateway +#### func NewGateway(srv *server.Server, scanner Scanner, options ...Option) *Gateway > 基于 server.Server 创建 Gateway 网关服务器 *** -#### func WithEndpointSelector(selector EndpointSelector) Option +#### func WithEndpointSelector(selector EndpointSelector) Option > 设置端点选择器 > - 默认情况下，网关会随机选择一个端点作为目标，如果需要自定义端点选择器，可以通过该选项设置 *** -#### func MarshalGatewayOutPacket(addr string, packet []byte) []byte, error +#### func MarshalGatewayOutPacket(addr string, packet []byte) ([]byte, error) > 将数据包转换为网关出网数据包 > - | identifier(4) | ipv4(4) | port(2) | packet | @@ -93,7 +93,7 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消 > - | identifier(4) | ipv4(4) | port(2) | packet | *** -#### func MarshalGatewayInPacket(addr string, currentTime int64, packet []byte) []byte, error +#### func MarshalGatewayInPacket(addr string, currentTime int64, packet []byte) ([]byte, error) > 将数据包转换为网关入网数据包 > - | ipv4(4) | port(2) | cost(4) | packet | @@ -105,6 +105,7 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消 > - | ipv4(4) | port(2) | cost(4) | packet | *** + ### Endpoint `STRUCT` 网关端点 - 每一个端点均表示了一个目标服务，网关会将数据包转发到该端点，由该端点负责将数据包转发到目标服务。 @@ -128,34 +129,50 @@ type Endpoint struct { cps int } ``` + + #### func (*Endpoint) GetName() string > 获取端点名称 + *** + + #### func (*Endpoint) GetAddress() string > 获取端点地址 + *** + + #### func (*Endpoint) GetState() float64 > 获取端点健康值 + *** + + #### func (*Endpoint) Forward(conn *server.Conn, packet []byte, callback ...func (err error)) > 转发数据包到该端点 > - 端点在处理数据包时，应区分数据包为普通直连数据包还是网关数据包。可通过 UnmarshalGatewayOutPacket 进行数据包解析，当解析失败且无其他数据包协议时，可认为该数据包为普通直连数据包。 + *** + ### EndpointOption `STRUCT` 网关端点选项 ```go type EndpointOption func(endpoint *Endpoint) ``` + ### ConnectionOpenedEventHandle `STRUCT` ```go type ConnectionOpenedEventHandle func(gateway *Gateway, conn *server.Conn) ``` + ### EndpointSelector `STRUCT` ```go type EndpointSelector func(endpoints []*Endpoint) *Endpoint ``` + ### Gateway `STRUCT` 基于 server.Server 实现的网关服务器 - 网关服务器是一个特殊的服务器，它会通过扫描器扫描端点列表，然后连接到端点列表中的所有端点，当端点连接成功后，网关服务器会将客户端的连接数据转发到端点服务器 @@ -181,8 +198,11 @@ type Gateway struct { cceLock sync.RWMutex } ``` + + #### func (*Gateway) Run(addr string) error > 运行网关 +
查看 / 收起单元测试 @@ -212,29 +232,46 @@ func TestGateway_Run(t *testing.T) { *** + + #### func (*Gateway) Shutdown() > 关闭网关 + *** + + #### func (*Gateway) Server() *server.Server > 获取网关服务器核心 + *** -#### func (*Gateway) GetEndpoint(name string) *Endpoint, error + + +#### func (*Gateway) GetEndpoint(name string) ( *Endpoint, error) > 获取一个可用的端点 > - name: 端点名称 + *** -#### func (*Gateway) GetConnEndpoint(name string, conn *server.Conn) *Endpoint, error + + +#### func (*Gateway) GetConnEndpoint(name string, conn *server.Conn) ( *Endpoint, error) > 获取一个可用的端点，如果客户端已经连接到了某个端点，将优先返回该端点 > - 当连接到的端点不可用或没有连接记录时，效果同 GetEndpoint 相同 > - 当连接行为为有状态时，推荐使用该方法 + *** + + #### func (*Gateway) SwitchEndpoint(source *Endpoint, dest *Endpoint) > 将端点端点的所有连接切换到另一个端点 + *** + ### Option `STRUCT` 网关选项 ```go type Option func(gateway *Gateway) ``` + ### Scanner `INTERFACE` 端点扫描器 ```go @@ -243,7 +280,13 @@ type Scanner interface { GetInterval() time.Duration } ``` -#### func (*Scanner) GetEndpoints() []*gateway.Endpoint, error + + +#### func (*Scanner) GetEndpoints() ( []*gateway.Endpoint, error) + *** + + #### func (*Scanner) GetInterval() time.Duration + *** diff --git a/server/internal/dispatcher/README.md b/server/internal/dispatcher/README.md index ac41cf8..bda4852 100644 --- a/server/internal/dispatcher/README.md +++ b/server/internal/dispatcher/README.md @@ -24,23 +24,24 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Action](#action)|消息分发器操作器，用于暴露外部可操作的消息分发器函数 -|`STRUCT`|[Handler](#handler)|消息处理器 -|`STRUCT`|[Dispatcher](#dispatcher)|用于服务器消息处理的消息分发器 -|`STRUCT`|[Manager](#manager)|消息分发器管理器 -|`INTERFACE`|[Message](#message)|暂无描述... -|`INTERFACE`|[Producer](#producer)|暂无描述... +|`STRUCT`|[Action](#struct_Action)|消息分发器操作器，用于暴露外部可操作的消息分发器函数 +|`STRUCT`|[Handler](#struct_Handler)|消息处理器 +|`STRUCT`|[Dispatcher](#struct_Dispatcher)|用于服务器消息处理的消息分发器 +|`STRUCT`|[Manager](#struct_Manager)|消息分发器管理器 +|`INTERFACE`|[Message](#struct_Message)|暂无描述... +|`INTERFACE`|[Producer](#struct_Producer)|暂无描述...
*** ## 详情信息 -#### func NewDispatcher(bufferSize int, name string, handler Handler[P, M]) *Dispatcher[P, M] +#### func NewDispatcher\[P Producer, M Message[P]\](bufferSize int, name string, handler Handler[P, M]) *Dispatcher[P, M] > 创建一个新的消息分发器 Dispatcher 实例 -示例代码： +**示例代码：** + ```go func ExampleNewDispatcher() { @@ -107,11 +108,12 @@ func TestNewDispatcher(t *testing.T) { *** -#### func NewManager(bufferSize int, handler Handler[P, M]) *Manager[P, M] +#### func NewManager\[P Producer, M Message[P]\](bufferSize int, handler Handler[P, M]) *Manager[P, M] > 生成消息分发器管理器 -示例代码： +**示例代码：** + ```go func ExampleNewManager() { @@ -165,6 +167,7 @@ func TestNewManager(t *testing.T) { *** + ### Action `STRUCT` 消息分发器操作器，用于暴露外部可操作的消息分发器函数 ```go @@ -173,11 +176,31 @@ type Action[P Producer, M Message[P]] struct { d *Dispatcher[P, M] } ``` + + +#### func (*Action) Name() string +> 获取消息分发器名称 + +*** + + +#### func (*Action) UnExpel() +> 取消特定生产者的驱逐计划 + +*** + + +#### func (*Action) Expel() +> 设置该消息分发器即将被驱逐，当消息分发器中没有任何消息时，会自动关闭 + +*** + ### Handler `STRUCT` 消息处理器 ```go type Handler[P Producer, M Message[P]] func(dispatcher *Dispatcher[P, M], message M) ``` + ### Dispatcher `STRUCT` 用于服务器消息处理的消息分发器 @@ -207,6 +230,394 @@ type Dispatcher[P Producer, M Message[P]] struct { abort chan struct{} } ``` + + +#### func (*Dispatcher) SetProducerDoneHandler(p P, handler func (p P, dispatcher *Action[P, M])) *Dispatcher[P, M] +> 设置特定生产者的所有消息处理完成时的回调函数 +> - 如果 handler 为 nil，则会删除该生产者的回调函数 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_SetProducerDoneHandler(t *testing.T) { + var cases = []struct { + name string + producer string + messageFinish *atomic.Bool + cancel bool + }{{name: "TestDispatcher_SetProducerDoneHandlerNotCancel", producer: "producer", cancel: false}, {name: "TestDispatcher_SetProducerDoneHandlerCancel", producer: "producer", cancel: true}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.messageFinish = &atomic.Bool{} + w := new(sync.WaitGroup) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + w.Done() + }) + d.Put(&TestMessage{producer: c.producer}) + d.SetProducerDoneHandler(c.producer, func(p string, dispatcher *dispatcher.Action[string, *TestMessage]) { + c.messageFinish.Store(true) + }) + if c.cancel { + d.SetProducerDoneHandler(c.producer, nil) + } + w.Add(1) + d.Start() + w.Wait() + if c.cancel && c.messageFinish.Load() { + t.Errorf("%s should cancel, but not", c.name) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) SetClosedHandler(handler func (dispatcher *Action[P, M])) *Dispatcher[P, M] +> 设置消息分发器关闭时的回调函数 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_SetClosedHandler(t *testing.T) { + var cases = []struct { + name string + handlerFinishMsgCount *atomic.Int64 + msgTime time.Duration + msgCount int + }{{name: "TestDispatcher_SetClosedHandler_Normal", msgTime: 0, msgCount: 1}, {name: "TestDispatcher_SetClosedHandler_MessageCount1024", msgTime: 0, msgCount: 1024}, {name: "TestDispatcher_SetClosedHandler_MessageTime1sMessageCount3", msgTime: 1 * time.Second, msgCount: 3}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.handlerFinishMsgCount = &atomic.Int64{} + w := new(sync.WaitGroup) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + time.Sleep(c.msgTime) + c.handlerFinishMsgCount.Add(1) + }) + d.SetClosedHandler(func(dispatcher *dispatcher.Action[string, *TestMessage]) { + w.Done() + }) + for i := 0; i < c.msgCount; i++ { + d.Put(&TestMessage{producer: "producer"}) + } + w.Add(1) + d.Start() + d.Expel() + w.Wait() + if c.handlerFinishMsgCount.Load() != int64(c.msgCount) { + t.Errorf("%s should finish %d messages, but finish %d", c.name, c.msgCount, c.handlerFinishMsgCount.Load()) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) Name() string +> 获取消息分发器名称 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_Name(t *testing.T) { + var cases = []struct{ name string }{{name: "TestDispatcher_Name_Normal"}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + if d.Name() != c.name { + t.Errorf("%s should equal %s, but not", c.name, c.name) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) Unique(name string) bool +> 设置唯一消息键，返回是否已存在 + +*** + + +#### func (*Dispatcher) AntiUnique(name string) +> 取消唯一消息键 + +*** + + +#### func (*Dispatcher) Expel() +> 设置该消息分发器即将被驱逐，当消息分发器中没有任何消息时，会自动关闭 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_Expel(t *testing.T) { + var cases = []struct { + name string + handlerFinishMsgCount *atomic.Int64 + msgTime time.Duration + msgCount int + }{{name: "TestDispatcher_Expel_Normal", msgTime: 0, msgCount: 1}, {name: "TestDispatcher_Expel_MessageCount1024", msgTime: 0, msgCount: 1024}, {name: "TestDispatcher_Expel_MessageTime1sMessageCount3", msgTime: 1 * time.Second, msgCount: 3}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.handlerFinishMsgCount = &atomic.Int64{} + w := new(sync.WaitGroup) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + time.Sleep(c.msgTime) + c.handlerFinishMsgCount.Add(1) + }) + d.SetClosedHandler(func(dispatcher *dispatcher.Action[string, *TestMessage]) { + w.Done() + }) + for i := 0; i < c.msgCount; i++ { + d.Put(&TestMessage{producer: "producer"}) + } + w.Add(1) + d.Start() + d.Expel() + w.Wait() + if c.handlerFinishMsgCount.Load() != int64(c.msgCount) { + t.Errorf("%s should finish %d messages, but finish %d", c.name, c.msgCount, c.handlerFinishMsgCount.Load()) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) UnExpel() +> 取消特定生产者的驱逐计划 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_UnExpel(t *testing.T) { + var cases = []struct { + name string + closed *atomic.Bool + isUnExpel bool + expect bool + }{{name: "TestDispatcher_UnExpel_Normal", isUnExpel: true, expect: false}, {name: "TestDispatcher_UnExpel_NotExpel", isUnExpel: false, expect: true}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.closed = &atomic.Bool{} + w := new(sync.WaitGroup) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + w.Done() + }) + d.SetClosedHandler(func(dispatcher *dispatcher.Action[string, *TestMessage]) { + c.closed.Store(true) + }) + d.Put(&TestMessage{producer: "producer"}) + w.Add(1) + if c.isUnExpel { + d.Expel() + d.UnExpel() + } else { + d.Expel() + } + d.Start() + w.Wait() + if c.closed.Load() != c.expect { + t.Errorf("%s should %v, but %v", c.name, c.expect, c.closed.Load()) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) IncrCount(producer P, i int64) +> 主动增量设置特定生产者的消息计数，这在等待异步消息完成后再关闭消息分发器时非常有用 +> - 如果 i 为负数，则会减少消息计数 + +*** + + +#### func (*Dispatcher) Put(message M) +> 将消息放入分发器 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_Put(t *testing.T) { + var cases = []struct { + name string + producer string + messageDone *atomic.Bool + }{{name: "TestDispatcher_Put_Normal", producer: "producer"}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.messageDone = &atomic.Bool{} + w := new(sync.WaitGroup) + w.Add(1) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + c.messageDone.Store(true) + w.Done() + }) + d.Start() + d.Put(&TestMessage{producer: c.producer}) + d.Expel() + w.Wait() + if !c.messageDone.Load() { + t.Errorf("%s should done, but not", c.name) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) Start() *Dispatcher[P, M] +> 以非阻塞的方式开始进行消息分发，当消息分发器中没有任何消息并且处于驱逐计划 Expel 时，将会自动关闭 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_Start(t *testing.T) { + var cases = []struct { + name string + producer string + messageDone *atomic.Bool + }{{name: "TestDispatcher_Start_Normal", producer: "producer"}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + c.messageDone = &atomic.Bool{} + w := new(sync.WaitGroup) + w.Add(1) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + c.messageDone.Store(true) + w.Done() + }) + d.Start() + d.Put(&TestMessage{producer: c.producer}) + d.Expel() + w.Wait() + if !c.messageDone.Load() { + t.Errorf("%s should done, but not", c.name) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Dispatcher) Closed() bool +> 判断消息分发器是否已关闭 + +
+查看 / 收起单元测试 + + +```go + +func TestDispatcher_Closed(t *testing.T) { + var cases = []struct{ name string }{{name: "TestDispatcher_Closed_Normal"}} + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + w := new(sync.WaitGroup) + w.Add(1) + d := dispatcher.NewDispatcher(1024, c.name, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + d.SetClosedHandler(func(dispatcher *dispatcher.Action[string, *TestMessage]) { + w.Done() + }) + d.Start() + d.Expel() + w.Wait() + if !d.Closed() { + t.Errorf("%s should closed, but not", c.name) + } + }) + } +} + +``` + + +
+ + +*** + ### Manager `STRUCT` 消息分发器管理器 ```go @@ -223,6 +634,323 @@ type Manager[P Producer, M Message[P]] struct { createdHandler func(name string) } ``` + + +#### func (*Manager) Wait() +> 等待所有消息分发器关闭 + +*** + + +#### func (*Manager) SetDispatcherClosedHandler(handler func (name string)) *Manager[P, M] +> 设置消息分发器关闭时的回调函数 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_SetDispatcherClosedHandler(t *testing.T) { + var cases = []struct { + name string + setCloseHandler bool + }{{name: "TestManager_SetDispatcherClosedHandler_Set", setCloseHandler: true}, {name: "TestManager_SetDispatcherClosedHandler_NotSet", setCloseHandler: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var closed atomic.Bool + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + if c.setCloseHandler { + m.SetDispatcherClosedHandler(func(name string) { + closed.Store(true) + }) + } + m.BindProducer(c.name, c.name) + m.UnBindProducer(c.name) + m.Wait() + if c.setCloseHandler && !closed.Load() { + t.Errorf("SetDispatcherClosedHandler() should be called") + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) SetDispatcherCreatedHandler(handler func (name string)) *Manager[P, M] +> 设置消息分发器创建时的回调函数 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_SetDispatcherCreatedHandler(t *testing.T) { + var cases = []struct { + name string + setCreatedHandler bool + }{{name: "TestManager_SetDispatcherCreatedHandler_Set", setCreatedHandler: true}, {name: "TestManager_SetDispatcherCreatedHandler_NotSet", setCreatedHandler: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var created atomic.Bool + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + if c.setCreatedHandler { + m.SetDispatcherCreatedHandler(func(name string) { + created.Store(true) + }) + } + m.BindProducer(c.name, c.name) + m.UnBindProducer(c.name) + m.Wait() + if c.setCreatedHandler && !created.Load() { + t.Errorf("SetDispatcherCreatedHandler() should be called") + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) HasDispatcher(name string) bool +> 检查是否存在指定名称的消息分发器 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_HasDispatcher(t *testing.T) { + var cases = []struct { + name string + bindName string + has bool + }{{name: "TestManager_HasDispatcher_Has", bindName: "TestManager_HasDispatcher_Has", has: true}, {name: "TestManager_HasDispatcher_NotHas", bindName: "TestManager_HasDispatcher_NotHas", has: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + m.BindProducer(c.bindName, c.bindName) + var cond string + if c.has { + cond = c.bindName + } + if m.HasDispatcher(cond) != c.has { + t.Errorf("HasDispatcher() should return %v", c.has) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) GetDispatcherNum() int +> 获取当前正在工作的消息分发器数量 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_GetDispatcherNum(t *testing.T) { + var cases = []struct { + name string + num int + }{{name: "TestManager_GetDispatcherNum_N1", num: -1}, {name: "TestManager_GetDispatcherNum_0", num: 0}, {name: "TestManager_GetDispatcherNum_1", num: 1}, {name: "TestManager_GetDispatcherNum_2", num: 2}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + switch { + case c.num <= 0: + return + case c.num == 1: + if m.GetDispatcherNum() != 1 { + t.Errorf("GetDispatcherNum() should return 1") + } + return + default: + for i := 0; i < c.num-1; i++ { + m.BindProducer(fmt.Sprintf("%s_%d", c.name, i), fmt.Sprintf("%s_%d", c.name, i)) + } + if m.GetDispatcherNum() != c.num { + t.Errorf("GetDispatcherNum() should return %v", c.num) + } + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) GetSystemDispatcher() *Dispatcher[P, M] +> 获取系统消息分发器 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_GetSystemDispatcher(t *testing.T) { + var cases = []struct{ name string }{{name: "TestManager_GetSystemDispatcher"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + if m.GetSystemDispatcher() == nil { + t.Errorf("GetSystemDispatcher() should not return nil") + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) GetDispatcher(p P) *Dispatcher[P, M] +> 获取生产者正在使用的消息分发器，如果生产者没有绑定消息分发器，则会返回系统消息分发器 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_GetDispatcher(t *testing.T) { + var cases = []struct { + name string + bindName string + }{{name: "TestManager_GetDispatcher", bindName: "TestManager_GetDispatcher"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + m.BindProducer(c.bindName, c.bindName) + if m.GetDispatcher(c.bindName) == nil { + t.Errorf("GetDispatcher() should not return nil") + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) BindProducer(p P, name string) +> 绑定生产者使用特定的消息分发器，如果生产者已经绑定了消息分发器，则会先解绑 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_BindProducer(t *testing.T) { + var cases = []struct { + name string + bindName string + }{{name: "TestManager_BindProducer", bindName: "TestManager_BindProducer"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + m.BindProducer(c.bindName, c.bindName) + if m.GetDispatcher(c.bindName) == nil { + t.Errorf("GetDispatcher() should not return nil") + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Manager) UnBindProducer(p P) +> 解绑生产者使用特定的消息分发器 + +
+查看 / 收起单元测试 + + +```go + +func TestManager_UnBindProducer(t *testing.T) { + var cases = []struct { + name string + bindName string + }{{name: "TestManager_UnBindProducer", bindName: "TestManager_UnBindProducer"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + m := dispatcher.NewManager[string, *TestMessage](1024, func(dispatcher *dispatcher.Dispatcher[string, *TestMessage], message *TestMessage) { + }) + m.BindProducer(c.bindName, c.bindName) + m.UnBindProducer(c.bindName) + if m.GetDispatcher(c.bindName) != m.GetSystemDispatcher() { + t.Errorf("GetDispatcher() should return SystemDispatcher") + } + }) + } +} + +``` + + +
+ + +*** + ### Message `INTERFACE` ```go @@ -230,6 +958,7 @@ type Message[P comparable] interface { GetProducer() P } ``` + ### Producer `INTERFACE` ```go diff --git a/server/internal/dispatcher/dispatcher.go b/server/internal/dispatcher/dispatcher.go index 7d696cd..b88dcd2 100644 --- a/server/internal/dispatcher/dispatcher.go +++ b/server/internal/dispatcher/dispatcher.go @@ -59,10 +59,8 @@ type Dispatcher[P Producer, M Message[P]] struct { abort chan struct{} } -// SetProducerDoneHandler 设置特定生产者所有消息处理完成时的回调函数 +// SetProducerDoneHandler 设置特定生产者的所有消息处理完成时的回调函数 // - 如果 handler 为 nil，则会删除该生产者的回调函数 -// -// 需要注意的是，该 handler 中 func (d *Dispatcher[P, M]) SetProducerDoneHandler(p P, handler func(p P, dispatcher *Action[P, M])) *Dispatcher[P, M] { d.lock.Lock() if handler == nil { diff --git a/server/internal/logger/README.md b/server/internal/logger/README.md index a4225b9..4b644d8 100644 --- a/server/internal/logger/README.md +++ b/server/internal/logger/README.md @@ -16,33 +16,53 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Ants](#ants)|暂无描述... -|`STRUCT`|[GNet](#gnet)|暂无描述... +|`STRUCT`|[Ants](#struct_Ants)|暂无描述... +|`STRUCT`|[GNet](#struct_GNet)|暂无描述...
*** ## 详情信息 + ### Ants `STRUCT` ```go type Ants struct{} ``` + + #### func (*Ants) Printf(format string, args ...interface {}) + *** + ### GNet `STRUCT` ```go type GNet struct{} ``` + + #### func (*GNet) Debugf(format string, args ...interface {}) + *** + + #### func (*GNet) Infof(format string, args ...interface {}) + *** + + #### func (*GNet) Warnf(format string, args ...interface {}) + *** + + #### func (*GNet) Errorf(format string, args ...interface {}) + *** + + #### func (*GNet) Fatalf(format string, args ...interface {}) + *** diff --git a/server/lockstep/README.md b/server/lockstep/README.md index 5be645f..7c74cfc 100644 --- a/server/lockstep/README.md +++ b/server/lockstep/README.md @@ -27,17 +27,17 @@ |类型|名称|描述 |:--|:--|:-- -|`INTERFACE`|[Client](#client)|帧同步客户端接口定义 -|`STRUCT`|[StoppedEventHandle](#stoppedeventhandle)|暂无描述... -|`STRUCT`|[Lockstep](#lockstep)|锁步（帧）同步默认实现 -|`STRUCT`|[Option](#option)|暂无描述... +|`INTERFACE`|[Client](#struct_Client)|帧同步客户端接口定义 +|`STRUCT`|[StoppedEventHandle](#struct_StoppedEventHandle)|暂无描述... +|`STRUCT`|[Lockstep](#struct_Lockstep)|锁步（帧）同步默认实现 +|`STRUCT`|[Option](#struct_Option)|暂无描述... *** ## 详情信息 -#### func NewLockstep(options ...Option[ClientID, Command]) *Lockstep[ClientID, Command] +#### func NewLockstep\[ClientID comparable, Command any\](options ...Option[ClientID, Command]) *Lockstep[ClientID, Command] > 创建一个锁步（帧）同步默认实现的组件(Lockstep)进行返回 @@ -78,19 +78,19 @@ func TestNewLockstep(t *testing.T) { *** -#### func WithFrameLimit(frameLimit int64) Option[ClientID, Command] +#### func WithFrameLimit\[ClientID comparable, Command any\](frameLimit int64) Option[ClientID, Command] > 通过特定逻辑帧上限创建锁步（帧）同步组件 > - 当达到上限时将停止广播 *** -#### func WithFrameRate(frameRate int64) Option[ClientID, Command] +#### func WithFrameRate\[ClientID comparable, Command any\](frameRate int64) Option[ClientID, Command] > 通过特定逻辑帧率创建锁步（帧）同步组件 > - 默认情况下为 15/s *** -#### func WithSerialization(handle func (frame int64, commands []Command) []byte) Option[ClientID, Command] +#### func WithSerialization\[ClientID comparable, Command any\](handle func (frame int64, commands []Command) []byte) Option[ClientID, Command] > 通过特定的序列化方式将每一帧的数据进行序列化 > @@ -102,12 +102,13 @@ func TestNewLockstep(t *testing.T) { > } *** -#### func WithInitFrame(initFrame int64) Option[ClientID, Command] +#### func WithInitFrame\[ClientID comparable, Command any\](initFrame int64) Option[ClientID, Command] > 通过特定的初始帧创建锁步（帧）同步组件 > - 默认情况下为 0，即第一帧索引为 0 *** + ### Client `INTERFACE` 帧同步客户端接口定义 - 客户端应该具备ID及写入数据包的实现 @@ -117,11 +118,13 @@ type Client[ID comparable] interface { Write(packet []byte, callback ...func(err error)) } ``` + ### StoppedEventHandle `STRUCT` ```go type StoppedEventHandle[ClientID comparable, Command any] func(lockstep *Lockstep[ClientID, Command]) ``` + ### Lockstep `STRUCT` 锁步（帧）同步默认实现 - 支持最大帧上限 WithFrameLimit @@ -149,6 +152,108 @@ type Lockstep[ClientID comparable, Command any] struct { lockstepStoppedEventHandles []StoppedEventHandle[ClientID, Command] } ``` + + +#### func (*Lockstep) JoinClient(client Client[ClientID]) +> 将客户端加入到广播队列中，通常在开始广播前使用 +> - 如果客户端在开始广播后加入，将丢失之前的帧数据，如要从特定帧开始追帧请使用 JoinClientWithFrame + +*** + + +#### func (*Lockstep) JoinClientWithFrame(client Client[ClientID], frameIndex int64) +> 加入客户端到广播队列中，并从特定帧开始追帧 +> - 可用于重连及状态同步、帧同步混用的情况 +> - 混用：服务端记录指令时同时做一次状态计算，新客户端加入时直接同步当前状态，之后从特定帧开始广播 + +*** + + +#### func (*Lockstep) GetClientCount() int +> 获取客户端数量 + +*** + + +#### func (*Lockstep) DropCache(handler func (frame int64) bool) +> 丢弃特定帧的缓存，当 handler 返回 true 时将丢弃缓存 + +*** + + +#### func (*Lockstep) LeaveClient(clientId ClientID) +> 将客户端从广播队列中移除 + +*** + + +#### func (*Lockstep) StartBroadcast() +> 开始广播 +> - 在开始广播后将持续按照设定的帧率进行帧数推进，并在每一帧推进时向客户端进行同步，需提前将客户端加入广播队列 JoinClient +> - 广播过程中使用 AddCommand 将该帧数据追加到当前帧中 + +*** + + +#### func (*Lockstep) StopBroadcast() +> 停止广播 + +*** + + +#### func (*Lockstep) IsRunning() bool +> 是否正在广播 + +*** + + +#### func (*Lockstep) AddCommand(command Command) +> 添加命令到当前帧 + +*** + + +#### func (*Lockstep) AddCommands(commands []Command) +> 添加命令到当前帧 + +*** + + +#### func (*Lockstep) GetCurrentFrame() int64 +> 获取当前帧 + +*** + + +#### func (*Lockstep) GetClientCurrentFrame(clientId ClientID) int64 +> 获取客户端当前帧 + +*** + + +#### func (*Lockstep) GetFrameLimit() int64 +> 获取帧上限 +> - 未设置时将返回0 + +*** + + +#### func (*Lockstep) GetCurrentCommands() []Command +> 获取当前帧还未结束时的所有指令 + +*** + + +#### func (*Lockstep) RegLockstepStoppedEvent(handle StoppedEventHandle[ClientID, Command]) +> 当广播停止时将触发被注册的事件处理函数 + +*** + + +#### func (*Lockstep) OnLockstepStoppedEvent() + +*** + ### Option `STRUCT` ```go diff --git a/server/network.go b/server/network.go index 3e5c1f0..6351ef1 100644 --- a/server/network.go +++ b/server/network.go @@ -16,6 +16,22 @@ import ( "time" ) +// Network 服务器运行的网络模式 +// - 根据不同的网络模式，服务器将会产生不同的行为，该类型将在服务器创建时候指定 +// +// 服务器支持的网络模式如下： +// - NetworkNone 该模式下不监听任何网络端口，仅开启消息队列，适用于纯粹的跨服服务器等情况 +// - NetworkTcp 该模式下将会监听 TCP 协议的所有地址，包括 IPv4 和 IPv6 +// - NetworkTcp4 该模式下将会监听 TCP 协议的 IPv4 地址 +// - NetworkTcp6 该模式下将会监听 TCP 协议的 IPv6 地址 +// - NetworkUdp 该模式下将会监听 UDP 协议的所有地址，包括 IPv4 和 IPv6 +// - NetworkUdp4 该模式下将会监听 UDP 协议的 IPv4 地址 +// - NetworkUdp6 该模式下将会监听 UDP 协议的 IPv6 地址 +// - NetworkUnix 该模式下将会监听 Unix 协议的地址 +// - NetworkHttp 该模式下将会监听 HTTP 协议的地址 +// - NetworkWebsocket 该模式下将会监听 Websocket 协议的地址 +// - NetworkKcp 该模式下将会监听 KCP 协议的地址 +// - NetworkGRPC 该模式下将会监听 GRPC 协议的地址 type Network string const ( @@ -103,6 +119,7 @@ func (n Network) adaptation(srv *Server) <-chan error { switch n { case NetworkNone: srv.addr = "-" + state <- nil case NetworkTcp: n.gNetMode(state, srv) case NetworkTcp4: @@ -125,6 +142,8 @@ func (n Network) adaptation(srv *Server) <-chan error { n.kcpMode(state, srv) case NetworkGRPC: n.grpcMode(state, srv) + default: + state <- fmt.Errorf("unsupported network mode: %s", n) } return state } @@ -248,7 +267,8 @@ func (n Network) websocketMode(state chan<- error, srv *Server) { if srv.websocketUpgrader == nil { srv.websocketUpgrader = DefaultWebsocketUpgrader() } - http.HandleFunc(pattern, func(writer http.ResponseWriter, request *http.Request) { + mux := http.NewServeMux() + mux.HandleFunc(pattern, func(writer http.ResponseWriter, request *http.Request) { ip := request.Header.Get("X-Real-IP") ws, err := srv.websocketUpgrader.Upgrade(writer, request, nil) if err != nil { @@ -304,20 +324,29 @@ func (n Network) websocketMode(state chan<- error, srv *Server) { srv.PushPacketMessage(conn, messageType, packet) } }) - go func(lis *listener) { + go func(lis *listener, mux *http.ServeMux) { var err error if len(lis.srv.certFile)+len(lis.srv.keyFile) > 0 { - err = http.ServeTLS(lis, nil, lis.srv.certFile, lis.srv.keyFile) + err = http.ServeTLS(lis, mux, lis.srv.certFile, lis.srv.keyFile) } else { - err = http.Serve(lis, nil) + err = http.Serve(lis, mux) } if err != nil { super.TryWriteChannel(lis.state, err) } - }((&listener{srv: srv, Listener: l, state: state}).init()) + }((&listener{srv: srv, Listener: l, state: state}).init(), mux) } -// IsSocket 返回当前服务器的网络模式是否为 Socket 模式 +// IsSocket 返回当前服务器的网络模式是否为 Socket 模式，目前为止仅有如下几种模式为 Socket 模式： +// - NetworkTcp +// - NetworkTcp4 +// - NetworkTcp6 +// - NetworkUdp +// - NetworkUdp4 +// - NetworkUdp6 +// - NetworkUnix +// - NetworkKcp +// - NetworkWebsocket func (n Network) IsSocket() bool { return collection.KeyInMap(socketNetworks, n) } diff --git a/server/options_example_test.go b/server/options_example_test.go new file mode 100644 index 0000000..c916603 --- /dev/null +++ b/server/options_example_test.go @@ -0,0 +1,51 @@ +package server_test + +import ( + "fmt" + "github.com/kercylan98/minotaur/server" + "github.com/kercylan98/minotaur/utils/times" + "time" +) + +// 服务器在启动时将阻塞 1s，模拟了慢消息的过程，这时候如果通过 RegMessageLowExecEvent 函数注册过慢消息事件，将会收到该事件的消息 +// - 该示例中，将在收到慢消息时关闭服务器 +func ExampleWithLowMessageDuration() { + srv := server.New(server.NetworkNone, + server.WithLowMessageDuration(time.Second), + ) + srv.RegStartFinishEvent(func(srv *server.Server) { + time.Sleep(time.Second) + }) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + srv.Shutdown() + fmt.Println(times.GetSecond(cost)) + }) + if err := srv.RunNone(); err != nil { + panic(err) + } + // Output: + // 1 +} + +// 服务器在启动时将发布一条阻塞 1s 的异步消息，模拟了慢消息的过程，这时候如果通过 RegMessageLowExecEvent 函数注册过慢消息事件，将会收到该事件的消息 +// - 该示例中，将在收到慢消息时关闭服务器 +func ExampleWithAsyncLowMessageDuration() { + srv := server.New(server.NetworkNone, + server.WithAsyncLowMessageDuration(time.Second), + ) + srv.RegStartFinishEvent(func(srv *server.Server) { + srv.PushAsyncMessage(func() error { + time.Sleep(time.Second) + return nil + }, nil) + }) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + srv.Shutdown() + fmt.Println(times.GetSecond(cost)) + }) + if err := srv.RunNone(); err != nil { + panic(err) + } + // Output: + // 1 +} diff --git a/server/options_test.go b/server/options_test.go new file mode 100644 index 0000000..aea3e50 --- /dev/null +++ b/server/options_test.go @@ -0,0 +1,109 @@ +package server_test + +import ( + "fmt" + "github.com/kercylan98/minotaur/server" + "github.com/kercylan98/minotaur/utils/random" + "testing" + "time" +) + +func TestWithLowMessageDuration(t *testing.T) { + var cases = []struct { + name string + duration time.Duration + }{ + {name: "TestWithLowMessageDuration", duration: server.DefaultLowMessageDuration}, + {name: "TestWithLowMessageDuration_Zero", duration: 0}, + {name: "TestWithLowMessageDuration_Negative", duration: -server.DefaultAsyncLowMessageDuration}, + } + + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + networks := server.GetNetworks() + for i := 0; i < len(networks); i++ { + low := false + network := networks[i] + srv := server.New(network, + server.WithLowMessageDuration(c.duration), + ) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + low = true + srv.Shutdown() + }) + srv.RegStartFinishEvent(func(srv *server.Server) { + if c.duration <= 0 { + srv.Shutdown() + return + } + time.Sleep(server.DefaultLowMessageDuration) + }) + var lis string + switch network { + case server.NetworkNone, server.NetworkUnix: + lis = "addr" + default: + lis = fmt.Sprintf(":%d", random.UsablePort()) + } + if err := srv.Run(lis); err != nil { + t.Fatalf("%s run error: %s", network, err) + } + if !low && c.duration > 0 { + t.Fatalf("%s low message not exec", network) + } + } + }) + } +} + +func TestWithAsyncLowMessageDuration(t *testing.T) { + var cases = []struct { + name string + duration time.Duration + }{ + {name: "TestWithAsyncLowMessageDuration", duration: time.Millisecond * 100}, + {name: "TestWithAsyncLowMessageDuration_Zero", duration: 0}, + {name: "TestWithAsyncLowMessageDuration_Negative", duration: -server.DefaultAsyncLowMessageDuration}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + networks := server.GetNetworks() + for i := 0; i < len(networks); i++ { + low := false + network := networks[i] + srv := server.New(network, + server.WithAsyncLowMessageDuration(c.duration), + ) + srv.RegMessageLowExecEvent(func(srv *server.Server, message *server.Message, cost time.Duration) { + low = true + srv.Shutdown() + }) + srv.RegStartFinishEvent(func(srv *server.Server) { + if c.duration <= 0 { + srv.Shutdown() + return + } + srv.PushAsyncMessage(func() error { + time.Sleep(c.duration) + return nil + }, nil) + }) + var lis string + switch network { + case server.NetworkNone, server.NetworkUnix: + lis = fmt.Sprintf("%s%d", "addr", random.Int(0, 9999)) + default: + lis = fmt.Sprintf(":%d", random.UsablePort()) + } + if err := srv.Run(lis); err != nil { + t.Fatalf("%s run error: %s", network, err) + } + if !low && c.duration > 0 { + t.Fatalf("%s low message not exec", network) + } + } + }) + } +} diff --git a/server/router/README.md b/server/router/README.md index 2c28968..f248399 100644 --- a/server/router/README.md +++ b/server/router/README.md @@ -24,20 +24,21 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[MultistageBind](#multistagebind)|多级分类路由绑定函数 -|`STRUCT`|[Multistage](#multistage)|支持多级分类的路由器 -|`STRUCT`|[MultistageOption](#multistageoption)|路由器选项 +|`STRUCT`|[MultistageBind](#struct_MultistageBind)|多级分类路由绑定函数 +|`STRUCT`|[Multistage](#struct_Multistage)|支持多级分类的路由器 +|`STRUCT`|[MultistageOption](#struct_MultistageOption)|路由器选项 *** ## 详情信息 -#### func NewMultistage(options ...MultistageOption[HandleFunc]) *Multistage[HandleFunc] +#### func NewMultistage\[HandleFunc any\](options ...MultistageOption[HandleFunc]) *Multistage[HandleFunc] > 创建一个支持多级分类的路由器 -示例代码： +**示例代码：** + ```go func ExampleNewMultistage() { @@ -47,20 +48,25 @@ func ExampleNewMultistage() { ``` *** -#### func WithRouteTrim(handle func (route any) any) MultistageOption[HandleFunc] +#### func WithRouteTrim\[HandleFunc any\](handle func (route any) any) MultistageOption[HandleFunc] > 路由修剪选项 > - 将在路由注册前对路由进行对应处理 *** + ### MultistageBind `STRUCT` 多级分类路由绑定函数 ```go type MultistageBind[HandleFunc any] func(HandleFunc) ``` + + #### func (MultistageBind) Bind(handleFunc HandleFunc) > 将处理函数绑定到预设的路由中 + *** + ### Multistage `STRUCT` 支持多级分类的路由器 ```go @@ -71,10 +77,14 @@ type Multistage[HandleFunc any] struct { trim func(route any) any } ``` + + #### func (*Multistage) Register(routes ...any) MultistageBind[HandleFunc] > 注册路由是结合 Sub 和 Route 的快捷方式，用于一次性注册多级路由 > - 该函数将返回一个注册函数，可通过调用其将路由绑定到特定处理函数，例如：router.Register("a", "b").Bind(onExec()) -示例代码： + +**示例代码：** + ```go func ExampleMultistage_Register() { @@ -86,9 +96,13 @@ func ExampleMultistage_Register() { ``` *** + + #### func (*Multistage) Route(route any, handleFunc HandleFunc) > 为特定路由绑定处理函数，被绑定的处理函数将可以通过 Match 函数进行匹配 -示例代码： + +**示例代码：** + ```go func ExampleMultistage_Route() { @@ -100,10 +114,14 @@ func ExampleMultistage_Route() { ``` *** + + #### func (*Multistage) Match(routes ...any) HandleFunc > 匹配已绑定处理函数的路由，返回处理函数 > - 如果未找到将会返回空指针 -示例代码： + +**示例代码：** + ```go func ExampleMultistage_Match() { @@ -150,9 +168,13 @@ func TestMultistage_Match(t *testing.T) { *** + + #### func (*Multistage) Sub(route any) *Multistage[HandleFunc] > 获取子路由器 -示例代码： + +**示例代码：** + ```go func ExampleMultistage_Sub() { @@ -164,6 +186,7 @@ func ExampleMultistage_Sub() { ``` *** + ### MultistageOption `STRUCT` 路由器选项 ```go diff --git a/server/server.go b/server/server.go index ea53720..72c37e7 100644 --- a/server/server.go +++ b/server/server.go @@ -84,6 +84,7 @@ type Server struct { systemSignal chan os.Signal // 系统信号 closeChannel chan struct{} // 关闭信号 multipleRuntimeErrorChan chan error // 多服务器模式下的运行时错误 + data map[string]any // 服务器全局数据 messageCounter atomic.Int64 // 消息计数器 addr string // 侦听地址 @@ -92,6 +93,33 @@ type Server struct { services []func() // 服务 } +// LoadData 加载绑定的服务器数据 +func LoadData[T any](srv *Server, name string, data any) T { + return srv.data[name].(T) +} + +// BindData 绑定数据到特定服务器 +func BindData(srv *Server, name string, data any) { + srv.BindData(name, data) +} + +// LoadData 加载绑定的服务器数据 +func (srv *Server) LoadData(name string, data any) any { + return srv.data[name] +} + +// BindData 绑定数据到特定服务器 +func (srv *Server) BindData(name string, data any) { + if srv.data == nil { + srv.data = map[string]any{} + } + _, exist := srv.data[name] + if exist { + panic(fmt.Errorf("data with duplicate names is bound, got: %s", name)) + } + srv.data[name] = data +} + // preCheckAndAdaptation 预检查及适配 func (srv *Server) preCheckAndAdaptation(addr string) (startState <-chan error, err error) { if srv.event == nil { @@ -149,7 +177,7 @@ func (srv *Server) Run(addr string) (err error) { return nil } -// IsSocket 是否是 Socket 模式 +// IsSocket 通过执行 Network.IsSocket 函数检查该服务器是否是 Socket 模式 func (srv *Server) IsSocket() bool { return srv.network.IsSocket() } diff --git a/server/server_example_test.go b/server/server_example_test.go index a7c2cb2..acc679c 100644 --- a/server/server_example_test.go +++ b/server/server_example_test.go @@ -1,30 +1,53 @@ package server_test import ( + "fmt" "github.com/kercylan98/minotaur/server" "time" ) +// 该案例将创建一个简单的 WebSocket 服务器，如果需要更多的服务器类型可参考 [` Network `](#struct_Network) 部分 +// - server.WithLimitLife(time.Millisecond) 通常不是在正常开发应该使用的，在这里只是为了让服务器在启动完成后的 1 毫秒后自动关闭 +// +// 该案例的输出结果为 true func ExampleNew() { srv := server.New(server.NetworkWebsocket, server.WithLimitLife(time.Millisecond)) - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) - if err := srv.Run(":9999"); err != nil { - panic(err) - } - + fmt.Println(srv != nil) // Output: + // true } +// 该案例将创建两个不同类型的服务器，其中 WebSocket 是一个 Socket 服务器，而 Http 是一个非 Socket 服务器 +// +// 可知案例输出结果为： +// - true +// - false +func ExampleServer_IsSocket() { + srv1 := server.New(server.NetworkWebsocket) + fmt.Println(srv1.IsSocket()) + srv2 := server.New(server.NetworkHttp) + fmt.Println(srv2.IsSocket()) + // Output: + // true + // false +} + +// 该案例将创建一个简单的 WebSocket 服务器并启动监听 `:9999/` 作为 WebSocket 监听地址，如果需要更多的服务器类型可参考 [` Network `](#struct_Network) 部分 +// - 当服务器启动失败后，将会返回错误信息并触发 panic +// - server.WithLimitLife(time.Millisecond) 通常不是在正常开发应该使用的，在这里只是为了让服务器在启动完成后的 1 毫秒后自动关闭 func ExampleServer_Run() { srv := server.New(server.NetworkWebsocket, server.WithLimitLife(time.Millisecond)) - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) if err := srv.Run(":9999"); err != nil { panic(err) } - + // Output: +} + +// RunNone 函数并没有特殊的意义，该函数内部调用了 `srv.Run("")` 函数，仅是一个语法糖，用来表示服务器不需要监听任何地址 +func ExampleServer_RunNone() { + srv := server.New(server.NetworkNone) + if err := srv.RunNone(); err != nil { + panic(err) + } // Output: } diff --git a/server/server_test.go b/server/server_test.go index 7e8fe1f..074f3d5 100644 --- a/server/server_test.go +++ b/server/server_test.go @@ -1,81 +1,101 @@ package server_test import ( - "fmt" "github.com/kercylan98/minotaur/server" - "github.com/kercylan98/minotaur/server/client" - "github.com/kercylan98/minotaur/utils/times" + "github.com/kercylan98/minotaur/utils/super" + "runtime/debug" "testing" "time" ) +// 该单元测试用于测试以不同的基本参数创建服务器是否存在异常 func TestNew(t *testing.T) { - srv := server.New(server.NetworkWebsocket, server.WithPProf()) - srv.RegStartBeforeEvent(func(srv *server.Server) { - fmt.Println("启动前") - }) - srv.RegStartFinishEvent(func(srv *server.Server) { - fmt.Println("启动完成") - }) - srv.RegConnectionClosedEvent(func(srv *server.Server, conn *server.Conn, err any) { - fmt.Println("关闭", conn.GetID(), err, "IncrCount", srv.GetOnlineCount()) - }) - - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) - if err := srv.Run(":9999"); err != nil { - panic(err) + var cases = []struct { + name string + network server.Network + addr string + shouldPanic bool + }{ + {name: "TestNew_Unknown", addr: "", network: "Unknown", shouldPanic: true}, + {name: "TestNew_None", addr: "", network: server.NetworkNone, shouldPanic: false}, + {name: "TestNew_None_Addr", addr: "addr", network: server.NetworkNone, shouldPanic: false}, + {name: "TestNew_Tcp_AddrEmpty", addr: "", network: server.NetworkTcp, shouldPanic: true}, + {name: "TestNew_Tcp_AddrIllegal", addr: "addr", network: server.NetworkTcp, shouldPanic: true}, + {name: "TestNew_Tcp_Addr", addr: ":9999", network: server.NetworkTcp, shouldPanic: false}, + {name: "TestNew_Tcp4_AddrEmpty", addr: "", network: server.NetworkTcp4, shouldPanic: true}, + {name: "TestNew_Tcp4_AddrIllegal", addr: "addr", network: server.NetworkTcp4, shouldPanic: true}, + {name: "TestNew_Tcp4_Addr", addr: ":9999", network: server.NetworkTcp4, shouldPanic: false}, + {name: "TestNew_Tcp6_AddrEmpty", addr: "", network: server.NetworkTcp6, shouldPanic: true}, + {name: "TestNew_Tcp6_AddrIllegal", addr: "addr", network: server.NetworkTcp6, shouldPanic: true}, + {name: "TestNew_Tcp6_Addr", addr: ":9999", network: server.NetworkTcp6, shouldPanic: false}, + {name: "TestNew_Udp_AddrEmpty", addr: "", network: server.NetworkUdp, shouldPanic: true}, + {name: "TestNew_Udp_AddrIllegal", addr: "addr", network: server.NetworkUdp, shouldPanic: true}, + {name: "TestNew_Udp_Addr", addr: ":9999", network: server.NetworkUdp, shouldPanic: false}, + {name: "TestNew_Udp4_AddrEmpty", addr: "", network: server.NetworkUdp4, shouldPanic: true}, + {name: "TestNew_Udp4_AddrIllegal", addr: "addr", network: server.NetworkUdp4, shouldPanic: true}, + {name: "TestNew_Udp4_Addr", addr: ":9999", network: server.NetworkUdp4, shouldPanic: false}, + {name: "TestNew_Udp6_AddrEmpty", addr: "", network: server.NetworkUdp6, shouldPanic: true}, + {name: "TestNew_Udp6_AddrIllegal", addr: "addr", network: server.NetworkUdp6, shouldPanic: true}, + {name: "TestNew_Udp6_Addr", addr: ":9999", network: server.NetworkUdp6, shouldPanic: false}, + {name: "TestNew_Unix_AddrEmpty", addr: "", network: server.NetworkUnix, shouldPanic: true}, + {name: "TestNew_Unix_AddrIllegal", addr: "addr", network: server.NetworkUnix, shouldPanic: true}, + {name: "TestNew_Unix_Addr", addr: "addr", network: server.NetworkUnix, shouldPanic: false}, + {name: "TestNew_Websocket_AddrEmpty", addr: "", network: server.NetworkWebsocket, shouldPanic: true}, + {name: "TestNew_Websocket_AddrIllegal", addr: "addr", network: server.NetworkWebsocket, shouldPanic: true}, + {name: "TestNew_Websocket_Addr", addr: ":9999/ws", network: server.NetworkWebsocket, shouldPanic: false}, + {name: "TestNew_Http_AddrEmpty", addr: "", network: server.NetworkHttp, shouldPanic: true}, + {name: "TestNew_Http_AddrIllegal", addr: "addr", network: server.NetworkHttp, shouldPanic: true}, + {name: "TestNew_Http_Addr", addr: ":9999", network: server.NetworkHttp, shouldPanic: false}, + {name: "TestNew_Kcp_AddrEmpty", addr: "", network: server.NetworkKcp, shouldPanic: true}, + {name: "TestNew_Kcp_AddrIllegal", addr: "addr", network: server.NetworkKcp, shouldPanic: true}, + {name: "TestNew_Kcp_Addr", addr: ":9999", network: server.NetworkKcp, shouldPanic: false}, + {name: "TestNew_GRPC_AddrEmpty", addr: "", network: server.NetworkGRPC, shouldPanic: true}, + {name: "TestNew_GRPC_AddrIllegal", addr: "addr", network: server.NetworkGRPC, shouldPanic: true}, + {name: "TestNew_GRPC_Addr", addr: ":9999", network: server.NetworkGRPC, shouldPanic: false}, } -} -func TestNew2(t *testing.T) { - srv := server.New(server.NetworkWebsocket, server.WithPProf()) - srv.RegStartBeforeEvent(func(srv *server.Server) { - fmt.Println("启动前") - }) - srv.RegStartFinishEvent(func(srv *server.Server) { - fmt.Println("启动完成") - }) - srv.RegConnectionClosedEvent(func(srv *server.Server, conn *server.Conn, err any) { - fmt.Println("关闭", conn.GetID(), err, "IncrCount", srv.GetOnlineCount()) - }) - - srv.RegConnectionReceivePacketEvent(func(srv *server.Server, conn *server.Conn, packet []byte) { - conn.Write(packet) - }) - if err := srv.Run(":9999"); err != nil { - panic(err) - } -} - -func TestNewClient(t *testing.T) { - count := 500 - for i := 0; i < count; i++ { - fmt.Println("启动", i+1) - cli := client.NewWebsocket("ws://172.29.5.138:9999") - cli.RegConnectionReceivePacketEvent(func(conn *client.Client, wst int, packet []byte) { - fmt.Println(time.Now().Unix(), "收到", string(packet)) - }) - cli.RegConnectionClosedEvent(func(conn *client.Client, err any) { - fmt.Println("关闭", err) - }) - cli.RegConnectionOpenedEvent(func(conn *client.Client) { - go func() { - for i < count { - time.Sleep(time.Second) - } - for { - for i := 0; i < 10; i++ { - cli.WriteWS(2, []byte("hello")) - } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if err := super.RecoverTransform(recover()); err != nil && !c.shouldPanic { + debug.PrintStack() + t.Fatal("not should panic, err:", err) } }() + if err := server.New(c.network, server.WithLimitLife(time.Millisecond*10)).Run(""); err != nil { + panic(err) + } }) - if err := cli.Run(); err != nil { - panic(err) - } + } +} + +// 这个测试检查了各个类型的服务器是否为 Socket 模式。如需查看为 Socket 模式的网络类型，请参考 [` Network.IsSocket` ](#struct_Network_IsSocket) +func TestServer_IsSocket(t *testing.T) { + var cases = []struct { + name string + network server.Network + expect bool + }{ + {name: "TestServer_IsSocket_None", network: server.NetworkNone, expect: false}, + {name: "TestServer_IsSocket_Tcp", network: server.NetworkTcp, expect: true}, + {name: "TestServer_IsSocket_Tcp4", network: server.NetworkTcp4, expect: true}, + {name: "TestServer_IsSocket_Tcp6", network: server.NetworkTcp6, expect: true}, + {name: "TestServer_IsSocket_Udp", network: server.NetworkUdp, expect: true}, + {name: "TestServer_IsSocket_Udp4", network: server.NetworkUdp4, expect: true}, + {name: "TestServer_IsSocket_Udp6", network: server.NetworkUdp6, expect: true}, + {name: "TestServer_IsSocket_Unix", network: server.NetworkUnix, expect: true}, + {name: "TestServer_IsSocket_Http", network: server.NetworkHttp, expect: false}, + {name: "TestServer_IsSocket_Websocket", network: server.NetworkWebsocket, expect: true}, + {name: "TestServer_IsSocket_Kcp", network: server.NetworkKcp, expect: true}, + {name: "TestServer_IsSocket_GRPC", network: server.NetworkGRPC, expect: false}, } - time.Sleep(times.Week) + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + s := server.New(c.network) + if s.IsSocket() != c.expect { + t.Fatalf("expect: %v, got: %v", c.expect, s.IsSocket()) + } + }) + } } diff --git a/server/service.go b/server/service.go index 54abe6c..722f923 100644 --- a/server/service.go +++ b/server/service.go @@ -5,7 +5,8 @@ import ( "reflect" ) -// Service 兼容传统 service 设计模式的接口 +// Service 兼容传统 service 设计模式的接口，通过该接口可以实现更简洁、更具有可读性的服务绑定 +// - 在这之前，我们在实现功能上会将 Server 进行全局存储，之后通过 init 函数进行初始化，这样的顺序是不可控的。 type Service interface { // OnInit 初始化服务，该方法将会在 Server 初始化时执行 // - 通常来说，该阶段发生任何错误都应该 panic 以阻止 Server 启动 diff --git a/server/service_example_test.go b/server/service_example_test.go new file mode 100644 index 0000000..8881711 --- /dev/null +++ b/server/service_example_test.go @@ -0,0 +1,44 @@ +package server_test + +import ( + "github.com/kercylan98/minotaur/server" + "time" +) + +// 这个案例中我们将 `TestService` 绑定到了 `srv` 服务器中，当服务器启动时，将会对 `TestService` 进行初始化 +// +// 其中 `TestService` 的定义如下： +// ```go +// +// type TestService struct{} +// +// func (ts *TestService) OnInit(srv *server.Server) { +// srv.RegStartFinishEvent(onStartFinish) +// +// srv.RegStopEvent(func(srv *server.Server) { +// fmt.Println("server stop") +// }) +// } +// +// func (ts *TestService) onStartFinish(srv *server.Server) { +// fmt.Println("server start finish") +// } +// +// ``` +// +// 可以看出，在服务初始化时，该服务向服务器注册了启动完成事件及停止事件。这是我们推荐的编码方式，这样编码有以下好处： +// - 具备可控制的初始化顺序，避免 init 产生的各种顺序导致的问题，如配置还未加载完成，即开始进行数据库连接等操作 +// - 可以方便的将不同的服务拆分到不同的包中进行管理 +// - 当不需要某个服务时，可以直接删除该服务的绑定，而不需要修改其他代码 +// - ... +func ExampleBindService() { + srv := server.New(server.NetworkNone, server.WithLimitLife(time.Second)) + server.BindService(srv, new(TestService)) + + if err := srv.RunNone(); err != nil { + panic(err) + } + // Output: + // server start finish + // server stop +} diff --git a/server/service_test.go b/server/service_test.go index 1ffb710..caafa7b 100644 --- a/server/service_test.go +++ b/server/service_test.go @@ -20,24 +20,19 @@ func (ts *TestService) OnInit(srv *server.Server) { } func TestBindService(t *testing.T) { - srv := server.New(server.NetworkNone, server.WithLimitLife(time.Second)) - - server.BindService(srv, new(TestService)) - - if err := srv.RunNone(); err != nil { - t.Fatal(err) - } -} - -func ExampleBindService() { - srv := server.New(server.NetworkNone, server.WithLimitLife(time.Second)) - server.BindService(srv, new(TestService)) - - if err := srv.RunNone(); err != nil { - panic(err) + var cases = []struct { + name string + }{ + {name: "TestBindService"}, } - // Output: - // server start finish - // server stop + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + srv := server.New(server.NetworkNone, server.WithLimitLife(time.Millisecond)) + server.BindService(srv, new(TestService)) + if err := srv.RunNone(); err != nil { + t.Fatal(err) + } + }) + } } diff --git a/server/writeloop/README.md b/server/writeloop/README.md index 73dfc13..649cb94 100644 --- a/server/writeloop/README.md +++ b/server/writeloop/README.md @@ -24,16 +24,16 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Channel](#channel)|基于 chan 的写循环，与 Unbounded 相同，但是使用 Channel 实现 -|`STRUCT`|[Unbounded](#unbounded)|写循环 -|`INTERFACE`|[WriteLoop](#writeloop)|暂无描述... +|`STRUCT`|[Channel](#struct_Channel)|基于 chan 的写循环，与 Unbounded 相同，但是使用 Channel 实现 +|`STRUCT`|[Unbounded](#struct_Unbounded)|写循环 +|`INTERFACE`|[WriteLoop](#struct_WriteLoop)|暂无描述... *** ## 详情信息 -#### func NewChannel(pool *hub.ObjectPool[Message], channelSize int, writeHandler func (message Message) error, errorHandler func (err any)) *Channel[Message] +#### func NewChannel\[Message any\](pool *hub.ObjectPool[Message], channelSize int, writeHandler func (message Message) error, errorHandler func (err any)) *Channel[Message] > 创建基于 Channel 的写循环 > - pool 用于管理 Message 对象的缓冲池，在创建 Message 对象时也应该使用该缓冲池，以便复用 Message 对象。 Channel 会在写入完成后将 Message 对象放回缓冲池 @@ -44,7 +44,7 @@ > 传入 writeHandler 的消息对象是从 Channel 中获取的，因此 writeHandler 不应该持有消息对象的引用，同时也不应该主动释放消息对象 *** -#### func NewUnbounded(pool *hub.ObjectPool[Message], writeHandler func (message Message) error, errorHandler func (err any)) *Unbounded[Message] +#### func NewUnbounded\[Message any\](pool *hub.ObjectPool[Message], writeHandler func (message Message) error, errorHandler func (err any)) *Unbounded[Message] > 创建写循环 > - pool 用于管理 Message 对象的缓冲池，在创建 Message 对象时也应该使用该缓冲池，以便复用 Message 对象。 Unbounded 会在写入完成后将 Message 对象放回缓冲池 @@ -53,7 +53,8 @@ > > 传入 writeHandler 的消息对象是从 pool 中获取的，并且在 writeHandler 执行完成后会被放回 pool 中，因此 writeHandler 不应该持有消息对象的引用，同时也不应该主动释放消息对象 -示例代码： +**示例代码：** + ```go func ExampleNewUnbounded() { @@ -106,6 +107,7 @@ func TestNewUnbounded(t *testing.T) { *** + ### Channel `STRUCT` 基于 chan 的写循环，与 Unbounded 相同，但是使用 Channel 实现 ```go @@ -113,12 +115,19 @@ type Channel[T any] struct { c chan T } ``` + + #### func (*Channel) Put(message T) > 将数据放入写循环，message 应该来源于 hub.ObjectPool + *** + + #### func (*Channel) Close() > 关闭写循环 + *** + ### Unbounded `STRUCT` 写循环 - 用于将数据并发安全的写入到底层连接 @@ -127,8 +136,11 @@ type Unbounded[Message any] struct { buf *buffer.Unbounded[Message] } ``` + + #### func (*Unbounded) Put(message Message) > 将数据放入写循环，message 应该来源于 hub.ObjectPool +
查看 / 收起单元测试 @@ -186,8 +198,11 @@ func BenchmarkUnbounded_Put(b *testing.B) { *** + + #### func (*Unbounded) Close() > 关闭写循环 +
查看 / 收起单元测试 @@ -217,6 +232,7 @@ func TestUnbounded_Close(t *testing.T) { *** + ### WriteLoop `INTERFACE` ```go diff --git a/utils/aoi/README.md b/utils/aoi/README.md index e2c7429..eb25601 100644 --- a/utils/aoi/README.md +++ b/utils/aoi/README.md @@ -28,16 +28,16 @@ AOI 问题是在大规模多人在线游戏中常见的问题，它涉及到确 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[TwoDimensional](#twodimensional)|暂无描述... -|`INTERFACE`|[TwoDimensionalEntity](#twodimensionalentity)|基于2D定义的AOI对象功能接口 -|`STRUCT`|[EntityJoinVisionEventHandle](#entityjoinvisioneventhandle)|暂无描述... +|`STRUCT`|[TwoDimensional](#struct_TwoDimensional)|暂无描述... +|`INTERFACE`|[TwoDimensionalEntity](#struct_TwoDimensionalEntity)|基于2D定义的AOI对象功能接口 +|`STRUCT`|[EntityJoinVisionEventHandle](#struct_EntityJoinVisionEventHandle)|暂无描述...
*** ## 详情信息 -#### func NewTwoDimensional(width int, height int, areaWidth int, areaHeight int) *TwoDimensional[EID, PosType, E] +#### func NewTwoDimensional\[EID generic.Basic, PosType generic.SignedNumber, E TwoDimensionalEntity[EID, PosType]\](width int, height int, areaWidth int, areaHeight int) *TwoDimensional[EID, PosType, E]
@@ -65,6 +65,7 @@ func TestNewTwoDimensional(t *testing.T) { *** + ### TwoDimensional `STRUCT` ```go @@ -82,6 +83,37 @@ type TwoDimensional[EID generic.Basic, PosType generic.SignedNumber, E TwoDimens repartitionQueue []func() } ``` + + +#### func (*TwoDimensional) AddEntity(entity E) + +*** + + +#### func (*TwoDimensional) DeleteEntity(entity E) + +*** + + +#### func (*TwoDimensional) Refresh(entity E) + +*** + + +#### func (*TwoDimensional) GetFocus(id EID) map[EID]E + +*** + + +#### func (*TwoDimensional) SetSize(width int, height int) + +*** + + +#### func (*TwoDimensional) SetAreaSize(width int, height int) + +*** + ### TwoDimensionalEntity `INTERFACE` 基于2D定义的AOI对象功能接口 - AOI 对象提供了 AOI 系统中常用的属性，诸如位置坐标和视野范围等 @@ -92,6 +124,7 @@ type TwoDimensionalEntity[EID generic.Basic, PosType generic.SignedNumber] inter GetPosition() geometry.Point[PosType] } ``` + ### EntityJoinVisionEventHandle `STRUCT` ```go diff --git a/utils/arrangement/README.md b/utils/arrangement/README.md index 93dcdb3..6694668 100644 --- a/utils/arrangement/README.md +++ b/utils/arrangement/README.md @@ -34,70 +34,70 @@ arrangement 包提供了一些有用的函数来处理数组的排列。 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Area](#area)|编排区域 -|`STRUCT`|[AreaOption](#areaoption)|编排区域选项 -|`STRUCT`|[AreaConstraintHandle](#areaconstrainthandle)|暂无描述... -|`STRUCT`|[Arrangement](#arrangement)|用于针对多条数据进行合理编排的数据结构 -|`STRUCT`|[Editor](#editor)|提供了大量辅助函数的编辑器 -|`INTERFACE`|[Item](#item)|编排成员 -|`STRUCT`|[ItemOption](#itemoption)|编排成员选项 -|`STRUCT`|[ItemFixedAreaHandle](#itemfixedareahandle)|暂无描述... -|`STRUCT`|[Option](#option)|编排选项 -|`STRUCT`|[ConstraintHandle](#constrainthandle)|暂无描述... +|`STRUCT`|[Area](#struct_Area)|编排区域 +|`STRUCT`|[AreaOption](#struct_AreaOption)|编排区域选项 +|`STRUCT`|[AreaConstraintHandle](#struct_AreaConstraintHandle)|暂无描述... +|`STRUCT`|[Arrangement](#struct_Arrangement)|用于针对多条数据进行合理编排的数据结构 +|`STRUCT`|[Editor](#struct_Editor)|提供了大量辅助函数的编辑器 +|`INTERFACE`|[Item](#struct_Item)|编排成员 +|`STRUCT`|[ItemOption](#struct_ItemOption)|编排成员选项 +|`STRUCT`|[ItemFixedAreaHandle](#struct_ItemFixedAreaHandle)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|编排选项 +|`STRUCT`|[ConstraintHandle](#struct_ConstraintHandle)|暂无描述...
*** ## 详情信息 -#### func WithAreaConstraint(constraint AreaConstraintHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] +#### func WithAreaConstraint\[ID comparable, AreaInfo any\](constraint AreaConstraintHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] > 设置编排区域的约束条件 > - 该约束用于判断一个成员是否可以被添加到该编排区域中 > - 与 WithAreaConflict 不同的是，约束通常用于非成员关系导致的硬性约束，例如：成员的等级过滤、成员的性别等 *** -#### func WithAreaConflict(conflict AreaConflictHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] +#### func WithAreaConflict\[ID comparable, AreaInfo any\](conflict AreaConflictHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] > 设置编排区域的冲突条件，冲突处理函数需要返回造成冲突的成员列表 > - 该冲突用于判断一个成员是否可以被添加到该编排区域中 > - 与 WithAreaConstraint 不同的是，冲突通常用于成员关系导致的软性约束，例如：成员的职业唯一性、成员的种族唯一性等 *** -#### func WithAreaEvaluate(evaluate AreaEvaluateHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] +#### func WithAreaEvaluate\[ID comparable, AreaInfo any\](evaluate AreaEvaluateHandle[ID, AreaInfo]) AreaOption[ID, AreaInfo] > 设置编排区域的评估函数 > - 该评估函数将影响成员被编入区域的优先级 *** -#### func NewArrangement(options ...Option[ID, AreaInfo]) *Arrangement[ID, AreaInfo] +#### func NewArrangement\[ID comparable, AreaInfo any\](options ...Option[ID, AreaInfo]) *Arrangement[ID, AreaInfo] > 创建一个新的编排 *** -#### func WithItemFixed(matcher ItemFixedAreaHandle[AreaInfo]) ItemOption[ID, AreaInfo] +#### func WithItemFixed\[ID comparable, AreaInfo any\](matcher ItemFixedAreaHandle[AreaInfo]) ItemOption[ID, AreaInfo] > 设置成员的固定编排区域 *** -#### func WithItemPriority(priority ItemPriorityHandle[ID, AreaInfo]) ItemOption[ID, AreaInfo] +#### func WithItemPriority\[ID comparable, AreaInfo any\](priority ItemPriorityHandle[ID, AreaInfo]) ItemOption[ID, AreaInfo] > 设置成员的优先级 *** -#### func WithItemNotAllow(verify ItemNotAllowVerifyHandle[ID, AreaInfo]) ItemOption[ID, AreaInfo] +#### func WithItemNotAllow\[ID comparable, AreaInfo any\](verify ItemNotAllowVerifyHandle[ID, AreaInfo]) ItemOption[ID, AreaInfo] > 设置成员不允许的编排区域 *** -#### func WithRetryThreshold(threshold int) Option[ID, AreaInfo] +#### func WithRetryThreshold\[ID comparable, AreaInfo any\](threshold int) Option[ID, AreaInfo] > 设置编排时的重试阈值 > - 当每一轮编排结束任有成员未被编排时，将会进行下一轮编排，直到编排次数达到该阈值 > - 默认的阈值为 10 次 *** -#### func WithConstraintHandle(handle ConstraintHandle[ID, AreaInfo]) Option[ID, AreaInfo] +#### func WithConstraintHandle\[ID comparable, AreaInfo any\](handle ConstraintHandle[ID, AreaInfo]) Option[ID, AreaInfo] > 设置编排时触发约束时的处理函数 > - 当约束条件触发时，将会调用该函数。如果无法在该函数中处理约束，应该继续返回 err，尝试进行下一层的约束处理 @@ -107,7 +107,7 @@ arrangement 包提供了一些有用的函数来处理数组的排列。 > 有意思的是，硬性约束应该永远是无解的，而当需要进行一些打破规则的操作时，则可以透过该函数传入的 editor 进行操作 *** -#### func WithConflictHandle(handle ConflictHandle[ID, AreaInfo]) Option[ID, AreaInfo] +#### func WithConflictHandle\[ID comparable, AreaInfo any\](handle ConflictHandle[ID, AreaInfo]) Option[ID, AreaInfo] > 设置编排时触发冲突时的处理函数 > - 当冲突条件触发时，将会调用该函数。如果无法在该函数中处理冲突，应该继续返回这一批成员，尝试进行下一层的冲突处理 @@ -115,6 +115,7 @@ arrangement 包提供了一些有用的函数来处理数组的排列。 > - 当所有的冲突处理函数都无法处理冲突时，将会进入下一个编排区域的尝试，如果均无法完成，将会将该成员加入到编排队列的末端，等待下一次编排 *** + ### Area `STRUCT` 编排区域 ```go @@ -126,16 +127,56 @@ type Area[ID comparable, AreaInfo any] struct { evaluate AreaEvaluateHandle[ID, AreaInfo] } ``` + + +#### func (*Area) GetAreaInfo() AreaInfo +> 获取编排区域的信息 + +*** + + +#### func (*Area) GetItems() map[ID]Item[ID] +> 获取编排区域中的所有成员 + +*** + + +#### func (*Area) IsAllow(item Item[ID]) (constraintErr error, conflictItems map[ID]Item[ID], allow bool) +> 检测一个成员是否可以被添加到该编排区域中 + +*** + + +#### func (*Area) IsConflict(item Item[ID]) bool +> 检测一个成员是否会造成冲突 + +*** + + +#### func (*Area) GetConflictItems(item Item[ID]) map[ID]Item[ID] +> 获取与一个成员产生冲突的所有其他成员 + +*** + + +#### func (*Area) GetScore(extra ...Item[ID]) float64 +> 获取该编排区域的评估分数 +> - 当 extra 不为空时，将会将 extra 中的内容添加到 items 中进行评估 + +*** + ### AreaOption `STRUCT` 编排区域选项 ```go type AreaOption[ID comparable, AreaInfo any] func(area *Area[ID, AreaInfo]) ``` + ### AreaConstraintHandle `STRUCT` ```go type AreaConstraintHandle[ID comparable, AreaInfo any] func(area *Area[ID, AreaInfo], item Item[ID]) error ``` + ### Arrangement `STRUCT` 用于针对多条数据进行合理编排的数据结构 - 我不知道这个数据结构的具体用途，但是我觉得这个数据结构应该是有用的 @@ -153,6 +194,75 @@ type Arrangement[ID comparable, AreaInfo any] struct { conflictHandles []ConflictHandle[ID, AreaInfo] } ``` + + +#### func (*Arrangement) AddArea(areaInfo AreaInfo, options ...AreaOption[ID, AreaInfo]) +> 添加一个编排区域 + +*** + + +#### func (*Arrangement) AddItem(item Item[ID]) +> 添加一个成员 + +*** + + +#### func (*Arrangement) Arrange() (areas []*Area[ID, AreaInfo], noSolution map[ID]Item[ID]) +> 编排 + +
+查看 / 收起单元测试 + + +```go + +func TestArrangement_Arrange(t *testing.T) { + var a = arrangement.NewArrangement[int, *Team]() + a.AddArea(&Team{ID: 1}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error { + if len(area.GetItems()) >= 2 { + return errors.New("too many") + } + return nil + })) + a.AddArea(&Team{ID: 2}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error { + if len(area.GetItems()) >= 1 { + return errors.New("too many") + } + return nil + })) + a.AddArea(&Team{ID: 3}, arrangement.WithAreaConstraint[int, *Team](func(area *arrangement.Area[int, *Team], item arrangement.Item[int]) error { + if len(area.GetItems()) >= 2 { + return errors.New("too many") + } + return nil + })) + for i := 0; i < 10; i++ { + a.AddItem(&Player{ID: i + 1}) + } + res, no := a.Arrange() + for _, area := range res { + var str = fmt.Sprintf("area %d: ", area.GetAreaInfo().ID) + for id := range area.GetItems() { + str += fmt.Sprintf("%d ", id) + } + fmt.Println(str) + } + var noStr = "no: " + for _, i := range no { + noStr += fmt.Sprintf("%d ", i.GetID()) + } + fmt.Println(noStr) +} + +``` + + +
+ + +*** + ### Editor `STRUCT` 提供了大量辅助函数的编辑器 ```go @@ -164,6 +274,91 @@ type Editor[ID comparable, AreaInfo any] struct { retryCount int } ``` + + +#### func (*Editor) GetPendingCount() int +> 获取待编排的成员数量 + +*** + + +#### func (*Editor) RemoveAreaItem(area *Area[ID, AreaInfo], item Item[ID]) +> 从编排区域中移除一个成员到待编排队列中，如果该成员不存在于编排区域中，则不进行任何操作 + +*** + + +#### func (*Editor) AddAreaItem(area *Area[ID, AreaInfo], item Item[ID]) +> 将一个成员添加到编排区域中，如果该成员已经存在于编排区域中，则不进行任何操作 + +*** + + +#### func (*Editor) GetAreas() []*Area[ID, AreaInfo] +> 获取所有的编排区域 + +*** + + +#### func (*Editor) GetAreasWithScoreAsc(extra ...Item[ID]) []*Area[ID, AreaInfo] +> 获取所有的编排区域，并按照分数升序排序 + +*** + + +#### func (*Editor) GetAreasWithScoreDesc(extra ...Item[ID]) []*Area[ID, AreaInfo] +> 获取所有的编排区域，并按照分数降序排序 + +*** + + +#### func (*Editor) GetRetryCount() int +> 获取重试次数 + +*** + + +#### func (*Editor) GetThresholdProgressRate() float64 +> 获取重试次数阈值进度 + +*** + + +#### func (*Editor) GetAllowAreas(item Item[ID]) []*Area[ID, AreaInfo] +> 获取允许的编排区域 + +*** + + +#### func (*Editor) GetNoAllowAreas(item Item[ID]) []*Area[ID, AreaInfo] +> 获取不允许的编排区域 + +*** + + +#### func (*Editor) GetBestAllowArea(item Item[ID]) *Area[ID, AreaInfo] +> 获取最佳的允许的编排区域，如果不存在，则返回 nil + +*** + + +#### func (*Editor) GetBestNoAllowArea(item Item[ID]) *Area[ID, AreaInfo] +> 获取最佳的不允许的编排区域，如果不存在，则返回 nil + +*** + + +#### func (*Editor) GetWorstAllowArea(item Item[ID]) *Area[ID, AreaInfo] +> 获取最差的允许的编排区域，如果不存在，则返回 nil + +*** + + +#### func (*Editor) GetWorstNoAllowArea(item Item[ID]) *Area[ID, AreaInfo] +> 获取最差的不允许的编排区域，如果不存在，则返回 nil + +*** + ### Item `INTERFACE` 编排成员 ```go @@ -172,21 +367,25 @@ type Item[ID comparable] interface { Equal(item Item[ID]) bool } ``` + ### ItemOption `STRUCT` 编排成员选项 ```go type ItemOption[ID comparable, AreaInfo any] func(arrangement *Arrangement[ID, AreaInfo], item Item[ID]) ``` + ### ItemFixedAreaHandle `STRUCT` ```go type ItemFixedAreaHandle[AreaInfo any] func(areaInfo AreaInfo) bool ``` + ### Option `STRUCT` 编排选项 ```go type Option[ID comparable, AreaInfo any] func(arrangement *Arrangement[ID, AreaInfo]) ``` + ### ConstraintHandle `STRUCT` ```go diff --git a/utils/buffer/README.md b/utils/buffer/README.md index b56d19e..81cd797 100644 --- a/utils/buffer/README.md +++ b/utils/buffer/README.md @@ -31,16 +31,16 @@ buffer 提供了缓冲区相关的实用程序。 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Ring](#ring)|环形缓冲区 -|`STRUCT`|[RingUnbounded](#ringunbounded)|基于环形缓冲区实现的无界缓冲区 -|`STRUCT`|[Unbounded](#unbounded)|是无界缓冲区的实现 +|`STRUCT`|[Ring](#struct_Ring)|环形缓冲区 +|`STRUCT`|[RingUnbounded](#struct_RingUnbounded)|基于环形缓冲区实现的无界缓冲区 +|`STRUCT`|[Unbounded](#struct_Unbounded)|是无界缓冲区的实现
*** ## 详情信息 -#### func NewRing(initSize ...int) *Ring[T] +#### func NewRing\[T any\](initSize ...int) *Ring[T] > 创建一个并发不安全的环形缓冲区 > - initSize: 初始容量 @@ -68,12 +68,12 @@ func TestNewRing(t *testing.T) { *** -#### func NewRingUnbounded(bufferSize int) *RingUnbounded[T] +#### func NewRingUnbounded\[T any\](bufferSize int) *RingUnbounded[T] > 创建一个并发安全的基于环形缓冲区实现的无界缓冲区 *** -#### func NewUnbounded() *Unbounded[V] +#### func NewUnbounded\[V any\]() *Unbounded[V] > 创建一个无界缓冲区 > - generateNil: 生成空值的函数，该函数仅需始终返回 nil 即可 @@ -82,6 +82,7 @@ func TestNewRing(t *testing.T) { > - 该缓冲区的所有方法都是线程安全的，除了用于同步的互斥锁外，不会阻塞任何东西 *** + ### Ring `STRUCT` 环形缓冲区 ```go @@ -93,8 +94,11 @@ type Ring[T any] struct { w int } ``` -#### func (*Ring) Read() T, error + + +#### func (*Ring) Read() ( T, error) > 读取数据 +
查看 / 收起基准测试 @@ -119,14 +123,23 @@ func BenchmarkRing_Read(b *testing.B) { *** + + #### func (*Ring) ReadAll() []T > 读取所有数据 + *** + + #### func (*Ring) Peek() (t T, err error) > 查看数据 + *** + + #### func (*Ring) Write(v T) > 写入数据 +
查看 / 收起基准测试 @@ -148,18 +161,31 @@ func BenchmarkRing_Write(b *testing.B) { *** + + #### func (*Ring) IsEmpty() bool > 是否为空 + *** + + #### func (*Ring) Cap() int > 返回缓冲区容量 + *** + + #### func (*Ring) Len() int > 返回缓冲区长度 + *** + + #### func (*Ring) Reset() > 重置缓冲区 + *** + ### RingUnbounded `STRUCT` 基于环形缓冲区实现的无界缓冲区 ```go @@ -173,8 +199,11 @@ type RingUnbounded[T any] struct { closedSignal chan struct{} } ``` + + #### func (*RingUnbounded) Write(v T) > 写入数据 +
查看 / 收起基准测试 @@ -196,8 +225,11 @@ func BenchmarkRingUnbounded_Write(b *testing.B) { *** + + #### func (*RingUnbounded) Read() chan T > 读取数据 +
查看 / 收起基准测试 @@ -222,11 +254,17 @@ func BenchmarkRingUnbounded_Read(b *testing.B) { *** + + #### func (*RingUnbounded) Closed() bool > 判断缓冲区是否已关闭 + *** + + #### func (*RingUnbounded) Close() chan struct {} > 关闭缓冲区，关闭后将不再接收新数据，但是已有数据仍然可以读取 +
查看 / 收起单元测试 @@ -255,6 +293,7 @@ func TestRingUnbounded_Close(t *testing.T) { *** + ### Unbounded `STRUCT` 是无界缓冲区的实现 ```go @@ -265,15 +304,24 @@ type Unbounded[V any] struct { backlog []V } ``` + + #### func (*Unbounded) Put(t V) > 将数据放入缓冲区 + *** + + #### func (*Unbounded) Load() > 将缓冲区中的数据发送到读取通道中，如果缓冲区中没有数据，则不会发送 > - 在每次 Get 后都应该执行该函数 + *** + + #### func (*Unbounded) Get() chan V > 获取读取通道 +
查看 / 收起单元测试 @@ -296,9 +344,15 @@ func TestUnbounded_Get(t *testing.T) { *** + + #### func (*Unbounded) Close() > 关闭 + *** + + #### func (*Unbounded) IsClosed() bool > 是否已关闭 + *** diff --git a/utils/collection/README.md b/utils/collection/README.md index 1fa259f..64f38b0 100644 --- a/utils/collection/README.md +++ b/utils/collection/README.md @@ -3,7 +3,7 @@ [![Go doc](https://img.shields.io/badge/go.dev-reference-brightgreen?logo=go&logoColor=white&style=flat)](https://pkg.go.dev/github.com/kercylan98/minotaur) ![](https://img.shields.io/badge/Email-kercylan@gmail.com-green.svg?style=flat) -collection 用于对 input 和 map 操作的工具函数 +collection 定义了各种对于集合操作有用的各种函数 ## 目录导航 @@ -16,12 +16,16 @@ collection 用于对 input 和 map 操作的工具函数 |函数名称|描述 |:--|:-- -|[CloneSlice](#CloneSlice)|克隆切片，该函数是 slices.Clone 的快捷方式 -|[CloneMap](#CloneMap)|克隆 map -|[CloneSliceN](#CloneSliceN)|克隆 slice 为 n 个切片进行返回 -|[CloneMapN](#CloneMapN)|克隆 map 为 n 个 map 进行返回 -|[CloneSlices](#CloneSlices)|克隆多个切片 -|[CloneMaps](#CloneMaps)|克隆多个 map +|[CloneSlice](#CloneSlice)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片 +|[CloneMap](#CloneMap)|通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map +|[CloneSliceN](#CloneSliceN)|通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 +|[CloneMapN](#CloneMapN)|通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map +|[CloneSlices](#CloneSlices)|对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片 +|[CloneMaps](#CloneMaps)|对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片 +|[EqualSlice](#EqualSlice)|检查两个切片是否相等，当 handler 返回 true 时，表示 slice1 中的某个元素和 slice2 中的某个元素相匹配 +|[EqualComparableSlice](#EqualComparableSlice)|检查两个切片的值是否相同 +|[EqualMap](#EqualMap)|检查两个 map 是否相等，当 handler 返回 true 时，表示 map1 中的某个元素和 map2 中的某个元素相匹配 +|[EqualComparableMap](#EqualComparableMap)|检查两个 map 的值是否相同 |[InSlice](#InSlice)|检查 v 是否被包含在 slice 中，当 handler 返回 true 时，表示 v 和 slice 中的某个元素相匹配 |[InComparableSlice](#InComparableSlice)|检查 v 是否被包含在 slice 中 |[AllInSlice](#AllInSlice)|检查 values 中的所有元素是否均被包含在 slice 中，当 handler 返回 true 时，表示 values 中的某个元素和 slice 中的某个元素相匹配 @@ -50,6 +54,9 @@ collection 用于对 input 和 map 操作的工具函数 |[AnyValueInMaps](#AnyValueInMaps)|检查 maps 中的任意一个元素是否包含 value 中的任意一个元素，当 handler 返回 true 时，表示 value 中的某个元素和 maps 中的某个元素相匹配 |[KeyInAllMaps](#KeyInAllMaps)|检查 key 是否被包含在 maps 的每一个元素中 |[AnyKeyInAllMaps](#AnyKeyInAllMaps)|检查 maps 中的每一个元素是否均包含 keys 中任意一个元素 +|[ConvertSliceToBatches](#ConvertSliceToBatches)|将切片 s 转换为分批次的切片，当 batchSize 小于等于 0 或者 s 长度为 0 时，将会返回 nil +|[ConvertMapKeysToBatches](#ConvertMapKeysToBatches)|将映射的键转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil +|[ConvertMapValuesToBatches](#ConvertMapValuesToBatches)|将映射的值转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil |[ConvertSliceToAny](#ConvertSliceToAny)|将切片转换为任意类型的切片 |[ConvertSliceToIndexMap](#ConvertSliceToIndexMap)|将切片转换为索引为键的映射 |[ConvertSliceToIndexOnlyMap](#ConvertSliceToIndexOnlyMap)|将切片转换为索引为键的映射 @@ -99,6 +106,17 @@ collection 用于对 input 和 map 操作的工具函数 |[FindMin2MaxFromComparableMap](#FindMin2MaxFromComparableMap)|获取 map 中的最小值和最大值 |[FindMin2MaxFromMap](#FindMin2MaxFromMap)|获取 map 中的最小值和最大值 |[SwapSlice](#SwapSlice)|将切片中的两个元素进行交换 +|[LoopSlice](#LoopSlice)|迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +|[ReverseLoopSlice](#ReverseLoopSlice)|逆序迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +|[LoopMap](#LoopMap)|迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByOrderedKeyAsc](#LoopMapByOrderedKeyAsc)|按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByOrderedKeyDesc](#LoopMapByOrderedKeyDesc)|按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByOrderedValueAsc](#LoopMapByOrderedValueAsc)|按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByOrderedValueDesc](#LoopMapByOrderedValueDesc)|按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByKeyGetterAsc](#LoopMapByKeyGetterAsc)|按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByValueGetterAsc](#LoopMapByValueGetterAsc)|按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByKeyGetterDesc](#LoopMapByKeyGetterDesc)|按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +|[LoopMapByValueGetterDesc](#LoopMapByValueGetterDesc)|按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 |[MappingFromSlice](#MappingFromSlice)|将切片中的元素进行转换 |[MappingFromMap](#MappingFromMap)|将 map 中的元素进行转换 |[MergeSlices](#MergeSlices)|合并切片 @@ -133,19 +151,24 @@ collection 用于对 input 和 map 操作的工具函数 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[ComparisonHandler](#comparisonhandler)|暂无描述... -|`STRUCT`|[OrderedValueGetter](#orderedvaluegetter)|暂无描述... +|`STRUCT`|[ComparisonHandler](#struct_ComparisonHandler)|用于比较 `source` 和 `target` 两个值是否相同的比较函数 +|`STRUCT`|[OrderedValueGetter](#struct_OrderedValueGetter)|用于获取 v 的可排序字段值的函数
*** ## 详情信息 -#### func CloneSlice(slice S) S +#### func CloneSlice\[S ~[]V, V any\](slice S) S -> 克隆切片，该函数是 slices.Clone 的快捷方式 +> 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片 + +**示例代码：** + +在该示例中，将 slice 克隆后将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 + - 示例中的结果将会输出 [1 2 3] + -示例代码： ```go func ExampleCloneSlice() { @@ -190,11 +213,17 @@ func TestCloneSlice(t *testing.T) { *** -#### func CloneMap(m M) M +#### func CloneMap\[M ~map[K]V, K comparable, V any\](m M) M -> 克隆 map +> 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map +> - 当 m 为空时，将会返回 nil + +**示例代码：** + +在该示例中，将 map 克隆后将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 + - 示例中的结果将会输出 3 + -示例代码： ```go func ExampleCloneMap() { @@ -239,11 +268,18 @@ func TestCloneMap(t *testing.T) { *** -#### func CloneSliceN(slice S, n int) []S +#### func CloneSliceN\[S ~[]V, V any\](slice S, n int) []S -> 克隆 slice 为 n 个切片进行返回 +> 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 +> - 当 slice 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 + +**示例代码：** + +通过将 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 + - result 的结果为 [[1 2 3] [1 2 3]] + - 示例中的结果将会输出 2 + -示例代码： ```go func ExampleCloneSliceN() { @@ -294,11 +330,18 @@ func TestCloneSliceN(t *testing.T) { *** -#### func CloneMapN(m M, n int) []M +#### func CloneMapN\[M ~map[K]V, K comparable, V any\](m M, n int) []M -> 克隆 map 为 n 个 map 进行返回 +> 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map +> - 当 m 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 + +**示例代码：** + +通过将 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 + - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对` + - 示例中的结果将会输出 2 + -示例代码： ```go func ExampleCloneMapN() { @@ -349,11 +392,18 @@ func TestCloneMapN(t *testing.T) { *** -#### func CloneSlices(slices ...S) []S +#### func CloneSlices\[S ~[]V, V any\](slices ...S) []S -> 克隆多个切片 +> 对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片 +> - 当 slices 为空时，将会返回 nil +> - 该函数相当于使用 CloneSlice 函数一次性对多个切片进行克隆 + +**示例代码：** + +通过将多个 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 + - result 的结果为 [[1 2 3] [1 2 3]] + -示例代码： ```go func ExampleCloneSlices() { @@ -401,11 +451,18 @@ func TestCloneSlices(t *testing.T) { *** -#### func CloneMaps(maps ...M) []M +#### func CloneMaps\[M ~map[K]V, K comparable, V any\](maps ...M) []M -> 克隆多个 map +> 对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片 +> - 当 maps 为空时，将会返回 nil +> - 该函数相当于使用 CloneMap 函数一次性对多个 map 进行克隆 + +**示例代码：** + +通过将多个 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 + - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对` + -示例代码： ```go func ExampleCloneMaps() { @@ -453,11 +510,220 @@ func TestCloneMaps(t *testing.T) { *** -#### func InSlice(slice S, v V, handler ComparisonHandler[V]) bool +#### func EqualSlice\[S ~[]V, V any\](slice1 S, slice2 S, handler ComparisonHandler[V]) bool + +> 检查两个切片是否相等，当 handler 返回 true 时，表示 slice1 中的某个元素和 slice2 中的某个元素相匹配 +> - 当两个切片的容量不同时，不会影响最终的比较结果 + +**示例代码：** + +```go + +func ExampleEqualSlice() { + s1 := []int{1, 2, 3} + s2 := []int{1} + s3 := []int{1, 2, 3} + fmt.Println(collection.EqualSlice(s1, s2, func(source, target int) bool { + return source == target + })) + fmt.Println(collection.EqualSlice(s1, s3, func(source, target int) bool { + return source == target + })) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestEqualSlice(t *testing.T) { + var cases = []struct { + name string + input []int + inputV []int + expected bool + }{{"TestEqualSlice_NonEmptySliceEqual", []int{1, 2, 3}, []int{1, 2, 3}, true}, {"TestEqualSlice_NonEmptySliceNotEqual", []int{1, 2, 3}, []int{1, 2}, false}, {"TestEqualSlice_EmptySlice", []int{}, []int{}, true}, {"TestEqualSlice_NilSlice", nil, nil, true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualSlice(c.input, c.inputV, func(source, target int) bool { + return source == target + }) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", c.name, c.expected, actual, "not as expected") + } + }) + } +} + +``` + + +
+ + +*** +#### func EqualComparableSlice\[S ~[]V, V comparable\](slice1 S, slice2 S) bool + +> 检查两个切片的值是否相同 +> - 当两个切片的容量不同时，不会影响最终的比较结果 + +**示例代码：** + +```go + +func ExampleEqualComparableSlice() { + s1 := []int{1, 2, 3} + s2 := []int{1} + s3 := []int{1, 2, 3} + fmt.Println(collection.EqualComparableSlice(s1, s2)) + fmt.Println(collection.EqualComparableSlice(s1, s3)) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestEqualComparableSlice(t *testing.T) { + var cases = []struct { + name string + input []int + inputV []int + expected bool + }{{"TestEqualComparableSlice_NonEmptySliceEqual", []int{1, 2, 3}, []int{1, 2, 3}, true}, {"TestEqualComparableSlice_NonEmptySliceNotEqual", []int{1, 2, 3}, []int{1, 2}, false}, {"TestEqualComparableSlice_EmptySlice", []int{}, []int{}, true}, {"TestEqualComparableSlice_NilSlice", nil, nil, true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualComparableSlice(c.input, c.inputV) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", c.name, c.expected, actual, "not as expected") + } + }) + } +} + +``` + + +
+ + +*** +#### func EqualMap\[M ~map[K]V, K comparable, V any\](map1 M, map2 M, handler ComparisonHandler[V]) bool + +> 检查两个 map 是否相等，当 handler 返回 true 时，表示 map1 中的某个元素和 map2 中的某个元素相匹配 +> - 当两个 map 的容量不同时，不会影响最终的比较结果 + +**示例代码：** + +```go + +func ExampleEqualMap() { + m1 := map[string]int{"a": 1, "b": 2} + m2 := map[string]int{"a": 1} + m3 := map[string]int{"a": 1, "b": 2} + fmt.Println(collection.EqualMap(m1, m2, func(source, target int) bool { + return source == target + })) + fmt.Println(collection.EqualMap(m1, m3, func(source, target int) bool { + return source == target + })) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestEqualMap(t *testing.T) { + var cases = []struct { + name string + input map[int]int + inputV map[int]int + expected bool + }{{"TestEqualMap_NonEmptyMapEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1, 2: 2}, true}, {"TestEqualMap_NonEmptyMapNotEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1}, false}, {"TestEqualMap_EmptyMap", map[int]int{}, map[int]int{}, true}, {"TestEqualMap_NilMap", nil, nil, true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualMap(c.input, c.inputV, func(source, target int) bool { + return source == target + }) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", c.name, c.expected, actual, "not as expected") + } + }) + } +} + +``` + + +
+ + +*** +#### func EqualComparableMap\[M ~map[K]V, K comparable, V comparable\](map1 M, map2 M) bool + +> 检查两个 map 的值是否相同 +> - 当两个 map 的容量不同时，不会影响最终的比较结果 + +**示例代码：** + +```go + +func ExampleEqualComparableMap() { + m1 := map[string]int{"a": 1, "b": 2} + m2 := map[string]int{"a": 1} + m3 := map[string]int{"a": 1, "b": 2} + fmt.Println(collection.EqualComparableMap(m1, m2)) + fmt.Println(collection.EqualComparableMap(m1, m3)) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestEqualComparableMap(t *testing.T) { + var cases = []struct { + name string + input map[int]int + inputV map[int]int + expected bool + }{{"TestEqualComparableMap_NonEmptyMapEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1, 2: 2}, true}, {"TestEqualComparableMap_NonEmptyMapNotEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1}, false}, {"TestEqualComparableMap_EmptyMap", map[int]int{}, map[int]int{}, true}, {"TestEqualComparableMap_NilMap", nil, nil, true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualComparableMap(c.input, c.inputV) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", c.name, c.expected, actual, "not as expected") + } + }) + } +} + +``` + + +
+ + +*** +#### func InSlice\[S ~[]V, V any\](slice S, v V, handler ComparisonHandler[V]) bool > 检查 v 是否被包含在 slice 中，当 handler 返回 true 时，表示 v 和 slice 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleInSlice() { @@ -501,11 +767,12 @@ func TestInSlice(t *testing.T) { *** -#### func InComparableSlice(slice S, v V) bool +#### func InComparableSlice\[S ~[]V, V comparable\](slice S, v V) bool > 检查 v 是否被包含在 slice 中 -示例代码： +**示例代码：** + ```go func ExampleInComparableSlice() { @@ -545,13 +812,14 @@ func TestInComparableSlice(t *testing.T) { *** -#### func AllInSlice(slice S, values []V, handler ComparisonHandler[V]) bool +#### func AllInSlice\[S ~[]V, V any\](slice S, values []V, handler ComparisonHandler[V]) bool > 检查 values 中的所有元素是否均被包含在 slice 中，当 handler 返回 true 时，表示 values 中的某个元素和 slice 中的某个元素相匹配 > - 在所有 values 中的元素都被包含在 slice 中时，返回 true > - 当 values 长度为 0 或为 nil 时，将返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInSlice() { @@ -595,13 +863,14 @@ func TestAllInSlice(t *testing.T) { *** -#### func AllInComparableSlice(slice S, values []V) bool +#### func AllInComparableSlice\[S ~[]V, V comparable\](slice S, values []V) bool > 检查 values 中的所有元素是否均被包含在 slice 中 > - 在所有 values 中的元素都被包含在 slice 中时，返回 true > - 当 values 长度为 0 或为 nil 时，将返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInComparableSlice() { @@ -641,12 +910,13 @@ func TestAllInComparableSlice(t *testing.T) { *** -#### func AnyInSlice(slice S, values []V, handler ComparisonHandler[V]) bool +#### func AnyInSlice\[S ~[]V, V any\](slice S, values []V, handler ComparisonHandler[V]) bool > 检查 values 中的任意一个元素是否被包含在 slice 中，当 handler 返回 true 时，表示 value 中的某个元素和 slice 中的某个元素相匹配 > - 当 values 中的任意一个元素被包含在 slice 中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInSlice() { @@ -690,12 +960,13 @@ func TestAnyInSlice(t *testing.T) { *** -#### func AnyInComparableSlice(slice S, values []V) bool +#### func AnyInComparableSlice\[S ~[]V, V comparable\](slice S, values []V) bool > 检查 values 中的任意一个元素是否被包含在 slice 中 > - 当 values 中的任意一个元素被包含在 slice 中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInComparableSlice() { @@ -735,12 +1006,13 @@ func TestAnyInComparableSlice(t *testing.T) { *** -#### func InSlices(slices []S, v V, handler ComparisonHandler[V]) bool +#### func InSlices\[S ~[]V, V any\](slices []S, v V, handler ComparisonHandler[V]) bool > 通过将多个切片合并后检查 v 是否被包含在 slices 中，当 handler 返回 true 时，表示 v 和 slices 中的某个元素相匹配 > - 当传入的 v 被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInSlices() { @@ -784,12 +1056,13 @@ func TestInSlices(t *testing.T) { *** -#### func InComparableSlices(slices []S, v V) bool +#### func InComparableSlices\[S ~[]V, V comparable\](slices []S, v V) bool > 通过将多个切片合并后检查 v 是否被包含在 slices 中 > - 当传入的 v 被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInComparableSlices() { @@ -829,12 +1102,13 @@ func TestInComparableSlices(t *testing.T) { *** -#### func AllInSlices(slices []S, values []V, handler ComparisonHandler[V]) bool +#### func AllInSlices\[S ~[]V, V any\](slices []S, values []V, handler ComparisonHandler[V]) bool > 通过将多个切片合并后检查 values 中的所有元素是否被包含在 slices 中，当 handler 返回 true 时，表示 values 中的某个元素和 slices 中的某个元素相匹配 > - 当 values 中的所有元素都被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInSlices() { @@ -878,12 +1152,13 @@ func TestAllInSlices(t *testing.T) { *** -#### func AllInComparableSlices(slices []S, values []V) bool +#### func AllInComparableSlices\[S ~[]V, V comparable\](slices []S, values []V) bool > 通过将多个切片合并后检查 values 中的所有元素是否被包含在 slices 中 > - 当 values 中的所有元素都被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAllInComparableSlices() { @@ -923,12 +1198,13 @@ func TestAllInComparableSlices(t *testing.T) { *** -#### func AnyInSlices(slices []S, values []V, handler ComparisonHandler[V]) bool +#### func AnyInSlices\[S ~[]V, V any\](slices []S, values []V, handler ComparisonHandler[V]) bool > 通过将多个切片合并后检查 values 中的任意一个元素是否被包含在 slices 中，当 handler 返回 true 时，表示 values 中的某个元素和 slices 中的某个元素相匹配 > - 当 values 中的任意一个元素被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInSlices() { @@ -972,12 +1248,13 @@ func TestAnyInSlices(t *testing.T) { *** -#### func AnyInComparableSlices(slices []S, values []V) bool +#### func AnyInComparableSlices\[S ~[]V, V comparable\](slices []S, values []V) bool > 通过将多个切片合并后检查 values 中的任意一个元素是否被包含在 slices 中 > - 当 values 中的任意一个元素被包含在 slices 的任一成员中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInComparableSlices() { @@ -1017,12 +1294,13 @@ func TestAnyInComparableSlices(t *testing.T) { *** -#### func InAllSlices(slices []S, v V, handler ComparisonHandler[V]) bool +#### func InAllSlices\[S ~[]V, V any\](slices []S, v V, handler ComparisonHandler[V]) bool > 检查 v 是否被包含在 slices 的每一项元素中，当 handler 返回 true 时，表示 v 和 slices 中的某个元素相匹配 > - 当 v 被包含在 slices 的每一项元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInAllSlices() { @@ -1066,12 +1344,13 @@ func TestInAllSlices(t *testing.T) { *** -#### func InAllComparableSlices(slices []S, v V) bool +#### func InAllComparableSlices\[S ~[]V, V comparable\](slices []S, v V) bool > 检查 v 是否被包含在 slices 的每一项元素中 > - 当 v 被包含在 slices 的每一项元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleInAllComparableSlices() { @@ -1111,12 +1390,13 @@ func TestInAllComparableSlices(t *testing.T) { *** -#### func AnyInAllSlices(slices []S, values []V, handler ComparisonHandler[V]) bool +#### func AnyInAllSlices\[S ~[]V, V any\](slices []S, values []V, handler ComparisonHandler[V]) bool > 检查 slices 中的每一个元素是否均包含至少任意一个 values 中的元素，当 handler 返回 true 时，表示 value 中的某个元素和 slices 中的某个元素相匹配 > - 当 slices 中的每一个元素均包含至少任意一个 values 中的元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInAllSlices() { @@ -1160,12 +1440,13 @@ func TestAnyInAllSlices(t *testing.T) { *** -#### func AnyInAllComparableSlices(slices []S, values []V) bool +#### func AnyInAllComparableSlices\[S ~[]V, V comparable\](slices []S, values []V) bool > 检查 slices 中的每一个元素是否均包含至少任意一个 values 中的元素 > - 当 slices 中的每一个元素均包含至少任意一个 values 中的元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyInAllComparableSlices() { @@ -1205,11 +1486,12 @@ func TestAnyInAllComparableSlices(t *testing.T) { *** -#### func KeyInMap(m M, key K) bool +#### func KeyInMap\[M ~map[K]V, K comparable, V any\](m M, key K) bool > 检查 m 中是否包含特定 key -示例代码： +**示例代码：** + ```go func ExampleKeyInMap() { @@ -1249,11 +1531,12 @@ func TestKeyInMap(t *testing.T) { *** -#### func ValueInMap(m M, value V, handler ComparisonHandler[V]) bool +#### func ValueInMap\[M ~map[K]V, K comparable, V any\](m M, value V, handler ComparisonHandler[V]) bool > 检查 m 中是否包含特定 value，当 handler 返回 true 时，表示 value 和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleValueInMap() { @@ -1296,11 +1579,12 @@ func TestValueInMap(t *testing.T) { *** -#### func AllKeyInMap(m M, keys ...K) bool +#### func AllKeyInMap\[M ~map[K]V, K comparable, V any\](m M, keys ...K) bool > 检查 m 中是否包含 keys 中所有的元素 -示例代码： +**示例代码：** + ```go func ExampleAllKeyInMap() { @@ -1340,11 +1624,12 @@ func TestAllKeyInMap(t *testing.T) { *** -#### func AllValueInMap(m M, values []V, handler ComparisonHandler[V]) bool +#### func AllValueInMap\[M ~map[K]V, K comparable, V any\](m M, values []V, handler ComparisonHandler[V]) bool > 检查 m 中是否包含 values 中所有的元素，当 handler 返回 true 时，表示 values 中的某个元素和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAllValueInMap() { @@ -1386,11 +1671,12 @@ func TestAllValueInMap(t *testing.T) { *** -#### func AnyKeyInMap(m M, keys ...K) bool +#### func AnyKeyInMap\[M ~map[K]V, K comparable, V any\](m M, keys ...K) bool > 检查 m 中是否包含 keys 中任意一个元素 -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInMap() { @@ -1430,11 +1716,12 @@ func TestAnyKeyInMap(t *testing.T) { *** -#### func AnyValueInMap(m M, values []V, handler ComparisonHandler[V]) bool +#### func AnyValueInMap\[M ~map[K]V, K comparable, V any\](m M, values []V, handler ComparisonHandler[V]) bool > 检查 m 中是否包含 values 中任意一个元素，当 handler 返回 true 时，表示 values 中的某个元素和 m 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAnyValueInMap() { @@ -1476,11 +1763,12 @@ func TestAnyValueInMap(t *testing.T) { *** -#### func AllKeyInMaps(maps []M, keys ...K) bool +#### func AllKeyInMaps\[M ~map[K]V, K comparable, V any\](maps []M, keys ...K) bool > 检查 maps 中的每一个元素是否均包含 keys 中所有的元素 -示例代码： +**示例代码：** + ```go func ExampleAllKeyInMaps() { @@ -1520,11 +1808,12 @@ func TestAllKeyInMaps(t *testing.T) { *** -#### func AllValueInMaps(maps []M, values []V, handler ComparisonHandler[V]) bool +#### func AllValueInMaps\[M ~map[K]V, K comparable, V any\](maps []M, values []V, handler ComparisonHandler[V]) bool > 检查 maps 中的每一个元素是否均包含 value 中所有的元素，当 handler 返回 true 时，表示 value 中的某个元素和 maps 中的某个元素相匹配 -示例代码： +**示例代码：** + ```go func ExampleAllValueInMaps() { @@ -1566,12 +1855,13 @@ func TestAllValueInMaps(t *testing.T) { *** -#### func AnyKeyInMaps(maps []M, keys ...K) bool +#### func AnyKeyInMaps\[M ~map[K]V, K comparable, V any\](maps []M, keys ...K) bool > 检查 keys 中的任意一个元素是否被包含在 maps 中的任意一个元素中 > - 当 keys 中的任意一个元素被包含在 maps 中的任意一个元素中时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInMaps() { @@ -1611,12 +1901,13 @@ func TestAnyKeyInMaps(t *testing.T) { *** -#### func AnyValueInMaps(maps []M, values []V, handler ComparisonHandler[V]) bool +#### func AnyValueInMaps\[M ~map[K]V, K comparable, V any\](maps []M, values []V, handler ComparisonHandler[V]) bool > 检查 maps 中的任意一个元素是否包含 value 中的任意一个元素，当 handler 返回 true 时，表示 value 中的某个元素和 maps 中的某个元素相匹配 > - 当 maps 中的任意一个元素包含 value 中的任意一个元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyValueInMaps() { @@ -1658,11 +1949,12 @@ func TestAnyValueInMaps(t *testing.T) { *** -#### func KeyInAllMaps(maps []M, key K) bool +#### func KeyInAllMaps\[M ~map[K]V, K comparable, V any\](maps []M, key K) bool > 检查 key 是否被包含在 maps 的每一个元素中 -示例代码： +**示例代码：** + ```go func ExampleKeyInAllMaps() { @@ -1702,12 +1994,13 @@ func TestKeyInAllMaps(t *testing.T) { *** -#### func AnyKeyInAllMaps(maps []M, keys []K) bool +#### func AnyKeyInAllMaps\[M ~map[K]V, K comparable, V any\](maps []M, keys []K) bool > 检查 maps 中的每一个元素是否均包含 keys 中任意一个元素 > - 当 maps 中的每一个元素均包含 keys 中任意一个元素时，返回 true -示例代码： +**示例代码：** + ```go func ExampleAnyKeyInAllMaps() { @@ -1747,11 +2040,164 @@ func TestAnyKeyInAllMaps(t *testing.T) { *** -#### func ConvertSliceToAny(s S) []any +#### func ConvertSliceToBatches\[S ~[]V, V any\](s S, batchSize int) []S + +> 将切片 s 转换为分批次的切片，当 batchSize 小于等于 0 或者 s 长度为 0 时，将会返回 nil + +**示例代码：** + +```go + +func ExampleConvertSliceToBatches() { + result := collection.ConvertSliceToBatches([]int{1, 2, 3}, 2) + for _, v := range result { + fmt.Println(v) + } +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestConvertSliceToBatches(t *testing.T) { + var cases = []struct { + name string + input []int + batch int + expected [][]int + }{{name: "TestConvertSliceToBatches_NonEmpty", input: []int{1, 2, 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, {name: "TestConvertSliceToBatches_Empty", input: []int{}, batch: 2, expected: nil}, {name: "TestConvertSliceToBatches_Nil", input: nil, batch: 2, expected: nil}, {name: "TestConvertSliceToBatches_NonPositive", input: []int{1, 2, 3}, batch: 0, expected: nil}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertSliceToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + for i := 0; i < len(actual); i++ { + av, ev := actual[i], c.expected[i] + if len(av) != len(ev) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + for j := 0; j < len(av); j++ { + aj, ej := av[j], ev[j] + if reflect.TypeOf(aj).Kind() != reflect.TypeOf(ej).Kind() { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + if aj != ej { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + } + } + }) + } +} + +``` + + +
+ + +*** +#### func ConvertMapKeysToBatches\[M ~map[K]V, K comparable, V any\](m M, batchSize int) [][]K + +> 将映射的键转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil + +**示例代码：** + +```go + +func ExampleConvertMapKeysToBatches() { + result := collection.ConvertMapKeysToBatches(map[int]int{1: 1, 2: 2, 3: 3}, 2) + fmt.Println(len(result)) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestConvertMapKeysToBatches(t *testing.T) { + var cases = []struct { + name string + input map[int]int + batch int + expected [][]int + }{{name: "TestConvertMapKeysToBatches_NonEmpty", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, {name: "TestConvertMapKeysToBatches_Empty", input: map[int]int{}, batch: 2, expected: nil}, {name: "TestConvertMapKeysToBatches_Nil", input: nil, batch: 2, expected: nil}, {name: "TestConvertMapKeysToBatches_NonPositive", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 0, expected: nil}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertMapKeysToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + }) + } +} + +``` + + +
+ + +*** +#### func ConvertMapValuesToBatches\[M ~map[K]V, K comparable, V any\](m M, batchSize int) [][]V + +> 将映射的值转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil + +**示例代码：** + +```go + +func ExampleConvertMapValuesToBatches() { + result := collection.ConvertMapValuesToBatches(map[int]int{1: 1, 2: 2, 3: 3}, 2) + fmt.Println(len(result)) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestConvertMapValuesToBatches(t *testing.T) { + var cases = []struct { + name string + input map[int]int + batch int + expected [][]int + }{{name: "TestConvertMapValuesToBatches_NonEmpty", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, {name: "TestConvertMapValuesToBatches_Empty", input: map[int]int{}, batch: 2, expected: nil}, {name: "TestConvertMapValuesToBatches_Nil", input: nil, batch: 2, expected: nil}, {name: "TestConvertMapValuesToBatches_NonPositive", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 0, expected: nil}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertMapValuesToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + }) + } +} + +``` + + +
+ + +*** +#### func ConvertSliceToAny\[S ~[]V, V any\](s S) []any > 将切片转换为任意类型的切片 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToAny() { @@ -1799,11 +2245,12 @@ func TestConvertSliceToAny(t *testing.T) { *** -#### func ConvertSliceToIndexMap(s S) map[int]V +#### func ConvertSliceToIndexMap\[S ~[]V, V any\](s S) map[int]V > 将切片转换为索引为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToIndexMap() { @@ -1850,11 +2297,12 @@ func TestConvertSliceToIndexMap(t *testing.T) { *** -#### func ConvertSliceToIndexOnlyMap(s S) map[int]struct {} +#### func ConvertSliceToIndexOnlyMap\[S ~[]V, V any\](s S) map[int]struct {} > 将切片转换为索引为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToIndexOnlyMap() { @@ -1905,11 +2353,12 @@ func TestConvertSliceToIndexOnlyMap(t *testing.T) { *** -#### func ConvertSliceToMap(s S) map[V]struct {} +#### func ConvertSliceToMap\[S ~[]V, V comparable\](s S) map[V]struct {} > 将切片转换为值为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToMap() { @@ -1957,11 +2406,12 @@ func TestConvertSliceToMap(t *testing.T) { *** -#### func ConvertSliceToBoolMap(s S) map[V]bool +#### func ConvertSliceToBoolMap\[S ~[]V, V comparable\](s S) map[V]bool > 将切片转换为值为键的映射 -示例代码： +**示例代码：** + ```go func ExampleConvertSliceToBoolMap() { @@ -2008,15 +2458,17 @@ func TestConvertSliceToBoolMap(t *testing.T) { *** -#### func ConvertMapKeysToSlice(m M) []K +#### func ConvertMapKeysToSlice\[M ~map[K]V, K comparable, V any\](m M) []K > 将映射的键转换为切片 -示例代码： +**示例代码：** + ```go func ExampleConvertMapKeysToSlice() { result := collection.ConvertMapKeysToSlice(map[int]int{1: 1, 2: 2, 3: 3}) + sort.Ints(result) for i, v := range result { fmt.Println(i, v) } @@ -2064,11 +2516,12 @@ func TestConvertMapKeysToSlice(t *testing.T) { *** -#### func ConvertMapValuesToSlice(m M) []V +#### func ConvertMapValuesToSlice\[M ~map[K]V, K comparable, V any\](m M) []V > 将映射的值转换为切片 -示例代码： +**示例代码：** + ```go func ExampleConvertMapValuesToSlice() { @@ -2121,11 +2574,12 @@ func TestConvertMapValuesToSlice(t *testing.T) { *** -#### func InvertMap(m M) N +#### func InvertMap\[M ~map[K]V, N map[V]K, K comparable, V comparable\](m M) N > 将映射的键和值互换 -示例代码： +**示例代码：** + ```go func ExampleInvertMap() { @@ -2169,11 +2623,12 @@ func TestInvertMap(t *testing.T) { *** -#### func ConvertMapValuesToBool(m M) N +#### func ConvertMapValuesToBool\[M ~map[K]V, N map[K]bool, K comparable, V any\](m M) N > 将映射的值转换为布尔值 -示例代码： +**示例代码：** + ```go func ExampleConvertMapValuesToBool() { @@ -2217,11 +2672,12 @@ func TestConvertMapValuesToBool(t *testing.T) { *** -#### func ReverseSlice(s *S) +#### func ReverseSlice\[S ~[]V, V any\](s *S) > 将切片反转 -示例代码： +**示例代码：** + ```go func ExampleReverseSlice() { @@ -2270,11 +2726,12 @@ func TestReverseSlice(t *testing.T) { *** -#### func ClearSlice(slice *S) +#### func ClearSlice\[S ~[]V, V any\](slice *S) > 清空切片 -示例代码： +**示例代码：** + ```go func ExampleClearSlice() { @@ -2319,11 +2776,12 @@ func TestClearSlice(t *testing.T) { *** -#### func ClearMap(m M) +#### func ClearMap\[M ~map[K]V, K comparable, V any\](m M) > 清空 map -示例代码： +**示例代码：** + ```go func ExampleClearMap() { @@ -2368,11 +2826,12 @@ func TestClearMap(t *testing.T) { *** -#### func DropSliceByIndices(slice *S, indices ...int) +#### func DropSliceByIndices\[S ~[]V, V any\](slice *S, indices ...int) > 删除切片中特定索引的元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceByIndices() { @@ -2418,12 +2877,13 @@ func TestDropSliceByIndices(t *testing.T) { *** -#### func DropSliceByCondition(slice *S, condition func (v V) bool) +#### func DropSliceByCondition\[S ~[]V, V any\](slice *S, condition func (v V) bool) > 删除切片中符合条件的元素 > - condition 的返回值为 true 时，将会删除该元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceByCondition() { @@ -2479,11 +2939,12 @@ func TestDropSliceByCondition(t *testing.T) { *** -#### func DropSliceOverlappingElements(slice *S, anotherSlice []V, comparisonHandler ComparisonHandler[V]) +#### func DropSliceOverlappingElements\[S ~[]V, V any\](slice *S, anotherSlice []V, comparisonHandler ComparisonHandler[V]) > 删除切片中与另一个切片重叠的元素 -示例代码： +**示例代码：** + ```go func ExampleDropSliceOverlappingElements() { @@ -2542,11 +3003,12 @@ func TestDropSliceOverlappingElements(t *testing.T) { *** -#### func DeduplicateSliceInPlace(s *S) +#### func DeduplicateSliceInPlace\[S ~[]V, V comparable\](s *S) > 去除切片中的重复元素 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceInPlace() { @@ -2592,11 +3054,12 @@ func TestDeduplicateSliceInPlace(t *testing.T) { *** -#### func DeduplicateSlice(s S) S +#### func DeduplicateSlice\[S ~[]V, V comparable\](s S) S > 去除切片中的重复元素，返回新切片 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSlice() { @@ -2641,11 +3104,12 @@ func TestDeduplicateSlice(t *testing.T) { *** -#### func DeduplicateSliceInPlaceWithCompare(s *S, compare func (a V) bool) +#### func DeduplicateSliceInPlaceWithCompare\[S ~[]V, V any\](s *S, compare func (a V) bool) > 去除切片中的重复元素，使用自定义的比较函数 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceInPlaceWithCompare() { @@ -2695,11 +3159,12 @@ func TestDeduplicateSliceInPlaceWithCompare(t *testing.T) { *** -#### func DeduplicateSliceWithCompare(s S, compare func (a V) bool) S +#### func DeduplicateSliceWithCompare\[S ~[]V, V any\](s S, compare func (a V) bool) S > 去除切片中的重复元素，使用自定义的比较函数，返回新的切片 -示例代码： +**示例代码：** + ```go func ExampleDeduplicateSliceWithCompare() { @@ -2748,11 +3213,12 @@ func TestDeduplicateSliceWithCompare(t *testing.T) { *** -#### func FilterOutByIndices(slice S, indices ...int) S +#### func FilterOutByIndices\[S []V, V any\](slice S, indices ...int) S > 过滤切片中特定索引的元素，返回过滤后的切片 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByIndices() { @@ -2798,12 +3264,13 @@ func TestFilterOutByIndices(t *testing.T) { *** -#### func FilterOutByCondition(slice S, condition func (v V) bool) S +#### func FilterOutByCondition\[S ~[]V, V any\](slice S, condition func (v V) bool) S > 过滤切片中符合条件的元素，返回过滤后的切片 > - condition 的返回值为 true 时，将会过滤掉该元素 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByCondition() { @@ -2857,11 +3324,12 @@ func TestFilterOutByCondition(t *testing.T) { *** -#### func FilterOutByKey(m M, key K) M +#### func FilterOutByKey\[M ~map[K]V, K comparable, V any\](m M, key K) M > 过滤 map 中特定的 key，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByKey() { @@ -2907,11 +3375,12 @@ func TestFilterOutByKey(t *testing.T) { *** -#### func FilterOutByValue(m M, value V, handler ComparisonHandler[V]) M +#### func FilterOutByValue\[M ~map[K]V, K comparable, V any\](m M, value V, handler ComparisonHandler[V]) M > 过滤 map 中特定的 value，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByValue() { @@ -2961,11 +3430,12 @@ func TestFilterOutByValue(t *testing.T) { *** -#### func FilterOutByKeys(m M, keys ...K) M +#### func FilterOutByKeys\[M ~map[K]V, K comparable, V any\](m M, keys ...K) M > 过滤 map 中多个 key，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByKeys() { @@ -3011,11 +3481,12 @@ func TestFilterOutByKeys(t *testing.T) { *** -#### func FilterOutByValues(m M, values []V, handler ComparisonHandler[V]) M +#### func FilterOutByValues\[M ~map[K]V, K comparable, V any\](m M, values []V, handler ComparisonHandler[V]) M > 过滤 map 中多个 values，返回过滤后的 map -示例代码： +**示例代码：** + ```go func ExampleFilterOutByValues() { @@ -3067,12 +3538,13 @@ func TestFilterOutByValues(t *testing.T) { *** -#### func FilterOutByMap(m M, condition func (k K, v V) bool) M +#### func FilterOutByMap\[M ~map[K]V, K comparable, V any\](m M, condition func (k K, v V) bool) M > 过滤 map 中符合条件的元素，返回过滤后的 map > - condition 的返回值为 true 时，将会过滤掉该元素 -示例代码： +**示例代码：** + ```go func ExampleFilterOutByMap() { @@ -3122,12 +3594,13 @@ func TestFilterOutByMap(t *testing.T) { *** -#### func FindLoopedNextInSlice(slice S, i int) (next int, value V) +#### func FindLoopedNextInSlice\[S ~[]V, V any\](slice S, i int) (next int, value V) > 返回 i 的下一个数组成员，当 i 达到数组长度时从 0 开始 > - 当 i 为负数时将返回第一个元素 -示例代码： +**示例代码：** + ```go func ExampleFindLoopedNextInSlice() { @@ -3167,12 +3640,13 @@ func TestFindLoopedNextInSlice(t *testing.T) { *** -#### func FindLoopedPrevInSlice(slice S, i int) (prev int, value V) +#### func FindLoopedPrevInSlice\[S ~[]V, V any\](slice S, i int) (prev int, value V) > 返回 i 的上一个数组成员，当 i 为 0 时从数组末尾开始 > - 当 i 为负数时将返回最后一个元素 -示例代码： +**示例代码：** + ```go func ExampleFindLoopedPrevInSlice() { @@ -3212,11 +3686,12 @@ func TestFindLoopedPrevInSlice(t *testing.T) { *** -#### func FindCombinationsInSliceByRange(s S, minSize int, maxSize int) []S +#### func FindCombinationsInSliceByRange\[S ~[]V, V any\](s S, minSize int, maxSize int) []S > 获取给定数组的所有组合，且每个组合的成员数量限制在指定范围内 -示例代码： +**示例代码：** + ```go func ExampleFindCombinationsInSliceByRange() { @@ -3257,11 +3732,12 @@ func TestFindCombinationsInSliceByRange(t *testing.T) { *** -#### func FindFirstOrDefaultInSlice(slice S, defaultValue V) V +#### func FindFirstOrDefaultInSlice\[S ~[]V, V any\](slice S, defaultValue V) V > 判断切片中是否存在元素，返回第一个元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindFirstOrDefaultInSlice() { @@ -3300,11 +3776,12 @@ func TestFindFirstOrDefaultInSlice(t *testing.T) { *** -#### func FindOrDefaultInSlice(slice S, defaultValue V, handler func (v V) bool) (t V) +#### func FindOrDefaultInSlice\[S ~[]V, V any\](slice S, defaultValue V, handler func (v V) bool) (t V) > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindOrDefaultInSlice() { @@ -3347,11 +3824,12 @@ func TestFindOrDefaultInSlice(t *testing.T) { *** -#### func FindOrDefaultInComparableSlice(slice S, v V, defaultValue V) (t V) +#### func FindOrDefaultInComparableSlice\[S ~[]V, V comparable\](slice S, v V, defaultValue V) (t V) > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则返回默认值 -示例代码： +**示例代码：** + ```go func ExampleFindOrDefaultInComparableSlice() { @@ -3390,11 +3868,12 @@ func TestFindOrDefaultInComparableSlice(t *testing.T) { *** -#### func FindInSlice(slice S, handler func (v V) bool) (i int, t V) +#### func FindInSlice\[S ~[]V, V any\](slice S, handler func (v V) bool) (i int, t V) > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindInSlice() { @@ -3437,11 +3916,12 @@ func TestFindInSlice(t *testing.T) { *** -#### func FindIndexInSlice(slice S, handler func (v V) bool) int +#### func FindIndexInSlice\[S ~[]V, V any\](slice S, handler func (v V) bool) int > 判断切片中是否存在某个元素，返回第一个匹配的索引，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindIndexInSlice() { @@ -3484,11 +3964,12 @@ func TestFindIndexInSlice(t *testing.T) { *** -#### func FindInComparableSlice(slice S, v V) (i int, t V) +#### func FindInComparableSlice\[S ~[]V, V comparable\](slice S, v V) (i int, t V) > 判断切片中是否存在某个元素，返回第一个匹配的索引和元素，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindInComparableSlice() { @@ -3527,11 +4008,12 @@ func TestFindInComparableSlice(t *testing.T) { *** -#### func FindIndexInComparableSlice(slice S, v V) int +#### func FindIndexInComparableSlice\[S ~[]V, V comparable\](slice S, v V) int > 判断切片中是否存在某个元素，返回第一个匹配的索引，不存在则索引返回 -1 -示例代码： +**示例代码：** + ```go func ExampleFindIndexInComparableSlice() { @@ -3570,11 +4052,12 @@ func TestFindIndexInComparableSlice(t *testing.T) { *** -#### func FindMinimumInComparableSlice(slice S) (result V) +#### func FindMinimumInComparableSlice\[S ~[]V, V generic.Ordered\](slice S) (result V) > 获取切片中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinimumInComparableSlice() { @@ -3613,11 +4096,12 @@ func TestFindMinimumInComparableSlice(t *testing.T) { *** -#### func FindMinimumInSlice(slice S, handler OrderedValueGetter[V, N]) (result V) +#### func FindMinimumInSlice\[S ~[]V, V any, N generic.Ordered\](slice S, handler OrderedValueGetter[V, N]) (result V) > 获取切片中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinimumInSlice() { @@ -3660,11 +4144,12 @@ func TestFindMinimumInSlice(t *testing.T) { *** -#### func FindMaximumInComparableSlice(slice S) (result V) +#### func FindMaximumInComparableSlice\[S ~[]V, V generic.Ordered\](slice S) (result V) > 获取切片中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaximumInComparableSlice() { @@ -3703,11 +4188,12 @@ func TestFindMaximumInComparableSlice(t *testing.T) { *** -#### func FindMaximumInSlice(slice S, handler OrderedValueGetter[V, N]) (result V) +#### func FindMaximumInSlice\[S ~[]V, V any, N generic.Ordered\](slice S, handler OrderedValueGetter[V, N]) (result V) > 获取切片中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaximumInSlice() { @@ -3750,11 +4236,12 @@ func TestFindMaximumInSlice(t *testing.T) { *** -#### func FindMin2MaxInComparableSlice(slice S) (min V, max V) +#### func FindMin2MaxInComparableSlice\[S ~[]V, V generic.Ordered\](slice S) (min V, max V) > 获取切片中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxInComparableSlice() { @@ -3794,11 +4281,12 @@ func TestFindMin2MaxInComparableSlice(t *testing.T) { *** -#### func FindMin2MaxInSlice(slice S, handler OrderedValueGetter[V, N]) (min V, max V) +#### func FindMin2MaxInSlice\[S ~[]V, V any, N generic.Ordered\](slice S, handler OrderedValueGetter[V, N]) (min V, max V) > 获取切片中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxInSlice() { @@ -3842,11 +4330,12 @@ func TestFindMin2MaxInSlice(t *testing.T) { *** -#### func FindMinFromComparableMap(m M) (result V) +#### func FindMinFromComparableMap\[M ~map[K]V, K comparable, V generic.Ordered\](m M) (result V) > 获取 map 中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinFromComparableMap() { @@ -3885,11 +4374,12 @@ func TestFindMinFromComparableMap(t *testing.T) { *** -#### func FindMinFromMap(m M, handler OrderedValueGetter[V, N]) (result V) +#### func FindMinFromMap\[M ~map[K]V, K comparable, V any, N generic.Ordered\](m M, handler OrderedValueGetter[V, N]) (result V) > 获取 map 中的最小值 -示例代码： +**示例代码：** + ```go func ExampleFindMinFromMap() { @@ -3932,11 +4422,12 @@ func TestFindMinFromMap(t *testing.T) { *** -#### func FindMaxFromComparableMap(m M) (result V) +#### func FindMaxFromComparableMap\[M ~map[K]V, K comparable, V generic.Ordered\](m M) (result V) > 获取 map 中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaxFromComparableMap() { @@ -3975,11 +4466,12 @@ func TestFindMaxFromComparableMap(t *testing.T) { *** -#### func FindMaxFromMap(m M, handler OrderedValueGetter[V, N]) (result V) +#### func FindMaxFromMap\[M ~map[K]V, K comparable, V any, N generic.Ordered\](m M, handler OrderedValueGetter[V, N]) (result V) > 获取 map 中的最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMaxFromMap() { @@ -4022,11 +4514,12 @@ func TestFindMaxFromMap(t *testing.T) { *** -#### func FindMin2MaxFromComparableMap(m M) (min V, max V) +#### func FindMin2MaxFromComparableMap\[M ~map[K]V, K comparable, V generic.Ordered\](m M) (min V, max V) > 获取 map 中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxFromComparableMap() { @@ -4066,11 +4559,12 @@ func TestFindMin2MaxFromComparableMap(t *testing.T) { *** -#### func FindMin2MaxFromMap(m M) (min V, max V) +#### func FindMin2MaxFromMap\[M ~map[K]V, K comparable, V generic.Ordered\](m M) (min V, max V) > 获取 map 中的最小值和最大值 -示例代码： +**示例代码：** + ```go func ExampleFindMin2MaxFromMap() { @@ -4110,11 +4604,12 @@ func TestFindMin2MaxFromMap(t *testing.T) { *** -#### func SwapSlice(slice *S, i int, j int) +#### func SwapSlice\[S ~[]V, V any\](slice *S, i int, j int) > 将切片中的两个元素进行交换 -示例代码： +**示例代码：** + ```go func ExampleSwapSlice() { @@ -4158,11 +4653,675 @@ func TestSwapSlice(t *testing.T) { *** -#### func MappingFromSlice(slice S, handler func (value V) N) NS +#### func LoopSlice\[S ~[]V, V any\](slice S, f func (i int, val V) bool) + +> 迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopSlice() { + var result []int + collection.LoopSlice([]int{1, 2, 3, 4, 5}, func(i int, val int) bool { + result = append(result, val) + if uint(i) == 1 { + return false + } + return true + }) + fmt.Println(result) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopSlice(t *testing.T) { + var cases = []struct { + name string + in []int + out []int + breakIndex uint + }{{"TestLoopSlice_Part", []int{1, 2, 3, 4, 5}, []int{1, 2}, 2}, {"TestLoopSlice_All", []int{1, 2, 3, 4, 5}, []int{1, 2, 3, 4, 5}, 0}, {"TestLoopSlice_Empty", []int{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopSlice(c.in, func(i int, val int) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopSlice(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func ReverseLoopSlice\[S ~[]V, V any\](slice S, f func (i int, val V) bool) + +> 逆序迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleReverseLoopSlice() { + var result []int + collection.ReverseLoopSlice([]int{1, 2, 3, 4, 5}, func(i int, val int) bool { + result = append(result, val) + if uint(i) == 1 { + return false + } + return true + }) + fmt.Println(result) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestReverseLoopSlice(t *testing.T) { + var cases = []struct { + name string + in []int + out []int + breakIndex uint + }{{"TestReverseLoopSlice_Part", []int{1, 2, 3, 4, 5}, []int{5, 4}, 2}, {"TestReverseLoopSlice_All", []int{1, 2, 3, 4, 5}, []int{5, 4, 3, 2, 1}, 0}, {"TestReverseLoopSlice_Empty", []int{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.ReverseLoopSlice(c.in, func(i int, val int) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == uint(len(c.in))-c.breakIndex { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("ReverseLoopSlice(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMap\[M ~map[K]V, K comparable, V any\](m M, f func (i int, key K, val V) bool) + +> 迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - m 的迭代顺序是不确定的，因此每次迭代的顺序可能不同 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMap() { + var result []int + collection.LoopMap(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMap(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out map[int]string + breakIndex uint + }{{"TestLoopMap_Part", map[int]string{1: "1", 2: "2", 3: "3"}, map[int]string{1: "1", 2: "2"}, 2}, {"TestLoopMap_All", map[int]string{1: "1", 2: "2", 3: "3"}, map[int]string{1: "1", 2: "2", 3: "3"}, 0}, {"TestLoopMap_Empty", map[int]string{}, map[int]string{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result = make(map[int]string) + collection.LoopMap(c.in, func(i int, key int, val string) bool { + result[key] = val + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableMap(result, c.out) { + t.Errorf("LoopMap(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByOrderedKeyAsc\[M ~map[K]V, K generic.Ordered, V any\](m M, f func (i int, key K, val V) bool) + +> 按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByOrderedKeyAsc() { + var result []int + collection.LoopMapByOrderedKeyAsc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByOrderedKeyAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{{"TestLoopMapByOrderedKeyAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2}, 2}, {"TestLoopMapByOrderedKeyAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2, 3}, 0}, {"TestLoopMapByOrderedKeyAsc_Empty", map[int]string{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByOrderedKeyAsc(c.in, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedKeyAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByOrderedKeyDesc\[M ~map[K]V, K generic.Ordered, V any\](m M, f func (i int, key K, val V) bool) + +> 按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByOrderedKeyDesc() { + var result []int + collection.LoopMapByOrderedKeyDesc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByOrderedKeyDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{{"TestLoopMapByOrderedKeyDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2}, 2}, {"TestLoopMapByOrderedKeyDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2, 1}, 0}, {"TestLoopMapByOrderedKeyDesc_Empty", map[int]string{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByOrderedKeyDesc(c.in, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedKeyDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByOrderedValueAsc\[M ~map[K]V, K comparable, V generic.Ordered\](m M, f func (i int, key K, val V) bool) + +> 按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByOrderedValueAsc() { + var result []int + collection.LoopMapByOrderedValueAsc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByOrderedValueAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{{"TestLoopMapByOrderedValueAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2"}, 2}, {"TestLoopMapByOrderedValueAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2", "3"}, 0}, {"TestLoopMapByOrderedValueAsc_Empty", map[int]string{}, []string{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByOrderedValueAsc(c.in, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedValueAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByOrderedValueDesc\[M ~map[K]V, K comparable, V generic.Ordered\](m M, f func (i int, key K, val V) bool) + +> 按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByOrderedValueDesc() { + var result []int + collection.LoopMapByOrderedValueDesc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByOrderedValueDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{{"TestLoopMapByOrderedValueDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2"}, 2}, {"TestLoopMapByOrderedValueDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2", "1"}, 0}, {"TestLoopMapByOrderedValueDesc_Empty", map[int]string{}, []string{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByOrderedValueDesc(c.in, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedValueDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByKeyGetterAsc\[M ~map[K]V, K comparable, V comparable, N generic.Ordered\](m M, getter func (k K) N, f func (i int, key K, val V) bool) + +> 按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByKeyGetterAsc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByKeyGetterAsc(m, func(k string) int { + return m[k] + }, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByKeyGetterAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{{"TestLoopMapByKeyGetterAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2}, 2}, {"TestLoopMapByKeyGetterAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2, 3}, 0}, {"TestLoopMapByKeyGetterAsc_Empty", map[int]string{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByKeyGetterAsc(c.in, func(key int) int { + return key + }, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByKeyGetterAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByValueGetterAsc\[M ~map[K]V, K comparable, V any, N generic.Ordered\](m M, getter func (v V) N, f func (i int, key K, val V) bool) + +> 按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByValueGetterAsc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByValueGetterAsc(m, func(v int) int { + return v + }, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByValueGetterAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{{"TestLoopMapByValueGetterAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2"}, 2}, {"TestLoopMapByValueGetterAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2", "3"}, 0}, {"TestLoopMapByValueGetterAsc_Empty", map[int]string{}, []string{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByValueGetterAsc(c.in, func(val string) string { + return val + }, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByValueGetterAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByKeyGetterDesc\[M ~map[K]V, K comparable, V comparable, N generic.Ordered\](m M, getter func (k K) N, f func (i int, key K, val V) bool) + +> 按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByKeyGetterDesc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByKeyGetterDesc(m, func(k string) int { + return m[k] + }, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByKeyGetterDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{{"TestLoopMapByKeyGetterDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2}, 2}, {"TestLoopMapByKeyGetterDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2, 1}, 0}, {"TestLoopMapByKeyGetterDesc_Empty", map[int]string{}, []int{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByKeyGetterDesc(c.in, func(key int) int { + return key + }, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByKeyGetterDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func LoopMapByValueGetterDesc\[M ~map[K]V, K comparable, V any, N generic.Ordered\](m M, getter func (v V) N, f func (i int, key K, val V) bool) + +> 按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +> - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +> - 迭代过程将在 f 函数返回 false 时中断 + +**示例代码：** + +```go + +func ExampleLoopMapByValueGetterDesc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByValueGetterDesc(m, func(v int) int { + return v + }, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestLoopMapByValueGetterDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{{"TestLoopMapByValueGetterDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2"}, 2}, {"TestLoopMapByValueGetterDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2", "1"}, 0}, {"TestLoopMapByValueGetterDesc_Empty", map[int]string{}, []string{}, 0}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByValueGetterDesc(c.in, func(val string) string { + return val + }, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByValueGetterDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +``` + + +
+ + +*** +#### func MappingFromSlice\[S ~[]V, NS []N, V any, N any\](slice S, handler func (value V) N) NS > 将切片中的元素进行转换 -示例代码： +**示例代码：** + ```go func ExampleMappingFromSlice() { @@ -4210,11 +5369,12 @@ func TestMappingFromSlice(t *testing.T) { *** -#### func MappingFromMap(m M, handler func (value V) N) NM +#### func MappingFromMap\[M ~map[K]V, NM map[K]N, K comparable, V any, N any\](m M, handler func (value V) N) NM > 将 map 中的元素进行转换 -示例代码： +**示例代码：** + ```go func ExampleMappingFromMap() { @@ -4262,11 +5422,12 @@ func TestMappingFromMap(t *testing.T) { *** -#### func MergeSlices(slices ...S) (result S) +#### func MergeSlices\[S ~[]V, V any\](slices ...S) (result S) > 合并切片 -示例代码： +**示例代码：** + ```go func ExampleMergeSlices() { @@ -4309,11 +5470,12 @@ func TestMergeSlices(t *testing.T) { *** -#### func MergeMaps(maps ...M) (result M) +#### func MergeMaps\[M ~map[K]V, K comparable, V any\](maps ...M) (result M) > 合并 map，当多个 map 中存在相同的 key 时，后面的 map 中的 key 将会覆盖前面的 map 中的 key -示例代码： +**示例代码：** + ```go func ExampleMergeMaps() { @@ -4352,11 +5514,12 @@ func TestMergeMaps(t *testing.T) { *** -#### func MergeMapsWithSkip(maps ...M) (result M) +#### func MergeMapsWithSkip\[M ~map[K]V, K comparable, V any\](maps ...M) (result M) > 合并 map，当多个 map 中存在相同的 key 时，后面的 map 中的 key 将会被跳过 -示例代码： +**示例代码：** + ```go func ExampleMergeMapsWithSkip() { @@ -4395,12 +5558,13 @@ func TestMergeMapsWithSkip(t *testing.T) { *** -#### func ChooseRandomSliceElementRepeatN(slice S, n int) (result []V) +#### func ChooseRandomSliceElementRepeatN\[S ~[]V, V any\](slice S, n int) (result []V) > 返回 slice 中的 n 个可重复随机元素 > - 当 slice 长度为 0 或 n 小于等于 0 时将会返回 nil -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElementRepeatN() { @@ -4439,12 +5603,13 @@ func TestChooseRandomSliceElementRepeatN(t *testing.T) { *** -#### func ChooseRandomIndexRepeatN(slice S, n int) (result []int) +#### func ChooseRandomIndexRepeatN\[S ~[]V, V any\](slice S, n int) (result []int) > 返回 slice 中的 n 个可重复随机元素的索引 > - 当 slice 长度为 0 或 n 小于等于 0 时将会返回 nil -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndexRepeatN() { @@ -4483,11 +5648,12 @@ func TestChooseRandomIndexRepeatN(t *testing.T) { *** -#### func ChooseRandomSliceElement(slice S) (v V) +#### func ChooseRandomSliceElement\[S ~[]V, V any\](slice S) (v V) > 返回 slice 中随机一个元素，当 slice 长度为 0 时将会得到 V 的零值 -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElement() { @@ -4526,11 +5692,12 @@ func TestChooseRandomSliceElement(t *testing.T) { *** -#### func ChooseRandomIndex(slice S) (index int) +#### func ChooseRandomIndex\[S ~[]V, V any\](slice S) (index int) > 返回 slice 中随机一个元素的索引，当 slice 长度为 0 时将会得到 -1 -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndex() { @@ -4569,12 +5736,13 @@ func TestChooseRandomIndex(t *testing.T) { *** -#### func ChooseRandomSliceElementN(slice S, n int) (result []V) +#### func ChooseRandomSliceElementN\[S ~[]V, V any\](slice S, n int) (result []V) > 返回 slice 中的 n 个不可重复的随机元素 > - 当 slice 长度为 0 或 n 大于 slice 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomSliceElementN() { @@ -4612,12 +5780,13 @@ func TestChooseRandomSliceElementN(t *testing.T) { *** -#### func ChooseRandomIndexN(slice S, n int) (result []int) +#### func ChooseRandomIndexN\[S ~[]V, V any\](slice S, n int) (result []int) > 获取切片中的 n 个随机元素的索引 > - 如果 n 大于切片长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomIndexN() { @@ -4656,12 +5825,13 @@ func TestChooseRandomIndexN(t *testing.T) { *** -#### func ChooseRandomMapKeyRepeatN(m M, n int) (result []K) +#### func ChooseRandomMapKeyRepeatN\[M ~map[K]V, K comparable, V any\](m M, n int) (result []K) > 获取 map 中的 n 个随机 key，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyRepeatN() { @@ -4700,12 +5870,13 @@ func TestChooseRandomMapKeyRepeatN(t *testing.T) { *** -#### func ChooseRandomMapValueRepeatN(m M, n int) (result []V) +#### func ChooseRandomMapValueRepeatN\[M ~map[K]V, K comparable, V any\](m M, n int) (result []V) > 获取 map 中的 n 个随机 n，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValueRepeatN() { @@ -4744,12 +5915,13 @@ func TestChooseRandomMapValueRepeatN(t *testing.T) { *** -#### func ChooseRandomMapKeyAndValueRepeatN(m M, n int) M +#### func ChooseRandomMapKeyAndValueRepeatN\[M ~map[K]V, K comparable, V any\](m M, n int) M > 获取 map 中的 n 个随机 key 和 v，允许重复 > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValueRepeatN() { @@ -4788,11 +5960,12 @@ func TestChooseRandomMapKeyAndValueRepeatN(t *testing.T) { *** -#### func ChooseRandomMapKey(m M) (k K) +#### func ChooseRandomMapKey\[M ~map[K]V, K comparable, V any\](m M) (k K) > 获取 map 中的随机 key -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKey() { @@ -4831,11 +6004,12 @@ func TestChooseRandomMapKey(t *testing.T) { *** -#### func ChooseRandomMapValue(m M) (v V) +#### func ChooseRandomMapValue\[M ~map[K]V, K comparable, V any\](m M) (v V) > 获取 map 中的随机 value -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValue() { @@ -4874,12 +6048,13 @@ func TestChooseRandomMapValue(t *testing.T) { *** -#### func ChooseRandomMapKeyN(m M, n int) (result []K) +#### func ChooseRandomMapKeyN\[M ~map[K]V, K comparable, V any\](m M, n int) (result []K) > 获取 map 中的 inputN 个随机 key > - 如果 inputN 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyN() { @@ -4890,12 +6065,13 @@ func ExampleChooseRandomMapKeyN() { ``` *** -#### func ChooseRandomMapValueN(m M, n int) (result []V) +#### func ChooseRandomMapValueN\[M ~map[K]V, K comparable, V any\](m M, n int) (result []V) > 获取 map 中的 n 个随机 value > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapValueN() { @@ -4934,11 +6110,12 @@ func TestChooseRandomMapValueN(t *testing.T) { *** -#### func ChooseRandomMapKeyAndValue(m M) (k K, v V) +#### func ChooseRandomMapKeyAndValue\[M ~map[K]V, K comparable, V any\](m M) (k K, v V) > 获取 map 中的随机 key 和 v -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValue() { @@ -4977,12 +6154,13 @@ func TestChooseRandomMapKeyAndValue(t *testing.T) { *** -#### func ChooseRandomMapKeyAndValueN(m M, n int) M +#### func ChooseRandomMapKeyAndValueN\[M ~map[K]V, K comparable, V any\](m M, n int) M > 获取 map 中的 inputN 个随机 key 和 v > - 如果 n 大于 map 长度或小于 0 时将会发生 panic -示例代码： +**示例代码：** + ```go func ExampleChooseRandomMapKeyAndValueN() { @@ -5023,11 +6201,12 @@ func TestChooseRandomMapKeyAndValueN(t *testing.T) { *** -#### func DescBy(a Sort, b Sort) bool +#### func DescBy\[Sort generic.Ordered\](a Sort, b Sort) bool > 返回降序比较结果 -示例代码： +**示例代码：** + ```go func ExampleDescBy() { @@ -5073,11 +6252,12 @@ func TestDescBy(t *testing.T) { *** -#### func AscBy(a Sort, b Sort) bool +#### func AscBy\[Sort generic.Ordered\](a Sort, b Sort) bool > 返回升序比较结果 -示例代码： +**示例代码：** + ```go func ExampleAscBy() { @@ -5123,11 +6303,12 @@ func TestAscBy(t *testing.T) { *** -#### func Desc(slice *S, getter func (index int) Sort) +#### func Desc\[S ~[]V, V any, Sort generic.Ordered\](slice *S, getter func (index int) Sort) > 对切片进行降序排序 -示例代码： +**示例代码：** + ```go func ExampleDesc() { @@ -5173,11 +6354,12 @@ func TestDesc(t *testing.T) { *** -#### func DescByClone(slice S, getter func (index int) Sort) S +#### func DescByClone\[S ~[]V, V any, Sort generic.Ordered\](slice S, getter func (index int) Sort) S > 对切片进行降序排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleDescByClone() { @@ -5223,11 +6405,12 @@ func TestDescByClone(t *testing.T) { *** -#### func Asc(slice *S, getter func (index int) Sort) +#### func Asc\[S ~[]V, V any, Sort generic.Ordered\](slice *S, getter func (index int) Sort) > 对切片进行升序排序 -示例代码： +**示例代码：** + ```go func ExampleAsc() { @@ -5273,11 +6456,12 @@ func TestAsc(t *testing.T) { *** -#### func AscByClone(slice S, getter func (index int) Sort) S +#### func AscByClone\[S ~[]V, V any, Sort generic.Ordered\](slice S, getter func (index int) Sort) S > 对切片进行升序排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleAscByClone() { @@ -5323,11 +6507,12 @@ func TestAscByClone(t *testing.T) { *** -#### func Shuffle(slice *S) +#### func Shuffle\[S ~[]V, V any\](slice *S) > 对切片进行随机排序 -示例代码： +**示例代码：** + ```go func ExampleShuffle() { @@ -5367,11 +6552,12 @@ func TestShuffle(t *testing.T) { *** -#### func ShuffleByClone(slice S) S +#### func ShuffleByClone\[S ~[]V, V any\](slice S) S > 对切片进行随机排序，返回排序后的切片 -示例代码： +**示例代码：** + ```go func ExampleShuffleByClone() { @@ -5411,13 +6597,16 @@ func TestShuffleByClone(t *testing.T) { *** + ### ComparisonHandler `STRUCT` - +用于比较 `source` 和 `target` 两个值是否相同的比较函数 + - 该函数接受两个参数，分别是源值和目标值，返回 true 的情况下即表示两者相同 ```go type ComparisonHandler[V any] func(source V) bool ``` + ### OrderedValueGetter `STRUCT` - +用于获取 v 的可排序字段值的函数 ```go type OrderedValueGetter[V any, N generic.Ordered] func(v V) N ``` diff --git a/utils/collection/clone.go b/utils/collection/clone.go index 69a7c0d..6f1e0ed 100644 --- a/utils/collection/clone.go +++ b/utils/collection/clone.go @@ -4,12 +4,13 @@ import ( "slices" ) -// CloneSlice 克隆切片，该函数是 slices.Clone 的快捷方式 +// CloneSlice 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片 func CloneSlice[S ~[]V, V any](slice S) S { return slices.Clone(slice) } -// CloneMap 克隆 map +// CloneMap 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map +// - 当 m 为空时，将会返回 nil func CloneMap[M ~map[K]V, K comparable, V any](m M) M { if m == nil { return nil @@ -22,7 +23,8 @@ func CloneMap[M ~map[K]V, K comparable, V any](m M) M { return result } -// CloneSliceN 克隆 slice 为 n 个切片进行返回 +// CloneSliceN 通过创建一个新切片并将 slice 的元素复制到新切片的方式来克隆切片为 n 个切片 +// - 当 slice 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 func CloneSliceN[S ~[]V, V any](slice S, n int) []S { if slice == nil { return nil @@ -38,7 +40,8 @@ func CloneSliceN[S ~[]V, V any](slice S, n int) []S { return result } -// CloneMapN 克隆 map 为 n 个 map 进行返回 +// CloneMapN 通过创建一个新 map 并将 m 的元素复制到新 map 的方式来克隆 map 为 n 个 map +// - 当 m 为空时，将会返回 nil，当 n <= 0 时，将会返回零值切片 func CloneMapN[M ~map[K]V, K comparable, V any](m M, n int) []M { if m == nil { return nil @@ -55,7 +58,9 @@ func CloneMapN[M ~map[K]V, K comparable, V any](m M, n int) []M { return result } -// CloneSlices 克隆多个切片 +// CloneSlices 对 slices 中的每一项元素进行克隆，最终返回一个新的二维切片 +// - 当 slices 为空时，将会返回 nil +// - 该函数相当于使用 CloneSlice 函数一次性对多个切片进行克隆 func CloneSlices[S ~[]V, V any](slices ...S) []S { if slices == nil { return nil @@ -68,7 +73,9 @@ func CloneSlices[S ~[]V, V any](slices ...S) []S { return result } -// CloneMaps 克隆多个 map +// CloneMaps 对 maps 中的每一项元素进行克隆，最终返回一个新的 map 切片 +// - 当 maps 为空时，将会返回 nil +// - 该函数相当于使用 CloneMap 函数一次性对多个 map 进行克隆 func CloneMaps[M ~map[K]V, K comparable, V any](maps ...M) []M { if maps == nil { return nil diff --git a/utils/collection/clone_example_test.go b/utils/collection/clone_example_test.go index e5e00ed..7fe9b83 100644 --- a/utils/collection/clone_example_test.go +++ b/utils/collection/clone_example_test.go @@ -5,6 +5,8 @@ import ( "github.com/kercylan98/minotaur/utils/collection" ) +// 在该示例中，将 slice 克隆后将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 +// - 示例中的结果将会输出 [1 2 3] func ExampleCloneSlice() { var slice = []int{1, 2, 3} var result = collection.CloneSlice(slice) @@ -13,6 +15,8 @@ func ExampleCloneSlice() { // [1 2 3] } +// 在该示例中，将 map 克隆后将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 +// - 示例中的结果将会输出 3 func ExampleCloneMap() { var m = map[int]int{1: 1, 2: 2, 3: 3} var result = collection.CloneMap(m) @@ -21,6 +25,9 @@ func ExampleCloneMap() { // 3 } +// 通过将 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 +// - result 的结果为 [[1 2 3] [1 2 3]] +// - 示例中的结果将会输出 2 func ExampleCloneSliceN() { var slice = []int{1, 2, 3} var result = collection.CloneSliceN(slice, 2) @@ -29,6 +36,9 @@ func ExampleCloneSliceN() { // 2 } +// 通过将 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 +// - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对` +// - 示例中的结果将会输出 2 func ExampleCloneMapN() { var m = map[int]int{1: 1, 2: 2, 3: 3} var result = collection.CloneMapN(m, 2) @@ -37,6 +47,8 @@ func ExampleCloneMapN() { // 2 } +// 通过将多个 slice 克隆为 2 个新的 slice，将会得到一个新的 slice result，而 result 和 slice 将不会有任何关联，但是如果 slice 中的元素是引用类型，那么 result 中的元素将会和 slice 中的元素指向同一个地址 +// - result 的结果为 [[1 2 3] [1 2 3]] func ExampleCloneSlices() { var slice1 = []int{1, 2, 3} var slice2 = []int{1, 2, 3} @@ -46,6 +58,8 @@ func ExampleCloneSlices() { // 2 } +// 通过将多个 map 克隆为 2 个新的 map，将会得到一个新的 map result，而 result 和 map 将不会有任何关联，但是如果 map 中的元素是引用类型，那么 result 中的元素将会和 map 中的元素指向同一个地址 +// - result 的结果为 [map[1:1 2:2 3:3] map[1:1 2:2 3:3]] `无序的 Key-Value 对` func ExampleCloneMaps() { var m1 = map[int]int{1: 1, 2: 2, 3: 3} var m2 = map[int]int{1: 1, 2: 2, 3: 3} diff --git a/utils/collection/collection.go b/utils/collection/collection.go index 69ec6ed..519b27d 100644 --- a/utils/collection/collection.go +++ b/utils/collection/collection.go @@ -2,5 +2,9 @@ package collection import "github.com/kercylan98/minotaur/utils/generic" +// ComparisonHandler 用于比较 `source` 和 `target` 两个值是否相同的比较函数 +// - 该函数接受两个参数，分别是源值和目标值，返回 true 的情况下即表示两者相同 type ComparisonHandler[V any] func(source, target V) bool + +// OrderedValueGetter 用于获取 v 的可排序字段值的函数 type OrderedValueGetter[V any, N generic.Ordered] func(v V) N diff --git a/utils/collection/contains.go b/utils/collection/contains.go index 7613122..dda4939 100644 --- a/utils/collection/contains.go +++ b/utils/collection/contains.go @@ -1,5 +1,61 @@ package collection +// EqualSlice 检查两个切片是否相等，当 handler 返回 true 时，表示 slice1 中的某个元素和 slice2 中的某个元素相匹配 +// - 当两个切片的容量不同时，不会影响最终的比较结果 +func EqualSlice[S ~[]V, V any](slice1 S, slice2 S, handler ComparisonHandler[V]) bool { + if len(slice1) != len(slice2) { + return false + } + for i, v1 := range slice1 { + if !handler(v1, slice2[i]) { + return false + } + } + return true +} + +// EqualComparableSlice 检查两个切片的值是否相同 +// - 当两个切片的容量不同时，不会影响最终的比较结果 +func EqualComparableSlice[S ~[]V, V comparable](slice1 S, slice2 S) bool { + if len(slice1) != len(slice2) { + return false + } + for i, v1 := range slice1 { + if v1 != slice2[i] { + return false + } + } + return true +} + +// EqualMap 检查两个 map 是否相等，当 handler 返回 true 时，表示 map1 中的某个元素和 map2 中的某个元素相匹配 +// - 当两个 map 的容量不同时，不会影响最终的比较结果 +func EqualMap[M ~map[K]V, K comparable, V any](map1 M, map2 M, handler ComparisonHandler[V]) bool { + if len(map1) != len(map2) { + return false + } + for k, v1 := range map1 { + if !handler(v1, map2[k]) { + return false + } + } + return true +} + +// EqualComparableMap 检查两个 map 的值是否相同 +// - 当两个 map 的容量不同时，不会影响最终的比较结果 +func EqualComparableMap[M ~map[K]V, K comparable, V comparable](map1 M, map2 M) bool { + if len(map1) != len(map2) { + return false + } + for k, v1 := range map1 { + if v1 != map2[k] { + return false + } + } + return true +} + // InSlice 检查 v 是否被包含在 slice 中，当 handler 返回 true 时，表示 v 和 slice 中的某个元素相匹配 func InSlice[S ~[]V, V any](slice S, v V, handler ComparisonHandler[V]) bool { if len(slice) == 0 { diff --git a/utils/collection/contains_example_test.go b/utils/collection/contains_example_test.go index 3b96d36..033f0fe 100644 --- a/utils/collection/contains_example_test.go +++ b/utils/collection/contains_example_test.go @@ -5,6 +5,58 @@ import ( "github.com/kercylan98/minotaur/utils/collection" ) +func ExampleEqualSlice() { + s1 := []int{1, 2, 3} + s2 := []int{1} + s3 := []int{1, 2, 3} + fmt.Println(collection.EqualSlice(s1, s2, func(source, target int) bool { + return source == target + })) + fmt.Println(collection.EqualSlice(s1, s3, func(source, target int) bool { + return source == target + })) + // Output: + // false + // true +} + +func ExampleEqualComparableSlice() { + s1 := []int{1, 2, 3} + s2 := []int{1} + s3 := []int{1, 2, 3} + fmt.Println(collection.EqualComparableSlice(s1, s2)) + fmt.Println(collection.EqualComparableSlice(s1, s3)) + // Output: + // false + // true +} + +func ExampleEqualMap() { + m1 := map[string]int{"a": 1, "b": 2} + m2 := map[string]int{"a": 1} + m3 := map[string]int{"a": 1, "b": 2} + fmt.Println(collection.EqualMap(m1, m2, func(source, target int) bool { + return source == target + })) + fmt.Println(collection.EqualMap(m1, m3, func(source, target int) bool { + return source == target + })) + // Output: + // false + // true +} + +func ExampleEqualComparableMap() { + m1 := map[string]int{"a": 1, "b": 2} + m2 := map[string]int{"a": 1} + m3 := map[string]int{"a": 1, "b": 2} + fmt.Println(collection.EqualComparableMap(m1, m2)) + fmt.Println(collection.EqualComparableMap(m1, m3)) + // Output: + // false + // true +} + func ExampleInSlice() { result := collection.InSlice([]int{1, 2, 3}, 2, func(source, target int) bool { return source == target diff --git a/utils/collection/contains_test.go b/utils/collection/contains_test.go index 2c339c3..f9f1b32 100644 --- a/utils/collection/contains_test.go +++ b/utils/collection/contains_test.go @@ -9,6 +9,106 @@ var intComparisonHandler = func(source, target int) bool { return source == target } +func TestEqualSlice(t *testing.T) { + var cases = []struct { + name string + input []int + inputV []int + expected bool + }{ + {"TestEqualSlice_NonEmptySliceEqual", []int{1, 2, 3}, []int{1, 2, 3}, true}, + {"TestEqualSlice_NonEmptySliceNotEqual", []int{1, 2, 3}, []int{1, 2}, false}, + {"TestEqualSlice_EmptySlice", []int{}, []int{}, true}, + {"TestEqualSlice_NilSlice", nil, nil, true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualSlice(c.input, c.inputV, func(source, target int) bool { + return source == target + }) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", + c.name, c.expected, actual, "not as expected") + } + }) + } +} + +func TestEqualComparableSlice(t *testing.T) { + var cases = []struct { + name string + input []int + inputV []int + expected bool + }{ + {"TestEqualComparableSlice_NonEmptySliceEqual", []int{1, 2, 3}, []int{1, 2, 3}, true}, + {"TestEqualComparableSlice_NonEmptySliceNotEqual", []int{1, 2, 3}, []int{1, 2}, false}, + {"TestEqualComparableSlice_EmptySlice", []int{}, []int{}, true}, + {"TestEqualComparableSlice_NilSlice", nil, nil, true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualComparableSlice(c.input, c.inputV) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", + c.name, c.expected, actual, "not as expected") + } + }) + } +} + +func TestEqualMap(t *testing.T) { + var cases = []struct { + name string + input map[int]int + inputV map[int]int + expected bool + }{ + {"TestEqualMap_NonEmptyMapEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1, 2: 2}, true}, + {"TestEqualMap_NonEmptyMapNotEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1}, false}, + {"TestEqualMap_EmptyMap", map[int]int{}, map[int]int{}, true}, + {"TestEqualMap_NilMap", nil, nil, true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualMap(c.input, c.inputV, func(source, target int) bool { + return source == target + }) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", + c.name, c.expected, actual, "not as expected") + } + }) + } +} + +func TestEqualComparableMap(t *testing.T) { + var cases = []struct { + name string + input map[int]int + inputV map[int]int + expected bool + }{ + {"TestEqualComparableMap_NonEmptyMapEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1, 2: 2}, true}, + {"TestEqualComparableMap_NonEmptyMapNotEqual", map[int]int{1: 1, 2: 2}, map[int]int{1: 1}, false}, + {"TestEqualComparableMap_EmptyMap", map[int]int{}, map[int]int{}, true}, + {"TestEqualComparableMap_NilMap", nil, nil, true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var actual = collection.EqualComparableMap(c.input, c.inputV) + if actual != c.expected { + t.Fatalf("%s failed, expected: %v, actual: %v, error: %s", + c.name, c.expected, actual, "not as expected") + } + }) + } +} + func TestInSlice(t *testing.T) { var cases = []struct { name string diff --git a/utils/collection/convert.go b/utils/collection/convert.go index 63df650..e5e7f54 100644 --- a/utils/collection/convert.go +++ b/utils/collection/convert.go @@ -1,5 +1,55 @@ package collection +// ConvertSliceToBatches 将切片 s 转换为分批次的切片，当 batchSize 小于等于 0 或者 s 长度为 0 时，将会返回 nil +func ConvertSliceToBatches[S ~[]V, V any](s S, batchSize int) []S { + if len(s) == 0 || batchSize <= 0 { + return nil + } + var batches = make([]S, 0, len(s)/batchSize+1) + for i := 0; i < len(s); i += batchSize { + var end = i + batchSize + if end > len(s) { + end = len(s) + } + batches = append(batches, s[i:end]) + } + return batches +} + +// ConvertMapKeysToBatches 将映射的键转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil +func ConvertMapKeysToBatches[M ~map[K]V, K comparable, V any](m M, batchSize int) [][]K { + if len(m) == 0 || batchSize <= 0 { + return nil + } + var batches = make([][]K, 0, len(m)/batchSize+1) + var keys = ConvertMapKeysToSlice(m) + for i := 0; i < len(keys); i += batchSize { + var end = i + batchSize + if end > len(keys) { + end = len(keys) + } + batches = append(batches, keys[i:end]) + } + return batches +} + +// ConvertMapValuesToBatches 将映射的值转换为分批次的切片，当 batchSize 小于等于 0 或者 m 长度为 0 时，将会返回 nil +func ConvertMapValuesToBatches[M ~map[K]V, K comparable, V any](m M, batchSize int) [][]V { + if len(m) == 0 || batchSize <= 0 { + return nil + } + var batches = make([][]V, 0, len(m)/batchSize+1) + var values = ConvertMapValuesToSlice(m) + for i := 0; i < len(values); i += batchSize { + var end = i + batchSize + if end > len(values) { + end = len(values) + } + batches = append(batches, values[i:end]) + } + return batches +} + // ConvertSliceToAny 将切片转换为任意类型的切片 func ConvertSliceToAny[S ~[]V, V any](s S) []any { if len(s) == 0 { diff --git a/utils/collection/convert_example_test.go b/utils/collection/convert_example_test.go index 3658224..468e6ea 100644 --- a/utils/collection/convert_example_test.go +++ b/utils/collection/convert_example_test.go @@ -4,8 +4,33 @@ import ( "fmt" "github.com/kercylan98/minotaur/utils/collection" "reflect" + "sort" ) +func ExampleConvertSliceToBatches() { + result := collection.ConvertSliceToBatches([]int{1, 2, 3}, 2) + for _, v := range result { + fmt.Println(v) + } + // Output: + // [1 2] + // [3] +} + +func ExampleConvertMapKeysToBatches() { + result := collection.ConvertMapKeysToBatches(map[int]int{1: 1, 2: 2, 3: 3}, 2) + fmt.Println(len(result)) + // Output: + // 2 +} + +func ExampleConvertMapValuesToBatches() { + result := collection.ConvertMapValuesToBatches(map[int]int{1: 1, 2: 2, 3: 3}, 2) + fmt.Println(len(result)) + // Output: + // 2 +} + func ExampleConvertSliceToAny() { result := collection.ConvertSliceToAny([]int{1, 2, 3}) fmt.Println(reflect.TypeOf(result).String(), len(result)) @@ -60,6 +85,7 @@ func ExampleConvertSliceToBoolMap() { func ExampleConvertMapKeysToSlice() { result := collection.ConvertMapKeysToSlice(map[int]int{1: 1, 2: 2, 3: 3}) + sort.Ints(result) for i, v := range result { fmt.Println(i, v) } diff --git a/utils/collection/convert_test.go b/utils/collection/convert_test.go index 8b875eb..a117cc9 100644 --- a/utils/collection/convert_test.go +++ b/utils/collection/convert_test.go @@ -6,6 +6,90 @@ import ( "testing" ) +func TestConvertSliceToBatches(t *testing.T) { + var cases = []struct { + name string + input []int + batch int + expected [][]int + }{ + {name: "TestConvertSliceToBatches_NonEmpty", input: []int{1, 2, 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, + {name: "TestConvertSliceToBatches_Empty", input: []int{}, batch: 2, expected: nil}, + {name: "TestConvertSliceToBatches_Nil", input: nil, batch: 2, expected: nil}, + {name: "TestConvertSliceToBatches_NonPositive", input: []int{1, 2, 3}, batch: 0, expected: nil}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertSliceToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + for i := 0; i < len(actual); i++ { + av, ev := actual[i], c.expected[i] + if len(av) != len(ev) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + for j := 0; j < len(av); j++ { + aj, ej := av[j], ev[j] + if reflect.TypeOf(aj).Kind() != reflect.TypeOf(ej).Kind() { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + if aj != ej { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + } + } + }) + } +} + +func TestConvertMapKeysToBatches(t *testing.T) { + var cases = []struct { + name string + input map[int]int + batch int + expected [][]int + }{ + {name: "TestConvertMapKeysToBatches_NonEmpty", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, + {name: "TestConvertMapKeysToBatches_Empty", input: map[int]int{}, batch: 2, expected: nil}, + {name: "TestConvertMapKeysToBatches_Nil", input: nil, batch: 2, expected: nil}, + {name: "TestConvertMapKeysToBatches_NonPositive", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 0, expected: nil}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertMapKeysToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + }) + } +} + +func TestConvertMapValuesToBatches(t *testing.T) { + var cases = []struct { + name string + input map[int]int + batch int + expected [][]int + }{ + {name: "TestConvertMapValuesToBatches_NonEmpty", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 2, expected: [][]int{{1, 2}, {3}}}, + {name: "TestConvertMapValuesToBatches_Empty", input: map[int]int{}, batch: 2, expected: nil}, + {name: "TestConvertMapValuesToBatches_Nil", input: nil, batch: 2, expected: nil}, + {name: "TestConvertMapValuesToBatches_NonPositive", input: map[int]int{1: 1, 2: 2, 3: 3}, batch: 0, expected: nil}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + actual := collection.ConvertMapValuesToBatches(c.input, c.batch) + if len(actual) != len(c.expected) { + t.Errorf("expected: %v, actual: %v", c.expected, actual) + } + }) + } +} + func TestConvertSliceToAny(t *testing.T) { var cases = []struct { name string diff --git a/utils/collection/doc.go b/utils/collection/doc.go index 50528d9..195bdbb 100644 --- a/utils/collection/doc.go +++ b/utils/collection/doc.go @@ -1,2 +1,2 @@ -// Package collection 用于对 input 和 map 操作的工具函数 +// Package collection 定义了各种对于集合操作有用的各种函数 package collection diff --git a/utils/collection/listings/README.md b/utils/collection/listings/README.md index 57dd1d8..6ff9276 100644 --- a/utils/collection/listings/README.md +++ b/utils/collection/listings/README.md @@ -26,36 +26,37 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Matrix](#matrix)|暂无描述... -|`STRUCT`|[PagedSlice](#pagedslice)|是一个高效的动态数组，它通过分页管理内存并减少频繁的内存分配来提高性能。 -|`STRUCT`|[PrioritySlice](#priorityslice)|是一个优先级切片 -|`STRUCT`|[SyncSlice](#syncslice)|是基于 sync.RWMutex 实现的线程安全的 slice +|`STRUCT`|[Matrix](#struct_Matrix)|暂无描述... +|`STRUCT`|[PagedSlice](#struct_PagedSlice)|是一个高效的动态数组，它通过分页管理内存并减少频繁的内存分配来提高性能。 +|`STRUCT`|[PrioritySlice](#struct_PrioritySlice)|是一个优先级切片 +|`STRUCT`|[SyncSlice](#struct_SyncSlice)|是基于 sync.RWMutex 实现的线程安全的 slice
*** ## 详情信息 -#### func NewMatrix(dimensions ...int) *Matrix[V] +#### func NewMatrix\[V any\](dimensions ...int) *Matrix[V] > 创建一个新的 Matrix 实例。 *** -#### func NewPagedSlice(pageSize int) *PagedSlice[T] +#### func NewPagedSlice\[T any\](pageSize int) *PagedSlice[T] > 创建一个新的 PagedSlice 实例。 *** -#### func NewPrioritySlice(lengthAndCap ...int) *PrioritySlice[V] +#### func NewPrioritySlice\[V any\](lengthAndCap ...int) *PrioritySlice[V] > 创建一个优先级切片 *** -#### func NewSyncSlice(length int, cap int) *SyncSlice[V] +#### func NewSyncSlice\[V any\](length int, cap int) *SyncSlice[V] > 创建一个 SyncSlice *** + ### Matrix `STRUCT` ```go @@ -64,18 +65,31 @@ type Matrix[V any] struct { data []V } ``` + + #### func (*Matrix) Get(index ...int) *V > 获取矩阵中给定索引的元素。 + *** + + #### func (*Matrix) Set(index []int, value V) > 设置矩阵中给定索引的元素。 + *** + + #### func (*Matrix) Dimensions() []int > 返回矩阵的维度大小。 + *** + + #### func (*Matrix) Clear() > 清空矩阵。 + *** + ### PagedSlice `STRUCT` 是一个高效的动态数组，它通过分页管理内存并减少频繁的内存分配来提高性能。 ```go @@ -86,24 +100,43 @@ type PagedSlice[T any] struct { lenLast int } ``` + + #### func (*PagedSlice) Add(value T) > 添加一个元素到 PagedSlice 中。 + *** + + #### func (*PagedSlice) Get(index int) *T > 获取 PagedSlice 中给定索引的元素。 + *** + + #### func (*PagedSlice) Set(index int, value T) > 设置 PagedSlice 中给定索引的元素。 + *** + + #### func (*PagedSlice) Len() int > 返回 PagedSlice 中元素的数量。 + *** + + #### func (*PagedSlice) Clear() > 清空 PagedSlice。 + *** + + #### func (*PagedSlice) Range(f func (index int, value T) bool) > 迭代 PagedSlice 中的所有元素。 + *** + ### PrioritySlice `STRUCT` 是一个优先级切片 ```go @@ -111,17 +144,29 @@ type PrioritySlice[V any] struct { items []*priorityItem[V] } ``` + + #### func (*PrioritySlice) Len() int > 返回切片长度 + *** + + #### func (*PrioritySlice) Cap() int > 返回切片容量 + *** + + #### func (*PrioritySlice) Clear() > 清空切片 + *** + + #### func (*PrioritySlice) Append(v V, p int) > 添加元素 +
查看 / 收起单元测试 @@ -142,45 +187,85 @@ func TestPrioritySlice_Append(t *testing.T) { *** + + #### func (*PrioritySlice) Appends(priority int, vs ...V) > 添加元素 + *** -#### func (*PrioritySlice) Get(index int) V, int + + +#### func (*PrioritySlice) Get(index int) ( V, int) > 获取元素 + *** + + #### func (*PrioritySlice) GetValue(index int) V > 获取元素值 + *** + + #### func (*PrioritySlice) GetPriority(index int) int > 获取元素优先级 + *** + + #### func (*PrioritySlice) Set(index int, value V, priority int) > 设置元素 + *** + + #### func (*PrioritySlice) SetValue(index int, value V) > 设置元素值 + *** + + #### func (*PrioritySlice) SetPriority(index int, priority int) > 设置元素优先级 + *** + + #### func (*PrioritySlice) Action(action func (items []*priorityItem[V]) []*priorityItem[V]) > 直接操作切片，如果返回值不为 nil，则替换切片 + *** + + #### func (*PrioritySlice) Range(action func (index int, item *priorityItem[V]) bool) > 遍历切片，如果返回值为 false，则停止遍历 + *** + + #### func (*PrioritySlice) RangeValue(action func (index int, value V) bool) > 遍历切片值，如果返回值为 false，则停止遍历 + *** + + #### func (*PrioritySlice) RangePriority(action func (index int, priority int) bool) > 遍历切片优先级，如果返回值为 false，则停止遍历 + *** + + #### func (*PrioritySlice) Slice() []V -> 返回切片 +> SyncSlice 返回切片 + *** + + #### func (*PrioritySlice) String() string > 返回切片字符串 + *** + ### SyncSlice `STRUCT` 是基于 sync.RWMutex 实现的线程安全的 slice ```go @@ -189,17 +274,38 @@ type SyncSlice[V any] struct { data []V } ``` + + #### func (*SyncSlice) Get(index int) V + *** + + #### func (*SyncSlice) GetWithRange(start int, end int) []V + *** + + #### func (*SyncSlice) Set(index int, value V) + *** + + #### func (*SyncSlice) Append(values ...V) + *** + + #### func (*SyncSlice) Release() + *** + + #### func (*SyncSlice) Clear() + *** + + #### func (*SyncSlice) GetData() []V + *** diff --git a/utils/collection/loop.go b/utils/collection/loop.go new file mode 100644 index 0000000..9b3700c --- /dev/null +++ b/utils/collection/loop.go @@ -0,0 +1,188 @@ +package collection + +import ( + "github.com/kercylan98/minotaur/utils/generic" + "sort" +) + +// LoopSlice 迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopSlice[S ~[]V, V any](slice S, f func(i int, val V) bool) { + for i, v := range slice { + if !f(i, v) { + break + } + } +} + +// ReverseLoopSlice 逆序迭代切片 slice 中的每一个函数，并将索引和值传递给 f 函数 +// - 迭代过程将在 f 函数返回 false 时中断 +func ReverseLoopSlice[S ~[]V, V any](slice S, f func(i int, val V) bool) { + for i := len(slice) - 1; i >= 0; i-- { + if !f(i, slice[i]) { + break + } + } +} + +// LoopMap 迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - m 的迭代顺序是不确定的，因此每次迭代的顺序可能不同 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMap[M ~map[K]V, K comparable, V any](m M, f func(i int, key K, val V) bool) { + var i int + for k, v := range m { + if !f(i, k, v) { + break + } + i++ + } +} + +// LoopMapByOrderedKeyAsc 按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByOrderedKeyAsc[M ~map[K]V, K generic.Ordered, V any](m M, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return AscBy(keys[i], keys[j]) + }) + for i, k := range keys { + if !f(i, k, m[k]) { + break + } + } +} + +// LoopMapByOrderedKeyDesc 按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByOrderedKeyDesc[M ~map[K]V, K generic.Ordered, V any](m M, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return DescBy(keys[i], keys[j]) + }) + for i, k := range keys { + if !f(i, k, m[k]) { + break + } + } +} + +// LoopMapByOrderedValueAsc 按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByOrderedValueAsc[M ~map[K]V, K comparable, V generic.Ordered](m M, f func(i int, key K, val V) bool) { + var keys []K + var values []V + for k, v := range m { + keys = append(keys, k) + values = append(values, v) + } + sort.Slice(values, func(i, j int) bool { + return AscBy(values[i], values[j]) + }) + for i, v := range values { + if !f(i, keys[i], v) { + break + } + } +} + +// LoopMapByOrderedValueDesc 按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByOrderedValueDesc[M ~map[K]V, K comparable, V generic.Ordered](m M, f func(i int, key K, val V) bool) { + var keys []K + var values []V + for k, v := range m { + keys = append(keys, k) + values = append(values, v) + } + sort.Slice(values, func(i, j int) bool { + return DescBy(values[i], values[j]) + }) + for i, v := range values { + if !f(i, keys[i], v) { + break + } + } +} + +// LoopMapByKeyGetterAsc 按照键的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByKeyGetterAsc[M ~map[K]V, K comparable, V comparable, N generic.Ordered](m M, getter func(k K) N, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return AscBy(getter(keys[i]), getter(keys[j])) + }) + for i, v := range keys { + if !f(i, keys[i], m[v]) { + break + } + } +} + +// LoopMapByValueGetterAsc 按照值的升序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByValueGetterAsc[M ~map[K]V, K comparable, V any, N generic.Ordered](m M, getter func(v V) N, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return AscBy(getter(m[keys[i]]), getter(m[keys[j]])) + }) + for i, v := range keys { + if !f(i, keys[i], m[v]) { + break + } + } +} + +// LoopMapByKeyGetterDesc 按照键的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByKeyGetterDesc[M ~map[K]V, K comparable, V comparable, N generic.Ordered](m M, getter func(k K) N, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return DescBy(getter(keys[i]), getter(keys[j])) + }) + for i, v := range keys { + if !f(i, keys[i], m[v]) { + break + } + } +} + +// LoopMapByValueGetterDesc 按照值的降序迭代 m 中的每一个函数，并将键和值传递给 f 函数 +// - 该函数会在 f 中传入一个从 0 开始的索引，用于表示当前迭代的次数 +// - 迭代过程将在 f 函数返回 false 时中断 +func LoopMapByValueGetterDesc[M ~map[K]V, K comparable, V any, N generic.Ordered](m M, getter func(v V) N, f func(i int, key K, val V) bool) { + var keys []K + for k := range m { + keys = append(keys, k) + } + sort.Slice(keys, func(i, j int) bool { + return DescBy(getter(m[keys[i]]), getter(m[keys[j]])) + }) + for i, v := range keys { + if !f(i, keys[i], m[v]) { + break + } + } +} diff --git a/utils/collection/loop_example_test.go b/utils/collection/loop_example_test.go new file mode 100644 index 0000000..f725606 --- /dev/null +++ b/utils/collection/loop_example_test.go @@ -0,0 +1,159 @@ +package collection_test + +import ( + "fmt" + "github.com/kercylan98/minotaur/utils/collection" +) + +func ExampleLoopSlice() { + var result []int + collection.LoopSlice([]int{1, 2, 3, 4, 5}, func(i int, val int) bool { + result = append(result, val) + if uint(i) == 1 { + return false + } + return true + }) + fmt.Println(result) + // Output: [1 2] +} + +func ExampleReverseLoopSlice() { + var result []int + collection.ReverseLoopSlice([]int{1, 2, 3, 4, 5}, func(i int, val int) bool { + result = append(result, val) + if uint(i) == 1 { + return false + } + return true + }) + fmt.Println(result) + // Output: [5 4 3 2] +} + +func ExampleLoopMap() { + var result []int + collection.LoopMap(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) + // Output: + // true +} + +func ExampleLoopMapByOrderedKeyAsc() { + var result []int + collection.LoopMapByOrderedKeyAsc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) + // Output: + // true +} + +func ExampleLoopMapByOrderedKeyDesc() { + var result []int + collection.LoopMapByOrderedKeyDesc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) + // Output: + // true +} + +func ExampleLoopMapByOrderedValueAsc() { + var result []int + collection.LoopMapByOrderedValueAsc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) + // Output: + // true +} + +func ExampleLoopMapByOrderedValueDesc() { + var result []int + collection.LoopMapByOrderedValueDesc(map[string]int{"a": 1, "b": 2, "c": 3}, func(i int, key string, val int) bool { + result = append(result, val) + return true + }) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) + // Output: + // true +} + +func ExampleLoopMapByKeyGetterAsc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByKeyGetterAsc( + m, + func(k string) int { + return m[k] + }, + func(i int, key string, val int) bool { + result = append(result, val) + return true + }, + ) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) + // Output: + // true +} + +func ExampleLoopMapByKeyGetterDesc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByKeyGetterDesc( + m, + func(k string) int { + return m[k] + }, + func(i int, key string, val int) bool { + result = append(result, val) + return true + }, + ) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) + // Output: + // true +} + +func ExampleLoopMapByValueGetterAsc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByValueGetterAsc( + m, + func(v int) int { + return v + }, + func(i int, key string, val int) bool { + result = append(result, val) + return true + }, + ) + fmt.Println(collection.AllInComparableSlice(result, []int{1, 2, 3})) + // Output: + // true +} + +func ExampleLoopMapByValueGetterDesc() { + var m = map[string]int{"a": 1, "b": 2, "c": 3} + var result []int + collection.LoopMapByValueGetterDesc( + m, + func(v int) int { + return v + }, + func(i int, key string, val int) bool { + result = append(result, val) + return true + }, + ) + fmt.Println(collection.AllInComparableSlice(result, []int{3, 2, 1})) + // Output: + // true +} diff --git a/utils/collection/loop_test.go b/utils/collection/loop_test.go new file mode 100644 index 0000000..8c0c739 --- /dev/null +++ b/utils/collection/loop_test.go @@ -0,0 +1,333 @@ +package collection_test + +import ( + "github.com/kercylan98/minotaur/utils/collection" + "testing" +) + +func TestLoopSlice(t *testing.T) { + var cases = []struct { + name string + in []int + out []int + breakIndex uint + }{ + {"TestLoopSlice_Part", []int{1, 2, 3, 4, 5}, []int{1, 2}, 2}, + {"TestLoopSlice_All", []int{1, 2, 3, 4, 5}, []int{1, 2, 3, 4, 5}, 0}, + {"TestLoopSlice_Empty", []int{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopSlice(c.in, func(i int, val int) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopSlice(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestReverseLoopSlice(t *testing.T) { + var cases = []struct { + name string + in []int + out []int + breakIndex uint + }{ + {"TestReverseLoopSlice_Part", []int{1, 2, 3, 4, 5}, []int{5, 4}, 2}, + {"TestReverseLoopSlice_All", []int{1, 2, 3, 4, 5}, []int{5, 4, 3, 2, 1}, 0}, + {"TestReverseLoopSlice_Empty", []int{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.ReverseLoopSlice(c.in, func(i int, val int) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == uint(len(c.in))-c.breakIndex { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("ReverseLoopSlice(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMap(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out map[int]string + breakIndex uint + }{ + {"TestLoopMap_Part", map[int]string{1: "1", 2: "2", 3: "3"}, map[int]string{1: "1", 2: "2"}, 2}, + {"TestLoopMap_All", map[int]string{1: "1", 2: "2", 3: "3"}, map[int]string{1: "1", 2: "2", 3: "3"}, 0}, + {"TestLoopMap_Empty", map[int]string{}, map[int]string{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result = make(map[int]string) + collection.LoopMap(c.in, func(i int, key int, val string) bool { + result[key] = val + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableMap(result, c.out) { + t.Errorf("LoopMap(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByOrderedKeyAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{ + {"TestLoopMapByOrderedKeyAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2}, 2}, + {"TestLoopMapByOrderedKeyAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2, 3}, 0}, + {"TestLoopMapByOrderedKeyAsc_Empty", map[int]string{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByOrderedKeyAsc(c.in, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedKeyAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByOrderedKeyDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{ + {"TestLoopMapByOrderedKeyDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2}, 2}, + {"TestLoopMapByOrderedKeyDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2, 1}, 0}, + {"TestLoopMapByOrderedKeyDesc_Empty", map[int]string{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByOrderedKeyDesc(c.in, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedKeyDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByOrderedValueAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{ + {"TestLoopMapByOrderedValueAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2"}, 2}, + {"TestLoopMapByOrderedValueAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2", "3"}, 0}, + {"TestLoopMapByOrderedValueAsc_Empty", map[int]string{}, []string{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByOrderedValueAsc(c.in, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedValueAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByOrderedValueDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{ + {"TestLoopMapByOrderedValueDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2"}, 2}, + {"TestLoopMapByOrderedValueDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2", "1"}, 0}, + {"TestLoopMapByOrderedValueDesc_Empty", map[int]string{}, []string{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByOrderedValueDesc(c.in, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByOrderedValueDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByKeyGetterAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{ + {"TestLoopMapByKeyGetterAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2}, 2}, + {"TestLoopMapByKeyGetterAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{1, 2, 3}, 0}, + {"TestLoopMapByKeyGetterAsc_Empty", map[int]string{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByKeyGetterAsc(c.in, func(key int) int { + return key + }, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByKeyGetterAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByKeyGetterDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []int + breakIndex uint + }{ + {"TestLoopMapByKeyGetterDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2}, 2}, + {"TestLoopMapByKeyGetterDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []int{3, 2, 1}, 0}, + {"TestLoopMapByKeyGetterDesc_Empty", map[int]string{}, []int{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []int + collection.LoopMapByKeyGetterDesc(c.in, func(key int) int { + return key + }, func(i int, key int, val string) bool { + result = append(result, key) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByKeyGetterDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByValueGetterAsc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{ + {"TestLoopMapByValueGetterAsc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2"}, 2}, + {"TestLoopMapByValueGetterAsc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"1", "2", "3"}, 0}, + {"TestLoopMapByValueGetterAsc_Empty", map[int]string{}, []string{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByValueGetterAsc(c.in, func(val string) string { + return val + }, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByValueGetterAsc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} + +func TestLoopMapByValueGetterDesc(t *testing.T) { + var cases = []struct { + name string + in map[int]string + out []string + breakIndex uint + }{ + {"TestLoopMapByValueGetterDesc_Part", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2"}, 2}, + {"TestLoopMapByValueGetterDesc_All", map[int]string{1: "1", 2: "2", 3: "3"}, []string{"3", "2", "1"}, 0}, + {"TestLoopMapByValueGetterDesc_Empty", map[int]string{}, []string{}, 0}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var result []string + collection.LoopMapByValueGetterDesc(c.in, func(val string) string { + return val + }, func(i int, key int, val string) bool { + result = append(result, val) + if c.breakIndex != 0 && uint(i) == c.breakIndex-1 { + return false + } + return true + }) + if !collection.EqualComparableSlice(result, c.out) { + t.Errorf("LoopMapByValueGetterDesc(%v) got %v, want %v", c.in, result, c.out) + } + }) + } +} diff --git a/utils/collection/mappings/README.md b/utils/collection/mappings/README.md index 0fa7236..17546e1 100644 --- a/utils/collection/mappings/README.md +++ b/utils/collection/mappings/README.md @@ -23,18 +23,19 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[SyncMap](#syncmap)|是基于 sync.RWMutex 实现的线程安全的 map +|`STRUCT`|[SyncMap](#struct_SyncMap)|是基于 sync.RWMutex 实现的线程安全的 map
*** ## 详情信息 -#### func NewSyncMap(source ...map[K]V) *SyncMap[K, V] +#### func NewSyncMap\[K comparable, V any\](source ...map[K]V) *SyncMap[K, V] > 创建一个 SyncMap *** + ### SyncMap `STRUCT` 是基于 sync.RWMutex 实现的线程安全的 map - 适用于要考虑并发读写但是并发读写的频率不高的情况 @@ -45,3 +46,109 @@ type SyncMap[K comparable, V any] struct { atom bool } ``` + + +#### func (*SyncMap) Set(key K, value V) +> 设置一个值 + +*** + + +#### func (*SyncMap) Get(key K) V +> 获取一个值 + +*** + + +#### func (*SyncMap) Atom(handle func (m map[K]V)) +> 原子操作 + +*** + + +#### func (*SyncMap) Exist(key K) bool +> 判断是否存在 + +*** + + +#### func (*SyncMap) GetExist(key K) ( V, bool) +> 获取一个值并判断是否存在 + +*** + + +#### func (*SyncMap) Delete(key K) +> 删除一个值 + +*** + + +#### func (*SyncMap) DeleteGet(key K) V +> 删除一个值并返回 + +*** + + +#### func (*SyncMap) DeleteGetExist(key K) ( V, bool) +> 删除一个值并返回是否存在 + +*** + + +#### func (*SyncMap) DeleteExist(key K) bool +> 删除一个值并返回是否存在 + +*** + + +#### func (*SyncMap) Clear() +> 清空 + +*** + + +#### func (*SyncMap) ClearHandle(handle func (key K, value V)) +> 清空并处理 + +*** + + +#### func (*SyncMap) Range(handle func (key K, value V) bool) +> 遍历所有值，如果 handle 返回 true 则停止遍历 + +*** + + +#### func (*SyncMap) Keys() []K +> 获取所有的键 + +*** + + +#### func (*SyncMap) Slice() []V +> 获取所有的值 + +*** + + +#### func (*SyncMap) Map() map[K]V +> 转换为普通 map + +*** + + +#### func (*SyncMap) Size() int +> 获取数量 + +*** + + +#### func (*SyncMap) MarshalJSON() ( []byte, error) + +*** + + +#### func (*SyncMap) UnmarshalJSON(bytes []byte) error + +*** diff --git a/utils/combination/README.md b/utils/combination/README.md index 0efb527..ec27303 100644 --- a/utils/combination/README.md +++ b/utils/combination/README.md @@ -44,7 +44,7 @@ combination 包提供了一些实用的组合函数。 |[WithValidatorHandleContinuousNot](#WithValidatorHandleContinuousNot)|校验组合成员是否不连续 |[WithValidatorHandleGroupContinuous](#WithValidatorHandleGroupContinuous)|校验组合成员是否能够按类型分组并且连续 |[WithValidatorHandleGroupContinuousN](#WithValidatorHandleGroupContinuousN)|校验组合成员是否能够按分组为 n 组类型并且连续 -|[WithValidatorHandleNCarryM](#WithValidatorHandleNCarryM)| 校验组合成员是否匹配 N 携带相同的 M 的组合 +|[WithValidatorHandleNCarryM](#WithValidatorHandleNCarryM)|校验组合成员是否匹配 N 携带相同的 M 的组合 |[WithValidatorHandleNCarryIndependentM](#WithValidatorHandleNCarryIndependentM)|校验组合成员是否匹配 N 携带独立的 M 的组合 @@ -52,25 +52,25 @@ combination 包提供了一些实用的组合函数。 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Combination](#combination)|用于从多个匹配器内提取组合的数据结构 -|`STRUCT`|[Option](#option)|组合器选项 -|`INTERFACE`|[Item](#item)|暂无描述... -|`STRUCT`|[Matcher](#matcher)|用于从一组数据内提取组合的数据结构 -|`STRUCT`|[MatcherOption](#matcheroption)|匹配器选项 -|`STRUCT`|[Validator](#validator)|用于对组合进行验证的校验器 -|`STRUCT`|[ValidatorOption](#validatoroption)|暂无描述... +|`STRUCT`|[Combination](#struct_Combination)|用于从多个匹配器内提取组合的数据结构 +|`STRUCT`|[Option](#struct_Option)|组合器选项 +|`INTERFACE`|[Item](#struct_Item)|暂无描述... +|`STRUCT`|[Matcher](#struct_Matcher)|用于从一组数据内提取组合的数据结构 +|`STRUCT`|[MatcherOption](#struct_MatcherOption)|匹配器选项 +|`STRUCT`|[Validator](#struct_Validator)|用于对组合进行验证的校验器 +|`STRUCT`|[ValidatorOption](#struct_ValidatorOption)|暂无描述...
*** ## 详情信息 -#### func NewCombination(options ...Option[T]) *Combination[T] +#### func NewCombination\[T Item\](options ...Option[T]) *Combination[T] > 创建一个新的组合器 *** -#### func WithEvaluation(evaluate func (items []T) float64) Option[T] +#### func WithEvaluation\[T Item\](evaluate func (items []T) float64) Option[T] > 设置组合评估函数 > - 用于对组合进行评估，返回一个分值的评价函数 @@ -79,57 +79,57 @@ combination 包提供了一些实用的组合函数。 > - 默认的评估函数将返回一个随机数 *** -#### func NewMatcher(options ...MatcherOption[T]) *Matcher[T] +#### func NewMatcher\[T Item\](options ...MatcherOption[T]) *Matcher[T] > 创建一个新的匹配器 *** -#### func WithMatcherEvaluation(evaluate func (items []T) float64) MatcherOption[T] +#### func WithMatcherEvaluation\[T Item\](evaluate func (items []T) float64) MatcherOption[T] > 设置匹配器评估函数 > - 用于对组合进行评估，返回一个分值的评价函数 > - 通过该选项将覆盖匹配器的默认(WithEvaluation)评估函数 *** -#### func WithMatcherLeastLength(length int) MatcherOption[T] +#### func WithMatcherLeastLength\[T Item\](length int) MatcherOption[T] > 通过匹配最小长度的组合创建匹配器 > - length: 组合的长度，表示需要匹配的组合最小数量 *** -#### func WithMatcherLength(length int) MatcherOption[T] +#### func WithMatcherLength\[T Item\](length int) MatcherOption[T] > 通过匹配长度的组合创建匹配器 > - length: 组合的长度，表示需要匹配的组合数量 *** -#### func WithMatcherMostLength(length int) MatcherOption[T] +#### func WithMatcherMostLength\[T Item\](length int) MatcherOption[T] > 通过匹配最大长度的组合创建匹配器 > - length: 组合的长度，表示需要匹配的组合最大数量 *** -#### func WithMatcherIntervalLength(min int, max int) MatcherOption[T] +#### func WithMatcherIntervalLength\[T Item\](min int, max int) MatcherOption[T] > 通过匹配长度区间的组合创建匹配器 > - min: 组合的最小长度，表示需要匹配的组合最小数量 > - max: 组合的最大长度，表示需要匹配的组合最大数量 *** -#### func WithMatcherContinuity(getIndex func (item T) Index) MatcherOption[T] +#### func WithMatcherContinuity\[T Item, Index generic.Number\](getIndex func (item T) Index) MatcherOption[T] > 通过匹配连续的组合创建匹配器 > - index: 用于获取组合中元素的索引值，用于判断是否连续 *** -#### func WithMatcherSame(count int, getType func (item T) E) MatcherOption[T] +#### func WithMatcherSame\[T Item, E generic.Ordered\](count int, getType func (item T) E) MatcherOption[T] > 通过匹配相同的组合创建匹配器 > - count: 组合中相同元素的数量，当 count <= 0 时，表示相同元素的数量不限 > - getType: 用于获取组合中元素的类型，用于判断是否相同 *** -#### func WithMatcherNCarryM(n int, m int, getType func (item T) E) MatcherOption[T] +#### func WithMatcherNCarryM\[T Item, E generic.Ordered\](n int, m int, getType func (item T) E) MatcherOption[T] > 通过匹配 N 携带 M 的组合创建匹配器 > - n: 组合中元素的数量，表示需要匹配的组合数量，n 的类型需要全部相同 @@ -137,7 +137,7 @@ combination 包提供了一些实用的组合函数。 > - getType: 用于获取组合中元素的类型，用于判断是否相同 *** -#### func WithMatcherNCarryIndependentM(n int, m int, getType func (item T) E) MatcherOption[T] +#### func WithMatcherNCarryIndependentM\[T Item, E generic.Ordered\](n int, m int, getType func (item T) E) MatcherOption[T] > 通过匹配 N 携带独立 M 的组合创建匹配器 > - n: 组合中元素的数量，表示需要匹配的组合数量，n 的类型需要全部相同 @@ -145,95 +145,95 @@ combination 包提供了一些实用的组合函数。 > - getType: 用于获取组合中元素的类型，用于判断是否相同 *** -#### func NewValidator(options ...ValidatorOption[T]) *Validator[T] +#### func NewValidator\[T Item\](options ...ValidatorOption[T]) *Validator[T] > 创建一个新的校验器 *** -#### func WithValidatorHandle(handle func (items []T) bool) ValidatorOption[T] +#### func WithValidatorHandle\[T Item\](handle func (items []T) bool) ValidatorOption[T] > 通过特定的验证函数对组合进行验证 *** -#### func WithValidatorHandleLength(length int) ValidatorOption[T] +#### func WithValidatorHandleLength\[T Item\](length int) ValidatorOption[T] > 校验组合的长度是否符合要求 *** -#### func WithValidatorHandleLengthRange(min int, max int) ValidatorOption[T] +#### func WithValidatorHandleLengthRange\[T Item\](min int, max int) ValidatorOption[T] > 校验组合的长度是否在指定的范围内 *** -#### func WithValidatorHandleLengthMin(min int) ValidatorOption[T] +#### func WithValidatorHandleLengthMin\[T Item\](min int) ValidatorOption[T] > 校验组合的长度是否大于等于指定的最小值 *** -#### func WithValidatorHandleLengthMax(max int) ValidatorOption[T] +#### func WithValidatorHandleLengthMax\[T Item\](max int) ValidatorOption[T] > 校验组合的长度是否小于等于指定的最大值 *** -#### func WithValidatorHandleLengthNot(length int) ValidatorOption[T] +#### func WithValidatorHandleLengthNot\[T Item\](length int) ValidatorOption[T] > 校验组合的长度是否不等于指定的值 *** -#### func WithValidatorHandleTypeLength(length int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleTypeLength\[T Item, E generic.Ordered\](length int, getType func (item T) E) ValidatorOption[T] > 校验组合成员类型数量是否为指定的值 *** -#### func WithValidatorHandleTypeLengthRange(min int, max int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleTypeLengthRange\[T Item, E generic.Ordered\](min int, max int, getType func (item T) E) ValidatorOption[T] > 校验组合成员类型数量是否在指定的范围内 *** -#### func WithValidatorHandleTypeLengthMin(min int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleTypeLengthMin\[T Item, E generic.Ordered\](min int, getType func (item T) E) ValidatorOption[T] > 校验组合成员类型数量是否大于等于指定的最小值 *** -#### func WithValidatorHandleTypeLengthMax(max int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleTypeLengthMax\[T Item, E generic.Ordered\](max int, getType func (item T) E) ValidatorOption[T] > 校验组合成员类型数量是否小于等于指定的最大值 *** -#### func WithValidatorHandleTypeLengthNot(length int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleTypeLengthNot\[T Item, E generic.Ordered\](length int, getType func (item T) E) ValidatorOption[T] > 校验组合成员类型数量是否不等于指定的值 *** -#### func WithValidatorHandleContinuous(getIndex func (item T) Index) ValidatorOption[T] +#### func WithValidatorHandleContinuous\[T Item, Index generic.Integer\](getIndex func (item T) Index) ValidatorOption[T] > 校验组合成员是否连续 *** -#### func WithValidatorHandleContinuousNot(getIndex func (item T) Index) ValidatorOption[T] +#### func WithValidatorHandleContinuousNot\[T Item, Index generic.Integer\](getIndex func (item T) Index) ValidatorOption[T] > 校验组合成员是否不连续 *** -#### func WithValidatorHandleGroupContinuous(getType func (item T) E, getIndex func (item T) Index) ValidatorOption[T] +#### func WithValidatorHandleGroupContinuous\[T Item, E generic.Ordered, Index generic.Integer\](getType func (item T) E, getIndex func (item T) Index) ValidatorOption[T] > 校验组合成员是否能够按类型分组并且连续 *** -#### func WithValidatorHandleGroupContinuousN(n int, getType func (item T) E, getIndex func (item T) Index) ValidatorOption[T] +#### func WithValidatorHandleGroupContinuousN\[T Item, E generic.Ordered, Index generic.Integer\](n int, getType func (item T) E, getIndex func (item T) Index) ValidatorOption[T] > 校验组合成员是否能够按分组为 n 组类型并且连续 *** -#### func WithValidatorHandleNCarryM(n int, m int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleNCarryM\[T Item, E generic.Ordered\](n int, m int, getType func (item T) E) ValidatorOption[T] -> 校验组合成员是否匹配 N 携带相同的 M 的组合 +> 校验组合成员是否匹配 N 携带相同的 M 的组合 > - n: 组合中元素的数量，表示需要匹配的组合数量，n 的类型需要全部相同 > - m: 组合中元素的数量，表示需要匹配的组合数量，m 的类型需要全部相同 > - getType: 用于获取组合中元素的类型，用于判断是否相同 *** -#### func WithValidatorHandleNCarryIndependentM(n int, m int, getType func (item T) E) ValidatorOption[T] +#### func WithValidatorHandleNCarryIndependentM\[T Item, E generic.Ordered\](n int, m int, getType func (item T) E) ValidatorOption[T] > 校验组合成员是否匹配 N 携带独立的 M 的组合 > - n: 组合中元素的数量，表示需要匹配的组合数量，n 的类型需要全部相同 @@ -241,6 +241,7 @@ combination 包提供了一些实用的组合函数。 > - getType: 用于获取组合中元素的类型，用于判断是否相同 *** + ### Combination `STRUCT` 用于从多个匹配器内提取组合的数据结构 ```go @@ -250,23 +251,41 @@ type Combination[T Item] struct { priority []string } ``` + + #### func (*Combination) NewMatcher(name string, options ...MatcherOption[T]) *Combination[T] > 添加一个新的匹配器 + *** + + #### func (*Combination) AddMatcher(name string, matcher *Matcher[T]) *Combination[T] > 添加一个匹配器 + *** + + #### func (*Combination) RemoveMatcher(name string) *Combination[T] > 移除一个匹配器 + *** + + #### func (*Combination) Combinations(items []T) (result [][]T) > 从一组数据中提取所有符合匹配器规则的组合 + *** + + #### func (*Combination) CombinationsToName(items []T) (result map[string][][]T) > 从一组数据中提取所有符合匹配器规则的组合，并返回匹配器名称 + *** + + #### func (*Combination) Best(items []T) (name string, result []T) > 从一组数据中提取符合匹配器规则的最佳组合 +
查看 / 收起单元测试 @@ -301,19 +320,25 @@ func TestCombination_Best(t *testing.T) { *** + + #### func (*Combination) Worst(items []T) (name string, result []T) > 从一组数据中提取符合匹配器规则的最差组合 + *** + ### Option `STRUCT` 组合器选项 ```go type Option[T Item] func(*Combination[T]) ``` + ### Item `INTERFACE` ```go type Item interface{} ``` + ### Matcher `STRUCT` 用于从一组数据内提取组合的数据结构 ```go @@ -322,24 +347,38 @@ type Matcher[T Item] struct { filter []func(items []T) [][]T } ``` + + #### func (*Matcher) AddFilter(filter func (items []T) [][]T) > 添加一个筛选器 > - 筛选器用于对组合进行筛选，返回一个二维数组，每个数组内的元素都是一个组合 + *** + + #### func (*Matcher) Combinations(items []T) [][]T > 从一组数据中提取所有符合筛选器规则的组合 + *** + + #### func (*Matcher) Best(items []T) []T > 从一组数据中提取符筛选器规则的最佳组合 + *** + + #### func (*Matcher) Worst(items []T) []T > 从一组数据中提取符筛选器规则的最差组合 + *** + ### MatcherOption `STRUCT` 匹配器选项 ```go type MatcherOption[T Item] func(matcher *Matcher[T]) ``` + ### Validator `STRUCT` 用于对组合进行验证的校验器 ```go @@ -347,8 +386,11 @@ type Validator[T Item] struct { vh []func(items []T) bool } ``` + + #### func (*Validator) Validate(items []T) bool > 校验组合是否符合要求 +
查看 / 收起单元测试 @@ -382,6 +424,7 @@ func TestValidator_Validate(t *testing.T) { *** + ### ValidatorOption `STRUCT` ```go diff --git a/utils/compress/README.md b/utils/compress/README.md index d576d74..03f09b7 100644 --- a/utils/compress/README.md +++ b/utils/compress/README.md @@ -30,32 +30,32 @@ compress 提供了一些用于压缩和解压缩数据的函数。 *** ## 详情信息 -#### func GZipCompress(data []byte) bytes.Buffer, error +#### func GZipCompress(data []byte) (bytes.Buffer, error) > 对数据进行GZip压缩，返回bytes.Buffer和错误信息 *** -#### func GZipUnCompress(dataByte []byte) []byte, error +#### func GZipUnCompress(dataByte []byte) ([]byte, error) > 对已进行GZip压缩的数据进行解压缩，返回字节数组及错误信息 *** -#### func TARCompress(data []byte) bytes.Buffer, error +#### func TARCompress(data []byte) (bytes.Buffer, error) > 对数据进行TAR压缩，返回bytes.Buffer和错误信息 *** -#### func TARUnCompress(dataByte []byte) []byte, error +#### func TARUnCompress(dataByte []byte) ([]byte, error) > 对已进行TAR压缩的数据进行解压缩，返回字节数组及错误信息 *** -#### func ZIPCompress(data []byte) bytes.Buffer, error +#### func ZIPCompress(data []byte) (bytes.Buffer, error) > 对数据进行ZIP压缩，返回bytes.Buffer和错误信息 *** -#### func ZIPUnCompress(dataByte []byte) []byte, error +#### func ZIPUnCompress(dataByte []byte) ([]byte, error) > 对已进行ZIP压缩的数据进行解压缩，返回字节数组及错误信息 diff --git a/utils/crypto/README.md b/utils/crypto/README.md index 88f6719..4864232 100644 --- a/utils/crypto/README.md +++ b/utils/crypto/README.md @@ -34,52 +34,52 @@ *** ## 详情信息 -#### func EncryptBase64(data []byte) string +#### func EncryptBase64(data []byte) string > 对数据进行Base64编码 *** -#### func DecodedBase64(data string) []byte, error +#### func DecodedBase64(data string) ([]byte, error) > 对数据进行Base64解码 *** -#### func EncryptCRC32(str string) uint32 +#### func EncryptCRC32(str string) uint32 > 对字符串进行CRC加密并返回其结果。 *** -#### func DecodedCRC32(data []byte) uint32 +#### func DecodedCRC32(data []byte) uint32 > 对字节数组进行CRC加密并返回其结果。 *** -#### func EncryptMD5(str string) string +#### func EncryptMD5(str string) string > 对字符串进行MD5加密并返回其结果。 *** -#### func DecodedMD5(data []byte) string +#### func DecodedMD5(data []byte) string > 对字节数组进行MD5加密并返回其结果。 *** -#### func EncryptSHA1(str string) string +#### func EncryptSHA1(str string) string > 对字符串进行SHA1加密并返回其结果。 *** -#### func DecodedSHA1(data []byte) string +#### func DecodedSHA1(data []byte) string > 对字节数组进行SHA1加密并返回其结果。 *** -#### func EncryptSHA256(str string) string +#### func EncryptSHA256(str string) string > 对字符串进行SHA256加密并返回其结果。 *** -#### func DecodedSHA256(data []byte) string +#### func DecodedSHA256(data []byte) string > 对字节数组进行SHA256加密并返回其结果。 diff --git a/utils/deck/README.md b/utils/deck/README.md index f6f342d..b34c7f8 100644 --- a/utils/deck/README.md +++ b/utils/deck/README.md @@ -24,25 +24,26 @@ deck 包中的内容用于针对一堆内容的管理，适用但不限于牌堆 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Deck](#deck)|甲板，用于针对一堆 Group 进行管理的数据结构 -|`STRUCT`|[Group](#group)|甲板中的组，用于针对一堆内容进行管理的数据结构 -|`INTERFACE`|[Item](#item)|甲板成员 +|`STRUCT`|[Deck](#struct_Deck)|甲板，用于针对一堆 Group 进行管理的数据结构 +|`STRUCT`|[Group](#struct_Group)|甲板中的组，用于针对一堆内容进行管理的数据结构 +|`INTERFACE`|[Item](#struct_Item)|甲板成员
*** ## 详情信息 -#### func NewDeck() *Deck[I] +#### func NewDeck\[I Item\]() *Deck[I] > 创建一个新的甲板 *** -#### func NewGroup(guid int64, fillHandle func (guid int64) []I) *Group[I] +#### func NewGroup\[I Item\](guid int64, fillHandle func (guid int64) []I) *Group[I] > 创建一个新的组 *** + ### Deck `STRUCT` 甲板，用于针对一堆 Group 进行管理的数据结构 ```go @@ -51,27 +52,49 @@ type Deck[I Item] struct { sort []int64 } ``` + + #### func (*Deck) AddGroup(group *Group[I]) > 将一个组添加到甲板中 + *** + + #### func (*Deck) RemoveGroup(guid int64) > 移除甲板中的一个组 + *** + + #### func (*Deck) GetCount() int > 获取甲板中的组数量 + *** + + #### func (*Deck) GetGroups() map[int64]*Group[I] > 获取所有组 + *** + + #### func (*Deck) GetGroupsSlice() []*Group[I] > 获取所有组 + *** + + #### func (*Deck) GetNext(guid int64) *Group[I] > 获取特定组的下一个组 + *** + + #### func (*Deck) GetPrev(guid int64) *Group[I] > 获取特定组的上一个组 + *** + ### Group `STRUCT` 甲板中的组，用于针对一堆内容进行管理的数据结构 ```go @@ -81,51 +104,97 @@ type Group[I Item] struct { items []I } ``` + + #### func (*Group) GetGuid() int64 > 获取组的 guid + *** + + #### func (*Group) Fill() > 将该组的数据填充为 WithGroupFillHandle 中设置的内容 + *** + + #### func (*Group) Pop() (item I) > 从顶部获取一个内容 + *** + + #### func (*Group) PopN(n int) (items []I) > 从顶部获取指定数量的内容 + *** + + #### func (*Group) PressOut() (item I) > 从底部压出一个内容 + *** + + #### func (*Group) PressOutN(n int) (items []I) > 从底部压出指定数量的内容 + *** + + #### func (*Group) Push(item I) > 向顶部压入一个内容 + *** + + #### func (*Group) PushN(items []I) > 向顶部压入指定数量的内容 + *** + + #### func (*Group) Insert(item I) > 向底部插入一个内容 + *** + + #### func (*Group) InsertN(items []I) > 向底部插入指定数量的内容 + *** + + #### func (*Group) Pull(index int) (item I) > 从特定位置拔出一个内容 + *** + + #### func (*Group) Thrust(index int, item I) > 向特定位置插入一个内容 + *** + + #### func (*Group) IsFree() bool > 检查组是否为空 + *** + + #### func (*Group) GetCount() int > 获取组中剩余的内容数量 + *** + + #### func (*Group) GetItem(index int) I > 获取组中的指定内容 + *** + ### Item `INTERFACE` 甲板成员 ```go diff --git a/utils/file/README.md b/utils/file/README.md index aa2cf96..fc7e257 100644 --- a/utils/file/README.md +++ b/utils/file/README.md @@ -35,46 +35,46 @@ *** ## 详情信息 -#### func PathExist(path string) bool, error +#### func PathExist(path string) (bool, error) > 路径是否存在 *** -#### func IsDir(path string) bool, error +#### func IsDir(path string) (bool, error) > 路径是否是文件夹 *** -#### func WriterFile(filePath string, content []byte) error +#### func WriterFile(filePath string, content []byte) error > 向特定文件写入内容 *** -#### func ReadOnce(filePath string) []byte, error +#### func ReadOnce(filePath string) ([]byte, error) > 单次读取文件 > - 一次性对整个文件进行读取，小文件读取可以很方便的一次性将文件内容读取出来，而大文件读取会造成性能影响。 *** -#### func ReadBlockHook(filePath string, bufferSize int, hook func (data []byte)) error +#### func ReadBlockHook(filePath string, bufferSize int, hook func (data []byte)) error > 分块读取文件 > - 将filePath路径对应的文件数据并将读到的每一部分传入hook函数中，当过程中如果产生错误则会返回error。 > - 分块读取可以在读取速度和内存消耗之间有一个很好的平衡。 *** -#### func ReadLine(filePath string, hook func (line string)) error +#### func ReadLine(filePath string, hook func (line string)) error > 分行读取文件 > - 将filePath路径对应的文件数据并将读到的每一行传入hook函数中，当过程中如果产生错误则会返回error。 *** -#### func LineCount(filePath string) int +#### func LineCount(filePath string) int > 统计文件行数 *** -#### func Paths(dir string) []string +#### func Paths(dir string) []string > 获取指定目录下的所有文件路径 > - 包括了子目录下的文件 @@ -88,7 +88,7 @@ > - 可通过 start 参数指定开始读取的位置，如果不指定则从文件开头开始读取。 *** -#### func FindLineChunks(file *os.File, chunkSize int64) [][2]int64 +#### func FindLineChunks(file *os.File, chunkSize int64) [][2]int64 > 查找文件按照每行划分的分块，每个分块的大小将在 chunkSize 和分割后的分块距离行首及行尾的距离中范围内 > - 使用该函数得到的分块是完整的行，不会出现行被分割的情况 @@ -96,7 +96,7 @@ > - 返回值的成员是一个长度为 2 的数组，第一个元素是分块的起始位置，第二个元素是分块的结束位置 *** -#### func FindLineChunksByOffset(file *os.File, offset int64, chunkSize int64) [][2]int64 +#### func FindLineChunksByOffset(file *os.File, offset int64, chunkSize int64) [][2]int64 > 该函数与 FindLineChunks 类似，不同的是该函数可以指定 offset 从指定位置开始读取文件 diff --git a/utils/fsm/README.md b/utils/fsm/README.md index f19ad85..12625fb 100644 --- a/utils/fsm/README.md +++ b/utils/fsm/README.md @@ -28,47 +28,48 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[FSM](#fsm)|状态机 -|`STRUCT`|[Option](#option)|暂无描述... +|`STRUCT`|[FSM](#struct_FSM)|状态机 +|`STRUCT`|[Option](#struct_Option)|暂无描述...
*** ## 详情信息 -#### func NewFSM(data Data) *FSM[State, Data] +#### func NewFSM\[State comparable, Data any\](data Data) *FSM[State, Data] > 创建一个新的状态机 *** -#### func WithEnterBeforeEvent(fn func (state *FSM[State, Data])) Option[State, Data] +#### func WithEnterBeforeEvent\[State comparable, Data any\](fn func (state *FSM[State, Data])) Option[State, Data] > 设置状态进入前的回调 > - 在首次设置状态时，状态机本身的当前状态为零值状态 *** -#### func WithEnterAfterEvent(fn func (state *FSM[State, Data])) Option[State, Data] +#### func WithEnterAfterEvent\[State comparable, Data any\](fn func (state *FSM[State, Data])) Option[State, Data] > 设置状态进入后的回调 *** -#### func WithUpdateEvent(fn func (state *FSM[State, Data])) Option[State, Data] +#### func WithUpdateEvent\[State comparable, Data any\](fn func (state *FSM[State, Data])) Option[State, Data] > 设置状态内刷新的回调 *** -#### func WithExitBeforeEvent(fn func (state *FSM[State, Data])) Option[State, Data] +#### func WithExitBeforeEvent\[State comparable, Data any\](fn func (state *FSM[State, Data])) Option[State, Data] > 设置状态退出前的回调 > - 该阶段状态机的状态为退出前的状态，而非新的状态 *** -#### func WithExitAfterEvent(fn func (state *FSM[State, Data])) Option[State, Data] +#### func WithExitAfterEvent\[State comparable, Data any\](fn func (state *FSM[State, Data])) Option[State, Data] > 设置状态退出后的回调 > - 该阶段状态机的状态为新的状态，而非退出前的状态 *** + ### FSM `STRUCT` 状态机 ```go @@ -84,6 +85,61 @@ type FSM[State comparable, Data any] struct { exitAfterEventHandles map[State][]func(state *FSM[State, Data]) } ``` + + +#### func (*FSM) Update() +> 触发当前状态 + +*** + + +#### func (*FSM) Register(state State, options ...Option[State, Data]) +> 注册状态 + +*** + + +#### func (*FSM) Unregister(state State) +> 反注册状态 + +*** + + +#### func (*FSM) HasState(state State) bool +> 检查状态机是否存在特定状态 + +*** + + +#### func (*FSM) Change(state State) +> 改变状态机状态到新的状态 + +*** + + +#### func (*FSM) Current() (state State) +> 获取当前状态 + +*** + + +#### func (*FSM) GetData() Data +> 获取状态机数据 + +*** + + +#### func (*FSM) IsZero() bool +> 检查状态机是否无状态 + +*** + + +#### func (*FSM) PrevIsZero() bool +> 检查状态机上一个状态是否无状态 + +*** + ### Option `STRUCT` ```go diff --git a/utils/generator/astgo/README.md b/utils/generator/astgo/README.md index 282a53c..3433548 100644 --- a/utils/generator/astgo/README.md +++ b/utils/generator/astgo/README.md @@ -23,20 +23,20 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Comment](#comment)|暂无描述... -|`STRUCT`|[Field](#field)|暂无描述... -|`STRUCT`|[File](#file)|暂无描述... -|`STRUCT`|[Function](#function)|暂无描述... -|`STRUCT`|[Package](#package)|暂无描述... -|`STRUCT`|[Struct](#struct)|暂无描述... -|`STRUCT`|[Type](#type)|暂无描述... +|`STRUCT`|[Comment](#struct_Comment)|暂无描述... +|`STRUCT`|[Field](#struct_Field)|暂无描述... +|`STRUCT`|[File](#struct_File)|暂无描述... +|`STRUCT`|[Function](#struct_Function)|暂无描述... +|`STRUCT`|[Package](#struct_Package)|暂无描述... +|`STRUCT`|[Struct](#struct_Struct)|暂无描述... +|`STRUCT`|[Type](#struct_Type)|暂无描述...
*** ## 详情信息 -#### func NewPackage(dir string) *Package, error +#### func NewPackage(dir string) (*Package, error)
@@ -60,6 +60,7 @@ func TestNewPackage(t *testing.T) { *** + ### Comment `STRUCT` ```go @@ -68,6 +69,7 @@ type Comment struct { Clear []string } ``` + ### Field `STRUCT` ```go @@ -78,6 +80,7 @@ type Field struct { Comments *Comment } ``` + ### File `STRUCT` ```go @@ -90,8 +93,12 @@ type File struct { Comment *Comment } ``` + + #### func (*File) Package() string + *** + ### Function `STRUCT` ```go @@ -110,8 +117,12 @@ type Function struct { Test bool } ``` + + #### func (*Function) Code() string + *** + ### Package `STRUCT` ```go @@ -123,20 +134,42 @@ type Package struct { Functions map[string]*Function } ``` + + #### func (*Package) StructFunc(name string) []*Function + *** + + #### func (*Package) PackageFunc() []*Function + *** + + #### func (*Package) Structs() []*Struct + *** + + #### func (*Package) FileComments() *Comment + *** + + #### func (*Package) GetUnitTest(f *Function) *Function + *** + + #### func (*Package) GetExampleTest(f *Function) *Function + *** + + #### func (*Package) GetBenchmarkTest(f *Function) *Function + *** + ### Struct `STRUCT` ```go @@ -151,6 +184,7 @@ type Struct struct { Test bool } ``` + ### Type `STRUCT` ```go diff --git a/utils/generator/astgo/comment.go b/utils/generator/astgo/comment.go index 68e7767..9e7527c 100644 --- a/utils/generator/astgo/comment.go +++ b/utils/generator/astgo/comment.go @@ -5,7 +5,7 @@ import ( "strings" ) -func newComment(cg *ast.CommentGroup) *Comment { +func newComment(name string, cg *ast.CommentGroup) *Comment { c := &Comment{} if cg == nil { return c @@ -14,9 +14,10 @@ func newComment(cg *ast.CommentGroup) *Comment { c.Comments = append(c.Comments, comment.Text) cc := strings.TrimPrefix(strings.Replace(comment.Text, "// ", "//", 1), "//") if i == 0 { - s := strings.SplitN(cc, " ", 2) - if len(s) == 2 { - cc = s[1] + tsc := strings.TrimSpace(cc) + if strings.HasPrefix(tsc, name) { + s := strings.TrimSpace(strings.TrimPrefix(tsc, name)) + cc = s } } c.Clear = append(c.Clear, cc) diff --git a/utils/generator/astgo/field.go b/utils/generator/astgo/field.go index 1c00789..da2a5e2 100644 --- a/utils/generator/astgo/field.go +++ b/utils/generator/astgo/field.go @@ -10,7 +10,7 @@ func newField(field *ast.Field) []*Field { return []*Field{{ Anonymous: true, Type: newType(field.Type), - Comments: newComment(field.Comment), + Comments: newComment("", field.Comment), }} } else { var fs []*Field @@ -22,7 +22,7 @@ func newField(field *ast.Field) []*Field { Anonymous: false, Name: name.String(), Type: newType(field.Type), - Comments: newComment(field.Comment), + Comments: newComment(name.String(), field.Comment), }) } return fs diff --git a/utils/generator/astgo/file.go b/utils/generator/astgo/file.go index 233b4a1..ff4c03c 100644 --- a/utils/generator/astgo/file.go +++ b/utils/generator/astgo/file.go @@ -16,7 +16,7 @@ func newFile(owner *Package, filePath string) (*File, error) { af: af, owner: owner, FilePath: filePath, - Comment: newComment(af.Doc), + Comment: newComment("Package", af.Doc), } for _, decl := range af.Decls { switch typ := decl.(type) { diff --git a/utils/generator/astgo/function.go b/utils/generator/astgo/function.go index feb9799..7613476 100644 --- a/utils/generator/astgo/function.go +++ b/utils/generator/astgo/function.go @@ -12,7 +12,7 @@ func newFunction(astFunc *ast.FuncDecl) *Function { f := &Function{ decl: astFunc, Name: astFunc.Name.String(), - Comments: newComment(astFunc.Doc), + Comments: newComment(astFunc.Name.String(), astFunc.Doc), } f.IsTest = strings.HasPrefix(f.Name, "Test") f.IsBenchmark = strings.HasPrefix(f.Name, "Benchmark") @@ -56,6 +56,9 @@ type Function struct { } func (f *Function) Code() string { + if f.Test { + f.decl.Doc = nil + } var bb bytes.Buffer if err := format.Node(&bb, token.NewFileSet(), f.decl); err != nil { panic(err) diff --git a/utils/generator/astgo/name.go b/utils/generator/astgo/name.go index 67abeae..89b8d73 100644 --- a/utils/generator/astgo/name.go +++ b/utils/generator/astgo/name.go @@ -14,7 +14,8 @@ func newName(expr ast.Expr) string { //case *ast.FuncType: //case *ast.InterfaceType: //case *ast.MapType: - //case *ast.ChanType: + case *ast.ChanType: + str.WriteString(newName(e.Value)) case *ast.Ident: str.WriteString(e.Name) case *ast.Ellipsis: @@ -28,13 +29,17 @@ func newName(expr ast.Expr) string { case *ast.IndexExpr: str.WriteString(newName(e.X)) case *ast.IndexListExpr: + str.WriteString(newName(e.X)) case *ast.SliceExpr: - case *ast.TypeAssertExpr: - case *ast.CallExpr: + str.WriteString(newName(e.X)) + //case *ast.TypeAssertExpr: + //case *ast.CallExpr: case *ast.StarExpr: str.WriteString(newName(e.X)) case *ast.UnaryExpr: + str.WriteString(newName(e.X)) case *ast.BinaryExpr: + str.WriteString(newName(e.X)) } return str.String() } diff --git a/utils/generator/astgo/package.go b/utils/generator/astgo/package.go index 681564d..1491e94 100644 --- a/utils/generator/astgo/package.go +++ b/utils/generator/astgo/package.go @@ -91,7 +91,7 @@ func (p *Package) Structs() []*Struct { } func (p *Package) FileComments() *Comment { - var comment = newComment(nil) + var comment = newComment("", nil) for _, file := range p.Files { for _, c := range file.Comment.Comments { comment.Comments = append(comment.Comments, c) diff --git a/utils/generator/astgo/struct.go b/utils/generator/astgo/struct.go index 263e9d1..5fba9db 100644 --- a/utils/generator/astgo/struct.go +++ b/utils/generator/astgo/struct.go @@ -8,7 +8,7 @@ func newStruct(astGen *ast.GenDecl) *Struct { astTypeSpec := astGen.Specs[0].(*ast.TypeSpec) s := &Struct{ Name: astTypeSpec.Name.String(), - Comments: newComment(astGen.Doc), + Comments: newComment(astTypeSpec.Name.String(), astGen.Doc), } s.Internal = s.Name[0] >= 97 && s.Name[0] <= 122 if astTypeSpec.TypeParams != nil { diff --git a/utils/generator/genreadme/README.md b/utils/generator/genreadme/README.md index e4851ac..cbfe512 100644 --- a/utils/generator/genreadme/README.md +++ b/utils/generator/genreadme/README.md @@ -23,17 +23,18 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Builder](#builder)|暂无描述... +|`STRUCT`|[Builder](#struct_Builder)|暂无描述...
*** ## 详情信息 -#### func New(pkgDirPath string, output string) *Builder, error +#### func New(pkgDirPath string, output string) (*Builder, error) *** + ### Builder `STRUCT` ```go @@ -43,7 +44,10 @@ type Builder struct { o string } ``` + + #### func (*Builder) Generate() error +
查看 / 收起单元测试 @@ -51,11 +55,11 @@ type Builder struct { ```go func TestBuilder_Generate(t *testing.T) { - filepath.Walk("/Users/kercylan/Coding.localized/Go/minotaur", func(path string, info fs.FileInfo, err error) error { + filepath.Walk("D:/sources/minotaur", func(path string, info fs.FileInfo, err error) error { if !info.IsDir() { return nil } - if strings.Contains(strings.TrimPrefix(path, "/Users/kercylan/Coding.localized/Go/minotaur"), ".") { + if strings.Contains(strings.TrimPrefix(path, "D:/sources/minotaur"), ".") { return nil } b, err := New(path, filepath.Join(path, "README.md")) diff --git a/utils/generator/genreadme/builder.go b/utils/generator/genreadme/builder.go index 06cf694..a15f662 100644 --- a/utils/generator/genreadme/builder.go +++ b/utils/generator/genreadme/builder.go @@ -115,7 +115,7 @@ func (b *Builder) genMenus() { structGen() b.tableRow( super.If(structInfo.Interface, "`INTERFACE`", "`STRUCT`"), - fmt.Sprintf("[%s](#%s)", structInfo.Name, strings.ToLower(structInfo.Name)), + fmt.Sprintf("[%s](#struct_%s)", structInfo.Name, structInfo.Name), collection.FindFirstOrDefaultInSlice(structInfo.Comments.Clear, "暂无描述..."), ) } @@ -154,8 +154,21 @@ func (b *Builder) genStructs() { continue } titleBuild() - b.title(4, strings.TrimSpace(fmt.Sprintf("func %s%s %s", + b.title(4, strings.TrimSpace(fmt.Sprintf("func %s%s%s %s", function.Name, + func() string { + var sb strings.Builder + if len(function.Generic) > 0 { + sb.WriteString("\\[") + var genericStr = make([]string, 0) + for _, field := range function.Generic { + genericStr = append(genericStr, fmt.Sprintf("%s %s", field.Name, field.Type.Sign)) + } + sb.WriteString(strings.Join(genericStr, ", ")) + sb.WriteString("\\]") + } + return sb.String() + }(), func() string { f := funcHandler(function.Params) if !strings.HasPrefix(f, "(") { @@ -163,7 +176,13 @@ func (b *Builder) genStructs() { } return f }(), - funcHandler(function.Results), + func() string { + f := strings.TrimSpace(funcHandler(function.Results)) + if len(function.Results) >= 2 && !strings.HasPrefix(f, "(") { + f = "(" + f + ")" + } + return f + }(), ))) b.newLine(fmt.Sprintf(``, function.Name)) b.quote() @@ -172,15 +191,34 @@ func (b *Builder) genStructs() { } b.newLine() if example := b.p.GetExampleTest(function); example != nil { - b.newLine("示例代码：", "```go\n", example.Code(), "```\n") + b.newLine("**示例代码：**").newLine() + if len(example.Comments.Clear) > 0 { + for _, s := range example.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } + b.newLine("```go\n", example.Code(), "```\n") } if unitTest := b.p.GetUnitTest(function); unitTest != nil { b.detailsStart("查看 / 收起单元测试") + if len(unitTest.Comments.Clear) > 0 { + for _, s := range unitTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", unitTest.Code(), "```\n") b.detailsEnd() } if benchmarkTest := b.p.GetBenchmarkTest(function); benchmarkTest != nil { b.detailsStart("查看 / 收起基准测试") + if len(benchmarkTest.Comments.Clear) > 0 { + for _, s := range benchmarkTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", benchmarkTest.Code(), "```\n") b.detailsEnd() } @@ -193,6 +231,7 @@ func (b *Builder) genStructs() { continue } titleBuild() + b.newLine(fmt.Sprintf(``, structInfo.Name)) b.title(3, fmt.Sprintf("%s `%s`", structInfo.Name, super.If(structInfo.Interface, "INTERFACE", "STRUCT"))) b.newLine(structInfo.Comments.Clear...) b.newLine("```go") @@ -249,6 +288,7 @@ func (b *Builder) genStructs() { if function.Internal || function.Test { continue } + b.newLine(fmt.Sprintf(``, structInfo.Name, function.Name)).newLine() b.title(4, strings.TrimSpace(fmt.Sprintf("func (%s%s) %s%s %s", super.If(function.Struct.Type.IsPointer, "*", ""), structInfo.Name, @@ -260,25 +300,48 @@ func (b *Builder) genStructs() { } return f }(), - funcHandler(function.Results), + func() string { + f := funcHandler(function.Results) + if len(function.Results) >= 2 && !strings.HasPrefix(strings.TrimSpace(f), "(") { + f = "(" + f + ")" + } + return f + }(), ))) b.quote() for _, comment := range function.Comments.Clear { b.quote(comment) } - if function.Name == "Write" { - fmt.Println() - } + b.newLine() if example := b.p.GetExampleTest(function); example != nil { - b.newLine("示例代码：", "```go\n", example.Code(), "```\n") + b.newLine("**示例代码：**").newLine() + if len(example.Comments.Clear) > 0 { + for _, s := range example.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } + b.newLine("```go\n", example.Code(), "```\n") } if unitTest := b.p.GetUnitTest(function); unitTest != nil { b.detailsStart("查看 / 收起单元测试") + if len(unitTest.Comments.Clear) > 0 { + for _, s := range unitTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", unitTest.Code(), "```\n") b.detailsEnd() } if benchmarkTest := b.p.GetBenchmarkTest(function); benchmarkTest != nil { b.detailsStart("查看 / 收起基准测试") + if len(benchmarkTest.Comments.Clear) > 0 { + for _, s := range benchmarkTest.Comments.Clear { + b.newLine(fmt.Sprintf("%s", s)) + } + b.newLine().newLine() + } b.newLine("```go\n", benchmarkTest.Code(), "```\n") b.detailsEnd() } diff --git a/utils/generator/genreadme/builder_test.go b/utils/generator/genreadme/builder_test.go index 9a420ab..ded811b 100644 --- a/utils/generator/genreadme/builder_test.go +++ b/utils/generator/genreadme/builder_test.go @@ -16,11 +16,11 @@ func TestBuilder_Generate(t *testing.T) { // panic(err) //} //return - filepath.Walk("/Users/kercylan/Coding.localized/Go/minotaur", func(path string, info fs.FileInfo, err error) error { + filepath.Walk("D:/sources/minotaur", func(path string, info fs.FileInfo, err error) error { if !info.IsDir() { return nil } - if strings.Contains(strings.TrimPrefix(path, "/Users/kercylan/Coding.localized/Go/minotaur"), ".") { + if strings.Contains(strings.TrimPrefix(path, "D:/sources/minotaur"), ".") { return nil } b, err := New( diff --git a/utils/generic/README.md b/utils/generic/README.md index c57f517..9894f69 100644 --- a/utils/generic/README.md +++ b/utils/generic/README.md @@ -27,42 +27,43 @@ generic 目的在于提供一组基于泛型的用于处理通用功能的函数 |类型|名称|描述 |:--|:--|:-- -|`INTERFACE`|[IdR](#idr)|暂无描述... -|`INTERFACE`|[IDR](#idr)|暂无描述... -|`INTERFACE`|[IdW](#idw)|暂无描述... -|`INTERFACE`|[IDW](#idw)|暂无描述... -|`INTERFACE`|[IdR2W](#idr2w)|暂无描述... -|`INTERFACE`|[IDR2W](#idr2w)|暂无描述... -|`INTERFACE`|[Ordered](#ordered)|可排序类型 -|`INTERFACE`|[Number](#number)|数字类型 -|`INTERFACE`|[SignedNumber](#signednumber)|有符号数字类型 -|`INTERFACE`|[Integer](#integer)|整数类型 -|`INTERFACE`|[Signed](#signed)|有符号整数类型 -|`INTERFACE`|[Unsigned](#unsigned)|无符号整数类型 -|`INTERFACE`|[UnsignedNumber](#unsignednumber)|无符号数字类型 -|`INTERFACE`|[Float](#float)|浮点类型 -|`INTERFACE`|[Basic](#basic)|基本类型 +|`INTERFACE`|[IdR](#struct_IdR)|暂无描述... +|`INTERFACE`|[IDR](#struct_IDR)|暂无描述... +|`INTERFACE`|[IdW](#struct_IdW)|暂无描述... +|`INTERFACE`|[IDW](#struct_IDW)|暂无描述... +|`INTERFACE`|[IdR2W](#struct_IdR2W)|暂无描述... +|`INTERFACE`|[IDR2W](#struct_IDR2W)|暂无描述... +|`INTERFACE`|[Ordered](#struct_Ordered)|可排序类型 +|`INTERFACE`|[Number](#struct_Number)|数字类型 +|`INTERFACE`|[SignedNumber](#struct_SignedNumber)|有符号数字类型 +|`INTERFACE`|[Integer](#struct_Integer)|整数类型 +|`INTERFACE`|[Signed](#struct_Signed)|有符号整数类型 +|`INTERFACE`|[Unsigned](#struct_Unsigned)|无符号整数类型 +|`INTERFACE`|[UnsignedNumber](#struct_UnsignedNumber)|无符号数字类型 +|`INTERFACE`|[Float](#struct_Float)|浮点类型 +|`INTERFACE`|[Basic](#struct_Basic)|基本类型
*** ## 详情信息 -#### func IsNil(v V) bool +#### func IsNil\[V any\](v V) bool > 检查指定的值是否为 nil *** -#### func IsAllNil(v ...V) bool +#### func IsAllNil\[V any\](v ...V) bool > 检查指定的值是否全部为 nil *** -#### func IsHasNil(v ...V) bool +#### func IsHasNil\[V any\](v ...V) bool > 检查指定的值是否存在 nil *** + ### IdR `INTERFACE` ```go @@ -70,6 +71,7 @@ type IdR[ID comparable] interface { GetId() ID } ``` + ### IDR `INTERFACE` ```go @@ -77,6 +79,7 @@ type IDR[ID comparable] interface { GetID() ID } ``` + ### IdW `INTERFACE` ```go @@ -84,6 +87,7 @@ type IdW[ID comparable] interface { SetId(id ID) } ``` + ### IDW `INTERFACE` ```go @@ -91,6 +95,7 @@ type IDW[ID comparable] interface { SetID(id ID) } ``` + ### IdR2W `INTERFACE` ```go @@ -99,6 +104,7 @@ type IdR2W[ID comparable] interface { IdW[ID] } ``` + ### IDR2W `INTERFACE` ```go @@ -107,6 +113,7 @@ type IDR2W[ID comparable] interface { IDW[ID] } ``` + ### Ordered `INTERFACE` 可排序类型 ```go @@ -114,6 +121,7 @@ type Ordered interface { Integer | Float | ~string } ``` + ### Number `INTERFACE` 数字类型 ```go @@ -121,6 +129,7 @@ type Number interface { Integer | Float } ``` + ### SignedNumber `INTERFACE` 有符号数字类型 ```go @@ -128,6 +137,7 @@ type SignedNumber interface { Signed | Float } ``` + ### Integer `INTERFACE` 整数类型 ```go @@ -135,6 +145,7 @@ type Integer interface { Signed | Unsigned } ``` + ### Signed `INTERFACE` 有符号整数类型 ```go @@ -142,6 +153,7 @@ type Signed interface { ~int | ~int8 | ~int16 | ~int32 | ~int64 } ``` + ### Unsigned `INTERFACE` 无符号整数类型 ```go @@ -149,6 +161,7 @@ type Unsigned interface { UnsignedNumber | ~uintptr } ``` + ### UnsignedNumber `INTERFACE` 无符号数字类型 ```go @@ -156,6 +169,7 @@ type UnsignedNumber interface { ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 } ``` + ### Float `INTERFACE` 浮点类型 ```go @@ -163,6 +177,7 @@ type Float interface { ~float32 | ~float64 } ``` + ### Basic `INTERFACE` 基本类型 ```go diff --git a/utils/geometry/README.md b/utils/geometry/README.md index 177eb01..1f5b0d0 100644 --- a/utils/geometry/README.md +++ b/utils/geometry/README.md @@ -117,26 +117,27 @@ geometry 旨在提供一组用于处理几何形状和计算几何属性的函 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Circle](#circle)|圆形 -|`STRUCT`|[FloorPlan](#floorplan)|平面图 -|`STRUCT`|[Direction](#direction)|方向 -|`STRUCT`|[LineSegment](#linesegment)|通过两个点表示一根线段 -|`STRUCT`|[LineSegmentCap](#linesegmentcap)|可以包含一份额外数据的线段 -|`STRUCT`|[Point](#point)|表示了一个由 x、y 坐标组成的点 -|`STRUCT`|[PointCap](#pointcap)|表示了一个由 x、y 坐标组成的点，这个点具有一个数据容量 -|`STRUCT`|[Shape](#shape)|通过多个点表示了一个形状 -|`STRUCT`|[ShapeSearchOption](#shapesearchoption)|图形搜索可选项，用于 Shape.ShapeSearch 搜索支持 +|`STRUCT`|[Circle](#struct_Circle)|圆形 +|`STRUCT`|[FloorPlan](#struct_FloorPlan)|平面图 +|`STRUCT`|[Direction](#struct_Direction)|方向 +|`STRUCT`|[LineSegment](#struct_LineSegment)|通过两个点表示一根线段 +|`STRUCT`|[LineSegmentCap](#struct_LineSegmentCap)|可以包含一份额外数据的线段 +|`STRUCT`|[Point](#struct_Point)|表示了一个由 x、y 坐标组成的点 +|`STRUCT`|[PointCap](#struct_PointCap)|表示了一个由 x、y 坐标组成的点，这个点具有一个数据容量 +|`STRUCT`|[Shape](#struct_Shape)|通过多个点表示了一个形状 +|`STRUCT`|[ShapeSearchOption](#struct_ShapeSearchOption)|图形搜索可选项，用于 Shape.ShapeSearch 搜索支持
*** ## 详情信息 -#### func NewCircle(radius V, points int) Circle[V] +#### func NewCircle\[V generic.SignedNumber\](radius V, points int) Circle[V] > 通过传入圆的半径和需要的点数量，生成一个圆 -示例代码： +**示例代码：** + ```go func ExampleNewCircle() { @@ -146,143 +147,143 @@ func ExampleNewCircle() { ``` *** -#### func CalcCircleCentroidDistance(circle1 Circle[V], circle2 Circle[V]) V +#### func CalcCircleCentroidDistance\[V generic.SignedNumber\](circle1 Circle[V], circle2 Circle[V]) V > 计算两个圆质心距离 *** -#### func GetOppositionDirection(direction Direction) Direction +#### func GetOppositionDirection(direction Direction) Direction > 获取特定方向的对立方向 *** -#### func GetDirectionNextWithCoordinate(direction Direction, x V, y V) (nx V, ny V) +#### func GetDirectionNextWithCoordinate\[V generic.SignedNumber\](direction Direction, x V, y V) (nx V, ny V) > 获取特定方向上的下一个坐标 *** -#### func GetDirectionNextWithPoint(direction Direction, point Point[V]) Point[V] +#### func GetDirectionNextWithPoint\[V generic.SignedNumber\](direction Direction, point Point[V]) Point[V] > 获取特定方向上的下一个坐标 *** -#### func GetDirectionNextWithPos(direction Direction, width V, pos V) V +#### func GetDirectionNextWithPos\[V generic.SignedNumber\](direction Direction, width V, pos V) V > 获取位置在特定宽度和特定方向上的下一个位置 > - 需要注意的是，在左右方向时，当下一个位置不在矩形区域内时，将会返回上一行的末位置或下一行的首位置 *** -#### func CalcDirection(x1 V, y1 V, x2 V, y2 V) Direction +#### func CalcDirection\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V) Direction > 计算点2位于点1的方向 *** -#### func CalcDistanceWithCoordinate(x1 V, y1 V, x2 V, y2 V) V +#### func CalcDistanceWithCoordinate\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V) V > 计算两点之间的距离 *** -#### func CalcDistanceWithPoint(point1 Point[V], point2 Point[V]) V +#### func CalcDistanceWithPoint\[V generic.SignedNumber\](point1 Point[V], point2 Point[V]) V > 计算两点之间的距离 *** -#### func CalcDistanceSquared(x1 V, y1 V, x2 V, y2 V) V +#### func CalcDistanceSquared\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V) V > 计算两点之间的平方距离 > - 这个函数的主要用途是在需要计算两点之间距离的情况下，但不需要得到实际的距离值，而只需要比较距离大小。因为平方根运算相对较为耗时，所以在只需要比较大小的情况下，通常会使用平方距离。 *** -#### func CalcAngle(x1 V, y1 V, x2 V, y2 V) V +#### func CalcAngle\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V) V > 计算点2位于点1之间的角度 *** -#### func CalcNewCoordinate(x V, y V, angle V, distance V) (newX V, newY V) +#### func CalcNewCoordinate\[V generic.SignedNumber\](x V, y V, angle V, distance V) (newX V, newY V) > 根据给定的x、y坐标、角度和距离计算新的坐标 *** -#### func CalcRadianWithAngle(angle V) V +#### func CalcRadianWithAngle\[V generic.SignedNumber\](angle V) V > 根据角度 angle 计算弧度 *** -#### func CalcAngleDifference(angleA V, angleB V) V +#### func CalcAngleDifference\[V generic.SignedNumber\](angleA V, angleB V) V > 计算两个角度之间的最小角度差 *** -#### func CalcRayIsIntersect(x V, y V, angle V, shape Shape[V]) bool +#### func CalcRayIsIntersect\[V generic.SignedNumber\](x V, y V, angle V, shape Shape[V]) bool > 根据给定的位置和角度生成射线，检测射线是否与多边形发生碰撞 *** -#### func NewLineSegment(start Point[V], end Point[V]) LineSegment[V] +#### func NewLineSegment\[V generic.SignedNumber\](start Point[V], end Point[V]) LineSegment[V] > 创建一根线段 *** -#### func NewLineSegmentCap(start Point[V], end Point[V], data Data) LineSegmentCap[V, Data] +#### func NewLineSegmentCap\[V generic.SignedNumber, Data any\](start Point[V], end Point[V], data Data) LineSegmentCap[V, Data] > 创建一根包含数据的线段 *** -#### func NewLineSegmentCapWithLine(line LineSegment[V], data Data) LineSegmentCap[V, Data] +#### func NewLineSegmentCapWithLine\[V generic.SignedNumber, Data any\](line LineSegment[V], data Data) LineSegmentCap[V, Data] > 通过已有线段创建一根包含数据的线段 *** -#### func ConvertLineSegmentGeneric(line LineSegment[V]) LineSegment[TO] +#### func ConvertLineSegmentGeneric\[V generic.SignedNumber, TO generic.SignedNumber\](line LineSegment[V]) LineSegment[TO] > 转换线段的泛型类型为特定类型 *** -#### func PointOnLineSegmentWithCoordinate(x1 V, y1 V, x2 V, y2 V, x V, y V) bool +#### func PointOnLineSegmentWithCoordinate\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V, x V, y V) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 *** -#### func PointOnLineSegmentWithPos(width V, pos1 V, pos2 V, pos V) bool +#### func PointOnLineSegmentWithPos\[V generic.SignedNumber\](width V, pos1 V, pos2 V, pos V) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 *** -#### func PointOnLineSegmentWithPoint(point1 Point[V], point2 Point[V], point Point[V]) bool +#### func PointOnLineSegmentWithPoint\[V generic.SignedNumber\](point1 Point[V], point2 Point[V], point Point[V]) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 *** -#### func PointOnLineSegmentWithCoordinateInBounds(x1 V, y1 V, x2 V, y2 V, x V, y V) bool +#### func PointOnLineSegmentWithCoordinateInBounds\[V generic.SignedNumber\](x1 V, y1 V, x2 V, y2 V, x V, y V) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 > - 与 PointOnLineSegmentWithCoordinate 不同的是， PointOnLineSegmentWithCoordinateInBounds 中会判断线段及点的位置是否正确 *** -#### func PointOnLineSegmentWithPosInBounds(width V, pos1 V, pos2 V, pos V) bool +#### func PointOnLineSegmentWithPosInBounds\[V generic.SignedNumber\](width V, pos1 V, pos2 V, pos V) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 > - 与 PointOnLineSegmentWithPos 不同的是， PointOnLineSegmentWithPosInBounds 中会判断线段及点的位置是否正确 *** -#### func PointOnLineSegmentWithPointInBounds(point1 Point[V], point2 Point[V], point Point[V]) bool +#### func PointOnLineSegmentWithPointInBounds\[V generic.SignedNumber\](point1 Point[V], point2 Point[V], point Point[V]) bool > 通过一个线段两个点的位置和一个点的坐标，判断这个点是否在一条线段上 > - 与 PointOnLineSegmentWithPoint 不同的是， PointOnLineSegmentWithPointInBounds 中会判断线段及点的位置是否正确 *** -#### func CalcLineSegmentIsCollinear(line1 LineSegment[V], line2 LineSegment[V], tolerance V) bool +#### func CalcLineSegmentIsCollinear\[V generic.SignedNumber\](line1 LineSegment[V], line2 LineSegment[V], tolerance V) bool > 检查两条线段在一个误差内是否共线 > - 共线是指两条线段在同一直线上，即它们的延长线可以重合 *** -#### func CalcLineSegmentIsOverlap(line1 LineSegment[V], line2 LineSegment[V]) (line LineSegment[V], overlap bool) +#### func CalcLineSegmentIsOverlap\[V generic.SignedNumber\](line1 LineSegment[V], line2 LineSegment[V]) (line LineSegment[V], overlap bool) > 通过对点进行排序来检查两条共线线段是否重叠，返回重叠线段 *** -#### func CalcLineSegmentIsIntersect(line1 LineSegment[V], line2 LineSegment[V]) bool +#### func CalcLineSegmentIsIntersect\[V generic.SignedNumber\](line1 LineSegment[V], line2 LineSegment[V]) bool > 计算两条线段是否相交 @@ -305,17 +306,17 @@ func TestCalcLineSegmentIsIntersect(t *testing.T) { *** -#### func CalcLineSegmentSlope(line LineSegment[V]) V +#### func CalcLineSegmentSlope\[V generic.SignedNumber\](line LineSegment[V]) V > 计算线段的斜率 *** -#### func CalcLineSegmentIntercept(line LineSegment[V]) V +#### func CalcLineSegmentIntercept\[V generic.SignedNumber\](line LineSegment[V]) V > 计算线段的截距 *** -#### func NewPoint(x V, y V) Point[V] +#### func NewPoint\[V generic.SignedNumber\](x V, y V) Point[V] > 创建一个由 x、y 坐标组成的点 @@ -337,150 +338,151 @@ func TestNewPoint(t *testing.T) { *** -#### func NewPointCap(x V, y V) PointCap[V, D] +#### func NewPointCap\[V generic.SignedNumber, D any\](x V, y V) PointCap[V, D] > 创建一个由 x、y 坐标组成的点，这个点具有一个数据容量 *** -#### func NewPointCapWithData(x V, y V, data D) PointCap[V, D] +#### func NewPointCapWithData\[V generic.SignedNumber, D any\](x V, y V, data D) PointCap[V, D] > 通过设置数据的方式创建一个由 x、y 坐标组成的点，这个点具有一个数据容量 *** -#### func NewPointCapWithPoint(point Point[V], data D) PointCap[V, D] +#### func NewPointCapWithPoint\[V generic.SignedNumber, D any\](point Point[V], data D) PointCap[V, D] > 通过设置数据的方式创建一个由已有坐标组成的点，这个点具有一个数据容量 *** -#### func CoordinateToPoint(x V, y V) Point[V] +#### func CoordinateToPoint\[V generic.SignedNumber\](x V, y V) Point[V] > 将坐标转换为x、y的坐标数组 *** -#### func CoordinateToPos(width V, x V, y V) V +#### func CoordinateToPos\[V generic.SignedNumber\](width V, x V, y V) V > 将坐标转换为二维数组的顺序位置坐标 > - 需要确保x的取值范围必须小于width，或者将会得到不正确的值 *** -#### func PointToCoordinate(position Point[V]) (x V, y V) +#### func PointToCoordinate\[V generic.SignedNumber\](position Point[V]) (x V, y V) > 将坐标数组转换为x和y坐标 *** -#### func PointToPos(width V, xy Point[V]) V +#### func PointToPos\[V generic.SignedNumber\](width V, xy Point[V]) V > 将坐标转换为二维数组的顺序位置 > - 需要确保x的取值范围必须小于width，或者将会得到不正确的值 *** -#### func PosToCoordinate(width V, pos V) (x V, y V) +#### func PosToCoordinate\[V generic.SignedNumber\](width V, pos V) (x V, y V) > 通过宽度将一个二维数组的顺序位置转换为xy坐标 *** -#### func PosToPoint(width V, pos V) Point[V] +#### func PosToPoint\[V generic.SignedNumber\](width V, pos V) Point[V] > 通过宽度将一个二维数组的顺序位置转换为x、y的坐标数组 *** -#### func PosToCoordinateX(width V, pos V) V +#### func PosToCoordinateX\[V generic.SignedNumber\](width V, pos V) V > 通过宽度将一个二维数组的顺序位置转换为X坐标 *** -#### func PosToCoordinateY(width V, pos V) V +#### func PosToCoordinateY\[V generic.SignedNumber\](width V, pos V) V > 通过宽度将一个二维数组的顺序位置转换为Y坐标 *** -#### func PointCopy(point Point[V]) Point[V] +#### func PointCopy\[V generic.SignedNumber\](point Point[V]) Point[V] > 复制一个坐标数组 *** -#### func PointToPosWithMulti(width V, points ...Point[V]) []V +#### func PointToPosWithMulti\[V generic.SignedNumber\](width V, points ...Point[V]) []V > 将一组坐标转换为二维数组的顺序位置 > - 需要确保x的取值范围必须小于width，或者将会得到不正确的值 *** -#### func PosToPointWithMulti(width V, positions ...V) []Point[V] +#### func PosToPointWithMulti\[V generic.SignedNumber\](width V, positions ...V) []Point[V] > 将一组二维数组的顺序位置转换为一组数组坐标 *** -#### func PosSameRow(width V, pos1 V, pos2 V) bool +#### func PosSameRow\[V generic.SignedNumber\](width V, pos1 V, pos2 V) bool > 返回两个顺序位置在同一宽度是否位于同一行 *** -#### func DoublePointToCoordinate(point1 Point[V], point2 Point[V]) (x1 V, y1 V, x2 V, y2 V) +#### func DoublePointToCoordinate\[V generic.SignedNumber\](point1 Point[V], point2 Point[V]) (x1 V, y1 V, x2 V, y2 V) > 将两个位置转换为 x1, y1, x2, y2 的坐标进行返回 *** -#### func CalcProjectionPoint(line LineSegment[V], point Point[V]) Point[V] +#### func CalcProjectionPoint\[V generic.SignedNumber\](line LineSegment[V], point Point[V]) Point[V] > 计算一个点到一条线段的最近点（即投影点）的。这个函数接收一个点和一条线段作为输入，线段由两个端点组成。 > - 该函数的主要用于需要计算一个点到一条线段的最近点的情况下 *** -#### func GetAdjacentTranslatePos(matrix []T, width P, pos P) (result []P) +#### func GetAdjacentTranslatePos\[T any, P generic.SignedNumber\](matrix []T, width P, pos P) (result []P) > 获取一个连续位置的矩阵中，特定位置相邻的最多四个平移方向（上下左右）的位置 *** -#### func GetAdjacentTranslateCoordinateXY(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentTranslateCoordinateXY\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 x、y 的二维矩阵中，特定位置相邻的最多四个平移方向（上下左右）的位置 *** -#### func GetAdjacentTranslateCoordinateYX(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentTranslateCoordinateYX\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 y、x 的二维矩阵中，特定位置相邻的最多四个平移方向（上下左右）的位置 *** -#### func GetAdjacentDiagonalsPos(matrix []T, width P, pos P) (result []P) +#### func GetAdjacentDiagonalsPos\[T any, P generic.SignedNumber\](matrix []T, width P, pos P) (result []P) > 获取一个连续位置的矩阵中，特定位置相邻的对角线最多四个方向的位置 *** -#### func GetAdjacentDiagonalsCoordinateXY(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentDiagonalsCoordinateXY\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 x、y 的二维矩阵中，特定位置相邻的对角线最多四个方向的位置 *** -#### func GetAdjacentDiagonalsCoordinateYX(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentDiagonalsCoordinateYX\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 tx 的二维矩阵中，特定位置相邻的对角线最多四个方向的位置 *** -#### func GetAdjacentPos(matrix []T, width P, pos P) (result []P) +#### func GetAdjacentPos\[T any, P generic.SignedNumber\](matrix []T, width P, pos P) (result []P) > 获取一个连续位置的矩阵中，特定位置相邻的最多八个方向的位置 *** -#### func GetAdjacentCoordinateXY(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentCoordinateXY\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 x、y 的二维矩阵中，特定位置相邻的最多八个方向的位置 *** -#### func GetAdjacentCoordinateYX(matrix [][]T, x P, y P) (result []Point[P]) +#### func GetAdjacentCoordinateYX\[T any, P generic.SignedNumber\](matrix [][]T, x P, y P) (result []Point[P]) > 获取一个基于 yx 的二维矩阵中，特定位置相邻的最多八个方向的位置 *** -#### func CoordinateMatrixToPosMatrix(matrix [][]V) (width int, posMatrix []V) +#### func CoordinateMatrixToPosMatrix\[V any\](matrix [][]V) (width int, posMatrix []V) > 将二维矩阵转换为顺序的二维矩阵 *** -#### func GetShapeCoverageAreaWithPoint(points ...Point[V]) (left V, right V, top V, bottom V) +#### func GetShapeCoverageAreaWithPoint\[V generic.SignedNumber\](points ...Point[V]) (left V, right V, top V, bottom V) > 通过传入的一组坐标 points 计算一个图形覆盖的矩形范围 -示例代码： +**示例代码：** + ```go func ExampleGetShapeCoverageAreaWithPoint() { @@ -521,11 +523,12 @@ func TestGetShapeCoverageAreaWithPoint(t *testing.T) { *** -#### func GetShapeCoverageAreaWithPos(width V, positions ...V) (left V, right V, top V, bottom V) +#### func GetShapeCoverageAreaWithPos\[V generic.SignedNumber\](width V, positions ...V) (left V, right V, top V, bottom V) > 通过传入的一组坐标 positions 计算一个图形覆盖的矩形范围 -示例代码： +**示例代码：** + ```go func ExampleGetShapeCoverageAreaWithPos() { @@ -558,12 +561,13 @@ func TestGetShapeCoverageAreaWithPos(t *testing.T) { *** -#### func CoverageAreaBoundless(l V, r V, t V, b V) (left V, right V, top V, bottom V) +#### func CoverageAreaBoundless\[V generic.SignedNumber\](l V, r V, t V, b V) (left V, right V, top V, bottom V) > 将一个图形覆盖矩形范围设置为无边的 > - 无边化表示会将多余的部分进行裁剪，例如图形左边从 2 开始的时候，那么左边将会被裁剪到从 0 开始 -示例代码： +**示例代码：** + ```go func ExampleCoverageAreaBoundless() { @@ -596,7 +600,7 @@ func TestCoverageAreaBoundless(t *testing.T) { *** -#### func GenerateShapeOnRectangle(points ...Point[V]) (result []PointCap[V, bool]) +#### func GenerateShapeOnRectangle\[V generic.SignedNumber\](points ...Point[V]) (result []PointCap[V, bool]) > 生成一组二维坐标的形状 > - 这个形状将被在一个刚好能容纳形状的矩形中表示 @@ -638,44 +642,44 @@ func TestGenerateShapeOnRectangle(t *testing.T) { *** -#### func GenerateShapeOnRectangleWithCoordinate(points ...Point[V]) (result [][]bool) +#### func GenerateShapeOnRectangleWithCoordinate\[V generic.SignedNumber\](points ...Point[V]) (result [][]bool) > 生成一组二维坐标的形状 > - 这个形状将被在一个刚好能容纳形状的矩形中表示 > - 为 true 的位置表示了形状的每一个点 *** -#### func GetExpressibleRectangleBySize(width V, height V, minWidth V, minHeight V) (result []Point[V]) +#### func GetExpressibleRectangleBySize\[V generic.SignedNumber\](width V, height V, minWidth V, minHeight V) (result []Point[V]) > 获取一个宽高可表达的所有特定尺寸以上的矩形形状 > - 返回值表示了每一个矩形右下角的x,y位置（左上角始终为0, 0） > - 矩形尺寸由大到小 *** -#### func GetExpressibleRectangle(width V, height V) (result []Point[V]) +#### func GetExpressibleRectangle\[V generic.SignedNumber\](width V, height V) (result []Point[V]) > 获取一个宽高可表达的所有矩形形状 > - 返回值表示了每一个矩形右下角的x,y位置（左上角始终为0, 0） > - 矩形尺寸由大到小 *** -#### func GetRectangleFullPointsByXY(startX V, startY V, endX V, endY V) (result []Point[V]) +#### func GetRectangleFullPointsByXY\[V generic.SignedNumber\](startX V, startY V, endX V, endY V) (result []Point[V]) > 通过开始结束坐标获取一个矩形包含的所有点 > - 例如 1,1 到 2,2 的矩形结果为 1,1 2,1 1,2 2,2 *** -#### func GetRectangleFullPoints(width V, height V) (result []Point[V]) +#### func GetRectangleFullPoints\[V generic.SignedNumber\](width V, height V) (result []Point[V]) > 获取一个矩形填充满后包含的所有点 *** -#### func GetRectangleFullPos(width V, height V) (result []V) +#### func GetRectangleFullPos\[V generic.SignedNumber\](width V, height V) (result []V) > 获取一个矩形填充满后包含的所有位置 *** -#### func CalcRectangleCentroid(shape Shape[V]) Point[V] +#### func CalcRectangleCentroid\[V generic.SignedNumber\](shape Shape[V]) Point[V] > 计算矩形质心 > - 非多边形质心计算，仅为顶点的平均值 - 该区域中多边形因子的适当质心 @@ -691,11 +695,12 @@ func TestGenerateShapeOnRectangle(t *testing.T) { > 设置 Shape.String 是没有边界的 *** -#### func NewShape(points ...Point[V]) Shape[V] +#### func NewShape\[V generic.SignedNumber\](points ...Point[V]) Shape[V] > 通过多个点生成一个形状进行返回 -示例代码： +**示例代码：** + ```go func ExampleNewShape() { @@ -733,12 +738,13 @@ func TestNewShape(t *testing.T) { *** -#### func NewShapeWithString(rows []string, point rune) (shape Shape[V]) +#### func NewShapeWithString\[V generic.SignedNumber\](rows []string, point rune) (shape Shape[V]) > 通过字符串将指定 rune 转换为点位置生成形状进行返回 > - 每个点的顺序从上到下，从左到右 -示例代码： +**示例代码：** + ```go func ExampleNewShapeWithString() { @@ -775,95 +781,96 @@ func TestNewShapeWithString(t *testing.T) { *** -#### func CalcBoundingRadius(shape Shape[V]) V +#### func CalcBoundingRadius\[V generic.SignedNumber\](shape Shape[V]) V > 计算多边形转换为圆的半径 *** -#### func CalcBoundingRadiusWithCentroid(shape Shape[V], centroid Point[V]) V +#### func CalcBoundingRadiusWithCentroid\[V generic.SignedNumber\](shape Shape[V], centroid Point[V]) V > 计算多边形在特定质心下圆的半径 *** -#### func CalcTriangleTwiceArea(a Point[V], b Point[V], c Point[V]) V +#### func CalcTriangleTwiceArea\[V generic.SignedNumber\](a Point[V], b Point[V], c Point[V]) V > 计算由 a、b、c 三个点组成的三角形的面积的两倍 *** -#### func IsPointOnEdge(edges []LineSegment[V], point Point[V]) bool +#### func IsPointOnEdge\[V generic.SignedNumber\](edges []LineSegment[V], point Point[V]) bool > 检查点是否在 edges 的任意一条边上 *** -#### func ProjectionPointToShape(point Point[V], shape Shape[V]) Point[V], V +#### func ProjectionPointToShape\[V generic.SignedNumber\](point Point[V], shape Shape[V]) (Point[V], V) > 将一个点投影到一个多边形上，找到离该点最近的投影点，并返回投影点和距离 *** -#### func WithShapeSearchRectangleLowerLimit(minWidth int, minHeight int) ShapeSearchOption +#### func WithShapeSearchRectangleLowerLimit(minWidth int, minHeight int) ShapeSearchOption > 通过矩形宽高下限的方式搜索 *** -#### func WithShapeSearchRectangleUpperLimit(maxWidth int, maxHeight int) ShapeSearchOption +#### func WithShapeSearchRectangleUpperLimit(maxWidth int, maxHeight int) ShapeSearchOption > 通过矩形宽高上限的方式搜索 *** -#### func WithShapeSearchRightAngle() ShapeSearchOption +#### func WithShapeSearchRightAngle() ShapeSearchOption > 通过直角的方式进行搜索 *** -#### func WithShapeSearchOppositionDirection(direction Direction) ShapeSearchOption +#### func WithShapeSearchOppositionDirection(direction Direction) ShapeSearchOption > 通过限制对立方向的方式搜索 > - 对立方向例如上不能与下共存 *** -#### func WithShapeSearchDirectionCount(count int) ShapeSearchOption +#### func WithShapeSearchDirectionCount(count int) ShapeSearchOption > 通过限制方向数量的方式搜索 *** -#### func WithShapeSearchDirectionCountLowerLimit(direction Direction, count int) ShapeSearchOption +#### func WithShapeSearchDirectionCountLowerLimit(direction Direction, count int) ShapeSearchOption > 通过限制特定方向数量下限的方式搜索 *** -#### func WithShapeSearchDirectionCountUpperLimit(direction Direction, count int) ShapeSearchOption +#### func WithShapeSearchDirectionCountUpperLimit(direction Direction, count int) ShapeSearchOption > 通过限制特定方向数量上限的方式搜索 *** -#### func WithShapeSearchDeduplication() ShapeSearchOption +#### func WithShapeSearchDeduplication() ShapeSearchOption > 通过去重的方式进行搜索 > - 去重方式中每个点仅会被使用一次 *** -#### func WithShapeSearchPointCountLowerLimit(lowerLimit int) ShapeSearchOption +#### func WithShapeSearchPointCountLowerLimit(lowerLimit int) ShapeSearchOption > 通过限制图形构成的最小点数进行搜索 > - 当搜索到的图形的点数量低于 lowerLimit 时，将被忽略 *** -#### func WithShapeSearchPointCountUpperLimit(upperLimit int) ShapeSearchOption +#### func WithShapeSearchPointCountUpperLimit(upperLimit int) ShapeSearchOption > 通过限制图形构成的最大点数进行搜索 > - 当搜索到的图形的点数量大于 upperLimit 时，将被忽略 *** -#### func WithShapeSearchAsc() ShapeSearchOption +#### func WithShapeSearchAsc() ShapeSearchOption > 通过升序的方式进行搜索 *** -#### func WithShapeSearchDesc() ShapeSearchOption +#### func WithShapeSearchDesc() ShapeSearchOption > 通过降序的方式进行搜索 *** + ### Circle `STRUCT` 圆形 ```go @@ -871,63 +878,109 @@ type Circle[V generic.SignedNumber] struct { Shape[V] } ``` + + #### func (Circle) Radius() V > 获取圆形半径 + *** + + #### func (Circle) Centroid() Point[V] > 获取圆形质心位置 + *** + + #### func (Circle) Overlap(circle Circle[V]) bool > 与另一个圆是否发生重叠 + *** + + #### func (Circle) Area() V > 获取圆形面积 + *** + + #### func (Circle) Length() V > 获取圆的周长 + *** + + #### func (Circle) CentroidDistance(circle Circle[V]) V > 计算与另一个圆的质心距离 + *** + ### FloorPlan `STRUCT` 平面图 ```go type FloorPlan []string ``` + + #### func (FloorPlan) IsFree(point Point[int]) bool > 检查位置是否为空格 + *** + + #### func (FloorPlan) IsInBounds(point Point[int]) bool > 检查位置是否在边界内 + *** + + #### func (FloorPlan) Put(point Point[int], c rune) > 设置平面图特定位置的字符 + *** + + #### func (FloorPlan) String() string > 获取平面图结果 + *** + ### Direction `STRUCT` 方向 ```go type Direction uint8 ``` + ### LineSegment `STRUCT` 通过两个点表示一根线段 ```go type LineSegment[V generic.SignedNumber] [2]Point[V] ``` + + #### func (LineSegment) GetPoints() [2]Point[V] > 获取该线段的两个点 + *** + + #### func (LineSegment) GetStart() Point[V] > 获取该线段的开始位置 + *** + + #### func (LineSegment) GetEnd() Point[V] > 获取该线段的结束位置 + *** + + #### func (LineSegment) GetLength() V > 获取该线段的长度 + *** + ### LineSegmentCap `STRUCT` 可以包含一份额外数据的线段 ```go @@ -936,59 +989,114 @@ type LineSegmentCap[V generic.SignedNumber, Data any] struct { Data Data } ``` + + +#### func (*LineSegmentCap) GetData() Data + +*** + ### Point `STRUCT` 表示了一个由 x、y 坐标组成的点 ```go type Point[V generic.SignedNumber] [2]V ``` + + #### func (Point) GetX() V > 返回该点的 x 坐标 + *** + + #### func (Point) GetY() V > 返回该点的 y 坐标 + *** + + #### func (Point) GetXY() (x V, y V) > 返回该点的 x、y 坐标 + *** + + #### func (Point) GetPos(width V) V > 返回该点位于特定宽度的二维数组的顺序位置 + *** + + #### func (Point) GetOffset(x V, y V) Point[V] > 获取偏移后的新坐标 + *** + + #### func (Point) Negative() bool > 返回该点是否是一个负数坐标 + *** + + #### func (Point) OutOf(minWidth V, minHeight V, maxWidth V, maxHeight V) bool > 返回该点在特定宽高下是否越界f + *** + + #### func (Point) Equal(point Point[V]) bool > 返回两个点是否相等 + *** + + #### func (Point) Copy() Point[V] > 复制一个点位置 + *** + + #### func (Point) Add(point Point[V]) Point[V] > 得到加上 point 后的点 + *** + + #### func (Point) Sub(point Point[V]) Point[V] > 得到减去 point 后的点 + *** + + #### func (Point) Mul(point Point[V]) Point[V] > 得到乘以 point 后的点 + *** + + #### func (Point) Div(point Point[V]) Point[V] > 得到除以 point 后的点 + *** + + #### func (Point) Abs() Point[V] > 返回位置的绝对值 + *** + + #### func (Point) Max(point Point[V]) Point[V] > 返回两个位置中每个维度的最大值组成的新的位置 + *** + + #### func (Point) Min(point Point[V]) Point[V] > 返回两个位置中每个维度的最小值组成的新的位置 + *** + ### PointCap `STRUCT` 表示了一个由 x、y 坐标组成的点，这个点具有一个数据容量 ```go @@ -997,14 +1105,25 @@ type PointCap[V generic.SignedNumber, D any] struct { Data D } ``` + + +#### func (PointCap) GetData() D +> 获取数据 + +*** + ### Shape `STRUCT` 通过多个点表示了一个形状 ```go type Shape[V generic.SignedNumber] []Point[V] ``` + + #### func (Shape) Points() []Point[V] > 获取这个形状的所有点 -示例代码： + +**示例代码：** + ```go func ExampleShape_Points() { @@ -1039,9 +1158,13 @@ func TestShape_Points(t *testing.T) { *** + + #### func (Shape) PointCount() int > 获取这个形状的点数量 -示例代码： + +**示例代码：** + ```go func ExampleShape_PointCount() { @@ -1071,16 +1194,26 @@ func TestShape_PointCount(t *testing.T) { *** + + #### func (Shape) Contains(point Point[V]) bool > 返回该形状中是否包含点 + *** + + #### func (Shape) ToCircle() Circle[V] > 将形状转换为圆形进行处理 > - 当形状非圆形时将会产生意外情况 + *** + + #### func (Shape) String() string > 将该形状转换为可视化的字符串进行返回 -示例代码： + +**示例代码：** + ```go func ExampleShape_String() { @@ -1111,6 +1244,8 @@ func TestShape_String(t *testing.T) { *** + + #### func (Shape) ShapeSearch(options ...ShapeSearchOption) (result []Shape[V]) > 获取该形状中包含的所有图形组合及其位置 > - 需要注意的是，即便图形最终表示为相同的，但是只要位置组合顺序不同，那么也将被认定为一种图形组合 @@ -1118,7 +1253,9 @@ func TestShape_String(t *testing.T) { > - 返回的坐标为原始形状的坐标 > > 可通过可选项对搜索结果进行过滤 -示例代码： + +**示例代码：** + ```go func ExampleShape_ShapeSearch() { @@ -1132,13 +1269,20 @@ func ExampleShape_ShapeSearch() { ``` *** + + #### func (Shape) Edges() (edges []LineSegment[V]) > 获取该形状每一条边 > - 该形状需要最少由3个点组成，否则将不会返回任意一边 + *** + + #### func (Shape) IsPointOnEdge(point Point[V]) bool > 检查点是否在该形状的一条边上 + *** + ### ShapeSearchOption `STRUCT` 图形搜索可选项，用于 Shape.ShapeSearch 搜索支持 ```go diff --git a/utils/geometry/astar/README.md b/utils/geometry/astar/README.md index 100b4ad..b5e8753 100644 --- a/utils/geometry/astar/README.md +++ b/utils/geometry/astar/README.md @@ -28,14 +28,14 @@ astar 提供用于实现 A* 算法的函数和数据结构。A* 算法是一种 |类型|名称|描述 |:--|:--|:-- -|`INTERFACE`|[Graph](#graph)|适用于 A* 算法的图数据结构接口定义，表示导航网格，其中包含了节点和连接节点的边。 +|`INTERFACE`|[Graph](#struct_Graph)|适用于 A* 算法的图数据结构接口定义，表示导航网格，其中包含了节点和连接节点的边。
*** ## 详情信息 -#### func Find(graph Graph[Node], start Node, end Node, cost func (a Node) V, heuristic func (a Node) V) []Node +#### func Find\[Node comparable, V generic.SignedNumber\](graph Graph[Node], start Node, end Node, cost func (a Node) V, heuristic func (a Node) V) []Node > 使用 A* 算法在导航网格上查找从起点到终点的最短路径，并返回路径上的节点序列。 > @@ -58,7 +58,8 @@ astar 提供用于实现 A* 算法的函数和数据结构。A* 算法是一种 > - 函数内部使用了堆数据结构来管理待处理的节点。 > - 函数返回一个节点序列，表示从起点到终点的最短路径。如果找不到路径，则返回空序列。 -示例代码： +**示例代码：** + ```go func ExampleFind() { @@ -77,6 +78,7 @@ func ExampleFind() { ``` *** + ### Graph `INTERFACE` 适用于 A* 算法的图数据结构接口定义，表示导航网格，其中包含了节点和连接节点的边。 ```go @@ -84,5 +86,8 @@ type Graph[Node comparable] interface { Neighbours(node Node) []Node } ``` + + #### func (Graph) Neighbours(point geometry.Point[int]) []geometry.Point[int] + *** diff --git a/utils/geometry/dp/README.md b/utils/geometry/dp/README.md index 5be6dee..bbec081 100644 --- a/utils/geometry/dp/README.md +++ b/utils/geometry/dp/README.md @@ -27,15 +27,15 @@ dp (DistributionPattern) 提供用于在二维数组中根据不同的特征标 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[DistributionPattern](#distributionpattern)|分布图 -|`STRUCT`|[Link](#link)|暂无描述... +|`STRUCT`|[DistributionPattern](#struct_DistributionPattern)|分布图 +|`STRUCT`|[Link](#struct_Link)|暂无描述... *** ## 详情信息 -#### func NewDistributionPattern(sameKindVerifyHandle func (itemA Item) bool) *DistributionPattern[Item] +#### func NewDistributionPattern\[Item any\](sameKindVerifyHandle func (itemA Item) bool) *DistributionPattern[Item] > 构建一个分布图实例 @@ -69,6 +69,7 @@ func TestNewDistributionPattern(t *testing.T) { *** + ### DistributionPattern `STRUCT` 分布图 ```go @@ -80,30 +81,49 @@ type DistributionPattern[Item any] struct { usePos bool } ``` + + #### func (*DistributionPattern) GetLinks(pos int) (result []Link[Item]) > 获取关联的成员 > - 其中包含传入的 pos 成员 + *** + + #### func (*DistributionPattern) HasLink(pos int) bool > 检查一个位置是否包含除它本身外的其他关联成员 + *** + + #### func (*DistributionPattern) LoadMatrix(matrix [][]Item) > 通过二维矩阵加载分布图 > - 通过该函数加载的分布图使用的矩阵是复制后的矩阵，因此无法直接通过刷新(Refresh)来更新分布关系 > - 需要通过直接刷新的方式请使用 LoadMatrixWithPos + *** + + #### func (*DistributionPattern) LoadMatrixWithPos(width int, matrix []Item) > 通过二维矩阵加载分布图 + *** + + #### func (*DistributionPattern) Refresh(pos int) > 刷新特定位置的分布关系 > - 由于 LoadMatrix 的矩阵是复制后的矩阵，所以任何外部的改动都不会影响到分布图的变化，在这种情况下，刷新将没有任何意义 > - 需要通过直接刷新的方式请使用 LoadMatrixWithPos 加载矩阵，或者通过 RefreshWithItem 函数进行刷新 + *** + + #### func (*DistributionPattern) RefreshWithItem(pos int, item Item) > 通过特定的成员刷新特定位置的分布关系 > - 如果矩阵通过 LoadMatrixWithPos 加载，将会重定向至 Refresh + *** + ### Link `STRUCT` ```go diff --git a/utils/geometry/matrix/README.md b/utils/geometry/matrix/README.md index 0981cdf..7ed208c 100644 --- a/utils/geometry/matrix/README.md +++ b/utils/geometry/matrix/README.md @@ -23,20 +23,21 @@ matrix 提供了一个简单的二维数组的实现 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Matrix](#matrix)|二维矩阵 +|`STRUCT`|[Matrix](#struct_Matrix)|二维矩阵 *** ## 详情信息 -#### func NewMatrix(width int, height int) *Matrix[T] +#### func NewMatrix\[T any\](width int, height int) *Matrix[T] > 生成特定宽高的二维矩阵 > - 虽然提供了通过x、y坐标的操作函数，但是建议无论如何使用pos进行处理 > - 该矩阵为XY，而非YX *** + ### Matrix `STRUCT` 二维矩阵 ```go @@ -46,52 +47,100 @@ type Matrix[T any] struct { m []T } ``` + + #### func (*Matrix) GetWidth() int > 获取二维矩阵宽度 + *** + + #### func (*Matrix) GetHeight() int > 获取二维矩阵高度 + *** + + #### func (*Matrix) GetWidth2Height() (width int, height int) > 获取二维矩阵的宽度和高度 + *** + + #### func (*Matrix) GetMatrix() [][]T > 获取二维矩阵 > - 通常建议使用 GetMatrixWithPos 进行处理这样将拥有更高的效率 + *** + + #### func (*Matrix) GetMatrixWithPos() []T > 获取顺序的矩阵 + *** + + #### func (*Matrix) Get(x int, y int) (value T) > 获取特定坐标的内容 + *** + + #### func (*Matrix) GetExist(x int, y int) (value T, exist bool) > 获取特定坐标的内容，如果不存在则返回 false + *** + + #### func (*Matrix) GetWithPos(pos int) (value T) > 获取特定坐标的内容 + *** + + #### func (*Matrix) Set(x int, y int, data T) > 设置特定坐标的内容 + *** + + #### func (*Matrix) SetWithPos(pos int, data T) > 设置特定坐标的内容 + *** + + #### func (*Matrix) Swap(x1 int, y1 int, x2 int, y2 int) > 交换两个位置的内容 + *** + + #### func (*Matrix) SwapWithPos(pos1 int, pos2 int) > 交换两个位置的内容 + *** + + #### func (*Matrix) TrySwap(x1 int, y1 int, x2 int, y2 int, expressionHandle func (matrix *Matrix[T]) bool) > 尝试交换两个位置的内容，交换后不满足表达式时进行撤销 + *** + + #### func (*Matrix) TrySwapWithPos(pos1 int, pos2 int, expressionHandle func (matrix *Matrix[T]) bool) > 尝试交换两个位置的内容，交换后不满足表达式时进行撤销 + *** + + #### func (*Matrix) FillFull(generateHandle func (x int) T) > 根据提供的生成器填充整个矩阵 + *** + + #### func (*Matrix) FillFullWithPos(generateHandle func (pos int) T) > 根据提供的生成器填充整个矩阵 + *** diff --git a/utils/geometry/navmesh/README.md b/utils/geometry/navmesh/README.md index 0374f76..301e2ed 100644 --- a/utils/geometry/navmesh/README.md +++ b/utils/geometry/navmesh/README.md @@ -26,14 +26,14 @@ navmesh 提供了用于导航网格处理的函数和数据结构。导航网格 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[NavMesh](#navmesh)|暂无描述... +|`STRUCT`|[NavMesh](#struct_NavMesh)|暂无描述... *** ## 详情信息 -#### func NewNavMesh(shapes []geometry.Shape[V], meshShrinkAmount V) *NavMesh[V] +#### func NewNavMesh\[V generic.SignedNumber\](shapes []geometry.Shape[V], meshShrinkAmount V) *NavMesh[V] > 创建一个新的导航网格，并返回一个指向该导航网格的指针。 > @@ -54,6 +54,7 @@ navmesh 提供了用于导航网格处理的函数和数据结构。导航网格 > - 确保 NavMesh 计算精度的情况下，V 建议使用 float64 类型 *** + ### NavMesh `STRUCT` ```go @@ -62,9 +63,14 @@ type NavMesh[V generic.SignedNumber] struct { meshShrinkAmount V } ``` + + #### func (*NavMesh) Neighbours(node *shape[V]) []*shape[V] > 实现 astar.Graph 的接口，用于向 A* 算法提供相邻图形 + *** + + #### func (*NavMesh) Find(point geometry.Point[V], maxDistance V) (distance V, findPoint geometry.Point[V], findShape geometry.Shape[V]) > 用于在 NavMesh 中查找离给定点最近的形状，并返回距离、找到的点和找到的形状。 > @@ -82,7 +88,10 @@ type NavMesh[V generic.SignedNumber] struct { > - 如果给定点不在任何形状内部或者形状的边上，将计算给定点到每个形状的距离，并找到最近的形状和对应的点。 > - 距离的计算采用几何学中的投影点到形状的距离。 > - 函数返回离给定点最近的形状的距离、找到的点和找到的形状。 + *** + + #### func (*NavMesh) FindPath(start geometry.Point[V], end geometry.Point[V]) (result []geometry.Point[V]) > 函数用于在 NavMesh 中查找从起点到终点的路径，并返回路径上的点序列。 > @@ -98,7 +107,9 @@ type NavMesh[V generic.SignedNumber] struct { > - 如果起点或终点不在任何形状内部，且 NavMesh 的 meshShrinkAmount 大于0，则会考虑缩小的形状。 > - 使用 A* 算法在 NavMesh 上搜索从起点形状到终点形状的最短路径。 > - 使用漏斗算法对路径进行优化，以得到最终的路径点序列。 -示例代码： + +**示例代码：** + ```go func ExampleNavMesh_FindPath() { diff --git a/utils/hub/README.md b/utils/hub/README.md index 3bb9577..a89558d 100644 --- a/utils/hub/README.md +++ b/utils/hub/README.md @@ -23,18 +23,19 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[ObjectPool](#objectpool)|基于 sync.Pool 实现的线程安全的对象池 +|`STRUCT`|[ObjectPool](#struct_ObjectPool)|基于 sync.Pool 实现的线程安全的对象池 *** ## 详情信息 -#### func NewObjectPool(generator func () *T, releaser func (data *T)) *ObjectPool[*T] +#### func NewObjectPool\[T any\](generator func () *T, releaser func (data *T)) *ObjectPool[*T] > 创建一个 ObjectPool -示例代码： +**示例代码：** + ```go func ExampleNewObjectPool() { @@ -89,6 +90,7 @@ func TestNewObjectPool(t *testing.T) { *** + ### ObjectPool `STRUCT` 基于 sync.Pool 实现的线程安全的对象池 - 一些高频临时生成使用的对象可以通过 ObjectPool 进行管理，例如属性计算等 @@ -98,8 +100,11 @@ type ObjectPool[T any] struct { releaser func(data T) } ``` + + #### func (*ObjectPool) Get() T > 获取一个对象 +
查看 / 收起单元测试 @@ -135,8 +140,11 @@ func TestObjectPool_Get(t *testing.T) { *** + + #### func (*ObjectPool) Release(data T) > 将使用完成的对象放回缓冲区 +
查看 / 收起单元测试 diff --git a/utils/huge/README.md b/utils/huge/README.md index 54c94c7..627fcaa 100644 --- a/utils/huge/README.md +++ b/utils/huge/README.md @@ -18,362 +18,1453 @@ |:--|:-- |[NewFloat](#NewFloat)|创建一个 Float |[NewFloatByString](#NewFloatByString)|通过字符串创建一个 Float -|[NewInt](#NewInt)|创建一个 Int -|[NewIntByString](#NewIntByString)|通过字符串创建一个 Int +|[NewInt](#NewInt)|创建一个 Int 对象，该对象的值为 x > 类型定义 |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Float](#float)|暂无描述... -|`STRUCT`|[Int](#int)|暂无描述... +|`STRUCT`|[Float](#struct_Float)|暂无描述... +|`STRUCT`|[Int](#struct_Int)|暂无描述...
*** ## 详情信息 -#### func NewFloat(x T) *Float +#### func NewFloat\[T generic.Number\](x T) *Float > 创建一个 Float *** -#### func NewFloatByString(i string) *Float +#### func NewFloatByString(i string) *Float > 通过字符串创建一个 Float > - 如果字符串不是一个合法的数字，则返回 0 *** -#### func NewInt(x T) *Int +#### func NewInt\[T generic.Basic\](x T) *Int -> 创建一个 Int - -*** -#### func NewIntByString(i string) *Int - -> 通过字符串创建一个 Int -> - 如果字符串不是一个合法的数字，则返回 0 +> 创建一个 Int 对象，该对象的值为 x + +**示例代码：** + +该案例展示了 NewInt 对各种基本类型的支持及用法 + + +```go + +func ExampleNewInt() { + fmt.Println(huge.NewInt("12345678900000000")) + fmt.Println(huge.NewInt(1234567890)) + fmt.Println(huge.NewInt(true)) + fmt.Println(huge.NewInt(123.123)) + fmt.Println(huge.NewInt(byte(1))) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestNewInt(t *testing.T) { + var cases = []struct { + name string + nil bool + in int64 + mul int64 + want string + }{{name: "TestNewIntNegative", in: -1, want: "-1"}, {name: "TestNewIntZero", in: 0, want: "0"}, {name: "TestNewIntPositive", in: 1, want: "1"}, {name: "TestNewIntMax", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestNewIntMin", in: -9223372036854775808, want: "-9223372036854775808"}, {name: "TestNewIntMulNegative", in: -9223372036854775808, mul: 10000000, want: "-92233720368547758080000000"}, {name: "TestNewIntMulPositive", in: 9223372036854775807, mul: 10000000, want: "92233720368547758070000000"}, {name: "TestNewIntNil", nil: true, want: "0"}, {name: "TestNewIntNilMul", nil: true, mul: 10000000, want: "0"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var got *huge.Int + switch { + case c.nil: + if c.mul > 0 { + got = huge.NewInt(0).MulInt64(c.mul) + } + case c.mul == 0: + got = huge.NewInt(c.in) + default: + got = huge.NewInt(c.in).MulInt64(c.mul) + } + if s := got.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, got.String()) + } else { + t.Log(s) + } + }) + } + t.Run("TestNewIntFromString", func(t *testing.T) { + if got := huge.NewInt("1234567890123456789012345678901234567890"); got.String() != "1234567890123456789012345678901234567890" { + t.Fatalf("want: %s, got: %s", "1234567890123456789012345678901234567890", got.String()) + } + }) + t.Run("TestNewIntFromInt", func(t *testing.T) { + if got := huge.NewInt(1234567890); got.String() != "1234567890" { + t.Fatalf("want: %s, got: %s", "1234567890", got.String()) + } + }) + t.Run("TestNewIntFromBool", func(t *testing.T) { + if got := huge.NewInt(true); got.String() != "1" { + t.Fatalf("want: %s, got: %s", "1", got.String()) + } + }) + t.Run("TestNewIntFromFloat", func(t *testing.T) { + if got := huge.NewInt(1234567890.1234567890); got.String() != "1234567890" { + t.Fatalf("want: %s, got: %s", "1234567890", got.String()) + } + }) +} + +``` + + +
+ *** + ### Float `STRUCT` ```go type Float big.Float ``` + + #### func (*Float) Copy() *Float + *** + + #### func (*Float) Set(i *Float) *Float + *** + + #### func (*Float) IsZero() bool + *** + + #### func (*Float) ToBigFloat() *big.Float + *** + + #### func (*Float) Cmp(i *Float) int > 比较，当 slf > i 时返回 1，当 slf < i 时返回 -1，当 slf == i 时返回 0 + *** + + #### func (*Float) GreaterThan(i *Float) bool > 大于 + *** + + #### func (*Float) GreaterThanOrEqualTo(i *Float) bool > 大于或等于 + *** + + #### func (*Float) LessThan(i *Float) bool > 小于 + *** + + #### func (*Float) LessThanOrEqualTo(i *Float) bool > 小于或等于 + *** + + #### func (*Float) EqualTo(i *Float) bool > 等于 + *** + + #### func (*Float) Float64() float64 + *** + + #### func (*Float) String() string + *** + + #### func (*Float) Add(i *Float) *Float + *** + + #### func (*Float) Sub(i *Float) *Float + *** + + #### func (*Float) Mul(i *Float) *Float + *** + + #### func (*Float) Div(i *Float) *Float + *** + + #### func (*Float) Sqrt() *Float > 平方根 + *** + + #### func (*Float) Abs() *Float > 返回数字的绝对值 + *** + + #### func (*Float) Sign() int > 返回数字的符号 > - 1：正数 > - 0：零 > - -1：负数 + *** + + #### func (*Float) IsPositive() bool > 是否为正数 + *** + + #### func (*Float) IsNegative() bool > 是否为负数 + *** + ### Int `STRUCT` ```go type Int big.Int ``` + + #### func (*Int) Copy() *Int +> 拷贝当前 Int 对象 + +**示例代码：** + +```go + +func ExampleInt_Copy() { + var a = huge.NewInt(1234567890) + var b = a.Copy().SetInt64(9876543210) + fmt.Println(a) + fmt.Println(b) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestInt_Copy(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{{name: "TestIntCopyNegative", in: -1, want: "-1"}, {name: "TestIntCopyZero", in: 0, want: "0"}, {name: "TestIntCopyPositive", in: 1, want: "1"}, {name: "TestIntCopyMax", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntCopyMin", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in = huge.NewInt(c.in) + var got = in.Copy() + if in.Int64() != c.in { + t.Fatalf("want: %d, got: %d", c.in, in.Int64()) + } + if s := got.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, got.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) Set(i *Int) *Int +> 设置当前 Int 对象的值为 i + +**示例代码：** + +```go + +func ExampleInt_Set() { + var a = huge.NewInt(1234567890) + var b = huge.NewInt(9876543210) + fmt.Println(a) + a.Set(b) + fmt.Println(a) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestInt_Set(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{{name: "TestIntSetNegative", in: -1, want: "-1"}, {name: "TestIntSetZero", in: 0, want: "0"}, {name: "TestIntSetPositive", in: 1, want: "1"}, {name: "TestIntSetMax", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntSetMin", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.Set(huge.NewInt(c.in)) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + +#### func (*Int) SetString(i string) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetString(t *testing.T) { + var cases = []struct { + name string + in string + want string + }{{name: "TestIntSetStringNegative", in: "-1", want: "-1"}, {name: "TestIntSetStringZero", in: "0", want: "0"}, {name: "TestIntSetStringPositive", in: "1", want: "1"}, {name: "TestIntSetStringMax", in: "9223372036854775807", want: "9223372036854775807"}, {name: "TestIntSetStringMin", in: "-9223372036854775808", want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetString(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + +*** + + #### func (*Int) SetInt(i int) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetInt(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{{name: "TestIntSetIntNegative", in: -1, want: "-1"}, {name: "TestIntSetIntZero", in: 0, want: "0"}, {name: "TestIntSetIntPositive", in: 1, want: "1"}, {name: "TestIntSetIntMax", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntSetIntMin", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetInt8(i int8) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetInt8(t *testing.T) { + var cases = []struct { + name string + in int8 + want string + }{{name: "TestIntSetInt8Negative", in: -1, want: "-1"}, {name: "TestIntSetInt8Zero", in: 0, want: "0"}, {name: "TestIntSetInt8Positive", in: 1, want: "1"}, {name: "TestIntSetInt8Max", in: 127, want: "127"}, {name: "TestIntSetInt8Min", in: -128, want: "-128"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt8(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetInt16(i int16) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetInt16(t *testing.T) { + var cases = []struct { + name string + in int16 + want string + }{{name: "TestIntSetInt16Negative", in: -1, want: "-1"}, {name: "TestIntSetInt16Zero", in: 0, want: "0"}, {name: "TestIntSetInt16Positive", in: 1, want: "1"}, {name: "TestIntSetInt16Max", in: 32767, want: "32767"}, {name: "TestIntSetInt16Min", in: -32768, want: "-32768"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt16(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetInt32(i int32) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetInt32(t *testing.T) { + var cases = []struct { + name string + in int32 + want string + }{{name: "TestIntSetInt32Negative", in: -1, want: "-1"}, {name: "TestIntSetInt32Zero", in: 0, want: "0"}, {name: "TestIntSetInt32Positive", in: 1, want: "1"}, {name: "TestIntSetInt32Max", in: 2147483647, want: "2147483647"}, {name: "TestIntSetInt32Min", in: -2147483648, want: "-2147483648"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetInt64(i int64) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetInt64(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{{name: "TestIntSetInt64Negative", in: -1, want: "-1"}, {name: "TestIntSetInt64Zero", in: 0, want: "0"}, {name: "TestIntSetInt64Positive", in: 1, want: "1"}, {name: "TestIntSetInt64Max", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntSetInt64Min", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetUint(i uint) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetUint(t *testing.T) { + var cases = []struct { + name string + in uint64 + want string + }{{name: "TestIntSetUintNegative", in: 0, want: "0"}, {name: "TestIntSetUintZero", in: 0, want: "0"}, {name: "TestIntSetUintPositive", in: 1, want: "1"}, {name: "TestIntSetUintMax", in: 18446744073709551615, want: "18446744073709551615"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetUint8(i uint8) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetUint8(t *testing.T) { + var cases = []struct { + name string + in uint8 + want string + }{{name: "TestIntSetUint8Negative", in: 0, want: "0"}, {name: "TestIntSetUint8Zero", in: 0, want: "0"}, {name: "TestIntSetUint8Positive", in: 1, want: "1"}, {name: "TestIntSetUint8Max", in: 255, want: "255"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint8(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetUint16(i uint16) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetUint16(t *testing.T) { + var cases = []struct { + name string + in uint16 + want string + }{{name: "TestIntSetUint16Negative", in: 0, want: "0"}, {name: "TestIntSetUint16Zero", in: 0, want: "0"}, {name: "TestIntSetUint16Positive", in: 1, want: "1"}, {name: "TestIntSetUint16Max", in: 65535, want: "65535"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint16(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetUint32(i uint32) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetUint32(t *testing.T) { + var cases = []struct { + name string + in uint32 + want string + }{{name: "TestIntSetUint32Negative", in: 0, want: "0"}, {name: "TestIntSetUint32Zero", in: 0, want: "0"}, {name: "TestIntSetUint32Positive", in: 1, want: "1"}, {name: "TestIntSetUint32Max", in: 4294967295, want: "4294967295"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) SetUint64(i uint64) *Int +> 设置当前 Int 对象的值为 i + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetUint64(t *testing.T) { + var cases = []struct { + name string + in uint64 + want string + }{{name: "TestIntSetUint64Negative", in: 0, want: "0"}, {name: "TestIntSetUint64Zero", in: 0, want: "0"}, {name: "TestIntSetUint64Positive", in: 1, want: "1"}, {name: "TestIntSetUint64Max", in: 18446744073709551615, want: "18446744073709551615"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + *** + + +#### func (*Int) SetFloat32(i float32) *Int +> 设置当前 Int 对象的值为 i 向下取整后的值 + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetFloat32(t *testing.T) { + var cases = []struct { + name string + in float32 + want string + }{{name: "TestIntSetFloat32Negative", in: -1.1, want: "-1"}, {name: "TestIntSetFloat32Zero", in: 0, want: "0"}, {name: "TestIntSetFloat32Positive", in: 1.1, want: "1"}, {name: "TestIntSetFloat32Max", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntSetFloat32Min", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetFloat32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Int) SetFloat64(i float64) *Int +> 设置当前 Int 对象的值为 i 向下取整后的值 + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetFloat64(t *testing.T) { + var cases = []struct { + name string + in float64 + want string + }{{name: "TestIntSetFloat64Negative", in: -1.1, want: "-1"}, {name: "TestIntSetFloat64Zero", in: 0, want: "0"}, {name: "TestIntSetFloat64Positive", in: 1.1, want: "1"}, {name: "TestIntSetFloat64Max", in: 9223372036854775807, want: "9223372036854775807"}, {name: "TestIntSetFloat64Min", in: -9223372036854775808, want: "-9223372036854775808"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetFloat64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + +*** + + +#### func (*Int) SetBool(i bool) *Int +> 设置当前 Int 对象的值为 i，当 i 为 true 时，值为 1，当 i 为 false 时，值为 0 + +
+查看 / 收起单元测试 + + +```go + +func TestInt_SetBool(t *testing.T) { + var cases = []struct { + name string + in bool + want string + }{{name: "TestIntSetBoolFalse", in: false, want: "0"}, {name: "TestIntSetBoolTrue", in: true, want: "1"}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetBool(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +``` + + +
+ + +*** + + #### func (*Int) IsZero() bool +> 判断当前 Int 对象的值是否为 0 + +
+查看 / 收起单元测试 + + +```go + +func TestInt_IsZero(t *testing.T) { + var cases = []struct { + name string + in int64 + want bool + }{{name: "TestIntIsZeroNegative", in: -1, want: false}, {name: "TestIntIsZeroZero", in: 0, want: true}, {name: "TestIntIsZeroPositive", in: 1, want: false}, {name: "TestIntIsZeroMax", in: 9223372036854775807, want: false}, {name: "TestIntIsZeroMin", in: -9223372036854775808, want: false}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := huge.NewInt(c.in).IsZero(); got != c.want { + t.Fatalf("want: %t, got: %t", c.want, got) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) ToBigint() *big.Int +> 转换为 *big.Int + +
+查看 / 收起单元测试 + + +```go + +func TestInt_ToBigint(t *testing.T) { + var cases = []struct { + name string + in int64 + want *big.Int + }{{name: "TestIntToBigintNegative", in: -1, want: big.NewInt(-1)}, {name: "TestIntToBigintZero", in: 0, want: big.NewInt(0)}, {name: "TestIntToBigintPositive", in: 1, want: big.NewInt(1)}, {name: "TestIntToBigintMax", in: 9223372036854775807, want: big.NewInt(9223372036854775807)}, {name: "TestIntToBigintMin", in: -9223372036854775808, want: big.NewInt(-9223372036854775808)}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := huge.NewInt(c.in).ToBigint(); got.Cmp(c.want) != 0 { + t.Fatalf("want: %s, got: %s", c.want.String(), got.String()) + } + }) + } +} + +``` + + +
+ + *** + + #### func (*Int) Cmp(i *Int) int > 比较，当 slf > i 时返回 1，当 slf < i 时返回 -1，当 slf == i 时返回 0 + *** + + #### func (*Int) GreaterThan(i *Int) bool -> 大于 +> 检查 slf 是否大于 i + *** + + #### func (*Int) GreaterThanOrEqualTo(i *Int) bool -> 大于或等于 +> 检查 slf 是否大于或等于 i + *** + + #### func (*Int) LessThan(i *Int) bool -> 小于 +> 检查 slf 是否小于 i + *** + + #### func (*Int) LessThanOrEqualTo(i *Int) bool -> 小于或等于 +> 检查 slf 是否小于或等于 i + *** + + #### func (*Int) EqualTo(i *Int) bool -> 等于 +> 检查 slf 是否等于 i + *** + + #### func (*Int) Int64() int64 +> 转换为 int64 类型进行返回 + *** + + #### func (*Int) String() string +> 转换为 string 类型进行返回 + *** + + #### func (*Int) Add(i *Int) *Int +> 使用 i 对 slf 进行加法运算，slf 的值会变为运算后的值。返回 slf + *** + + #### func (*Int) AddInt(i int) *Int + *** + + #### func (*Int) AddInt8(i int8) *Int + *** + + #### func (*Int) AddInt16(i int16) *Int + *** + + #### func (*Int) AddInt32(i int32) *Int + *** + + #### func (*Int) AddInt64(i int64) *Int + *** + + #### func (*Int) AddUint(i uint) *Int + *** + + #### func (*Int) AddUint8(i uint8) *Int + *** + + #### func (*Int) AddUint16(i uint16) *Int + *** + + #### func (*Int) AddUint32(i uint32) *Int + *** + + #### func (*Int) AddUint64(i uint64) *Int + *** + + #### func (*Int) Mul(i *Int) *Int + *** + + #### func (*Int) MulInt(i int) *Int + *** + + #### func (*Int) MulInt8(i int8) *Int + *** + + #### func (*Int) MulInt16(i int16) *Int + *** + + #### func (*Int) MulInt32(i int32) *Int + *** + + #### func (*Int) MulInt64(i int64) *Int + *** + + #### func (*Int) MulUint(i uint) *Int + *** + + #### func (*Int) MulUint8(i uint8) *Int + *** + + #### func (*Int) MulUint16(i uint16) *Int + *** + + #### func (*Int) MulUint32(i uint32) *Int + *** + + #### func (*Int) MulUint64(i uint64) *Int + *** + + #### func (*Int) Sub(i *Int) *Int + *** + + #### func (*Int) SubInt(i int) *Int + *** + + #### func (*Int) SubInt8(i int8) *Int + *** + + #### func (*Int) SubInt16(i int16) *Int + *** + + #### func (*Int) SubInt32(i int32) *Int + *** + + #### func (*Int) SubInt64(i int64) *Int + *** + + #### func (*Int) SubUint(i uint) *Int + *** + + #### func (*Int) SubUint8(i uint8) *Int + *** + + #### func (*Int) SubUint16(i uint16) *Int + *** + + #### func (*Int) SubUint32(i uint32) *Int + *** + + #### func (*Int) SubUint64(i uint64) *Int + *** + + #### func (*Int) Div(i *Int) *Int + *** + + #### func (*Int) DivInt(i int) *Int + *** + + #### func (*Int) DivInt8(i int8) *Int + *** + + #### func (*Int) DivInt16(i int16) *Int + *** + + #### func (*Int) DivInt32(i int32) *Int + *** + + #### func (*Int) DivInt64(i int64) *Int + *** + + #### func (*Int) DivUint(i uint) *Int + *** + + #### func (*Int) DivUint8(i uint8) *Int + *** + + #### func (*Int) DivUint16(i uint16) *Int + *** + + #### func (*Int) DivUint32(i uint32) *Int + *** + + #### func (*Int) DivUint64(i uint64) *Int + *** + + #### func (*Int) Mod(i *Int) *Int + *** + + #### func (*Int) ModInt(i int) *Int + *** + + #### func (*Int) ModInt8(i int8) *Int + *** + + #### func (*Int) ModInt16(i int16) *Int + *** + + #### func (*Int) ModInt32(i int32) *Int + *** + + #### func (*Int) ModInt64(i int64) *Int + *** + + #### func (*Int) ModUint(i uint) *Int + *** + + #### func (*Int) ModUint8(i uint8) *Int + *** + + #### func (*Int) ModUint16(i uint16) *Int + *** + + #### func (*Int) ModUint32(i uint32) *Int + *** + + #### func (*Int) ModUint64(i uint64) *Int + *** + + #### func (*Int) Pow(i *Int) *Int + *** + + #### func (*Int) PowInt(i int) *Int + *** + + #### func (*Int) PowInt8(i int8) *Int + *** + + #### func (*Int) PowInt16(i int16) *Int + *** + + #### func (*Int) PowInt32(i int32) *Int + *** + + #### func (*Int) PowInt64(i int64) *Int + *** + + #### func (*Int) PowUint(i uint) *Int + *** + + #### func (*Int) PowUint8(i uint8) *Int + *** + + #### func (*Int) PowUint16(i uint16) *Int + *** + + #### func (*Int) PowUint32(i uint32) *Int + *** + + #### func (*Int) PowUint64(i uint64) *Int + *** + + #### func (*Int) Lsh(i int) *Int > 左移 + *** + + #### func (*Int) Rsh(i int) *Int > 右移 + *** + + #### func (*Int) And(i *Int) *Int > 与 + *** + + #### func (*Int) AndNot(i *Int) *Int > 与非 + *** + + #### func (*Int) Or(i *Int) *Int > 或 + *** + + #### func (*Int) Xor(i *Int) *Int > 异或 + *** + + #### func (*Int) Not() *Int > 非 + *** + + #### func (*Int) Sqrt() *Int > 平方根 + *** + + #### func (*Int) GCD(i *Int) *Int > 最大公约数 + *** + + #### func (*Int) LCM(i *Int) *Int > 最小公倍数 + *** + + #### func (*Int) ModInverse(i *Int) *Int > 模反元素 + *** + + #### func (*Int) ModSqrt(i *Int) *Int > 模平方根 + *** + + #### func (*Int) BitLen() int > 二进制长度 + *** + + #### func (*Int) Bit(i int) uint > 二进制位 + *** + + #### func (*Int) SetBit(i int, v uint) *Int > 设置二进制位 + *** + + #### func (*Int) Neg() *Int > 返回数字的相反数 + *** + + #### func (*Int) Abs() *Int > 返回数字的绝对值 + *** + + #### func (*Int) Sign() int > 返回数字的符号 > - 1：正数 > - 0：零 > - -1：负数 + *** + + #### func (*Int) IsPositive() bool > 是否为正数 + *** + + #### func (*Int) IsNegative() bool > 是否为负数 + *** + + #### func (*Int) IsEven() bool > 是否为偶数 + *** + + #### func (*Int) IsOdd() bool > 是否为奇数 + *** + + #### func (*Int) ProportionalCalc(proportional *Int, formula func (v *Int) *Int) *Int > 比例计算，该函数会再 formula 返回值的基础上除以 proportional > - formula 为计算公式，该公式的参数为调用该函数的 Int 的拷贝 + *** diff --git a/utils/huge/int.go b/utils/huge/int.go index 68db831..44bc742 100644 --- a/utils/huge/int.go +++ b/utils/huge/int.go @@ -17,73 +17,135 @@ var ( type Int big.Int -// NewInt 创建一个 Int -func NewInt[T generic.Number](x T) *Int { - return (*Int)(big.NewInt(int64(x))) -} - -// NewIntByString 通过字符串创建一个 Int -// - 如果字符串不是一个合法的数字，则返回 0 -func NewIntByString(i string) *Int { - v, suc := new(big.Int).SetString(i, 10) - if !suc { - return IntZero.Copy() +// NewInt 创建一个 Int 对象，该对象的值为 x +func NewInt[T generic.Basic](x T) *Int { + var xa any = x + switch x := xa.(type) { + case int: + return (*Int)(big.NewInt(int64(x))) + case int8: + return (*Int)(big.NewInt(int64(x))) + case int16: + return (*Int)(big.NewInt(int64(x))) + case int32: + return (*Int)(big.NewInt(int64(x))) + case int64: + return (*Int)(big.NewInt(x)) + case uint: + return (*Int)(big.NewInt(int64(x))) + case uint8: + return (*Int)(big.NewInt(int64(x))) + case uint16: + return (*Int)(big.NewInt(int64(x))) + case uint32: + return (*Int)(big.NewInt(int64(x))) + case uint64: + return (*Int)(big.NewInt(int64(x))) + case string: + si, suc := new(big.Int).SetString(x, 10) + if !suc { + return (*Int)(big.NewInt(0)) + } + return (*Int)(si) + case bool: + if x { + return (*Int)(big.NewInt(1)) + } + return (*Int)(big.NewInt(0)) + case float32: + return (*Int)(big.NewInt(int64(x))) + case float64: + return (*Int)(big.NewInt(int64(x))) } - return (*Int)(v) + return (*Int)(big.NewInt(0)) } +// applyIntOperation 应用一个 Int 操作 func applyIntOperation[T generic.Number](v *Int, i T, op func(*big.Int, *big.Int) *big.Int) *Int { return (*Int)(op(v.ToBigint(), NewInt(i).ToBigint())) } +// Copy 拷贝当前 Int 对象 func (slf *Int) Copy() *Int { return (*Int)(new(big.Int).Set(slf.ToBigint())) } +// Set 设置当前 Int 对象的值为 i func (slf *Int) Set(i *Int) *Int { return (*Int)(slf.ToBigint().Set(i.ToBigint())) } +// SetString 设置当前 Int 对象的值为 i +func (slf *Int) SetString(i string) *Int { + return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) +} + +// SetInt 设置当前 Int 对象的值为 i func (slf *Int) SetInt(i int) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetInt8 设置当前 Int 对象的值为 i func (slf *Int) SetInt8(i int8) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetInt16 设置当前 Int 对象的值为 i func (slf *Int) SetInt16(i int16) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetInt32 设置当前 Int 对象的值为 i func (slf *Int) SetInt32(i int32) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetInt64 设置当前 Int 对象的值为 i func (slf *Int) SetInt64(i int64) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetUint 设置当前 Int 对象的值为 i func (slf *Int) SetUint(i uint) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetUint8 设置当前 Int 对象的值为 i func (slf *Int) SetUint8(i uint8) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetUint16 设置当前 Int 对象的值为 i func (slf *Int) SetUint16(i uint16) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetUint32 设置当前 Int 对象的值为 i func (slf *Int) SetUint32(i uint32) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetUint64 设置当前 Int 对象的值为 i func (slf *Int) SetUint64(i uint64) *Int { return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) } +// SetFloat32 设置当前 Int 对象的值为 i 向下取整后的值 +func (slf *Int) SetFloat32(i float32) *Int { + return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) +} + +// SetFloat64 设置当前 Int 对象的值为 i 向下取整后的值 +func (slf *Int) SetFloat64(i float64) *Int { + return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) +} + +// SetBool 设置当前 Int 对象的值为 i，当 i 为 true 时，值为 1，当 i 为 false 时，值为 0 +func (slf *Int) SetBool(i bool) *Int { + return (*Int)(slf.ToBigint().Set((*big.Int)(NewInt(i)))) +} + +// IsZero 判断当前 Int 对象的值是否为 0 func (slf *Int) IsZero() bool { if slf == nil || slf.EqualTo(IntZero) { return true @@ -91,7 +153,11 @@ func (slf *Int) IsZero() bool { return false } +// ToBigint 转换为 *big.Int func (slf *Int) ToBigint() *big.Int { + if slf == nil { + return big.NewInt(0) + } return (*big.Int)(slf) } @@ -100,39 +166,45 @@ func (slf *Int) Cmp(i *Int) int { return slf.ToBigint().Cmp(i.ToBigint()) } -// GreaterThan 大于 +// GreaterThan 检查 slf 是否大于 i func (slf *Int) GreaterThan(i *Int) bool { return slf.Cmp(i) > 0 } -// GreaterThanOrEqualTo 大于或等于 +// GreaterThanOrEqualTo 检查 slf 是否大于或等于 i func (slf *Int) GreaterThanOrEqualTo(i *Int) bool { return slf.Cmp(i) >= 0 } -// LessThan 小于 +// LessThan 检查 slf 是否小于 i func (slf *Int) LessThan(i *Int) bool { return slf.Cmp(i) < 0 } -// LessThanOrEqualTo 小于或等于 +// LessThanOrEqualTo 检查 slf 是否小于或等于 i func (slf *Int) LessThanOrEqualTo(i *Int) bool { return slf.Cmp(i) <= 0 } -// EqualTo 等于 +// EqualTo 检查 slf 是否等于 i func (slf *Int) EqualTo(i *Int) bool { return slf.Cmp(i) == 0 } +// Int64 转换为 int64 类型进行返回 func (slf *Int) Int64() int64 { return slf.ToBigint().Int64() } +// String 转换为 string 类型进行返回 func (slf *Int) String() string { + if slf == nil { + return "0" + } return slf.ToBigint().String() } +// Add 使用 i 对 slf 进行加法运算，slf 的值会变为运算后的值。返回 slf func (slf *Int) Add(i *Int) *Int { x := slf.ToBigint() return (*Int)(x.Add(x, i.ToBigint())) diff --git a/utils/huge/int_example_test.go b/utils/huge/int_example_test.go new file mode 100644 index 0000000..c4ce3f0 --- /dev/null +++ b/utils/huge/int_example_test.go @@ -0,0 +1,42 @@ +package huge_test + +import ( + "fmt" + "github.com/kercylan98/minotaur/utils/huge" +) + +// 该案例展示了 NewInt 对各种基本类型的支持及用法 +func ExampleNewInt() { + fmt.Println(huge.NewInt("12345678900000000")) + fmt.Println(huge.NewInt(1234567890)) + fmt.Println(huge.NewInt(true)) + fmt.Println(huge.NewInt(123.123)) + fmt.Println(huge.NewInt(byte(1))) + // Output: + // 12345678900000000 + // 1234567890 + // 1 + // 123 + // 1 +} + +func ExampleInt_Copy() { + var a = huge.NewInt(1234567890) + var b = a.Copy().SetInt64(9876543210) + fmt.Println(a) + fmt.Println(b) + // Output: + // 1234567890 + // 9876543210 +} + +func ExampleInt_Set() { + var a = huge.NewInt(1234567890) + var b = huge.NewInt(9876543210) + fmt.Println(a) + a.Set(b) + fmt.Println(a) + // Output: + // 1234567890 + // 9876543210 +} diff --git a/utils/huge/int_test.go b/utils/huge/int_test.go new file mode 100644 index 0000000..851ac30 --- /dev/null +++ b/utils/huge/int_test.go @@ -0,0 +1,525 @@ +package huge_test + +import ( + "github.com/kercylan98/minotaur/utils/huge" + "math/big" + "testing" +) + +func TestNewInt(t *testing.T) { + var cases = []struct { + name string + nil bool + in int64 + mul int64 + want string + }{ + {name: "TestNewIntNegative", in: -1, want: "-1"}, + {name: "TestNewIntZero", in: 0, want: "0"}, + {name: "TestNewIntPositive", in: 1, want: "1"}, + {name: "TestNewIntMax", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestNewIntMin", in: -9223372036854775808, want: "-9223372036854775808"}, + {name: "TestNewIntMulNegative", in: -9223372036854775808, mul: 10000000, want: "-92233720368547758080000000"}, + {name: "TestNewIntMulPositive", in: 9223372036854775807, mul: 10000000, want: "92233720368547758070000000"}, + {name: "TestNewIntNil", nil: true, want: "0"}, + {name: "TestNewIntNilMul", nil: true, mul: 10000000, want: "0"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var got *huge.Int + switch { + case c.nil: + if c.mul > 0 { + got = huge.NewInt(0).MulInt64(c.mul) + } + case c.mul == 0: + got = huge.NewInt(c.in) + default: + got = huge.NewInt(c.in).MulInt64(c.mul) + } + if s := got.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, got.String()) + } else { + t.Log(s) + } + }) + } + + // other + t.Run("TestNewIntFromString", func(t *testing.T) { + if got := huge.NewInt("1234567890123456789012345678901234567890"); got.String() != "1234567890123456789012345678901234567890" { + t.Fatalf("want: %s, got: %s", "1234567890123456789012345678901234567890", got.String()) + } + }) + t.Run("TestNewIntFromInt", func(t *testing.T) { + if got := huge.NewInt(1234567890); got.String() != "1234567890" { + t.Fatalf("want: %s, got: %s", "1234567890", got.String()) + } + }) + t.Run("TestNewIntFromBool", func(t *testing.T) { + if got := huge.NewInt(true); got.String() != "1" { + t.Fatalf("want: %s, got: %s", "1", got.String()) + } + }) + t.Run("TestNewIntFromFloat", func(t *testing.T) { + if got := huge.NewInt(1234567890.1234567890); got.String() != "1234567890" { + t.Fatalf("want: %s, got: %s", "1234567890", got.String()) + } + }) +} + +func TestInt_Copy(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{ + {name: "TestIntCopyNegative", in: -1, want: "-1"}, + {name: "TestIntCopyZero", in: 0, want: "0"}, + {name: "TestIntCopyPositive", in: 1, want: "1"}, + {name: "TestIntCopyMax", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntCopyMin", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in = huge.NewInt(c.in) + var got = in.Copy() + if in.Int64() != c.in { + t.Fatalf("want: %d, got: %d", c.in, in.Int64()) + } + if s := got.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, got.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_Set(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{ + {name: "TestIntSetNegative", in: -1, want: "-1"}, + {name: "TestIntSetZero", in: 0, want: "0"}, + {name: "TestIntSetPositive", in: 1, want: "1"}, + {name: "TestIntSetMax", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntSetMin", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.Set(huge.NewInt(c.in)) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetString(t *testing.T) { + var cases = []struct { + name string + in string + want string + }{ + {name: "TestIntSetStringNegative", in: "-1", want: "-1"}, + {name: "TestIntSetStringZero", in: "0", want: "0"}, + {name: "TestIntSetStringPositive", in: "1", want: "1"}, + {name: "TestIntSetStringMax", in: "9223372036854775807", want: "9223372036854775807"}, + {name: "TestIntSetStringMin", in: "-9223372036854775808", want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetString(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetInt(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{ + {name: "TestIntSetIntNegative", in: -1, want: "-1"}, + {name: "TestIntSetIntZero", in: 0, want: "0"}, + {name: "TestIntSetIntPositive", in: 1, want: "1"}, + {name: "TestIntSetIntMax", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntSetIntMin", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetInt8(t *testing.T) { + var cases = []struct { + name string + in int8 + want string + }{ + {name: "TestIntSetInt8Negative", in: -1, want: "-1"}, + {name: "TestIntSetInt8Zero", in: 0, want: "0"}, + {name: "TestIntSetInt8Positive", in: 1, want: "1"}, + {name: "TestIntSetInt8Max", in: 127, want: "127"}, + {name: "TestIntSetInt8Min", in: -128, want: "-128"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt8(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetInt16(t *testing.T) { + var cases = []struct { + name string + in int16 + want string + }{ + {name: "TestIntSetInt16Negative", in: -1, want: "-1"}, + {name: "TestIntSetInt16Zero", in: 0, want: "0"}, + {name: "TestIntSetInt16Positive", in: 1, want: "1"}, + {name: "TestIntSetInt16Max", in: 32767, want: "32767"}, + {name: "TestIntSetInt16Min", in: -32768, want: "-32768"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt16(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetInt32(t *testing.T) { + var cases = []struct { + name string + in int32 + want string + }{ + {name: "TestIntSetInt32Negative", in: -1, want: "-1"}, + {name: "TestIntSetInt32Zero", in: 0, want: "0"}, + {name: "TestIntSetInt32Positive", in: 1, want: "1"}, + {name: "TestIntSetInt32Max", in: 2147483647, want: "2147483647"}, + {name: "TestIntSetInt32Min", in: -2147483648, want: "-2147483648"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetInt64(t *testing.T) { + var cases = []struct { + name string + in int64 + want string + }{ + {name: "TestIntSetInt64Negative", in: -1, want: "-1"}, + {name: "TestIntSetInt64Zero", in: 0, want: "0"}, + {name: "TestIntSetInt64Positive", in: 1, want: "1"}, + {name: "TestIntSetInt64Max", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntSetInt64Min", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetInt64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetUint(t *testing.T) { + var cases = []struct { + name string + in uint64 + want string + }{ + {name: "TestIntSetUintNegative", in: 0, want: "0"}, + {name: "TestIntSetUintZero", in: 0, want: "0"}, + {name: "TestIntSetUintPositive", in: 1, want: "1"}, + {name: "TestIntSetUintMax", in: 18446744073709551615, want: "18446744073709551615"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetUint8(t *testing.T) { + var cases = []struct { + name string + in uint8 + want string + }{ + {name: "TestIntSetUint8Negative", in: 0, want: "0"}, + {name: "TestIntSetUint8Zero", in: 0, want: "0"}, + {name: "TestIntSetUint8Positive", in: 1, want: "1"}, + {name: "TestIntSetUint8Max", in: 255, want: "255"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint8(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetUint16(t *testing.T) { + var cases = []struct { + name string + in uint16 + want string + }{ + {name: "TestIntSetUint16Negative", in: 0, want: "0"}, + {name: "TestIntSetUint16Zero", in: 0, want: "0"}, + {name: "TestIntSetUint16Positive", in: 1, want: "1"}, + {name: "TestIntSetUint16Max", in: 65535, want: "65535"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint16(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetUint32(t *testing.T) { + var cases = []struct { + name string + in uint32 + want string + }{ + {name: "TestIntSetUint32Negative", in: 0, want: "0"}, + {name: "TestIntSetUint32Zero", in: 0, want: "0"}, + {name: "TestIntSetUint32Positive", in: 1, want: "1"}, + {name: "TestIntSetUint32Max", in: 4294967295, want: "4294967295"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetUint64(t *testing.T) { + var cases = []struct { + name string + in uint64 + want string + }{ + {name: "TestIntSetUint64Negative", in: 0, want: "0"}, + {name: "TestIntSetUint64Zero", in: 0, want: "0"}, + {name: "TestIntSetUint64Positive", in: 1, want: "1"}, + {name: "TestIntSetUint64Max", in: 18446744073709551615, want: "18446744073709551615"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetUint64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetFloat32(t *testing.T) { + var cases = []struct { + name string + in float32 + want string + }{ + {name: "TestIntSetFloat32Negative", in: -1.1, want: "-1"}, + {name: "TestIntSetFloat32Zero", in: 0, want: "0"}, + {name: "TestIntSetFloat32Positive", in: 1.1, want: "1"}, + {name: "TestIntSetFloat32Max", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntSetFloat32Min", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetFloat32(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetFloat64(t *testing.T) { + var cases = []struct { + name string + in float64 + want string + }{ + {name: "TestIntSetFloat64Negative", in: -1.1, want: "-1"}, + {name: "TestIntSetFloat64Zero", in: 0, want: "0"}, + {name: "TestIntSetFloat64Positive", in: 1.1, want: "1"}, + {name: "TestIntSetFloat64Max", in: 9223372036854775807, want: "9223372036854775807"}, + {name: "TestIntSetFloat64Min", in: -9223372036854775808, want: "-9223372036854775808"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetFloat64(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_SetBool(t *testing.T) { + var cases = []struct { + name string + in bool + want string + }{ + {name: "TestIntSetBoolFalse", in: false, want: "0"}, + {name: "TestIntSetBoolTrue", in: true, want: "1"}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + var in *huge.Int + in = in.SetBool(c.in) + if s := in.String(); s != c.want { + t.Fatalf("want: %s, got: %s", c.want, in.String()) + } else { + t.Log(s) + } + }) + } +} + +func TestInt_IsZero(t *testing.T) { + var cases = []struct { + name string + in int64 + want bool + }{ + {name: "TestIntIsZeroNegative", in: -1, want: false}, + {name: "TestIntIsZeroZero", in: 0, want: true}, + {name: "TestIntIsZeroPositive", in: 1, want: false}, + {name: "TestIntIsZeroMax", in: 9223372036854775807, want: false}, + {name: "TestIntIsZeroMin", in: -9223372036854775808, want: false}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := huge.NewInt(c.in).IsZero(); got != c.want { + t.Fatalf("want: %t, got: %t", c.want, got) + } + }) + } +} + +func TestInt_ToBigint(t *testing.T) { + var cases = []struct { + name string + in int64 + want *big.Int + }{ + {name: "TestIntToBigintNegative", in: -1, want: big.NewInt(-1)}, + {name: "TestIntToBigintZero", in: 0, want: big.NewInt(0)}, + {name: "TestIntToBigintPositive", in: 1, want: big.NewInt(1)}, + {name: "TestIntToBigintMax", in: 9223372036854775807, want: big.NewInt(9223372036854775807)}, + {name: "TestIntToBigintMin", in: -9223372036854775808, want: big.NewInt(-9223372036854775808)}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := huge.NewInt(c.in).ToBigint(); got.Cmp(c.want) != 0 { + t.Fatalf("want: %s, got: %s", c.want.String(), got.String()) + } + }) + } +} diff --git a/utils/leaderboard/README.md b/utils/leaderboard/README.md index 6be6bd6..1576b6c 100644 --- a/utils/leaderboard/README.md +++ b/utils/leaderboard/README.md @@ -25,20 +25,21 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[BinarySearch](#binarysearch)|暂无描述... -|`STRUCT`|[BinarySearchRankChangeEventHandle](#binarysearchrankchangeeventhandle)|暂无描述... -|`STRUCT`|[BinarySearchOption](#binarysearchoption)|暂无描述... +|`STRUCT`|[BinarySearch](#struct_BinarySearch)|暂无描述... +|`STRUCT`|[BinarySearchRankChangeEventHandle](#struct_BinarySearchRankChangeEventHandle)|暂无描述... +|`STRUCT`|[BinarySearchOption](#struct_BinarySearchOption)|暂无描述...
*** ## 详情信息 -#### func NewBinarySearch(options ...BinarySearchOption[CompetitorID, Score]) *BinarySearch[CompetitorID, Score] +#### func NewBinarySearch\[CompetitorID comparable, Score generic.Ordered\](options ...BinarySearchOption[CompetitorID, Score]) *BinarySearch[CompetitorID, Score] > 创建一个基于内存的二分查找排行榜 -示例代码： +**示例代码：** + ```go func ExampleNewBinarySearch() { @@ -49,18 +50,19 @@ func ExampleNewBinarySearch() { ``` *** -#### func WithBinarySearchCount(rankCount int) BinarySearchOption[CompetitorID, Score] +#### func WithBinarySearchCount\[CompetitorID comparable, Score generic.Ordered\](rankCount int) BinarySearchOption[CompetitorID, Score] > 通过限制排行榜竞争者数量来创建排行榜 > - 默认情况下允许100位竞争者 *** -#### func WithBinarySearchASC() BinarySearchOption[CompetitorID, Score] +#### func WithBinarySearchASC\[CompetitorID comparable, Score generic.Ordered\]() BinarySearchOption[CompetitorID, Score] > 通过升序的方式创建排行榜 > - 默认情况下为降序 *** + ### BinarySearch `STRUCT` ```go @@ -74,11 +76,168 @@ type BinarySearch[CompetitorID comparable, Score generic.Ordered] struct { rankClearBeforeEventHandles []BinarySearchRankClearBeforeEventHandle[CompetitorID, Score] } ``` + + +#### func (*BinarySearch) Competitor(competitorId CompetitorID, score Score) +> 声明排行榜竞争者 +> - 如果竞争者存在的情况下，会更新已有成绩，否则新增竞争者 + +**示例代码：** + +```go + +func ExampleBinarySearch_Competitor() { + bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10)) + scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666} + for i := 1; i <= 15; i++ { + bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1]) + } + for rank, competitor := range bs.GetAllCompetitor() { + fmt.Println(rank, competitor) + } +} + +``` + +*** + + +#### func (*BinarySearch) RemoveCompetitor(competitorId CompetitorID) +> 删除特定竞争者 + +**示例代码：** + +```go + +func ExampleBinarySearch_RemoveCompetitor() { + bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10)) + scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666} + for i := 1; i <= 15; i++ { + bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1]) + } + bs.RemoveCompetitor("competitor_ 1") + for rank, competitor := range bs.GetAllCompetitor() { + fmt.Println(rank, competitor) + } +} + +``` + +*** + + +#### func (*BinarySearch) Size() int +> 获取竞争者数量 + +*** + + +#### func (*BinarySearch) GetRankDefault(competitorId CompetitorID, defaultValue int) int +> 获取竞争者排名，如果竞争者不存在则返回默认值 +> - 排名从 0 开始 + +*** + + +#### func (*BinarySearch) GetRank(competitorId CompetitorID) ( int, error) +> 获取竞争者排名 +> - 排名从 0 开始 + +**示例代码：** + +```go + +func ExampleBinarySearch_GetRank() { + bs := leaderboard2.NewBinarySearch[string, int](leaderboard2.WithBinarySearchCount[string, int](10)) + scores := []int{6131, 132, 5133, 134, 135, 136, 137, 138, 139, 140, 222, 333, 444, 555, 666} + for i := 1; i <= 15; i++ { + bs.Competitor(fmt.Sprintf("competitor_%2d", i), scores[i-1]) + } + fmt.Println(bs.GetRank("competitor_ 1")) +} + +``` + +*** + + +#### func (*BinarySearch) GetCompetitor(rank int) (competitorId CompetitorID, err error) +> 获取特定排名的竞争者 + +*** + + +#### func (*BinarySearch) GetCompetitorWithRange(start int, end int) ( []CompetitorID, error) +> 获取第start名到第end名竞争者 + +*** + + +#### func (*BinarySearch) GetScore(competitorId CompetitorID) (score Score, err error) +> 获取竞争者成绩 + +*** + + +#### func (*BinarySearch) GetScoreDefault(competitorId CompetitorID, defaultValue Score) Score +> 获取竞争者成绩，不存在时返回默认值 + +*** + + +#### func (*BinarySearch) GetAllCompetitor() []CompetitorID +> 获取所有竞争者ID +> - 结果为名次有序的 + +*** + + +#### func (*BinarySearch) Clear() +> 清空排行榜 + +*** + + +#### func (*BinarySearch) Cmp(s1 Score, s2 Score) int + +*** + + +#### func (*BinarySearch) UnmarshalJSON(bytes []byte) error + +*** + + +#### func (*BinarySearch) MarshalJSON() ( []byte, error) + +*** + + +#### func (*BinarySearch) RegRankChangeEvent(handle BinarySearchRankChangeEventHandle[CompetitorID, Score]) + +*** + + +#### func (*BinarySearch) OnRankChangeEvent(competitorId CompetitorID, oldRank int, newRank int, oldScore Score, newScore Score) + +*** + + +#### func (*BinarySearch) RegRankClearBeforeEvent(handle BinarySearchRankClearBeforeEventHandle[CompetitorID, Score]) + +*** + + +#### func (*BinarySearch) OnRankClearBeforeEvent() + +*** + ### BinarySearchRankChangeEventHandle `STRUCT` ```go type BinarySearchRankChangeEventHandle[CompetitorID comparable, Score generic.Ordered] func(leaderboard *BinarySearch[CompetitorID, Score], competitorId CompetitorID, oldRank int, oldScore Score) ``` + ### BinarySearchOption `STRUCT` ```go diff --git a/utils/log/README.md b/utils/log/README.md index 7980ed3..a743124 100644 --- a/utils/log/README.md +++ b/utils/log/README.md @@ -77,10 +77,10 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Field](#field)|暂无描述... -|`STRUCT`|[Logger](#logger)|暂无描述... -|`STRUCT`|[MultiHandler](#multihandler)|暂无描述... -|`STRUCT`|[Option](#option)|暂无描述... +|`STRUCT`|[Field](#struct_Field)|暂无描述... +|`STRUCT`|[Logger](#struct_Logger)|暂无描述... +|`STRUCT`|[MultiHandler](#struct_MultiHandler)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|暂无描述... @@ -96,7 +96,7 @@ *** -#### func Default() *Logger +#### func Default() *Logger > 获取默认的日志记录器 @@ -150,193 +150,193 @@ > - 然后记录器调用 os.Exit(1)，即使 FatalLevel 的日志记录被禁用 *** -#### func Skip(vs ...any) slog.Attr +#### func Skip(vs ...any) slog.Attr > 构造一个无操作字段，这在处理其他 Field 构造函数中的无效输入时通常很有用 > - 该函数还支持将其他字段快捷的转换为 Skip 字段 *** -#### func Duration(key string, val time.Duration) slog.Attr +#### func Duration(key string, val time.Duration) slog.Attr > 使用给定的键和值构造一个字段。编码器控制持续时间的序列化方式 *** -#### func DurationP(key string, val *time.Duration) slog.Attr +#### func DurationP(key string, val *time.Duration) slog.Attr > 构造一个带有 time.Duration 的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Bool(key string, val bool) slog.Attr +#### func Bool(key string, val bool) slog.Attr > 构造一个带有布尔值的字段 *** -#### func BoolP(key string, val *bool) slog.Attr +#### func BoolP(key string, val *bool) slog.Attr > 构造一个带有布尔值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func String(key string, val string) slog.Attr +#### func String(key string, val string) slog.Attr > 构造一个带有字符串值的字段 *** -#### func StringP(key string, val *string) slog.Attr +#### func StringP(key string, val *string) slog.Attr > 构造一个带有字符串值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Int(key string, val I) slog.Attr +#### func Int\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func IntP(key string, val *I) slog.Attr +#### func IntP\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Int8(key string, val I) slog.Attr +#### func Int8\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Int8P(key string, val *I) slog.Attr +#### func Int8P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Int16(key string, val I) slog.Attr +#### func Int16\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Int16P(key string, val *I) slog.Attr +#### func Int16P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Int32(key string, val I) slog.Attr +#### func Int32\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Int32P(key string, val *I) slog.Attr +#### func Int32P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Int64(key string, val I) slog.Attr +#### func Int64\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Int64P(key string, val *I) slog.Attr +#### func Int64P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Uint(key string, val I) slog.Attr +#### func Uint\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func UintP(key string, val *I) slog.Attr +#### func UintP\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Uint8(key string, val I) slog.Attr +#### func Uint8\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Uint8P(key string, val *I) slog.Attr +#### func Uint8P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Uint16(key string, val I) slog.Attr +#### func Uint16\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Uint16P(key string, val *I) slog.Attr +#### func Uint16P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Uint32(key string, val I) slog.Attr +#### func Uint32\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Uint32P(key string, val *I) slog.Attr +#### func Uint32P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Uint64(key string, val I) slog.Attr +#### func Uint64\[I generic.Integer\](key string, val I) slog.Attr > 构造一个带有整数值的字段 *** -#### func Uint64P(key string, val *I) slog.Attr +#### func Uint64P\[I generic.Integer\](key string, val *I) slog.Attr > 构造一个带有整数值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Float(key string, val F) slog.Attr +#### func Float\[F generic.Float\](key string, val F) slog.Attr > 构造一个带有浮点值的字段 *** -#### func FloatP(key string, val *F) slog.Attr +#### func FloatP\[F generic.Float\](key string, val *F) slog.Attr > 构造一个带有浮点值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Float32(key string, val F) slog.Attr +#### func Float32\[F generic.Float\](key string, val F) slog.Attr > 构造一个带有浮点值的字段 *** -#### func Float32P(key string, val *F) slog.Attr +#### func Float32P\[F generic.Float\](key string, val *F) slog.Attr > 构造一个带有浮点值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Float64(key string, val F) slog.Attr +#### func Float64\[F generic.Float\](key string, val F) slog.Attr > 构造一个带有浮点值的字段 *** -#### func Float64P(key string, val *F) slog.Attr +#### func Float64P\[F generic.Float\](key string, val *F) slog.Attr > 构造一个带有浮点值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Time(key string, val time.Time) slog.Attr +#### func Time(key string, val time.Time) slog.Attr > 构造一个带有时间值的字段 *** -#### func TimeP(key string, val *time.Time) slog.Attr +#### func TimeP(key string, val *time.Time) slog.Attr > 构造一个带有时间值的字段。返回的 Field 将在适当的时候安全且显式地表示 "null" *** -#### func Any(key string, val any) slog.Attr +#### func Any(key string, val any) slog.Attr > 构造一个带有任意值的字段 *** -#### func Group(key string, args ...any) slog.Attr +#### func Group(key string, args ...any) slog.Attr > 返回分组字段 *** -#### func Stack(key string) slog.Attr +#### func Stack(key string) slog.Attr > 返回堆栈字段 @@ -368,36 +368,38 @@ func TestStack(t *testing.T) { *** -#### func Err(err error) slog.Attr +#### func Err(err error) slog.Attr > 构造一个带有错误值的字段 *** -#### func NewHandler(w io.Writer, opts *Options) slog.Handler +#### func NewHandler(w io.Writer, opts *Options) slog.Handler > 创建一个更偏向于人类可读的处理程序，该处理程序也是默认的处理程序 *** -#### func NewLogger(handlers ...slog.Handler) *Logger +#### func NewLogger(handlers ...slog.Handler) *Logger > 创建一个新的日志记录器 *** -#### func NewMultiHandler(handlers ...slog.Handler) slog.Handler +#### func NewMultiHandler(handlers ...slog.Handler) slog.Handler > 创建一个新的多处理程序 *** -#### func NewOptions() *Options +#### func NewOptions() *Options > 创建一个新的日志选项 *** + ### Field `STRUCT` ```go type Field slog.Attr ``` + ### Logger `STRUCT` ```go @@ -405,6 +407,7 @@ type Logger struct { *slog.Logger } ``` + ### MultiHandler `STRUCT` ```go @@ -412,14 +415,27 @@ type MultiHandler struct { handlers []slog.Handler } ``` + + #### func (MultiHandler) Enabled(ctx context.Context, level slog.Level) bool + *** + + #### func (MultiHandler) Handle(ctx context.Context, record slog.Record) (err error) + *** + + #### func (MultiHandler) WithAttrs(attrs []slog.Attr) slog.Handler + *** + + #### func (MultiHandler) WithGroup(name string) slog.Handler + *** + ### Option `STRUCT` ```go diff --git a/utils/log/survey/README.md b/utils/log/survey/README.md index 7c2e721..18084d7 100644 --- a/utils/log/survey/README.md +++ b/utils/log/survey/README.md @@ -32,26 +32,26 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Analyzer](#analyzer)|分析器 -|`INTERFACE`|[Flusher](#flusher)|用于刷新缓冲区的接口 -|`STRUCT`|[FileFlusher](#fileflusher)|暂无描述... -|`STRUCT`|[Option](#option)|选项 -|`STRUCT`|[Result](#result)|暂无描述... -|`STRUCT`|[R](#r)|记录器所记录的一条数据 -|`STRUCT`|[Report](#report)|分析报告 +|`STRUCT`|[Analyzer](#struct_Analyzer)|分析器 +|`INTERFACE`|[Flusher](#struct_Flusher)|用于刷新缓冲区的接口 +|`STRUCT`|[FileFlusher](#struct_FileFlusher)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|选项 +|`STRUCT`|[Result](#struct_Result)|暂无描述... +|`STRUCT`|[R](#struct_R)|记录器所记录的一条数据 +|`STRUCT`|[Report](#struct_Report)|分析报告 *** ## 详情信息 -#### func NewFileFlusher(filePath string, layout ...string) *FileFlusher +#### func NewFileFlusher(filePath string, layout ...string) *FileFlusher > 创建一个文件刷新器 > - layout 为日志文件名的时间戳格式 (默认为 time.DateOnly) *** -#### func WithFlushInterval(interval time.Duration) Option +#### func WithFlushInterval(interval time.Duration) Option > 设置日志文件刷新间隔 > - 默认为 3s，当日志文件刷新间隔 <= 0 时，将会在每次写入日志时刷新日志文件 @@ -83,19 +83,19 @@ > 关闭运营日志记录器 *** -#### func Analyze(filePath string, handle func (analyzer *Analyzer, record R)) *Report +#### func Analyze(filePath string, handle func (analyzer *Analyzer, record R)) *Report > 分析特定文件的记录，当发生错误时，会发生 panic > - handle 为并行执行的，需要自行处理并发安全 > - 适用于外部进程对于日志文件的读取，但是需要注意的是，此时日志文件可能正在被写入，所以可能会读取到错误的数据 *** -#### func AnalyzeMulti(filePaths []string, handle func (analyzer *Analyzer, record R)) *Report +#### func AnalyzeMulti(filePaths []string, handle func (analyzer *Analyzer, record R)) *Report > 与 Analyze 类似，但是可以分析多个文件 *** -#### func IncrementAnalyze(filePath string, handle func (analyzer *Analyzer, record R)) func () ( *Report, error) +#### func IncrementAnalyze(filePath string, handle func (analyzer *Analyzer, record R)) func () ( *Report, error) > 增量分析，返回一个函数，每次调用该函数都会分析文件中新增的内容 @@ -153,6 +153,7 @@ func TestIncrementAnalyze(t *testing.T) { *** + ### Analyzer `STRUCT` 分析器 ```go @@ -165,32 +166,58 @@ type Analyzer struct { m sync.Mutex } ``` + + #### func (*Analyzer) Sub(key string) *Analyzer > 获取子分析器 + *** + + #### func (*Analyzer) SetFormat(key string, format func (v any) any) > 设置格式化函数 + *** + + #### func (*Analyzer) SetValueIfGreaterThan(key string, value float64) > 设置指定 key 的值，当新值大于旧值时 > - 当已有值不为 float64 时，将会被忽略 + *** + + #### func (*Analyzer) SetValueIfLessThan(key string, value float64) > 设置指定 key 的值，当新值小于旧值时 > - 当已有值不为 float64 时，将会被忽略 + *** + + #### func (*Analyzer) SetValueIf(key string, expression bool, value float64) > 当表达式满足的时候将设置指定 key 的值为 value + *** + + #### func (*Analyzer) SetValueStringIf(key string, expression bool, value string) > 当表达式满足的时候将设置指定 key 的值为 value + *** + + #### func (*Analyzer) SetValue(key string, value float64) > 设置指定 key 的值 + *** + + #### func (*Analyzer) SetValueString(key string, value string) > 设置指定 key 的值 + *** + + #### func (*Analyzer) Increase(key string, record R, recordKey string) > 在指定 key 现有值的基础上增加 recordKey 的值 > - 当分析器已经记录过相同 key 的值时，会根据已有的值类型进行不同处理 @@ -198,22 +225,39 @@ type Analyzer struct { > 处理方式： > - 当已有值类型为 string 时，将会使用新的值的 string 类型进行覆盖 > - 当已有值类型为 float64 时，当新的值类型不为 float64 时，将会被忽略 + *** + + #### func (*Analyzer) IncreaseValue(key string, value float64) > 在指定 key 现有值的基础上增加 value + *** + + #### func (*Analyzer) IncreaseNonRepeat(key string, record R, recordKey string, dimension ...string) > 在指定 key 现有值的基础上增加 recordKey 的值，但是当去重维度 dimension 相同时，不会增加 + *** + + #### func (*Analyzer) IncreaseValueNonRepeat(key string, record R, value float64, dimension ...string) > 在指定 key 现有值的基础上增加 value，但是当去重维度 dimension 相同时，不会增加 + *** + + #### func (*Analyzer) GetValue(key string) float64 > 获取当前记录的值 + *** + + #### func (*Analyzer) GetValueString(key string) string > 获取当前记录的值 + *** + ### Flusher `INTERFACE` 用于刷新缓冲区的接口 ```go @@ -222,6 +266,7 @@ type Flusher interface { Info() string } ``` + ### FileFlusher `STRUCT` ```go @@ -233,53 +278,90 @@ type FileFlusher struct { layoutLen int } ``` + + #### func (*FileFlusher) Flush(records []string) + *** + + #### func (*FileFlusher) Info() string + *** + ### Option `STRUCT` 选项 ```go type Option func(logger *logger) ``` + ### Result `STRUCT` ```go type Result gjson.Result ``` + ### R `STRUCT` 记录器所记录的一条数据 ```go type R string ``` + + #### func (R) GetTime(layout string) time.Time > 获取该记录的时间 + *** + + #### func (R) Get(key string) Result > 获取指定 key 的值 > - 当 key 为嵌套 key 时，使用 . 进行分割，例如：a.b.c > - 更多用法参考：https://github.com/tidwall/gjson + *** + + #### func (R) Exist(key string) bool > 判断指定 key 是否存在 + *** + + #### func (R) GetString(key string) string > 该函数为 Get(key).String() 的简写 + *** + + #### func (R) GetInt64(key string) int64 > 该函数为 Get(key).Int() 的简写 + *** + + #### func (R) GetInt(key string) int > 该函数为 Get(key).Int() 的简写，但是返回值为 int 类型 + *** + + #### func (R) GetFloat64(key string) float64 > 该函数为 Get(key).Float() 的简写 + *** + + #### func (R) GetBool(key string) bool > 该函数为 Get(key).Bool() 的简写 + *** + + #### func (R) String() string + *** + ### Report `STRUCT` 分析报告 ```go @@ -291,26 +373,50 @@ type Report struct { Subs []*Report } ``` + + #### func (*Report) Avg(key string) float64 > 计算平均值 + *** + + #### func (*Report) Count(key string) int64 > 获取特定 key 的计数次数 + *** + + #### func (*Report) Sum(keys ...string) float64 > 获取特定 key 的总和 + *** + + #### func (*Report) Sub(name string) *Report > 获取特定名称的子报告 + *** + + #### func (*Report) ReserveSubByPrefix(prefix string) *Report > 仅保留特定前缀的子报告 + *** + + #### func (*Report) ReserveSub(names ...string) *Report > 仅保留特定名称子报告 + *** + + #### func (*Report) FilterSub(names ...string) *Report > 将特定名称的子报告过滤掉 + *** + + #### func (*Report) String() string + *** diff --git a/utils/maths/README.md b/utils/maths/README.md index 004d1fe..db1cf2e 100644 --- a/utils/maths/README.md +++ b/utils/maths/README.md @@ -45,23 +45,24 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[CompareExpression](#compareexpression)|比较表达式 +|`STRUCT`|[CompareExpression](#struct_CompareExpression)|比较表达式 *** ## 详情信息 -#### func Compare(a V, expression CompareExpression, b V) bool +#### func Compare\[V generic.Ordered\](a V, expression CompareExpression, b V) bool > 根据特定表达式比较两个值 *** -#### func IsContinuity(values S) bool +#### func IsContinuity\[S ~[]V, V generic.Integer\](values S) bool > 检查一组值是否连续 -示例代码： +**示例代码：** + ```go func ExampleIsContinuity() { @@ -72,82 +73,83 @@ func ExampleIsContinuity() { ``` *** -#### func IsContinuityWithSort(values S) bool +#### func IsContinuityWithSort\[S ~[]V, V generic.Integer\](values S) bool > 检查一组值排序后是否连续 *** -#### func GetDefaultTolerance() float64 +#### func GetDefaultTolerance() float64 > 获取默认误差范围 *** -#### func Pow(a int, n int) int +#### func Pow(a int, n int) int > 整数幂运算 *** -#### func PowInt64(a int64, n int64) int64 +#### func PowInt64(a int64, n int64) int64 > 整数幂运算 *** -#### func Min(a V, b V) V +#### func Min\[V generic.Number\](a V, b V) V > 返回两个数之中较小的值 *** -#### func Max(a V, b V) V +#### func Max\[V generic.Number\](a V, b V) V > 返回两个数之中较大的值 *** -#### func MinMax(a V, b V) (min V, max V) +#### func MinMax\[V generic.Number\](a V, b V) (min V, max V) > 将两个数按照较小的和较大的顺序进行返回 *** -#### func MaxMin(a V, b V) (max V, min V) +#### func MaxMin\[V generic.Number\](a V, b V) (max V, min V) > 将两个数按照较大的和较小的顺序进行返回 *** -#### func Clamp(value V, min V, max V) V +#### func Clamp\[V generic.Number\](value V, min V, max V) V > 将给定值限制在最小值和最大值之间 *** -#### func Tolerance(value1 V, value2 V, tolerance V) bool +#### func Tolerance\[V generic.Number\](value1 V, value2 V, tolerance V) bool > 检查两个值是否在一个误差范围内 *** -#### func Merge(refer V, a V, b V) V +#### func Merge\[V generic.SignedNumber\](refer V, a V, b V) V > 通过一个参考值合并两个数字 *** -#### func UnMerge(refer V, num V) (a V, b V) +#### func UnMerge\[V generic.SignedNumber\](refer V, num V) (a V, b V) > 通过一个参考值取消合并的两个数字 *** -#### func MergeToInt64(v1 V, v2 V) int64 +#### func MergeToInt64\[V generic.SignedNumber\](v1 V, v2 V) int64 > 将两个数字合并为一个 int64 数字 *** -#### func UnMergeInt64(n int64) V, V +#### func UnMergeInt64\[V generic.SignedNumber\](n int64) (V, V) > 将一个 int64 数字拆分为两个数字 *** -#### func ToContinuous(nums S) map[V]V +#### func ToContinuous\[S ~[]V, V generic.Integer\](nums S) map[V]V > 将一组非连续的数字转换为从1开始的连续数字 > - 返回值是一个 map，key 是从 1 开始的连续数字，value 是原始数字 -示例代码： +**示例代码：** + ```go func ExampleToContinuous() { @@ -160,34 +162,34 @@ func ExampleToContinuous() { ``` *** -#### func CountDigits(num V) int +#### func CountDigits\[V generic.Number\](num V) int > 接收一个整数 num 作为输入，并返回该数字的位数 *** -#### func GetDigitValue(num int64, digit int) int64 +#### func GetDigitValue(num int64, digit int) int64 > 接收一个整数 num 和一个表示目标位数的整数 digit 作为输入，并返 > 回数字 num 在指定位数上的数值。我们使用 math.Abs() 函数获取 num 的绝对值，并通 > 过除以10的操作将 num 移动到目标位数上。然后，通过取余运算得到位数上的数值 *** -#### func JoinNumbers(num1 V, n ...V) V +#### func JoinNumbers\[V generic.Number\](num1 V, n ...V) V > 将一组数字连接起来 *** -#### func IsOdd(n V) bool +#### func IsOdd\[V generic.Integer\](n V) bool > 返回 n 是否为奇数 *** -#### func IsEven(n V) bool +#### func IsEven\[V generic.Integer\](n V) bool > 返回 n 是否为偶数 *** -#### func MakeLastDigitsZero(num T, digits int) T +#### func MakeLastDigitsZero\[T generic.Number\](num T, digits int) T > 返回一个新的数，其中 num 的最后 digits 位数被设为零。 > - 函数首先创建一个 10 的 digits 次方的遮罩，然后通过整除和乘以这个遮罩来使 num 的最后 digits 位归零。 @@ -213,6 +215,7 @@ func TestMakeLastDigitsZero(t *testing.T) { *** + ### CompareExpression `STRUCT` 比较表达式 ```go diff --git a/utils/memory/README.md b/utils/memory/README.md index 4d1c180..4410a5e 100644 --- a/utils/memory/README.md +++ b/utils/memory/README.md @@ -26,7 +26,7 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Option](#option)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|暂无描述... @@ -38,7 +38,7 @@ > 运行持久化缓存程序 *** -#### func BindPersistCacheProgram(name string, handler OutputParamHandlerFunc, option ...*Option) func () +#### func BindPersistCacheProgram\[OutputParamHandlerFunc any\](name string, handler OutputParamHandlerFunc, option ...*Option) func () > 绑定持久化缓存程序 > - name 持久化缓存程序名称 @@ -52,7 +52,7 @@ > - 所有持久化程序绑定完成后，应该主动调用 Run 函数运行 *** -#### func BindAction(name string, handler Func) Func +#### func BindAction\[Func any\](name string, handler Func) Func > 绑定需要缓存的操作函数 > - name 缓存操作名称 @@ -92,10 +92,11 @@ func TestBindAction(t *testing.T) { *** -#### func NewOption() *Option +#### func NewOption() *Option *** + ### Option `STRUCT` ```go @@ -106,10 +107,13 @@ type Option struct { delay time.Duration } ``` + + #### func (*Option) WithPeriodicity(ticker *timer.Ticker, firstDelay time.Duration, interval time.Duration, delay time.Duration) *Option > 设置持久化周期 > - ticker 定时器，通常建议使用服务器的定时器，这样可以降低多线程的程序复杂性 > - firstDelay 首次持久化延迟，当首次持久化为 0 时，将会在下一个持久化周期开始时持久化 > - interval 持久化间隔 > - delay 每条数据持久化间隔，适当的设置该值可以使持久化期间尽量降低对用户体验的影响，如果为0，将会一次性持久化所有数据 + *** diff --git a/utils/moving/README.md b/utils/moving/README.md index e243217..48538d6 100644 --- a/utils/moving/README.md +++ b/utils/moving/README.md @@ -27,21 +27,22 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[TwoDimensional](#twodimensional)|用于2D对象移动的数据结构 -|`INTERFACE`|[TwoDimensionalEntity](#twodimensionalentity)|2D移动对象接口定义 -|`STRUCT`|[Position2DChangeEventHandle](#position2dchangeeventhandle)|暂无描述... -|`STRUCT`|[TwoDimensionalOption](#twodimensionaloption)|暂无描述... +|`STRUCT`|[TwoDimensional](#struct_TwoDimensional)|用于2D对象移动的数据结构 +|`INTERFACE`|[TwoDimensionalEntity](#struct_TwoDimensionalEntity)|2D移动对象接口定义 +|`STRUCT`|[Position2DChangeEventHandle](#struct_Position2DChangeEventHandle)|暂无描述... +|`STRUCT`|[TwoDimensionalOption](#struct_TwoDimensionalOption)|暂无描述... *** ## 详情信息 -#### func NewTwoDimensional(options ...TwoDimensionalOption[EID, PosType]) *TwoDimensional[EID, PosType] +#### func NewTwoDimensional\[EID generic.Basic, PosType generic.SignedNumber\](options ...TwoDimensionalOption[EID, PosType]) *TwoDimensional[EID, PosType] > 创建一个用于2D对象移动的实例(TwoDimensional) -示例代码： +**示例代码：** + ```go func ExampleNewTwoDimensional() { @@ -74,27 +75,28 @@ func TestNewTwoDimensional(t *testing.T) { *** -#### func WithTwoDimensionalTimeUnit(duration time.Duration) TwoDimensionalOption[EID, PosType] +#### func WithTwoDimensionalTimeUnit\[EID generic.Basic, PosType generic.SignedNumber\](duration time.Duration) TwoDimensionalOption[EID, PosType] > 通过特定时间单位创建 > - 默认单位为1毫秒，最小单位也为1毫秒 *** -#### func WithTwoDimensionalIdleWaitTime(duration time.Duration) TwoDimensionalOption[EID, PosType] +#### func WithTwoDimensionalIdleWaitTime\[EID generic.Basic, PosType generic.SignedNumber\](duration time.Duration) TwoDimensionalOption[EID, PosType] > 通过特定的空闲等待时间创建 > - 默认情况下在没有新的移动计划时将限制 100毫秒 + 移动间隔事件(默认100毫秒) *** -#### func WithTwoDimensionalInterval(duration time.Duration) TwoDimensionalOption[EID, PosType] +#### func WithTwoDimensionalInterval\[EID generic.Basic, PosType generic.SignedNumber\](duration time.Duration) TwoDimensionalOption[EID, PosType] > 通过特定的移动间隔时间创建 *** -#### func NewEntity(guid int64, speed float64) *MoveEntity +#### func NewEntity(guid int64, speed float64) *MoveEntity *** + ### TwoDimensional `STRUCT` 用于2D对象移动的数据结构 - 通过对象调用 MoveTo 方法后将开始执行该对象的移动 @@ -113,6 +115,152 @@ type TwoDimensional[EID generic.Basic, PosType generic.SignedNumber] struct { position2DStopMoveEventHandles []Position2DStopMoveEventHandle[EID, PosType] } ``` + + +#### func (*TwoDimensional) MoveTo(entity TwoDimensionalEntity[EID, PosType], x PosType, y PosType) +> 设置对象移动到特定位置 + +**示例代码：** + +```go + +func ExampleTwoDimensional_MoveTo() { + m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second)) + defer func() { + m.Release() + }() + var wait sync.WaitGroup + m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) { + fmt.Println("done") + wait.Done() + }) + wait.Add(1) + entity := NewEntity(1, 100) + m.MoveTo(entity, 50, 30) + wait.Wait() +} + +``` + +*** + + +#### func (*TwoDimensional) StopMove(id EID) +> 停止特定对象的移动 + +**示例代码：** + +```go + +func ExampleTwoDimensional_StopMove() { + m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second)) + defer func() { + m.Release() + }() + var wait sync.WaitGroup + m.RegPosition2DChangeEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64], oldX, oldY float64) { + fmt.Println("move") + }) + m.RegPosition2DStopMoveEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) { + fmt.Println("stop") + wait.Done() + }) + m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) { + fmt.Println("done") + wait.Done() + }) + wait.Add(1) + entity := NewEntity(1, 100) + m.MoveTo(entity, 50, 300) + m.StopMove(1) + wait.Wait() +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestTwoDimensional_StopMove(t *testing.T) { + var wait sync.WaitGroup + m := moving2.NewTwoDimensional(moving2.WithTwoDimensionalTimeUnit[int64, float64](time.Second)) + defer func() { + m.Release() + }() + m.RegPosition2DChangeEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64], oldX, oldY float64) { + x, y := entity.GetPosition().GetXY() + fmt.Println(fmt.Sprintf("%d : %d | %f, %f > %f, %f", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli(), oldX, oldY, x, y)) + }) + m.RegPosition2DDestinationEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) { + fmt.Println(fmt.Sprintf("%d : %d | destination", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli())) + wait.Done() + }) + m.RegPosition2DStopMoveEvent(func(moving *moving2.TwoDimensional[int64, float64], entity moving2.TwoDimensionalEntity[int64, float64]) { + fmt.Println(fmt.Sprintf("%d : %d | stop", entity.GetTwoDimensionalEntityID(), time.Now().UnixMilli())) + wait.Done() + }) + for i := 0; i < 10; i++ { + wait.Add(1) + entity := NewEntity(int64(i)+1, float64(10+i)) + m.MoveTo(entity, 50, 30) + } + time.Sleep(time.Second * 1) + for i := 0; i < 10; i++ { + m.StopMove(int64(i) + 1) + } + wait.Wait() +} + +``` + + +
+ + +*** + + +#### func (*TwoDimensional) RegPosition2DChangeEvent(handle Position2DChangeEventHandle[EID, PosType]) +> 在对象位置改变时将执行注册的事件处理函数 + +*** + + +#### func (*TwoDimensional) OnPosition2DChangeEvent(entity TwoDimensionalEntity[EID, PosType], oldX PosType, oldY PosType) + +*** + + +#### func (*TwoDimensional) RegPosition2DDestinationEvent(handle Position2DDestinationEventHandle[EID, PosType]) +> 在对象到达终点时将执行被注册的事件处理函数 + +*** + + +#### func (*TwoDimensional) OnPosition2DDestinationEvent(entity TwoDimensionalEntity[EID, PosType]) + +*** + + +#### func (*TwoDimensional) RegPosition2DStopMoveEvent(handle Position2DStopMoveEventHandle[EID, PosType]) +> 在对象停止移动时将执行被注册的事件处理函数 + +*** + + +#### func (*TwoDimensional) OnPosition2DStopMoveEvent(entity TwoDimensionalEntity[EID, PosType]) + +*** + + +#### func (*TwoDimensional) Release() +> 释放对象移动对象所占用的资源 + +*** + ### TwoDimensionalEntity `INTERFACE` 2D移动对象接口定义 ```go @@ -123,11 +271,13 @@ type TwoDimensionalEntity[EID generic.Basic, PosType generic.SignedNumber] inter SetPosition(geometry.Point[PosType]) } ``` + ### Position2DChangeEventHandle `STRUCT` ```go type Position2DChangeEventHandle[EID generic.Basic, PosType generic.SignedNumber] func(moving *TwoDimensional[EID, PosType], entity TwoDimensionalEntity[EID, PosType], oldX PosType) ``` + ### TwoDimensionalOption `STRUCT` ```go diff --git a/utils/offset/README.md b/utils/offset/README.md index 3c35959..a25117d 100644 --- a/utils/offset/README.md +++ b/utils/offset/README.md @@ -27,14 +27,14 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Time](#time)|带有偏移量的时间 +|`STRUCT`|[Time](#struct_Time)|带有偏移量的时间 *** ## 详情信息 -#### func NewTime(offset time.Duration) *Time +#### func NewTime(offset time.Duration) *Time > 新建一个包含偏移的时间 @@ -44,21 +44,22 @@ > 设置全局偏移时间 *** -#### func GetGlobal() *Time +#### func GetGlobal() *Time > 获取全局偏移时间 *** -#### func Now() time.Time +#### func Now() time.Time > 获取当前时间偏移后的时间 *** -#### func Since(t time.Time) time.Duration +#### func Since(t time.Time) time.Duration > 获取当前时间偏移后的时间自从 t 以来经过的时间 *** + ### Time `STRUCT` 带有偏移量的时间 ```go @@ -66,12 +67,21 @@ type Time struct { offset time.Duration } ``` + + #### func (*Time) SetOffset(offset time.Duration) > 设置时间偏移 + *** + + #### func (*Time) Now() time.Time > 获取当前时间偏移后的时间 + *** + + #### func (*Time) Since(t time.Time) time.Duration > 获取当前时间偏移后的时间自从 t 以来经过的时间 + *** diff --git a/utils/random/README.md b/utils/random/README.md index e607042..d4e92fc 100644 --- a/utils/random/README.md +++ b/utils/random/README.md @@ -20,6 +20,7 @@ |[DiceN](#DiceN)|掷骰子 |[NetIP](#NetIP)|返回一个随机的IP地址 |[Port](#Port)|返回一个随机的端口号 +|[UsablePort](#UsablePort)|随机返回一个可用的端口号，如果没有可用端口号则返回 -1 |[IPv4](#IPv4)|返回一个随机产生的IPv4地址。 |[IPv4Port](#IPv4Port)|返回一个随机产生的IPv4地址和端口。 |[Int64](#Int64)|返回一个介于min和max之间的int64类型的随机数。 @@ -52,74 +53,79 @@ *** ## 详情信息 -#### func Dice() int +#### func Dice() int > 掷骰子 > - 常规掷骰子将返回 1-6 的随机数 *** -#### func DiceN(n int) int +#### func DiceN(n int) int > 掷骰子 > - 与 Dice 不同的是，将返回 1-N 的随机数 *** -#### func NetIP() net.IP +#### func NetIP() net.IP > 返回一个随机的IP地址 *** -#### func Port() int +#### func Port() int > 返回一个随机的端口号 *** -#### func IPv4() string +#### func UsablePort() int + +> 随机返回一个可用的端口号，如果没有可用端口号则返回 -1 + +*** +#### func IPv4() string > 返回一个随机产生的IPv4地址。 *** -#### func IPv4Port() string +#### func IPv4Port() string > 返回一个随机产生的IPv4地址和端口。 *** -#### func Int64(min int64, max int64) int64 +#### func Int64(min int64, max int64) int64 > 返回一个介于min和max之间的int64类型的随机数。 *** -#### func Int(min int, max int) int +#### func Int(min int, max int) int > 返回一个介于min和max之间的的int类型的随机数。 *** -#### func Duration(min int64, max int64) time.Duration +#### func Duration(min int64, max int64) time.Duration > 返回一个介于min和max之间的的Duration类型的随机数。 *** -#### func Float64() float64 +#### func Float64() float64 > 返回一个0~1的浮点数 *** -#### func Float32() float32 +#### func Float32() float32 > 返回一个0~1的浮点数 *** -#### func IntN(n int) int +#### func IntN(n int) int > 返回一个0~n的整数 *** -#### func Bool() bool +#### func Bool() bool > 返回一个随机的布尔值 *** -#### func ProbabilitySlice(getProbabilityHandle func (data T) float64, data ...T) (hit T, miss bool) +#### func ProbabilitySlice\[T any\](getProbabilityHandle func (data T) float64, data ...T) (hit T, miss bool) > 按概率随机从切片中产生一个数据并返回命中的对象及是否未命中 > - 当总概率小于 1 将会发生未命中的情况 @@ -147,19 +153,19 @@ func TestProbabilitySlice(t *testing.T) { *** -#### func ProbabilitySliceIndex(getProbabilityHandle func (data T) float64, data ...T) (hit T, index int, miss bool) +#### func ProbabilitySliceIndex\[T any\](getProbabilityHandle func (data T) float64, data ...T) (hit T, index int, miss bool) > 按概率随机从切片中产生一个数据并返回命中的对象及对象索引以及是否未命中 > - 当总概率小于 1 将会发生未命中的情况 *** -#### func Probability(p int, full ...int) bool +#### func Probability(p int, full ...int) bool > 输入一个概率，返回是否命中 > - 当 full 不为空时，将以 full 为基数，p 为分子，计算命中概率 *** -#### func ProbabilityChooseOne(ps ...int) int +#### func ProbabilityChooseOne(ps ...int) int > 输入一组概率，返回命中的索引 @@ -168,54 +174,54 @@ func TestProbabilitySlice(t *testing.T) { *** -#### func ChineseName() string +#### func ChineseName() string > 返回一个随机组成的中文姓名。 *** -#### func EnglishName() string +#### func EnglishName() string > 返回一个随机组成的英文姓名。 *** -#### func Name() string +#### func Name() string > 返回一个随机组成的中文或英文姓名 > - 以1/2的概率决定生产的是中文还是英文姓名。 *** -#### func NumberString(min int, max int) string +#### func NumberString(min int, max int) string > 返回一个介于min和max之间的string类型的随机数。 *** -#### func NumberStringRepair(min int, max int) string +#### func NumberStringRepair(min int, max int) string > 返回一个介于min和max之间的string类型的随机数 > - 通过Int64生成一个随机数，当结果的字符串长度小于max的字符串长度的情况下，使用0在开头补齐。 *** -#### func HostName() string +#### func HostName() string > 返回一个随机产生的hostname。 *** -#### func WeightSlice(getWeightHandle func (data T) int64, data ...T) T +#### func WeightSlice\[T any\](getWeightHandle func (data T) int64, data ...T) T > 按权重随机从切片中产生一个数据并返回 *** -#### func WeightSliceIndex(getWeightHandle func (data T) int64, data ...T) (item T, index int) +#### func WeightSliceIndex\[T any\](getWeightHandle func (data T) int64, data ...T) (item T, index int) > 按权重随机从切片中产生一个数据并返回数据和对应索引 *** -#### func WeightMap(getWeightHandle func (data T) int64, data map[K]T) T +#### func WeightMap\[K comparable, T any\](getWeightHandle func (data T) int64, data map[K]T) T > 按权重随机从map中产生一个数据并返回 *** -#### func WeightMapKey(getWeightHandle func (data T) int64, data map[K]T) (item T, key K) +#### func WeightMapKey\[K comparable, T any\](getWeightHandle func (data T) int64, data map[K]T) (item T, key K) > 按权重随机从map中产生一个数据并返回数据和对应 key diff --git a/utils/random/ip.go b/utils/random/ip.go index 952552f..862af97 100644 --- a/utils/random/ip.go +++ b/utils/random/ip.go @@ -15,6 +15,20 @@ func Port() int { return Int(1, 65535) } +// UsablePort 随机返回一个可用的端口号，如果没有可用端口号则返回 -1 +func UsablePort() int { + addr, err := net.ResolveTCPAddr("tcp", "127.0.0.1:0") + if err != nil { + return -1 + } + cli, err := net.ListenTCP("tcp", addr) + if err != nil { + return -1 + } + defer func() { _ = cli.Close() }() + return cli.Addr().(*net.TCPAddr).Port +} + // IPv4 返回一个随机产生的IPv4地址。 func IPv4() string { return fmt.Sprintf("%d.%d.%d.%d", Int(1, 255), Int(0, 255), Int(0, 255), Int(0, 255)) diff --git a/utils/reflects/README.md b/utils/reflects/README.md index bf685e0..63f0ea6 100644 --- a/utils/reflects/README.md +++ b/utils/reflects/README.md @@ -32,27 +32,27 @@ *** ## 详情信息 -#### func WrapperFunc(f any, wrapper func (call func ( []reflect.Value) []reflect.Value) func (args []reflect.Value) []reflect.Value) (wf Func, err error) +#### func WrapperFunc\[Func any\](f any, wrapper func (call func ( []reflect.Value) []reflect.Value) func (args []reflect.Value) []reflect.Value) (wf Func, err error) > 包装函数 *** -#### func WrapperFuncBefore2After(f Func, before func (), after func ()) (wf Func, err error) +#### func WrapperFuncBefore2After\[Func any\](f Func, before func (), after func ()) (wf Func, err error) > 包装函数，前置函数执行前，后置函数执行后 *** -#### func WrapperFuncBefore(f Func, before func ()) (wf Func, err error) +#### func WrapperFuncBefore\[Func any\](f Func, before func ()) (wf Func, err error) > 包装函数，前置函数执行前 *** -#### func WrapperFuncAfter(f Func, after func ()) (wf Func, err error) +#### func WrapperFuncAfter\[Func any\](f Func, after func ()) (wf Func, err error) > 包装函数，后置函数执行后 *** -#### func GetPtrUnExportFiled(s reflect.Value, filedIndex int) reflect.Value +#### func GetPtrUnExportFiled(s reflect.Value, filedIndex int) reflect.Value > 获取指针类型的未导出字段 @@ -62,12 +62,12 @@ > 设置指针类型的未导出字段 *** -#### func Copy(s reflect.Value) reflect.Value +#### func Copy(s reflect.Value) reflect.Value > 拷贝 *** -#### func GetPointer(src T) reflect.Value +#### func GetPointer\[T any\](src T) reflect.Value > 获取指针 diff --git a/utils/runtimes/README.md b/utils/runtimes/README.md index 63c3494..b716fdb 100644 --- a/utils/runtimes/README.md +++ b/utils/runtimes/README.md @@ -29,27 +29,27 @@ *** ## 详情信息 -#### func GetWorkingDir() string +#### func GetWorkingDir() string > 获取工作目录绝对路径 *** -#### func GetTempDir() string +#### func GetTempDir() string > 获取系统临时目录 *** -#### func GetExecutablePathByBuild() string +#### func GetExecutablePathByBuild() string > 获取当前执行文件绝对路径（go build） *** -#### func GetExecutablePathByCaller() string +#### func GetExecutablePathByCaller() string > 获取当前执行文件绝对路径（go run） *** -#### func CurrentRunningFuncName(skip ...int) string +#### func CurrentRunningFuncName(skip ...int) string > 获取正在运行的函数名 diff --git a/utils/sole/README.md b/utils/sole/README.md index b02da32..0bfd023 100644 --- a/utils/sole/README.md +++ b/utils/sole/README.md @@ -38,7 +38,7 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[Once](#once)|用于数据取值去重的结构体 +|`STRUCT`|[Once](#struct_Once)|用于数据取值去重的结构体 @@ -55,7 +55,7 @@ > 解除注销特定命名空间的唯一标识符 *** -#### func Get() int64 +#### func Get() int64 > 获取全局唯一标识符 @@ -65,7 +65,7 @@ > 重置全局唯一标识符 *** -#### func GetWith(name any) int64 +#### func GetWith(name any) int64 > 获取特定命名空间的唯一标识符 @@ -75,17 +75,17 @@ > 重置特定命名空间的唯一标识符 *** -#### func NewOnce() *Once[V] +#### func NewOnce\[V any\]() *Once[V] > 创建一个用于数据取值去重的结构实例 *** -#### func SonyflakeIDE() int64, error +#### func SonyflakeIDE() (int64, error) > 获取一个雪花id *** -#### func SonyflakeID() int64 +#### func SonyflakeID() int64 > 获取一个雪花id @@ -95,36 +95,37 @@ > 配置雪花id生成策略 *** -#### func AutoIncrementUint32() uint32 +#### func AutoIncrementUint32() uint32 > 获取一个自增的 uint32 值 *** -#### func AutoIncrementUint64() uint64 +#### func AutoIncrementUint64() uint64 > 获取一个自增的 uint64 值 *** -#### func AutoIncrementInt32() int32 +#### func AutoIncrementInt32() int32 > 获取一个自增的 int32 值 *** -#### func AutoIncrementInt64() int64 +#### func AutoIncrementInt64() int64 > 获取一个自增的 int64 值 *** -#### func AutoIncrementInt() int +#### func AutoIncrementInt() int > 获取一个自增的 int 值 *** -#### func AutoIncrementString() string +#### func AutoIncrementString() string > 获取一个自增的字符串 *** + ### Once `STRUCT` 用于数据取值去重的结构体 ```go @@ -132,9 +133,15 @@ type Once[V any] struct { r map[any]struct{} } ``` + + #### func (*Once) Get(key any, value V, defaultValue V) V > 获取一个值，当该值已经被获取过的时候，返回 defaultValue，否则返回 value + *** + + #### func (*Once) Reset(key ...any) > 当 key 数量大于 0 时，将会重置对应 key 的记录，否则重置所有记录 + *** diff --git a/utils/sorts/README.md b/utils/sorts/README.md index 6375347..57fc082 100644 --- a/utils/sorts/README.md +++ b/utils/sorts/README.md @@ -25,7 +25,7 @@ *** ## 详情信息 -#### func Topological(slice S, queryIndexHandler func (item V) Index, queryDependsHandler func (item V) []Index) S, error +#### func Topological\[S ~[]V, Index comparable, V any\](slice S, queryIndexHandler func (item V) Index, queryDependsHandler func (item V) []Index) (S, error) > 拓扑排序是一种对有向图进行排序的算法，它可以用来解决一些依赖关系的问题，比如计算字段的依赖关系。拓扑排序会将存在依赖关系的元素进行排序，使得依赖关系的元素总是排在被依赖的元素之前。 > - slice: 需要排序的切片 @@ -34,7 +34,8 @@ > > 该函数在存在循环依赖的情况下将会返回 ErrCircularDependencyDetected 错误 -示例代码： +**示例代码：** + ```go func ExampleTopological() { diff --git a/utils/str/README.md b/utils/str/README.md index 04e35d0..a0d020a 100644 --- a/utils/str/README.md +++ b/utils/str/README.md @@ -46,7 +46,7 @@ *** ## 详情信息 -#### func RangeLine(eachString string, eachFunc func (index int, line string) error) error +#### func RangeLine(eachString string, eachFunc func (index int, line string) error) error > 对传入的eachString进行按行切片后再进行遍历 > - 该函数会预先对“\r\n”进行处理替换为“\n”。 @@ -54,72 +54,72 @@ > - index表示了当前行的行号（由0开始），line表示了当前行的内容。 *** -#### func SplitTrimSpace(str string, sep string) []string +#### func SplitTrimSpace(str string, sep string) []string > 按照空格分割字符串并去除空格 *** -#### func FirstUpper(str string) string +#### func FirstUpper(str string) string > 首字母大写 *** -#### func FirstLower(str string) string +#### func FirstLower(str string) string > 首字母小写 *** -#### func FirstUpperBytes(str []byte) []byte +#### func FirstUpperBytes(str []byte) []byte > 首字母大写 *** -#### func FirstLowerBytes(str []byte) []byte +#### func FirstLowerBytes(str []byte) []byte > 首字母小写 *** -#### func IsEmpty(str string) bool +#### func IsEmpty(str string) bool > 判断字符串是否为空 *** -#### func IsEmptyBytes(str []byte) bool +#### func IsEmptyBytes(str []byte) bool > 判断字符串是否为空 *** -#### func IsNotEmpty(str string) bool +#### func IsNotEmpty(str string) bool > 判断字符串是否不为空 *** -#### func IsNotEmptyBytes(str []byte) bool +#### func IsNotEmptyBytes(str []byte) bool > 判断字符串是否不为空 *** -#### func SnakeString(str string) string +#### func SnakeString(str string) string > 蛇形字符串 *** -#### func SnakeStringBytes(str []byte) []byte +#### func SnakeStringBytes(str []byte) []byte > 蛇形字符串 *** -#### func CamelString(str string) string +#### func CamelString(str string) string > 驼峰字符串 *** -#### func CamelStringBytes(str []byte) []byte +#### func CamelStringBytes(str []byte) []byte > 驼峰字符串 *** -#### func SortJoin(delimiter string, s ...string) string +#### func SortJoin(delimiter string, s ...string) string > 将多个字符串排序后拼接 @@ -130,19 +130,19 @@ > - 隐藏身份证、邮箱、手机号等敏感信息用*号替代 *** -#### func ThousandsSeparator(str string) string +#### func ThousandsSeparator(str string) string > 返回将str进行千位分隔符处理后的字符串。 *** -#### func KV(str string, tag ...string) string, string +#### func KV(str string, tag ...string) (string, string) > 返回str经过转换后形成的key、value > - 这里tag表示使用什么字符串来区分key和value的分隔符。 > - 默认情况即不传入tag的情况下分隔符为“=”。 *** -#### func FormatSpeedyInt(numberStr string) int, error +#### func FormatSpeedyInt(numberStr string) (int, error) > 返回numberStr经过格式化后去除空格和“,”分隔符的结果 > - 当字符串为“123,456,789”的时候，返回结果为“123456789”。 @@ -150,7 +150,7 @@ > - 当字符串为“1 23, 45 6, 789”的时候，返回结果为“123456789”。 *** -#### func FormatSpeedyInt64(numberStr string) int64, error +#### func FormatSpeedyInt64(numberStr string) (int64, error) > 返回numberStr经过格式化后去除空格和“,”分隔符的结果 > - 当字符串为“123,456,789”的时候，返回结果为“123456789”。 @@ -158,7 +158,7 @@ > - 当字符串为“1 23, 45 6, 789”的时候，返回结果为“123456789”。 *** -#### func FormatSpeedyFloat32(numberStr string) float64, error +#### func FormatSpeedyFloat32(numberStr string) (float64, error) > 返回numberStr经过格式化后去除空格和“,”分隔符的结果 > - 当字符串为“123,456,789.123”的时候，返回结果为“123456789.123”。 @@ -166,7 +166,7 @@ > - 当字符串为“1 23, 45 6, 789.123”的时候，返回结果为“123456789.123”。 *** -#### func FormatSpeedyFloat64(numberStr string) float64, error +#### func FormatSpeedyFloat64(numberStr string) (float64, error) > 返回numberStr经过格式化后去除空格和“,”分隔符的结果 > - 当字符串为“123,456,789.123”的时候，返回结果为“123456789.123”。 diff --git a/utils/super/README.md b/utils/super/README.md index b3561fb..8b40832 100644 --- a/utils/super/README.md +++ b/utils/super/README.md @@ -19,6 +19,8 @@ |[NewBitSet](#NewBitSet)|通过指定的 Bit 位创建一个 BitSet |[TryWriteChannel](#TryWriteChannel)|尝试写入 channel，如果 channel 无法写入则忽略，返回是否写入成功 |[TryWriteChannelByHandler](#TryWriteChannelByHandler)|尝试写入 channel，如果 channel 无法写入则执行 handler +|[TryReadChannel](#TryReadChannel)|尝试读取 channel，如果 channel 无法读取则忽略，返回是否读取成功 +|[TryReadChannelByHandler](#TryReadChannelByHandler)|尝试读取 channel，如果 channel 无法读取则执行 handler |[RegError](#RegError)|通过错误码注册错误，返回错误的引用 |[RegErrorRef](#RegErrorRef)|通过错误码注册错误，返回错误的引用 |[GetError](#GetError)|通过错误引用获取错误码和真实错误信息，如果错误不存在则返回 0，如果错误引用不存在则返回原本的错误 @@ -92,47 +94,103 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[BitSet](#bitset)|是一个可以动态增长的比特位集合 -|`STRUCT`|[LossCounter](#losscounter)|暂无描述... -|`STRUCT`|[Matcher](#matcher)|匹配器 -|`STRUCT`|[Permission](#permission)|暂无描述... -|`STRUCT`|[StackGo](#stackgo)|用于获取上一个协程调用的堆栈信息 -|`STRUCT`|[VerifyHandle](#verifyhandle)|校验句柄 +|`STRUCT`|[BitSet](#struct_BitSet)|是一个可以动态增长的比特位集合 +|`STRUCT`|[LossCounter](#struct_LossCounter)|暂无描述... +|`STRUCT`|[Matcher](#struct_Matcher)|匹配器 +|`STRUCT`|[Permission](#struct_Permission)|暂无描述... +|`STRUCT`|[StackGo](#struct_StackGo)|用于获取上一个协程调用的堆栈信息 +|`STRUCT`|[VerifyHandle](#struct_VerifyHandle)|校验句柄 *** ## 详情信息 -#### func NewBitSet(bits ...Bit) *BitSet[Bit] +#### func NewBitSet\[Bit generic.Integer\](bits ...Bit) *BitSet[Bit] > 通过指定的 Bit 位创建一个 BitSet +> - 当指定的 Bit 位存在负数时，将会 panic + +**示例代码：** + +```go + +func ExampleNewBitSet() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Set(10) + fmt.Println(bs.Bits()) +} + +``` + +
+查看 / 收起单元测试 + + +```go + +func TestNewBitSet(t *testing.T) { + var cases = []struct { + name string + in []int + shouldPanic bool + }{{name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, {name: "empty", in: make([]int, 0)}, {name: "nil", in: nil}, {name: "negative", in: []int{-1, -2}, shouldPanic: true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet(c.in...) + t.Log(bs) + }) + } +} + +``` + + +
+ *** -#### func TryWriteChannel(ch chan T, data T) bool +#### func TryWriteChannel\[T any\](ch chan T, data T) bool > 尝试写入 channel，如果 channel 无法写入则忽略，返回是否写入成功 > - 无法写入的情况包括：channel 已满、channel 已关闭 *** -#### func TryWriteChannelByHandler(ch chan T, data T, handler func ()) +#### func TryWriteChannelByHandler\[T any\](ch chan T, data T, handler func ()) > 尝试写入 channel，如果 channel 无法写入则执行 handler > - 无法写入的情况包括：channel 已满、channel 已关闭 *** -#### func RegError(code int, message string) error +#### func TryReadChannel\[T any\](ch chan T) (v T, suc bool) + +> 尝试读取 channel，如果 channel 无法读取则忽略，返回是否读取成功 +> - 无法读取的情况包括：channel 已空、channel 已关闭 + +*** +#### func TryReadChannelByHandler\[T any\](ch chan T, handler func (ch chan T) T) (v T) + +> 尝试读取 channel，如果 channel 无法读取则执行 handler +> - 无法读取的情况包括：channel 已空、channel 已关闭 + +*** +#### func RegError(code int, message string) error > 通过错误码注册错误，返回错误的引用 *** -#### func RegErrorRef(code int, message string, ref error) error +#### func RegErrorRef(code int, message string, ref error) error > 通过错误码注册错误，返回错误的引用 > - 引用将会被重定向到注册的错误信息 *** -#### func GetError(err error) int, error +#### func GetError(err error) (int, error) > 通过错误引用获取错误码和真实错误信息，如果错误不存在则返回 0，如果错误引用不存在则返回原本的错误 @@ -155,11 +213,12 @@ func TestGetError(t *testing.T) { *** -#### func RecoverTransform(a any) error +#### func RecoverTransform(a any) error > recover 错误转换 -示例代码： +**示例代码：** + ```go func ExampleRecoverTransform() { @@ -179,12 +238,12 @@ func ExampleRecoverTransform() { > 执行 f 函数，如果 f 为 nil，则不执行 *** -#### func HandleErr(f func () error) error +#### func HandleErr(f func () error) error > 执行 f 函数，如果 f 为 nil，则不执行 *** -#### func HandleV(v V, f func (v V)) +#### func HandleV\[V any\](v V, f func (v V)) > 执行 f 函数，如果 f 为 nil，则不执行 @@ -194,43 +253,43 @@ func ExampleRecoverTransform() { > go 代码格式化 *** -#### func If(expression bool, t T, f T) T +#### func If\[T any\](expression bool, t T, f T) T *** -#### func MarshalJSON(v interface {}) []byte +#### func MarshalJSON(v interface {}) []byte > 将对象转换为 json > - 当转换失败时，将返回 json 格式的空对象 *** -#### func MarshalJSONE(v interface {}) []byte, error +#### func MarshalJSONE(v interface {}) ([]byte, error) > 将对象转换为 json > - 当转换失败时，将返回错误信息 *** -#### func UnmarshalJSON(data []byte, v interface {}) error +#### func UnmarshalJSON(data []byte, v interface {}) error > 将 json 转换为对象 *** -#### func MarshalIndentJSON(v interface {}, prefix string, indent string) []byte +#### func MarshalIndentJSON(v interface {}, prefix string, indent string) []byte > 将对象转换为 json *** -#### func MarshalToTargetWithJSON(src interface {}, dest interface {}) error +#### func MarshalToTargetWithJSON(src interface {}, dest interface {}) error > 将对象转换为目标对象 *** -#### func StartLossCounter() *LossCounter +#### func StartLossCounter() *LossCounter > 开始损耗计数 *** -#### func Match(value Value) *Matcher[Value, Result] +#### func Match\[Value any, Result any\](value Value) *Matcher[Value, Result] > 匹配 @@ -255,12 +314,12 @@ func TestMatch(t *testing.T) { *** -#### func IsNumber(v any) bool +#### func IsNumber(v any) bool > 判断是否为数字 *** -#### func NumberToRome(num int) string +#### func NumberToRome(num int) string > 将数字转换为罗马数字 @@ -290,167 +349,167 @@ func TestNumberToRome(t *testing.T) { *** -#### func StringToInt(value string) int +#### func StringToInt(value string) int > 字符串转换为整数 *** -#### func StringToFloat64(value string) float64 +#### func StringToFloat64(value string) float64 > 字符串转换为 float64 *** -#### func StringToBool(value string) bool +#### func StringToBool(value string) bool > 字符串转换为 bool *** -#### func StringToUint64(value string) uint64 +#### func StringToUint64(value string) uint64 > 字符串转换为 uint64 *** -#### func StringToUint(value string) uint +#### func StringToUint(value string) uint > 字符串转换为 uint *** -#### func StringToFloat32(value string) float32 +#### func StringToFloat32(value string) float32 > 字符串转换为 float32 *** -#### func StringToInt64(value string) int64 +#### func StringToInt64(value string) int64 > 字符串转换为 int64 *** -#### func StringToUint32(value string) uint32 +#### func StringToUint32(value string) uint32 > 字符串转换为 uint32 *** -#### func StringToInt32(value string) int32 +#### func StringToInt32(value string) int32 > 字符串转换为 int32 *** -#### func StringToUint16(value string) uint16 +#### func StringToUint16(value string) uint16 > 字符串转换为 uint16 *** -#### func StringToInt16(value string) int16 +#### func StringToInt16(value string) int16 > 字符串转换为 int16 *** -#### func StringToUint8(value string) uint8 +#### func StringToUint8(value string) uint8 > 字符串转换为 uint8 *** -#### func StringToInt8(value string) int8 +#### func StringToInt8(value string) int8 > 字符串转换为 int8 *** -#### func StringToByte(value string) byte +#### func StringToByte(value string) byte > 字符串转换为 byte *** -#### func StringToRune(value string) rune +#### func StringToRune(value string) rune > 字符串转换为 rune *** -#### func IntToString(value int) string +#### func IntToString(value int) string > 整数转换为字符串 *** -#### func Float64ToString(value float64) string +#### func Float64ToString(value float64) string > float64 转换为字符串 *** -#### func BoolToString(value bool) string +#### func BoolToString(value bool) string > bool 转换为字符串 *** -#### func Uint64ToString(value uint64) string +#### func Uint64ToString(value uint64) string > uint64 转换为字符串 *** -#### func UintToString(value uint) string +#### func UintToString(value uint) string > uint 转换为字符串 *** -#### func Float32ToString(value float32) string +#### func Float32ToString(value float32) string > float32 转换为字符串 *** -#### func Int64ToString(value int64) string +#### func Int64ToString(value int64) string > int64 转换为字符串 *** -#### func Uint32ToString(value uint32) string +#### func Uint32ToString(value uint32) string > uint32 转换为字符串 *** -#### func Int32ToString(value int32) string +#### func Int32ToString(value int32) string > int32 转换为字符串 *** -#### func Uint16ToString(value uint16) string +#### func Uint16ToString(value uint16) string > uint16 转换为字符串 *** -#### func Int16ToString(value int16) string +#### func Int16ToString(value int16) string > int16 转换为字符串 *** -#### func Uint8ToString(value uint8) string +#### func Uint8ToString(value uint8) string > uint8 转换为字符串 *** -#### func Int8ToString(value int8) string +#### func Int8ToString(value int8) string > int8 转换为字符串 *** -#### func ByteToString(value byte) string +#### func ByteToString(value byte) string > byte 转换为字符串 *** -#### func RuneToString(value rune) string +#### func RuneToString(value rune) string > rune 转换为字符串 *** -#### func StringToSlice(value string) []string +#### func StringToSlice(value string) []string > 字符串转换为切片 *** -#### func SliceToString(value []string) string +#### func SliceToString(value []string) string > 切片转换为字符串 *** -#### func NewPermission() *Permission[Code, EntityID] +#### func NewPermission\[Code generic.Integer, EntityID comparable\]() *Permission[Code, EntityID] > 创建权限 @@ -488,19 +547,19 @@ func TestNewPermission(t *testing.T) { *** -#### func Retry(count int, interval time.Duration, f func () error) error +#### func Retry(count int, interval time.Duration, f func () error) error > 根据提供的 count 次数尝试执行 f 函数，如果 f 函数返回错误，则在 interval 后重试，直到成功或者达到 count 次数 *** -#### func RetryByRule(f func () error, rule func (count int) time.Duration) error +#### func RetryByRule(f func () error, rule func (count int) time.Duration) error > 根据提供的规则尝试执行 f 函数，如果 f 函数返回错误，则根据 rule 的返回值进行重试 > - rule 将包含一个入参，表示第几次重试，返回值表示下一次重试的时间间隔，当返回值为 0 时，表示不再重试 > - rule 的 count 将在 f 首次失败后变为 1，因此 rule 的入参将从 1 开始 *** -#### func RetryByExponentialBackoff(f func () error, maxRetries int, baseDelay time.Duration, maxDelay time.Duration, multiplier float64, randomization float64, ignoreErrors ...error) error +#### func RetryByExponentialBackoff(f func () error, maxRetries int, baseDelay time.Duration, maxDelay time.Duration, multiplier float64, randomization float64, ignoreErrors ...error) error > 根据指数退避算法尝试执行 f 函数 > - maxRetries：最大重试次数 @@ -511,7 +570,7 @@ func TestNewPermission(t *testing.T) { > - ignoreErrors：忽略的错误，当 f 返回的错误在 ignoreErrors 中时，将不会进行重试 *** -#### func ConditionalRetryByExponentialBackoff(f func () error, cond func () bool, maxRetries int, baseDelay time.Duration, maxDelay time.Duration, multiplier float64, randomization float64, ignoreErrors ...error) error +#### func ConditionalRetryByExponentialBackoff(f func () error, cond func () bool, maxRetries int, baseDelay time.Duration, maxDelay time.Duration, multiplier float64, randomization float64, ignoreErrors ...error) error > 该函数与 RetryByExponentialBackoff 类似，但是可以被中断 > - cond 为中断条件，当 cond 返回 false 时，将会中断重试 @@ -532,37 +591,37 @@ func TestNewPermission(t *testing.T) { > 根据提供的 interval 时间间隔尝试执行 f 函数，如果 f 函数返回错误，则在 interval 后重试，直到成功 *** -#### func NewStackGo() *StackGo +#### func NewStackGo() *StackGo > 返回一个用于获取上一个协程调用的堆栈信息的收集器 *** -#### func LaunchTime() time.Time +#### func LaunchTime() time.Time > 获取程序启动时间 *** -#### func Hostname() string +#### func Hostname() string > 获取主机名 *** -#### func PID() int +#### func PID() int > 获取进程 PID *** -#### func StringToBytes(s string) []byte +#### func StringToBytes(s string) []byte > 以零拷贝的方式将字符串转换为字节切片 *** -#### func BytesToString(b []byte) string +#### func BytesToString(b []byte) string > 以零拷贝的方式将字节切片转换为字符串 *** -#### func Convert(src A) B +#### func Convert\[A any, B any\](src A) B > 以零拷贝的方式将一个对象转换为另一个对象 > - 两个对象字段必须完全一致 @@ -591,11 +650,12 @@ func TestConvert(t *testing.T) { *** -#### func Verify(handle func ( V)) *VerifyHandle[V] +#### func Verify\[V any\](handle func ( V)) *VerifyHandle[V] > 对特定表达式进行校验，当表达式不成立时，将执行 handle -示例代码： +**示例代码：** + ```go func ExampleVerify() { @@ -618,11 +678,12 @@ func ExampleVerify() { ``` *** -#### func OldVersion(version1 string, version2 string) bool +#### func OldVersion(version1 string, version2 string) bool > 检查 version2 对于 version1 来说是不是旧版本 -示例代码： +**示例代码：** + ```go func ExampleOldVersion() { @@ -677,14 +738,15 @@ func BenchmarkOldVersion(b *testing.B) { *** -#### func CompareVersion(version1 string, version2 string) int +#### func CompareVersion(version1 string, version2 string) int > 返回一个整数，用于表示两个版本号的比较结果： > - 如果 version1 大于 version2，它将返回 1 > - 如果 version1 小于 version2，它将返回 -1 > - 如果 version1 和 version2 相等，它将返回 0 -示例代码： +**示例代码：** + ```go func ExampleCompareVersion() { @@ -739,6 +801,7 @@ func BenchmarkCompareVersion(b *testing.B) { *** + ### BitSet `STRUCT` 是一个可以动态增长的比特位集合 - 默认情况下将使用 64 位无符号整数来表示比特位，当需要表示的比特位超过 64 位时，将自动增长 @@ -747,8 +810,23 @@ type BitSet[Bit generic.Integer] struct { set []uint64 } ``` + + #### func (*BitSet) Set(bit Bit) *BitSet[Bit] > 将指定的位 bit 设置为 1 + +**示例代码：** + +```go + +func ExampleBitSet_Set() { + var bs = super.NewBitSet[int]() + bs.Set(10) + fmt.Println(bs.Bits()) +} + +``` +
查看 / 收起单元测试 @@ -756,11 +834,29 @@ type BitSet[Bit generic.Integer] struct { ```go func TestBitSet_Set(t *testing.T) { - bs := super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) - bs.Set(11) - bs.Set(12) - bs.Set(13) - t.Log(bs) + var cases = []struct { + name string + in []int + shouldPanic bool + }{{name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, {name: "empty", in: make([]int, 0)}, {name: "nil", in: nil}, {name: "negative", in: []int{-1, -2}, shouldPanic: true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet[int]() + for _, bit := range c.in { + bs.Set(bit) + } + for _, bit := range c.in { + if !bs.Has(bit) { + t.Fatalf("bit %v not set", bit) + } + } + }) + } } ``` @@ -770,8 +866,23 @@ func TestBitSet_Set(t *testing.T) { *** + + #### func (*BitSet) Del(bit Bit) *BitSet[Bit] > 将指定的位 bit 设置为 0 + +**示例代码：** + +```go + +func ExampleBitSet_Del() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Del(1) + fmt.Println(bs.Bits()) +} + +``` +
查看 / 收起单元测试 @@ -779,12 +890,32 @@ func TestBitSet_Set(t *testing.T) { ```go func TestBitSet_Del(t *testing.T) { - bs := super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) - bs.Del(11) - bs.Del(12) - bs.Del(13) - bs.Del(10) - t.Log(bs) + var cases = []struct { + name string + in []int + shouldPanic bool + }{{name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, {name: "empty", in: make([]int, 0)}, {name: "nil", in: nil}, {name: "negative", in: []int{-1, -2}, shouldPanic: true}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet[int]() + for _, bit := range c.in { + bs.Set(bit) + } + for _, bit := range c.in { + bs.Del(bit) + } + for _, bit := range c.in { + if bs.Has(bit) { + t.Fatalf("bit %v not del", bit) + } + } + }) + } } ``` @@ -794,9 +925,27 @@ func TestBitSet_Del(t *testing.T) { *** + + #### func (*BitSet) Shrink() *BitSet[Bit] > 将 BitSet 中的比特位集合缩小到最小 > - 正常情况下当 BitSet 中的比特位超出 64 位时，将自动增长，当 BitSet 中的比特位数量减少时，可以使用该方法将 BitSet 中的比特位集合缩小到最小 + +**示例代码：** + +```go + +func ExampleBitSet_Shrink() { + var bs = super.NewBitSet(111, 222, 333, 444) + fmt.Println(bs.Cap()) + bs.Del(444) + fmt.Println(bs.Cap()) + bs.Shrink() + fmt.Println(bs.Cap()) +} + +``` +
查看 / 收起单元测试 @@ -804,13 +953,22 @@ func TestBitSet_Del(t *testing.T) { ```go func TestBitSet_Shrink(t *testing.T) { - bs := super.NewBitSet(63) - t.Log(bs.Cap()) - bs.Set(200) - t.Log(bs.Cap()) - bs.Del(200) - bs.Shrink() - t.Log(bs.Cap()) + var cases = []struct { + name string + in []int + }{{name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, {name: "empty", in: make([]int, 0)}, {name: "nil", in: nil}} + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + bs := super.NewBitSet(c.in...) + for _, v := range c.in { + bs.Del(v) + } + bs.Shrink() + if bs.Cap() != 0 { + t.Fatalf("cap %v != 0", bs.Cap()) + } + }) + } } ``` @@ -820,93 +978,227 @@ func TestBitSet_Shrink(t *testing.T) { *** + + #### func (*BitSet) Cap() int > 返回当前 BitSet 中可以表示的最大比特位数量 + +**示例代码：** + +```go + +func ExampleBitSet_Cap() { + var bs = super.NewBitSet(63) + fmt.Println(bs.Cap()) +} + +``` + *** + + #### func (*BitSet) Has(bit Bit) bool > 检查指定的位 bit 是否被设置为 1 + +**示例代码：** + +```go + +func ExampleBitSet_Has() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + fmt.Println(bs.Has(1)) + fmt.Println(bs.Has(10)) +} + +``` + *** + + #### func (*BitSet) Clear() *BitSet[Bit] > 清空所有的比特位 + +**示例代码：** + +```go + +func ExampleBitSet_Clear() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Clear() + fmt.Println(bs.Bits()) +} + +``` + *** + + #### func (*BitSet) Len() int > 返回当前 BitSet 中被设置的比特位数量 + +**示例代码：** + +```go + +func ExampleBitSet_Len() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + fmt.Println(bs.Len()) +} + +``` + *** + + #### func (*BitSet) Bits() []Bit > 返回当前 BitSet 中被设置的比特位 + *** + + #### func (*BitSet) Reverse() *BitSet[Bit] > 反转当前 BitSet 中的所有比特位 + *** + + #### func (*BitSet) Not() *BitSet[Bit] > 返回当前 BitSet 中所有比特位的反转 + *** + + #### func (*BitSet) And(other *BitSet[Bit]) *BitSet[Bit] > 将当前 BitSet 与另一个 BitSet 进行按位与运算 + *** + + #### func (*BitSet) Or(other *BitSet[Bit]) *BitSet[Bit] > 将当前 BitSet 与另一个 BitSet 进行按位或运算 + *** + + #### func (*BitSet) Xor(other *BitSet[Bit]) *BitSet[Bit] > 将当前 BitSet 与另一个 BitSet 进行按位异或运算 + *** + + #### func (*BitSet) Sub(other *BitSet[Bit]) *BitSet[Bit] > 将当前 BitSet 与另一个 BitSet 进行按位减运算 + *** + + #### func (*BitSet) IsZero() bool > 检查当前 BitSet 是否为空 + *** + + #### func (*BitSet) Clone() *BitSet[Bit] > 返回当前 BitSet 的副本 + *** + + #### func (*BitSet) Equal(other *BitSet[Bit]) bool > 检查当前 BitSet 是否与另一个 BitSet 相等 + *** + + #### func (*BitSet) Contains(other *BitSet[Bit]) bool > 检查当前 BitSet 是否包含另一个 BitSet + *** + + #### func (*BitSet) ContainsAny(other *BitSet[Bit]) bool > 检查当前 BitSet 是否包含另一个 BitSet 中的任意比特位 + *** + + #### func (*BitSet) ContainsAll(other *BitSet[Bit]) bool > 检查当前 BitSet 是否包含另一个 BitSet 中的所有比特位 + *** + + #### func (*BitSet) Intersect(other *BitSet[Bit]) bool > 检查当前 BitSet 是否与另一个 BitSet 有交集 + *** + + #### func (*BitSet) Union(other *BitSet[Bit]) bool > 检查当前 BitSet 是否与另一个 BitSet 有并集 + *** + + #### func (*BitSet) Difference(other *BitSet[Bit]) bool > 检查当前 BitSet 是否与另一个 BitSet 有差集 + *** + + #### func (*BitSet) SymmetricDifference(other *BitSet[Bit]) bool > 检查当前 BitSet 是否与另一个 BitSet 有对称差集 + *** + + #### func (*BitSet) Subset(other *BitSet[Bit]) bool > 检查当前 BitSet 是否为另一个 BitSet 的子集 + *** + + #### func (*BitSet) Superset(other *BitSet[Bit]) bool > 检查当前 BitSet 是否为另一个 BitSet 的超集 + *** + + #### func (*BitSet) Complement(other *BitSet[Bit]) bool > 检查当前 BitSet 是否为另一个 BitSet 的补集 + *** + + #### func (*BitSet) Max() Bit > 返回当前 BitSet 中最大的比特位 + *** + + #### func (*BitSet) Min() Bit > 返回当前 BitSet 中最小的比特位 + *** + + #### func (*BitSet) String() string > 返回当前 BitSet 的字符串表示 + *** -#### func (*BitSet) MarshalJSON() []byte, error + + +#### func (*BitSet) MarshalJSON() ( []byte, error) > 实现 json.Marshaler 接口 + *** + + #### func (*BitSet) UnmarshalJSON(data []byte) error > 实现 json.Unmarshaler 接口 + *** + ### LossCounter `STRUCT` ```go @@ -916,14 +1208,24 @@ type LossCounter struct { lossKey []string } ``` + + #### func (*LossCounter) Record(name string) > 记录一次损耗 + *** + + #### func (*LossCounter) GetLoss(handler func (step int, name string, loss time.Duration)) > 获取损耗 + *** + + #### func (*LossCounter) String() string + *** + ### Matcher `STRUCT` 匹配器 ```go @@ -933,6 +1235,19 @@ type Matcher[Value any, Result any] struct { d bool } ``` + + +#### func (*Matcher) Case(value Value, result Result) *Matcher[Value, Result] +> 匹配 + +*** + + +#### func (*Matcher) Default(value Result) Result +> 默认 + +*** + ### Permission `STRUCT` ```go @@ -941,6 +1256,31 @@ type Permission[Code generic.Integer, EntityID comparable] struct { l sync.RWMutex } ``` + + +#### func (*Permission) HasPermission(entityId EntityID, permission Code) bool +> 是否有权限 + +*** + + +#### func (*Permission) AddPermission(entityId EntityID, permission ...Code) +> 添加权限 + +*** + + +#### func (*Permission) RemovePermission(entityId EntityID, permission ...Code) +> 移除权限 + +*** + + +#### func (*Permission) SetPermission(entityId EntityID, permission ...Code) +> 设置权限 + +*** + ### StackGo `STRUCT` 用于获取上一个协程调用的堆栈信息 - 应当最先运行 Wait 函数，然后在其他协程中调用 Stack 函数或者 GiveUp 函数 @@ -951,20 +1291,30 @@ type StackGo struct { collect chan []byte } ``` + + #### func (*StackGo) Wait() > 等待收集消息堆栈 > - 在调用 Wait 函数后，当前协程将会被挂起，直到调用 Stack 或 GiveUp 函数 + *** + + #### func (*StackGo) Stack() []byte > 获取消息堆栈 > - 在调用 Wait 函数后调用该函数，将会返回上一个协程的堆栈信息 > - 在调用 GiveUp 函数后调用该函数，将会 panic + *** + + #### func (*StackGo) GiveUp() > 放弃收集消息堆栈 > - 在调用 Wait 函数后调用该函数，将会放弃收集消息堆栈并且释放资源 > - 在调用 GiveUp 函数后调用 Stack 函数，将会 panic + *** + ### VerifyHandle `STRUCT` 校验句柄 ```go @@ -974,13 +1324,22 @@ type VerifyHandle[V any] struct { hit bool } ``` + + #### func (*VerifyHandle) PreCase(expression func () bool, value V, caseHandle func (verify *VerifyHandle[V]) bool) bool > 先决校验用例，当 expression 成立时，将跳过 caseHandle 的执行，直接执行 handle 并返回 false > - 常用于对前置参数的空指针校验，例如当 a 为 nil 时，不执行 a.B()，而是直接返回 false + *** + + #### func (*VerifyHandle) Case(expression bool, value V) *VerifyHandle[V] > 校验用例，当 expression 成立时，将忽略后续 Case，并将在 Do 时执行 handle，返回 false + *** + + #### func (*VerifyHandle) Do() bool > 执行校验，当校验失败时，将执行 handle，并返回 false + *** diff --git a/utils/super/bit_set.go b/utils/super/bit_set.go index a7cce23..43efac2 100644 --- a/utils/super/bit_set.go +++ b/utils/super/bit_set.go @@ -7,9 +7,13 @@ import ( ) // NewBitSet 通过指定的 Bit 位创建一个 BitSet +// - 当指定的 Bit 位存在负数时，将会 panic func NewBitSet[Bit generic.Integer](bits ...Bit) *BitSet[Bit] { set := &BitSet[Bit]{set: make([]uint64, 0, 1)} for _, bit := range bits { + if bit < 0 { + panic(fmt.Errorf("bit %v is negative", bit)) + } set.Set(bit) } return set @@ -43,6 +47,15 @@ func (slf *BitSet[Bit]) Del(bit Bit) *BitSet[Bit] { // Shrink 将 BitSet 中的比特位集合缩小到最小 // - 正常情况下当 BitSet 中的比特位超出 64 位时，将自动增长，当 BitSet 中的比特位数量减少时，可以使用该方法将 BitSet 中的比特位集合缩小到最小 func (slf *BitSet[Bit]) Shrink() *BitSet[Bit] { + switch len(slf.set) { + case 0: + return slf + case 1: + if slf.set[0] == 0 { + slf.set = nil + return slf + } + } index := len(slf.set) - 1 if slf.set[index] != 0 { return slf diff --git a/utils/super/bit_set_example_test.go b/utils/super/bit_set_example_test.go new file mode 100644 index 0000000..ead6ea7 --- /dev/null +++ b/utils/super/bit_set_example_test.go @@ -0,0 +1,74 @@ +package super_test + +import ( + "fmt" + "github.com/kercylan98/minotaur/utils/super" +) + +func ExampleNewBitSet() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Set(10) + fmt.Println(bs.Bits()) + // Output: + // [1 2 3 4 5 6 7 8 9 10] +} + +func ExampleBitSet_Set() { + var bs = super.NewBitSet[int]() + bs.Set(10) + fmt.Println(bs.Bits()) + // Output: + // [10] +} + +func ExampleBitSet_Del() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Del(1) + fmt.Println(bs.Bits()) + // Output: + // [2 3 4 5 6 7 8 9] +} + +func ExampleBitSet_Shrink() { + var bs = super.NewBitSet(111, 222, 333, 444) + fmt.Println(bs.Cap()) + bs.Del(444) + fmt.Println(bs.Cap()) + bs.Shrink() + fmt.Println(bs.Cap()) + // Output: + // 448 + // 448 + // 384 +} + +func ExampleBitSet_Cap() { + var bs = super.NewBitSet(63) + fmt.Println(bs.Cap()) + // Output: + // 64 +} + +func ExampleBitSet_Has() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + fmt.Println(bs.Has(1)) + fmt.Println(bs.Has(10)) + // Output: + // true + // false +} + +func ExampleBitSet_Clear() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + bs.Clear() + fmt.Println(bs.Bits()) + // Output: + // [] +} + +func ExampleBitSet_Len() { + var bs = super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9) + fmt.Println(bs.Len()) + // Output: + // 9 +} diff --git a/utils/super/bit_set_test.go b/utils/super/bit_set_test.go index f654139..e74e9b9 100644 --- a/utils/super/bit_set_test.go +++ b/utils/super/bit_set_test.go @@ -5,29 +5,118 @@ import ( "testing" ) +func TestNewBitSet(t *testing.T) { + var cases = []struct { + name string + in []int + shouldPanic bool + }{ + {name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, + {name: "empty", in: make([]int, 0)}, + {name: "nil", in: nil}, + {name: "negative", in: []int{-1, -2}, shouldPanic: true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet(c.in...) + t.Log(bs) + }) + } +} + func TestBitSet_Set(t *testing.T) { - bs := super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) - bs.Set(11) - bs.Set(12) - bs.Set(13) - t.Log(bs) + var cases = []struct { + name string + in []int + shouldPanic bool + }{ + {name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, + {name: "empty", in: make([]int, 0)}, + {name: "nil", in: nil}, + {name: "negative", in: []int{-1, -2}, shouldPanic: true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet[int]() + for _, bit := range c.in { + bs.Set(bit) + } + for _, bit := range c.in { + if !bs.Has(bit) { + t.Fatalf("bit %v not set", bit) + } + } + }) + } } func TestBitSet_Del(t *testing.T) { - bs := super.NewBitSet(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) - bs.Del(11) - bs.Del(12) - bs.Del(13) - bs.Del(10) - t.Log(bs) + var cases = []struct { + name string + in []int + shouldPanic bool + }{ + {name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, + {name: "empty", in: make([]int, 0)}, + {name: "nil", in: nil}, + {name: "negative", in: []int{-1, -2}, shouldPanic: true}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + defer func() { + if r := recover(); r != nil && !c.shouldPanic { + t.Fatalf("panic: %v", r) + } + }() + bs := super.NewBitSet[int]() + for _, bit := range c.in { + bs.Set(bit) + } + for _, bit := range c.in { + bs.Del(bit) + } + for _, bit := range c.in { + if bs.Has(bit) { + t.Fatalf("bit %v not del", bit) + } + } + }) + } } func TestBitSet_Shrink(t *testing.T) { - bs := super.NewBitSet(63) - t.Log(bs.Cap()) - bs.Set(200) - t.Log(bs.Cap()) - bs.Del(200) - bs.Shrink() - t.Log(bs.Cap()) + var cases = []struct { + name string + in []int + }{ + {name: "normal", in: []int{1, 2, 3, 4, 5, 6, 7, 8, 9}}, + {name: "empty", in: make([]int, 0)}, + {name: "nil", in: nil}, + } + + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + bs := super.NewBitSet(c.in...) + for _, v := range c.in { + bs.Del(v) + } + bs.Shrink() + if bs.Cap() != 0 { + t.Fatalf("cap %v != 0", bs.Cap()) + } + }) + } } diff --git a/utils/super/channel.go b/utils/super/channel.go index 242510c..3d3e24b 100644 --- a/utils/super/channel.go +++ b/utils/super/channel.go @@ -20,3 +20,25 @@ func TryWriteChannelByHandler[T any](ch chan<- T, data T, handler func()) { handler() } } + +// TryReadChannel 尝试读取 channel，如果 channel 无法读取则忽略，返回是否读取成功 +// - 无法读取的情况包括：channel 已空、channel 已关闭 +func TryReadChannel[T any](ch <-chan T) (v T, suc bool) { + select { + case data := <-ch: + return data, true + default: + return v, false + } +} + +// TryReadChannelByHandler 尝试读取 channel，如果 channel 无法读取则执行 handler +// - 无法读取的情况包括：channel 已空、channel 已关闭 +func TryReadChannelByHandler[T any](ch <-chan T, handler func(ch <-chan T) T) (v T) { + select { + case data := <-ch: + return data + default: + return handler(ch) + } +} diff --git a/utils/super/json.go b/utils/super/json.go index 70e375e..61e88c2 100644 --- a/utils/super/json.go +++ b/utils/super/json.go @@ -12,12 +12,7 @@ var json = jsonIter.ConfigCompatibleWithStandardLibrary func MarshalJSON(v interface{}) []byte { b, err := json.Marshal(v) if err != nil { - switch reflect.TypeOf(v).Kind() { - case reflect.Array, reflect.Slice: - return StringToBytes("[]") - default: - return StringToBytes("{}") - } + return jsonZero(v) } return b } @@ -37,12 +32,7 @@ func UnmarshalJSON(data []byte, v interface{}) error { func MarshalIndentJSON(v interface{}, prefix, indent string) []byte { b, err := json.MarshalIndent(v, prefix, indent) if err != nil { - switch reflect.TypeOf(v).Kind() { - case reflect.Array, reflect.Slice: - return StringToBytes("[]") - default: - return StringToBytes("{}") - } + return jsonZero(v) } return b } @@ -51,3 +41,23 @@ func MarshalIndentJSON(v interface{}, prefix, indent string) []byte { func MarshalToTargetWithJSON(src, dest interface{}) error { return json.Unmarshal(MarshalJSON(src), dest) } + +// 获取 json 格式的空对象 +func jsonZero(v any) []byte { + vof := reflect.Indirect(reflect.ValueOf(v)) + switch vof.Kind() { + case reflect.Array, reflect.Slice: + return StringToBytes("[]") + case reflect.Bool: + return StringToBytes("false") // false 在 JSON 中是不合法的，但是 Golang 中能够正确解析 + case + reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, + reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, + reflect.Float32, reflect.Float64: + return StringToBytes("0") // 0 在 JSON 中是不合法的，但是 Golang 中能够正确解析 + case reflect.String: + return StringToBytes("\"\"") + default: + return StringToBytes("{}") + } +} diff --git a/utils/timer/README.md b/utils/timer/README.md index 63d2f22..38d3129 100644 --- a/utils/timer/README.md +++ b/utils/timer/README.md @@ -31,11 +31,11 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[SystemNewDayEventHandle](#systemnewdayeventhandle)|暂无描述... -|`STRUCT`|[Option](#option)|暂无描述... -|`STRUCT`|[Pool](#pool)|定时器池 -|`STRUCT`|[Scheduler](#scheduler)|调度器 -|`STRUCT`|[Ticker](#ticker)|定时器 +|`STRUCT`|[SystemNewDayEventHandle](#struct_SystemNewDayEventHandle)|暂无描述... +|`STRUCT`|[Option](#struct_Option)|暂无描述... +|`STRUCT`|[Pool](#struct_Pool)|定时器池 +|`STRUCT`|[Scheduler](#struct_Scheduler)|调度器 +|`STRUCT`|[Ticker](#struct_Ticker)|定时器
@@ -66,17 +66,17 @@ > 偏移时间新的一天事件 *** -#### func WithCaller(handle func (name string, caller func ())) Option +#### func WithCaller(handle func (name string, caller func ())) Option > 通过其他的 handle 执行 Caller *** -#### func WithMark(mark string) Option +#### func WithMark(mark string) Option > 通过特定的标记创建定时器 *** -#### func NewPool(tickerPoolSize int) *Pool +#### func NewPool(tickerPoolSize int) *Pool > 创建一个定时器池，当 tickerPoolSize 小于等于 0 时，将会引发 panic，可指定为 DefaultTickerPoolSize @@ -87,21 +87,24 @@ > - 默认值为 DefaultTickerPoolSize，当定时器池中的定时器不足时，会自动创建新的定时器，当定时器释放时，会将多余的定时器进行释放，否则将放入定时器池中 *** -#### func GetTicker(size int, options ...Option) *Ticker +#### func GetTicker(size int, options ...Option) *Ticker > 获取标准池中的一个定时器 *** + ### SystemNewDayEventHandle `STRUCT` ```go type SystemNewDayEventHandle func() ``` + ### Option `STRUCT` ```go type Option func(ticker *Ticker) ``` + ### Pool `STRUCT` 定时器池 ```go @@ -112,17 +115,27 @@ type Pool struct { closed bool } ``` + + #### func (*Pool) ChangePoolSize(size int) error > 改变定时器池大小 > - 当传入的大小小于或等于 0 时，将会返回错误，并且不会发生任何改变 + *** + + #### func (*Pool) GetTicker(size int, options ...Option) *Ticker > 获取一个新的定时器 + *** + + #### func (*Pool) Release() > 释放定时器池的资源，释放后由其产生的 Ticker 在 Ticker.Release 后将不再回到池中，而是直接释放 > - 虽然定时器池已被释放，但是依旧可以产出 Ticker + *** + ### Scheduler `STRUCT` 调度器 ```go @@ -141,15 +154,25 @@ type Scheduler struct { expr *cronexpr.Expression } ``` + + #### func (*Scheduler) Name() string > 获取调度器名称 + *** + + #### func (*Scheduler) Next(prev time.Time) time.Time > 获取下一次执行的时间 + *** + + #### func (*Scheduler) Caller() > 可由外部发起调用的执行函数 + *** + ### Ticker `STRUCT` 定时器 ```go @@ -162,24 +185,42 @@ type Ticker struct { mark string } ``` + + #### func (*Ticker) Mark() string > 获取定时器的标记 > - 通常用于鉴别定时器来源 + *** + + #### func (*Ticker) Release() > 释放定时器，并将定时器重新放回 Pool 池中 + *** + + #### func (*Ticker) StopTimer(name string) > 停止特定名称的调度器 + *** + + #### func (*Ticker) IsStopped(name string) bool > 特定名称的调度器是否已停止 + *** + + #### func (*Ticker) GetSchedulers() []string > 获取所有调度器名称 + *** + + #### func (*Ticker) Cron(name string, expression string, handleFunc interface {}, args ...interface {}) > 通过 cron 表达式设置一个调度器，当 cron 表达式错误时，将会引发 panic +
查看 / 收起单元测试 @@ -207,12 +248,21 @@ func TestTicker_Cron(t *testing.T) { *** + + #### func (*Ticker) CronByInstantly(name string, expression string, handleFunc interface {}, args ...interface {}) > 与 Cron 相同，但是会立即执行一次 + *** + + #### func (*Ticker) After(name string, after time.Duration, handleFunc interface {}, args ...interface {}) > 设置一个在特定时间后运行一次的调度器 + *** + + #### func (*Ticker) Loop(name string, after time.Duration, interval time.Duration, times int, handleFunc interface {}, args ...interface {}) > 设置一个在特定时间后反复运行的调度器 + *** diff --git a/utils/times/README.md b/utils/times/README.md index ff82c67..90dc59c 100644 --- a/utils/times/README.md +++ b/utils/times/README.md @@ -70,24 +70,25 @@ |类型|名称|描述 |:--|:--|:-- -|`STRUCT`|[StateLine](#stateline)|状态时间线 -|`STRUCT`|[Period](#period)|表示一个时间段 +|`STRUCT`|[StateLine](#struct_StateLine)|状态时间线 +|`STRUCT`|[Period](#struct_Period)|表示一个时间段
*** ## 详情信息 -#### func CalcNextSec(sec int) int +#### func CalcNextSec(sec int) int > 计算下一个N秒在多少秒之后 *** -#### func CalcNextSecWithTime(t time.Time, sec int) int +#### func CalcNextSecWithTime(t time.Time, sec int) int > 计算下一个N秒在多少秒之后 -示例代码： +**示例代码：** + ```go func ExampleCalcNextSecWithTime() { @@ -98,7 +99,7 @@ func ExampleCalcNextSecWithTime() { ``` *** -#### func CalcNextTimeWithRefer(now time.Time, refer time.Duration) time.Time +#### func CalcNextTimeWithRefer(now time.Time, refer time.Duration) time.Time > 根据参考时间计算下一个整点时间 > - 假设当 now 为 14:15:16 ， 参考时间为 10 分钟， 则返回 14:20:00 @@ -112,69 +113,69 @@ func ExampleCalcNextSecWithTime() { > 针对 IntervalFormat 函数设置格式化内容 *** -#### func IntervalFormat(time1 time.Time, time2 time.Time) string +#### func IntervalFormat(time1 time.Time, time2 time.Time) string > 返回指定时间戳之间的间隔 > - 使用传入的时间进行计算换算，将结果体现为几年前、几天前、几小时前、几分钟前、几秒前。 *** -#### func GetMonthDays(t time.Time) int +#### func GetMonthDays(t time.Time) int > 获取一个时间当月共有多少天 *** -#### func WeekDay(t time.Time) int +#### func WeekDay(t time.Time) int > 获取一个时间是星期几 > - 1 ~ 7 *** -#### func GetNextDayInterval(t time.Time) time.Duration +#### func GetNextDayInterval(t time.Time) time.Duration > 获取一个时间到下一天间隔多少秒 *** -#### func GetToday(t time.Time) time.Time +#### func GetToday(t time.Time) time.Time > 获取一个时间的今天 *** -#### func GetSecond(d time.Duration) int +#### func GetSecond(d time.Duration) int > 获取共有多少秒 *** -#### func IsSameDay(t1 time.Time, t2 time.Time) bool +#### func IsSameDay(t1 time.Time, t2 time.Time) bool > 两个时间是否是同一天 *** -#### func IsSameHour(t1 time.Time, t2 time.Time) bool +#### func IsSameHour(t1 time.Time, t2 time.Time) bool > 两个时间是否是同一小时 *** -#### func GetMondayZero(t time.Time) time.Time +#### func GetMondayZero(t time.Time) time.Time > 获取本周一零点 *** -#### func Date(year int, month time.Month, day int) time.Time +#### func Date(year int, month time.Month, day int) time.Time > 返回一个特定日期的时间 *** -#### func DateWithHMS(year int, month time.Month, day int, hour int, min int, sec int) time.Time +#### func DateWithHMS(year int, month time.Month, day int, hour int, min int, sec int) time.Time > 返回一个精确到秒的时间 *** -#### func GetDeltaDay(t1 time.Time, t2 time.Time) int +#### func GetDeltaDay(t1 time.Time, t2 time.Time) int > 获取两个时间需要加减的天数 *** -#### func GetDeltaWeek(t1 time.Time, t2 time.Time) int +#### func GetDeltaWeek(t1 time.Time, t2 time.Time) int > 获取两个时间需要加减的周数 @@ -184,73 +185,73 @@ func ExampleCalcNextSecWithTime() { > 从时间字符串中获取时分秒 *** -#### func GetTimeFromString(timeStr string, layout string) time.Time +#### func GetTimeFromString(timeStr string, layout string) time.Time > 将时间字符串转化为时间 *** -#### func GetDayZero(t time.Time, day int) time.Time +#### func GetDayZero(t time.Time, day int) time.Time > 获取 t 增加 day 天后的零点时间 *** -#### func GetYesterday(t time.Time) time.Time +#### func GetYesterday(t time.Time) time.Time > 获取昨天 *** -#### func GetDayLast(t time.Time) time.Time +#### func GetDayLast(t time.Time) time.Time > 获取某天的最后一刻 > - 最后一刻即 23:59:59 *** -#### func GetYesterdayLast(t time.Time) time.Time +#### func GetYesterdayLast(t time.Time) time.Time > 获取昨天最后一刻 *** -#### func GetMinuteStart(t time.Time) time.Time +#### func GetMinuteStart(t time.Time) time.Time > 获取一个时间的 0 秒 *** -#### func GetMinuteEnd(t time.Time) time.Time +#### func GetMinuteEnd(t time.Time) time.Time > 获取一个时间的 59 秒 *** -#### func GetHourStart(t time.Time) time.Time +#### func GetHourStart(t time.Time) time.Time > 获取一个时间的 0 分 0 秒 *** -#### func GetHourEnd(t time.Time) time.Time +#### func GetHourEnd(t time.Time) time.Time > 获取一个时间的 59 分 59 秒 *** -#### func GetMonthStart(t time.Time) time.Time +#### func GetMonthStart(t time.Time) time.Time > 获取一个时间的月初 *** -#### func GetMonthEnd(t time.Time) time.Time +#### func GetMonthEnd(t time.Time) time.Time > 获取一个时间的月末 *** -#### func GetYearStart(t time.Time) time.Time +#### func GetYearStart(t time.Time) time.Time > 获取一个时间的年初 *** -#### func GetYearEnd(t time.Time) time.Time +#### func GetYearEnd(t time.Time) time.Time > 获取一个时间的年末 *** -#### func NewStateLine(zero State) *StateLine[State] +#### func NewStateLine\[State generic.Basic\](zero State) *StateLine[State] > 创建一个从左向右由早到晚的状态时间线 @@ -304,12 +305,12 @@ func TestSetGlobalTimeOffset(t *testing.T) { *** -#### func NowByNotOffset() time.Time +#### func NowByNotOffset() time.Time > 获取未偏移的当前时间 *** -#### func GetGlobalTimeOffset() time.Duration +#### func GetGlobalTimeOffset() time.Duration > 获取全局时间偏移量 @@ -319,13 +320,13 @@ func TestSetGlobalTimeOffset(t *testing.T) { > 重置全局时间偏移量 *** -#### func NewPeriod(start time.Time, end time.Time) Period +#### func NewPeriod(start time.Time, end time.Time) Period > 创建一个时间段 > - 如果 start 比 end 晚，则会自动交换两个时间 *** -#### func NewPeriodWindow(t time.Time, size time.Duration) Period +#### func NewPeriodWindow(t time.Time, size time.Duration) Period > 创建一个特定长度的时间窗口 @@ -349,56 +350,57 @@ func TestNewPeriodWindow(t *testing.T) { *** -#### func NewPeriodWindowWeek(t time.Time) Period +#### func NewPeriodWindowWeek(t time.Time) Period > 创建一周长度的时间窗口，从周一零点开始至周日 23:59:59 结束 *** -#### func NewPeriodWithTimeArray(times [2]time.Time) Period +#### func NewPeriodWithTimeArray(times [2]time.Time) Period > 创建一个时间段 *** -#### func NewPeriodWithDayZero(t time.Time, day int) Period +#### func NewPeriodWithDayZero(t time.Time, day int) Period > 创建一个时间段，从 t 开始，持续到 day 天后的 0 点 *** -#### func NewPeriodWithDay(t time.Time, day int) Period +#### func NewPeriodWithDay(t time.Time, day int) Period > 创建一个时间段，从 t 开始，持续 day 天 *** -#### func NewPeriodWithHour(t time.Time, hour int) Period +#### func NewPeriodWithHour(t time.Time, hour int) Period > 创建一个时间段，从 t 开始，持续 hour 小时 *** -#### func NewPeriodWithMinute(t time.Time, minute int) Period +#### func NewPeriodWithMinute(t time.Time, minute int) Period > 创建一个时间段，从 t 开始，持续 minute 分钟 *** -#### func NewPeriodWithSecond(t time.Time, second int) Period +#### func NewPeriodWithSecond(t time.Time, second int) Period > 创建一个时间段，从 t 开始，持续 second 秒 *** -#### func NewPeriodWithMillisecond(t time.Time, millisecond int) Period +#### func NewPeriodWithMillisecond(t time.Time, millisecond int) Period > 创建一个时间段，从 t 开始，持续 millisecond 毫秒 *** -#### func NewPeriodWithMicrosecond(t time.Time, microsecond int) Period +#### func NewPeriodWithMicrosecond(t time.Time, microsecond int) Period > 创建一个时间段，从 t 开始，持续 microsecond 微秒 *** -#### func NewPeriodWithNanosecond(t time.Time, nanosecond int) Period +#### func NewPeriodWithNanosecond(t time.Time, nanosecond int) Period > 创建一个时间段，从 t 开始，持续 nanosecond 纳秒 *** + ### StateLine `STRUCT` 状态时间线 ```go @@ -408,6 +410,8 @@ type StateLine[State generic.Basic] struct { trigger [][]func() } ``` + + #### func (*StateLine) Check(missingAllowed bool, states ...State) bool > 根据状态顺序检查时间线是否合法 > - missingAllowed: 是否允许状态缺失，如果为 true，则状态可以不连续，如果为 false，则状态必须连续 @@ -415,137 +419,265 @@ type StateLine[State generic.Basic] struct { > 状态不连续表示时间线中存在状态缺失，例如： > - 状态为 [1, 2, 3, 4, 5] 的时间线，如果 missingAllowed 为 true，则状态为 [1, 3, 5] 也是合法的 > - 状态为 [1, 2, 3, 4, 5] 的时间线，如果 missingAllowed 为 false，则状态为 [1, 3, 5] 是不合法的 + *** + + #### func (*StateLine) GetMissingStates(states ...State) []State > 获取缺失的状态 + *** + + #### func (*StateLine) HasState(state State) bool > 检查时间线中是否包含指定状态 + *** + + #### func (*StateLine) String() string > 获取时间线的字符串表示 + *** + + #### func (*StateLine) AddState(state State, t time.Time, onTrigger ...func ()) *StateLine[State] > 添加一个状态到时间线中，状态不能与任一时间点重合，否则将被忽略 > - onTrigger: 该状态绑定的触发器，该触发器不会被主动执行，需要主动获取触发器执行 + *** + + #### func (*StateLine) GetTimeByState(state State) time.Time > 获取指定状态的时间点 + *** + + #### func (*StateLine) GetNextTimeByState(state State) time.Time > 获取指定状态的下一个时间点 + *** + + #### func (*StateLine) GetLastState() State > 获取最后一个状态 + *** + + #### func (*StateLine) GetPrevTimeByState(state State) time.Time > 获取指定状态的上一个时间点 + *** + + #### func (*StateLine) GetIndexByState(state State) int > 获取指定状态的索引 + *** + + #### func (*StateLine) GetStateByTime(t time.Time) State > 获取指定时间点的状态 + *** + + #### func (*StateLine) GetTimeByIndex(index int) time.Time > 获取指定索引的时间点 + *** + + #### func (*StateLine) Move(d time.Duration) *StateLine[State] > 时间线整体移动 + *** + + #### func (*StateLine) GetNextStateTimeByIndex(index int) time.Time > 获取指定索引的下一个时间点 + *** + + #### func (*StateLine) GetPrevStateTimeByIndex(index int) time.Time > 获取指定索引的上一个时间点 + *** + + #### func (*StateLine) GetStateIndexByTime(t time.Time) int > 获取指定时间点的索引 + *** + + #### func (*StateLine) GetStateCount() int > 获取状态数量 + *** + + #### func (*StateLine) GetStateByIndex(index int) State > 获取指定索引的状态 + *** + + #### func (*StateLine) GetTriggerByTime(t time.Time) []func () > 获取指定时间点的触发器 + *** + + #### func (*StateLine) GetTriggerByIndex(index int) []func () > 获取指定索引的触发器 + *** + + #### func (*StateLine) GetTriggerByState(state State) []func () > 获取指定状态的触发器 + *** + + #### func (*StateLine) AddTriggerToState(state State, onTrigger ...func ()) *StateLine[State] > 给指定状态添加触发器 + *** + + #### func (*StateLine) Range(handler func (index int, state State, t time.Time) bool) > 按照时间顺序遍历时间线 + *** + + #### func (*StateLine) RangeReverse(handler func (index int, state State, t time.Time) bool) > 按照时间逆序遍历时间线 + *** + ### Period `STRUCT` 表示一个时间段 ```go type Period [2]time.Time ``` + + #### func (Period) Start() time.Time > 返回时间段的开始时间 + *** + + #### func (Period) End() time.Time > 返回时间段的结束时间 + *** + + #### func (Period) Duration() time.Duration > 返回时间段的持续时间 + *** + + #### func (Period) Day() int > 返回时间段的持续天数 + *** + + #### func (Period) Hour() int > 返回时间段的持续小时数 + *** + + #### func (Period) Minute() int > 返回时间段的持续分钟数 + *** + + #### func (Period) Seconds() int > 返回时间段的持续秒数 + *** + + #### func (Period) Milliseconds() int > 返回时间段的持续毫秒数 + *** + + #### func (Period) Microseconds() int > 返回时间段的持续微秒数 + *** + + #### func (Period) Nanoseconds() int > 返回时间段的持续纳秒数 + *** + + #### func (Period) IsZero() bool > 判断时间段是否为零值 + *** + + #### func (Period) IsInvalid() bool > 判断时间段是否无效 + *** + + #### func (Period) IsBefore(t time.Time) bool > 判断时间段是否在指定时间之前 + *** + + #### func (Period) IsAfter(t time.Time) bool > 判断时间段是否在指定时间之后 + *** + + #### func (Period) IsBetween(t time.Time) bool > 判断指定时间是否在时间段之间 + *** + + #### func (Period) IsOngoing(t time.Time) bool > 判断指定时间是否正在进行时 > - 如果时间段的开始时间在指定时间之前或者等于指定时间，且时间段的结束时间在指定时间之后，则返回 true + *** + + #### func (Period) IsBetweenOrEqual(t time.Time) bool > 判断指定时间是否在时间段之间或者等于时间段的开始或结束时间 + *** + + #### func (Period) IsBetweenOrEqualPeriod(t Period) bool > 判断指定时间是否在时间段之间或者等于时间段的开始或结束时间 + *** + + #### func (Period) IsOverlap(t Period) bool > 判断时间段是否与指定时间段重叠 + *** diff --git a/utils/xlsxtool/README.md b/utils/xlsxtool/README.md index 2fefedb..1dbcee7 100644 --- a/utils/xlsxtool/README.md +++ b/utils/xlsxtool/README.md @@ -25,7 +25,7 @@ *** ## 详情信息 -#### func GetSheetMatrix(sheet *xlsx.Sheet) *matrix.Matrix[*xlsx.Cell] +#### func GetSheetMatrix(sheet *xlsx.Sheet) *matrix.Matrix[*xlsx.Cell] > 将sheet转换为二维矩阵