Renamed shifted(right:) to shifted(rightBy:).

Author: stephentyrone

Sources/IntegerUtilities/Divide.swift

@@ -77,7 +77,7 @@ extension BinaryInteger {
     case .toNearestOrAwayFromZero:
       // For round to nearest or away, the condition we want to satisfy is
       // |r| <= |other/2|, with sign(q) != sign(r) when equality holds.
-      if r.magnitude < other.magnitude.shifted(right: 1, rounding: .up) {
+      if r.magnitude < other.magnitude.shifted(rightBy: 1, rounding: .up) {
         return q
       }
       // The (q,r) we have does not satisfy the to nearest or away condition;
@@ -87,7 +87,7 @@ extension BinaryInteger {
     case .toNearestOrEven:
       // For round to nearest or away, the condition we want to satisfy is
       // |r| <= |other/2|, with q even when equality holds.
-      if r.magnitude >  other.magnitude.shifted(right: 1, rounding: .down) ||
+      if r.magnitude >  other.magnitude.shifted(rightBy: 1, rounding: .down) ||
           2*r.magnitude == other.magnitude && q._lowWord & 1 == 1 {
         if (other > 0) != (r > 0) { return q-1 }
         return q+1
@@ -218,7 +218,7 @@ extension SignedInteger {
     case .toNearestOrAwayFromZero:
       // For round to nearest or away, the condition we want to satisfy is
       // |r| <= |other/2|, with sign(q) != sign(r) when equality holds.
-      if r.magnitude < other.magnitude.shifted(right: 1, rounding: .up) {
+      if r.magnitude < other.magnitude.shifted(rightBy: 1, rounding: .up) {
         return (q, r)
       }
       // The (q,r) we have does not satisfy the to nearest or away condition;
@@ -228,7 +228,7 @@ extension SignedInteger {
     case .toNearestOrEven:
       // For round to nearest or away, the condition we want to satisfy is
       // |r| <= |other/2|, with q even when equality holds.
-      if r.magnitude >  other.magnitude.shifted(right: 1, rounding: .down) ||
+      if r.magnitude >  other.magnitude.shifted(rightBy: 1, rounding: .down) ||
           2*r.magnitude == other.magnitude && q._lowWord & 1 == 1 {
         if (other > 0) != (r > 0) { return (q-1, r+other) }
         return (q+1, r-other)

Sources/IntegerUtilities/Rounding.swift

@@ -58,8 +58,8 @@ public enum RoundingRule {
   case toNearestOrEven
 
   /// Adds a uniform random value from [0, d) to the value being rounded,
-  /// then returns the floor of the resulting value, where d is the
-  /// distance between the two closest representable values.
+  /// where d is the distance between the two closest representable values,
+  /// then rounds the sum downwards.
   case stochastically
 
   /// If the value being rounded is representable, that value is returned.

Sources/IntegerUtilities/Shift.swift

@@ -18,27 +18,27 @@ extension BinaryInteger {
   /// Some examples of different rounding rules:
   ///
   ///     // 3/2 is 1.5, which rounds (down by default) to 1.
-  ///     3.shifted(right: 1)
+  ///     3.shifted(rightBy: 1)
   ///
   ///     // 1.5 rounds up to 2.
-  ///     3.shifted(right: 1, rounding: .up)
+  ///     3.shifted(rightBy: 1, rounding: .up)
   ///
   ///     // The two closest values are 1 and 2, 1 is returned because it
   ///     // is odd.
-  ///     3.shifted(right: 1, rounding: .toOdd)
+  ///     3.shifted(rightBy: 1, rounding: .toOdd)
   ///
   ///     // 7/2^2 = 1.75, so the result is 1 with probability 1/4, and 2
   ///     // with probability 3/4.
-  ///     7.shifted(right: 2, rounding: .stochastically)
+  ///     7.shifted(rightBy: 2, rounding: .stochastically)
   ///
   ///     // 4/2^2 = 4/4 = 1, exactly.
-  ///     4.shifted(right: 2, rounding: .trap)
+  ///     4.shifted(rightBy: 2, rounding: .trap)
   ///
   ///     // 5/2 is 2.5, which is not exact, so this traps.
-  ///     5.shifted(right: 1, rounding: .trap)
+  ///     5.shifted(rightBy: 1, rounding: .trap)
   @inlinable
   public func shifted<Count: BinaryInteger>(
-    right count: Count,
+    rightBy count: Count,
     rounding rule: RoundingRule = .down
   ) -> Self {
     // Easiest case: count is zero or negative, so shift is always exact;
@@ -50,7 +50,7 @@ extension BinaryInteger {
       // that we encounter such a case, we promote to Int8, do the shift, and
       // then convert back to the appropriate result type.
       if bitWidth <= 1 {
-        return Self(Int8(self).shifted(right: count, rounding: rule))
+        return Self(Int8(self).shifted(rightBy: count, rounding: rule))
       }
       // That pathological case taken care of, we can now handle over-wide
       // shifts by first shifting all but bitWidth - 1 bits with sticky
@@ -60,7 +60,7 @@ extension BinaryInteger {
       var floor = self >> count
       let lost = self - (floor << count)
       if lost != 0 { floor |= 1 } // insert sticky bit
-      return floor.shifted(right: bitWidth - 1, rounding: rule)
+      return floor.shifted(rightBy: bitWidth - 1, rounding: rule)
     }
     // Now we are in the happy case: 0 < count < bitWidth, which makes all
     // the math to handle rounding simpler.

Tests/IntegerUtilitiesTests/ShiftTests.swift

@@ -37,7 +37,7 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
     case .toNearestOrAwayFromZero:
       if exact { expected = floor }
       else {
-        let step = value.shifted(right: count - 2, rounding: .toOdd)
+        let step = value.shifted(rightBy: count - 2, rounding: .toOdd)
         switch step & 0b11 {
         case 0b01: expected = floor
         case 0b10: expected = value > 0 ? ceiling : floor
@@ -48,7 +48,7 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
     case .toNearestOrEven:
       if exact { expected = floor }
       else {
-        let step = value.shifted(right: count - 2, rounding: .toOdd)
+        let step = value.shifted(rightBy: count - 2, rounding: .toOdd)
         switch step & 0b11 {
         case 0b01: expected = floor
         case 0b10: expected = floor & 1 == 0 ? floor : ceiling
@@ -61,9 +61,9 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
       // or ceiling.
       if exact { expected = floor }
       else {
-        let observed = value.shifted(right: count, rounding: rule)
+        let observed = value.shifted(rightBy: count, rounding: rule)
         if observed != floor && observed != ceiling {
-          print("Error found in \(T.self).shifted(right: \(count), rounding: \(rule)).")
+          print("Error found in \(T.self).shifted(rightBy: \(count), rounding: \(rule)).")
           print("   Value: \(String(value, radix: 16))")
           print("Expected: \(String(floor, radix: 16)) or \(String(ceiling, radix: 16))")
           print("Observed: \(String(observed, radix: 16))")
@@ -74,9 +74,9 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
     case .requireExact:
       preconditionFailure()
     }
-    let observed = value.shifted(right: count, rounding: rule)
+    let observed = value.shifted(rightBy: count, rounding: rule)
     if observed != expected {
-      print("Error found in \(T.self).shifted(right: \(count), rounding: \(rule)).")
+      print("Error found in \(T.self).shifted(rightBy: \(count), rounding: \(rule)).")
       print("   Value: \(String(value, radix: 16))")
       print("Expected: \(String(expected, radix: 16))")
       print("Observed: \(String(observed, radix: 16))")
@@ -89,7 +89,7 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
   ) {
     for count in -2*T.bitWidth ... 2*T.bitWidth {
       // zero shifted by anything is always zero
-      XCTAssertEqual(0, (0 as T).shifted(right: count, rounding: rule))
+      XCTAssertEqual(0, (0 as T).shifted(rightBy: count, rounding: rule))
       for _ in 0 ..< 100 {
         testRoundingShift(T.random(in: .min ... .max), count, rounding: rule)
       }
@@ -147,7 +147,7 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
     var fails = 0
     for count in 0 ... 64 {
       let sum = (0..<1024).reduce(into: 0.0) { sum, _ in
-        let rounded = value.shifted(right: count, rounding: .stochastically)
+        let rounded = value.shifted(rightBy: count, rounding: .stochastically)
         sum += Double(rounded)
       }
       let expected = Double(sign: .plus, exponent: -count, significand: 1024*Double(value))
@@ -164,15 +164,15 @@ final class IntegerUtilitiesShiftTests: XCTestCase {
       // but if you see a repeated failure for a given shift count, that's
       // almost surely a real bug.
       XCTAssertLessThanOrEqual(difference, 64,
-      "Accumulated error (\(difference)) was unexpectedly large in \(value).shifted(right: \(count))"
+      "Accumulated error (\(difference)) was unexpectedly large in \(value).shifted(rightBy: \(count))"
       )
     }
     // Threshold chosen so that this is expected to _almost always_ pass, but
     // it may fail sporadically. This is not a great fit for CI workflows,
     // sorry. Basically ignore one-off failures, but a repeated failure here
     // is an indication that a bug exists.
     XCTAssertLessThanOrEqual(fails, 16,
-    "Accumulated error was large more often than expected for \(value).shifted(right:)"
+    "Accumulated error was large more often than expected for \(value).shifted(rightBy:)"
     )
   }