[APInt] Add saturating truncation methods

[lebedev.ri]

Summary

The signed one is needed for implementation of ConstantRange::smul_sat(),
unsigned is for completeness only.

[nikic]

LGTM

I feel like the names are a bit inconsistent with existing uadd_sat etc, but utrunc_sat seems worse than truncUSat, so let's just go with it...

[lebedev.ri]

In D69993#1738340, @nikic wrote:

LGTM

I feel like the names are a bit inconsistent with existing uadd_sat etc, but utrunc_sat seems worse than truncUSat, so let's just go with it...

Yes, i'm on the fence regarding names here.
I initially used trunc{Unsigned,Sign/Signed}Sat(), but that didn't seem much better..

llvm/include/llvm/ADT/APInt.h

#endif
   /// @{
 
   /// Truncate to new width.
   ///
   /// Truncate the APInt to a specified width. It is an error to specify a width
   /// that is greater than or equal to the current width.
   APInt trunc(unsigned width) const;
 
+  /// Truncate to new width with unsigned saturation.
+  ///
+  /// If the APInt, treated as unsigned integer, can be losslessly truncated to
+  /// the new bitwidth, then return truncated APInt. Else, return max value.
+  APInt truncUSat(unsigned width) const;
+
+  /// Truncate to new width with signed saturation.
+  ///
+  /// If this APInt, treated as signed integer, can be losslessly truncated to
+  /// the new bitwidth, then return truncated APInt. Else, return either
+  /// signed min value if the APInt was negative, or signed max value.
+  APInt truncSSat(unsigned width) const;
+
   /// Sign extend to a new width.
   ///
   /// This operation sign extends the APInt to a new width. If the high order
   /// bit is set, the fill on the left will be done with 1 bits, otherwise zero.
   /// It is an error to specify a width that is less than or equal to the
   /// current width.
   APInt sext(unsigned width) const;
 

llvm/lib/Support/APInt.cpp

APInt APInt::trunc(unsigned width) const {
   // Truncate and copy any partial word.
   unsigned bits = (0 - width) % APINT_BITS_PER_WORD;
   if (bits != 0)
     Result.U.pVal[i] = U.pVal[i] << bits >> bits;
 
   return Result;
 }
 
+// Truncate to new width with unsigned saturation.
+APInt APInt::truncUSat(unsigned width) const {
+  assert(width < BitWidth && "Invalid APInt Truncate request");
+  assert(width && "Can't truncate to 0 bits");
+
+  // Can we just losslessly truncate it?
+  if (isIntN(width))
+    return trunc(width);
+  // If not, then just return the new limit.
+  return APInt::getMaxValue(width);
+}
+
+// Truncate to new width with signed saturation.
+APInt APInt::truncSSat(unsigned width) const {
+  assert(width < BitWidth && "Invalid APInt Truncate request");
+  assert(width && "Can't truncate to 0 bits");
+
+  // Can we just losslessly truncate it?
+  if (isSignedIntN(width))
+    return trunc(width);
+  // If not, then just return the new limits.
+  return isNegative() ? APInt::getSignedMinValue(width)
+                      : APInt::getSignedMaxValue(width);
+}
+
 // Sign extend to a new width.
 APInt APInt::sext(unsigned Width) const {
   assert(Width > BitWidth && "Invalid APInt SignExtend request");
 
   if (Width <= APINT_BITS_PER_WORD)
     return APInt(Width, SignExtend64(U.VAL, BitWidth));
 
   APInt Result(getMemory(getNumWords(Width)), Width);

llvm/unittests/ADT/APIntTest.cpp

TEST(APIntTest, fromString) {
   EXPECT_EQ(APInt(32, uint64_t(-35LL)), APInt(32,  "-Z", 36));
   EXPECT_EQ(APInt(32, uint64_t(-36LL)), APInt(32, "-10", 36));
   EXPECT_EQ(APInt(32, uint64_t(-71LL)), APInt(32, "-1Z", 36));
   EXPECT_EQ(APInt(32, uint64_t(-72LL)), APInt(32, "-20", 36));
 }
 
 TEST(APIntTest, SaturatingMath) {
   APInt AP_10 = APInt(8, 10);
+  APInt AP_42 = APInt(8, 42);
   APInt AP_100 = APInt(8, 100);
   APInt AP_200 = APInt(8, 200);
 
+  EXPECT_EQ(APInt(7, 100), AP_100.truncUSat(7));
+  EXPECT_EQ(APInt(6, 63), AP_100.truncUSat(6));
+  EXPECT_EQ(APInt(5, 31), AP_100.truncUSat(5));
+
+  EXPECT_EQ(APInt(7, 127), AP_200.truncUSat(7));
+  EXPECT_EQ(APInt(6, 63), AP_200.truncUSat(6));
+  EXPECT_EQ(APInt(5, 31), AP_200.truncUSat(5));
+
+  EXPECT_EQ(APInt(7, 42), AP_42.truncSSat(7));
+  EXPECT_EQ(APInt(6, 31), AP_42.truncSSat(6));
+  EXPECT_EQ(APInt(5, 15), AP_42.truncSSat(5));
+
+  EXPECT_EQ(APInt(7, -56), AP_200.truncSSat(7));
+  EXPECT_EQ(APInt(6, -32), AP_200.truncSSat(6));
+  EXPECT_EQ(APInt(5, -16), AP_200.truncSSat(5));
+
   EXPECT_EQ(APInt(8, 200), AP_100.uadd_sat(AP_100));
   EXPECT_EQ(APInt(8, 255), AP_100.uadd_sat(AP_200));
   EXPECT_EQ(APInt(8, 255), APInt(8, 255).uadd_sat(APInt(8, 255)));
 
   EXPECT_EQ(APInt(8, 110), AP_10.sadd_sat(AP_100));
   EXPECT_EQ(APInt(8, 127), AP_100.sadd_sat(AP_100));
   EXPECT_EQ(APInt(8, -128), (-AP_100).sadd_sat(-AP_100));
   EXPECT_EQ(APInt(8, -128), APInt(8, -128).sadd_sat(APInt(8, -128)));