Merge branch 'Dev'

README.md

@@ -1,13 +1,24 @@
-[![Build Status](https://travis-ci.org/JohnCGriffin/overflow.png)](https://travis-ci.org/JohnCGriffin/overflow)
 # overflow
 Check for integer overflow in Golang arithmetic and type conversion.
+
+Other language README: [中文版](./README.zh_CN.md)
 ### Install
+
+*This is a special README before the PR is merged by the upstream.*
+
+This repository forks from `johncgriffin/overflow` and adds overflow detection for unsigned integer arithmetic and type conversions between integers.
+
+It has been well tested and benchmarked, and passed the code security scan provided by Github Workflow.
+
+[![CodeQL](https://github.com/rwxe/overflow/actions/workflows/codeql.yml/badge.svg)](https://github.com/rwxe/overflow/actions/workflows/codeql.yml)
+
 ```sh
-go get github.com/johncgriffin/overflow
+go get github.com/rwxe/overflow
 ```
-Note that because Go has no template types, the majority of repetitive code is 
-generated by overflow_template.sh.  If you have to change an
-algorithm, change it there and regenerate the Go code via:
+
+In order to be compatible with the old code and keep the code simple and readable, the new code still does not use generics, but uses templates to generate code. So the majority of repetitive code is generated by `overflow_template.sh`. 
+
+If you have to change an algorithm, change it there and regenerate the Go code via: 
 ```sh
 go generate
 ```
@@ -19,18 +30,15 @@ package main
 
 import "fmt"
 import "math"
-import "github.com/JohnCGriffin/overflow"
+import "github.com/rwxe/overflow"
 
 func main() {
-
 	addend := math.MaxInt64 - 5
-
 	for i := 0; i < 10; i++ {
 		sum, ok := overflow.Add(addend, i)
 		fmt.Printf("%v+%v -> (%v,%v)\n",
 			addend, i, sum, ok)
 	}
-
 }
 ```
 yields the output
@@ -46,7 +54,6 @@ yields the output
 9223372036854775802+8 -> (0,false)
 9223372036854775802+9 -> (0,false)
 ```
-
 For (u)int types, provide (U)Add, (U)Sub, (U)Mul, (U)Div, (U)Quotient, etc.
 
 
@@ -79,30 +86,17 @@ Provide UintToInt, IntToUint, Uint64ToInt32, Int32ToUint64, etc.
 
 ### Stay calm and panic
 
-There's a good case to be made that a panic is an unidiomatic but proper response.  Iff you
-believe that there's no valid way to continue your program after math goes wayward, you can
-use the easier Addp, Mulp, Subp, and Divp versions which return the normal result or panic.
+There's a good case to be made that a panic is an unidiomatic but proper response.  Iff you believe that there's no valid way to continue your program after math goes wayward, you can use the easier Addp, Mulp, Subp, Divp, IntToUintp, UintToIntp versions which return the normal result or panic.
 
 ### Performance considerations
 
-Compared with the integer type safety libraries of other languages (such as C++), this
-library uses some seemingly slow operations, such as division. But this does not mean that
-these methods will be slow, on the contrary, it will be faster than complex implementations
-in other languages. The reason is that Go does not allow forced inlining, and any complex
-functions will be abandoned for inlining, resulting in additional calling overhead. Short
-functions are lightning fast due to automatic inlining. For example, for unsigned 64-bit
-integer multiplication overflow detection, when inlining is disabled, division takes five
-times as long as long multiplication, but after automatic inlining is allowed, division
-takes 1/5 of long multiplication.
+Compared with the integer type safety libraries of other languages (such as C++), this library uses some seemingly slow operations, such as division. But this does not mean that these methods will be slow, on the contrary, it will be faster than complex implementations in other languages. The reason is that Go does not allow forced inlining, and any complex functions will be abandoned for inlining, resulting in additional calling overhead. Short functions are lightning fast due to automatic inlining. For example, for unsigned 64-bit integer multiplication overflow detection, when inlining is disabled, division takes five times as long as long multiplication, but after automatic inlining is allowed, division takes 1/5 of long multiplication.
 
-Note that using `//go:noinline` in your business function will not affect the inlining of
-the library function. Only disabling global inlining through `-gcflags="-l"` will affect the
-inlining of this library function.
+Note that using `//go:noinline` in your business function will not affect the inlining of the library function. Only disabling global inlining through `-gcflags="-l"` will affect the inlining of this library function.
 
 ### Basis and dependencies
 
-This library is based on Go's official compiler implementation and language specification,
-which defines the behavior when integer overflow occurs.
+This library is based on Go's official compiler implementation and language specification, which defines the behavior when integer overflow occurs.
 
 ### License
 

README.zh_CN.md

@@ -0,0 +1,102 @@
+# overflow 溢出
+检查 Golang 算术和类型转换中的整数溢出。
+### 安装
+
+*这是一份PR被上游合并之前的特殊README。*
+
+该库从`johncgriffin/overflow`派生而来并添加了无符号整数的算术和整数之间的溢出检测。
+
+它经过了良好的测试和基准测试，并通过了由GitHub提供的Workflow代码安全扫描。
+
+[![CodeQL](https://github.com/rwxe/overflow/actions/workflows/codeql.yml/badge.svg)](https://github.com/rwxe/overflow/actions/workflows/codeql.yml)
+
+```sh
+go get github.com/rwxe/overflow
+```
+
+为了兼容旧代码并保持代码简单易读，新的代码仍然不使用泛型，而是使用模板来生成代码。 所以大多数重复代码由`overflow_template.sh`生成。
+
+如果您必须更改算法，请在那里更改并通过以下方式重新生成 Go 代码：
+```sh
+go generate
+```
+### 概要
+
+#### 算术溢出检测
+```go
+package main
+
+import "fmt"
+import "math"
+import "github.com/rwxe/overflow"
+
+func main() {
+	addend := math.MaxInt64 - 5
+	for i := 0; i < 10; i++ {
+		sum, ok := overflow.Add(addend, i)
+		fmt.Printf("%v+%v -> (%v,%v)\n",
+			addend, i, sum, ok)
+	}
+}
+```
+输出
+```go
+9223372036854775802+0 -> (9223372036854775802,true)
+9223372036854775802+1 -> (9223372036854775803,true)
+9223372036854775802+2 -> (9223372036854775804,true)
+9223372036854775802+3 -> (9223372036854775805,true)
+9223372036854775802+4 -> (9223372036854775806,true)
+9223372036854775802+5 -> (9223372036854775807,true)
+9223372036854775802+6 -> (0,false)
+9223372036854775802+7 -> (0,false)
+9223372036854775802+8 -> (0,false)
+9223372036854775802+9 -> (0,false)
+```
+对于 (u)int 类型，提供 (U)Add、(U)Sub、(U)Mul、(U)Div、(U)Quotient 等操作。
+
+
+#### 类型转换溢出检测
+```go
+func main() {
+	var i uint
+	for i = math.MaxInt - 5; i <= math.MaxInt+5; i++ {
+		ret, ok := overflow.UintToInt(i)
+		fmt.Printf("%v -> (%v,%v)\n",
+			i, ret, ok)
+	}
+}
+```
+输出
+```go
+9223372036854775802 -> (9223372036854775802,true)
+9223372036854775803 -> (9223372036854775803,true)
+9223372036854775804 -> (9223372036854775804,true)
+9223372036854775805 -> (9223372036854775805,true)
+9223372036854775806 -> (9223372036854775806,true)
+9223372036854775807 -> (9223372036854775807,true)
+9223372036854775808 -> (-9223372036854775808,false)
+9223372036854775809 -> (-9223372036854775807,false)
+9223372036854775810 -> (-9223372036854775806,false)
+9223372036854775811 -> (-9223372036854775805,false)
+9223372036854775812 -> (-9223372036854775804,false)
+```
+提供UintToInt、IntToUint、Uint64ToInt32、Int32ToUint64等操作。
+
+### 保持冷静并恐慌
+
+有充分的证据表明，恐慌是一种不惯用但正确的反应。 如果你相信在算术和转换出现问题后，没有有效的方法可以继续你的程序，你可以使用更简单的 Addp、Mulp、Subp 、Divp、UintToIntp、IntToUintp 版本，它们返回正常结果或恐慌。
+
+### 性能考虑
+
+与其他语言（例如C++）的整数类型安全库相比，该库使用了一些看似缓慢的操作，例如除法。 但这并不意味着这些方法会很慢，相反，它会比其他语言中的复杂实现更快。 原因是Go不允许强制内联，任何复杂的函数都会被抛弃内联，导致额外的调用开销。 而短函数由于自动内联将快如闪电。 例如，对于无符号64位整数乘法溢出检测，当禁用内联时，除法所需的时间是长乘法的5倍，但允许自动内联后，除法所需的时间是长乘法的1/5。
+
+请注意，在业务函数中使用 `//go:noinline` 不会影响本库函数的内联。 只有通过 `-gcflags="-l"` 禁用全局内联才会影响该本库函数的内联。
+
+### 基于和依赖
+
+该库基于Go的官方编译器实现和语言规范，其定义了整数溢出发生时的行为。
+
+### 许可
+
+[MIT LICENSE](./LICENSE.md)
+