✨ [safecast] Adds safe numeric cast helpers, including generic value and reference casting, with clamping (#824)

helpers to perform casting in a safe way

Author: acabarbaye

changes/20260317181439.feature

@@ -0,0 +1 @@
+:sparkles: `[safecast]` Adds safe numeric cast helpers, including generic value and reference casting, with clamping

utils/collection/range.go

@@ -7,14 +7,14 @@ import (
 	"github.com/ARM-software/golang-utils/utils/safecast"
 )
 
-func sign[T safecast.IConvertable](x T) int64 {
+func sign[T safecast.IConvertible](x T) int64 {
 	if x < 0 {
 		return -1
 	}
 	return 1
 }
 
-func determineRangeLength[T safecast.IConvertable](start, stop, step T) (length int) {
+func determineRangeLength[T safecast.IConvertible](start, stop, step T) (length int) {
 	if (step > 0 && start < stop) || (step < 0 && start > stop) {
 		length = safecast.ToInt((safecast.ToInt64(stop-start+step) - sign(step)) / safecast.ToInt64(step))
 	}
@@ -25,7 +25,7 @@ func determineRangeLength[T safecast.IConvertable](start, stop, step T) (length
 // https://docs.python.org/2/library/functions.html#range
 //
 //	Note: The stop value is always exclusive.
-func Range[T safecast.IConvertable](start, stop T, step *T) (result []T) {
+func Range[T safecast.IConvertible](start, stop T, step *T) (result []T) {
 	it, length := rangeSequence(start, stop, step)
 	result = make([]T, length)
 	i := 0
@@ -37,12 +37,12 @@ func Range[T safecast.IConvertable](start, stop T, step *T) (result []T) {
 }
 
 // RangeSequence returns an iterator over a range
-func RangeSequence[T safecast.IConvertable](start, stop T, step *T) iter.Seq[T] {
+func RangeSequence[T safecast.IConvertible](start, stop T, step *T) iter.Seq[T] {
 	it, _ := rangeSequence(start, stop, step)
 	return it
 }
 
-func rangeSequence[T safecast.IConvertable](start, stop T, step *T) (it iter.Seq[T], length int) {
+func rangeSequence[T safecast.IConvertible](start, stop T, step *T) (it iter.Seq[T], length int) {
 	s := field.Optional[T](step, 1)
 	if s == 0 {
 		it = func(yield func(T) bool) {}

utils/collection/range_test.go

@@ -12,7 +12,7 @@ import (
 	"github.com/ARM-software/golang-utils/utils/safecast"
 )
 
-func testRange[T safecast.IConvertable](t *testing.T, start, stop T, step *T, expected []T) {
+func testRange[T safecast.IConvertible](t *testing.T, start, stop T, step *T, expected []T) {
 	t.Helper()
 	assert.Equal(t, expected, Range[T](start, stop, step))
 	if reflection.IsEmpty(expected) {

utils/safecast/boundary.go

@@ -1,6 +1,6 @@
 package safecast
 
-func greaterThanUpperBoundary[C1 IConvertable, C2 IConvertable](value C1, upperBoundary C2) (greater bool) {
+func greaterThanUpperBoundary[C1 IConvertible, C2 IConvertible](value C1, upperBoundary C2) (greater bool) {
 	if value <= 0 {
 		return
 	}
@@ -18,7 +18,7 @@ func greaterThanUpperBoundary[C1 IConvertable, C2 IConvertable](value C1, upperB
 	return
 }
 
-func lessThanLowerBoundary[T IConvertable, T2 IConvertable](value T, boundary T2) (lower bool) {
+func lessThanLowerBoundary[T IConvertible, T2 IConvertible](value T, boundary T2) (lower bool) {
 	if value >= 0 {
 		return
 	}

utils/safecast/cast.go

@@ -1,11 +1,94 @@
 package safecast
 
-import "math"
+import (
+	"math"
 
-// ToInt attempts to convert any [IConvertable] value to an int.
-// If the conversion results in a value outside the range of an int,
-// the closest boundary value will be returned.
-func ToInt[C IConvertable](i C) int {
+	"github.com/ARM-software/golang-utils/utils/commonerrors"
+	"github.com/ARM-software/golang-utils/utils/ptr"
+)
+
+// CastFunc defines a function that converts a value of type F to type T,
+// where both types satisfy [IConvertible].
+type CastFunc[F, T IConvertible] func(F) T
+
+// Cast converts an [IConvertible] value to another [IConvertible] type
+// using the supplied conversion function.
+func Cast[F, T IConvertible](i F, f CastFunc[F, T]) T {
+	return f(i)
+}
+
+// RobustCast converts an [IConvertible] value to the target type T by
+// dispatching to the appropriate safe helper for T.
+//
+// Conversions to bounded integer and float32 types use the corresponding
+// helper, so out-of-range values are clamped to the nearest valid boundary.
+// If types are not supported, an error is returned.
+func RobustCast[F, T IConvertible](i F) (c T, err error) {
+	var zero T
+
+	switch any(zero).(type) {
+	case int:
+		c = any(Cast(i, ToInt[F])).(T)
+	case uint:
+		c = any(Cast(i, ToUint[F])).(T)
+	case int8:
+		c = any(Cast(i, ToInt8[F])).(T)
+	case uint8:
+		c = any(Cast(i, ToUint8[F])).(T)
+	case int16:
+		c = any(Cast(i, ToInt16[F])).(T)
+	case uint16:
+		c = any(Cast(i, ToUint16[F])).(T)
+	case int32:
+		c = any(Cast(i, ToInt32[F])).(T)
+	case uint32:
+		c = any(Cast(i, ToUint32[F])).(T)
+	case int64:
+		c = any(Cast(i, ToInt64[F])).(T)
+	case uint64:
+		c = any(Cast(i, ToUint64[F])).(T)
+	case float32:
+		c = any(Cast(i, ToFloat32[F])).(T)
+	case float64:
+		c = any(Cast(i, ToFloat64[F])).(T)
+	default:
+		err = commonerrors.New(commonerrors.ErrUnsupported, "target type for casting is not supported")
+	}
+	return
+}
+
+// CastRef converts a reference to an [IConvertible] value to a reference
+// to another [IConvertible] type using the supplied conversion function.
+// A nil input returns nil.
+func CastRef[F, T IConvertible](i *F, f CastFunc[F, T]) *T {
+	if i == nil {
+		return nil
+	}
+	return ptr.To(Cast[F, T](ptr.From(i), f))
+}
+
+// RobustCastRef converts a reference to an [IConvertible] value to a reference
+// to the target type T by dispatching to the appropriate safe helper for T.
+// A nil input returns nil.
+// If types are not supported, an error is returned.
+func RobustCastRef[F, T IConvertible](i *F) (c *T, err error) {
+	if i == nil {
+		c = nil
+		return
+	}
+
+	v, err := RobustCast[F, T](ptr.From(i))
+	if err != nil {
+		return
+	}
+	c = ptr.To(v)
+	return
+}
+
+// ToInt attempts to convert an [IConvertible] value to an int.
+// If the converted value falls outside the range of int,
+// the nearest boundary value is returned instead.
+func ToInt[C IConvertible](i C) int {
 	if lessThanLowerBoundary(i, math.MinInt) {
 		return math.MinInt
 	}
@@ -15,10 +98,16 @@ func ToInt[C IConvertable](i C) int {
 	return int(i)
 }
 
-// ToUint attempts to convert any [IConvertable] value to an uint.
-// If the conversion results in a value outside the range of an uint,
-// the closest boundary value will be returned.
-func ToUint[C IConvertable](i C) uint {
+// ToIntRef attempts to convert a reference to an [IConvertible] value
+// to a reference to an int. A nil input returns nil.
+func ToIntRef[C IConvertible](i *C) *int {
+	return CastRef(i, ToInt[C])
+}
+
+// ToUint attempts to convert an [IConvertible] value to a uint.
+// If the converted value falls outside the range of uint,
+// the nearest boundary value is returned instead.
+func ToUint[C IConvertible](i C) uint {
 	if lessThanLowerBoundary(i, uint(0)) {
 		return 0
 	}
@@ -28,10 +117,16 @@ func ToUint[C IConvertable](i C) uint {
 	return uint(i)
 }
 
-// ToInt8 attempts to convert any [IConvertable] value to an int8.
-// If the conversion results in a value outside the range of an int8,
-// the closest boundary value will be returned.
-func ToInt8[C IConvertable](i C) int8 {
+// ToUintRef attempts to convert a reference to an [IConvertible] value
+// to a reference to a uint. A nil input returns nil.
+func ToUintRef[C IConvertible](i *C) *uint {
+	return CastRef(i, ToUint[C])
+}
+
+// ToInt8 attempts to convert an [IConvertible] value to an int8.
+// If the converted value falls outside the range of int8,
+// the nearest boundary value is returned instead.
+func ToInt8[C IConvertible](i C) int8 {
 	if lessThanLowerBoundary(i, math.MinInt8) {
 		return math.MinInt8
 	}
@@ -41,10 +136,16 @@ func ToInt8[C IConvertable](i C) int8 {
 	return int8(i)
 }
 
-// ToUint8 attempts to convert any [IConvertable] value to an uint8.
-// If the conversion results in a value outside the range of an uint8,
-// the closest boundary value will be returned.
-func ToUint8[C IConvertable](i C) uint8 {
+// ToInt8Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to an int8. A nil input returns nil.
+func ToInt8Ref[C IConvertible](i *C) *int8 {
+	return CastRef(i, ToInt8[C])
+}
+
+// ToUint8 attempts to convert an [IConvertible] value to a uint8.
+// If the converted value falls outside the range of uint8,
+// the nearest boundary value is returned instead.
+func ToUint8[C IConvertible](i C) uint8 {
 	if lessThanLowerBoundary(i, 0) {
 		return 0
 	}
@@ -54,10 +155,16 @@ func ToUint8[C IConvertable](i C) uint8 {
 	return uint8(i)
 }
 
-// ToInt16 attempts to convert any [IConvertable] value to an int16.
-// If the conversion results in a value outside the range of an int16,
-// the closest boundary value will be returned.
-func ToInt16[C IConvertable](i C) int16 {
+// ToUint8Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a uint8. A nil input returns nil.
+func ToUint8Ref[C IConvertible](i *C) *uint8 {
+	return CastRef(i, ToUint8[C])
+}
+
+// ToInt16 attempts to convert an [IConvertible] value to an int16.
+// If the converted value falls outside the range of int16,
+// the nearest boundary value is returned instead.
+func ToInt16[C IConvertible](i C) int16 {
 	if lessThanLowerBoundary(i, math.MinInt16) {
 		return math.MinInt16
 	}
@@ -67,10 +174,16 @@ func ToInt16[C IConvertable](i C) int16 {
 	return int16(i)
 }
 
-// ToUint16 attempts to convert any [IConvertable] value to an uint16.
-// If the conversion results in a value outside the range of an uint16,
-// the closest boundary value will be returned.
-func ToUint16[C IConvertable](i C) uint16 {
+// ToInt16Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to an int16. A nil input returns nil.
+func ToInt16Ref[C IConvertible](i *C) *int16 {
+	return CastRef(i, ToInt16[C])
+}
+
+// ToUint16 attempts to convert an [IConvertible] value to a uint16.
+// If the converted value falls outside the range of uint16,
+// the nearest boundary value is returned instead.
+func ToUint16[C IConvertible](i C) uint16 {
 	if lessThanLowerBoundary(i, 0) {
 		return 0
 	}
@@ -80,10 +193,16 @@ func ToUint16[C IConvertable](i C) uint16 {
 	return uint16(i)
 }
 
-// ToInt32 attempts to convert any [IConvertable] value to an int32.
-// If the conversion results in a value outside the range of an int32,
-// the closest boundary value will be returned.
-func ToInt32[C IConvertable](i C) int32 {
+// ToUint16Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a uint16. A nil input returns nil.
+func ToUint16Ref[C IConvertible](i *C) *uint16 {
+	return CastRef(i, ToUint16[C])
+}
+
+// ToInt32 attempts to convert an [IConvertible] value to an int32.
+// If the converted value falls outside the range of int32,
+// the nearest boundary value is returned instead.
+func ToInt32[C IConvertible](i C) int32 {
 	if lessThanLowerBoundary(i, math.MinInt32) {
 		return math.MinInt32
 	}
@@ -93,10 +212,16 @@ func ToInt32[C IConvertable](i C) int32 {
 	return int32(i)
 }
 
-// ToUint32 attempts to convert any [IConvertable] value to an uint32.
-// If the conversion results in a value outside the range of an uint32,
-// the closest boundary value will be returned.
-func ToUint32[C IConvertable](i C) uint32 {
+// ToInt32Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to an int32. A nil input returns nil.
+func ToInt32Ref[C IConvertible](i *C) *int32 {
+	return CastRef(i, ToInt32[C])
+}
+
+// ToUint32 attempts to convert an [IConvertible] value to a uint32.
+// If the converted value falls outside the range of uint32,
+// the nearest boundary value is returned instead.
+func ToUint32[C IConvertible](i C) uint32 {
 	if lessThanLowerBoundary(i, 0) {
 		return 0
 	}
@@ -106,10 +231,16 @@ func ToUint32[C IConvertable](i C) uint32 {
 	return uint32(i)
 }
 
-// ToInt64 attempts to convert any [IConvertable] value to an int64.
-// If the conversion results in a value outside the range of an int64,
-// the closest boundary value will be returned.
-func ToInt64[C IConvertable](i C) int64 {
+// ToUint32Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a uint32. A nil input returns nil.
+func ToUint32Ref[C IConvertible](i *C) *uint32 {
+	return CastRef(i, ToUint32[C])
+}
+
+// ToInt64 attempts to convert an [IConvertible] value to an int64.
+// If the converted value falls outside the range of int64,
+// the nearest boundary value is returned instead.
+func ToInt64[C IConvertible](i C) int64 {
 	if lessThanLowerBoundary(i, math.MinInt64) {
 		return math.MinInt64
 	}
@@ -119,10 +250,16 @@ func ToInt64[C IConvertable](i C) int64 {
 	return int64(i)
 }
 
-// ToUint64 attempts to convert any [IConvertable] value to an uint64.
-// If the conversion results in a value outside the range of an uint64,
-// the closest boundary value will be returned.
-func ToUint64[C IConvertable](i C) uint64 {
+// ToInt64Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to an int64. A nil input returns nil.
+func ToInt64Ref[C IConvertible](i *C) *int64 {
+	return CastRef(i, ToInt64[C])
+}
+
+// ToUint64 attempts to convert an [IConvertible] value to a uint64.
+// If the converted value falls outside the range of uint64,
+// the nearest boundary value is returned instead.
+func ToUint64[C IConvertible](i C) uint64 {
 	if lessThanLowerBoundary(i, uint64(0)) {
 		return 0
 	}
@@ -132,7 +269,38 @@ func ToUint64[C IConvertable](i C) uint64 {
 	return uint64(i)
 }
 
-// ToFloat64 attempts to convert any [IConvertable] value to an float64.
-func ToFloat64[C IConvertable](i C) float64 {
+// ToUint64Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a uint64. A nil input returns nil.
+func ToUint64Ref[C IConvertible](i *C) *uint64 {
+	return CastRef(i, ToUint64[C])
+}
+
+// ToFloat64 attempts to convert an [IConvertible] value to a float64.
+func ToFloat64[C IConvertible](i C) float64 {
 	return float64(i)
 }
+
+// ToFloat64Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a float64. A nil input returns nil.
+func ToFloat64Ref[C IConvertible](i *C) *float64 {
+	return CastRef(i, ToFloat64[C])
+}
+
+// ToFloat32 attempts to convert an [IConvertible] value to a float32.
+// If the converted value falls outside the range of float32,
+// the nearest boundary value is returned instead.
+func ToFloat32[C IConvertible](i C) float32 {
+	if lessThanLowerBoundary(i, -math.MaxFloat32) || math.IsInf(float64(i), -1) {
+		return -math.MaxFloat32
+	}
+	if greaterThanUpperBoundary(i, math.MaxFloat32) || math.IsInf(float64(i), 1) {
+		return math.MaxFloat32
+	}
+	return float32(i)
+}
+
+// ToFloat32Ref attempts to convert a reference to an [IConvertible] value
+// to a reference to a float32. A nil input returns nil.
+func ToFloat32Ref[C IConvertible](i *C) *float32 {
+	return CastRef(i, ToFloat32[C])
+}