[llvm] 136e5e2 - [LangRef] make consequences of NaN rules for pow(i) more explicit (#170177)

[via llvm-commits]

Author: Ralf Jung
Date: 2025-12-10T15:26:19+01:00
New Revision: 136e5e288402f5519fdba21c8838145399a27e07

URL: https://github.com/llvm/llvm-project/commit/136e5e288402f5519fdba21c8838145399a27e07
DIFF: https://github.com/llvm/llvm-project/commit/136e5e288402f5519fdba21c8838145399a27e07.diff

LOG: [LangRef] make consequences of NaN rules for pow(i) more explicit (#170177)

The NaN section says

> Floating-point math operations are allowed to treat all NaNs as if
they were quiet NaNs. For example, “pow(1.0, SNaN)” may be simplified to
1.0.

This seems worth also spelling out in the section for `pow` (and `powi`
which has a similar situation), to have everything concerning those
operations in a single place.

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index a1804848221dd..1c55eabf9a39a 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -16289,6 +16289,13 @@ Semantics:
 This function returns the first value raised to the second power with an
 unspecified sequence of rounding operations.
 
+Note that the `powi` function is unusual in that NaN inputs can lead to non-NaN
+results, and this depends on the kind of NaN (quiet vs signaling). Due to how
+:ref:`LLVM treats NaN values <floatnan>` in non-constrained functions, the
+function may non-deterministically treat signaling NaNs as quiet NaNs. For
+example, `powi(QNaN, 0)` returns `1.0`, and `powi(SNaN, 0)` may
+non-deterministically return `1.0` or a NaN.
+
 .. _t_llvm_sin:
 
 '``llvm.sin.*``' Intrinsic
@@ -16851,6 +16858,13 @@ trapping or setting ``errno``.
 When specified with the fast-math-flag 'afn', the result may be approximated
 using a less accurate calculation.
 
+Note that the `pow` function is unusual in that NaN inputs can lead to non-NaN
+results, and this depends on the kind of NaN (quiet vs signaling). Due to how
+:ref:`LLVM treats NaN values <floatnan>` in non-constrained functions, the
+function may non-deterministically treat signaling NaNs as quiet NaNs. For
+example, `pow(QNaN, 0.0)` returns `1.0`, and `pow(SNaN, 0.0)` may
+non-deterministically return `1.0` or a NaN.
+
 .. _int_exp:
 
 '``llvm.exp.*``' Intrinsic