SwiftDoc.org

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a vector with zero in all lanes.

Declaration

public init()

Creates a new value, rounded to the closest possible representation.

If two representable values are equally close, the result is the value with more trailing zeros in its significand bit pattern.

• Parameter value: The integer to convert to a floating-point value.

Declaration

public init(_ v: Int)

Creates a new value, rounded to the closest possible representation.

If two representable values are equally close, the result is the value with more trailing zeros in its significand bit pattern.

• Parameter value: The integer to convert to a floating-point value.

Declaration

@inlinable public init<Source>(_ value: Source) where Source: BinaryInteger

Creates a new instance initialized to the given value.

The value of other is represented exactly by the new instance. A NaN passed as other results in another NaN, with a signaling NaN value converted to quiet NaN.

let x: Float = 21.25
let y = Float(x)
// y == 21.25

let z = Float(Float.nan)
// z.isNaN == true

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init(_ other: Float)

Creates a new instance that approximates the given value.

The value of other is rounded to a representable value, if necessary. A NaN passed as other results in another NaN, with a signaling NaN value converted to quiet NaN.

let x: Double = 21.25
let y = Float(x)
// y == 21.25

let z = Float(Double.nan)
// z.isNaN == true

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init(_ other: Double)

Creates a new instance that approximates the given value.

The value of other is rounded to a representable value, if necessary. A NaN passed as other results in another NaN, with a signaling NaN value converted to quiet NaN.

let x: Float80 = 21.25
let y = Float(x)
// y == 21.25

let z = Float(Float80.nan)
// z.isNaN == true

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init(_ other: Float80)

Creates a new instance from the given value, rounded to the closest possible representation.

If two representable values are equally close, the result is the value with more trailing zeros in its significand bit pattern.

• Parameter value: A floating-point value to be converted.

Declaration

@inlinable public init<Source>(_ value: Source) where Source: BinaryFloatingPoint

Creates a new value with the given bit pattern.

The value passed as bitPattern is interpreted in the binary interchange format defined by the IEEE 754 specification.

• Parameter bitPattern: The integer encoding of a Float instance.

Declaration

@inlinable public init(bitPattern: UInt32)

Creates an instance initialized to the specified floating-point value.

Do not call this initializer directly. Instead, initialize a variable or constant using a floating-point literal. For example:

let x = 21.5

In this example, the assignment to the x constant calls this floating-point literal initializer behind the scenes.

• Parameter value: The value to create.

Declaration

@inlinable public init(floatLiteral value: Float)

Creates a new instance by decoding from the given decoder.

This initializer throws an error if reading from the decoder fails, or if the data read is corrupted or otherwise invalid.

• Parameter decoder: The decoder to read data from.

Declaration

public init(from decoder: Decoder) throws

Creates an instance initialized to the specified integer value.

Do not call this initializer directly. Instead, initialize a variable or constant using an integer literal. For example:

let x = 23

In this example, the assignment to the x constant calls this integer literal initializer behind the scenes.

• Parameter value: The value to create.

Declaration

public init(integerLiteral value: Int64)

Creates a NaN ("not a number") value with the specified payload.

NaN values compare not equal to every value, including themselves. Most operations with a NaN operand produce a NaN result. Don't use the equal-to operator (==) to test whether a value is NaN. Instead, use the value's isNaN property.

let x = Float(nan: 0, signaling: false)
print(x == .nan)
// Prints "false"
print(x.isNaN)
// Prints "true"

Declaration

@inlinable public init(nan payload: Float.RawSignificand, signaling: Bool)

Creates a new value from the given sign, exponent, and significand.

The following example uses this initializer to create a new Double instance. Double is a binary floating-point type that has a radix of 2.

let x = Double(sign: .plus, exponent: -2, significand: 1.5)
// x == 0.375

This initializer is equivalent to the following calculation, where ** is exponentiation, computed as if by a single, correctly rounded, floating-point operation:

let sign: FloatingPointSign = .plus
let exponent = -2
let significand = 1.5
let y = (sign == .minus ? -1 : 1) * significand * Double.radix ** exponent
// y == 0.375

As with any basic operation, if this value is outside the representable range of the type, overflow or underflow occurs, and zero, a subnormal value, or infinity may result. In addition, there are two other edge cases:

For any floating-point value x of type F, the result of the following is equal to x, with the distinction that the result is canonicalized if x is in a noncanonical encoding:

let x0 = F(sign: x.sign, exponent: x.exponent, significand: x.significand)

This initializer implements the scaleB operation defined by the IEEE 754 specification.

Declaration

@inlinable public init(sign: FloatingPointSign, exponent: Int, significand: Float)

Creates a new instance from the specified sign and bit patterns.

The values passed as exponentBitPattern and significandBitPattern are interpreted in the binary interchange format defined by the IEEE 754 specification.

Declaration

@inlinable public init(sign: FloatingPointSign, exponentBitPattern: UInt, significandBitPattern: UInt32)

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.

Declaration

public init(signOf sign: Float, magnitudeOf mag: Float)

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.

Declaration

@inlinable public init(signOf: Self, magnitudeOf: Self)

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").

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:

Passing any other format or any additional characters as text results in nil. For example, the following conversions result in nil:

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

• Parameter text: The input string to convert to a Float instance. If text has invalid characters or is in an invalid format, the result is nil.

Declaration

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

Creates a new instance initialized to the given value, if it can be represented without rounding.

If other can't be represented as an instance of Float without rounding, the result of this initializer is nil. In particular, passing NaN as other always results in nil.

let x: Float = 21.25
let y = Float(exactly: x)
// y == Optional.some(21.25)

let z = Float(exactly: Float.nan)
// z == nil

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init?(exactly other: Float)

Creates a new instance initialized to the given value, if it can be represented without rounding.

If other can't be represented as an instance of Float without rounding, the result of this initializer is nil. In particular, passing NaN as other always results in nil.

let x: Double = 21.25
let y = Float(exactly: x)
// y == Optional.some(21.25)

let z = Float(exactly: Double.nan)
// z == nil

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init?(exactly other: Double)

Creates a new instance initialized to the given value, if it can be represented without rounding.

If other can't be represented as an instance of Float without rounding, the result of this initializer is nil. In particular, passing NaN as other always results in nil.

let x: Float80 = 21.25
let y = Float(exactly: x)
// y == Optional.some(21.25)

let z = Float(exactly: Float80.nan)
// z == nil

• Parameter other: The value to use for the new instance.

Declaration

@inlinable public init?(exactly other: Float80)

Creates a new instance from the given value, if it can be represented exactly.

If the given floating-point value cannot be represented exactly, the result is nil.

• Parameter value: A floating-point value to be converted.

Declaration

@inlinable public init?<Source>(exactly value: Source) where Source: BinaryFloatingPoint

The floating-point value with the same sign and exponent as this value, but with a significand of 1.0.

A binade is a set of binary floating-point values that all have the same sign and exponent. The binade property is a member of the same binade as this value, but with a unit significand.

In this example, x has a value of 21.5, which is stored as 1.34375 * 2**4, where ** is exponentiation. Therefore, x.binade is equal to 1.0 * 2**4, or 16.0.

let x = 21.5
// x.significand == 1.34375
// x.exponent == 4

let y = x.binade
// y == 16.0
// y.significand == 1.0
// y.exponent == 4

Declaration

var binade: Float

The bit pattern of the value's encoding.

The bit pattern matches the binary interchange format defined by the IEEE 754 specification.

Declaration

var bitPattern: UInt32

A mirror that reflects the Float instance.

Declaration

var customMirror: Mirror

A custom playground Quick Look for the Float instance.

Declaration

var customPlaygroundQuickLook: _PlaygroundQuickLook

A textual representation of the value, suitable for debugging.

Declaration

var debugDescription: String

A textual representation of the value.

Declaration

var description: String

The exponent of the floating-point value.

The exponent of a floating-point value is the integer part of the logarithm of the value's magnitude. For a value x of a floating-point type F, the magnitude can be calculated as the following, where ** is exponentiation:

let magnitude = x.significand * F.radix ** x.exponent

In the next example, y has a value of 21.5, which is encoded as 1.34375 * 2 ** 4. The significand of y is therefore 1.34375.

let y: Double = 21.5
// y.significand == 1.34375
// y.exponent == 4
// Double.radix == 2

The exponent property has the following edge cases:

This property implements the logB operation defined by the IEEE 754 specification.

Declaration

var exponent: Int

The raw encoding of the value's exponent field.

This value is unadjusted by the type's exponent bias.

Declaration

var exponentBitPattern: UInt

A Boolean value indicating whether the instance's representation is in its canonical form.

The IEEE 754 specification defines a canonical, or preferred, encoding of a floating-point value. On platforms that fully support IEEE 754, every Float or Double value is canonical, but non-canonical values can exist on other platforms or for other types. Some examples:

Declaration

var isCanonical: Bool

A Boolean value indicating whether this instance is finite.

All values other than NaN and infinity are considered finite, whether normal or subnormal.

Declaration

var isFinite: Bool

A Boolean value indicating whether the instance is infinite.

Note that isFinite and isInfinite do not form a dichotomy, because they are not total: If x is NaN, then both properties are false.

Declaration

var isInfinite: Bool

A Boolean value indicating whether the instance is NaN ("not a number").

Because NaN is not equal to any value, including NaN, use this property instead of the equal-to operator (==) or not-equal-to operator (!=) to test whether a value is or is not NaN. For example:

let x = 0.0
let y = x * .infinity
// y is a NaN

// Comparing with the equal-to operator never returns 'true'
print(x == Double.nan)
// Prints "false"
print(y == Double.nan)
// Prints "false"

// Test with the 'isNaN' property instead
print(x.isNaN)
// Prints "false"
print(y.isNaN)
// Prints "true"

This property is true for both quiet and signaling NaNs.

Declaration

var isNaN: Bool

A Boolean value indicating whether this instance is normal.

A normal value is a finite number that uses the full precision available to values of a type. Zero is neither a normal nor a subnormal number.

Declaration

var isNormal: Bool

A Boolean value indicating whether the instance is a signaling NaN.

Signaling NaNs typically raise the Invalid flag when used in general computing operations.

Declaration

var isSignalingNaN: Bool

A Boolean value indicating whether the instance is subnormal.

A subnormal value is a nonzero number that has a lesser magnitude than the smallest normal number. Subnormal values do not use the full precision available to values of a type.

Zero is neither a normal nor a subnormal number. Subnormal numbers are often called denormal or denormalized---these are different names for the same concept.

Declaration

var isSubnormal: Bool

A Boolean value indicating whether the instance is equal to zero.

The isZero property of a value x is true when x represents either -0.0 or +0.0. x.isZero is equivalent to the following comparison: x == 0.0.

let x = -0.0
x.isZero        // true
x == 0.0        // true

Declaration

var isZero: Bool

The magnitude of this value.

For any numeric value x, x.magnitude is the absolute value of x. You can use the magnitude property in operations that are simpler to implement in terms of unsigned values, such as printing the value of an integer, which is just printing a '-' character in front of an absolute value.

let x = -200
// x.magnitude == 200

The global abs(_:) function provides more familiar syntax when you need to find an absolute value. In addition, because abs(_:) always returns a value of the same type, even in a generic context, using the function instead of the magnitude property is encouraged.

Declaration

var magnitude: Float

The least representable value that compares greater than this value.

For any finite value x, x.nextUp is greater than x. For nan or infinity, x.nextUp is x itself. The following special cases also apply:

Declaration

var nextUp: Float

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The number of scalars, or elements, in the vector.

Declaration

var scalarCount: Int

The sign of the floating-point value.

The sign property is .minus if the value's signbit is set, and .plus otherwise. For example:

let x = -33.375
// x.sign == .minus

Do not use this property to check whether a floating point value is negative. For a value x, the comparison x.sign == .minus is not necessarily the same as x < 0. In particular, x.sign == .minus if x is -0, and while x < 0 is always false if x is NaN, x.sign could be either .plus or .minus.

Declaration

var sign: FloatingPointSign

The significand of the floating-point value.

The magnitude of a floating-point value x of type F can be calculated by using the following formula, where ** is exponentiation:

let magnitude = x.significand * F.radix ** x.exponent

In the next example, y has a value of 21.5, which is encoded as 1.34375 * 2 ** 4. The significand of y is therefore 1.34375.

let y: Double = 21.5
// y.significand == 1.34375
// y.exponent == 4
// Double.radix == 2

If a type's radix is 2, then for finite nonzero numbers, the significand is in the range 1.0 ..< 2.0. For other values of x, x.significand is defined as follows:

Note: The significand is frequently also called the mantissa, but significand is the preferred terminology in the IEEE 754 specification, to allay confusion with the use of mantissa for the fractional part of a logarithm.

Declaration

var significand: Float

The raw encoding of the value's significand field.

The significandBitPattern property does not include the leading integral bit of the significand, even for types like Float80 that store it explicitly.

Declaration

var significandBitPattern: UInt32

The number of bits required to represent the value's significand.

If this value is a finite nonzero number, significandWidth is the number of fractional bits required to represent the value of significand; otherwise, significandWidth is -1. The value of significandWidth is always -1 or between zero and significandBitCount. For example:

Declaration

var significandWidth: Int

The unit in the last place of this value.

This is the unit of the least significant digit in this value's significand. For most numbers x, this is the difference between x and the next greater (in magnitude) representable number. There are some edge cases to be aware of:

See also the ulpOfOne static property.

Declaration

var ulp: Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Accesses the element at the specified index.

• Parameter index: The index of the element to access. index must be in the range 0..<scalarCount.

Declaration

public subscript(index: Int) -> Float

Adds the product of the two given values to this value in place, computed without intermediate rounding.

Declaration

public mutating func addProduct(_ lhs: Float, _ rhs: Float)

Returns a value that is offset the specified distance from this value.

Use the advanced(by:) method in generic code to offset a value by a specified distance. If you're working directly with numeric values, use the addition operator (+) instead of this method.

func addOne<T: Strideable>(to x: T) -> T
    where T.Stride: ExpressibleByIntegerLiteral
{
    return x.advanced(by: 1)
}

let x = addOne(to: 5)
// x == 6
let y = addOne(to: 3.5)
// y = 4.5

If this type's Stride type conforms to BinaryInteger, then for a value x, a distance n, and a value y = x.advanced(by: n), x.distance(to: y) == n. Using this method with types that have a noninteger Stride may result in an approximation.

• Parameter n: The distance to advance this value.

Complexity: O(1)

Declaration

public func advanced(by amount: Float) -> Float

Returns the distance from this value to the given value, expressed as a stride.

If this type's Stride type conforms to BinaryInteger, then for two values x and y, and a distance n = x.distance(to: y), x.advanced(by: n) == y. Using this method with types that have a noninteger Stride may result in an approximation.

• Parameter other: The value to calculate the distance to.

Complexity: O(1)

Declaration

public func distance(to other: Float) -> Float

Encodes this value into the given encoder.

This function throws an error if any values are invalid for the given encoder's format.

• Parameter encoder: The encoder to write data to.

Declaration

public func encode(to encoder: Encoder) throws

Replaces this value with the remainder of itself 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:

var x = 8.625
print(x / 0.75)
// Prints "11.5"

let q = (x / 0.75).rounded(.toNearestOrEven)
// q == 12.0
x.formRemainder(dividingBy: 0.75)
// x == -0.375

let x1 = 0.75 * q + x
// 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 formRemainder(dividingBy:) method is always exact.

• Parameter other: The value to use when dividing this value.

Declaration

@inlinable public mutating func formRemainder(dividingBy other: Float)

Replaces this value with its square root, rounded to a representable value.

Declaration

public mutating func formSquareRoot()

Replaces this value with the remainder of itself 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:

var x = 8.625
print(x / 0.75)
// Prints "11.5"

let q = (x / 0.75).rounded(.towardZero)
// q == 11.0
x.formTruncatingRemainder(dividingBy: 0.75)
// x == 0.375

let x1 = 0.75 * q + x
// 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 formTruncatingRemainder(dividingBy:) method is always exact.

• Parameter other: The value to use when dividing this value.

Declaration

@inlinable public mutating func formTruncatingRemainder(dividingBy other: Float)

Hashes the essential components of this value by feeding them into the given hasher.

Implement this method to conform to the Hashable protocol. The components used for hashing must be the same as the components compared in your type's == operator implementation. Call hasher.combine(_:) with each of these components.

Important: Never call finalize() on hasher. Doing so may become a compile-time error in the future.

• Parameter hasher: The hasher to use when combining the components of this instance.

Declaration

@inlinable public func hash(into hasher: inout Hasher)

Returns a Boolean value indicating whether this instance is equal to the given value.

This method serves as the basis for the equal-to operator (==) for floating-point values. When comparing two values with this method, -0 is equal to +0. NaN is not equal to any value, including itself. For example:

let x = 15.0
x.isEqual(to: 15.0)
// true
x.isEqual(to: .nan)
// false
Double.nan.isEqual(to: .nan)
// false

The isEqual(to:) method implements the equality predicate defined by the IEEE 754 specification.

• Parameter other: The value to compare with this value.

Declaration

public func isEqual(to other: Float) -> Bool

Returns a Boolean value indicating whether this instance is less than the given value.

This method serves as the basis for the less-than operator (<) for floating-point values. Some special cases apply:

The isLess(than:) method implements the less-than predicate defined by the IEEE 754 specification.

• Parameter other: The value to compare with this value.

Declaration

public func isLess(than other: Float) -> Bool

Returns a Boolean value indicating whether this instance is less than or equal to the given value.

This method serves as the basis for the less-than-or-equal-to operator (<=) for floating-point values. Some special cases apply:

The isLessThanOrEqualTo(_:) method implements the less-than-or-equal predicate defined by the IEEE 754 specification.

• Parameter other: The value to compare with this value.

Declaration

public func isLessThanOrEqualTo(_ other: Float) -> Bool

Returns a Boolean value indicating whether this instance should precede or tie positions with 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 signed zeros and NaNs.

The following example uses isTotallyOrdered(belowOrEqualTo:) 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 { !$1.isTotallyOrdered(belowOrEqualTo: $0) }
// 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.

• Parameter other: A floating-point value to compare to this value.

Declaration

@inlinable public func isTotallyOrdered(belowOrEqualTo other: Self) -> Bool

Replaces this value with its additive inverse.

The result is always exact. This example uses the negate() method to negate the value of the variable x:

var x = 21.5
x.negate()
// x == -21.5

Declaration

public mutating func negate()

Rounds the value to an integral value using the specified rounding rule.

The following example rounds a value using four different rounding rules:

// Equivalent to the C 'round' function:
var w = 6.5
w.round(.toNearestOrAwayFromZero)
// w == 7.0

// Equivalent to the C 'trunc' function:
var x = 6.5
x.round(.towardZero)
// x == 6.0

// Equivalent to the C 'ceil' function:
var y = 6.5
y.round(.up)
// y == 7.0

// Equivalent to the C 'floor' function:
var z = 6.5
z.round(.down)
// z == 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 round() method instead.

var w1 = 6.5
w1.round()
// w1 == 7.0

• Parameter rule: The rounding rule to use.

Declaration

public mutating func round(_ rule: FloatingPointRoundingRule)

Writes a textual representation of this instance into the given output stream.

Declaration

public func write<Target>(to target: inout Target) where Target: TextOutputStream

The number of bits used to represent the type's exponent.

A binary floating-point type's exponentBitCount imposes a limit on the range of the exponent for normal, finite values. The exponent bias of a type F can be calculated as the following, where ** is exponentiation:

let bias = 2 ** (F.exponentBitCount - 1) - 1

The least normal exponent for values of the type F is 1 - bias, and the largest finite exponent is bias. An all-zeros exponent is reserved for subnormals and zeros, and an all-ones exponent is reserved for infinity and NaN.

For example, the Float type has an exponentBitCount of 8, which gives an exponent bias of 127 by the calculation above.

let bias = 2 ** (Float.exponentBitCount - 1) - 1
// bias == 127
print(Float.greatestFiniteMagnitude.exponent)
// Prints "127"
print(Float.leastNormalMagnitude.exponent)
// Prints "-126"

Declaration

var exponentBitCount: Int

The greatest finite number representable by this type.

This value compares greater than or equal to all finite numbers, but less than infinity.

This value corresponds to type-specific C macros such as FLT_MAX and DBL_MAX. The naming of those macros is slightly misleading, because infinity is greater than this value.

Declaration

var greatestFiniteMagnitude: Float

Positive infinity.

Infinity compares greater than all finite numbers and equal to other infinite values.

let x = Double.greatestFiniteMagnitude
let y = x * 2
// y == Double.infinity
// y > x

Declaration

var infinity: Float

The least positive number.

This value compares less than or equal to all positive numbers, but greater than zero. If the type supports subnormal values, leastNonzeroMagnitude is smaller than leastNormalMagnitude; otherwise they are equal.

Declaration

var leastNonzeroMagnitude: Float

The least positive normal number.

This value compares less than or equal to all positive normal numbers. There may be smaller positive numbers, but they are subnormal, meaning that they are represented with less precision than normal numbers.

This value corresponds to type-specific C macros such as FLT_MIN and DBL_MIN. The naming of those macros is slightly misleading, because subnormals, zeros, and negative numbers are smaller than this value.

Declaration

var leastNormalMagnitude: Float

A quiet NaN ("not a number").

A NaN compares not equal, not greater than, and not less than every value, including itself. Passing a NaN to an operation generally results in NaN.

let x = 1.21
// x > Double.nan == false
// x < Double.nan == false
// x == Double.nan == false

Because a NaN always compares not equal to itself, to test whether a floating-point value is NaN, use its isNaN property instead of the equal-to operator (==). In the following example, y is NaN.

let y = x + Double.nan
print(y == Double.nan)
// Prints "false"
print(y.isNaN)
// Prints "true"

Declaration

var nan: Float

The mathematical constant pi.

This value should be rounded toward zero to keep user computations with angles from inadvertently ending up in the wrong quadrant. A type that conforms to the FloatingPoint protocol provides the value for pi at its best possible precision.

print(Double.pi)
// Prints "3.14159265358979"

Declaration

var pi: Float

The radix, or base of exponentiation, for a floating-point type.

The magnitude of a floating-point value x of type F can be calculated by using the following formula, where ** is exponentiation:

let magnitude = x.significand * F.radix ** x.exponent

A conforming type may use any integer radix, but values other than 2 (for binary floating-point types) or 10 (for decimal floating-point types) are extraordinarily rare in practice.

Declaration

var radix: Int

A signaling NaN ("not a number").

The default IEEE 754 behavior of operations involving a signaling NaN is to raise the Invalid flag in the floating-point environment and return a quiet NaN.

Operations on types conforming to the FloatingPoint protocol should support this behavior, but they might also support other options. For example, it would be reasonable to implement alternative operations in which operating on a signaling NaN triggers a runtime error or results in a diagnostic for debugging purposes. Types that implement alternative behaviors for a signaling NaN must document the departure.

Other than these signaling operations, a signaling NaN behaves in the same manner as a quiet NaN.

Declaration

var signalingNaN: Float

The available number of fractional significand bits.

For fixed-width floating-point types, this is the actual number of fractional significand bits.

For extensible floating-point types, significandBitCount should be the maximum allowed significand width (without counting any leading integral bit of the significand). If there is no upper limit, then significandBitCount should be Int.max.

Note that Float80.significandBitCount is 63, even though 64 bits are used to store the significand in the memory representation of a Float80 (unlike other floating-point types, Float80 explicitly stores the leading integral significand bit, but the BinaryFloatingPoint APIs provide an abstraction so that users don't need to be aware of this detail).

Declaration

var significandBitCount: Int

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.

Declaration

var ulpOfOne: Float

Multiplies two values and produces their product, rounding to a representable value.

The multiplication operator (*) calculates the product of its two arguments. For example:

let x = 7.5
let y = x * 2.25
// y == 16.875

The * operator implements the multiplication operation defined by the IEEE 754 specification.

Declaration

public static func *(lhs: Float, rhs: Float) -> Float

Multiplies two values and stores the result in the left-hand-side variable, rounding to a representable value.

Declaration

public static func *=(lhs: inout Float, rhs: Float)

Adds two values and produces their sum, rounded to a representable value.

The addition operator (+) calculates the sum of its two arguments. For example:

let x = 1.5
let y = x + 2.25
// y == 3.75

The + operator implements the addition operation defined by the IEEE 754 specification.

Declaration

public static func +(lhs: Float, rhs: Float) -> Float

Adds two values and stores the result in the left-hand-side variable, rounded to a representable value.

Declaration

public static func +=(lhs: inout Float, rhs: Float)

Subtracts one value from another and produces their difference, rounded to a representable value.

The subtraction operator (-) calculates the difference of its two arguments. For example:

let x = 7.5
let y = x - 2.25
// y == 5.25

The - operator implements the subtraction operation defined by the IEEE 754 specification.

Declaration

public static func -(lhs: Float, rhs: Float) -> Float

Calculates the additive inverse of a value.

The unary minus operator (prefix -) calculates the negation of its operand. The result is always exact.

let x = 21.5
let y = -x
// y == -21.5

• Parameter operand: The value to negate.

Declaration

prefix public static func -(x: Float) -> Float

Subtracts the second value from the first and stores the difference in the left-hand-side variable, rounding to a representable value.

Declaration

public static func -=(lhs: inout Float, rhs: Float)

Returns the quotient of dividing the first value by the second, rounded to a representable value.

The division operator (/) calculates the quotient of the division if rhs is nonzero. If rhs is zero, the result of the division is infinity, with the sign of the result matching the sign of lhs.

let x = 16.875
let y = x / 2.25
// y == 7.5

let z = x / 0
// z.isInfinite == true

The / operator implements the division operation defined by the IEEE 754 specification.

Declaration

public static func /(lhs: Float, rhs: Float) -> Float

Divides the first value by the second and stores the quotient in the left-hand-side variable, rounding to a representable value.

Declaration

public static func /=(lhs: inout Float, rhs: Float)

Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

This function is the only requirement of the Comparable protocol. The remainder of the relational operator functions are implemented by the standard library for any type that conforms to Comparable.

Declaration

@inlinable public static func <(x: Self, y: Self) -> Bool

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values a and b, a == b implies that a != b is false.

Declaration

@inlinable public static func ==(x: Self, y: Self) -> Bool