Contents

init(_:)

Creates a new instance from the given string.

Declaration

init?<S>(_ text: S) where S : StringProtocol

Parameters

  • text:

    An input string to convert to a Float? instance.

Discussion

The string passed as text can represent a real number in decimal or 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 text string consists of an optional plus or minus sign character (+ or -) followed by one of the following:

  • A decimal string contains a significand consisting of one or more decimal digits that may include a decimal point:

    let c = Float("-1.0")
// c == -1.0

let d = Float("28.375")
// d == 28.375

    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 = Float("2837.5e-2")
// e == 28.375

  • 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 = Float("0x1c.6")
// f == 28.375

    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 = Float("0x1.c6p4")
// g == 28.375

  • The input strings "inf" or "infinity" (case insensitive) are converted to an infinite result:

    let i = Float("inf")
// i == Float.infinity

let j = Float("-Infinity")
// j == -Float.infinity

  • An input string of "nan" (case insensitive) is converted into a NaN value:

    let n = Float("-nan")
// n?.isNaN == true
// n?.sign == .minus

    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. If the value of the payload is larger than can be stored as the payload of a Float.nan, the least significant bits are used.

    let p = Float("nan(0x10)")
// p?.isNaN == true
// String(p!) == "nan(0x10)"

  • An input string of "snan" (case insensitive) is converted into a signaling NaN value. This form permits an optional payload in the same format as for a non-signaling NaN.

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:

  Float(" 5.0")      // Includes whitespace
  Float("±2.0")      // Invalid character
  Float("0x1.25e4")  // Incorrect exponent format

A decimal or hexadecimal string is converted to a Float instance using the IEEE 754 roundTiesToEven (default) rounding attribute. Values with absolute value smaller than one-half of Float.leastNonzeroMagnitude are rounded to plus or minus zero. Values with absolute value larger than Float.greatestFiniteMagnitude are rounded to plus or minus infinity.

  let y = Float("1.23e-9999")
  // y == 0.0
  // y?.sign == .plus

  let z = Float("-7.89e-7206")
  // z == -0.0
  // z?.sign == .minus

  let r = Float("1.23e17802")
  // r == Float.infinity

  let s = Float("-7.89e7206")
  // s == Float.-infinity

See Also

Converting Strings