Skip to content

Commit 3fd57e2

Browse files
committed
Add readme about new features and improve comments
1 parent e5a4341 commit 3fd57e2

File tree

3 files changed

+114
-98
lines changed

3 files changed

+114
-98
lines changed

README.md

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,19 @@
22
# overflow
33
Check for integer overflow in Golang arithmetic and type conversion.
44
### Install
5-
```
5+
```sh
66
go get github.com/johncgriffin/overflow
77
```
88
Note that because Go has no template types, the majority of repetitive code is
99
generated by overflow_template.sh. If you have to change an
1010
algorithm, change it there and regenerate the Go code via:
11-
```
11+
```sh
1212
go generate
1313
```
1414
### Synopsis
1515

1616
#### Arithmetic overflow detection
17-
```
17+
```go
1818
package main
1919

2020
import "fmt"
@@ -34,7 +34,7 @@ func main() {
3434
}
3535
```
3636
yields the output
37-
```
37+
```go
3838
9223372036854775802+0 -> (9223372036854775802,true)
3939
9223372036854775802+1 -> (9223372036854775803,true)
4040
9223372036854775802+2 -> (9223372036854775804,true)
@@ -51,7 +51,7 @@ For (u)int types, provide (U)Add, (U)Sub, (U)Mul, (U)Div, (U)Quotient, etc.
5151

5252

5353
#### Type conversion overflow detection
54-
```
54+
```go
5555
func main() {
5656
var i uint
5757
for i = math.MaxInt - 5; i <= math.MaxInt+5; i++ {
@@ -62,7 +62,7 @@ func main() {
6262
}
6363
```
6464
yields the output
65-
```
65+
```go
6666
9223372036854775802 -> (9223372036854775802,true)
6767
9223372036854775803 -> (9223372036854775803,true)
6868
9223372036854775804 -> (9223372036854775804,true)
@@ -83,6 +83,22 @@ There's a good case to be made that a panic is an unidiomatic but proper respons
8383
believe that there's no valid way to continue your program after math goes wayward, you can
8484
use the easier Addp, Mulp, Subp, and Divp versions which return the normal result or panic.
8585

86+
### Performance considerations
87+
88+
Compared with the integer type safety libraries of other languages (such as C++), this
89+
library uses some seemingly slow operations, such as division. But this does not mean that
90+
these methods will be slow, on the contrary, it will be faster than complex implementations
91+
in other languages. The reason is that Go does not allow forced inlining, and any complex
92+
functions will be abandoned for inlining, resulting in additional calling overhead. Short
93+
functions are lightning fast due to automatic inlining. For example, for unsigned 64-bit
94+
integer multiplication overflow detection, when inlining is disabled, division takes five
95+
times as long as long multiplication, but after automatic inlining is allowed, division
96+
takes 1/5 of long multiplication.
97+
98+
Note that using `//go:noinline` in your business function will not affect the inlining of
99+
the library function. Only disabling global inlining through `-gcflags="-l"` will affect the
100+
inlining of this library function.
101+
86102

87103
- - -
88104
MIT License

0 commit comments

Comments
 (0)