feat: update readme file

Author: Jiawen

README.md

@@ -962,6 +962,12 @@ import "github.com/duke-git/lancet/v2/formatter"
 -   **<big>ParseBinaryBytes</big>** : return the human readable bytes size string into the amount it represents(base 1024).
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/formatter.md#ParseBinaryBytes)]
     [[play](https://go.dev/play/p/69v1tTT62x8)]
+-   **<big>ParseCNAddress</big>** : parses a Chinese address string intelligently and extracts structured information (province, city, district, street, name, phone, etc.). Supports various address formats including county-level cities.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/formatter.md#ParseCNAddress)]
+    [[play](https://go.dev/play/p/o5l09hQopEV)]
+-   **<big>ParsePersonInfo</big>** : extracts user information (name, phone, ID card, postal code) from an address string and separates it from the location address.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/formatter.md#ParsePersonInfo)]
+    [[play](https://go.dev/play/p/JO-uTlJlTy7)]
 
 <h3 id="function"> 13. Function package can control the flow of function execution and support part of functional programming.&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>
 

README_zh-CN.md

@@ -972,6 +972,12 @@ import "github.com/duke-git/lancet/v2/formatter"
 -   **<big>ParseBinaryBytes</big>** : 将字节单位字符串转换成其所表示的字节数（以 1024 为基数）。
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/formatter.md#ParseBinaryBytes)]
     [[play](https://go.dev/play/p/69v1tTT62x8)]
+-   **<big>ParseCNAddress</big>** : 智能解析中国地址字符串并提取结构化信息（省、市、区、街道、姓名、电话等）。支持多种地址格式，包括县级市。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/formatter.md#ParseCNAddress)]
+    [[play](https://go.dev/play/p/o5l09hQopEV)]
+-   **<big>ParsePersonInfo</big>** : 从地址字符串中提取用户信息（姓名、电话、身份证、邮编）并将其与位置地址分离。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/formatter.md#ParsePersonInfo)]
+    [[play](https://go.dev/play/p/JO-uTlJlTy7)]
 
 <h3 id="function"> 13. function 函数包控制函数执行流程，包含部分函数式编程。&nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">回到目录</a></h3>
 

docs/api/packages/formatter.md

@@ -31,8 +31,8 @@ import (
 -   [BinaryBytes](#BinaryBytes)
 -   [ParseDecimalBytes](#ParseDecimalBytes)
 -   [ParseBinaryBytes](#ParseBinaryBytes)
--   [Smart](#Smart)
--   [Decompose](#Decompose)
+-   [ParseCNAddress](#ParseCNAddress)
+-   [ParsePersonInfo](#ParsePersonInfo)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -312,17 +312,17 @@ func main() {
 }
 ```
 
-### <span id="Smart">Smart</span>
+### <span id="ParseCNAddress">ParseCNAddress</span>
 
 <p>智能解析中国地址字符串并提取结构化信息。可以解析带或不带用户信息（姓名、电话、身份证等）的地址。当 withUser 为 true 时，从地址字符串中提取用户信息。当 withUser 为 false 时，仅解析位置信息。支持多种地址格式：标准格式、紧凑格式、带关键词格式、县级市格式等。</p>
 
 <b>函数签名:</b>
 
 ```go
-func Smart(str string, withUser bool) *AddressInfo
+func ParseCNAddress(str string, withUser bool) *AddressInfo
 ```
 
-<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/HtTw0FSzenp)</span></b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/o5l09hQopEV)</span></b>
 
 ```go
 package main
@@ -335,25 +335,25 @@ import (
 
 func main() {
     // 解析包含用户信息的完整地址
-    result1 := formatter.Smart("张三 13800138000 北京市朝阳区建国路1号", true)
+    result1 := formatter.ParseCNAddress("张三 13800138000 北京市朝阳区建国路1号", true)
     jsonData1, _ := json.MarshalIndent(result1, "", "  ")
     fmt.Println("示例 1 - 带用户信息:")
     fmt.Println(string(jsonData1))
 
     // 仅解析地址，不提取用户信息
-    result2 := formatter.Smart("北京市海淀区中关村大街1号", false)
+    result2 := formatter.ParseCNAddress("北京市海淀区中关村大街1号", false)
     fmt.Printf("\n示例 2 - 仅地址:\n")
     fmt.Printf("省: %s, 市: %s, 区: %s, 街道: %s\n",
         result2.Province, result2.City, result2.Region, result2.Street)
 
     // 解析县级市地址
-    result3 := formatter.Smart("河北省石家庄市新乐市经济开发区兴工街10号", false)
+    result3 := formatter.ParseCNAddress("河北省石家庄市新乐市经济开发区兴工街10号", false)
     fmt.Printf("\n示例 3 - 县级市:\n")
     fmt.Printf("省: %s, 市: %s, 区/县: %s, 街道: %s\n",
         result3.Province, result3.City, result3.Region, result3.Street)
 
     // 紧凑格式
-    result4 := formatter.Smart("马云13593464918陕西省西安市雁塔区丈八沟街道", true)
+    result4 := formatter.ParseCNAddress("马云13593464918陕西省西安市雁塔区丈八沟街道", true)
     fmt.Printf("\n示例 4 - 紧凑格式:\n")
     fmt.Printf("姓名: %s, 电话: %s, 地址: %s%s%s%s\n",
         result4.Name, result4.Mobile, result4.Province, result4.City, result4.Region, result4.Street)
@@ -383,17 +383,17 @@ func main() {
 }
 ```
 
-### <span id="Decompose">Decompose</span>
+### <span id="ParsePersonInfo">ParsePersonInfo</span>
 
 <p>从地址字符串中提取用户信息（姓名、电话、身份证、邮编）。将个人信息与地址分离，支持带标签格式、紧凑格式、带分隔符格式。返回包含提取的用户信息和清理后地址字符串的 AddressInfo。</p>
 
 <b>函数签名:</b>
 
 ```go
-func Decompose(str string) *AddressInfo
+func ParsePersonInfo(str string) *AddressInfo
 ```
 
-<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/wXsE5aKfhPk)</span></b>
+<b>示例:<span style="float:right;display:inline-block;">[运行](https://go.dev/play/p/JO-uTlJlTy7)</span></b>
 
 ```go
 package main
@@ -406,17 +406,17 @@ import (
 
 func main() {
     // 提取姓名和手机号
-    result1 := formatter.Decompose("张三 13800138000 北京市朝阳区")
+    result1 := formatter.ParsePersonInfo("张三 13800138000 北京市朝阳区")
     fmt.Println("示例 1 - 姓名和手机号:")
     fmt.Printf("姓名: %s, 手机: %s, 地址: %s\n", result1.Name, result1.Mobile, result1.Addr)
 
     // 提取身份证号
-    result2 := formatter.Decompose("李四 110101199001011234 上海市")
+    result2 := formatter.ParsePersonInfo("李四 110101199001011234 上海市")
     fmt.Println("\n示例 2 - 身份证号:")
     fmt.Printf("姓名: %s, 身份证: %s, 地址: %s\n", result2.Name, result2.IDN, result2.Addr)
 
     // 带标签格式
-    result3 := formatter.Decompose("收货人：王五 电话：13900139000 收货地址：天津市河西区友谊路20号")
+    result3 := formatter.ParsePersonInfo("收货人：王五 电话：13900139000 收货地址：天津市河西区友谊路20号")
     jsonData3, _ := json.MarshalIndent(result3, "", "  ")
     fmt.Println("\n示例 3 - 带标签格式:")
     fmt.Println(string(jsonData3))

docs/en/api/packages/formatter.md

@@ -31,8 +31,8 @@ import (
 -   [BinaryBytes](#BinaryBytes)
 -   [ParseDecimalBytes](#ParseDecimalBytes)
 -   [ParseBinaryBytes](#ParseBinaryBytes)
--   [Smart](#Smart)
--   [Decompose](#Decompose)
+-   [ParseCNAddress](#ParseCNAddress)
+-   [ParsePersonInfo](#ParsePersonInfo)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -312,17 +312,17 @@ func main() {
 }
 ```
 
-### <span id="Smart">Smart</span>
+### <span id="ParseCNAddress">ParseCNAddress</span>
 
 <p>Parses a Chinese address string intelligently and extracts structured information. It can parse addresses with or without user information (name, phone, ID card, etc.). When withUser is true, it extracts user information from the address string. When withUser is false, it only parses the location information. Supports various address formats: standard format, compact format, labeled format, county-level cities format, etc.</p>
 
 <b>Signature:</b>
 
 ```go
-func Smart(str string, withUser bool) *AddressInfo
+func ParseCNAddress(str string, withUser bool) *AddressInfo
 ```
 
-<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/HtTw0FSzenp)</span></b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/o5l09hQopEV)</span></b>
 
 ```go
 package main
@@ -335,25 +335,25 @@ import (
 
 func main() {
     // Parse complete address with user information
-    result1 := formatter.Smart("张三 13800138000 北京市朝阳区建国路1号", true)
+    result1 := formatter.ParseCNAddress("张三 13800138000 北京市朝阳区建国路1号", true)
     jsonData1, _ := json.MarshalIndent(result1, "", "  ")
     fmt.Println("Example 1 - With user info:")
     fmt.Println(string(jsonData1))
 
     // Parse address only, without extracting user information
-    result2 := formatter.Smart("北京市海淀区中关村大街1号", false)
+    result2 := formatter.ParseCNAddress("北京市海淀区中关村大街1号", false)
     fmt.Printf("\nExample 2 - Address only:\n")
     fmt.Printf("Province: %s, City: %s, Region: %s, Street: %s\n",
         result2.Province, result2.City, result2.Region, result2.Street)
 
     // Parse county-level city address
-    result3 := formatter.Smart("河北省石家庄市新乐市经济开发区兴工街10号", false)
+    result3 := formatter.ParseCNAddress("河北省石家庄市新乐市经济开发区兴工街10号", false)
     fmt.Printf("\nExample 3 - County-level city:\n")
     fmt.Printf("Province: %s, City: %s, Region: %s, Street: %s\n",
         result3.Province, result3.City, result3.Region, result3.Street)
 
     // Compact format
-    result4 := formatter.Smart("马云13593464918陕西省西安市雁塔区丈八沟街道", true)
+    result4 := formatter.ParseCNAddress("马云13593464918陕西省西安市雁塔区丈八沟街道", true)
     fmt.Printf("\nExample 4 - Compact format:\n")
     fmt.Printf("Name: %s, Phone: %s, Address: %s%s%s%s\n",
         result4.Name, result4.Mobile, result4.Province, result4.City, result4.Region, result4.Street)
@@ -383,17 +383,17 @@ func main() {
 }
 ```
 
-### <span id="Decompose">Decompose</span>
+### <span id="ParsePersonInfo">ParsePersonInfo</span>
 
 <p>Extracts user information (name, phone, ID card, postal code) from an address string. It separates personal information from the address, supporting labeled format, compact format, and formats with separators. Returns an AddressInfo with extracted user information and cleaned address string.</p>
 
 <b>Signature:</b>
 
 ```go
-func Decompose(str string) *AddressInfo
+func ParsePersonInfo(str string) *AddressInfo
 ```
 
-<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/wXsE5aKfhPk)</span></b>
+<b>Example:<span style="float:right;display:inline-block;">[Run](https://go.dev/play/p/JO-uTlJlTy7)</span></b>
 
 ```go
 package main
@@ -406,17 +406,17 @@ import (
 
 func main() {
     // Extract name and phone
-    result1 := formatter.Decompose("张三 13800138000 北京市朝阳区")
+    result1 := formatter.ParsePersonInfo("张三 13800138000 北京市朝阳区")
     fmt.Println("Example 1 - Name and phone:")
     fmt.Printf("Name: %s, Phone: %s, Address: %s\n", result1.Name, result1.Mobile, result1.Addr)
 
     // Extract ID card number
-    result2 := formatter.Decompose("李四 110101199001011234 上海市")
+    result2 := formatter.ParsePersonInfo("李四 110101199001011234 上海市")
     fmt.Println("\nExample 2 - ID card number:")
     fmt.Printf("Name: %s, ID Card: %s, Address: %s\n", result2.Name, result2.IDN, result2.Addr)
 
     // Labeled format
-    result3 := formatter.Decompose("收货人：王五 电话：13900139000 收货地址：天津市河西区友谊路20号")
+    result3 := formatter.ParsePersonInfo("收货人：王五 电话：13900139000 收货地址：天津市河西区友谊路20号")
     jsonData3, _ := json.MarshalIndent(result3, "", "  ")
     fmt.Println("\nExample 3 - Labeled format:")
     fmt.Println(string(jsonData3))

formatter/address.go

@@ -30,7 +30,7 @@ type fuzzyResult struct {
 	Street string // Street address / 街道地址
 }
 
-// Smart parses a Chinese address string intelligently and extracts structured information.
+// ParseCNAddress parses a Chinese address string intelligently and extracts structured information.
 // It can parse addresses with or without user information (name, phone, ID card, etc.).
 // When withUser is true, it extracts user information from the address string.
 // When withUser is false, it only parses the location information.
@@ -39,7 +39,7 @@ type fuzzyResult struct {
 // - Compact format: "Name Phone Province City District Street"
 // - With keywords: "Name: xxx Phone: xxx Address: xxx"
 // - County-level cities: "Province City CountyCity District" (e.g., "河北省石家庄市新乐市")
-// Smart 智能解析中国地址字符串并提取结构化信息。
+// ParseCNAddress 智能解析中国地址字符串并提取结构化信息。
 // 可以解析带或不带用户信息（姓名、电话、身份证等）的地址。
 // 当 withUser 为 true 时，从地址字符串中提取用户信息。
 // 当 withUser 为 false 时，仅解析位置信息。
@@ -48,12 +48,12 @@ type fuzzyResult struct {
 // - 紧凑格式："姓名 电话 省 市 区 街道"
 // - 带关键词："姓名:xxx 电话:xxx 地址:xxx"
 // - 县级市："省 市 县级市 区"（如"河北省石家庄市新乐市"）
-func Smart(str string, withUser bool) *AddressInfo {
+func ParseCNAddress(str string, withUser bool) *AddressInfo {
 	result := &AddressInfo{}
 
 	if withUser {
-		decompose := Decompose(str)
-		result = decompose
+		ParsePersonInfo := ParsePersonInfo(str)
+		result = ParsePersonInfo
 	} else {
 		result.Addr = str
 	}
@@ -98,19 +98,19 @@ func Smart(str string, withUser bool) *AddressInfo {
 	return result
 }
 
-// Decompose extracts user information (name, phone, ID card, postal code) from an address string.
+// ParsePersonInfo extracts user information (name, phone, ID card, postal code) from an address string.
 // It separates personal information from the address, supporting various formats:
 // - Labeled format: "Name: xxx Phone: xxx Address: xxx"
 // - Compact format: "Name Phone Address" (e.g., "张三13800138000北京市朝阳区")
 // - With separators: using colons, commas, newlines as delimiters
 // Returns an AddressInfo with extracted user information and cleaned address string in Addr field.
-// Decompose 从地址字符串中提取用户信息（姓名、电话、身份证、邮编）。
+// ParsePersonInfo 从地址字符串中提取用户信息（姓名、电话、身份证、邮编）。
 // 将个人信息与地址分离，支持多种格式：
 // - 带标签格式："姓名:xxx 电话:xxx 地址:xxx"
 // - 紧凑格式："姓名 电话 地址"（如"张三13800138000北京市朝阳区"）
 // - 带分隔符：使用冒号、逗号、换行符作为分隔符
 // 返回包含提取的用户信息和清理后地址字符串（在 Addr 字段中）的 AddressInfo。
-func Decompose(str string) *AddressInfo {
+func ParsePersonInfo(str string) *AddressInfo {
 	compose := &AddressInfo{}
 
 	// 先尝试提取带标签的信息

formatter/address_test.go

@@ -5,7 +5,7 @@ import (
 	"testing"
 )
 
-func TestSmart(t *testing.T) {
+func TestParseCNAddress(t *testing.T) {
 	tests := []struct {
 		name     string
 		input    string
@@ -176,7 +176,7 @@ func TestSmart(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := Smart(tt.input, tt.withUser)
+			got := ParseCNAddress(tt.input, tt.withUser)
 
 			// 打印结果便于调试
 			jsonData, _ := json.MarshalIndent(got, "", "  ")
@@ -202,7 +202,7 @@ func TestSmart(t *testing.T) {
 	}
 }
 
-func TestDecompose(t *testing.T) {
+func TestParsePersonInfo(t *testing.T) {
 	tests := []struct {
 		name   string
 		input  string
@@ -248,7 +248,7 @@ func TestDecompose(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := Decompose(tt.input)
+			got := ParsePersonInfo(tt.input)
 			jsonData, _ := json.MarshalIndent(got, "", "  ")
 			t.Logf("Result: %s", jsonData)
 			tt.verify(t, got)
@@ -345,16 +345,16 @@ func TestFuzz(t *testing.T) {
 	}
 }
 
-func ExampleSmart() {
+func ExampleParseCNAddress() {
 	// 解析包含用户信息的完整地址
-	result := Smart("张三 13800138000 北京市朝阳区建国路1号", true)
+	result := ParseCNAddress("张三 13800138000 北京市朝阳区建国路1号", true)
 	jsonData, _ := json.MarshalIndent(result, "", "  ")
 	println(string(jsonData))
 }
 
-func ExampleDecompose() {
+func ExampleParsePersonInfo() {
 	// 分离用户信息
-	result := Decompose("收货人：李四 电话：18612345678 地址：上海市浦东新区世纪大道100号")
+	result := ParsePersonInfo("收货人：李四 电话：18612345678 地址：上海市浦东新区世纪大道100号")
 	jsonData, _ := json.MarshalIndent(result, "", "  ")
 	println(string(jsonData))
 }