protocol BinaryFloatingPoint
A radix2 (binary) floatingpoint type.
Inheritance  ExpressibleByFloatLiteral, FloatingPoint 

Conforming Types  Double, Float, Float80 
Associated Types 
associatedtype RawSignificand
associatedtype RawExponent

Initializers
Creates a new instance from the given value, rounded to the closest possible representation.
 Parameter value: A floatingpoint 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 floatingpoint 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 floatingpoint 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 floatingpoint 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 floatingpoint 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 floatingpoint value to be converted.
Declaration
init?<Source>(exactly value: Source) where Source: BinaryFloatingPoint
Instance Variables
The floatingpoint value with the same sign and exponent as this value, but with a significand of 1.0.
A binade is a set of binary floatingpoint 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
Type Variables
The number of bits used to represent the type's exponent.
A binary floatingpoint 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 allzeros exponent is reserved
for subnormals and zeros, and an allones 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 fixedwidth floatingpoint types, this is the actual number of fractional significand bits.
For extensible floatingpoint 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 floatingpoint 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
Default Implementations
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
floatingpoint 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 floatingpoint 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
The
BinaryFloatingPoint
protocol extends theFloatingPoint
protocol with operations specific to floatingpoint binary types, as defined by the IEEE 754 specification.BinaryFloatingPoint
is implemented in the standard library byFloat
,Double
, andFloat80
where available.