cleanup

Sources/ANKCoreKit/Private/Messages.swift

@@ -17,15 +17,15 @@ extension ANK {
     // MARK: Utilities
     //=------------------------------------------------------------------------=
 
-    /// A message describing the source code location of an overflow occurrence.
+    /// A message describing the source code location of an overflow error.
     @inlinable public static func callsiteOverflowInfo(
     function: StaticString = #function, file: StaticString = #file, line: UInt = #line) -> String {
         "overflow in \(function) at \(file):\(line)"
     }
 
-    /// A message describing the source code location of an index-out-of-bounds occurrence.
-    @inlinable public static func callsiteIndexOutOfBoundsInfo(
+    /// A message describing the source code location of an out-of-bounds error.
+    @inlinable public static func callsiteOutOfBoundsInfo(
     function: StaticString = #function, file: StaticString = #file, line: UInt = #line) -> String {
-        "index out of bounds in \(function) at \(file):\(line)"
+        "out of bounds in \(function) at \(file):\(line)"
     }
 }

Sources/ANKFullWidthKit/ANKFullWidth+Shifts.swift

@@ -62,19 +62,19 @@ extension ANKFullWidth {
         var result = self; result.bitshiftLeftSmart(by: distance); return result
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - distance: `0 <= distance < Self.bitWidth`
     ///
     @inlinable public mutating func bitshiftLeft(by distance: Int) {
-        precondition(distance >= 0, "shift distance must be at least zero")
+        precondition(distance >= 0, ANK.callsiteOutOfBoundsInfo())
         let major  = distance .quotientDividingByBitWidthAssumingIsAtLeastZero()
         let minor  = distance.remainderDividingByBitWidthAssumingIsAtLeastZero()
         return self.bitshiftLeft(words: major, bits: minor)
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - distance: `0 <= distance < Self.bitWidth`
@@ -83,15 +83,15 @@ extension ANKFullWidth {
         var result = self; result.bitshiftLeft(by: distance); return result
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
     ///   - bits:  `0 <= bits  < UInt.bitWidth`
     ///
     @inlinable public mutating func bitshiftLeft(words: Int, bits: Int) {
-        precondition(0 ..< self.endIndex ~= words, "invalid major shift distance")
-        precondition(0 ..< UInt.bitWidth ~= bits,  "invalid minor shift distance")
+        precondition(0 ..< self.endIndex ~= words, ANK.callsiteOutOfBoundsInfo())
+        precondition(0 ..< UInt.bitWidth ~= bits,  ANK.callsiteOutOfBoundsInfo())
         //=--------------------------------------=
         if  bits.isZero {
             return self.bitshiftLeft(words: words)
@@ -113,7 +113,7 @@ extension ANKFullWidth {
         }
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
@@ -123,13 +123,13 @@ extension ANKFullWidth {
         var result = self; result.bitshiftLeft(words: words, bits: bits); return result
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
     ///
     @inlinable public mutating func bitshiftLeft(words: Int) {
-        precondition(0 ..< self.endIndex ~= words, "invalid major shift distance")
+        precondition(0 ..< self.endIndex ~= words, ANK.callsiteOutOfBoundsInfo())
         //=--------------------------------------=
         if  words.isZero { return }
         //=--------------------------------------=
@@ -138,7 +138,7 @@ extension ANKFullWidth {
         }
     }
 
-    /// Performs an unchecked left shift.
+    /// Performs a left shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
@@ -201,19 +201,19 @@ extension ANKFullWidth {
         var result = self; result.bitshiftRightSmart(by: distance); return result
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - distance: `0 <= distance < Self.bitWidth`
     ///
     @inlinable public mutating func bitshiftRight(by distance: Int) {
-        precondition(distance >= 0, "shift distance must be at least zero")
+        precondition(distance >= 0, ANK.callsiteOutOfBoundsInfo())
         let major =  distance .quotientDividingByBitWidthAssumingIsAtLeastZero()
         let minor =  distance.remainderDividingByBitWidthAssumingIsAtLeastZero()
         return self.bitshiftRight(words: major, bits: minor)
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - distance: `0 <= distance < Self.bitWidth`
@@ -222,15 +222,15 @@ extension ANKFullWidth {
         var result = self; result.bitshiftRight(by: distance); return result
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
     ///   - bits:  `0 <= bits  < UInt.bitWidth`
     ///
     @inlinable public mutating func bitshiftRight(words: Int, bits: Int) {
-        precondition(0 ..< self.endIndex ~= words, "invalid major shift distance")
-        precondition(0 ..< UInt.bitWidth ~= bits,  "invalid minor shift distance")
+        precondition(0 ..< self.endIndex ~= words, ANK.callsiteOutOfBoundsInfo())
+        precondition(0 ..< UInt.bitWidth ~= bits,  ANK.callsiteOutOfBoundsInfo())
         //=--------------------------------------=
         if  bits.isZero {
             return self.bitshiftRight(words: words)
@@ -254,7 +254,7 @@ extension ANKFullWidth {
         }
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
@@ -264,13 +264,13 @@ extension ANKFullWidth {
         var result = self; result.bitshiftRight(words: words, bits: bits); return result
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`
     ///
     @inlinable public mutating func bitshiftRight(words: Int) {
-        precondition(0 ..< self.endIndex ~= words, "invalid major shift distance")
+        precondition(0 ..< self.endIndex ~= words, ANK.callsiteOutOfBoundsInfo())
         //=--------------------------------------=
         if  words.isZero { return }
         //=--------------------------------------=
@@ -283,7 +283,7 @@ extension ANKFullWidth {
         }
     }
 
-    /// Performs an unchecked, signed, right shift.
+    /// Performs a signed right shift.
     ///
     /// - Parameters:
     ///   - words: `0 <= words < Self.endIndex`

Sources/ANKFullWidthKit/ANKFullWidth+Words+Pointers.swift

@@ -211,7 +211,7 @@ extension ANKFullWidth {
 
         /// Accesses the word at the given index, from least significant to most.
         @inlinable public subscript(index: Int) -> UInt {
-            precondition(self.indices ~= index, ANK.callsiteIndexOutOfBoundsInfo())
+            precondition(self.indices ~= index, ANK.callsiteOutOfBoundsInfo())
             return self[unchecked: index]
         }
 
@@ -332,12 +332,12 @@ extension ANKFullWidth {
         /// Accesses the word at the given index, from least significant to most.
         @inlinable public subscript(index: Int) -> UInt {
             nonmutating get {
-                precondition(self.indices ~= index, ANK.callsiteIndexOutOfBoundsInfo())
+                precondition(self.indices ~= index, ANK.callsiteOutOfBoundsInfo())
                 return self[unchecked: index]
             }
 
             nonmutating set {
-                precondition(self.indices ~= index, ANK.callsiteIndexOutOfBoundsInfo())
+                precondition(self.indices ~= index, ANK.callsiteOutOfBoundsInfo())
                 self[unchecked: index] = newValue
             }
         }

Sources/ANKFullWidthKit/ANKFullWidth+Words.swift

@@ -228,7 +228,7 @@ extension ANKFullWidth where High == High.Magnitude {
     //=------------------------------------------------------------------------=
 
     @inlinable static func endiannessSensitiveIndex(unchecked index: Int) -> Int {
-        assert(self.indices ~= index, ANK.callsiteIndexOutOfBoundsInfo())
+        assert(self.indices ~= index, ANK.callsiteOutOfBoundsInfo())
         #if _endian(big)
         return self.lastIndex - index
         #else

Tests/ANKCoreKitBenchmarks/Int+Division.swift

@@ -0,0 +1,161 @@
+//=----------------------------------------------------------------------------=
+// This source file is part of the AwesomeNumbersKit open source project.
+//
+// Copyright (c) 2022 Oscar Byström Ericsson
+// Licensed under Apache License, Version 2.0
+//
+// See http://www.apache.org/licenses/LICENSE-2.0 for license information.
+//=----------------------------------------------------------------------------=
+
+#if !DEBUG
+
+import ANKCoreKit
+import XCTest
+
+//*============================================================================*
+// MARK: * ANK x Int x Division
+//*============================================================================*
+
+final class IntBenchmarksOnDivision: XCTestCase {
+
+    typealias T =  Int
+    typealias M = UInt
+
+    //=------------------------------------------------------------------------=
+    // MARK: Tests
+    //=------------------------------------------------------------------------=
+
+    func testQuotientAndRemainder() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.quotientAndRemainder(dividingBy: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testQuotientReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividedReportingOverflow(by: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testRemainderReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.remainderReportingOverflow(dividingBy: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    //=------------------------------------------------------------------------=
+    // MARK: Tests x Full Width
+    //=------------------------------------------------------------------------=
+
+    func testDividingFullWidth() {
+        var lhs = ANK.blackHoleIdentity((T.max))
+        var rhs = ANK.blackHoleIdentity((T.max / 2, M(bitPattern: T.max)))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividingFullWidth(rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testDividingFullWidthReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity((T.max))
+        var rhs = ANK.blackHoleIdentity((T.max / 2, M(bitPattern: T.max)))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividingFullWidthReportingOverflow(rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+}
+
+//*============================================================================*
+// MARK: * ANK x UInt x Division
+//*============================================================================*
+
+final class UIntBenchmarksOnDivision: XCTestCase {
+
+    typealias T = UInt
+    typealias M = UInt
+
+    //=------------------------------------------------------------------------=
+    // MARK: Tests
+    //=------------------------------------------------------------------------=
+
+    func testQuotientAndRemainder() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.quotientAndRemainder(dividingBy: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testQuotientReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividedReportingOverflow(by: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testRemainderReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity(~T(123))
+        var rhs = ANK.blackHoleIdentity( T(123))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.remainderReportingOverflow(dividingBy: rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    //=------------------------------------------------------------------------=
+    // MARK: Tests x Full Width
+    //=------------------------------------------------------------------------=
+
+    func testDividingFullWidth() {
+        var lhs = ANK.blackHoleIdentity((T.max))
+        var rhs = ANK.blackHoleIdentity((T.max - 1, M.max))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividingFullWidth(rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+
+    func testDividingFullWidthReportingOverflow() {
+        var lhs = ANK.blackHoleIdentity((T.max))
+        var rhs = ANK.blackHoleIdentity((T.max - 1, M.max))
+
+        for _ in 0 ..< 5_000_000 {
+            ANK.blackHole(lhs.dividingFullWidthReportingOverflow(rhs))
+            ANK.blackHoleInoutIdentity(&lhs)
+            ANK.blackHoleInoutIdentity(&rhs)
+        }
+    }
+}
+
+#endif