Skip to content

Commit 5750897

Browse files
stephentyronestephentyrone
authored
Merge pull request #228 from markuswntr/quaternion/sync
Sync latest package changes with `Quaternions` branch
2 parents 3aaab70 + 4f97344 commit 5750897

File tree

67 files changed

+4417
-1587
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+4417
-1587
lines changed

‎.github/workflows/macos.yml

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎.xcodesamplecode.plist

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎Package.swift

Lines changed: 87 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
// swift-tools-version:5.0
1+
// swift-tools-version:5.4
22
//===--- Package.swift ----------------------------------------*- swift -*-===//
33
//
44
// This source file is part of the Swift Numerics open source project
55
//
6-
// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
6+
// Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
77
// Licensed under Apache License v2.0 with Runtime Library Exception
88
//
99
// See https://swift.org/LICENSE.txt for license information
@@ -12,6 +12,8 @@
1212

1313
import PackageDescription
1414

15+
let excludedFilenames = ["CMakeLists.txt", "README.md"]
16+
1517
let package = Package(
1618

1719
name: "swift-numerics",
@@ -23,23 +25,88 @@ let package = Package(
2325
],
2426

2527
targets: [
26-
// User-facing modules
27-
.target(name: "ComplexModule", dependencies: ["RealModule"]),
28-
.target(name: "Numerics", dependencies: ["ComplexModule", "QuaternionModule", "RealModule"]),
29-
.target(name: "QuaternionModule", dependencies: ["RealModule"]),
30-
.target(name: "RealModule", dependencies: ["_NumericsShims"]),
31-
32-
// Implementation details
33-
.target(name: "_NumericsShims", dependencies: []),
34-
.target(name: "_TestSupport", dependencies: ["Numerics"]),
35-
36-
// Unit test bundles
37-
.testTarget(name: "ComplexTests", dependencies: ["_TestSupport"]),
38-
.testTarget(name: "QuaternionTests", dependencies: ["_TestSupport"]),
39-
.testTarget(name: "RealTests", dependencies: ["_TestSupport"]),
40-
41-
// Test executables
42-
.target(name: "ComplexLog", dependencies: ["Numerics", "_TestSupport"], path: "Tests/Executable/ComplexLog"),
43-
.target(name: "ComplexLog1p", dependencies: ["Numerics", "_TestSupport"], path: "Tests/Executable/ComplexLog1p")
28+
// MARK: - Public API
29+
.target(
30+
name: "ComplexModule",
31+
dependencies: ["RealModule"],
32+
exclude: excludedFilenames
33+
),
34+
35+
.target(
36+
name: "IntegerUtilities",
37+
dependencies: [],
38+
exclude: excludedFilenames
39+
),
40+
41+
.target(
42+
name: "Numerics",
43+
dependencies: [
44+
"ComplexModule", "IntegerUtilities",
45+
"QuaternionModule", "RealModule"
46+
],
47+
exclude: excludedFilenames
48+
),
49+
50+
.target(
51+
name: "QuaternionModule",
52+
dependencies: ["RealModule"],
53+
exclude: ["README.md", "Transformation.md"]
54+
),
55+
56+
.target(
57+
name: "RealModule",
58+
dependencies: ["_NumericsShims"],
59+
exclude: excludedFilenames
60+
),
61+
62+
// MARK: - Implementation details
63+
.target(
64+
name: "_NumericsShims",
65+
exclude: excludedFilenames,
66+
linkerSettings: [.linkedLibrary("m", .when(platforms: [.linux, .android]))]
67+
),
68+
69+
.target(
70+
name: "_TestSupport",
71+
dependencies: ["Numerics"],
72+
exclude: ["CMakeLists.txt"]
73+
),
74+
75+
// MARK: - Unit test bundles
76+
.testTarget(
77+
name: "ComplexTests",
78+
dependencies: ["_TestSupport"],
79+
exclude: ["CMakeLists.txt"]
80+
),
81+
82+
.testTarget(
83+
name: "IntegerUtilitiesTests",
84+
dependencies: ["IntegerUtilities", "_TestSupport"],
85+
exclude: ["CMakeLists.txt"]
86+
),
87+
88+
.testTarget(
89+
name: "QuaternionTests",
90+
dependencies: ["_TestSupport"]
91+
),
92+
93+
.testTarget(
94+
name: "RealTests",
95+
dependencies: ["_TestSupport"],
96+
exclude: ["CMakeLists.txt"]
97+
),
98+
99+
// MARK: - Test executables
100+
.executableTarget(
101+
name: "ComplexLog",
102+
dependencies: ["Numerics", "_TestSupport"],
103+
path: "Tests/Executable/ComplexLog"
104+
),
105+
106+
.executableTarget(
107+
name: "ComplexLog1p",
108+
dependencies: ["Numerics", "_TestSupport"],
109+
path: "Tests/Executable/ComplexLog1p"
110+
)
44111
]
45112
)

‎README.md

Lines changed: 43 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ These modules fall broadly into two categories:
1111
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.
1212

1313
Swift Numerics modules are fine-grained.
14-
For example, if you need support for Complex numbers, you can import ComplexModule¹ as a standalone module:
14+
For example, if you need support for Complex numbers, you can import ComplexModule[^1] as a standalone module:
1515

1616
```swift
1717
import ComplexModule
@@ -42,7 +42,7 @@ To use Swift Numerics in a SwiftPM project:
4242
1. Add the following line to the dependencies in your `Package.swift` file:
4343

4444
```swift
45-
.package(url: "https://github.com/apple/swift-numerics", from: "0.0.7"),
45+
.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
4646
```
4747

4848
2. Add `Numerics` as a dependency for your target:
@@ -56,6 +56,22 @@ To use Swift Numerics in a SwiftPM project:
5656

5757
3. Add `import Numerics` in your source code.
5858

59+
## Source stability
60+
61+
The Swift Numerics package is source stable; version numbers follow [Semantic Versioning](https://semver.org).
62+
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.
63+
Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
64+
65+
Note that contents of the `_NumericsShims` and `_TestSupport` modules, as well as contents of the `Tests` directory, explicitly are not public API.
66+
The definitions therein may therefore change at whim, and the entire module may be removed in any new release.
67+
If you have a use case that requires underscored operations, please raise an issue to request that they be made public API.
68+
69+
Future minor versions of the package may introduce changes to these rules as needed.
70+
71+
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.
72+
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.
73+
Requiring a new Swift release will only require a minor version bump.
74+
5975
## Contributing to Swift Numerics
6076

6177
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
89105

90106
1. [`RealModule`](Sources/RealModule/README.md)
91107
2. [`ComplexModule`](Sources/ComplexModule/README.md)
92-
3. [`QuaternionModule`](Sources/QuaternionModule/README.md)
108+
3. [`IntegerUtilities`](Sources/IntegerUtilties/README.md) (on main only, not yet present in a released tag)
109+
4. [`QuaternionModule`](Sources/QuaternionModule/README.md)
93110

94111
## Future expansion
95112

@@ -98,28 +115,26 @@ Questions about how to use Swift Numerics modules, or issues that are not clearl
98115
3. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6)
99116
4. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7)
100117

101-
## Notes
102-
103-
¹ 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).
104-
This would prevent users of Swift Numerics who don't need generic types from doing things such as:
105-
106-
```swift
107-
import Complex
108-
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
109-
typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.
110-
```
111-
112-
For this reason, modules that would have this ambiguity are suffixed with `Module` within Swift Numerics:
113-
114-
```swift
115-
import ComplexModule
116-
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
117-
typealias Complex = ComplexModule.Complex<Double>
118-
// But I can still refer to the generic type by qualifying the name if I need it occasionally:
119-
let a = ComplexModule.Complex<Float>
120-
```
121-
122-
The `Real` module does not contain a `Real` type, but does contain a `Real` protocol.
123-
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.
124-
New modules have to evaluate this decision carefully, but can err on the side of adding the suffix.
125-
It's expected that most users will simply `import Numerics`, so this isn't an issue for them.
118+
[^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).
119+
This would prevent users of Swift Numerics who don't need generic types from doing things such as:
120+
121+
```swift
122+
import Complex
123+
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
124+
typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.
125+
```
126+
127+
For this reason, modules that would have this ambiguity are suffixed with `Module` within Swift Numerics:
128+
129+
```swift
130+
import ComplexModule
131+
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
132+
typealias Complex = ComplexModule.Complex<Double>
133+
// But I can still refer to the generic type by qualifying the name if I need it occasionally:
134+
let a = ComplexModule.Complex<Float>
135+
```
136+
137+
The `Real` module does not contain a `Real` type, but does contain a `Real` protocol.
138+
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.
139+
New modules have to evaluate this decision carefully, but can err on the side of adding the suffix.
140+
It's expected that most users will simply `import Numerics`, so this isn't an issue for them.

‎Sources/CMakeLists.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
#[[
22
This source file is part of the Swift Numerics open source project
33
4-
Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors
4+
Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
55
Licensed under Apache License v2.0 with Runtime Library Exception
66
77
See https://swift.org/LICENSE.txt for license information
88
#]]
99

1010
add_subdirectory(_NumericsShims)
1111
add_subdirectory(ComplexModule)
12+
add_subdirectory(IntegerUtilities)
1213
add_subdirectory(Numerics)
1314
add_subdirectory(RealModule)
1415
if(BUILD_TESTING)

‎Sources/ComplexModule/CMakeLists.txt

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,17 @@ See https://swift.org/LICENSE.txt for license information
88
#]]
99

1010
add_library(ComplexModule
11-
Arithmetic.swift
1211
Complex.swift
13-
Differentiable.swift
14-
ElementaryFunctions.swift)
12+
Complex+AdditiveArithmetic.swift
13+
Complex+AlgebraicField.swift
14+
Complex+Codable.swift
15+
Complex+ElementaryFunctions.swift
16+
Complex+Hashable.swift
17+
Complex+IntegerLiteral.swift
18+
Complex+Numeric.swift
19+
Complex+StringConvertible.swift
20+
Polar.swift
21+
Scale.swift)
1522
set_target_properties(ComplexModule PROPERTIES
1623
INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_Swift_MODULE_DIRECTORY})
1724
target_link_libraries(ComplexModule PUBLIC

‎Sources/ComplexModule/Complex+AdditiveArithmetic.swift

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
//===--- Complex+AdditiveArithmetic.swift ---------------------*- swift -*-===//
2+
//
3+
// This source file is part of the Swift Numerics open source project
4+
//
5+
// Copyright (c) 2019-2021 Apple Inc. and the Swift Numerics project authors
6+
// Licensed under Apache License v2.0 with Runtime Library Exception
7+
//
8+
// See https://swift.org/LICENSE.txt for license information
9+
//
10+
//===----------------------------------------------------------------------===//
11+
12+
import RealModule
13+
14+
extension Complex: AdditiveArithmetic {
15+
/// The additive identity, with real and imaginary parts both zero.
16+
///
17+
/// See also: `one`, `i`, `infinity`
18+
@_transparent
19+
public static var zero: Complex {
20+
Complex(0, 0)
21+
}
22+
23+
@_transparent
24+
public static func +(z: Complex, w: Complex) -> Complex {
25+
return Complex(z.x + w.x, z.y + w.y)
26+
}
27+
28+
@_transparent
29+
public static func -(z: Complex, w: Complex) -> Complex {
30+
return Complex(z.x - w.x, z.y - w.y)
31+
}
32+
33+
@_transparent
34+
public static func +=(z: inout Complex, w: Complex) {
35+
z = z + w
36+
}
37+
38+
@_transparent
39+
public static func -=(z: inout Complex, w: Complex) {
40+
z = z - w
41+
}
42+
}

0 commit comments

Comments
 (0)