From 4a298876e9ec94b0319f9a3f034ae6706de266d8 Mon Sep 17 00:00:00 2001 From: dudaodong Date: Fri, 7 Apr 2023 14:53:48 +0800 Subject: [PATCH] doc: add docment and example for byte.go --- docs/formatter.md | 161 ++++++++++++++++++++++++++++ docs/formatter_zh-CN.md | 161 ++++++++++++++++++++++++++++ formatter/byte.go | 6 +- formatter/formatter_example_test.go | 72 +++++++++++++ 4 files changed, 397 insertions(+), 3 deletions(-) diff --git a/docs/formatter.md b/docs/formatter.md index 18e5192..84104fb 100644 --- a/docs/formatter.md +++ b/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)
@@ -25,6 +26,10 @@ import ( - [Comma](#Comma) - [Pretty](#Pretty) - [PrettyToWriter](#PrettyToWriter) +- [DecimalBytes](#DecimalBytes) +- [BinaryBytes](#BinaryBytes) +- [ParseDecimalBytes](#ParseDecimalBytes) +- [ParseBinaryBytes](#ParseBinaryBytes)
@@ -147,3 +152,159 @@ func main() { // } ``` + +### 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 is 4 for default.

+ +Signature: + +```go +func DecimalBytes(size float64, precision ...int) string +``` + +Example: + +```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 +} +``` + +### 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 is 4 for default.

+ +Signature: + +```go +func BinaryBytes(size float64, precision ...int) string +``` + +Example: + +```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 +} +``` + +### ParseDecimalBytes + +

Returns the human readable bytes size string into the amount it represents(base 1000).

+ +Signature: + +```go +func ParseDecimalBytes(size string) (uint64, error) +``` + +Example: + +```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 +} +``` + +### ParseBinaryBytes + +

Returns the human readable bytes size string into the amount it represents(base 1024).

+ +Signature: + +```go +func ParseBinaryBytes(size string) (uint64, error) +``` + +Example: + +```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 +} +``` diff --git a/docs/formatter_zh-CN.md b/docs/formatter_zh-CN.md index 080dabd..ab29ae2 100644 --- a/docs/formatter_zh-CN.md +++ b/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)
@@ -25,6 +26,10 @@ import ( - [Comma](#Comma) - [Pretty](#Pretty) - [PrettyToWriter](#PrettyToWriter) +- [DecimalBytes](#DecimalBytes) +- [BinaryBytes](#BinaryBytes) +- [ParseDecimalBytes](#ParseDecimalBytes) +- [ParseBinaryBytes](#ParseBinaryBytes)
@@ -147,3 +152,159 @@ func main() { // } ``` + +### DecimalBytes + +

返回十进制标准（以1000为基数）下的可读字节单位字符串。precision参数指定小数点后的位数，默认为4。

+ +函数签名: + +```go +func DecimalBytes(size float64, precision ...int) string +``` + +示例: + +```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 +} +``` + +### BinaryBytes + +

返回binary标准（以1024为基数）下的可读字节单位字符串。precision参数指定小数点后的位数，默认为4。

+ +函数签名: + +```go +func BinaryBytes(size float64, precision ...int) string +``` + +示例: + +```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 +} +``` + +### ParseDecimalBytes + +

将字节单位字符串转换成其所表示的字节数（以1000为基数）。

+ +函数签名: + +```go +func ParseDecimalBytes(size string) (uint64, error) +``` + +示例: + +```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 +} +``` + +### ParseBinaryBytes + +

将字节单位字符串转换成其所表示的字节数（以1024为基数）。

+ +函数签名: + +```go +func ParseBinaryBytes(size string) (uint64, error) +``` + +示例: + +```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 +} +``` diff --git a/formatter/byte.go b/formatter/byte.go index a90c00b..685661f 100644 --- a/formatter/byte.go +++ b/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) { diff --git a/formatter/formatter_example_test.go b/formatter/formatter_example_test.go index ec14587..5f18e4e 100644 --- a/formatter/formatter_example_test.go +++ b/formatter/formatter_example_test.go @@ -59,3 +59,75 @@ func ExamplePrettyToWriter() { // // } + +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 +}