Merge (#119) - UIntXL (work in progress)

.swiftpm/NBKFlexibleWidthKit-Benchmarks.xctestplan

@@ -0,0 +1,34 @@
+{
+  "configurations" : [
+    {
+      "id" : "2BBD9A51-D890-4B97-AED4-B9962867DF57",
+      "name" : "Main",
+      "options" : {
+
+      }
+    }
+  ],
+  "defaultOptions" : {
+    "codeCoverage" : false
+  },
+  "testTargets" : [
+    {
+      "skippedTests" : [
+        "NBKFibonacciXLBenchmarks\/testNoLoop10000000()",
+        "NBKFlexibleWidthBenchmarksOnExponentiationAsUIntXL\/test7RaisedToPrime777()",
+        "NBKFlexibleWidthBenchmarksOnExponentiationAsUIntXL\/testNoLoop5RaisedToPrime22222()",
+        "NBKFlexibleWidthBenchmarksOnExponentiationAsUIntXL\/testNoLoop5RaisedToPrime33333()",
+        "NBKFlexibleWidthBenchmarksOnExponentiationAsUIntXL\/testNoLoop5RaisedToPrime55555()",
+        "NBKFlexibleWidthBenchmarksOnExponentiationAsUIntXL\/testNoLoop7RaisedToPrime77777()",
+        "NBKFlexibleWidthBenchmarksOnTextAsUIntXL\/testEncodingUsingSwiftStdlibRadix10()",
+        "NBKFlexibleWidthBenchmarksOnTextAsUIntXL\/testEncodingUsingSwiftStdlibRadix16()"
+      ],
+      "target" : {
+        "containerPath" : "container:",
+        "identifier" : "NBKFlexibleWidthKitBenchmarks",
+        "name" : "NBKFlexibleWidthKitBenchmarks"
+      }
+    }
+  ],
+  "version" : 1
+}

.swiftpm/NBKFlexibleWidthKit.xctestplan

@@ -0,0 +1,32 @@
+{
+  "configurations" : [
+    {
+      "id" : "6FC9897F-2BF3-4836-8372-787CE5195F87",
+      "name" : "Main",
+      "options" : {
+
+      }
+    }
+  ],
+  "defaultOptions" : {
+    "codeCoverage" : {
+      "targets" : [
+        {
+          "containerPath" : "container:",
+          "identifier" : "NBKFlexibleWidthKit",
+          "name" : "NBKFlexibleWidthKit"
+        }
+      ]
+    }
+  },
+  "testTargets" : [
+    {
+      "target" : {
+        "containerPath" : "container:",
+        "identifier" : "NBKFlexibleWidthKitTests",
+        "name" : "NBKFlexibleWidthKitTests"
+      }
+    }
+  ],
+  "version" : 1
+}

.swiftpm/xcode/xcshareddata/xcschemes/NBKFlexibleWidthKit-Benchmarks.xcscheme

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1430"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "NBKFlexibleWidthKit"
+               BuildableName = "NBKFlexibleWidthKit"
+               BlueprintName = "NBKFlexibleWidthKit"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Release"
+      selectedDebuggerIdentifier = ""
+      selectedLauncherIdentifier = "Xcode.IDEFoundation.Launcher.PosixSpawn"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:.swiftpm/NBKFlexibleWidthKit.xctestplan">
+         </TestPlanReference>
+         <TestPlanReference
+            reference = "container:.swiftpm/NBKFlexibleWidthKit-Benchmarks.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Release"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = "Time Profiler"
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "NBKFlexibleWidthKit"
+            BuildableName = "NBKFlexibleWidthKit"
+            BlueprintName = "NBKFlexibleWidthKit"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Release">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

.swiftpm/xcode/xcshareddata/xcschemes/NBKFlexibleWidthKit.xcscheme

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1430"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "NBKFlexibleWidthKit"
+               BuildableName = "NBKFlexibleWidthKit"
+               BlueprintName = "NBKFlexibleWidthKit"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:.swiftpm/NBKFlexibleWidthKit.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "NBKFlexibleWidthKit"
+            BuildableName = "NBKFlexibleWidthKit"
+            BlueprintName = "NBKFlexibleWidthKit"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

Package.swift

@@ -48,6 +48,12 @@ let package = Package(
         .library(
         name: "NBKDoubleWidthKit",
         targets: ["NBKDoubleWidthKit"]),
+        //=--------------------------------------=
+        // NBK x Flexible Width Kit
+        //=--------------------------------------=
+        .library(
+        name: "NBKFlexibleWidthKit",
+        targets: ["NBKFlexibleWidthKit"]),
     ],
     targets: [
         //=--------------------------------------=
@@ -84,6 +90,20 @@ let package = Package(
         .testTarget(
         name: "NBKDoubleWidthKitTests",
         dependencies: ["NBKDoubleWidthKit"]),
+        //=--------------------------------------=
+        // NBK x Flexible Width Kit
+        //=--------------------------------------=
+        .target(
+        name: "NBKFlexibleWidthKit",
+        dependencies: ["NBKCoreKit"]),
+
+        .testTarget(
+        name: "NBKFlexibleWidthKitBenchmarks",
+        dependencies: ["NBKFlexibleWidthKit"]),
+
+        .testTarget(
+        name: "NBKFlexibleWidthKitTests",
+        dependencies: ["NBKFlexibleWidthKit"]),
     ]
 )
 

README.md

@@ -10,6 +10,7 @@
 
 * [NBKCoreKit](#nbkcorekit)
 * [NBKDoubleWidthKit](#nbkdoublewidthkit)
+* [NBKFlexibleWidthKit](#nbkflexiblewidthkit)
 * [Installation](#installation)
 * [Acknowledgements](#acknowledgements)
 
@@ -113,6 +114,43 @@ Int256(5) % Int(5), UInt256(5) % UInt(5)
 > [!NOTE]
 > You can use `StaticString` until `StaticBigInt` becomes available.
 
+<a name="nbkflexiblewidthkit"/>
+
+## [NBKFlexibleWidthKit][FLX/D] ([Sources][FLX/S], [Tests][FLX/T], [Benchmarks][FLX/B])
+
+> [!IMPORTANT]
+> It's a work in progress. I may rework it at any time.
+
+### Models
+
+- [NBKFibonacciXL](Sources/NBKFlexibleWidthKit/Models/NBKFibonacciXL.swift)
+- [UIntXL](Sources/NBKFlexibleWidthKit/Models/NBKFlexibleWidth.swift)
+
+### Fibonacci
+
+```swift
+NBKFibonacciXL(0) // (index: 0, element: 0, next: 1)
+NBKFibonacciXL(1) // (index: 1, element: 1, next: 1)
+NBKFibonacciXL(2) // (index: 2, element: 1, next: 2)
+NBKFibonacciXL(3) // (index: 3, element: 2, next: 3)
+NBKFibonacciXL(4) // (index: 4, element: 3, next: 5)
+NBKFibonacciXL(5) // (index: 5, element: 5, next: 8)
+```
+
+It uses a fast double-and-add algorithm:
+
+```swift
+NBKFibonacciXL(10_000_000) // 2.3s on M1 MacBook Pro
+```
+
+But you can also step through it manually:
+
+```swift
+public mutating func increment() { ... } // index + 1
+public mutating func decrement() { ... } // index - 1
+public mutating func    double() { ... } // index * 2
+```
+
 <a name="installation"/>
 
 ## Installation
@@ -138,9 +176,10 @@ Add this package to your list of package dependencies.
 Choose target dependencies from the products in [Package.swift](Package.swift).
 
 ```swift
-.product(name: "Numberick",         package: "Numberick"),
-.product(name: "NBKCoreKit",        package: "Numberick"),
-.product(name: "NBKDoubleWidthKit", package: "Numberick"),
+.product(name: "Numberick",           package: "Numberick"),
+.product(name: "NBKCoreKit",          package: "Numberick"),
+.product(name: "NBKDoubleWidthKit",   package: "Numberick"),
+.product(name: "NBKFlexibleWidthKit", package: "Numberick"),
 ```
 
 ### Using [CocoaPods](http://cocoapods.org)
@@ -163,15 +202,20 @@ This project is inspired by [**Int128**][Apple/Int128] and [**DoubleWidth**][App
 
 [NBK/D]: https://oscbyspro.github.io/Numberick/documentation/numberick
 [DBL/D]: https://oscbyspro.github.io/Numberick/documentation/numberick/nbkdoublewidth
+[FLX/D]: https://oscbyspro.github.io/Numberick/documentation/numberick/nbkflexiblewidth
+[SIG/D]: https://oscbyspro.github.io/Numberick/documentation/numberick/nbksigned
 
 [COR/S]: Sources/NBKCoreKit
 [DBL/S]: Sources/NBKDoubleWidthKit
+[FLX/S]: Sources/NBKFlexibleWidthKit
 
 [COR/T]: Tests/NBKCoreKitTests
 [DBL/T]: Tests/NBKDoubleWidthKitTests
+[FLX/T]: Tests/NBKFlexibleWidthKitTests
 
 [COR/B]: Tests/NBKCoreKitBenchmarks
 [DBL/B]: Tests/NBKDoubleWidthKitBenchmarks
+[FLX/B]: Tests/NBKFlexibleWidthKitBenchmarks
 
 <!-- Links x Miscellaneous -->
 

Sources/NBKCoreKit/Models/NBKPrimeSieve.swift

@@ -717,7 +717,7 @@ extension NBKPrimeSieve {
         ///     5) [6A, 6B, 2A, 6D, 6E, 2B] // 6B, 6E
         ///     6) [6A, 6B, 6C, 6D, 6E, 6F] // 6C, 6F
         ///
-        /// The idea is to reuse words and subsequences whenever possible.
+        /// The idea is to reuse elements and subsequences whenever possible.
         ///
         /// - Important: The sieve culls even numbers by omission, so start with `[3,5]`.
         ///
@@ -736,7 +736,7 @@ extension NBKPrimeSieve {
                         patternIndex.remainder &+= current.prime
                     };  chunk.formOnesComplement()
                     //=--------------------------=
-                    // pattern: reuse words
+                    // pattern: reuse elements
                     //=--------------------------=
                     var ((destination)) = patternIndex.quotient
                     while destination < current.product {