doc: add example and update doc for formatter package

README.md

@@ -373,7 +373,10 @@ import "github.com/duke-git/lancet/v2/formatter"
 
 #### Function list:
 
--   [Comma](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#Comma)
+-   **<big>Comma</big>** : add comma to a number value by every 3 numbers from right, ahead by symbol char.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#Comma)]
+    [[play](https://go.dev/play/p/eRD5k2vzUVX)]
+
 
 ### 10. Function package can control the flow of function execution and support part of functional programming
 

README_zh-CN.md

@@ -371,7 +371,11 @@ import "github.com/duke-git/lancet/v2/formatter"
 
 #### 函数列表:
 
--   [Comma](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#Comma)
+-   **<big>Comma</big>** : 用逗号每隔3位分割数字/字符串，支持前缀添加符号。
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#Comma)]
+    [[play](https://go.dev/play/p/eRD5k2vzUVX)]
+
+
 
 ### 10. function 函数包控制函数执行流程，包含部分函数式编程。
 

formatter/formatter.go

@@ -5,6 +5,9 @@
 package formatter
 
 import (
+	"fmt"
+	"reflect"
+	"strconv"
 	"strings"
 
 	"golang.org/x/exp/constraints"
@@ -13,6 +16,7 @@ import (
 // Comma add comma to a number value by every 3 numbers from right. ahead by symbol char.
 // if value is invalid number string eg "aa", return empty string
 // Comma("12345", "$") => "$12,345", Comma(12345, "$") => "$12,345"
+// Play: https://go.dev/play/p/eRD5k2vzUVX
 func Comma[T constraints.Float | constraints.Integer | string](value T, symbol string) string {
 	s, err := numberToString(value)
 	if err != nil {
@@ -26,3 +30,42 @@ func Comma[T constraints.Float | constraints.Integer | string](value T, symbol s
 
 	return symbol + commaString(s)
 }
+
+func commaString(s string) string {
+	if len(s) <= 3 {
+		return s
+	}
+	return commaString(s[:len(s)-3]) + "," + commaString(s[len(s)-3:])
+}
+
+func numberToString(value any) (string, error) {
+	switch reflect.TypeOf(value).Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
+		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return fmt.Sprintf("%v", value), nil
+
+		// todo: need to handle 12345678.9 => 1.23456789e+07
+	case reflect.Float32, reflect.Float64:
+		return fmt.Sprintf("%v", value), nil
+
+	case reflect.String:
+		{
+			sv := fmt.Sprintf("%v", value)
+			if strings.Contains(sv, ".") {
+				_, err := strconv.ParseFloat(sv, 64)
+				if err != nil {
+					return "", err
+				}
+				return sv, nil
+			} else {
+				_, err := strconv.ParseInt(sv, 10, 64)
+				if err != nil {
+					return "", nil
+				}
+				return sv, nil
+			}
+		}
+	default:
+		return "", nil
+	}
+}

formatter/formatter_example_test.go

@@ -0,0 +1,18 @@
+package formatter
+
+import "fmt"
+
+func ExampleComma() {
+	result1 := Comma("123", "")
+	result2 := Comma("12345", "$")
+	result3 := Comma(1234567, "￥")
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+
+	// Output:
+	// 123
+	// $12,345
+	// ￥1,234,567
+}

formatter/formatter_internal.go

@@ -1,47 +0,0 @@
-package formatter
-
-import (
-	"fmt"
-	"reflect"
-	"strconv"
-	"strings"
-)
-
-func commaString(s string) string {
-	if len(s) <= 3 {
-		return s
-	}
-	return commaString(s[:len(s)-3]) + "," + commaString(s[len(s)-3:])
-}
-
-func numberToString(value any) (string, error) {
-	switch reflect.TypeOf(value).Kind() {
-	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
-		reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
-		return fmt.Sprintf("%v", value), nil
-
-		// todo: need to handle 12345678.9 => 1.23456789e+07
-	case reflect.Float32, reflect.Float64:
-		return fmt.Sprintf("%v", value), nil
-
-	case reflect.String:
-		{
-			sv := fmt.Sprintf("%v", value)
-			if strings.Contains(sv, ".") {
-				_, err := strconv.ParseFloat(sv, 64)
-				if err != nil {
-					return "", err
-				}
-				return sv, nil
-			} else {
-				_, err := strconv.ParseInt(sv, 10, 64)
-				if err != nil {
-					return "", nil
-				}
-				return sv, nil
-			}
-		}
-	default:
-		return "", nil
-	}
-}