Make 'proc sgn' and 'proc bigint.sgn' overloads unstable (chapel-lang…

…#24582)

This PR makes `proc sgn` and `proc bigint.sgn` unstable based upon
discussion in
https://chapel.discourse.group/t/what-is-the-value-of-sgn-nan-or-sgn-nan/31343
. The discussion there is focused on being able to get a floating-point
`NaN` result from `sgn(NaN)`, which is not possible with the current
return type of `int(8)` for the `real` overload.

This PR makes the integer and bigint overloads unstable in addition to
the `real` overload in order to leave room for reconsideration of the
entire family of functions. This might include changing the name or
making the return type always match the argument type.

Issue chapel-lang#24583 asks how these functions should be adjusted in order to
become stable.

- [x] full comm=none testing

Reviewed by @ShreyasKhandekar - thanks!

modules/standard/AutoMath.chpl

@@ -580,24 +580,28 @@ module AutoMath {
   /* Returns the signum function of the integer argument `x`:
      1 if positive, -1 if negative, 0 if zero.
   */
+  @unstable("sgn is unstable and may change its name and return type in the future")
   inline proc sgn(x : int(?w)): int(8) do
     return ((x > 0) : int(8) - (x < 0) : int(8)) : int(8);
 
   /* Returns the signum function of the unsigned integer argument `x`:
      1 if positive, -1 if negative, 0 if zero.
   */
+  @unstable("sgn is unstable and may change its name and return type in the future")
   inline proc sgn(x : uint(?w)): uint(8) do
     return (x > 0) : uint(8);
 
   /* Returns the signum function of the integer param argument `x`:
      1 if positive, -1 if negative, 0 if zero.
   */
+  @unstable("sgn is unstable and may change its name and return type in the future")
   proc sgn(param x : integral) param do
     return if x > 0 then 1 else if x == 0 then 0 else -1;
 
   /* Returns the signum function of the real argument `x`:
      1 if positive, -1 if negative, 0 if zero.
   */
+  @unstable("sgn is unstable and may change its name and return type in the future")
   inline proc sgn(x : real(?w)): int(8) do
     return ((x > 0.0) : int(8) - (x < 0.0) : int(8)) : int(8);
 

modules/standard/BigInteger.chpl

@@ -3686,6 +3686,7 @@ module BigInteger {
         :proc:`GMP.mpz_sgn` and
         `mpz_sgn <https://gmplib.org/manual/Integer-Comparisons#index-mpz_005fsgn>`_.
   */
+  @unstable("bigint.sgn is unstable and may change its name and return type in the future")
   proc bigint.sgn() : int {
     const this_ = this.localize();
     var ret : c_int;

test/unstable/BigInteger/unstable-sgn-bigint.chpl

@@ -0,0 +1,5 @@
+use BigInteger;
+
+// bigint
+var b = new bigint(1);
+assert(b.sgn() == 1);

test/unstable/BigInteger/unstable-sgn-bigint.good

@@ -0,0 +1 @@
+unstable-sgn-bigint.chpl:5: warning: bigint.sgn is unstable and may change its name and return type in the future

test/unstable/unstable-sgn.chpl

@@ -0,0 +1,48 @@
+// non-param numeric types
+var i8: int(8) = 1;
+var i16: int(16) = 1;
+var i32: int(32) = 1;
+var i64: int(64) = 1;
+assert(sgn(i8) == 1);
+assert(sgn(i16) == 1);
+assert(sgn(i32) == 1);
+assert(sgn(i64) == 1);
+
+var u8: uint(8) = 1;
+var u16: uint(16) = 1;
+var u32: uint(32) = 1;
+var u64: uint(64) = 1;
+assert(sgn(u8) == 1);
+assert(sgn(u16) == 1);
+assert(sgn(u32) == 1);
+assert(sgn(u64) == 1);
+
+var r32: real(32) = 1;
+var r64: real(64) = 1;
+assert(sgn(r32) == 1);
+assert(sgn(r64) == 1);
+
+
+// param numeric types
+param pi8: int(8) = 1;
+param pi16: int(16) = 1;
+param pi32: int(32) = 1;
+param pi64: int(64) = 1;
+assert(sgn(pi8) == 1);
+assert(sgn(pi16) == 1);
+assert(sgn(pi32) == 1);
+assert(sgn(pi64) == 1);
+
+param pu8: uint(8) = 1;
+param pu16: uint(16) = 1;
+param pu32: uint(32) = 1;
+param pu64: uint(64) = 1;
+assert(sgn(pu8) == 1);
+assert(sgn(pu16) == 1);
+assert(sgn(pu32) == 1);
+assert(sgn(pu64) == 1);
+
+param pr32: real(32) = 1;
+param pr64: real(64) = 1;
+assert(sgn(pr32) == 1);
+assert(sgn(pr64) == 1);

test/unstable/unstable-sgn.good

@@ -0,0 +1,20 @@
+unstable-sgn.chpl:6: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:7: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:8: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:9: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:15: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:16: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:17: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:18: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:22: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:23: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:31: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:32: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:33: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:34: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:40: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:41: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:42: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:43: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:47: warning: sgn is unstable and may change its name and return type in the future
+unstable-sgn.chpl:48: warning: sgn is unstable and may change its name and return type in the future