diff --git a/Package.swift b/Package.swift index f91f4414..566bf44e 100644 --- a/Package.swift +++ b/Package.swift @@ -15,19 +15,19 @@ import PackageDescription let package = Package( name: "swift-numerics", products: [ - .library(name: "Complex", targets: ["Complex"]), + .library(name: "ComplexModule", targets: ["ComplexModule"]), .library(name: "Numerics", targets: ["Numerics"]), - .library(name: "Real", targets: ["Real"]), + .library(name: "RealModule", targets: ["RealModule"]), ], dependencies: [ ], targets: [ - .target(name: "Complex", dependencies: ["Real"]), - .target(name: "Numerics", dependencies: ["Complex", "Real"]), - .target(name: "NumericsShims", dependencies: []), - .target(name: "Real", dependencies: ["NumericsShims"]), + .target(name: "ComplexModule", dependencies: ["RealModule"]), + .target(name: "Numerics", dependencies: ["ComplexModule", "RealModule"]), + .target(name: "_NumericsShims", dependencies: []), + .target(name: "RealModule", dependencies: ["_NumericsShims"]), - .testTarget(name: "ComplexTests", dependencies: ["Complex", "NumericsShims"]), - .testTarget(name: "RealTests", dependencies: ["Real"]), + .testTarget(name: "ComplexTests", dependencies: ["ComplexModule", "_NumericsShims"]), + .testTarget(name: "RealTests", dependencies: ["RealModule"]), ] ) diff --git a/README.md b/README.md index 28848e31..1f166c06 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ These modules fall broadly into two categories: There is some overlap between these two categories, and API that begins in the first category may migrate to the second as it matures and new uses are discovered. -Swift Numerics modules are fine-grained; if you need support for Complex numbers, you can import the Complex module without pulling in everything else in the library as well: +Swift Numerics modules are fine-grained; if you need support for Complex numbers, you can import ComplexModule[1](#foot1) without pulling in everything else in the library as well: ```swift -import Complex +import ComplexModule let z = Complex.i ``` @@ -51,8 +51,8 @@ To fix a bug, or make smaller improvements: Questions about how to use Swift Numerics modules, or issues that are not clearly bugs can be discussed in the ["Swift Numerics" section of the Swift forums.](https://forums.swift.org/c/related-projects/swift-numerics) ## Modules -1. [Real](Sources/Real/README.md) -2. [Complex](Sources/Complex/README.md) +1. [RealModule](Sources/RealModule/README.md) +2. [ComplexModule](Sources/ComplexModule/README.md) ## Future expansion 1. [Approximate Equality](https://github.com/apple/swift-numerics/issues/3) @@ -60,4 +60,23 @@ Questions about how to use Swift Numerics modules, or issues that are not clearl 3. [Arbitrary-Precision Integers](https://github.com/apple/swift-numerics/issues/5) 4. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6) 5. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7) -6. [Float16](https://github.com/apple/swift-numerics/issues/8) + +## Notes +[1](#back1) 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 like: +```swift +import Complex +// I know I only ever want Complex, so I shouldn't need the generic parameter. +typealias Complex = Complex.Complex // 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, so I shouldn't need the generic parameter. +typealias Complex = ComplexModule.Complex +// But I can still refer to the generic type by qualifying the name if I need it occasionally: +let a = ComplexModule.Complex +``` +The `Real` module does not contain a `Real` type, but does contain a `Real` protocol, and users may want to define their own `Real` type (and possibly re-export the `Real` module), so 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. diff --git a/Sources/Complex/Arithmetic.swift b/Sources/ComplexModule/Arithmetic.swift similarity index 99% rename from Sources/Complex/Arithmetic.swift rename to Sources/ComplexModule/Arithmetic.swift index 654f9b89..c08b4cf9 100644 --- a/Sources/Complex/Arithmetic.swift +++ b/Sources/ComplexModule/Arithmetic.swift @@ -9,7 +9,7 @@ // //===----------------------------------------------------------------------===// -import Real +import RealModule // MARK: - Additive structure extension Complex: AdditiveArithmetic { diff --git a/Sources/Complex/Complex.swift b/Sources/ComplexModule/Complex.swift similarity index 99% rename from Sources/Complex/Complex.swift rename to Sources/ComplexModule/Complex.swift index 00fe5ca0..eb235997 100644 --- a/Sources/Complex/Complex.swift +++ b/Sources/ComplexModule/Complex.swift @@ -9,7 +9,7 @@ // //===----------------------------------------------------------------------===// -import Real +import RealModule /// A complex number represented by real and imaginary parts. /// diff --git a/Sources/Complex/README.md b/Sources/ComplexModule/README.md similarity index 99% rename from Sources/Complex/README.md rename to Sources/ComplexModule/README.md index 3c9dc0c4..a8b33700 100644 --- a/Sources/Complex/README.md +++ b/Sources/ComplexModule/README.md @@ -2,7 +2,7 @@ This module provides a `Complex` number type generic over an underlying `RealType`: ```swift -1> import Complex +1> import ComplexModule 2> let z = Complex(1,1) // z = 1 + i ``` This module provides approximate feature parity and memory layout compatibility with C, Fortran, and C++ complex types (although the importer cannot map the types for you, buffers may be reinterpreted to shim API defined in other languages). @@ -10,7 +10,7 @@ This module provides approximate feature parity and memory layout compatibility The usual arithmetic operators are provided for Complex numbers, as well as conversion to and from polar coordinates and many useful properties, plus conformances to the obvious usual protocols: `Equatable`, `Hashable`, `Codable` (if the underlying `RealType` is), and `AlgebraicField` (hence also `AdditiveArithmetic` and `SignedNumeric`). ### Dependencies: -- The `Real` module. +- `RealModule`. ## Design notes diff --git a/Sources/Numerics/Numerics.swift b/Sources/Numerics/Numerics.swift index 72e83f17..360ba9a3 100644 --- a/Sources/Numerics/Numerics.swift +++ b/Sources/Numerics/Numerics.swift @@ -10,5 +10,5 @@ //===----------------------------------------------------------------------===// // A module that re-exports the complete Swift Numerics public API. -@_exported import Real -@_exported import Complex +@_exported import RealModule +@_exported import ComplexModule diff --git a/Sources/Real/AlgebraicField.swift b/Sources/RealModule/AlgebraicField.swift similarity index 100% rename from Sources/Real/AlgebraicField.swift rename to Sources/RealModule/AlgebraicField.swift diff --git a/Sources/Real/Double+Real.swift b/Sources/RealModule/Double+Real.swift similarity index 99% rename from Sources/Real/Double+Real.swift rename to Sources/RealModule/Double+Real.swift index addf1e65..05e44e92 100644 --- a/Sources/Real/Double+Real.swift +++ b/Sources/RealModule/Double+Real.swift @@ -9,7 +9,7 @@ // //===----------------------------------------------------------------------===// -import NumericsShims +import _NumericsShims extension Double: Real { @_transparent diff --git a/Sources/Real/ElementaryFunctions.swift b/Sources/RealModule/ElementaryFunctions.swift similarity index 100% rename from Sources/Real/ElementaryFunctions.swift rename to Sources/RealModule/ElementaryFunctions.swift diff --git a/Sources/Real/Float+Real.swift b/Sources/RealModule/Float+Real.swift similarity index 99% rename from Sources/Real/Float+Real.swift rename to Sources/RealModule/Float+Real.swift index 04dfd8f2..b5df21ff 100644 --- a/Sources/Real/Float+Real.swift +++ b/Sources/RealModule/Float+Real.swift @@ -9,7 +9,7 @@ // //===----------------------------------------------------------------------===// -import NumericsShims +import _NumericsShims extension Float: Real { @_transparent diff --git a/Sources/Real/Float80+Real.swift b/Sources/RealModule/Float80+Real.swift similarity index 99% rename from Sources/Real/Float80+Real.swift rename to Sources/RealModule/Float80+Real.swift index c3357343..9ae7e922 100644 --- a/Sources/Real/Float80+Real.swift +++ b/Sources/RealModule/Float80+Real.swift @@ -9,7 +9,7 @@ // //===----------------------------------------------------------------------===// -import NumericsShims +import _NumericsShims // Restrict extension to platforms for which Float80 exists. #if (arch(i386) || arch(x86_64)) && !os(Windows) && !os(Android) diff --git a/Sources/Real/README.md b/Sources/RealModule/README.md similarity index 91% rename from Sources/Real/README.md rename to Sources/RealModule/README.md index a4752edf..a77d6fec 100644 --- a/Sources/Real/README.md +++ b/Sources/RealModule/README.md @@ -1,8 +1,8 @@ -# Real +# Real Module [SE-0246] proposed an API for "basic math functions" that would make operations like sine and logarithm available in generic contexts. It was accepted, but because of limitations in the compiler, the API could not be added to the standard library in a source-stable manner. -The `Real` module provides that API as a separate module so that you can use it right away to get access to the improved API for these operations in your projects. +`RealModule` provides that API as a separate module so that you can use it right away to get access to the improved API for these operations in your projects. ## Protocols and Methods @@ -34,7 +34,7 @@ The primary use of this protocol is for writing code that is generic over real a ## Using Real -First, either import `Real` directly or import the `Numerics` umbrella module. +First, either import `RealModule` directly or import the `Numerics` umbrella module. Suppose we were experimenting with some basic machine learning, and needed a generic [sigmoid function][Sigmoid] activation function: @@ -69,7 +69,7 @@ When new basic floating-point types are added to Swift, like `Float16` or `Float Not having this protocol is a significant missing feature for numerical computing in Swift, and I'm really looking forward to seeing what people do with it. ### Dependencies: -- The C standard math library (`libm`) via the `NumericShims` target. +- The C standard math library (`libm`) via the `_NumericsShims` target. [ErrorFunction]: https://en.wikipedia.org/wiki/Error_function [GammaFunction]: https://en.wikipedia.org/wiki/Gamma_function diff --git a/Sources/Real/Real.swift b/Sources/RealModule/Real.swift similarity index 100% rename from Sources/Real/Real.swift rename to Sources/RealModule/Real.swift diff --git a/Sources/Real/RealFunctions.swift b/Sources/RealModule/RealFunctions.swift similarity index 100% rename from Sources/Real/RealFunctions.swift rename to Sources/RealModule/RealFunctions.swift diff --git a/Sources/NumericsShims/README.md b/Sources/_NumericsShims/README.md similarity index 100% rename from Sources/NumericsShims/README.md rename to Sources/_NumericsShims/README.md diff --git a/Sources/NumericsShims/NumericsShims.c b/Sources/_NumericsShims/_NumericsShims.c similarity index 96% rename from Sources/NumericsShims/NumericsShims.c rename to Sources/_NumericsShims/_NumericsShims.c index 40751743..8ac212f3 100644 --- a/Sources/NumericsShims/NumericsShims.c +++ b/Sources/_NumericsShims/_NumericsShims.c @@ -16,4 +16,4 @@ // If any shims are added that are not pure header inlines, whatever runtime // support they require can be added to this file. -#include "NumericsShims.h" +#include "_NumericsShims.h" diff --git a/Sources/NumericsShims/include/NumericsShims.h b/Sources/_NumericsShims/include/_NumericsShims.h similarity index 100% rename from Sources/NumericsShims/include/NumericsShims.h rename to Sources/_NumericsShims/include/_NumericsShims.h diff --git a/Tests/ComplexTests/ArithmeticBenchmarkTests.swift b/Tests/ComplexTests/ArithmeticBenchmarkTests.swift index 14f01b5d..6b2d94d2 100644 --- a/Tests/ComplexTests/ArithmeticBenchmarkTests.swift +++ b/Tests/ComplexTests/ArithmeticBenchmarkTests.swift @@ -10,10 +10,10 @@ //===----------------------------------------------------------------------===// import XCTest -import Complex +import ComplexModule // For CComplex and shims -import NumericsShims +import _NumericsShims extension Complex where RealType == Double { @_transparent diff --git a/Tests/ComplexTests/ArithmeticTests.swift b/Tests/ComplexTests/ArithmeticTests.swift index de4c7e8d..ba88d94c 100644 --- a/Tests/ComplexTests/ArithmeticTests.swift +++ b/Tests/ComplexTests/ArithmeticTests.swift @@ -10,8 +10,8 @@ //===----------------------------------------------------------------------===// import XCTest -import Complex -import Real +import ComplexModule +import RealModule // TODO: improve this to be a general-purpose complex comparison with tolerance func relativeError(_ a: Complex, _ b: Complex) -> T { diff --git a/Tests/ComplexTests/PropertyTests.swift b/Tests/ComplexTests/PropertyTests.swift index 6c21791a..ca371484 100644 --- a/Tests/ComplexTests/PropertyTests.swift +++ b/Tests/ComplexTests/PropertyTests.swift @@ -10,8 +10,8 @@ //===----------------------------------------------------------------------===// import XCTest -import Complex -import Real +import ComplexModule +import RealModule final class PropertyTests: XCTestCase { diff --git a/Tests/RealTests/IntegerExponentTests.swift b/Tests/RealTests/IntegerExponentTests.swift index b1ec3f97..0d8997b2 100644 --- a/Tests/RealTests/IntegerExponentTests.swift +++ b/Tests/RealTests/IntegerExponentTests.swift @@ -10,7 +10,7 @@ //===----------------------------------------------------------------------===// import XCTest -import Real +import RealModule internal extension Real where Self: BinaryFloatingPoint { static func testIntegerExponentCommon() { diff --git a/Tests/RealTests/RealTestSupport.swift b/Tests/RealTests/RealTestSupport.swift index 63edcd84..8296c430 100644 --- a/Tests/RealTests/RealTestSupport.swift +++ b/Tests/RealTests/RealTestSupport.swift @@ -10,7 +10,7 @@ //===----------------------------------------------------------------------===// import XCTest -import Real +import RealModule #if (arch(i386) || arch(x86_64)) && !os(Windows) && !os(Android) typealias TestLiteralType = Float80 diff --git a/Tests/RealTests/RealTests.swift b/Tests/RealTests/RealTests.swift index bd3a21d6..60afb5d8 100644 --- a/Tests/RealTests/RealTests.swift +++ b/Tests/RealTests/RealTests.swift @@ -10,7 +10,7 @@ //===----------------------------------------------------------------------===// import XCTest -import Real +import RealModule internal extension ElementaryFunctions where Self: BinaryFloatingPoint { static func elementaryFunctionChecks() {