diff --git a/README.md b/README.md
index 498ded9..b0793a2 100644
--- 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)
```
+Example (6alue In Range)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ n, ok := safecast.To[uint](1)
+ fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+1 true
+```
+
+
+
+
+Example (Float Overflow)
+
+
+```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
+```
+
+
+
+
+Example (Int No Overflow)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ b, ok := safecast.To[byte](255)
+ fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+255 true
+```
+
+
+
+
+Example (Int Overflow)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ b, ok := safecast.To[byte](256)
+ fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+0 false
+```
+
+
+
+
+Example (Value Out Of Range)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ n, ok := safecast.To[uint32](-1)
+ fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+4294967295 false
+```
+
+
+
Generated by [gomarkdoc]()
diff --git a/README_zh.md b/README_zh.md
index 9e044f0..8adce9a 100755
--- 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)`)的结果。
@@ -31,6 +39,137 @@ import "github.com/chen3feng/safecast"
func To[T numericType, F numericType](value F) (to T, ok bool)
```
+Example (6alue In Range)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ n, ok := safecast.To[uint](1)
+ fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+1 true
+```
+
+
+
+
+Example (Float Overflow)
+
+
+```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
+```
+
+
+
+
+Example (Int No Overflow)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ b, ok := safecast.To[byte](255)
+ fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+255 true
+```
+
+
+
+
+Example (Int Overflow)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ b, ok := safecast.To[byte](256)
+ fmt.Print(b, ok)
+}
+```
+
+#### Output
+
+```
+0 false
+```
+
+
+
+
+Example (Value Out Of Range)
+
+
+```go
+package main
+
+import (
+ "fmt"
+ "github.com/chen3feng/safecast"
+)
+
+func main() {
+ n, ok := safecast.To[uint32](-1)
+ fmt.Print(n, ok)
+}
+```
+
+#### Output
+
+```
+4294967295 false
+```
+
+
+
+
Generated by [gomarkdoc]()
diff --git a/cafecast_test.go b/cafecast_test.go
index ed8a4fc..3798d82 100644
--- 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
+}