doc: add docment and example for byte.go

docs/formatter.md

@@ -7,6 +7,7 @@ formatter contains some functions for data formatting.
 ## Source:
 
 -   [https://github.com/duke-git/lancet/blob/main/formatter/formatter.go](https://github.com/duke-git/lancet/blob/main/formatter/formatter.go)
+-   [https://github.com/duke-git/lancet/blob/main/formatter/byte.go](https://github.com/duke-git/lancet/blob/main/formatter/byte.go)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -25,6 +26,10 @@ import (
 -   [Comma](#Comma)
 -   [Pretty](#Pretty)
 -   [PrettyToWriter](#PrettyToWriter)
+-   [DecimalBytes](#DecimalBytes)
+-   [BinaryBytes](#BinaryBytes)
+-   [ParseDecimalBytes](#ParseDecimalBytes)
+-   [ParseBinaryBytes](#ParseBinaryBytes)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -147,3 +152,159 @@ func main() {
     // <nil>
 }
 ```
+
+### <span id="DecimalBytes">DecimalBytes</span>
+
+<p>Returns a human readable byte size under decimal standard (base 1000). The precision parameter specifies the number of digits after the decimal point, which is 4 for default.</p>
+
+<b>Signature:</b>
+
+```go
+func DecimalBytes(size float64, precision ...int) string
+```
+
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1 := formatter.DecimalBytes(1000)
+    result2 := formatter.DecimalBytes(1024)
+    result3 := formatter.DecimalBytes(1234567)
+    result4 := formatter.DecimalBytes(1234567, 3)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 1KB
+    // 1.024KB
+    // 1.2346MB
+    // 1.235MB
+}
+```
+
+### <span id="BinaryBytes">BinaryBytes</span>
+
+<p>Returns a human readable byte size under binary standard (base 1024). The precision parameter specifies the number of digits after the decimal point, which is 4 for default.</p>
+
+<b>Signature:</b>
+
+```go
+func BinaryBytes(size float64, precision ...int) string
+```
+
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1 := formatter.BinaryBytes(1024)
+    result2 := formatter.BinaryBytes(1024 * 1024)
+    result3 := formatter.BinaryBytes(1234567)
+    result4 := formatter.BinaryBytes(1234567, 2)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 1KiB
+    // 1MiB
+    // 1.1774MiB
+    // 1.18MiB
+}
+```
+
+### <span id="ParseDecimalBytes">ParseDecimalBytes</span>
+
+<p>Returns the human readable bytes size string into the amount it represents(base 1000).</p>
+
+<b>Signature:</b>
+
+```go
+func ParseDecimalBytes(size string) (uint64, error)
+```
+
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1, _ := formatter.ParseDecimalBytes("12")
+    result2, _ := formatter.ParseDecimalBytes("12k")
+    result3, _ := formatter.ParseDecimalBytes("12 Kb")
+    result4, _ := formatter.ParseDecimalBytes("12.2 kb")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 12
+    // 12000
+    // 12000
+    // 12200
+}
+```
+
+### <span id="ParseBinaryBytes">ParseBinaryBytes</span>
+
+<p>Returns the human readable bytes size string into the amount it represents(base 1024).</p>
+
+<b>Signature:</b>
+
+```go
+func ParseBinaryBytes(size string) (uint64, error)
+```
+
+<b>Example:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1, _ := formatter.ParseBinaryBytes("12")
+    result2, _ := formatter.ParseBinaryBytes("12ki")
+    result3, _ := formatter.ParseBinaryBytes("12 KiB")
+    result4, _ := formatter.ParseBinaryBytes("12.2 kib")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 12
+    // 12288
+    // 12288
+    // 12492
+}
+```

docs/formatter_zh-CN.md

@@ -7,6 +7,7 @@ formatter 格式化器包含一些数据格式化处理方法。
 ## 源码:
 
 -   [https://github.com/duke-git/lancet/blob/main/formatter/formatter.go](https://github.com/duke-git/lancet/blob/main/formatter/formatter.go)
+-   [https://github.com/duke-git/lancet/blob/main/formatter/byte.go](https://github.com/duke-git/lancet/blob/main/formatter/byte.go)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -25,6 +26,10 @@ import (
 -   [Comma](#Comma)
 -   [Pretty](#Pretty)
 -   [PrettyToWriter](#PrettyToWriter)
+-   [DecimalBytes](#DecimalBytes)
+-   [BinaryBytes](#BinaryBytes)
+-   [ParseDecimalBytes](#ParseDecimalBytes)
+-   [ParseBinaryBytes](#ParseBinaryBytes)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -147,3 +152,159 @@ func main() {
     // <nil>
 }
 ```
+
+### <span id="DecimalBytes">DecimalBytes</span>
+
+<p>返回十进制标准（以1000为基数）下的可读字节单位字符串。precision参数指定小数点后的位数，默认为4。</p>
+
+<b>函数签名:</b>
+
+```go
+func DecimalBytes(size float64, precision ...int) string
+```
+
+<b>示例:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1 := formatter.DecimalBytes(1000)
+    result2 := formatter.DecimalBytes(1024)
+    result3 := formatter.DecimalBytes(1234567)
+    result4 := formatter.DecimalBytes(1234567, 3)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 1KB
+    // 1.024KB
+    // 1.2346MB
+    // 1.235MB
+}
+```
+
+### <span id="BinaryBytes">BinaryBytes</span>
+
+<p>返回binary标准（以1024为基数）下的可读字节单位字符串。precision参数指定小数点后的位数，默认为4。</p>
+
+<b>函数签名:</b>
+
+```go
+func BinaryBytes(size float64, precision ...int) string
+```
+
+<b>示例:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1 := formatter.BinaryBytes(1024)
+    result2 := formatter.BinaryBytes(1024 * 1024)
+    result3 := formatter.BinaryBytes(1234567)
+    result4 := formatter.BinaryBytes(1234567, 2)
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 1KiB
+    // 1MiB
+    // 1.1774MiB
+    // 1.18MiB
+}
+```
+
+### <span id="ParseDecimalBytes">ParseDecimalBytes</span>
+
+<p>将字节单位字符串转换成其所表示的字节数（以1000为基数）。</p>
+
+<b>函数签名:</b>
+
+```go
+func ParseDecimalBytes(size string) (uint64, error)
+```
+
+<b>示例:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1, _ := formatter.ParseDecimalBytes("12")
+    result2, _ := formatter.ParseDecimalBytes("12k")
+    result3, _ := formatter.ParseDecimalBytes("12 Kb")
+    result4, _ := formatter.ParseDecimalBytes("12.2 kb")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 12
+    // 12000
+    // 12000
+    // 12200
+}
+```
+
+### <span id="ParseBinaryBytes">ParseBinaryBytes</span>
+
+<p>将字节单位字符串转换成其所表示的字节数（以1024为基数）。</p>
+
+<b>函数签名:</b>
+
+```go
+func ParseBinaryBytes(size string) (uint64, error)
+```
+
+<b>示例:</b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/formatter"
+)
+
+func main() {
+    result1, _ := formatter.ParseBinaryBytes("12")
+    result2, _ := formatter.ParseBinaryBytes("12ki")
+    result3, _ := formatter.ParseBinaryBytes("12 KiB")
+    result4, _ := formatter.ParseBinaryBytes("12.2 kib")
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+    fmt.Println(result3)
+    fmt.Println(result4)
+
+    // Output:
+    // 12
+    // 12288
+    // 12288
+    // 12492
+}
+```

formatter/byte.go

@@ -93,7 +93,7 @@ func DecimalBytes(size float64, precision ...int) string {
 	return fmt.Sprintf("%.*g%s", p, size, unit)
 }
 
-// BinaryBytes returns a human-readable byte size under decimal standard (base 1024)
+// 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
 func BinaryBytes(size float64, precision ...int) string {
@@ -116,14 +116,14 @@ func calculateByteSize(size float64, base float64, byteUnits []string) (float64,
 	return size, byteUnits[i]
 }
 
-// ParseDecimalBytes the human readable bytes size string into the amount it represents(base 1000).
+// ParseDecimalBytes return the human readable bytes size string into the amount it represents(base 1000).
 // ParseDecimalBytes("42 MB") -> 42000000, nil
 // Play: todo
 func ParseDecimalBytes(size string) (uint64, error) {
 	return parseBytes(size, "decimal")
 }
 
-// ParseBinaryBytes the human readable bytes size string into the amount it represents(base 1024).
+// ParseBinaryBytes return the human readable bytes size string into the amount it represents(base 1024).
 // ParseBinaryBytes("42 mib") -> 44040192, nil
 // Play: todo
 func ParseBinaryBytes(size string) (uint64, error) {

formatter/formatter_example_test.go

@@ -59,3 +59,75 @@ func ExamplePrettyToWriter() {
 	//
 	// <nil>
 }
+
+func ExampleDecimalBytes() {
+	result1 := DecimalBytes(1000)
+	result2 := DecimalBytes(1024)
+	result3 := DecimalBytes(1234567)
+	result4 := DecimalBytes(1234567, 3)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+	fmt.Println(result4)
+
+	// Output:
+	// 1KB
+	// 1.024KB
+	// 1.2346MB
+	// 1.235MB
+}
+
+func ExampleBinaryBytes() {
+	result1 := BinaryBytes(1024)
+	result2 := BinaryBytes(1024 * 1024)
+	result3 := BinaryBytes(1234567)
+	result4 := BinaryBytes(1234567, 2)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+	fmt.Println(result4)
+
+	// Output:
+	// 1KiB
+	// 1MiB
+	// 1.1774MiB
+	// 1.18MiB
+}
+
+func ExampleParseDecimalBytes() {
+	result1, _ := ParseDecimalBytes("12")
+	result2, _ := ParseDecimalBytes("12k")
+	result3, _ := ParseDecimalBytes("12 Kb")
+	result4, _ := ParseDecimalBytes("12.2 kb")
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+	fmt.Println(result4)
+
+	// Output:
+	// 12
+	// 12000
+	// 12000
+	// 12200
+}
+
+func ExampleParseBinaryBytes() {
+	result1, _ := ParseBinaryBytes("12")
+	result2, _ := ParseBinaryBytes("12ki")
+	result3, _ := ParseBinaryBytes("12 KiB")
+	result4, _ := ParseBinaryBytes("12.2 kib")
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+	fmt.Println(result4)
+
+	// Output:
+	// 12
+	// 12288
+	// 12288
+	// 12492
+}