Merge pull request swiftlang#36945 from tbkka/tbkka/rdar76728925

Author: swift-ci

stdlib/public/core/FloatingPointParsing.swift.gyb

@@ -53,63 +53,65 @@ extension ${Self}: LosslessStringConvertible {
   /// Creates a new instance from the given string.
   ///
   /// The string passed as `text` can represent a real number in decimal or
-  /// hexadecimal format or special floating-point values for infinity and NaN
-  /// ("not a number").
+  /// hexadecimal format or can be in a special format representing infinity
+  /// or NaN ("not a number"). If `text` is not in a recognized format,
+  /// the optional initializer will fail and return `nil`.
   ///
-  /// The given string may begin with a plus or minus sign character (`+` or
-  /// `-`). The allowed formats for each of these representations is then as
-  /// follows:
+  /// The `text` string consists of an optional
+  /// plus or minus sign character (`+` or `-`)
+  /// followed by one of the following:
   ///
-  /// - A *decimal value* contains the significand, a sequence of decimal
-  ///   digits that may include a decimal point.
+  /// - A *decimal string* contains a significand consisting of one
+  ///   or more decimal digits that may include a decimal point:
   ///
   ///       let c = ${Self}("-1.0")
   ///       // c == -1.0
   ///
   ///       let d = ${Self}("28.375")
   ///       // d == 28.375
   ///
-  ///   A decimal value may also include an exponent following the significand,
-  ///   indicating the power of 10 by which the significand should be
-  ///   multiplied. If included, the exponent is separated by a single
+  ///   A decimal string may also include an exponent following the
+  ///   significand, indicating the power of 10 by which the significand should
+  ///   be multiplied. If included, the exponent is separated by a single
   ///   character, `e` or `E`, and consists of an optional plus or minus sign
   ///   character and a sequence of decimal digits.
   ///
   ///       let e = ${Self}("2837.5e-2")
   ///       // e == 28.375
   ///
-  /// - A *hexadecimal value* contains the significand, either `0X` or `0x`,
-  ///   followed by a sequence of hexadecimal digits. The significand may
+  /// - A *hexadecimal string* contains a significand consisting of
+  ///   `0X` or `0x` followed by one or more hexadecimal digits that may
   ///   include a decimal point.
   ///
   ///       let f = ${Self}("0x1c.6")
   ///       // f == 28.375
   ///
-  ///   A hexadecimal value may also include an exponent following the
-  ///   significand, indicating the power of 2 by which the significand should
+  ///   A hexadecimal string may also include an exponent
+  ///   indicating the power of 2 by which the significand should
   ///   be multiplied. If included, the exponent is separated by a single
   ///   character, `p` or `P`, and consists of an optional plus or minus sign
   ///   character and a sequence of decimal digits.
   ///
   ///       let g = ${Self}("0x1.c6p4")
   ///       // g == 28.375
   ///
-  /// - A value of *infinity* contains one of the strings `"inf"` or
-  ///   `"infinity"`, case insensitive.
+  /// - The input strings `"inf"` or `"infinity"` (case insensitive)
+  ///   are converted to an infinite result:
   ///
   ///       let i = ${Self}("inf")
   ///       // i == ${Self}.infinity
   ///
   ///       let j = ${Self}("-Infinity")
   ///       // j == -${Self}.infinity
   ///
-  /// - A value of *NaN* contains the string `"nan"`, case insensitive.
+  /// - An input string of `"nan"` (case insensitive) is converted
+  ///   into a *NaN* value:
   ///
   ///       let n = ${Self}("-nan")
   ///       // n?.isNaN == true
   ///       // n?.sign == .minus
   ///
-  ///   A NaN value may also include a payload in parentheses following the
+  ///   A NaN string may also include a payload in parentheses following the
   ///   `"nan"` keyword. The payload consists of a sequence of decimal digits,
   ///   or the characters `0X` or `0x` followed by a sequence of hexadecimal
   ///   digits. If the payload contains any other characters, it is ignored.
@@ -120,16 +122,44 @@ extension ${Self}: LosslessStringConvertible {
   ///       // p?.isNaN == true
   ///       // String(p!) == "nan(0x10)"
   ///
-  /// Passing any other format or any additional characters as `text` results
-  /// in `nil`. For example, the following conversions result in `nil`:
+  /// A string in any other format than those described above
+  /// or containing additional characters
+  /// results in a `nil` value. For example, the following conversions
+  /// result in `nil`:
+  ///
+  ///       ${Self}(" 5.0")      // Includes whitespace
+  ///       ${Self}("±2.0")      // Invalid character
+  ///       ${Self}("0x1.25e4")  // Incorrect exponent format
+  ///
+  /// A decimal or hexadecimal string is converted to a `${Self}`
+  /// instance using the IEEE 754 roundTiesToEven (default) rounding
+  /// attribute.
+  /// Values with absolute value smaller than `${Self}.leastNonzeroMagnitude`
+  /// are rounded to plus or minus zero.
+  /// Values with absolute value larger than `${Self}.greatestFiniteMagnitude`
+  /// are rounded to plus or minus infinity.
+  ///
+  ///       let y = ${Self}("1.23e-9999")
+  ///       // y == 0.0
+  ///       // y?.sign == .plus
+  ///
+  ///       let z = ${Self}("-7.89e-7206")
+  ///       // z == -0.0
+  ///       // z?.sign == .minus
+  ///
+  ///       let r = ${Self}("1.23e17802")
+  ///       // r == ${Self}.infinity
+  ///
+  ///       let s = ${Self}("-7.89e7206")
+  ///       // s == ${Self}.-infinity
+  ///
+  /// - Note:  Prior to Swift 5.4, a decimal or
+  /// hexadecimal input string whose value was too large to represent
+  /// as a finite `${Self}` instance returned `nil` instead of
+  /// `${Self}.infinity`.
   ///
-  ///     ${Self}(" 5.0")      // Includes whitespace
-  ///     ${Self}("±2.0")      // Invalid character
-  ///     ${Self}("0x1.25e4")  // Incorrect exponent format
+  /// - Parameter text: An input string to convert to a `${Self}?` instance.
   ///
-  /// - Parameter text: The input string to convert to a `${Self}` instance. If
-  ///   `text` has invalid characters or is in an invalid format, the result
-  ///   is `nil`.
   @inlinable
   public init?<S: StringProtocol>(_ text: S) {
   %if bits == 16: