Merge branch 'main' into quaternion/sync

# Conflicts:
#	Package.swift
#	README.md
#	Sources/Numerics/Numerics.swift

Author: markuswntr

.github/workflows/macos.yml

@@ -12,6 +12,8 @@
 
 import PackageDescription
 
+let excludedFilenames = ["CMakeLists.txt", "README.md"]
+
 let package = Package(
 
   name: "swift-numerics",
@@ -23,23 +25,87 @@ let package = Package(
   ],
 
   targets: [
-    // User-facing modules
-    .target(name: "ComplexModule", dependencies: ["RealModule"]),
-    .target(name: "Numerics", dependencies: ["ComplexModule", "QuaternionModule", "RealModule"]),
-    .target(name: "QuaternionModule", dependencies: ["RealModule"]),
-    .target(name: "RealModule", dependencies: ["_NumericsShims"]),
-    
-    // Implementation details
-    .target(name: "_NumericsShims", dependencies: []),
-    .target(name: "_TestSupport", dependencies: ["Numerics"]),
-    
-    // Unit test bundles
-    .testTarget(name: "ComplexTests", dependencies: ["_TestSupport"]),
-    .testTarget(name: "QuaternionTests", dependencies: ["_TestSupport"]),
-    .testTarget(name: "RealTests", dependencies: ["_TestSupport"]),
-    
-    // Test executables
-    .target(name: "ComplexLog", dependencies: ["Numerics", "_TestSupport"], path: "Tests/Executable/ComplexLog"),
-    .target(name: "ComplexLog1p", dependencies: ["Numerics", "_TestSupport"], path: "Tests/Executable/ComplexLog1p")
+    // MARK: - Public API
+    .target(
+      name: "ComplexModule",
+      dependencies: ["RealModule"],
+      exclude: excludedFilenames
+    ),
+    
+    .target(
+      name: "IntegerUtilities",
+      dependencies: [],
+      exclude: excludedFilenames
+    ),
+    
+    .target(
+      name: "Numerics",
+      dependencies: [
+        "ComplexModule", "IntegerUtilities",
+        "QuaternionModule", "RealModule"
+      ],
+      exclude: excludedFilenames
+    ),
+
+    .target(
+      name: "QuaternionModule",
+      dependencies: ["RealModule"]
+    ),
+    
+    .target(
+      name: "RealModule",
+      dependencies: ["_NumericsShims"],
+      exclude: excludedFilenames
+    ),
+    
+    // MARK: - Implementation details
+    .target(
+      name: "_NumericsShims",
+      dependencies: [],
+      exclude: excludedFilenames
+    ),
+    
+    .target(
+      name: "_TestSupport",
+      dependencies: ["Numerics"],
+      exclude: ["CMakeLists.txt"]
+    ),
+    
+    // MARK: - Unit test bundles
+    .testTarget(
+      name: "ComplexTests",
+      dependencies: ["_TestSupport"],
+      exclude: ["CMakeLists.txt"]
+    ),
+    
+    .testTarget(
+      name: "IntegerUtilitiesTests",
+      dependencies: ["IntegerUtilities"],
+      exclude: ["CMakeLists.txt"]
+    ),
+
+    .testTarget(
+      name: "QuaternionTests",
+      dependencies: ["_TestSupport"]
+    ),
+    
+    .testTarget(
+      name: "RealTests",
+      dependencies: ["_TestSupport"],
+      exclude: ["CMakeLists.txt"]
+    ),
+    
+    // MARK: - Test executables
+    .target(
+      name: "ComplexLog",
+      dependencies: ["Numerics", "_TestSupport"],
+      path: "Tests/Executable/ComplexLog"
+    ),
+    
+    .target(
+      name: "ComplexLog1p",
+      dependencies: ["Numerics", "_TestSupport"],
+      path: "Tests/Executable/ComplexLog1p"
+    )
   ]
 )

.xcodesamplecode.plist

@@ -11,7 +11,7 @@ These modules fall broadly into two categories:
 There is some overlap between these two categories, and an API that begins in the first category may migrate into the second as it matures and new uses are discovered.
 
 Swift Numerics modules are fine-grained.
-For example, if you need support for Complex numbers, you can import ComplexModule¹ as a standalone module:
+For example, if you need support for Complex numbers, you can import ComplexModule[^1] as a standalone module:
 
 ```swift
 import ComplexModule
@@ -42,7 +42,7 @@ To use Swift Numerics in a SwiftPM project:
 1. Add the following line to the dependencies in your `Package.swift` file:
 
 ```swift
-.package(url: "https://github.com/apple/swift-numerics", from: "0.0.7"),
+.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
 ```
 
 2. Add `Numerics` as a dependency for your target:
@@ -56,6 +56,22 @@ To use Swift Numerics in a SwiftPM project:
 
 3. Add `import Numerics` in your source code.
 
+## Source stability
+
+The Swift Numerics package is source stable; version numbers follow [Semantic Versioning](https://semver.org).
+The public API of the `swift-numerics` package consists of non-underscored declarations that are marked either `public` or `usableFromInline` in modules re-exported by the top-level `Numerics` module, *excepting any API that involves a conformance to Differentiable (because Differentiable itself is not stable in Swift)*.
+Interfaces that aren't part of the public API may continue to change in any release, including patch releases. 
+
+Note that contents of the `_NumericsShims` and `_TestSupport` modules, as well as contents of the `Tests` directory, explicitly are not public API.
+The definitions therein may therefore change at whim, and the entire module may be removed in any new release.
+If you have a use case that requires underscored operations, please raise an issue to request that they be made public API.
+
+Future minor versions of the package may introduce changes to these rules as needed.
+
+We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.
+Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release.
+Requiring a new Swift release will only require a minor version bump.
+
 ## Contributing to Swift Numerics
 
 Swift Numerics is a standalone library that is separate from the core Swift project, but it will sometimes act as a staging ground for APIs that will later be incorporated into the Swift Standard Library.
@@ -89,7 +105,8 @@ Questions about how to use Swift Numerics modules, or issues that are not clearl
 
 1. [`RealModule`](Sources/RealModule/README.md)
 2. [`ComplexModule`](Sources/ComplexModule/README.md)
-3. [`QuaternionModule`](Sources/QuaternionModule/README.md)
+3. [`IntegerUtilities`](Sources/IntegerUtilties/README.md) (on main only, not yet present in a released tag)
+4. [`QuaternionModule`](Sources/QuaternionModule/README.md)
 
 ## Future expansion
 
@@ -98,28 +115,26 @@ Questions about how to use Swift Numerics modules, or issues that are not clearl
 3. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6)
 4. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7)
 
-## Notes
-
-¹ Swift is currently unable to use the fully-qualified name for types when a type and module have the same name (discussion here: https://forums.swift.org/t/pitch-fully-qualified-name-syntax/28482).
-This would prevent users of Swift Numerics who don't need generic types from doing things such as:
-
-```swift
-import Complex
-// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
-typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.
-```
-
-For this reason, modules that would have this ambiguity are suffixed with `Module` within Swift Numerics:
-
-```swift
-import ComplexModule
-// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
-typealias Complex = ComplexModule.Complex<Double>
-// But I can still refer to the generic type by qualifying the name if I need it occasionally:
-let a = ComplexModule.Complex<Float>
-```
-
-The `Real` module does not contain a `Real` type, but does contain a `Real` protocol.
-Users may want to define their own `Real` type (and possibly re-export the `Real` module)--that is why the suffix is also applied there.
-New modules have to evaluate this decision carefully, but can err on the side of adding the suffix.
-It's expected that most users will simply `import Numerics`, so this isn't an issue for them.
+[^1]: The module is named `ComplexModule` instead of `Complex` because Swift is currently unable to use the fully-qualified name for types when a type and module have the same name (discussion here: https://forums.swift.org/t/pitch-fully-qualified-name-syntax/28482).
+    This would prevent users of Swift Numerics who don't need generic types from doing things such as:
+
+    ```swift
+    import Complex
+    // I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
+    typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.
+    ```
+    
+    For this reason, modules that would have this ambiguity are suffixed with `Module` within Swift Numerics:
+    
+    ```swift
+    import ComplexModule
+    // I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
+    typealias Complex = ComplexModule.Complex<Double>
+    // But I can still refer to the generic type by qualifying the name if I need it occasionally:
+    let a = ComplexModule.Complex<Float>
+    ```
+
+    The `Real` module does not contain a `Real` type, but does contain a `Real` protocol.
+    Users may want to define their own `Real` type (and possibly re-export the `Real` module)--that is why the suffix is also applied there.
+    New modules have to evaluate this decision carefully, but can err on the side of adding the suffix.
+    It's expected that most users will simply `import Numerics`, so this isn't an issue for them.

Package.swift

@@ -1,14 +1,15 @@
 #[[
 This source file is part of the Swift Numerics open source project
 
-Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
+Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
 Licensed under Apache License v2.0 with Runtime Library Exception
 
 See https://swift.org/LICENSE.txt for license information
 #]]
 
 add_subdirectory(_NumericsShims)
 add_subdirectory(ComplexModule)
+add_subdirectory(IntegerUtilities)
 add_subdirectory(Numerics)
 add_subdirectory(RealModule)
 if(BUILD_TESTING)

README.md

@@ -52,13 +52,31 @@ extension Complex: AdditiveArithmetic {
 // and turn these into operators if/when we have it.
 // (https://github.com/apple/swift-numerics/issues/12)
 extension Complex {
+  /// `self` scaled by `a`.
   @usableFromInline @_transparent
   internal func multiplied(by a: RealType) -> Complex {
+    // This can be viewed in two different ways, which are mathematically
+    // equivalent: either we are computing `self * Complex(a)` (i.e.
+    // converting `a` to be a complex value, and then using the complex
+    // multiplication) or we are using the scalar product of the vector
+    // space structure: `Complex(a*real, a*imaginary)`.
+    //
+    // Although these two interpretations are _mathematically_ equivalent,
+    // they will generate different representations of the point at
+    // infinity in general. For example, suppose `self` is represented by
+    // `(infinity, 0)`. Then `self * Complex(1)` would evaluate as
+    // `(1*infinity - 0*0, 0*infinity + 1*0) = (infinity, nan)`, but
+    // the vector space interpretation produces `(infinity, 0)`. This does
+    // not matter much, because these are two representations of the same
+    // semantic value, but note that one requires four multiplies and two
+    // additions, while the one we use requires only two real multiplications.
     Complex(x*a, y*a)
   }
 
+  /// `self` unscaled by `a`.
   @usableFromInline @_transparent
   internal func divided(by a: RealType) -> Complex {
+    // See implementation notes for `multiplied` above.
     Complex(x/a, y/a)
   }
 }
@@ -126,8 +144,8 @@ extension Complex: AlgebraicField {
 
   /// A normalized complex number with the same phase as this value.
   ///
-  /// If such a value cannot be produced (because the phase of zero and infinity is undefined),
-  /// `nil` is returned.
+  /// If such a value cannot be produced (because the phase of zero and
+  /// infinity is undefined), `nil` is returned.
   @inlinable
   public var normalized: Complex? {
     if length.isNormal {
@@ -139,23 +157,31 @@ extension Complex: AlgebraicField {
     return self.divided(by: magnitude).normalized
   }
 
-  /// The reciprocal of this value, if it can be computed without undue overflow or underflow.
+  /// The reciprocal of this value, if it can be computed without undue
+  /// overflow or underflow.
   ///
-  /// If z.reciprocal is non-nil, you can safely replace division by z with multiplication by this value. It is
-  /// not advantageous to do this for an isolated division, but if you are dividing many values by a single
+  /// If z.reciprocal is non-nil, you can safely replace division by z with
+  /// multiplication by this value. It is not advantageous to do this for an
+  /// isolated division, but if you are dividing many values by a single
   /// denominator, this will often be a significant performance win.
   ///
-  /// Typical use looks like this:
+  /// A typical use case looks something like this:
   /// ```
   /// func divide<T: Real>(data: [Complex<T>], by divisor: Complex<T>) -> [Complex<T>] {
-  ///   // If divisor is well-scaled, use multiply by reciprocal.
+  ///   // If divisor is well-scaled, multiply by reciprocal.
   ///   if let recip = divisor.reciprocal {
   ///     return data.map { $0 * recip }
   ///   }
   ///   // Fallback on using division.
   ///   return data.map { $0 / divisor }
   /// }
   /// ```
+  ///
+  /// Error Bounds:
+  /// -
+  /// Unlike real types, when working with complex types, multiplying by the
+  /// reciprocal instead of dividing cannot change the result. If the
+  /// reciprocal is non-nil, the two computations are always equivalent.
   @inlinable
   public var reciprocal: Complex? {
     let recip = 1/self