Clarify the return value ​​of the exponentiation methods in special cases

[sorairolake]

Location (URL)

For floating-point types (including f32 etc.):

• f64::powf
• f64::powi

For integer types (including u8 etc.):

• i32::checked_pow
• i32::overflowing_pow
• i32::pow
• i32::saturating_pow
• i32::strict_pow
• i32::wrapping_pow

Summary

The following is a table of the return value ​​of the exponentiation methods in special cases:

self	n/exp	Return value
x	±0	1 for any x
1	y	1 for any y
x	1	x for any x
NAN	y	NAN
x	NAN	NAN
±0	y	INFINITY or NEG_INFINITY for y an odd integer < 0
±0	NEG_INFINITY	INFINITY
±0	INFINITY	+0
±0	y	INFINITY for finite y < 0 and not an odd integer
±0	y	±0 for y an odd integer > 0
±0	y	+0 for finite y > 0 and not an odd integer
-1	INFINITY or NEG_INFINITY	1
x	INFINITY	INFINITY for |x| > 1
x	NEG_INFINITY	+0 for |x| > 1
x	INFINITY	+0 for |x| < 1
x	NEG_INFINITY	INFINITY for |x| < 1
INFINITY	y	INFINITY for y > 0
INFINITY	y	+0 for y < 0
NEG_INFINITY	y	(-0).pow(-y)
x	y	NAN for finite x < 0 and finite non-integer y

Some programming language documentation has descriptions similar to this:

• math.Pow in Go
• std.math.pow in Zig
• System.Math.Pow in .NET

I think this can be expressed as doc comments or doctests. This is primarily intended for floating-point types, but I think some of it can be used for integer types as well.

In particular, in most programming languages, zero to the power of zero ($0^0$) returns 1, but in some programming languages it is undefined or ​​it returns an error. So I think it's useful to be clear the return value ​​of the exponentiation methods in special cases.

[hkBst]

Looks like this documentation is indeed missing...

[sorairolake]

It might be better to write the above table as doctests with comments for description. This allows us to test whether these methods work as described in the comments. This is not exhaustive, but I think it's easier to understand with examples.

// ±0 to the power of -Inf always returns +Inf.
assert_eq!(f64::powf(0.0, f64::NEG_INFINITY), f64::INFINITY);
// -1 to the power of +Inf or -Inf always returns 1.
assert_eq!(f64::powf(-1.0, f64::INFINITY), 1.0);

// any `self` to the power of zero always returns 1.
assert_eq!(i32::pow(0, 0), 1);
// 1 to the power of any `exp` always returns 1.
assert_eq!(i32::pow(1, 2), 1);

[reddevilmidzy]

I'd like to work on this issue:) @rustbot claim