chores: add nolint explanation (#29)

.github/workflows/fuzz.yaml

@@ -0,0 +1,26 @@
+name: Fuzz
+
+on:
+  pull_request:
+    paths:
+      - "**.go"
+      - go.mod
+      - go.sum
+      - ".github/workflows/fuzz.yaml"
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run fuzz tests
+        run: make fuzz-all 20

.github/workflows/ci.yaml → .github/workflows/test.yaml

@@ -1,12 +1,12 @@
-name: CI
+name: Lint and Test
 
 on:
   pull_request:
     paths:
       - "**.go"
       - go.mod
       - go.sum
-      - ".github/workflows/ci.yaml"
+      - ".github/workflows/test.yaml"
       - ".golangci.yaml"
 
 jobs:
@@ -54,19 +54,3 @@ jobs:
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-
-  fuzz:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code into the Go module directory
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: go.mod
-
-      - name: Run fuzz tests
-        run: make fuzz-all 20

.golangci.yaml

@@ -1,6 +1,15 @@
 run:
   timeout: 5m
 
+linters-settings:
+  nolintlint:
+    # Enable to require an explanation of nonzero length after each nolint directive.
+    # Default: false
+    require-explanation: true
+    # Enable to require nolint directives to mention the specific linter being suppressed.
+    # Default: false
+    require-specific: true
+
 linters:
   enable:
     - nolintlint

README.md

@@ -56,13 +56,13 @@ func main() {
 	fmt.Println(a.Div(d)) // 123.456 / 4123547.1234567890123456789 = 0.0000299392722585176
 
 	// Rounding
-	fmt.Println(c.RoundBank(3)) // banker's rounding: 1.2345 -> 1.234
+	fmt.Println(c.RoundBank(3))         // banker's rounding: 1.2345 -> 1.234
 	fmt.Println(c.RoundAwayFromZero(2)) // round away from zero: 1.2345 -> 1.24
-	fmt.Println(c.RoundHAZ(3))  // half away from zero: 1.2345 -> 1.235
-	fmt.Println(c.RoundHTZ(3))  // half towards zero: 1.2345 -> 1.234
-	fmt.Println(c.Trunc(2))     // truncate: 1.2345 -> 1.23
-	fmt.Println(c.Floor())      // floor: 1.2345 -> 1
-	fmt.Println(c.Ceil())       // ceil: 1.2345 -> 2
+	fmt.Println(c.RoundHAZ(3))          // half away from zero: 1.2345 -> 1.235
+	fmt.Println(c.RoundHTZ(3))          // half towards zero: 1.2345 -> 1.234
+	fmt.Println(c.Trunc(2))             // truncate: 1.2345 -> 1.23
+	fmt.Println(c.Floor())              // floor: 1.2345 -> 1
+	fmt.Println(c.Ceil())               // ceil: 1.2345 -> 2
 
 	// Display
 	fmt.Println(a.String())         // 123.456
@@ -108,10 +108,10 @@ func main() {
 	a, _ := udecimal.NewFromFloat64(1.345) // a = 1.345
 
 	// Rounding
-	fmt.Println(a.RoundBank(2)) // banker's rounding: 1.345 -> 1.34
+	fmt.Println(a.RoundBank(2))         // banker's rounding: 1.345 -> 1.34
 	fmt.Println(a.RoundAwayFromZero(2)) // round away from zero: 1.345 -> 1.35
-	fmt.Println(a.RoundHAZ(2))  // half away from zero: 1.45 -> 1.35
-	fmt.Println(a.RoundHTZ(2))  // half towards zero: 1.45 -> 1.34
+	fmt.Println(a.RoundHAZ(2))          // half away from zero: 1.45 -> 1.35
+	fmt.Println(a.RoundHTZ(2))          // half towards zero: 1.45 -> 1.34
 }
 ```
 

benchmarks/README.md

@@ -4,31 +4,6 @@ This section provides benchmarks for the `udecimal` library in comparision with
 
 For full benchmark details, checkout [benchmark-udec.txt](./bench-ss.txt) and [benchstat.txt](./benchstat.txt)
 
-## How to run benchmarks
-
-### 1. Clone the repository and go to the benchmarks directory
-
-```bash
-git clone https://github.com/quagmt/udecimal.git
-cd udecimal/benchmarks
-```
-
-### 2. Run benchmarks
-
-Run full benchmarks with benchstat comparison (it will take some time)
-
-```bash
-make bench-ss
-make bench-udec
-make stats
-```
-
-Or run benchmarks for `udecimal` only
-
-```bash
-make bench-udec
-```
-
 ## Benchmark Results
 
 <i>**NOTE**: The results are for references and can be varied depending on the hardware</i>
@@ -63,15 +38,15 @@ BenchmarkPow/1.01.Pow(10)-32
 BenchmarkPow/1.01.Pow(100)-32                                                            	   994129	  1137 ns/op	 817 B/op	13 allocs/op
 
 # Parsing string
-BenchmarkParse/1234567890123456789.1234567890123456879-32                                    32111433    38.21 ns/op       0 B/op    0 allocs/op
-BenchmarkParse/1234567890-32                                                                 98585916    12.58 ns/op       0 B/op    0 allocs/op
-BenchmarkParse/0.1234567890123456879-32                                                      44339668    26.45 ns/op       0 B/op    0 allocs/op
-BenchmarkParseFallBack/123456789123456789123456.1234567890123456-32                        	  2805122 	 473.3 ns/op	 192 B/op	 6 allocs/op
-BenchmarkParseFallBack/111222333444555666777888999.1234567890123456789-32                  	  2442004 	 500.8 ns/op	 216 B/op	 6 allocs/op
+BenchmarkParse/1234567890123456789.1234567890123456879-32                                  	 32111433	 38.21 ns/op	   0 B/op	 0 allocs/op
+BenchmarkParse/1234567890-32                                                               	 98585916	 12.58 ns/op	   0 B/op	 0 allocs/op
+BenchmarkParse/0.1234567890123456879-32                                                    	 44339668	 26.45 ns/op	   0 B/op	 0 allocs/op
+BenchmarkParseFallBack/123456789123456789123456.1234567890123456-32                        	  2805122	 473.3 ns/op	 192 B/op	 6 allocs/op
+BenchmarkParseFallBack/111222333444555666777888999.1234567890123456789-32                  	  2442004	 500.8 ns/op	 216 B/op	 6 allocs/op
 BenchmarkString/1234567890123456789.1234567890123456879-32                                 	 14577884	 76.50 ns/op	  48 B/op	 1 allocs/op
 BenchmarkString/0.1234567890123456879-32                                                   	 41109242	 40.02 ns/op	  24 B/op	 1 allocs/op
-BenchmarkStringFallBack/123456789123456789123456.1234567890123456-32                       	  4147044 	 256.2 ns/op	 208 B/op	 4 allocs/op
-BenchmarkStringFallBack/111222333444555666777888999.1234567890123456789-32                 	  3808071 	 313.3 ns/op	 208 B/op	 4 allocs/op
+BenchmarkStringFallBack/123456789123456789123456.1234567890123456-32                       	  4147044	 256.2 ns/op	 208 B/op	 4 allocs/op
+BenchmarkStringFallBack/111222333444555666777888999.1234567890123456789-32                 	  3808071	 313.3 ns/op	 208 B/op	 4 allocs/op
 
 # Marshal/Unmarshal
 BenchmarkMarshalJSON/1234567890123456789.1234567890123456879-32                            	 13965998	 77.22 ns/op	  48 B/op	 1 allocs/op

bint.go

@@ -178,7 +178,7 @@ func parseBint(s []byte) (bool, bint, uint8, error) {
 		return false, bint{}, 0, errInvalidFormat(s)
 	}
 
-	//nolint:gosec
+	//nolint:gosec // prec <= maxPrec (19) and can be safely converted to uint8
 	return neg, bintFromBigInt(dValue), uint8(prec), nil
 }
 
@@ -244,7 +244,7 @@ func parseSmallToU128(s []byte) (u128, uint8, error) {
 				return u128{}, 0, ErrInvalidFormat
 			}
 
-			//nolint:gosec
+			//nolint:gosec // len(s) <= maxDigitU64 and len(s)-i-1 >= 0, can be safely converted to uint8
 			prec = uint8(len(s) - i - 1)
 
 			// prevent "123." or "-123."
@@ -293,7 +293,7 @@ func parseLargeToU128(s []byte) (u128, uint8, error) {
 	}
 
 	// now 0 < pos < l-1
-	//nolint:gosec
+	//nolint:gosec // l < maxStrLen, so 0 < l-pos-1 < 256, can be safely converted to uint8
 	prec := uint8(l - pos - 1)
 	if prec > defaultPrec {
 		return u128{}, 0, ErrPrecOutOfRange

decimal.go

@@ -225,7 +225,7 @@ func NewFromInt64(coef int64, prec uint8) (Decimal, error) {
 		return Decimal{}, ErrPrecOutOfRange
 	}
 
-	//nolint:gosec
+	//nolint:gosec // coef is positive, so it's safe to convert to uint64
 	return newDecimal(neg, bintFromU64(uint64(coef)), prec), nil
 }
 
@@ -1354,7 +1354,7 @@ func (d Decimal) PowInt(e int) Decimal {
 		neg = false
 	}
 
-	//nolint:gosec
+	//nolint:gosec // powPrecision <= defaultPrec, so it's safe to convert to uint8
 	return newDecimal(neg, bintFromBigInt(qBig), uint8(powPrecision))
 }
 
@@ -1422,7 +1422,7 @@ func (d Decimal) PowInt32(e int32) (Decimal, error) {
 		neg = false
 	}
 
-	//nolint:gosec
+	//nolint:gosec // powPrecision <= defaultPrec, so it's safe to convert to uint8
 	return newDecimal(neg, bintFromBigInt(qBig), uint8(powPrecision)), nil
 }
 
@@ -1484,7 +1484,7 @@ func (d Decimal) tryPowIntU128(e int) (Decimal, error) {
 			return Decimal{}, errOverflow
 		}
 
-		//nolint:gosec
+		//nolint:gosec // exponent <= defaultPrec, so it's safe to convert to uint8
 		return newDecimal(neg, bintFromU128(u128{hi: result.hi, lo: result.lo}), uint8(exponent)), nil
 	}
 
@@ -1600,8 +1600,8 @@ func (d Decimal) sqrtU128() (Decimal, error) {
 		return Decimal{}, errOverflow
 	}
 
-	//nolint:gosec
-	bitLen := uint(coef.bitLen()) // bitLen < 256
+	//nolint:gosec // 0 <= coef.bitLen() < 256, so it's safe to convert to uint
+	bitLen := uint(coef.bitLen())
 
 	// initial guess = 2^((bitLen + 1) / 2) ≥ √coef
 	x := one128.Lsh((bitLen + 1) / 2)

u128.go

@@ -180,7 +180,7 @@ func (u u128) QuoRem(v u128) (q, r u128, err error) {
 		// generate a "trial quotient," guaranteed to be within 1 of the actual
 		// quotient, then adjust.
 
-		//nolint:gosec
+		//nolint:gosec // 0 <= bits.LeadingZeros64(v.hi) <= 63, so it's safe to convert to uint
 		n := uint(bits.LeadingZeros64(v.hi))
 		v1 := v.Lsh(n)
 		u1 := u.Rsh(1)

u256.go

@@ -167,7 +167,7 @@ func (u u256) div256by128(v u128) (u128, u128) {
 	// normalize v
 	n := bits.LeadingZeros64(v.hi)
 
-	//nolint:gosec
+	//nolint:gosec // 0 <= n <= 63, so it's safe to convert to uint
 	v = v.Lsh(uint(n))
 
 	// shift u to the left by n bits (n < 64)
@@ -235,7 +235,7 @@ func (u u256) div256by128(v u128) (u128, u128) {
 		a[i+1], a[i] = rem.hi, rem.lo
 	}
 
-	//nolint:gosec
+	//nolint:gosec // 0 <= n <= 63, so it's safe to convert to uint
 	r := u128{hi: a[1], lo: a[0]}.Rsh(uint(n))
 
 	return u128{hi: q[1], lo: q[0]}, r