doc: add docment and playground demo for v2.1.19

2026-02-04 12:52:28 +08:00 · 2023-04-18 15:21:03 +08:00
parent 52ea64bc33
commit fcb3b97b45
10 changed files with 49 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -543,6 +543,7 @@ import "github.com/duke-git/lancet/v2/fileutil"
    [[play](https://go.dev/play/p/g0w34kS7B8m)]
 -   **<big>CurrentPath</big>** : return current absolute path.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/fileutil.md#CurrentPath)]
+    [[play](https://go.dev/play/p/s74a9iBGcSw)]

 ### 9. Formatter contains some functions for data formatting.

@@ -557,16 +558,22 @@ import "github.com/duke-git/lancet/v2/formatter"
    [[play](https://go.dev/play/p/eRD5k2vzUVX)]
 -   **<big>Pretty</big>** : pretty print data to JSON string.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#Pretty)]
+    [[play](https://go.dev/play/p/YsciGj3FH2x)]
 -   **<big>PrettyToWriter</big>** : pretty encode data to writer.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#PrettyToWriter)]
+    [[play](https://go.dev/play/p/LPLZ3lDi5ma)]
 -   **<big>DecimalBytes</big>** : returns a human readable byte size under decimal standard (base 1000).
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#DecimalBytes)]
+    [[play](https://go.dev/play/p/FPXs1suwRcs)]
 -   **<big>BinaryBytes</big>** : returns a human-readable byte size under binary standard (base 1024).
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#BinaryBytes)]
+    [[play](https://go.dev/play/p/G9oHHMCAZxP)]
 -   **<big>ParseDecimalBytes</big>** : return the human readable bytes size string into the amount it represents(base 1000).
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter.md#ParseDecimalBytes)]
+    [[play](https://go.dev/play/p/Am98ybWjvjj)]
 -   **<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/formatter.md#ParseBinaryBytes)]
+    [[play](https://go.dev/play/p/69v1tTT62x8)]

 ### 10. Function package can control the flow of function execution and support part of functional programming

@@ -614,6 +621,7 @@ import "github.com/duke-git/lancet/v2/maputil"

 -   **<big>MapTo</big>** : quick map any value to struct or any base type.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/maputil.md#MapTo)]
+    [[play](https://go.dev/play/p/4K7KBEPgS5M)]
 -   **<big>ForEach</big>** : executes iteratee funcation for every key and value pair in map.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/maputil.md#ForEach)]
    [[play](https://go.dev/play/p/OaThj6iNVXK)]
@@ -988,11 +996,13 @@ import "github.com/duke-git/lancet/v2/slice"
    [[play](https://go.dev/play/p/8uI8f1lwNrQ)]
 -   **<big>Reduce<sup>deprecated</sup></big>** : creates an slice of values by running each element of slice thru iteratee function.(Deprecated: use ReduceBy)
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice.md#Reduce)]
+    [[play](https://go.dev/play/p/_RfXJJWIsIm)]
 -   **<big>ReduceBy</big>** : produces a value from slice by accumulating the result of each element as passed through the reducer function.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice.md#ReduceBy)]
+    [[play](https://go.dev/play/p/YKDpLi7gtee)]
 -   **<big>ReduceRight</big>** : ReduceRight is like ReduceBy, but it iterates over elements of slice from right to left.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice.md#ReduceRight)]
-    [[play](https://go.dev/play/p/_RfXJJWIsIm)]
+    [[play](https://go.dev/play/p/qT9dZC03A1K)]
 -   **<big>Replace</big>** : returns a copy of the slice with the first n non-overlapping instances of old replaced by new.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice.md#Replace)]
    [[play](https://go.dev/play/p/P5mZp7IhOFo)]
@@ -1351,11 +1361,13 @@ import "github.com/duke-git/lancet/v2/validator"
    [[play](https://go.dev/play/p/dpzgUjFnBCX)]
 -   **<big>IsFloat</big>** : check if the value is float(float32, float34) or not.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsFloat)]
+    [[play](https://go.dev/play/p/vsyG-sxr99_Z)]
 -   **<big>IsFloatStr</big>** : check if the string can convert to a float.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsFloatStr)]
    [[play](https://go.dev/play/p/LOYwS_Oyl7U)]
 -   **<big>IsNumber</big>** : check if the value is number(integer, float) or not.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsNumber)]
+    [[play](https://go.dev/play/p/mdJHOAvtsvF)]
 -   **<big>IsNumberStr</big>** : check if the string can convert to a number.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsNumberStr)]
    [[play](https://go.dev/play/p/LzaKocSV79u)]
@@ -1367,6 +1379,7 @@ import "github.com/duke-git/lancet/v2/validator"
    [[play](https://go.dev/play/p/z_XeZo_litG)]
 -   **<big>IsInt</big>** : check if the string can convert to a number.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsInt)]
+    [[play](https://go.dev/play/p/eFoIHbgzl-z)]
 -   **<big>IsIntStr</big>** : check if the string can convert to a integer.
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator.md#IsIntStr)]
    [[play](https://go.dev/play/p/jQRtFv-a0Rk)]
--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -542,6 +542,7 @@ import "github.com/duke-git/lancet/v2/fileutil"
    [[play](https://go.dev/play/p/g0w34kS7B8m)]
 -   **<big>CurrentPath</big>** : 返回当前位置的绝对路径。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/fileutil_zh-CN.md#CurrentPath)]
+    [[play](https://go.dev/play/p/s74a9iBGcSw)]

 ### 9. formatter 格式化器包含一些数据格式化处理方法。

@@ -556,16 +557,22 @@ import "github.com/duke-git/lancet/v2/formatter"
    [[play](https://go.dev/play/p/eRD5k2vzUVX)]
 -   **<big>Pretty</big>** : 返回 pretty JSON 字符串。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#Pretty)]
+    [[play](https://go.dev/play/p/YsciGj3FH2x)]
 -   **<big>PrettyToWriter</big>** : Pretty encode 数据到 writer。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#PrettyToWriter)]
+    [[play](https://go.dev/play/p/LPLZ3lDi5ma)]
 -   **<big>DecimalBytes</big>** : 返回十进制标准（以 1000 为基数）下的可读字节单位字符串。precision 参数指定小数点后的位数，默认为 4。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#DecimalBytes)]
+    [[play](https://go.dev/play/p/FPXs1suwRcs)]
 -   **<big>BinaryBytes</big>** : 返回 binary 标准（以 1024 为基数）下的可读字节单位字符串。precision 参数指定小数点后的位数，默认为 4。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#BinaryBytes)]
+    [[play](https://go.dev/play/p/G9oHHMCAZxP)]
 -   **<big>ParseDecimalBytes</big>** : 将字节单位字符串转换成其所表示的字节数（以 1000 为基数）。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#ParseDecimalBytes)]
+    [[play](https://go.dev/play/p/Am98ybWjvjj)]
 -   **<big>ParseBinaryBytes</big>** : 将字节单位字符串转换成其所表示的字节数（以 1024 为基数）。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/formatter_zh-CN.md#ParseBinaryBytes)]
+    [[play](https://go.dev/play/p/69v1tTT62x8)]

 ### 10. function 函数包控制函数执行流程，包含部分函数式编程。

@@ -613,6 +620,7 @@ import "github.com/duke-git/lancet/v2/maputil"

 -   **<big>MapTo</big>** : 快速将 map 或者其他类型映射到结构体或者指定类型。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/maputil_zh-CN.md#MapTo)]
+    [[play](https://go.dev/play/p/4K7KBEPgS5M)]
 -   **<big>ForEach</big>** : 对 map 中的每对 key 和 value 执行 iteratee 函数。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/maputil_zh-CN.md#ForEach)]
    [[play](https://go.dev/play/p/OaThj6iNVXK)]
@@ -990,8 +998,10 @@ import "github.com/duke-git/lancet/v2/slice"
    [[play](https://go.dev/play/p/_RfXJJWIsIm)]
 -   **<big>ReduceBy</big>** : 对切片元素执行 reduce 操作。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice_zh-CN.md#ReduceBy)]
+    [[play](https://go.dev/play/p/YKDpLi7gtee)]
 -   **<big>ReduceRight</big>** : 类似 ReduceBy 操作，迭代切片元素顺序从右至左。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice_zh-CN.md#ReduceRight)]
+    [[play](https://go.dev/play/p/qT9dZC03A1K)]
 -   **<big>Replace</big>** : 返回切片的副本，其中前 n 个不重叠的 old 替换为 new。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/slice_zh-CN.md#Replace)]
    [[play](https://go.dev/play/p/P5mZp7IhOFo)]
@@ -1353,11 +1363,13 @@ import "github.com/duke-git/lancet/v2/validator"
    [[play](https://go.dev/play/p/dpzgUjFnBCX)]
 -   **<big>IsFloat</big>** : 验证参数是否是浮点数((float32，float34)。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsFloat)]
+    [[play](https://go.dev/play/p/vsyG-sxr99_Z)]
 -   **<big>IsFloatStr</big>** : 验证字符串是否是可以转换为浮点数。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsFloatStr)]
    [[play](https://go.dev/play/p/LOYwS_Oyl7U)]
 -   **<big>IsNumber</big>** : 验证参数是否是数字(integer，float)。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsNumber)]
+    [[play](https://go.dev/play/p/mdJHOAvtsvF)]
 -   **<big>IsNumberStr</big>** : 验证字符串是否是可以转换为数字。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsNumberStr)]
    [[play](https://go.dev/play/p/LzaKocSV79u)]
@@ -1369,6 +1381,7 @@ import "github.com/duke-git/lancet/v2/validator"
    [[play](https://go.dev/play/p/z_XeZo_litG)]
 -   **<big>IsInt</big>** : 验证参数是否是整数(int, unit)。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsInt)]
+    [[play](https://go.dev/play/p/eFoIHbgzl-z)]
 -   **<big>IsIntStr</big>** : 验证字符串是否是可以转换为整数。
    [[doc](https://github.com/duke-git/lancet/blob/main/docs/validator_zh-CN.md#IsIntStr)]
    [[play](https://go.dev/play/p/jQRtFv-a0Rk)]
--- a/docs/system.md
+++ b/docs/system.md
@@ -239,14 +239,17 @@ func main() {
 }
 ```

-### <span id="ExecCommand">CompareOsEnv</span>
+### <span id="ExecCommand">ExecCommand</span>

 <p>Execute shell command, return the stdout and stderr string of command, and error if error occur. param `command` is a complete command string, like, ls -a (linux), dir(windows), ping 127.0.0.1. In linux, use /bin/bash -c to execute command, In windows, use powershell.exe to execute command.</p>

 <b>Signature:</b>

 ```go
-func ExecCommand(command string) (stdout, stderr string, err error)
+type (
+	Option func(*exec.Cmd)
+)
+func ExecCommand(command string, opts ...Option) (stdout, stderr string, err error)
 ```

 <b>Example:</b>
--- a/docs/system_zh-CN.md
+++ b/docs/system_zh-CN.md
@@ -246,7 +246,10 @@ func main() {
 <b>Signature:</b>

 ```go
-func ExecCommand(command string) (stdout, stderr string, err error)
+type (
+	Option func(*exec.Cmd)
+)
+func ExecCommand(command string, opts ...Option) (stdout, stderr string, err error)
 ```

 <b>Example:</b>
--- a/fileutil/file.go
+++ b/fileutil/file.go
@@ -348,7 +348,7 @@ func MiMeType(file any) string {
 }

 // CurrentPath return current absolute path.
-// Play: todo
+// Play: https://go.dev/play/p/s74a9iBGcSw
 func CurrentPath() string {
 	var absPath string
 	_, filename, _, ok := runtime.Caller(1)
--- a/formatter/byte.go
+++ b/formatter/byte.go
@@ -82,7 +82,7 @@ var (

 // DecimalBytes returns a human readable byte size under decimal standard (base 1000)
 // The precision parameter specifies the number of digits after the decimal point, which defaults to 4.
-// Play: todo
+// Play: https://go.dev/play/p/FPXs1suwRcs
 func DecimalBytes(size float64, precision ...int) string {
 	p := 5
 	if len(precision) > 0 {
@@ -95,7 +95,7 @@ func DecimalBytes(size float64, precision ...int) string {

 // BinaryBytes returns a human-readable byte size under binary standard (base 1024)
 // The precision parameter specifies the number of digits after the decimal point, which defaults to 4.
-// Play: todo
+// Play: https://go.dev/play/p/G9oHHMCAZxP
 func BinaryBytes(size float64, precision ...int) string {
 	p := 5
 	if len(precision) > 0 {
@@ -118,14 +118,14 @@ func calculateByteSize(size float64, base float64, byteUnits []string) (float64,

 // ParseDecimalBytes return the human readable bytes size string into the amount it represents(base 1000).
 // ParseDecimalBytes("42 MB") -> 42000000, nil
-// Play: todo
+// Play: https://go.dev/play/p/Am98ybWjvjj
 func ParseDecimalBytes(size string) (uint64, error) {
 	return parseBytes(size, "decimal")
 }

 // ParseBinaryBytes return the human readable bytes size string into the amount it represents(base 1024).
 // ParseBinaryBytes("42 mib") -> 44040192, nil
-// Play: todo
+// Play: https://go.dev/play/p/69v1tTT62x8
 func ParseBinaryBytes(size string) (uint64, error) {
 	return parseBytes(size, "binary")
 }
--- a/formatter/formatter.go
+++ b/formatter/formatter.go
@@ -48,14 +48,14 @@ func Comma[T constraints.Float | constraints.Integer | string](value T, symbol s
 }

 // Pretty data to JSON string.
-// Play: todo
+// Play: https://go.dev/play/p/YsciGj3FH2x
 func Pretty(v any) (string, error) {
 	out, err := json.MarshalIndent(v, "", "    ")
 	return string(out), err
 }

 // PrettyToWriter pretty encode data to writer.
-// Play: todo
+// Play: https://go.dev/play/p/LPLZ3lDi5ma
 func PrettyToWriter(v any, out io.Writer) error {
 	enc := json.NewEncoder(out)
 	enc.SetIndent("", "    ")
--- a/maputil/typemap.go
+++ b/maputil/typemap.go
@@ -60,6 +60,7 @@ var _ = func() struct{} {
 		log.Println(dist)

 */
+// Play: https://go.dev/play/p/4K7KBEPgS5M
 func MapTo(src any, dst any) error {

 	dstRef := reflect.ValueOf(dst)
--- a/slice/slice.go
+++ b/slice/slice.go
@@ -523,7 +523,7 @@ func Reduce[T any](slice []T, iteratee func(index int, item1, item2 T) T, initia
 }

 // ReduceBy produces a value from slice by accumulating the result of each element as passed through the reducer function.
-// Play: todo
+// Play: https://go.dev/play/p/YKDpLi7gtee
 func ReduceBy[T any, U any](slice []T, initial U, reducer func(index int, item T, agg U) U) U {
 	accumulator := initial

@@ -535,7 +535,7 @@ func ReduceBy[T any, U any](slice []T, initial U, reducer func(index int, item T
 }

 // ReduceRight is like ReduceBy, but it iterates over elements of slice from right to left.
-// Play: todo
+// Play: https://go.dev/play/p/qT9dZC03A1K
 func ReduceRight[T any, U any](slice []T, initial U, reducer func(index int, item T, agg U) U) U {
 	accumulator := initial

--- a/validator/validator.go
+++ b/validator/validator.go
@@ -371,13 +371,13 @@ func IsGBK(data []byte) bool {
 }

 // IsNumberStr check if the value is number(integer, float) or not.
-// Play: todo
+// Play: https://go.dev/play/p/mdJHOAvtsvF
 func IsNumber(v any) bool {
 	return IsInt(v) || IsFloat(v)
 }

 // IsFloat check if the value is float(float32, float34) or not.
-// Play: todo
+// Play: https://go.dev/play/p/vsyG-sxr99_Z
 func IsFloat(v any) bool {
 	switch v.(type) {
 	case float32, float64:
@@ -387,7 +387,7 @@ func IsFloat(v any) bool {
 }

 // IsInt check if the value is integer(int, unit) or not.
-// Play: todo
+// Play: https://go.dev/play/p/eFoIHbgzl-z
 func IsInt(v any) bool {
 	switch v.(type) {
 	case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, uintptr: