[llvm] Add 3 way compare <=> integer intrinsics to Langref (PR #83227)

[via llvm-commits]

================
@@ -14531,6 +14531,63 @@ The arguments (``%a`` and ``%b``) may be of any integer type or a vector with
 integer element type. The argument types must match each other, and the return
 type must match the argument type.
 
+.. _int_sthreecmp:
+
+'``llvm.sthreecmp.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.sthreecmp`` on any
+integer bit width or any vector of integer elements.
+
+::
+
+      declare i32 @llvm.sthreecmp.i32(i32 %a, i32 %b)
+      declare <4 x i32> @llvm.sthreecmp.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+Overview:
+"""""""""
+
+Return ``-1`` if ``%a`` is less than ``%b``, ``0`` if they are equal, and 
+``1`` if ``%a`` is greater than ``%b``. Vector intrinsics operate on a per-element basis. 
+
+Arguments:
+""""""""""
+
+The arguments (``%a`` and ``%b``) may be of any signed integer type or a vector with
+integer element type. The argument types must match each other, and the return
+type must be at least as wide as ``i2``, to uphold the ``-1`` return value.
+
+.. _int_uthreecmp:
+
+'``llvm.uthreecmp.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``@llvm.sthreecmp`` on any
+integer bit width or any vector of integer elements.
+
+::
+
+      declare i2 @llvm.uthreecmp.i32(i32 %a, i32 %b)
----------------
scottmcm wrote:

> Is this meant to be `i32`?

FWIW, I feel strongly that it shouldn't be `i32`, because it would be a shame to need a `trunc` on it for both clang & rustc -- today `std::strong_ordering` (<https://cpp.godbolt.org/z/4qc7YhqW3>) and `std::cmp::Ordering` (<https://rust.godbolt.org/z/5E3fK5hf5>) are both `i8`.

Sometimes needing a lossless instruction like `sext` to get an i32 feels much more tolerable than nearly-always needing a lossy `trunc` instruction to get `i8` -- especially when we don't yet have `trunc nsw`.

I don't know enough to be able to say whether overloading it for multiple possible return types would be valuable, so I'll leave that for others to comment on.


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