chore: add deprecation notice to all ToIntXX and ToUIntXX functions

Convert method should be used as a replacement for all ToIntXX and ToUIntXX functions.

These methods will be removed in the next major release.

Author: ccoVeille

README.md

@@ -25,41 +25,40 @@ import (
 )
 
 func main() {
-  var a int
+  var a int64
 
   a = 42
-  b, err := safecast.ToUint8(a) // everything is fine
+  b, err := safecast.Convert[int16](a) // everything is fine because 42 fits in int16
   if err != nil {
     fmt.Println(err)
   }
   fmt.Println(b)
-  // Output: 42
 
   a = 255 + 1
-  _, err = safecast.ToUint8(a) // 256 is greater than uint8 maximum value
+  _, err = safecast.Convert[uint8](a) // 256 is greater than uint8 maximum value
   if err != nil {
+    // Output: conversion issue: 256 (int64) is greater than 255 (uint8): maximum value for this type exceeded
     fmt.Println(err)
-    // Output: conversion issue: 256 (int) is greater than 255 (uint8): maximum value for this type exceeded
   }
 
   a = -1
-  _, err = safecast.ToUint8(a) // -1 cannot fit in uint8
+  _, err = safecast.Convert[uint64](a) // -1 cannot fit in uint64
   if err != nil {
+    // Output: conversion issue: -1 (int64) is less than 0 (uint64): minimum value for this type exceeded
     fmt.Println(err)
-    // Output: conversion issue: -1 (int) is less than 0 (uint8): minimum value for this type exceeded
   }
 
   str := "\x99" // ASCII code 153 for Trademark symbol
-  e := str[0]
-  _, err = safecast.ToInt8(e)
+  e := str[0] // e is a rune (uint8)
+  _, err = safecast.Convert[int8](e)
   if err != nil {
-    fmt.Println(err)
     // Output: conversion issue: 153 (uint8) is greater than 127 (int8): maximum value for this type exceeded
+    fmt.Println(err)
   }
 }
 ```
 
-[Go Playground](https://go.dev/play/p/nelJshulOnj)
+[Go Playground](https://go.dev/play/p/OC9ueLHY0D2)
 
 ## Conversion issues
 

conversion.go

@@ -216,86 +216,110 @@ func getRangeError[NumOut Number, NumIn Number](value NumIn) error {
 	}
 }
 
-// ToInt attempts to convert any [Type] value to an int.
+// ToInt attempts to convert any [Number] value to an int.
 // If the conversion results in a value outside the range of an int,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[int](i)
 func ToInt[T Number](i T) (int, error) {
 	return convertFromNumber[int](i)
 }
 
 // ToUint attempts to convert any [Number] value to an uint.
 // If the conversion results in a value outside the range of an uint,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[uint](i)
 func ToUint[T Number](i T) (uint, error) {
 	return convertFromNumber[uint](i)
 }
 
 // ToInt8 attempts to convert any [Number] value to an int8.
 // If the conversion results in a value outside the range of an int8,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[int8](i)
 func ToInt8[T Number](i T) (int8, error) {
 	return convertFromNumber[int8](i)
 }
 
 // ToUint8 attempts to convert any [Number] value to an uint8.
 // If the conversion results in a value outside the range of an uint8,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[uint8](i)
 func ToUint8[T Number](i T) (uint8, error) {
 	return convertFromNumber[uint8](i)
 }
 
 // ToInt16 attempts to convert any [Number] value to an int16.
 // If the conversion results in a value outside the range of an int16,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[int16](i)
 func ToInt16[T Number](i T) (int16, error) {
 	return convertFromNumber[int16](i)
 }
 
 // ToUint16 attempts to convert any [Number] value to an uint16.
 // If the conversion results in a value outside the range of an uint16,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[uint16](i)
 func ToUint16[T Number](i T) (uint16, error) {
 	return convertFromNumber[uint16](i)
 }
 
 // ToInt32 attempts to convert any [Number] value to an int32.
 // If the conversion results in a value outside the range of an int32,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[int32](i)
 func ToInt32[T Number](i T) (int32, error) {
 	return convertFromNumber[int32](i)
 }
 
 // ToUint32 attempts to convert any [Number] value to an uint32.
 // If the conversion results in a value outside the range of an uint32,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[uint32](i)
 func ToUint32[T Number](i T) (uint32, error) {
 	return convertFromNumber[uint32](i)
 }
 
 // ToInt64 attempts to convert any [Number] value to an int64.
 // If the conversion results in a value outside the range of an int64,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[int64](i)
 func ToInt64[T Number](i T) (int64, error) {
 	return convertFromNumber[int64](i)
 }
 
 // ToUint64 attempts to convert any [Number] value to an uint64.
 // If the conversion results in a value outside the range of an uint64,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[uint64](i)
 func ToUint64[T Number](i T) (uint64, error) {
 	return convertFromNumber[uint64](i)
 }
 
 // ToFloat32 attempts to convert any [Number] value to a float32.
 // If the conversion results in a value outside the range of a float32,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[float32](i)
 func ToFloat32[T Number](i T) (float32, error) {
 	return convertFromNumber[float32](i)
 }
 
 // ToFloat64 attempts to convert any [Number] value to a float64.
 // If the conversion results in a value outside the range of a float64,
 // an [ErrConversionIssue] error is returned.
+//
+// Deprecated: use [Convert] instead with Convert[float64](i)
 func ToFloat64[T Number](i T) (float64, error) {
 	return convertFromNumber[float64](i)
 }

examples_32bit_test.go

@@ -33,3 +33,19 @@ func ExampleToInt() {
 	// 42 <nil>
 	// 0 conversion issue: 3.4028235e+38 (float32) is greater than 2147483647 (int): maximum value for this type exceeded
 }
+
+func ExampleToInt_deprecation() {
+	// Example showing the use of the [safecast.Convert] function as a replacement for the deprecated [safecast.ToInt] function.
+
+	a := uint64(42)
+	i, err := safecast.Convert[int](a)
+	fmt.Println(i, err)
+
+	b := float32(math.MaxFloat32)
+	_, err = safecast.Convert[int](b)
+	fmt.Println(err)
+
+	// Output:
+	// 42 <nil>
+	// conversion issue: 3.4028235e+38 (float32) is greater than 2147483647 (int): maximum value for this type exceeded
+}

examples_64bit_test.go

@@ -32,3 +32,20 @@ func ExampleToInt() {
 	// 42 <nil>
 	// 0 conversion issue: 3.4028235e+38 (float32) is greater than 9223372036854775807 (int): maximum value for this type exceeded
 }
+
+func ExampleToInt_deprecation() {
+	// Example showing the use of the [safecast.Convert] function as a replacement for the deprecated [safecast.ToInt] function.
+
+	a := uint64(42)
+	i, err := safecast.Convert[int](a)
+	fmt.Println(i, err)
+
+	b := float32(math.MaxFloat32)
+	_, err = safecast.Convert[int](b)
+
+	fmt.Println(err)
+
+	// Output:
+	// 42 <nil>
+	// conversion issue: 3.4028235e+38 (float32) is greater than 9223372036854775807 (int): maximum value for this type exceeded
+}