doc: add docment for new or fixed function

2026-02-04 12:52:28 +08:00 · 2025-10-31 13:37:41 +08:00
parent f407e51b24
commit cbdc3971dd
11 changed files with 434 additions and 48 deletions
--- a/README.md
+++ b/README.md
@@ -1125,6 +1125,10 @@ import "github.com/duke-git/lancet/v2/maputil"
 -   **<big>FindValuesBy</big>** : returns a slice of values from the map that satisfy the given predicate function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/maputil.md#FindValuesBy)]
    [[play](https://go.dev/play/p/bvNwNBZDm6v)]
+-   **<big>ToMarkdownTable</big>** : Convert a map slice data to a Markdown table string. It supports custom header display names and column display order.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/maputil.md#ToMarkdownTable)]
+    [[play](https://go.dev/play/p/todo)]
+

 <h3 id="mathutil"> 13. Mathutil package implements some functions for math calculation. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>

@@ -1819,30 +1823,50 @@ import "github.com/duke-git/lancet/v2/structs"

 -   **<big>New</big>** : creates a `Struct` instance.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#New)]
+    [[play](https://go.dev/play/p/O29l8kk-Z17)]
 -   **<big>ToMap</big>** : converts a valid struct to a map.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#ToMap)]
+    [[play](https://go.dev/play/p/qQbLySBgerZ)]
 -   **<big>Fields</big>** : get all fields of a given struct, that the fields are abstract struct field.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#Fields)]
+    [[play](https://go.dev/play/p/w3Kk_CyVY7D)]
+-   **<big>Field</big>** : get an abstract field of a struct by given field name
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Field)]
+    [[play](https://go.dev/play/p/KocZMSYarza)]
 -   **<big>IsStruct</big>** : check if the struct is valid.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsStruct)]
+    [[play](https://go.dev/play/p/bU2FSdkbK1C)]
 -   **<big>Tag</big>** : get a `Tag` of the `Field`, `Tag` is a abstract struct field tag.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#Tag)]
+    [[play](https://go.dev/play/p/DVrx5HvvUJr)]
 -   **<big>Name</big>** : get the field name.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#Name)]
+    [[play](https://go.dev/play/p/zfIGlqsatee)]
 -   **<big>Value</big>** : get the `Field` underlying value.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#Value)]
+    [[play](https://go.dev/play/p/qufYEU2o4Oi)]
 -   **<big>Kind</big>** : get the field's kind.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#Kind)]
+    [[play](https://go.dev/play/p/wg4NlcUNG5o)]
 -   **<big>IsEmbedded</big>** : check if the field is an embedded field.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsEmbedded)]
+    [[play](https://go.dev/play/p/wV2PrbYm3Ec)]
 -   **<big>IsExported</big>** : check if the field is exported.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsExported)]
+    [[play](https://go.dev/play/p/csK4AXYaNbJ)]
 -   **<big>IsZero</big>** : check if the field is zero value.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsZero)]
+    [[play](https://go.dev/play/p/RzqpGISf87r)]
 -   **<big>IsSlice</big>** : check if the field is a slice.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsSlice)]
+    [[play](https://go.dev/play/p/MKz4CgBIUrU)]
 -   **<big>IsTargetType</big>** : check if the field is target type.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#IsTargetType)]
+    [[play](https://go.dev/play/p/Ig75P-agN39)]
+-   **<big>TypeName</big>** : Return struct type name.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/struct.md#TypeName)]
+    [[play](https://go.dev/play/p/todo)]
+

 <h3 id="strutil"> 21. Strutil package contains some functions to manipulate string. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>

@@ -2301,6 +2325,12 @@ import "github.com/duke-git/lancet/v2/validator"
 -   **<big>IsChinaUnionPay</big>** : check if a give string is a valid china union pay number or not.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/validator.md#IsChinaUnionPay)]
    [[play](https://go.dev/play/p/yafpdxLiymu)]
+-   **<big>IsPassport</big>** : Passport validation(using regex).
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/validator.md#IsPassport)]
+    [[play](https://go.dev/play/p/todo)]
+-   **<big>IsChineseHMPassport</big>** : Mainland travel permit for Hong Kong, Macao validation (using regex). 
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/validator.md#IsChineseHMPassport)]
+    [[play](https://go.dev/play/p/todo)]

 <h3 id="xerror"> 25. Xerror package implements helpers for errors. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>

--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -1135,6 +1135,9 @@ import "github.com/duke-git/lancet/v2/maputil"
 -   **<big>FindValuesBy</big>** : 返回一个切片，包含满足给定谓词判断函数的 map 中的值。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/maputil.md#FindValuesBy)]
    [[play](https://go.dev/play/p/bvNwNBZDm6v)]
+-   **<big>ToMarkdownTable</big>** : 将一个 map 切片数据转换为 Markdown 表格字符串。支持自定义表头显示名称和列的显示顺序。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/maputil.md#ToMarkdownTable)]
+    [[play](https://go.dev/play/p/todo)]

 <h3 id="mathutil"> 14. mathutil 包实现了一些数学计算的函数。&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">回到目录</a></h3>

@@ -1825,32 +1828,50 @@ import "github.com/duke-git/lancet/v2/structs"

 -   **<big>New</big>** : `Struct`结构体的构造函数。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#New)]
+    [[play](https://go.dev/play/p/O29l8kk-Z17)]
 -   **<big>ToMap</big>** : 将一个合法的 struct 对象转换为 map[string]any。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#ToMap)]
+    [[play](https://go.dev/play/p/qQbLySBgerZ)]
 -   **<big>Fields</big>** : 获取一个 struct 对象的属性列表。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Fields)]
+    [[play](https://go.dev/play/p/w3Kk_CyVY7D)]
 -   **<big>Field</big>** : 根据属性名获取一个 struct 对象的属性。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Fields)]
+    [[play](https://go.dev/play/p/KocZMSYarza)]
 -   **<big>IsStruct</big>** : 判断是否为一个合法的 struct 对象。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsStruct)]
+    [[play](https://go.dev/play/p/bU2FSdkbK1C)]
 -   **<big>Tag</big>** : 获取`Field`的`Tag`，默认的 tag key 是 json。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Tag)]
+    [[play](https://go.dev/play/p/DVrx5HvvUJr)]
 -   **<big>Name</big>** : 获取属性名。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Name)]
+    [[play](https://go.dev/play/p/zfIGlqsatee)]
 -   **<big>Value</big>** : 获取`Field`属性的值。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Value)]
+    [[play](https://go.dev/play/p/qufYEU2o4Oi)]
 -   **<big>Kind</big>** : 获取属性 Kind。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#Kind)]
+    [[play](https://go.dev/play/p/wg4NlcUNG5o)]
 -   **<big>IsEmbedded</big>** : 判断属性是否为嵌入。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsEmbedded)]
+    [[play](https://go.dev/play/p/wV2PrbYm3Ec)]
 -   **<big>IsExported</big>** : 判断属性是否导出。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsExported)]
+    [[play](https://go.dev/play/p/csK4AXYaNbJ)]
 -   **<big>IsZero</big>** : 判断属性是否为零值。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsZero)]
+    [[play](https://go.dev/play/p/RzqpGISf87r)]
 -   **<big>IsSlice</big>** : 判断属性是否是切片。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsSlice)]
+    [[play](https://go.dev/play/p/MKz4CgBIUrU)]
 -   **<big>IsTargetType</big>** : 判断属性是否是目标类型。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#IsTargetType)]
+    [[play](https://go.dev/play/p/Ig75P-agN39)]
+-   **<big>TypeName</big>** : 获取结构体类型名。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/struct.md#TypeName)]
+    [[play](https://go.dev/play/p/todo)]
+

 <h3 id="strutil"> 22. strutil 包含字符串处理的相关函数。&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">回到目录</a></h3>

@@ -2310,7 +2331,12 @@ import "github.com/duke-git/lancet/v2/validator"
 -   **<big>IsChinaUnionPay</big>** : 检查字符串是否是有效的中国银联卡号。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/validator.md#IsChinaUnionPay)]
    [[play](https://go.dev/play/p/yafpdxLiymu)]
-
+-   **<big>IsPassport</big>** : 判断护照(正则判断)。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/validator.md#IsPassport)]
+    [[play](https://go.dev/play/p/todo)]
+-   **<big>IsChineseHMPassport</big>** : 判断港澳台通行证(正则判断)。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/validator.md#IsChineseHMPassport)]
+    [[play](https://go.dev/play/p/todo)]
 <h3 id="xerror"> 26. xerror 包实现一些错误处理函数。&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">回到目录</a></h3>

 ```go
--- a/docs/api/packages/maputil.md
+++ b/docs/api/packages/maputil.md
@@ -2357,7 +2357,7 @@ func main() {
 编辑
 func ToMarkdownTable(data []map[string]interface{}, headerMap map[string]string, columnOrder []string) string
 ```
-<b>示例:<span style="float:right;display:inline-block;">[运行]()</span></b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/todo)</span></b>


 ```go
--- a/docs/api/packages/struct.md
+++ b/docs/api/packages/struct.md
@@ -31,6 +31,7 @@ import (
 -   [IsStruct](#IsStruct)
 -   [Tag](#Tag)
 -   [Name](#Name)
+-   [TypeName](#TypeName)
 -   [Value](#Value)
 -   [Kind](#Kind)
 -   [IsEmbedded](#IsEmbedded)
@@ -53,7 +54,7 @@ import (
 func New(value any, tagName ...string) *Struct
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/O29l8kk-Z17)</span></b>

 ```go
 package main
@@ -68,7 +69,11 @@ func main() {
    }
    p1 := &People{Name: "11"}
    s := structs.New(p1)
-    // to do something
+    
+    fmt.Println(s.ToMap())
+
+    // Output:
+    // map[name:11] <nil>
 }
 ```

@@ -88,7 +93,7 @@ func (s *Struct) ToMap() (map[string]any, error)
 func ToMap(v any) (map[string]any, error)
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/qQbLySBgerZ)</span></b>

 ```go
 package main
@@ -129,7 +134,7 @@ func main() {
 func (s *Struct) Fields() []*Field
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/w3Kk_CyVY7D)</span></b>

 ```go
 package main
@@ -161,10 +166,10 @@ func main() {
 <b>函数签名:</b>

 ```go
-func (s *Struct) Field(name string) *Field
+func (s *Struct) Field(name string) (*Field, bool)
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/KocZMSYarza)</span></b>

 ```go
 package main
@@ -180,12 +185,14 @@ func main() {
    }
    p1 := &People{Name: "11"}
    s := structs.New(p1)
-    f := s.Field("Name")
+    f, found := s.Field("Name")

    fmt.Println(f.Value())
+    fmt.Println(found)

    // Output:
    // 11
+    // true
 }
 ```

@@ -199,7 +206,7 @@ func main() {
 func (s *Struct) IsStruct() bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/bU2FSdkbK1C)</span></b>

 ```go
 package main
@@ -233,7 +240,7 @@ func main() {
 func (f *Field) Tag() *Tag
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/DVrx5HvvUJr)</span></b>

 ```go
 package main
@@ -270,7 +277,7 @@ func main() {
 func (f *Field) Value() any
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/qufYEU2o4Oi)</span></b>

 ```go
 package main
@@ -306,7 +313,7 @@ func main() {
 func (f *Field) IsEmbedded() bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/wV2PrbYm3Ec)</span></b>

 ```go
 package main
@@ -351,7 +358,7 @@ func main() {
 func (f *Field) IsExported() bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/csK4AXYaNbJ)</span></b>

 ```go
 package main
@@ -390,7 +397,7 @@ func main() {
 func (f *Field) IsZero() bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/RzqpGISf87r)</span></b>

 ```go
 package main
@@ -429,7 +436,7 @@ func main() {
 func (f *Field) Name() string
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/zfIGlqsatee)</span></b>

 ```go
 package main
@@ -468,7 +475,7 @@ func main() {
 func (f *Field) Kind() reflect.Kind
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/wg4NlcUNG5o)</span></b>

 ```go
 package main
@@ -497,6 +504,42 @@ func main() {
 }
 ```

+### <span id="TypeName">TypeName</span>
+
+<p>获取结构体类型名。</p>
+
+<b>函数签名:</b>
+
+```go
+func (s *Struct) TypeName() string
+```
+
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/todo)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/structs"
+)
+
+func main() {
+    type Parent struct {
+        Name string
+        Age  int
+    }
+    
+    p := &Parent{Age: 11}
+    s := structs.New(p1)
+
+    fmt.Println(s.TypeName())
+    
+    // Output: 
+    // Parent
+}
+```
+
 ### <span id="IsSlice">IsSlice</span>

 <p>判断属性是否是切片</p>
@@ -507,7 +550,7 @@ func main() {
 func (f *Field) IsSlice() bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/MKz4CgBIUrU)</span></b>

 ```go
 package main
@@ -544,7 +587,7 @@ func main() {
 func (f *Field) IsTargetType(targetType reflect.Kind) bool
 ```

-<b>示例:</b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/Ig75P-agN39)</span></b>

 ```go
 package main
--- a/docs/api/packages/validator.md
+++ b/docs/api/packages/validator.md
@@ -65,6 +65,8 @@ import (
 -   [IsAmericanExpress](#IsAmericanExpress)
 -   [IsUnionPay](#IsUnionPay)
 -   [IsChinaUnionPay](#IsChinaUnionPay)
+-   [IsPassport](#IsPassport)
+-   [IsChineseHMPassport](#IsChineseHMPassport)

 <div STYLE="page-break-after: always;"></div>

@@ -1567,3 +1569,80 @@ func main() {
    // false
 }
 ```
+
+### <span id="IsPassport">IsPassport</span>
+
+<p>判断护照(正则判断)。</p>
+
+<b>函数签名:</b>
+
+```go
+func IsPassport(passport, country string) bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/todo)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/validator"
+)
+
+func main() {
+    result1 := validator.IsPassport("P123456789", "CN")
+    result2 := validator.IsPassport("123456789", "US")
+    result3 := validator.IsPassport("AB1234567", "RU")
+    result4 := validator.IsPassport("123456789", "CN")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // true
+    // true
+    // true
+    // false
+}
+```
+
+### <span id="IsChineseHMPassport">IsChineseHMPassport</span>
+
+<p>判断港澳台通行证(正则判断)。</p>
+
+<b>函数签名:</b>
+
+```go
+func IsChineseHMPassport(hmPassport string) bool
+```
+
+<b>示例:<span style="float:right;display:inline-block">[运行](https://go.dev/play/p/todo)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/validator"
+)
+
+func main() {
+    result1 := validator.IsChineseHMPassport("C12345678")
+    result2 := validator.IsChineseHMPassport("C00000000")
+    result3 := validator.IsChineseHMPassport("M12345678")
+    result4 := validator.IsChineseHMPassport("c12345678")
+    result5 := validator.IsChineseHMPassport("C1234567")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+    fmt.Println(result5)
+
+    // Output:
+    // true
+    // true
+    // true
+    // false
+    // false
+}
+```
--- a/docs/en/api/packages/maputil.md
+++ b/docs/en/api/packages/maputil.md
@@ -79,6 +79,8 @@ import (
 -   [SortByKey](#SortByKey)
 -   [GetOrDefault](#GetOrDefault)
 -   [FindValuesBy](#FindValuesBy)
+-   [ToMarkdownTable](#ToMarkdownTable)
+

 <div STYLE="page-break-after: always;"></div>

@@ -2363,3 +2365,69 @@ func main() {
    // [b d]
 }
 ```
+
+### <span id="ToMarkdownTable">ToMarkdownTable</span>
+
+<p>Convert a map slice data to a Markdown table string. It supports custom header display names and column display order.</p>
+
+<b>Signature:</b>
+
+```go
+编辑
+func ToMarkdownTable(data []map[string]interface{}, headerMap map[string]string, columnOrder []string) string
+```
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/todo)</span></b>
+
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/maputil"
+)
+
+func main() {
+    // basic usage: automatically extract column names from data as table headers
+
+    data := []map[string]interface{}{
+        {"name": "Alice", "age": 25, "salary": 50000},
+        {"name": "Bob", "age": 30, "salary": 60000},
+    }
+
+    result := maputil.ToMarkdownTable(data, nil, nil)
+    fmt.Println(result)
+
+    // output:
+    // |name|age|salary|
+    // |---|---|---|
+    // |Alice|25|50000|
+    // |Bob|30|60000|
+
+    // custom header name
+    headerMap := map[string]string{
+        "name":   "n",
+        "age":    "a",
+        "salary": "s",
+    }
+    result = maputil.ToMarkdownTable(data, headerMap, nil)
+    fmt.Println(result)
+
+    // ouput:
+    // |m|a|s|
+    // |---|---|---|
+    // |Alice|25|50000|
+    // |Bob|30|60000|
+
+    // custom column display order
+    columnOrder := []string{"salary", "name"}
+    result = maputil.ToMarkdownTable(data, nil, columnOrder)
+    fmt.Println(result)
+
+    // 输出:
+    // |salary|name|
+    // |---|---|
+    // |50000|Alice|
+    // |60000|Bob|
+}
+```
--- a/docs/en/api/packages/struct.md
+++ b/docs/en/api/packages/struct.md
@@ -31,6 +31,7 @@ import (
 -   [IsStruct](#IsStruct)
 -   [Tag](#Tag)
 -   [Name](#Name)
+-   [TypeName](#TypeName)
 -   [Value](#Value)
 -   [Kind](#Kind)
 -   [IsEmbedded](#IsEmbedded)
@@ -53,12 +54,13 @@ import (
 func New(value any, tagName ...string) *Struct
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/O29l8kk-Z17)</span></b>

 ```go
 package main

 import (
+    "fmt"
    "github.com/duke-git/lancet/v2/structs"
 )

@@ -68,7 +70,11 @@ func main() {
    }
    p1 := &People{Name: "11"}
    s := structs.New(p1)
-    // to do something
+    
+    fmt.Println(s.ToMap())
+
+    // Output:
+    // map[name:11] <nil>
 }
 ```

@@ -88,7 +94,7 @@ func (s *Struct) ToMap() (map[string]any, error)
 func ToMap(v any) (map[string]any, error)
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/qQbLySBgerZ)</span></b>

 ```go
 package main
@@ -130,7 +136,7 @@ func main() {
 func (s *Struct) Fields() []*Field
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/w3Kk_CyVY7D)</span></b>

 ```go
 package main
@@ -162,10 +168,10 @@ func main() {
 <b>Signature:</b>

 ```go
-func (s *Struct) Field(name string) *Field
+func (s *Struct) Field(name string) (*Field, bool)
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/KocZMSYarza)</span></b>

 ```go
 package main
@@ -181,12 +187,14 @@ func main() {
    }
    p1 := &People{Name: "11"}
    s := structs.New(p1)
-    f := s.Field("Name")
+    f, found := s.Field("Name")

    fmt.Println(f.Value())
+    fmt.Println(found)

    // Output:
    // 11
+    // true
 }
 ```

@@ -200,7 +208,7 @@ func main() {
 func (s *Struct) IsStruct() bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/bU2FSdkbK1C)</span></b>

 ```go
 package main
@@ -234,7 +242,7 @@ func main() {
 func (f *Field) Tag() *Tag
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/DVrx5HvvUJr)</span></b>

 ```go
 package main
@@ -271,7 +279,7 @@ func main() {
 func (f *Field) Value() any
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/qufYEU2o4Oi)</span></b>

 ```go
 package main
@@ -307,7 +315,7 @@ func main() {
 func (f *Field) IsEmbedded() bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/wV2PrbYm3Ec)</span></b>

 ```go
 package main
@@ -352,7 +360,7 @@ func main() {
 func (f *Field) IsExported() bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/csK4AXYaNbJ)</span></b>

 ```go
 package main
@@ -391,7 +399,7 @@ func main() {
 func (f *Field) IsZero() bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/RzqpGISf87r)</span></b>

 ```go
 package main
@@ -430,7 +438,7 @@ func main() {
 func (f *Field) Name() string
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/zfIGlqsatee)</span></b>

 ```go
 package main
@@ -469,7 +477,7 @@ func main() {
 func (f *Field) Kind() reflect.Kind
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/wg4NlcUNG5o)</span></b>

 ```go
 package main
@@ -498,6 +506,42 @@ func main() {
 }
 ```

+### <span id="TypeName">TypeName</span>
+
+<p>Return struct type name.</p>
+
+<b>Signature:</b>
+
+```go
+func (s *Struct) TypeName() string
+```
+
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/todo)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/structs"
+)
+
+func main() {
+    type Parent struct {
+        Name string
+        Age  int
+    }
+
+    p := &Parent{Age: 11}
+    s := structs.New(p1)
+
+    fmt.Println(s.TypeName())
+    
+    // Output: 
+    // Parent
+}
+```
+
 ### <span id="IsSlice">IsSlice</span>

 <p>Check if the field is a slice</p>
@@ -508,7 +552,7 @@ func main() {
 func (f *Field) IsSlice() bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/MKz4CgBIUrU)</span></b>

 ```go
 package main
@@ -545,7 +589,7 @@ func main() {
 func (f *Field) IsTargetType(targetType reflect.Kind) bool
 ```

-<b>Example:</b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/Ig75P-agN39)</span></b>

 ```go
 package main
--- a/docs/en/api/packages/validator.md
+++ b/docs/en/api/packages/validator.md
@@ -65,6 +65,8 @@ import (
 -   [IsAmericanExpress](#IsAmericanExpress)
 -   [IsUnionPay](#IsUnionPay)
 -   [IsChinaUnionPay](#IsChinaUnionPay)
+-   [IsPassport](#IsPassport)
+-   [IsChineseHMPassport](#IsChineseHMPassport)

 <div STYLE="page-break-after: always;"></div>

@@ -1569,3 +1571,80 @@ func main() {
    // false
 }
 ```
+
+### <span id="IsPassport">IsPassport</span>
+
+<p>Passport validation(using regex).</p>
+
+<b>Signature:</b>
+
+```go
+func IsPassport(passport, country string) bool
+```
+
+<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/todo)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/validator"
+)
+
+func main() {
+    result1 := validator.IsPassport("P123456789", "CN")
+    result2 := validator.IsPassport("123456789", "US")
+    result3 := validator.IsPassport("AB1234567", "RU")
+    result4 := validator.IsPassport("123456789", "CN")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // true
+    // true
+    // true
+    // false
+}
+```
+
+### <span id="IsChineseHMPassport">IsChineseHMPassport</span>
+
+<p>Mainland travel permit for Hong Kong, Macao validation (using regex). </p>
+
+<b>Signature:</b>
+
+```go
+func IsChineseHMPassport(hmPassport string) bool
+```
+
+<b>Example:<span style="float:right;display:inline-block">[Run](https://go.dev/play/p/todo)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/validator"
+)
+
+func main() {
+    result1 := validator.IsChineseHMPassport("C12345678")
+    result2 := validator.IsChineseHMPassport("C00000000")
+    result3 := validator.IsChineseHMPassport("M12345678")
+    result4 := validator.IsChineseHMPassport("c12345678")
+    result5 := validator.IsChineseHMPassport("C1234567")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+    fmt.Println(result5)
+
+    // Output:
+    // true
+    // true
+    // true
+    // false
+    // false
+}
+```
--- a/maputil/map.go
+++ b/maputil/map.go
@@ -683,6 +683,7 @@ func FindValuesBy[K comparable, V any](m map[K]V, predicate func(key K, value V)
 }

 // ToMarkdownTable converts a slice of maps to a Markdown table.
+// Play: ttps://go.dev/play/p/todo
 func ToMarkdownTable(data []map[string]interface{}, headerMap map[string]string, columnOrder []string) string {
 	if len(data) == 0 {
 		return "| |\n|---|\n"
--- a/structs/field.go
+++ b/structs/field.go
@@ -26,26 +26,31 @@ func newField(v reflect.Value, f reflect.StructField, tagName string) *Field {
 }

 // Tag returns the value that the key in the tag string.
+// Play: https://go.dev/play/p/DVrx5HvvUJr
 func (f *Field) Tag() *Tag {
 	return f.tag
 }

 // Value returns the underlying value of the field.
+// Play: https://go.dev/play/p/qufYEU2o4Oi
 func (f *Field) Value() any {
 	return f.rvalue.Interface()
 }

 // IsEmbedded returns true if the given field is an embedded field.
+// Play: https://go.dev/play/p/wV2PrbYm3Ec
 func (f *Field) IsEmbedded() bool {
 	return len(f.field.Index) > 1
 }

 // IsExported returns true if the given field is exported.
+// Play: https://go.dev/play/p/csK4AXYaNbJ
 func (f *Field) IsExported() bool {
 	return f.field.IsExported()
 }

 // IsZero returns true if the given field is zero value.
+// Play: https://go.dev/play/p/RzqpGISf87r
 func (f *Field) IsZero() bool {
 	z := reflect.Zero(f.rvalue.Type()).Interface()
 	v := f.Value()
@@ -63,22 +68,26 @@ func (f *Field) IsNil() bool {
 }

 // Name returns the name of the given field
+// Play: https://go.dev/play/p/zfIGlqsatee
 func (f *Field) Name() string {
 	return f.field.Name
 }

 // Kind returns the field's kind
+// Play: https://go.dev/play/p/wg4NlcUNG5o
 func (f *Field) Kind() reflect.Kind {
 	return f.rvalue.Kind()
 }

 // IsSlice check if a struct field type is slice or not
+// Play: https://go.dev/play/p/MKz4CgBIUrU
 func (f *Field) IsSlice() bool {
 	k := f.rvalue.Kind()
 	return k == reflect.Slice
 }

 // IsTargetType check if a struct field type is target type or not
+// Play: https://go.dev/play/p/Ig75P-agN39
 func (f *Field) IsTargetType(targetType reflect.Kind) bool {
 	return f.rvalue.Kind() == targetType
 }
--- a/structs/struct.go
+++ b/structs/struct.go
@@ -20,6 +20,7 @@ type Struct struct {
 }

 // New returns a new *Struct
+// Play: https://go.dev/play/p/O29l8kk-Z17
 func New(value any, tagName ...string) *Struct {
 	value = pointer.ExtractPointer(value)
 	v := reflect.ValueOf(value)
@@ -60,6 +61,7 @@ func New(value any, tagName ...string) *Struct {
 //	 	Name string `json:"myName"`
 //
 // ToMap convert the exported fields of a struct to map.
+// Play: https://go.dev/play/p/qQbLySBgerZ
 func (s *Struct) ToMap() (map[string]any, error) {
 	if !s.IsStruct() {
 		return nil, fmt.Errorf("invalid struct %v", s)
@@ -87,6 +89,7 @@ func (s *Struct) ToMap() (map[string]any, error) {
 }

 // Fields returns all the struct fields within a slice
+// Play: https://go.dev/play/p/w3Kk_CyVY7D
 func (s *Struct) Fields() []*Field {
 	fieldNum := s.rvalue.NumField()
 	fields := make([]*Field, 0, fieldNum)
@@ -100,6 +103,7 @@ func (s *Struct) Fields() []*Field {
 }

 // Field returns a Field if the given field name was found
+// Play: https://go.dev/play/p/KocZMSYarza
 func (s *Struct) Field(name string) (*Field, bool) {
 	f, ok := s.rtype.FieldByName(name)
 	if !ok {
@@ -109,6 +113,7 @@ func (s *Struct) Field(name string) (*Field, bool) {
 }

 // IsStruct returns true if the given rvalue is a struct
+// Play: https://go.dev/play/p/bU2FSdkbK1C
 func (s *Struct) IsStruct() bool {
 	k := s.rvalue.Kind()
 	if k == reflect.Invalid {
@@ -119,11 +124,13 @@ func (s *Struct) IsStruct() bool {

 // ToMap convert struct to map, only convert exported struct field
 // map key is specified same as struct field tag `json` value.
+// Play: https://go.dev/play/p/qQbLySBgerZ
 func ToMap(v any) (map[string]any, error) {
 	return New(v).ToMap()
 }

 // TypeName return struct type name
+// Play: https://go.dev/play/p/todo
 func (s *Struct) TypeName() string {
 	return s.rtype.Name()
 }