Further docc improvements for RealModule.

This commit _also_ relaxes the constraint on Augmented algorithms from Real to FloatingPoint. It's worth calling out that fastTwoSum does not work with decimal floating-point types, so the unordered `Augemented.sum(_:_:)` now has a radix check and calls into the ordered twoSum function instead for Decimal. This makes more sense that a `BinaryFloatingPoint` constraint, as otherwise generic code written against Real or FloatingPoint would have to do the check at every call site.
This commit is contained in:
Stephen Canon committed 2025-08-13 12:38:56 -04:00
1 parent 2c19b7b8cd
commit aa901641d1
10 files changed
+222 -137

No files matched your search

+7 -6
View File
@@ -2,7 +2,7 @@
//
// 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-2025 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
@@ -32,12 +32,13 @@
/// Because integer multiplication does not form a group; it's commutative and
/// associative, but integers do not have multiplicative inverses.
/// I.e. if a is any integer other than 1 or -1, there is no integer b such
/// that a*b = 1. The existence of inverses is requried to form a field.
/// that `a*b = 1`. The existence of inverses is requried to form a field.
///
/// If a type `T` conforms to the `Real` protocol, then `T` and `Complex<T>`
/// If a type `T` conforms to the ``Real`` protocol, then `T` and ``Complex<T>``
/// both conform to `AlgebraicField`.
///
/// See also `Real`, `SignedNumeric`, `Numeric` and `AdditiveArithmetic`.
/// See also Swift's `SignedNumeric`, `Numeric` and `AdditiveArithmetic`
/// protocols.
///
/// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
public protocol AlgebraicField: SignedNumeric where Magnitude: AlgebraicField {
@@ -90,10 +91,10 @@ public protocol AlgebraicField: SignedNumeric where Magnitude: AlgebraicField {
/// ```
var reciprocal: Self? { get }
/// a + b, with the optimizer licensed to reassociate and form FMAs.
/// `a + b`, with the optimizer licensed to reassociate and form FMAs.
static func _relaxedAdd(_ a: Self, _ b: Self) -> Self
/// a * b, with the optimizer licensed to reassociate and form FMAs.
/// `a * b`, with the optimizer licensed to reassociate and form FMAs.
static func _relaxedMul(_ a: Self, _ b: Self) -> Self
}
+2 -8
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2020-2025 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
@@ -218,7 +218,7 @@ extension AdditiveArithmetic {
/// norm: \.length
/// )
/// ```
/// (if we used the default norm, `.magnitude`, we would be testing if
/// (if we used the default norm, `\.magnitude`, we would be testing if
/// `z` were inside a square region instead.)
@inlinable
public func isApproximatelyEqual<Magnitude>(
@@ -227,12 +227,6 @@ extension AdditiveArithmetic {
relativeTolerance: Magnitude = 0,
norm: (Self) -> Magnitude
) -> Bool
// TODO: constraint should really be weaker than FloatingPoint,
// but we need to have `isFinite` for it to work correctly with
// floating-point magnitudes in generic contexts, which is the
// most common case. The fix for this is to lift the isFinite
// requirement to Numeric in the standard library, but that's
// source-breaking, so requires an ABI rumspringa.
where Magnitude: FloatingPoint {
assert(
absoluteTolerance >= 0 && absoluteTolerance.isFinite,
+25 -11
View File
@@ -2,14 +2,13 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2020-2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2020-2025 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
//
//===----------------------------------------------------------------------===//
/// Namespace for augmented arithmetic operations.
public enum Augmented { }
extension Augmented {
@@ -40,7 +39,9 @@ extension Augmented {
/// - If both `head` and `tail` are normal, then `a * b` is exactly
/// equal to `head + tail` when computed as real numbers.
@_transparent
public static func product<T:Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
public static func product<T:FloatingPoint>(
_ a: T, _ b: T
) -> (head: T, tail: T) {
let head = a*b
// TODO: consider providing an FMA-less implementation for use when
// targeting platforms without hardware FMA support. This works everywhere,
@@ -59,11 +60,6 @@ extension Augmented {
/// error from that computation rounded to the closest representable
/// value.
///
/// Unlike `Augmented.product(a, b)`, the rounding error of a sum can
/// never underflow.
///
/// This operation is sometimes called ["fastTwoSum"].
///
/// > Note:
/// > `tail` is guaranteed to be the best approximation to the error of
/// the sum only if `large.magnitude` >= `small.magnitude`. If this is
@@ -72,6 +68,15 @@ extension Augmented {
/// how the magnitudes of `a` and `b` compare, you likely want to use
/// ``sum(_:_:)`` instead.
///
/// Unlike ``product(_:_:)``, the rounding error of `sum` never underflows.
///
/// This operation is sometimes called ["fastTwoSum"].
///
/// > Note:
/// > Classical fastTwoSum does not work when `radix` is 10. This function
/// will fall back on another algorithm for decimal floating-point types
/// to ensure correct results.
///
/// Edge Cases:
///
/// - `head` is always the IEEE 754 sum `a + b`.
@@ -85,7 +90,14 @@ extension Augmented {
///
/// ["fastTwoSum"]: https://en.wikipedia.org/wiki/2Sum
@_transparent
public static func sum<T:Real>(large a: T, small b: T) -> (head: T, tail: T) {
public static func sum<T: FloatingPoint>(
large a: T, small b: T
) -> (head: T, tail: T) {
// Fall back on 2Sum if radix != 2. Future implementations might use an
// cheaper algorithm specialized for decimal FP, but must deliver a
// correct result if the preconditions are satisfied.
guard T.radix == 2 else { return sum(a, b) }
// Fast2Sum:
let head = a + b
let tail = a - head + b
return (head, tail)
@@ -103,7 +115,7 @@ extension Augmented {
/// result somewhat more efficiently. If you do not have such a static
/// bound, you usually want to use this function instead.
///
/// Unlike ``product(_:_:)``, the rounding error of a sum never underflows.
/// Unlike ``product(_:_:)``, the rounding error of `sum` never underflows.
///
/// This operation is sometimes called ["twoSum"].
///
@@ -124,7 +136,9 @@ extension Augmented {
///
/// ["twoSum"]: https://en.wikipedia.org/wiki/2Sum
@_transparent
public static func sum<T: Real>(_ a: T, _ b: T) -> (head: T, tail: T) {
public static func sum<T: FloatingPoint>(
_ a: T, _ b: T
) -> (head: T, tail: T) {
let head = a + b
let x = head - b
let y = head - x
@@ -0,0 +1,68 @@
# ``ElementaryFunctions``
A type that has elementary functions (`sin`, `cos`, etc.) available.
## Overview
An ["elementary function"][elfn] is a function built up from powers, roots,
exponentials, logarithms, trigonometric functions (sin, cos, tan) and
their inverses, and the hyperbolic functions (sinh, cosh, tanh) and their
inverses.
Conformance to this protocol means that all of these building blocks are
available as static functions on the type.
```swift
let x: Float = 1
let y = Float.sin(x) // 0.84147096
```
`ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
and subtraction and the `zero` property are also available.
``RealFunctions`` refines this protocol and adds additional functions that
are primarily used with real numbers, such as ``RealFunctions/atan2(y:x:)``
and ``RealFunctions/exp10(_:)``.
``Real`` conforms to `RealFunctions` and `FloatingPoint`, and is the
protocol that you will use most often for generic code.
## Topics
There are a few families of functions defined by `ElementaryFunctions`:
### Exponential functions
- ``exp(_:)``
- ``expMinusOne(_:)``
### Logarithmetic functions
- ``log(_:)``
- ``log(onePlus:)``
### Power and root functions:
- ``pow(_:_:)-9imp6``
- ``pow(_:_:)-2qmul``
- ``sqrt(_:)``
- ``root(_:_:)``
### Trigonometric functions
- ``cos(_:)``
- ``sin(_:)``
- ``tan(_:)``
### Inverse trigonometric functions
- ``acos(_:)``
- ``asin(_:)``
- ``atan(_:)``
### Hyperbolic functions
- ``cosh(_:)``
- ``sinh(_:)``
- ``tanh(_:)``
### Inverse hyperbolic functions
- ``acosh(_:)``
- ``asinh(_:)``
- ``atanh(_:)``
[elfn]: http://en.wikipedia.org/wiki/Elementary_function
@@ -0,0 +1,27 @@
# ``RealFunctions``
A type that extends ``ElementaryFunctions`` with additional operations that
are primarily used with real numbers.
## Topics
### Exponential functions
- ``exp2(_:)``
- ``exp10(_:)``
### Logarithmetic functions
- ``log2(_:)``
- ``log10(_:)``
### Plane geometry
- ``atan2(y:x:)``
- ``hypot(_:_:)``
### Gamma function
- ``gamma(_:)``
- ``logGamma(_:)``
- ``signGamma(_:)``
### Error function
- ``erf(_:)``
- ``erfc(_:)``
+1 -1
View File
@@ -2,7 +2,7 @@
//
// 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-2025 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
+39 -77
View File
@@ -2,62 +2,19 @@
//
// 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-2025 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
//
//===----------------------------------------------------------------------===//
/// A type that has elementary functions (`sin`, `cos`, etc.) available.
///
/// An ["elementary function"][elfn] is a function built up from powers, roots,
/// exponentials, logarithms, trigonometric functions (sin, cos, tan) and
/// their inverses, and the hyperbolic functions (sinh, cosh, tanh) and their
/// inverses.
///
/// Conformance to this protocol means that all of these building blocks are
/// available as static functions on the type.
///
/// ```swift
/// let x: Float = 1
/// let y = Float.sin(x) // 0.84147096
/// ```
///
/// There are three broad families of functions defined by
/// `ElementaryFunctions`:
/// - Exponential, trigonometric, and hyperbolic functions:
/// `exp`, `expMinusOne`, `cos`, `sin`, `tan`, `cosh`, `sinh`, and `tanh`.
/// - Logarithmic, inverse trigonometric, and inverse hyperbolic functions:
/// `log`, `log(onePlus:)`, `acos`, `asin`, `atan`, `acosh`, `asinh`, and
/// `atanh`.
/// - Power and root functions:
/// `pow`, `sqrt`, and `root`.
///
/// `ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
/// and subtraction and the `.zero` property are also available.
///
/// There are two other protocols that you are more likely to want to use
/// directly:
///
/// `RealFunctions` refines `ElementaryFunctions` and includes
/// additional functions specific to real number types.
///
/// `Real` conforms to `RealFunctions` and `FloatingPoint`, and is the
/// protocol that you will want to use most often for generic code.
///
/// See Also:
///
/// - `RealFunctions`
/// - `Real`
///
/// [elfn]: http://en.wikipedia.org/wiki/Elementary_function
public protocol ElementaryFunctions: AdditiveArithmetic {
/// The [exponential function][wiki] e^x whose base `e` is the base of the
/// natural logarithm.
///
/// See also `expMinusOne()`, as well as `exp2()` and `exp10()`
/// defined for types conforming to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see
/// ``RealFunctions/exp2(_:)`` and ``RealFunctions/exp10(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Exponential_function
static func exp(_ x: Self) -> Self
@@ -68,7 +25,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// catastrophic cancellation and the result will not have full accuracy.
/// The `.expMinusOne(x)` function gives you a means to address this problem.
///
/// As an example, consider the expression `(x + 1)*exp(x) - 1`. When `x`
/// As an example, consider the expression `(x + 1) * .exp(x) - 1`. When `x`
/// is smaller than `.ulpOfOne`, this expression evaluates to `0.0`, when it
/// should actually round to `2*x`. We can get a full-accuracy result by
/// using the following instead:
@@ -79,8 +36,8 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// This re-written expression delivers an accurate result for all values
/// of `x`, not just for small values.
///
/// See also `exp()`, as well as `exp2()` and `exp10()` defined for types
/// conforming to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see
/// ``RealFunctions/exp2(_:)`` and ``RealFunctions/exp10(_:)``.
static func expMinusOne(_ x: Self) -> Self
/// The [hyperbolic cosine][wiki] of `x`.
@@ -90,7 +47,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// 2
/// ```
///
/// See also `sinh()`, `tanh()` and `acosh()`.
/// See also ``acosh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func cosh(_ x: Self) -> Self
@@ -102,7 +59,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// 2
/// ```
///
/// See also `cosh()`, `tanh()` and `asinh()`.
/// See also ``asinh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func sinh(_ x: Self) -> Self
@@ -114,7 +71,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// cosh(x)
/// ```
///
/// See also `cosh()`, `sinh()` and `atanh()`.
/// See also ``atanh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Hyperbolic_function
static func tanh(_ x: Self) -> Self
@@ -123,7 +80,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `sin()`, `tan()` and `acos()`.
/// See also ``acos(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Cosine
static func cos(_ x: Self) -> Self
@@ -133,7 +90,7 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `cos()`, `tan()` and `asin()`.
/// See also ``asin(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Sine
static func sin(_ x: Self) -> Self
@@ -142,49 +99,54 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, `x` may be interpreted as an angle measured in radians.
///
/// See also `cos()`, `sin()` and `atan()`, as well as `atan2(y:x:)` for
/// types that conform to `RealFunctions`.
/// See also ``atan(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Tangent
static func tan(_ x: Self) -> Self
/// The [natural logarithm][wiki] of `x`.
///
/// See also `log(onePlus:)`, as well as `log2()` and `log10()` for types
/// that conform to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see also
/// ``RealFunctions/log2(_:)`` and ``RealFunctions/log10(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Logarithm
static func log(_ x: Self) -> Self
/// log(1 + x), computed in such a way as to maintain accuracy for small x.
///
/// See also `log()`, as well as `log2()` and `log10()` for types
/// that conform to `RealFunctions`.
/// For types that conform to ``RealFunctions`` see also
/// ``RealFunctions/log2(_:)`` and ``RealFunctions/log10(_:)``.
static func log(onePlus x: Self) -> Self
/// The [inverse hyperbolic cosine][wiki] of `x`.
///
/// ```
/// cosh(acosh(x)) ≅ x
/// ```
/// See also `asinh()`, `atanh()` and `cosh()`.
///
/// See also ``cosh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func acosh(_ x: Self) -> Self
/// The [inverse hyperbolic sine][wiki] of `x`.
///
/// ```
/// sinh(asinh(x)) ≅ x
/// ```
/// See also `acosh()`, `atanh()` and `sinh()`.
///
/// See also ``sinh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func asinh(_ x: Self) -> Self
/// The [inverse hyperbolic tangent][wiki] of `x`.
///
/// ```
/// tanh(atanh(x)) ≅ x
/// ```
/// See also `acosh()`, `asinh()` and `tanh()`.
///
/// See also ``tanh(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_hyperbolic_function
static func atanh(_ x: Self) -> Self
@@ -193,10 +155,12 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// cos(acos(x)) ≅ x
/// ```
/// See also `asin()`, `atan()` and `cos()`.
///
/// See also ``cos(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func acos(_ x: Self) -> Self
@@ -205,10 +169,12 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// sin(asin(x)) ≅ x
/// ```
/// See also `acos()`, `atan()` and `sin()`.
///
/// See also ``sin(_:)``.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func asin(_ x: Self) -> Self
@@ -217,11 +183,14 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
///
/// For real types, the result may be interpreted as an angle measured in
/// radians.
///
/// ```
/// tan(atan(x)) ≅ x
/// ```
/// See also `acos()`, `asin()` and `tan()`, as well as `atan2(y:x:)` for
/// types that conform to `RealArithmetic`.
///
/// See also ``tan(_:)``.
/// For types that conform to ``RealFunctions``, you will sometimes want
/// to use ``RealFunctions/atan2(y:x:)`` instead.
///
/// [wiki]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions
static func atan(_ x: Self) -> Self
@@ -233,10 +202,9 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// In particular, this means that if `x` and `y` are both zero, `pow(x,y)`
/// is `nan` for real types and `infinity` for complex types, rather than 1.
///
/// There is also a `pow(_:Self,_:Int)` overload, whose behavior is defined
/// in terms of repeated multiplication, and hence returns 1 for this case.
///
/// See also `sqrt()` and `root()`.
/// There is also
/// <doc:/documentation/RealModule/ElementaryFunctions/pow(_:_:)-9imp6>,
/// whose behavior is defined in terms of repeated multiplication.
static func pow(_ x: Self, _ y: Self) -> Self
/// `x` raised to the nth power.
@@ -244,19 +212,13 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
/// The edge-cases of this function are defined in terms of repeated
/// multiplication or division, rather than exp(n log x). In particular,
/// `Float.pow(0, 0)` is 1.
///
/// See also `sqrt()` and `root()`.
static func pow(_ x: Self, _ n: Int) -> Self
/// The [square root][wiki] of `x`.
///
/// See also `pow()` and `root()`.
///
/// [wiki]: https://en.wikipedia.org/wiki/Square_root
static func sqrt(_ x: Self) -> Self
/// The nth root of `x`.
///
/// See also `pow()` and `sqrt()`.
static func root(_ x: Self, _ n: Int) -> Self
}
+2 -2
View File
@@ -2,7 +2,7 @@
//
// 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-2025 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
@@ -41,7 +41,7 @@ extension Real {
/// cos(x) - 1, computed in such a way as to maintain accuracy for small x.
///
/// See also `ElementaryFunctions.expMinusOne()`.
/// See also ``ElementaryFunctions.expMinusOne()``.
@_transparent
public static func cosMinusOne(_ x: Self) -> Self {
let sinxOver2 = sin(x/2)
+46 -27
View File
@@ -2,7 +2,7 @@
//
// 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-2025 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
@@ -10,70 +10,89 @@
//===----------------------------------------------------------------------===//
public protocol RealFunctions: ElementaryFunctions {
/// `atan(y/x)`, with sign selected according to the quadrant of `(x, y)`.
/// The signed angle formed in the plane between the vector `(x,y)` and the
/// positive real axis, measured in radians.
///
/// See also `atan()`.
/// The result is in the interval `[-π, π]`.
///
/// The argument order to `atan2` may be surprising to new programmers.
/// The convention of `y` being the first argument goes back at least to
/// Fortran IV in 1961 and is generally followed in computing with a few
/// notable exceptions (e.g. Mathematica and Excel). This convention was
/// originally chosen because of the mathematical definition of the
/// function:
///
/// ```
/// atan2(y,x) = atan(y/x) if x > 0
/// ```
///
/// See also ``ElementaryFunctions/atan(_:)``, as well as the `phase` and
/// `polar` properties defined on the `Complex` type.
static func atan2(y: Self, x: Self) -> Self
/// The error function evaluated at `x`.
///
/// See also `erfc()`.
/// The [error function](https://en.wikipedia.org/wiki/Error_function)
/// evaluated at `x`.
static func erf(_ x: Self) -> Self
/// The complimentary error function evaluated at `x`.
///
/// See also `erf()`.
/// The complimentary [error function](https://en.wikipedia.org/wiki/Error_function)
/// evaluated at `x`.
static func erfc(_ x: Self) -> Self
/// 2^x
/// 2 raised to the power x.
///
/// See also `exp()`, `expMinusOne()`, `exp10()`, `log2()` and `pow()`.
/// See also ``log2(_:)``, ``ElementaryFunctions/exp(_:)``,
/// ``ElementaryFunctions/expMinusOne(_:)``
/// and ``ElementaryFunctions/pow(_:_:)-2qmul``.
static func exp2(_ x: Self) -> Self
/// 10^x
/// 10 raised to the power x.
///
/// See also `exp()`, `expMinusOne()`, `exp2()`, `log10()` and `pow()`.
/// See also ``log10(_:)``, ``ElementaryFunctions/exp(_:)``,
/// ``ElementaryFunctions/expMinusOne(_:)``
/// and ``ElementaryFunctions/pow(_:_:)-2qmul``.
static func exp10(_ x: Self) -> Self
/// `sqrt(x*x + y*y)`, computed in a manner that avoids spurious overflow or
/// underflow.
/// The length of the vector `(x,y)`, computed in a manner that avoids
/// spurious overflow or underflow.
///
/// See also the `length` and `polar` properties defined on the `Complex`
/// type.
static func hypot(_ x: Self, _ y: Self) -> Self
/// The gamma function Γ(x).
///
/// See also `logGamma()` and `signGamma()`.
/// The [gamma function](https://en.wikipedia.org/wiki/Gamma_function) Γ(x).
static func gamma(_ x: Self) -> Self
/// The base-2 logarithm of `x`.
///
/// See also `exp2()`, `log()`, `log(onePlus:)` and `log10()`.
/// See also ``exp2(_:)``, ``ElementaryFunctions/log(_:)``,
/// and ``ElementaryFunctions/log(onePlus:)``.
static func log2(_ x: Self) -> Self
/// The base-10 logarithm of `x`.
///
/// See also: `exp10()`, `log()`, `log(onePlus:)` and `log2()`.
/// See also ``exp10(_:)``, ``ElementaryFunctions/log(_:)``,
/// and ``ElementaryFunctions/log(onePlus:)``.
static func log10(_ x: Self) -> Self
#if !os(Windows)
/// The logarithm of the absolute value of the gamma function, log(|Γ(x)|).
/// The logarithm of the absolute value of the
/// [gamma function](https://en.wikipedia.org/wiki/Gamma_function),
/// log(|Γ(x)|).
///
/// Not available on Windows targets.
///
/// See also `gamma()` and `signGamma()`.
static func logGamma(_ x: Self) -> Self
/// The sign of the gamma function, Γ(x).
/// The sign of the
/// [gamma function](https://en.wikipedia.org/wiki/Gamma_function), Γ(x).
///
/// For `x >= 0`, `signGamma(x)` is `.plus`. For negative `x`, `signGamma(x)`
/// is `.plus` when `x` is an integer, and otherwise it is `.minus` whenever
/// `trunc(x)` is even, and `.plus` when `trunc(x)` is odd.
///
/// This function is used together with `logGamma`, which computes the
/// This function is used together with ``logGamma(_:)``, which computes the
/// logarithm of the absolute value of Γ(x), to recover the sign information.
///
/// Not available on Windows targets.
///
/// See also `gamma()` and `logGamma()`.
static func signGamma(_ x: Self) -> FloatingPointSign
#endif
}
+5 -5
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Numerics open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift Numerics project authors
// Copyright (c) 2021-2025 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
@@ -11,12 +11,11 @@
import _NumericsShims
/// A namespace for "relaxed arithmetic" operations for types conforming to
/// `AlgebraicField`.
public enum Relaxed { }
extension Relaxed {
/// a+b with the optimizer licensed to reassociate expressions and form FMAs.
/// a+b, but grants the optimizer permission to reassociate expressions
/// and form FMAs.
///
/// Floating-point addition is not an associative operation, so the Swift
/// compiler does not have any flexibility in how it evaluates an expression
@@ -45,7 +44,8 @@ extension Relaxed {
T._relaxedAdd(a, b)
}
/// a*b with the optimizer licensed to reassociate expressions and form FMAs.
/// a*b, but grants the optimizer permission to reassociate expressions
/// and form FMAs.
///
/// Floating-point addition and multiplication are not associative operations,
/// so the Swift compiler does not have any flexibility in how it evaluates