[stdlib] Manually propagate floating point documentation

Author: natecook1000

stdlib/public/core/FloatingPoint.swift.gyb

@@ -1596,10 +1596,48 @@ public protocol BinaryFloatingPoint: FloatingPoint, ExpressibleByFloatLiteral {
 
 extension FloatingPoint {
 
+  /// The unit in the last place of 1.0.
+  ///
+  /// The positive difference between 1.0 and the next greater representable
+  /// number. The `ulpOfOne` constant corresponds to the C macros
+  /// `FLT_EPSILON`, `DBL_EPSILON`, and others with a similar purpose.
   public static var ulpOfOne: Self {
     return Self(1).ulp
   }
 
+  /// Returns this value rounded to an integral value using the specified
+  /// rounding rule.
+  ///
+  /// The following example rounds a value using four different rounding rules:
+  ///
+  ///     let x = 6.5
+  ///
+  ///     // Equivalent to the C 'round' function:
+  ///     print(x.rounded(.toNearestOrAwayFromZero))
+  ///     // Prints "7.0"
+  ///
+  ///     // Equivalent to the C 'trunc' function:
+  ///     print(x.rounded(.towardZero))
+  ///     // Prints "6.0"
+  ///
+  ///     // Equivalent to the C 'ceil' function:
+  ///     print(x.rounded(.up))
+  ///     // Prints "7.0"
+  ///
+  ///     // Equivalent to the C 'floor' function:
+  ///     print(x.rounded(.down))
+  ///     // Prints "6.0"
+  ///
+  /// For more information about the available rounding rules, see the
+  /// `FloatingPointRoundingRule` enumeration. To round a value using the
+  /// default "schoolbook rounding", you can use the shorter `rounded()`
+  /// method instead.
+  ///
+  ///     print(x.rounded())
+  ///     // Prints "7.0"
+  ///
+  /// - Parameter rule: The rounding rule to use.
+  /// - Returns: The integral value found by rounding using `rule`.
   @_transparent
   public func rounded(_ rule: FloatingPointRoundingRule) -> Self {
     var lhs = self
@@ -1658,39 +1696,166 @@ extension FloatingPoint {
     round(.toNearestOrAwayFromZero)
   }
 
+  /// The greatest representable value that compares less than this value.
+  ///
+  /// For any finite value `x`, `x.nextDown` is less than `x`. For `nan` or
+  /// `-infinity`, `x.nextDown` is `x` itself. The following special cases
+  /// also apply:
+  ///
+  /// - If `x` is `infinity`, then `x.nextDown` is `greatestFiniteMagnitude`.
+  /// - If `x` is `leastNonzeroMagnitude`, then `x.nextDown` is `0.0`.
+  /// - If `x` is zero, then `x.nextDown` is `-leastNonzeroMagnitude`.
+  /// - If `x` is `-greatestFiniteMagnitude`, then `x.nextDown` is `-infinity`.
   @_transparent
   public var nextDown: Self {
     return -(-self).nextUp
   }
 
+  /// Returns the remainder of this value divided by the given value using
+  /// truncating division.
+  ///
+  /// Performing truncating division with floating-point values results in a
+  /// truncated integer quotient and a remainder. For values `x` and `y` and
+  /// their truncated integer quotient `q`, the remainder `r` satisfies
+  /// `x == y * q + r`.
+  ///
+  /// The following example calculates the truncating remainder of dividing
+  /// 8.625 by 0.75:
+  ///
+  ///     let x = 8.625
+  ///     print(x / 0.75)
+  ///     // Prints "11.5"
+  ///
+  ///     let q = (x / 0.75).rounded(.towardZero)
+  ///     // q == 11.0
+  ///     let r = x.truncatingRemainder(dividingBy: 0.75)
+  ///     // r == 0.375
+  ///
+  ///     let x1 = 0.75 * q + r
+  ///     // x1 == 8.625
+  ///
+  /// If this value and `other` are both finite numbers, the truncating
+  /// remainder has the same sign as this value and is strictly smaller in
+  /// magnitude than `other`. The `truncatingRemainder(dividingBy:)` method
+  /// is always exact.
+  ///
+  /// - Parameter other: The value to use when dividing this value.
+  /// - Returns: The remainder of this value divided by `other` using
+  ///   truncating division.
   @_transparent
   public func truncatingRemainder(dividingBy other: Self) -> Self {
     var lhs = self
     lhs.formTruncatingRemainder(dividingBy: other)
     return lhs
   }
 
+  /// Returns the remainder of this value divided by the given value.
+  ///
+  /// For two finite values `x` and `y`, the remainder `r` of dividing `x` by
+  /// `y` satisfies `x == y * q + r`, where `q` is the integer nearest to
+  /// `x / y`. If `x / y` is exactly halfway between two integers, `q` is
+  /// chosen to be even. Note that `q` is *not* `x / y` computed in
+  /// floating-point arithmetic, and that `q` may not be representable in any
+  /// available integer type.
+  ///
+  /// The following example calculates the remainder of dividing 8.625 by 0.75:
+  ///
+  ///     let x = 8.625
+  ///     print(x / 0.75)
+  ///     // Prints "11.5"
+  ///
+  ///     let q = (x / 0.75).rounded(.toNearestOrEven)
+  ///     // q == 12.0
+  ///     let r = x.remainder(dividingBy: 0.75)
+  ///     // r == -0.375
+  ///
+  ///     let x1 = 0.75 * q + r
+  ///     // x1 == 8.625
+  ///
+  /// If this value and `other` are finite numbers, the remainder is in the
+  /// closed range `-abs(other / 2)...abs(other / 2)`. The
+  /// `remainder(dividingBy:)` method is always exact. This method implements
+  /// the remainder operation defined by the [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameter other: The value to use when dividing this value.
+  /// - Returns: The remainder of this value divided by `other`.
   @_transparent
   public func remainder(dividingBy other: Self) -> Self {
     var lhs = self
     lhs.formRemainder(dividingBy: other)
     return lhs
   }
 
+  /// Returns the square root of the value, rounded to a representable value.
+  ///
+  /// The following example declares a function that calculates the length of
+  /// the hypotenuse of a right triangle given its two perpendicular sides.
+  ///
+  ///     func hypotenuse(_ a: Double, _ b: Double) -> Double {
+  ///         return (a * a + b * b).squareRoot()
+  ///     }
+  ///
+  ///     let (dx, dy) = (3.0, 4.0)
+  ///     let distance = hypotenuse(dx, dy)
+  ///     // distance == 5.0
+  ///
+  /// - Returns: The square root of the value.
   @_transparent
   public func squareRoot( ) -> Self {
     var lhs = self
     lhs.formSquareRoot( )
     return lhs
   }
 
+  /// Returns the result of adding the product of the two given values to this
+  /// value, computed without intermediate rounding.
+  ///
+  /// This method is equivalent to the C `fma` function and implements the
+  /// `fusedMultiplyAdd` operation defined by the [IEEE 754
+  /// specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameters:
+  ///   - lhs: One of the values to multiply before adding to this value.
+  ///   - rhs: The other value to multiply.
+  /// - Returns: The product of `lhs` and `rhs`, added to this value.
   @_transparent
   public func addingProduct(_ lhs: Self, _ rhs: Self) -> Self {
     var addend = self
     addend.addProduct(lhs, rhs)
     return addend
   }
 
+  /// Returns the lesser of the two given values.
+  ///
+  /// This method returns the minimum of two values, preserving order and
+  /// eliminating NaN when possible. For two values `x` and `y`, the result of
+  /// `minimum(x, y)` is `x` if `x <= y`, `y` if `y < x`, or whichever of `x`
+  /// or `y` is a number if the other is a quiet NaN. If both `x` and `y` are
+  /// NaN, or either `x` or `y` is a signaling NaN, the result is NaN.
+  ///
+  ///     Double.minimum(10.0, -25.0)
+  ///     // -25.0
+  ///     Double.minimum(10.0, .nan)
+  ///     // 10.0
+  ///     Double.minimum(.nan, -25.0)
+  ///     // -25.0
+  ///     Double.minimum(.nan, .nan)
+  ///     // nan
+  ///
+  /// The `minimum` method implements the `minNum` operation defined by the
+  /// [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameters:
+  ///   - x: A floating-point value.
+  ///   - y: Another floating-point value.
+  /// - Returns: The minimum of `x` and `y`, or whichever is a number if the
+  ///   other is NaN.
   public static func minimum(_ x: Self, _ y: Self) -> Self {
     if x.isSignalingNaN || y.isSignalingNaN {
       //  Produce a quiet NaN matching platform arithmetic behavior.
@@ -1700,6 +1865,33 @@ extension FloatingPoint {
     return y
   }
 
+  /// Returns the greater of the two given values.
+  ///
+  /// This method returns the maximum of two values, preserving order and
+  /// eliminating NaN when possible. For two values `x` and `y`, the result of
+  /// `maximum(x, y)` is `x` if `x > y`, `y` if `x <= y`, or whichever of `x`
+  /// or `y` is a number if the other is a quiet NaN. If both `x` and `y` are
+  /// NaN, or either `x` or `y` is a signaling NaN, the result is NaN.
+  ///
+  ///     Double.maximum(10.0, -25.0)
+  ///     // 10.0
+  ///     Double.maximum(10.0, .nan)
+  ///     // 10.0
+  ///     Double.maximum(.nan, -25.0)
+  ///     // -25.0
+  ///     Double.maximum(.nan, .nan)
+  ///     // nan
+  ///
+  /// The `maximum` method implements the `maxNum` operation defined by the
+  /// [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameters:
+  ///   - x: A floating-point value.
+  ///   - y: Another floating-point value.
+  /// - Returns: The greater of `x` and `y`, or whichever is a number if the
+  ///   other is NaN.
   public static func maximum(_ x: Self, _ y: Self) -> Self {
     if x.isSignalingNaN || y.isSignalingNaN {
       //  Produce a quiet NaN matching platform arithmetic behavior.
@@ -1709,6 +1901,35 @@ extension FloatingPoint {
     return y
   }
 
+  /// Returns the value with lesser magnitude.
+  ///
+  /// This method returns the value with lesser magnitude of the two given
+  /// values, preserving order and eliminating NaN when possible. For two
+  /// values `x` and `y`, the result of `minimumMagnitude(x, y)` is `x` if
+  /// `x.magnitude <= y.magnitude`, `y` if `y.magnitude < x.magnitude`, or
+  /// whichever of `x` or `y` is a number if the other is a quiet NaN. If both
+  /// `x` and `y` are NaN, or either `x` or `y` is a signaling NaN, the result
+  /// is NaN.
+  ///
+  ///     Double.minimumMagnitude(10.0, -25.0)
+  ///     // 10.0
+  ///     Double.minimumMagnitude(10.0, .nan)
+  ///     // 10.0
+  ///     Double.minimumMagnitude(.nan, -25.0)
+  ///     // -25.0
+  ///     Double.minimumMagnitude(.nan, .nan)
+  ///     // nan
+  ///
+  /// The `minimumMagnitude` method implements the `minNumMag` operation
+  /// defined by the [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameters:
+  ///   - x: A floating-point value.
+  ///   - y: Another floating-point value.
+  /// - Returns: Whichever of `x` or `y` has lesser magnitude, or whichever is
+  ///   a number if the other is NaN.
   public static func minimumMagnitude(_ x: Self, _ y: Self) -> Self {
     if x.isSignalingNaN || y.isSignalingNaN {
       //  Produce a quiet NaN matching platform arithmetic behavior.
@@ -1718,6 +1939,35 @@ extension FloatingPoint {
     return y
   }
 
+  /// Returns the value with greater magnitude.
+  ///
+  /// This method returns the value with greater magnitude of the two given
+  /// values, preserving order and eliminating NaN when possible. For two
+  /// values `x` and `y`, the result of `maximumMagnitude(x, y)` is `x` if
+  /// `x.magnitude > y.magnitude`, `y` if `x.magnitude <= y.magnitude`, or
+  /// whichever of `x` or `y` is a number if the other is a quiet NaN. If both
+  /// `x` and `y` are NaN, or either `x` or `y` is a signaling NaN, the result
+  /// is NaN.
+  ///
+  ///     Double.maximumMagnitude(10.0, -25.0)
+  ///     // -25.0
+  ///     Double.maximumMagnitude(10.0, .nan)
+  ///     // 10.0
+  ///     Double.maximumMagnitude(.nan, -25.0)
+  ///     // -25.0
+  ///     Double.maximumMagnitude(.nan, .nan)
+  ///     // nan
+  ///
+  /// The `maximumMagnitude` method implements the `maxNumMag` operation
+  /// defined by the [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameters:
+  ///   - x: A floating-point value.
+  ///   - y: Another floating-point value.
+  /// - Returns: Whichever of `x` or `y` has greater magnitude, or whichever is
+  ///   a number if the other is NaN.
   public static func maximumMagnitude(_ x: Self, _ y: Self) -> Self {
     if x.isSignalingNaN || y.isSignalingNaN {
       //  Produce a quiet NaN matching platform arithmetic behavior.
@@ -1727,6 +1977,12 @@ extension FloatingPoint {
     return y
   }
 
+  /// The classification of this value.
+  ///
+  /// A value's `floatingPointClass` property describes its "class" as
+  /// described by the [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
   public var floatingPointClass: FloatingPointClassification {
     if isSignalingNaN { return .signalingNaN }
     if isNaN { return .quietNaN }
@@ -1748,12 +2004,55 @@ extension BinaryFloatingPoint {
   ///     let magnitude = x.significand * F.radix ** x.exponent
   public static var radix: Int { return 2 }
 
+  /// Creates a new floating-point value using the sign of one value and the
+  /// magnitude of another.
+  ///
+  /// The following example uses this initializer to create a new `Double`
+  /// instance with the sign of `a` and the magnitude of `b`:
+  ///
+  ///     let a = -21.5
+  ///     let b = 305.15
+  ///     let c = Double(signOf: a, magnitudeOf: b)
+  ///     print(c)
+  ///     // Prints "-305.15"
+  ///
+  /// This initializer implements the IEEE 754 `copysign` operation.
+  ///
+  /// - Parameters:
+  ///   - signOf: A value from which to use the sign. The result of the
+  ///     initializer has the same sign as `signOf`.
+  ///   - magnitudeOf: A value from which to use the magnitude. The result of
+  ///     the initializer has the same magnitude as `magnitudeOf`.
   public init(signOf: Self, magnitudeOf: Self) {
     self.init(sign: signOf.sign,
       exponentBitPattern: magnitudeOf.exponentBitPattern,
       significandBitPattern: magnitudeOf.significandBitPattern)
   }
 
+  /// Returns a Boolean value indicating whether this instance should precede the
+  /// given value in an ascending sort.
+  ///
+  /// This relation is a refinement of the less-than-or-equal-to operator
+  /// (`<=`) that provides a total order on all values of the type, including
+  /// noncanonical encodings, signed zeros, and NaNs. Because it is used much
+  /// less frequently than the usual comparisons, there is no operator form of
+  /// this relation.
+  ///
+  /// The following example uses `isTotallyOrdered(below:)` to sort an array of
+  /// floating-point values, including some that are NaN:
+  ///
+  ///     var numbers = [2.5, 21.25, 3.0, .nan, -9.5]
+  ///     numbers.sort { $0.isTotallyOrdered(below: $1) }
+  ///     // numbers == [-9.5, 2.5, 3.0, 21.25, nan]
+  ///
+  /// The `isTotallyOrdered(belowOrEqualTo:)` method implements the total order
+  /// relation as defined by the [IEEE 754 specification][spec].
+  ///
+  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
+  ///
+  /// - Parameter other: A floating-point value to compare to this value.
+  /// - Returns: `true` if this value is ordered below `other` in a total
+  ///   ordering of the floating-point type; otherwise, `false`.
   public func isTotallyOrdered(belowOrEqualTo other: Self) -> Bool {
     // Quick return when possible.
     if self < other { return true }