Deprecate saturating_arith and saturation_arith (#266)

* Depracate saturating_arith and saturation_arith.

* Update stew/saturating_arith.nim

Co-authored-by: Jacek Sieka <jacek@status.im>

* saturation_arith: Add intops link in the deprecation notice.

---------

Co-authored-by: Jacek Sieka <jacek@status.im>

Author: moigagoo

stew/saturating_arith.nim

@@ -1,7 +1,19 @@
 ## This module may hold various saturating arithmetic definitions.
 ## It will be expanded on demand as more definitions are requred.
 
+{.deprecated: "Use https://github.com/vacp2p/nim-intops instead".}
+
 func saturate*(T: type int64, u: uint64): T =
+  ##[ Convert a uint64 to int64. If the value won't fit in int64,
+  return maximal value.
+
+  Notice: This function is deprecated.
+
+  If you need to limit the value of an integer, use `clamp(a, minVal, maxVal)` from stdlib.
+
+  If you use this function to implement saturating addition, use `saturatingAdd` from [intops](https://github.com/vacp2p/nim-intops/) library.
+  ]##
+
   if u > high(int64).uint64:
     high(int64)
   else:

stew/saturation_arith.nim

@@ -1,7 +1,19 @@
 ## This module may hold various saturating arithmetic definitions.
 ## It will be expanded on demand as Status project require its definition
 
+{.deprecated: "Use https://github.com/vacp2p/nim-intops instead".}
+
 func saturate*(T: type int64, u: uint64): T =
+  ##[ Convert a uint64 to int64. If the value won't fit in int64,
+  return maximal value.
+
+  Notice: This function is deprecated.
+
+  If you need to limit the value of an integer, use `clamp(a, minVal, maxVal)` from stdlib.
+
+  If you use this function to implement saturating addition, use `saturatingAdd` from [intops](https://github.com/vacp2p/nim-intops/) library.
+  ]##
+
   if u > high(int64).uint64:
     high(int64)
   else: