Rollup merge of rust-lang#137828 - folkertdev:simd-intrinsic-doc-fixes, r=workingjubilee

Fix inaccurate `std::intrinsics::simd` documentation

This addresses two issues:

- the docs on comparison operators (`simd_gt` etc.) said they only work for floating-point vectors, but they work for integer vectors too.
- the docs on various functions that use a mask did not document that the mask must be a signed integer vector. Unsigned integer vectors would cause invalid behavior when the mask vector is widened (unsigned integers would use zero extension, producing incorrect results).

r? ``@workingjubilee``

Author: matthiaskrgr

core/src/intrinsics/simd.rs

@@ -26,28 +26,28 @@ pub const unsafe fn simd_extract<T, U>(_x: T, _idx: u32) -> U;
 
 /// Adds two simd vectors elementwise.
 ///
-/// `T` must be a vector of integer or floating point primitive types.
+/// `T` must be a vector of integers or floats.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_add<T>(_x: T, _y: T) -> T;
 
 /// Subtracts `rhs` from `lhs` elementwise.
 ///
-/// `T` must be a vector of integer or floating point primitive types.
+/// `T` must be a vector of integers or floats.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_sub<T>(_lhs: T, _rhs: T) -> T;
 
 /// Multiplies two simd vectors elementwise.
 ///
-/// `T` must be a vector of integer or floating point primitive types.
+/// `T` must be a vector of integers or floats.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_mul<T>(_x: T, _y: T) -> T;
 
 /// Divides `lhs` by `rhs` elementwise.
 ///
-/// `T` must be a vector of integer or floating point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// # Safety
 /// For integers, `rhs` must not contain any zero elements.
@@ -58,7 +58,7 @@ pub unsafe fn simd_div<T>(_lhs: T, _rhs: T) -> T;
 
 /// Returns remainder of two vectors elementwise.
 ///
-/// `T` must be a vector of integer or floating point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// # Safety
 /// For integers, `rhs` must not contain any zero elements.
@@ -71,7 +71,7 @@ pub unsafe fn simd_rem<T>(_lhs: T, _rhs: T) -> T;
 ///
 /// Shifts `lhs` left by `rhs`, shifting in sign bits for signed types.
 ///
-/// `T` must be a vector of integer primitive types.
+/// `T` must be a vector of integers.
 ///
 /// # Safety
 ///
@@ -82,7 +82,7 @@ pub unsafe fn simd_shl<T>(_lhs: T, _rhs: T) -> T;
 
 /// Shifts vector right elementwise, with UB on overflow.
 ///
-/// `T` must be a vector of integer primitive types.
+/// `T` must be a vector of integers.
 ///
 /// Shifts `lhs` right by `rhs`, shifting in sign bits for signed types.
 ///
@@ -95,29 +95,28 @@ pub unsafe fn simd_shr<T>(_lhs: T, _rhs: T) -> T;
 
 /// "Ands" vectors elementwise.
 ///
-/// `T` must be a vector of integer primitive types.
+/// `T` must be a vector of integers.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_and<T>(_x: T, _y: T) -> T;
 
 /// "Ors" vectors elementwise.
 ///
-/// `T` must be a vector of integer primitive types.
+/// `T` must be a vector of integers.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_or<T>(_x: T, _y: T) -> T;
 
 /// "Exclusive ors" vectors elementwise.
 ///
-/// `T` must be a vector of integer primitive types.
+/// `T` must be a vector of integers.
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn simd_xor<T>(_x: T, _y: T) -> T;
 
 /// Numerically casts a vector, elementwise.
 ///
-/// `T` and `U` must be vectors of integer or floating point primitive types, and must have the
-/// same length.
+/// `T` and `U` must be vectors of integers or floats, and must have the same length.
 ///
 /// When casting floats to integers, the result is truncated. Out-of-bounds result lead to UB.
 /// When casting integers to floats, the result is rounded.
@@ -138,8 +137,7 @@ pub unsafe fn simd_cast<T, U>(_x: T) -> U;
 
 /// Numerically casts a vector, elementwise.
 ///
-/// `T` and `U` be a vectors of integer or floating point primitive types, and must have the
-/// same length.
+/// `T` and `U` be a vectors of integers or floats, and must have the same length.
 ///
 /// Like `simd_cast`, but saturates float-to-integer conversions (NaN becomes 0).
 /// This matches regular `as` and is always safe.
@@ -153,7 +151,7 @@ pub unsafe fn simd_as<T, U>(_x: T) -> U;
 
 /// Negates a vector elementwise.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// Rust panics for `-<int>::Min` due to overflow, but it is not UB with this intrinsic.
 #[rustc_intrinsic]
@@ -187,7 +185,7 @@ pub unsafe fn simd_fmax<T>(_x: T, _y: T) -> T;
 
 /// Tests elementwise equality of two vectors.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -198,7 +196,7 @@ pub unsafe fn simd_eq<T, U>(_x: T, _y: T) -> U;
 
 /// Tests elementwise inequality equality of two vectors.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -209,7 +207,7 @@ pub unsafe fn simd_ne<T, U>(_x: T, _y: T) -> U;
 
 /// Tests if `x` is less than `y`, elementwise.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -220,7 +218,7 @@ pub unsafe fn simd_lt<T, U>(_x: T, _y: T) -> U;
 
 /// Tests if `x` is less than or equal to `y`, elementwise.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -231,7 +229,7 @@ pub unsafe fn simd_le<T, U>(_x: T, _y: T) -> U;
 
 /// Tests if `x` is greater than `y`, elementwise.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -242,7 +240,7 @@ pub unsafe fn simd_gt<T, U>(_x: T, _y: T) -> U;
 
 /// Tests if `x` is greater than or equal to `y`, elementwise.
 ///
-/// `T` must be a vector of floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be a vector of integers with the same number of elements and element size as `T`.
 ///
@@ -273,7 +271,7 @@ pub unsafe fn simd_shuffle<T, U, V>(_x: T, _y: T, _idx: U) -> V;
 ///
 /// `U` must be a vector of pointers to the element type of `T`, with the same length as `T`.
 ///
-/// `V` must be a vector of integers with the same length as `T` (but any element size).
+/// `V` must be a vector of signed integers with the same length as `T` (but any element size).
 ///
 /// For each pointer in `ptr`, if the corresponding value in `mask` is `!0`, read the pointer.
 /// Otherwise if the corresponding value in `mask` is `0`, return the corresponding value from
@@ -294,7 +292,7 @@ pub unsafe fn simd_gather<T, U, V>(_val: T, _ptr: U, _mask: V) -> T;
 ///
 /// `U` must be a vector of pointers to the element type of `T`, with the same length as `T`.
 ///
-/// `V` must be a vector of integers with the same length as `T` (but any element size).
+/// `V` must be a vector of signed integers with the same length as `T` (but any element size).
 ///
 /// For each pointer in `ptr`, if the corresponding value in `mask` is `!0`, write the
 /// corresponding value in `val` to the pointer.
@@ -318,7 +316,7 @@ pub unsafe fn simd_scatter<T, U, V>(_val: T, _ptr: U, _mask: V);
 ///
 /// `U` must be a pointer to the element type of `T`
 ///
-/// `V` must be a vector of integers with the same length as `T` (but any element size).
+/// `V` must be a vector of signed integers with the same length as `T` (but any element size).
 ///
 /// For each element, if the corresponding value in `mask` is `!0`, read the corresponding
 /// pointer offset from `ptr`.
@@ -341,7 +339,7 @@ pub unsafe fn simd_masked_load<V, U, T>(_mask: V, _ptr: U, _val: T) -> T;
 ///
 /// `U` must be a pointer to the element type of `T`
 ///
-/// `V` must be a vector of integers with the same length as `T` (but any element size).
+/// `V` must be a vector of signed integers with the same length as `T` (but any element size).
 ///
 /// For each element, if the corresponding value in `mask` is `!0`, write the corresponding
 /// value in `val` to the pointer offset from `ptr`.
@@ -375,7 +373,7 @@ pub unsafe fn simd_saturating_sub<T>(_lhs: T, _rhs: T) -> T;
 
 /// Adds elements within a vector from left to right.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 ///
@@ -387,7 +385,7 @@ pub unsafe fn simd_reduce_add_ordered<T, U>(_x: T, _y: U) -> U;
 /// Adds elements within a vector in arbitrary order. May also be re-associated with
 /// unordered additions on the inputs/outputs.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 #[rustc_intrinsic]
@@ -396,7 +394,7 @@ pub unsafe fn simd_reduce_add_unordered<T, U>(_x: T) -> U;
 
 /// Multiplies elements within a vector from left to right.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 ///
@@ -408,7 +406,7 @@ pub unsafe fn simd_reduce_mul_ordered<T, U>(_x: T, _y: U) -> U;
 /// Multiplies elements within a vector in arbitrary order. May also be re-associated with
 /// unordered additions on the inputs/outputs.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 #[rustc_intrinsic]
@@ -437,7 +435,7 @@ pub unsafe fn simd_reduce_any<T>(_x: T) -> bool;
 
 /// Returns the maximum element of a vector.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 ///
@@ -448,7 +446,7 @@ pub unsafe fn simd_reduce_max<T, U>(_x: T) -> U;
 
 /// Returns the minimum element of a vector.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 ///
@@ -459,7 +457,7 @@ pub unsafe fn simd_reduce_min<T, U>(_x: T) -> U;
 
 /// Logical "ands" all elements together.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 #[rustc_intrinsic]
@@ -468,7 +466,7 @@ pub unsafe fn simd_reduce_and<T, U>(_x: T) -> U;
 
 /// Logical "ors" all elements together.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 #[rustc_intrinsic]
@@ -477,7 +475,7 @@ pub unsafe fn simd_reduce_or<T, U>(_x: T) -> U;
 
 /// Logical "exclusive ors" all elements together.
 ///
-/// `T` must be a vector of integer or floating-point primitive types.
+/// `T` must be a vector of integers or floats.
 ///
 /// `U` must be the element type of `T`.
 #[rustc_intrinsic]
@@ -523,9 +521,9 @@ pub unsafe fn simd_bitmask<T, U>(_x: T) -> U;
 
 /// Selects elements from a mask.
 ///
-/// `M` must be an integer vector.
+/// `T` must be a vector.
 ///
-/// `T` must be a vector with the same number of elements as `M`.
+/// `M` must be a signed integer vector with the same length as `T` (but any element size).
 ///
 /// For each element, if the corresponding value in `mask` is `!0`, select the element from
 /// `if_true`.  If the corresponding value in `mask` is `0`, select the element from