feat: add decimal loss support for Convert

TODO: add it to ParseOption later

Author: ccoVeille

asserters_test.go

@@ -106,4 +106,9 @@ func TestErrorMessage(t *testing.T) {
 	requireErrorIs(t, err, safecast.ErrConversionIssue)
 	requireErrorIs(t, err, safecast.ErrExceedMinimumValue)
 	requireErrorContains(t, err, "than -128 (int8)")
+
+	_, err = safecast.Convert[int8](3.14, safecast.WithDecimalLossReport())
+	requireErrorIs(t, err, safecast.ErrConversionIssue)
+	requireErrorIs(t, err, safecast.ErrDecimalLoss)
+	requireErrorContains(t, err, "decimal loss")
 }

conversion.go

@@ -55,7 +55,7 @@ func RequireConvert[NumOut Number, NumIn Number](t TestingT, orig NumIn) (conver
 // # General errors wrapped on conversion failure:
 //
 //   - [ErrConversionIssue] is always wrapped in the returned error when [Convert] fails (example "abc", -1, or 1000 to uint8).
-func Convert[NumOut Number, NumIn Number](orig NumIn) (NumOut, error) {
+func Convert[NumOut Number, NumIn Number](orig NumIn, opts ...ConvertOption) (NumOut, error) {
 	converted := NumOut(orig)
 	if isFloat64[NumIn]() {
 		floatOrig := float64(orig)
@@ -70,6 +70,8 @@ func Convert[NumOut Number, NumIn Number](orig NumIn) (NumOut, error) {
 		}
 	}
 
+	config := newConvertOptions(opts...)
+
 	if isFloat64[NumOut]() {
 		// float64 cannot overflow, so we don't have to worry about it
 		return converted, nil
@@ -103,6 +105,15 @@ func Convert[NumOut Number, NumIn Number](orig NumIn) (NumOut, error) {
 		return converted, getRangeError[NumOut](orig)
 	}
 
+	if config.reportDecimalLoss && isFloat[NumIn]() && !isFloat[NumOut]() {
+		if orig != cast {
+			return converted, errorHelper[NumOut]{
+				value: orig,
+				err:   ErrDecimalLoss,
+			}
+		}
+	}
+
 	return converted, nil
 }
 
@@ -117,3 +128,36 @@ func getRangeError[NumOut Number, NumIn Number](value NumIn) error {
 		err:   err,
 	}
 }
+
+type convertConfig struct {
+	reportDecimalLoss bool
+}
+
+// ConvertOption is a function type used to set options for the [Convert] function.
+type ConvertOption func(*convertConfig)
+
+func newConvertOptions(opts ...ConvertOption) *convertConfig {
+	po := &convertConfig{
+		reportDecimalLoss: false,
+	}
+
+	for _, opt := range opts {
+		opt(po)
+	}
+	return po
+}
+
+// WithDecimalLossReport is a [ConvertOption] that enables reporting of decimal loss
+// when converting from a floating-point type to an integer type.
+//
+// When this option is used, if the conversion results in loss of decimal information,
+// the returned error will wrap [ErrDecimalLoss].
+//
+// Example:
+//
+//	value, err := Convert[int](3.14, WithDecimalLossReport())
+func WithDecimalLossReport() ConvertOption {
+	return func(cfg *convertConfig) {
+		cfg.reportDecimalLoss = true
+	}
+}

conversion_test.go

@@ -18,6 +18,7 @@ import (
 
 type MapTest[TypeInput safecast.Number, TypeOutput safecast.Number] struct {
 	Input          TypeInput
+	Options        []safecast.ConvertOption
 	ExpectedOutput TypeOutput
 	ExpectedError  error
 	ErrorContains  string
@@ -36,7 +37,7 @@ func (mt MapTest[I, O]) Run(t *testing.T) {
 		}
 	}(t)
 
-	out, err := safecast.Convert[O](mt.Input)
+	out, err := safecast.Convert[O](mt.Input, mt.Options...)
 	if mt.ExpectedError != nil {
 		requireErrorIs(t, err, safecast.ErrConversionIssue)
 		requireErrorIs(t, err, mt.ExpectedError)
@@ -432,6 +433,46 @@ func TestConvert(t *testing.T) {
 			})
 		}
 	})
+
+	t.Run("float to int rounding", func(t *testing.T) {
+		t.Run("without decimal loss", func(t *testing.T) {
+			for name, tt := range map[string]TestRunner{
+				"float32": MapTest[float32, int]{
+					Input:          3.14,
+					ExpectedOutput: 3,
+				},
+				"float64": MapTest[float64, int]{
+					Input:          3.14,
+					ExpectedOutput: 3,
+				},
+			} {
+				t.Run(name, func(t *testing.T) {
+					tt.Run(t)
+				})
+			}
+		})
+
+		t.Run("with decimal loss", func(t *testing.T) {
+			for name, tt := range map[string]TestRunner{
+				"float32": MapTest[float32, int]{
+					Input:          3.14,
+					Options:        []safecast.ConvertOption{safecast.WithDecimalLossReport()},
+					ExpectedOutput: 3,
+					ExpectedError:  safecast.ErrDecimalLoss,
+				},
+				"float64": MapTest[float64, int]{
+					Input:          3.14,
+					Options:        []safecast.ConvertOption{safecast.WithDecimalLossReport()},
+					ExpectedOutput: 3,
+					ExpectedError:  safecast.ErrDecimalLoss,
+				},
+			} {
+				t.Run(name, func(t *testing.T) {
+					tt.Run(t)
+				})
+			}
+		})
+	})
 }
 
 type MapMustConvertTest[TypeInput safecast.Number, TypeOutput safecast.Number] struct {
@@ -602,3 +643,17 @@ func ExampleRequireConvert_failure() {
 	// --- FAIL:
 	// 	conversion issue: -1 (int) is less than 0 (uint8): minimum value for this type exceeded
 }
+
+func ExampleWithDecimalLossReport() {
+	// By default, converting from float to int does not report decimal loss
+	val1, err1 := safecast.Convert[int](3.14)
+	fmt.Println(val1, err1)
+
+	// Using the WithDecimalLossReport option, decimal loss is reported as an error
+	val2, err2 := safecast.Convert[int](3.14, safecast.WithDecimalLossReport())
+	fmt.Println(val2, err2)
+
+	// Output:
+	// 3 <nil>
+	// 3 conversion issue: decimal loss during conversion
+}

errors.go

@@ -48,6 +48,13 @@ var ErrUnsupportedConversion = errors.New("unsupported type")
 // [ErrConversionIssue] is also wrapped when this error is returned.
 var ErrStringConversion = errors.New("cannot convert from string")
 
+// ErrDecimalLoss is an error for when decimal loss occurs during conversion.
+//
+// Examples include converting 3.14 to int.
+//
+// [ErrConversionIssue] is also wrapped when this error is returned.
+var ErrDecimalLoss = errors.New("decimal loss during conversion")
+
 // errorHelper is a helper struct for error messages
 // It is used to wrap other errors, and provides additional information
 type errorHelper[NumOut Number] struct {