feat: adds (Must)ConvertAny funcs (#2)

Signed-off-by: Dwi Siswanto <git@dw1.io>

Author: dwisiswant0

README.md

@@ -11,7 +11,7 @@ It provides overflow-safe arithmetic (`+`, `-`, `*`, `/`) and safe type conversi
 
 * **Comprehensive generics**: works with all standard integer types.
 * **Checked arithmetic**: [`Add`](https://pkg.go.dev/go.dw1.io/safemath#Add), [`Sub`](https://pkg.go.dev/go.dw1.io/safemath#Sub), [`Mul`](https://pkg.go.dev/go.dw1.io/safemath#Mul), [`Div`](https://pkg.go.dev/go.dw1.io/safemath#Div) functions return an error instead of allowing silent, dangerous wrapping.
-* **Safe conversions**: [`Convert[To, From](v)`](https://pkg.go.dev/go.dw1.io/safemath#Convert) makes sure no data is lost during type conversion (e.g., checking bounds when casting larger types to smaller ones or signed to unsigned).
+* **Safe conversions**: [`Convert[To, From](v)`](https://pkg.go.dev/go.dw1.io/safemath#Convert) makes sure no data is lost during type conversion (e.g., checking bounds when casting larger types to smaller ones or signed to unsigned). [`ConvertAny`](https://pkg.go.dev/go.dw1.io/safemath#ConvertAny) extends the checks to `any` values, rejecting non-integer inputs.
 * **Panic APIs**: [`Must*`](https://pkg.go.dev/go.dw1.io/safemath#MustAdd) variants are available for situations where panicking on failure is preferred.
 * **Adversarial safety**: robustly handles dangerous edge cases like $$MinInt / -1$$ and avoids hardware exceptions.
 
@@ -56,6 +56,20 @@ func main() {
 }
 ```
 
+### Converting from interface{}
+
+```go
+val := any(int64(42))
+out, err := safemath.ConvertAny[uint16](val)
+if err != nil {
+    fmt.Println(err)
+}
+fmt.Println(out)
+
+// Will panic (ErrInvalidType) because input is not an integer
+// _ = safemath.MustConvertAny[uint16]("nope")
+```
+
 ### Safe Conversion
 
 ```go

doc.go

@@ -10,5 +10,7 @@
 //
 // For type conversions, [Convert] ensures that the value can be represented
 // in the target type without data loss, handling both signed-to-unsigned and
-// size-based truncation checks.
+// size-based truncation checks. When the source value is only available as
+// an interface, [ConvertAny] (and [MustConvertAny]) perform the same checks
+// while also rejecting non-integer inputs.
 package safemath

errors.go

@@ -5,5 +5,6 @@ import "errors"
 var (
 	ErrOverflow       = errors.New("integer overflow/underflow")
 	ErrTruncation     = errors.New("integer type truncation")
+	ErrInvalidType    = errors.New("invalid integer type")
 	ErrDivisionByZero = errors.New("division by zero")
 )

safemath.go

@@ -123,6 +123,38 @@ func Convert[To, From Integer](v From) (To, error) {
 	return to, nil
 }
 
+// ConvertAny attempts to convert v (any integer type) into To.
+//
+// Returns ErrInvalidType when v is not an integer or cannot fit in To.
+func ConvertAny[To Integer](v any) (To, error) {
+	switch x := v.(type) {
+	case int:
+		return Convert[To](x)
+	case int8:
+		return Convert[To](x)
+	case int16:
+		return Convert[To](x)
+	case int32:
+		return Convert[To](x)
+	case int64:
+		return Convert[To](x)
+	case uint:
+		return Convert[To](x)
+	case uint8:
+		return Convert[To](x)
+	case uint16:
+		return Convert[To](x)
+	case uint32:
+		return Convert[To](x)
+	case uint64:
+		return Convert[To](x)
+	case uintptr:
+		return Convert[To](x)
+	default:
+		return 0, ErrInvalidType
+	}
+}
+
 // MustAdd returns the sum of a and b on success. Panics on error.
 func MustAdd[T Integer](a, b T) T {
 	c, err := Add(a, b)
@@ -172,3 +204,13 @@ func MustConvert[To, From Integer](v From) To {
 
 	return c
 }
+
+// MustConvertAny converts v (any integer type) into To or panics on error.
+func MustConvertAny[To Integer](v any) To {
+	c, err := ConvertAny[To](v)
+	if err != nil {
+		panic(err)
+	}
+
+	return c
+}

safemath_bench_test.go

@@ -163,3 +163,19 @@ func BenchmarkMustConvert(b *testing.B) {
 	}
 	_ = res
 }
+
+func BenchmarkConvertAny(b *testing.B) {
+	var res uint8
+	for i := 0; i < b.N; i++ {
+		res, _ = safemath.ConvertAny[uint8](int64(i % 127))
+	}
+	_ = res
+}
+
+func BenchmarkMustConvertAny(b *testing.B) {
+	var res uint8
+	for i := 0; i < b.N; i++ {
+		res = safemath.MustConvertAny[uint8](int64(i % 127))
+	}
+	_ = res
+}

safemath_example_test.go

@@ -104,6 +104,25 @@ func ExampleConvert() {
 	// integer type truncation
 }
 
+func ExampleConvertAny() {
+	// Convert from interface{} holding an int64
+	var v any = int64(42)
+	res, err := safemath.ConvertAny[uint8](v)
+	if err != nil {
+		fmt.Println(err)
+	}
+	fmt.Println(res)
+
+	// Non-integer input is rejected
+	_, err = safemath.ConvertAny[int]("nope")
+	if err != nil {
+		fmt.Println(err)
+	}
+	// Output:
+	// 42
+	// invalid integer type
+}
+
 func ExampleMustAdd() {
 	// MustAdd succeeds
 	fmt.Println(safemath.MustAdd(100, 200))
@@ -139,6 +158,24 @@ func ExampleMustConvert() {
 	// Recovered from: integer type truncation
 }
 
+func ExampleMustConvertAny() {
+	// MustConvertAny succeeds when the interface holds an integer
+	var v any = uint32(255)
+	fmt.Println(safemath.MustConvertAny[uint8](v))
+
+	// MustConvertAny panics on invalid type
+	defer func() {
+		if r := recover(); r != nil {
+			fmt.Println("Recovered from:", r)
+		}
+	}()
+	safemath.MustConvertAny[int]("bad")
+
+	// Output:
+	// 255
+	// Recovered from: invalid integer type
+}
+
 func ExampleMustSub() {
 	// MustSub succeeds
 	fmt.Println(safemath.MustSub(100, 40))

safemath_fuzz_test.go

@@ -112,3 +112,25 @@ func FuzzConvertUnsignedToUnsignedSmall(f *testing.F) {
 		checkConsistency(t, res, err, func() uint8 { return safemath.MustConvert[uint8](a) })
 	})
 }
+
+// FuzzConvertAny covers the interface-based conversion path.
+func FuzzConvertAnyInt64ToUint8(f *testing.F) {
+	f.Add(int64(100))
+	f.Add(int64(-1))
+	f.Add(int64(300))
+
+	f.Fuzz(func(t *testing.T, a int64) {
+		res, err := safemath.ConvertAny[uint8](a)
+		checkConsistency(t, res, err, func() uint8 { return safemath.MustConvertAny[uint8](a) })
+	})
+}
+
+func FuzzConvertAnyUint64ToInt64(f *testing.F) {
+	f.Add(uint64(1))
+	f.Add(uint64(1) << 63)
+
+	f.Fuzz(func(t *testing.T, a uint64) {
+		res, err := safemath.ConvertAny[int64](a)
+		checkConsistency(t, res, err, func() int64 { return safemath.MustConvertAny[int64](a) })
+	})
+}

safemath_test.go

@@ -464,3 +464,56 @@ func TestMust(t *testing.T) {
 		safemath.MustConvert[int8](128)
 	})
 }
+
+func TestConvertAny(t *testing.T) {
+	tests := []struct {
+		name string
+		val  any
+		want uint8
+		err  error
+	}{
+		{name: "int to uint8", val: int(10), want: uint8(10), err: nil},
+		{name: "uint8 to uint8", val: uint8(5), want: uint8(5), err: nil},
+		{name: "overflow", val: uint16(256), want: 0, err: safemath.ErrTruncation},
+		{name: "non-integer", val: 1.5, want: 0, err: safemath.ErrInvalidType},
+		{name: "nil", val: nil, want: 0, err: safemath.ErrInvalidType},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := safemath.ConvertAny[uint8](tt.val)
+			if err != tt.err {
+				t.Fatalf("error = %v, want %v", err, tt.err)
+			}
+			if tt.err == nil && got != tt.want {
+				t.Fatalf("got %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMustConvertAny(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		if got := safemath.MustConvertAny[uint8](int(7)); got != 7 {
+			t.Fatalf("MustConvertAny returned %v, want 7", got)
+		}
+	})
+
+	t.Run("panic on truncation", func(t *testing.T) {
+		defer func() {
+			if r := recover(); r == nil {
+				t.Fatal("MustConvertAny did not panic")
+			}
+		}()
+		safemath.MustConvertAny[uint8](uint16(256))
+	})
+
+	t.Run("panic on non-integer", func(t *testing.T) {
+		defer func() {
+			if r := recover(); r == nil {
+				t.Fatal("MustConvertAny did not panic for non-integer")
+			}
+		}()
+		safemath.MustConvertAny[uint8](1.5)
+	})
+}