update readme file

README.md

@@ -24,7 +24,7 @@ English | [简体中文](./README_zh-CN.md)
 ## Feature
 
 -   👏 Comprehensive, efficient and reusable.
--   💪 400+ go util functions, support string, slice, datetime, net, crypt...
+-   💪 500+ go util functions, support string, slice, datetime, net, crypt...
 -   💅 Only depend on the go standard library.
 -   🌍 Unit test for every exported function.
 
@@ -41,7 +41,7 @@ go get github.com/duke-git/lancet/v2 // will install latest version of v2.x.x
 2. <b>For users who use version below go1.18, you should install v1.x.x. The latest of v1.x.x is v1.3.7. </b>
 
 ```go
-go get github.com/duke-git/lancet@v1.3.7 // below go1.18, install latest version of v1.x.x
+go get github.com/duke-git/lancet // below go1.18, install latest version of v1.x.x
 ```
 
 ## Usage
@@ -772,15 +772,15 @@ import "github.com/duke-git/lancet/v2/netutil"
 -   **<big>StructToUrlValues</big>** : convert struct to url valuse.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#StructToUrlValues)]
     [[play](https://go.dev/play/p/pFqMkM40w9z)]
--   **<big>HttpGet<sup>deprecated</sup></big>** : send get http request.
+-   **<big>HttpGet<sup>deprecated</sup></big>** : send http get request.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#HttpGet)]
--   **<big>HttpDelete<sup>deprecated</sup></big>** : send delete http request.
+-   **<big>HttpDelete<sup>deprecated</sup></big>** : send http delete request.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#HttpDelete)]
--   **<big>HttpPost<sup>deprecated</sup></big>** : send post http request.
+-   **<big>HttpPost<sup>deprecated</sup></big>** : send http post request.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#HttpPost)]
--   **<big>HttpPut<sup>deprecated</sup></big>** : send put http request.
+-   **<big>HttpPut<sup>deprecated</sup></big>** : send http put request.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#HttpPut)]
--   **<big>HttpPatch<sup>deprecated</sup></big>** : send patch http request.
+-   **<big>HttpPatch<sup>deprecated</sup></big>** : send http patch request.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#HttpPatch)]
 -   **<big>ParseHttpResponse</big>** : decode http response into target object.
     [[doc](https://github.com/duke-git/lancet/blob/main/docs/netutil.md#ParseHttpResponse)]

README_zh-CN.md

@@ -23,7 +23,7 @@
 ## 特性
 
 -   👏 全面、高效、可复用
--   💪 400+常用 go 工具函数，支持 string、slice、datetime、net、crypt...
+-   💪 500+常用 go 工具函数，支持 string、slice、datetime、net、crypt...
 -   💅 只依赖 go 标准库
 -   🌍 所有导出函数单元测试覆盖率 100%
 
@@ -40,7 +40,7 @@ go get github.com/duke-git/lancet/v2 //安装v2最新版本v2.x.x
 2. <b>使用 go1.18 以下版本的用户，必须安装 v1.x.x。目前最新的 v1 版本是 v1.3.7。</b>
 
 ```go
-go get github.com/duke-git/lancet@v1.3.7 // 使用go1.18以下版本, 必须安装v1.x.x版本
+go get github.com/duke-git/lancet// 使用go1.18以下版本, 必须安装v1.x.x版本
 ```
 
 ## 用法

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

@@ -0,0 +1,178 @@
+package formatter
+
+import (
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"unicode"
+)
+
+//
+// code logic come from:
+// https://github.com/docker/go-units/blob/master/size.go
+
+// http://en.wikipedia.org/wiki/Binary_prefix
+const (
+	// Decimal
+	UnitB  = 1
+	UnitKB = 1000
+	UnitMB = 1000 * UnitKB
+	UnitGB = 1000 * UnitMB
+	UnitTB = 1000 * UnitGB
+	UnitPB = 1000 * UnitTB
+	UnitEB = 1000 * UnitPB
+
+	// Binary
+	UnitBiB = 1
+	UnitKiB = 1024
+	UnitMiB = 1024 * UnitKiB
+	UnitGiB = 1024 * UnitMiB
+	UnitTiB = 1024 * UnitGiB
+	UnitPiB = 1024 * UnitTiB
+	UnitEiB = 1024 * UnitPiB
+)
+
+// type byteUnitMap map[byte]int64
+
+var (
+	decimalByteMap = map[string]uint64{
+		"b":  UnitB,
+		"kb": UnitKB,
+		"mb": UnitMB,
+		"gb": UnitGB,
+		"tb": UnitTB,
+		"pb": UnitPB,
+		"eb": UnitEB,
+
+		// Without suffix
+		"":  UnitB,
+		"k": UnitKB,
+		"m": UnitMB,
+		"g": UnitGB,
+		"t": UnitTB,
+		"p": UnitPB,
+		"e": UnitEB,
+	}
+
+	binaryByteMap = map[string]uint64{
+		"bi":  UnitBiB,
+		"kib": UnitKiB,
+		"mib": UnitMiB,
+		"gib": UnitGiB,
+		"tib": UnitTiB,
+		"pib": UnitPiB,
+		"eib": UnitEiB,
+
+		// Without suffix
+		"":   UnitBiB,
+		"ki": UnitKiB,
+		"mi": UnitMiB,
+		"gi": UnitGiB,
+		"ti": UnitTiB,
+		"pi": UnitPiB,
+		"ei": UnitEiB,
+	}
+)
+
+var (
+	decimalByteUnits = []string{"B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"}
+	binaryByteUnits  = []string{"B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"}
+)
+
+// 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
+func DecimalBytes(size float64, precision ...int) string {
+	p := 5
+	if len(precision) > 0 {
+		p = precision[0] + 1
+	}
+	size, unit := calculateByteSize(size, 1000.0, decimalByteUnits)
+
+	return fmt.Sprintf("%.*g%s", p, size, unit)
+}
+
+// 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 {
+	p := 5
+	if len(precision) > 0 {
+		p = precision[0] + 1
+	}
+	size, unit := calculateByteSize(size, 1024.0, binaryByteUnits)
+
+	return fmt.Sprintf("%.*g%s", p, size, unit)
+}
+
+func calculateByteSize(size float64, base float64, byteUnits []string) (float64, string) {
+	i := 0
+	unitsLimit := len(byteUnits) - 1
+	for size >= base && i < unitsLimit {
+		size = size / base
+		i++
+	}
+	return size, byteUnits[i]
+}
+
+// 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 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) {
+	return parseBytes(size, "binary")
+}
+
+// see https://github.com/dustin/go-humanize/blob/master/bytes.go
+func parseBytes(s string, kind string) (uint64, error) {
+	lastDigit := 0
+	hasComma := false
+	for _, r := range s {
+		if !(unicode.IsDigit(r) || r == '.' || r == ',') {
+			break
+		}
+		if r == ',' {
+			hasComma = true
+		}
+		lastDigit++
+	}
+
+	num := s[:lastDigit]
+	if hasComma {
+		num = strings.Replace(num, ",", "", -1)
+	}
+
+	f, err := strconv.ParseFloat(num, 64)
+	if err != nil {
+		return 0, err
+	}
+
+	extra := strings.ToLower(strings.TrimSpace(s[lastDigit:]))
+
+	if kind == "decimal" {
+		if m, ok := decimalByteMap[extra]; ok {
+			f *= float64(m)
+			if f >= math.MaxUint64 {
+				return 0, fmt.Errorf("too large: %v", s)
+			}
+			return uint64(f), nil
+		}
+	} else {
+		if m, ok := binaryByteMap[extra]; ok {
+			f *= float64(m)
+			if f >= math.MaxUint64 {
+				return 0, fmt.Errorf("too large: %v", s)
+			}
+			return uint64(f), nil
+		}
+	}
+
+	return 0, fmt.Errorf("unhandled size name: %v", extra)
+}

formatter/byte_test.go

@@ -0,0 +1,87 @@
+package formatter
+
+import (
+	"testing"
+
+	"github.com/duke-git/lancet/v2/internal"
+)
+
+func TestDecimalBytes(t *testing.T) {
+	assert := internal.NewAssert(t, "TestDecimalBytes")
+
+	assert.Equal("1KB", DecimalBytes(1000))
+	assert.Equal("1.024KB", DecimalBytes(1024))
+	assert.Equal("1.2346MB", DecimalBytes(1234567))
+	assert.Equal("1.235MB", DecimalBytes(1234567, 3))
+	assert.Equal("1.123GB", DecimalBytes(float64(1.123*UnitGB)))
+	assert.Equal("2.123TB", DecimalBytes(float64(2.123*UnitTB)))
+	assert.Equal("3.123PB", DecimalBytes(float64(3.123*UnitPB)))
+	assert.Equal("4.123EB", DecimalBytes(float64(4.123*UnitEB)))
+	assert.Equal("1EB", DecimalBytes(float64(1000*UnitPB)))
+}
+
+func TestBinaryBytes(t *testing.T) {
+	assert := internal.NewAssert(t, "TestBinaryBytes")
+
+	assert.Equal("1KiB", BinaryBytes(1024))
+	assert.Equal("1MiB", BinaryBytes(1024*1024))
+	assert.Equal("1.1774MiB", BinaryBytes(1234567))
+	assert.Equal("1.18MiB", BinaryBytes(1234567, 2))
+}
+
+func TestParseDecimalBytes(t *testing.T) {
+	assert := internal.NewAssert(t, "TestParseDecimalBytes")
+
+	cases := map[string]uint64{
+		"12":      uint64(12),
+		"12 k":    uint64(12000),
+		"12 kb":   uint64(12000),
+		"12kb":    uint64(12000),
+		"12k":     uint64(12000),
+		"12K":     uint64(12000),
+		"12KB":    uint64(12000),
+		"12 K":    uint64(12000),
+		"12 KB":   uint64(12000),
+		"12 Kb":   uint64(12000),
+		"12 kB":   uint64(12000),
+		"12.2 KB": uint64(12200),
+	}
+
+	for k, v := range cases {
+		result, err := ParseDecimalBytes(k)
+		assert.Equal(v, result)
+		assert.IsNil(err)
+	}
+
+	_, err := ParseDecimalBytes("12 AB")
+	assert.IsNotNil(err)
+}
+
+func TestParseBinaryBytes(t *testing.T) {
+	assert := internal.NewAssert(t, "TestParseBinaryBytes")
+
+	cases := map[string]uint64{
+		"12":       uint64(12),
+		"12 ki":    uint64(12288),
+		"12 kib":   uint64(12288),
+		"12kib":    uint64(12288),
+		"12ki":     uint64(12288),
+		"12KI":     uint64(12288),
+		"12KIB":    uint64(12288),
+		"12KiB":    uint64(12288),
+		"12 Ki":    uint64(12288),
+		"12 KiB":   uint64(12288),
+		"12 Kib":   uint64(12288),
+		"12 kiB":   uint64(12288),
+		"12.2 KiB": uint64(12492),
+	}
+
+	for k, v := range cases {
+		result, err := ParseBinaryBytes(k)
+		assert.Equal(v, result)
+		assert.IsNil(err)
+	}
+
+	_, err := ParseDecimalBytes("12 AB")
+	assert.IsNotNil(err)
+}

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
+}