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

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-llvm-ir

Author: Ralf Jung (RalfJung)

<details>
<summary>Changes</summary>

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.

---
Full diff: https://github.com/llvm/llvm-project/pull/170177.diff


1 Files Affected:

- (modified) llvm/docs/LangRef.rst (+11) 


``````````diff
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 02865f8a29c67..292f70f062bd2 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -16269,6 +16269,11 @@ Semantics:
 This function returns the first value raised to the second power with an
 unspecified sequence of rounding operations.
 
+Note that due to how :ref:`LLVM treats NaN values <floatnan>`, the special case
+of `powi(SNaN, 0.0)` can non-deterministically return *either* some NaN value
+(using the usual NaN propagation rules, so in particular the result could be
+either a signaling NaN or a quiet NaN), *or* the value `1.0`.
+
 .. _t_llvm_sin:
 
 '``llvm.sin.*``' Intrinsic
@@ -16831,6 +16836,12 @@ trapping or setting ``errno``.
 When specified with the fast-math-flag 'afn', the result may be approximated
 using a less accurate calculation.
 
+Note that due to how :ref:`LLVM treats NaN values <floatnan>`, the special cases
+of `pow(1.0, SNaN)` and `pow(SNaN, 0.0)` can non-deterministically return
+*either* some NaN value (using the usual NaN propagation rules, so in particular
+the result could be either a signaling NaN or a quiet NaN), *or* the value
+`1.0`.
+
 .. _int_exp:
 
 '``llvm.exp.*``' Intrinsic

``````````

</details>


https://github.com/llvm/llvm-project/pull/170177