SwiftDoc.org

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

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

Declaration

init(_ value: Float)

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

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

Declaration

init(_ value: Double)

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

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

Declaration

init(_ value: 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

init<Source>(_ value: Source) where Source: BinaryFloatingPoint

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

init(sign: FloatingPointSign, exponentBitPattern: Self.RawExponent, significandBitPattern: Self.RawSignificand)

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. A value that is NaN ("not a number") cannot be represented exactly if its payload cannot be encoded exactly.

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

Declaration

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: Self

The raw encoding of the value's exponent field.

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

Declaration

var exponentBitPattern: Self.RawExponent

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: Self.RawSignificand

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 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 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

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

public static func <(lhs: Self, rhs: Self) -> Bool

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

Declaration

public static func <=(lhs: Self, rhs: 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

public static func ==(lhs: Self, rhs: Self) -> Bool

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

Declaration

public static func >(lhs: Self, rhs: Self) -> Bool

Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.

Declaration

public static func >=(lhs: Self, rhs: Self) -> Bool

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.

Declaration

public func addingProduct(_ lhs: Self, _ rhs: Self) -> Self

The classification of this value.

A value's floatingPointClass property describes its "class" as described by the IEEE 754 specification.

Declaration

var floatingPointClass: FloatingPointClassification

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.

Declaration

@inlinable public static func maximum(_ x: Self, _ y: Self) -> Self

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.

Declaration

@inlinable public static func maximumMagnitude(_ x: Self, _ y: Self) -> Self

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.

Declaration

@inlinable public static func minimum(_ x: Self, _ y: Self) -> Self

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.

Declaration

@inlinable public static func minimumMagnitude(_ x: Self, _ y: Self) -> Self

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:

Declaration

var nextDown: Self

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.

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

Declaration

@inlinable public func remainder(dividingBy other: Self) -> Self

Declaration

public mutating func round()

Declaration

public func rounded() -> Self

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.

Declaration

public func rounded(_ rule: FloatingPointRoundingRule) -> Self

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

Declaration

public func squareRoot() -> Self

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.

Declaration

@inlinable public func truncatingRemainder(dividingBy other: Self) -> Self

The unit in the last place of 1.0.

The positive difference between 1.0 and the next greater representable number. ulpOfOne corresponds to the value represented by the C macros FLT_EPSILON, DBL_EPSILON, etc, and is sometimes called epsilon or machine epsilon. Swift deliberately avoids using the term "epsilon" because:

See also the ulp member property.

Declaration

var ulpOfOne: Self