Only generic (#2)

chen3feng · Aug 14, 2022 · 4be512f · 4be512f
1 parent 6dffb17
commit 4be512f
Show file tree

Hide file tree

Showing 3 changed files with 316 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -10,7 +10,13 @@ English | [简体中文](README_zh.md)
 [![Coverage Status](https://coveralls.io/repos/github/chen3feng/safecast/badge.svg?branch=master)](https://coveralls.io/github/chen3feng/safecast?branch=master)
 [![GoReport](https://goreportcard.com/badge/github.com/securego/gosec)](https://goreportcard.com/report/github.com/chen3feng/safecast)
 
-Safe numeric type cast library.
+Safe numeric type cast library. suppoer all integral and floating types, except uintptr.
+
+```go
+val, ok := To[type](value)
+```
+
+`ok == false` indicates overflow occured. but whatever，`val` is always equals to the result of the type cast (`type(value)`) expression。
 
 This library depends on go generics, which is introduced in 1.18+.
 
@@ -35,6 +41,136 @@ import "github.com/chen3feng/safecast"
 func To[T numericType, F numericType](value F) (to T, ok bool)
 ```
 
+<details><summary>Example (6alue In Range)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	n, ok := safecast.To[uint](1)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+1 true
+```
+
+</p>
+</details>
+
+<details><summary>Example (Float Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+	"math"
+)
+
+func main() {
+	n, ok := safecast.To[float32](math.MaxFloat32 * 2)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
++Inf false
+```
+
+</p>
+</details>
+
+<details><summary>Example (Int No Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	b, ok := safecast.To[byte](255)
+	fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+255 true
+```
+
+</p>
+</details>
+
+<details><summary>Example (Int Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	b, ok := safecast.To[byte](256)
+	fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+0 false
+```
+
+</p>
+</details>
+
+<details><summary>Example (Value Out Of Range)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	n, ok := safecast.To[uint32](-1)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+4294967295 false
+```
+
+</p>
+</details>
 
 
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

diff --git a/README_zh.md b/README_zh.md
@@ -8,7 +8,15 @@
 [![Coverage Status](https://coveralls.io/repos/github/chen3feng/safecast/badge.svg?branch=master)](https://coveralls.io/github/chen3feng/safecast?branch=master)
 [![GoReport](https://goreportcard.com/badge/github.com/securego/gosec)](https://goreportcard.com/report/github.com/chen3feng/safecast)
 
-安全的数值类型转换库。
+安全的数值类型转换库。支持除了 `uintptr` 外的所有整数和浮点数类型。
+
+用法：
+
+```go
+val, ok := To[type](value)
+```
+
+`ok == false` 表示值溢出，无论成功失败，`val` 都等效于直接用类型转换（`type(value)`）的结果。
 
 <!-- gomarkdoc:embed:start -->
 
@@ -31,6 +39,137 @@ import "github.com/chen3feng/safecast"
 func To[T numericType, F numericType](value F) (to T, ok bool)
 ```
 
+<details><summary>Example (6alue In Range)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	n, ok := safecast.To[uint](1)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+1 true
+```
+
+</p>
+</details>
+
+<details><summary>Example (Float Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+	"math"
+)
+
+func main() {
+	n, ok := safecast.To[float32](math.MaxFloat32 * 2)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
++Inf false
+```
+
+</p>
+</details>
+
+<details><summary>Example (Int No Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	b, ok := safecast.To[byte](255)
+	fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+255 true
+```
+
+</p>
+</details>
+
+<details><summary>Example (Int Overflow)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	b, ok := safecast.To[byte](256)
+	fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+0 false
+```
+
+</p>
+</details>
+
+<details><summary>Example (Value Out Of Range)</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/chen3feng/safecast"
+)
+
+func main() {
+	n, ok := safecast.To[uint32](-1)
+	fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+4294967295 false
+```
+
+</p>
+</details>
+
 
 
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

diff --git a/cafecast_test.go b/cafecast_test.go
@@ -1,8 +1,11 @@
 package safecast_test
 
 import (
-	"github.com/chen3feng/safecast"
+	"fmt"
+	"math"
 	"testing"
+
+	"github.com/chen3feng/safecast"
 )
 
 func TestTo(t *testing.T) {
@@ -11,3 +14,38 @@ func TestTo(t *testing.T) {
 		t.Fail()
 	}
 }
+
+func ExampleTo_intNoOverflow() {
+	b, ok := safecast.To[byte](255)
+	fmt.Print(b, ok)
+	// Output:
+	// 255 true
+}
+
+func ExampleTo_intOverflow() {
+	b, ok := safecast.To[byte](256)
+	fmt.Print(b, ok)
+	// Output:
+	// 0 false
+}
+
+func ExampleTo_ValueInRange() {
+	n, ok := safecast.To[uint](1)
+	fmt.Print(n, ok)
+	// Output:
+	// 1 true
+}
+
+func ExampleTo_valueOutOfRange() {
+	n, ok := safecast.To[uint32](-1)
+	fmt.Print(n, ok)
+	// Output:
+	// 4294967295 false
+}
+
+func ExampleTo_floatOverflow() {
+	n, ok := safecast.To[float32](math.MaxFloat32 * 2)
+	fmt.Print(n, ok)
+	// Output:
+	// +Inf false
+}