protocol BinaryFloatingPoint
Inheritance 
Comparable, Equatable, ExpressibleByFloatLiteral, ExpressibleByIntegerLiteral, FloatingPoint, Hashable, Numeric, SignedNumeric, Strideable
View Protocol Hierarchy →


Associated Types 
RawSignificand : UnsignedInteger
A type that represents the encoded significand of a value. RawExponent : UnsignedInteger
A type that represents the encoded exponent of a value. FloatLiteralType : _ExpressibleByBuiltinFloatLiteral
A type that represents a floatingpoint literal. Valid types for IntegerLiteralType : _ExpressibleByBuiltinIntegerLiteral
A type that represents an integer literal. The standard library integer and floatingpoint types are all valid types
for Magnitude = Self
A type that can represent the absolute value of any possible value of the conforming type. Exponent : SignedInteger
A type that can represent any written exponent. Stride : Comparable, SignedNumeric
A type that represents the distance between two values. 
Import  import Swift 
Initializers
Creates a new instance from the given value, rounded to the closest possible representation.
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.
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.
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.
value
: A floatingpoint value to be converted.
Declaration
init<Source>(_ value: Source)
Declared In
BinaryFloatingPoint
, FloatingPoint
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.
Parameters: sign: The sign of the new value. exponentBitPattern: The bit pattern to use for the exponent field of the new value. significandBitPattern: The bit pattern to use for the significand field of the new value.
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.
value
: A floatingpoint value to be converted.
Declaration
init?<Source>(exactly value: Source)
Declared In
BinaryFloatingPoint
, FloatingPoint
, Numeric
Creates an instance initialized to the specified floatingpoint value.
Do not call this initializer directly. Instead, initialize a variable or constant using a floatingpoint literal. For example:
let x = 21.5
In this example, the assignment to the x
constant calls this
floatingpoint literal initializer behind the scenes.
value
: The value to create.
Declaration
init(floatLiteral value: Self.FloatLiteralType)
Declared In
ExpressibleByFloatLiteral
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.
value
: The value to create.
Declaration
init(integerLiteral value: Self.IntegerLiteralType)
Declared In
ExpressibleByIntegerLiteral
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: Int)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: Int8)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: Int16)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: Int32)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: Int64)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: UInt)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: UInt8)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: UInt16)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: UInt32)
Declared In
FloatingPoint
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init(_ value: UInt64)
Declared In
FloatingPoint
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 floatingpoint 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,
floatingpoint 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:
 If the value you pass to
significand
is zero or infinite, the result is zero or infinite, regardless of the value ofexponent
.  If the value you pass to
significand
is NaN, the result is NaN.
For any floatingpoint 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.
Parameters: sign: The sign to use for the new value. exponent: The new value's exponent. significand: The new value's significand.
Declaration
init(sign: FloatingPointSign, exponent: Self.Exponent, significand: Self)
Declared In
FloatingPoint
Creates a new floatingpoint 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.
Parameters:
signOf: A value from which to use the sign. The result of the
initializer has the same sign as signOf
.
magnitudeOf: A value from which to use the magnitude. The result of
the initializer has the same magnitude as magnitudeOf
.
Declaration
init(signOf: Self, magnitudeOf: Self)
Declared In
FloatingPoint
Static 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
static var exponentBitCount: Int { get }
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
static var significandBitCount: Int { get }
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 typespecific 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
static var greatestFiniteMagnitude: Self { get }
Declared In
FloatingPoint
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
static var infinity: Self { get }
Declared In
FloatingPoint
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
static var leastNonzeroMagnitude: Self { get }
Declared In
FloatingPoint
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 typespecific 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
static var leastNormalMagnitude: Self { get }
Declared In
FloatingPoint
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
floatingpoint value is NaN, use its isNaN
property instead of the
equalto 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
static var nan: Self { get }
Declared In
FloatingPoint
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
static var pi: Self { get }
Declared In
FloatingPoint
The radix, or base of exponentiation, for a floatingpoint type.
The magnitude of a floatingpoint 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 floatingpoint types) or 10 (for decimal floatingpoint types) are extraordinarily rare in practice.
Declaration
static var radix: Int { get }
Declared In
FloatingPoint
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 floatingpoint 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
static var signalingNaN: Self { get }
Declared In
FloatingPoint
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
static var ulpOfOne: Self { get }
Declared In
FloatingPoint
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 { get }
The raw encoding of the value's exponent field.
This value is unadjusted by the type's exponent bias.
Declaration
var exponentBitPattern: Self.RawExponent { get }
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 { get }
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:
 For any representable power of two,
significandWidth
is zero, becausesignificand
is1.0
.  If
x
is 10,x.significand
is1.01
in binary, sox.significandWidth
is 2.  If
x
is Float.pi,x.significand
is1.10010010000111111011011
in binary, andx.significandWidth
is 23.
Declaration
var significandWidth: Int { get }
The exponent of the floatingpoint value.
The exponent of a floatingpoint value is the integer part of the
logarithm of the value's magnitude. For a value x
of a floatingpoint
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:
 If
x
is zero, thenx.exponent
isInt.min
.  If
x
is +/infinity or NaN, thenx.exponent
isInt.max
This property implements the logB
operation defined by the IEEE 754
specification.
Declaration
var exponent: Self.Exponent { get }
Declared In
FloatingPoint
The classification of this value.
A value's floatingPointClass
property describes its "class" as
described by the IEEE 754 specification.
Declaration
var floatingPointClass: FloatingPointClassification { get }
Declared In
FloatingPoint
A Boolean value indicating whether the instance's representation is in the canonical form.
The IEEE 754 specification defines a canonical, or preferred,
encoding of a floatingpoint value's representation. Every Float
or
Double
value is canonical, but noncanonical values of the Float80
type exist, and noncanonical values may exist for other types that
conform to the FloatingPoint
protocol.
Declaration
var isCanonical: Bool { get }
Declared In
FloatingPoint
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 { get }
Declared In
FloatingPoint
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 { get }
Declared In
FloatingPoint
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 equalto operator (==
) or notequalto 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 equalto 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 { get }
Declared In
FloatingPoint
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 { get }
Declared In
FloatingPoint
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 { get }
Declared In
FloatingPoint
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 denormalizedthese are different names for the same concept.
Declaration
var isSubnormal: Bool { get }
Declared In
FloatingPoint
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 { get }
Declared In
FloatingPoint
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:
 If
x
isinfinity
, thenx.nextDown
isgreatestFiniteMagnitude
.  If
x
isleastNonzeroMagnitude
, thenx.nextDown
is0.0
.  If
x
is zero, thenx.nextDown
isleastNonzeroMagnitude
.  If
x
isgreatestFiniteMagnitude
, thenx.nextDown
isinfinity
.
Declaration
var nextDown: Self { get }
Declared In
FloatingPoint
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:
 If
x
isinfinity
, thenx.nextUp
isgreatestFiniteMagnitude
.  If
x
isleastNonzeroMagnitude
, thenx.nextUp
is0.0
.  If
x
is zero, thenx.nextUp
isleastNonzeroMagnitude
.  If
x
isgreatestFiniteMagnitude
, thenx.nextUp
isinfinity
.
Declaration
var nextUp: Self { get }
Declared In
FloatingPoint
The sign of the floatingpoint 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 { get }
Declared In
FloatingPoint
The significand of the floatingpoint value.
The magnitude of a floatingpoint 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:
 If
x
is zero, thenx.significand
is 0.0.  If
x
is infinity, thenx.significand
is 1.0.  If
x
is NaN, thenx.significand
is NaN. 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: Self { get }
Declared In
FloatingPoint
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:
 If
x
is not a finite number, thenx.ulp
is NaN.  If
x
is very small in magnitude, thenx.ulp
may be a subnormal number. If a type does not support subnormals,x.ulp
may be rounded to zero. greatestFiniteMagnitude.ulp
is a finite number, even though the next greater representable value isinfinity
.
This quantity, or a related quantity, is sometimes called epsilon or machine epsilon. Avoid that name because it has different meanings in different languages, which can lead to confusion, and because it suggests that it is a good tolerance to use for comparisons, which it almost never is.
Declaration
var ulp: Self { get }
Declared In
FloatingPoint
The hash value.
Hash values are not guaranteed to be equal across different executions of your program. Do not save hash values to use during a future execution.
Declaration
var hashValue: Int { get }
Declared In
Hashable
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: Self.Magnitude { get }
Declared In
Numeric
Static Methods
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: The greater of x
and y
, or whichever is a number if the
other is NaN.
Declaration
static func maximum(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: Whichever of x
or y
has greater magnitude, or whichever is
a number if the other is NaN.
Declaration
static func maximumMagnitude(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: The minimum of x
and y
, or whichever is a number if the
other is NaN.
Declaration
static func minimum(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: Whichever of x
or y
has lesser magnitude, or whichever is
a number if the other is NaN.
Declaration
static func minimumMagnitude(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
Instance Methods
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.
Parameters: lhs: The first value to multiply. rhs: The second value to multiply.
Declaration
func *(lhs: Self, rhs: Self) > Self
Declared In
FloatingPoint
, Numeric
Multiplies two values and stores the result in the lefthandside variable, rounding to a representable value.
Parameters: lhs: The first value to multiply. rhs: The second value to multiply.
Declaration
func *=(lhs: inout Self, rhs: Self)
Declared In
FloatingPoint
, Numeric
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.
Parameters: lhs: The first value to add. rhs: The second value to add.
Declaration
func +(lhs: Self, rhs: Self) > Self
Declared In
FloatingPoint
, Numeric
Adds two values and stores the result in the lefthandside variable, rounded to a representable value.
Parameters: lhs: The first value to add. rhs: The second value to add.
Declaration
func +=(lhs: inout Self, rhs: Self)
Declared In
FloatingPoint
, Numeric
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.
Parameters:
lhs: The value to divide.
rhs: The value to divide lhs
by.
Declaration
func /(lhs: Self, rhs: Self) > Self
Declared In
FloatingPoint
Divides the first value by the second and stores the quotient in the lefthandside variable, rounding to a representable value.
Parameters:
lhs: The value to divide.
rhs: The value to divide lhs
by.
Declaration
func /=(lhs: inout Self, rhs: Self)
Declared In
FloatingPoint
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
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func <(lhs: Self, rhs: Self) > Bool
Declared In
Comparable
Returns a Boolean value indicating whether the value of the first argument is less than or equal to that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func <=(lhs: Self, rhs: Self) > Bool
Declared In
Comparable
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
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func ==(lhs: Self, rhs: Self) > Bool
Declared In
Equatable
Returns a Boolean value indicating whether the value of the first argument is greater than that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func >(lhs: Self, rhs: Self) > Bool
Declared In
Comparable
Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func >=(lhs: Self, rhs: Self) > Bool
Declared In
Comparable
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
operand
: The value to negate.
Declaration
prefix func (operand: Self) > Self
Declared In
FloatingPoint
, SignedNumeric
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.
Parameters:
lhs: A numeric value.
rhs: The value to subtract from lhs
.
Declaration
func (lhs: Self, rhs: Self) > Self
Declared In
FloatingPoint
, Numeric
Subtracts the second value from the first and stores the difference in the lefthandside variable, rounding to a representable value.
Parameters:
lhs: A numeric value.
rhs: The value to subtract from lhs
.
Declaration
func =(lhs: inout Self, rhs: Self)
Declared In
FloatingPoint
, Numeric
Adds the product of the two given values to this value in place, computed without intermediate rounding.
Parameters: lhs: One of the values to multiply before adding to this value. rhs: The other value to multiply.
Declaration
mutating func addProduct(_ lhs: Self, _ rhs: Self)
Declared In
FloatingPoint
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.
Parameters:
lhs: One of the values to multiply before adding to this value.
rhs: The other value to multiply.
Returns: The product of lhs
and rhs
, added to this value.
Declaration
func addingProduct(_ lhs: Self, _ rhs: Self) > Self
Declared In
FloatingPoint
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.
n
: The distance to advance this value.
Returns: A value that is offset from this value by n
.
Complexity: O(1)
Declaration
func advanced(by n: Self.Stride) > Self
Declared In
Strideable
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.
other
: The value to calculate the distance to.
Returns: The distance from this value to other
.
Complexity: O(1)
Declaration
func distance(to other: Self) > Self.Stride
Declared In
Strideable
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
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:
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.
other
: The value to use when dividing this value.
Declaration
mutating func formRemainder(dividingBy other: Self)
Declared In
FloatingPoint
Replaces this value with its square root, rounded to a representable value.
Declaration
mutating func formSquareRoot()
Declared In
FloatingPoint
Replaces this value with the remainder of itself 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:
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.
other
: The value to use when dividing this value.
Declaration
mutating func formTruncatingRemainder(dividingBy other: Self)
Declared In
FloatingPoint
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
compiletime error in the future.
hasher
: The hasher to use when combining the components
of this instance.
Declaration
func hash(into hasher: inout Hasher)
Declared In
Hashable
Returns a Boolean value indicating whether this instance is equal to the given value.
This method serves as the basis for the equalto operator (==
) for
floatingpoint 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.
other
: The value to compare with this value.
Returns: true
if other
has the same value as this instance;
otherwise, false
. If either this value or other
is NaN, the result
of this method is false
.
Declaration
func isEqual(to other: Self) > Bool
Declared In
FloatingPoint
Returns a Boolean value indicating whether this instance is less than the given value.
This method serves as the basis for the lessthan operator (<
) for
floatingpoint values. Some special cases apply:
 Because NaN compares not less than nor greater than any value, this
method returns
false
when called on NaN or when NaN is passed asother
. infinity
compares less than all values except for itself and NaN.
Every value except for NaN and
+infinity
compares less than+infinity
.let x = 15.0 x.isLess(than: 20.0) // true x.isLess(than: .nan) // false Double.nan.isLess(than: x) // false
The isLess(than:)
method implements the lessthan predicate defined by
the IEEE 754 specification.
other
: The value to compare with this value.
Returns: true
if this value is less than other
; otherwise, false
.
If either this value or other
is NaN, the result of this method is
false
.
Declaration
func isLess(than other: Self) > Bool
Declared In
FloatingPoint
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 lessthanorequalto operator
(<=
) for floatingpoint values. Some special cases apply:
 Because NaN is incomparable with any value, this method returns
false
when called on NaN or when NaN is passed asother
. infinity
compares less than or equal to all values except NaN.
Every value except NaN compares less than or equal to
+infinity
.let x = 15.0 x.isLessThanOrEqualTo(20.0) // true x.isLessThanOrEqualTo(.nan) // false Double.nan.isLessThanOrEqualTo(x) // false
The isLessThanOrEqualTo(_:)
method implements the lessthanorequal
predicate defined by the IEEE 754 specification.
other
: The value to compare with this value.
Returns: true
if other
is greater than this value; otherwise,
false
. If either this value or other
is NaN, the result of this
method is false
.
Declaration
func isLessThanOrEqualTo(_ other: Self) > Bool
Declared In
FloatingPoint
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 lessthanorequalto 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 floatingpoint 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.
other
: A floatingpoint value to compare to this value.
Returns: true
if this value is ordered below or the same as other
in a total ordering of the floatingpoint type; otherwise, false
.
Declaration
func isTotallyOrdered(belowOrEqualTo other: Self) > Bool
Declared In
FloatingPoint
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
mutating func negate()
Declared In
FloatingPoint
, SignedNumeric
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.
other
: The value to use when dividing this value.
Returns: The remainder of this value divided by other
.
Declaration
func remainder(dividingBy other: Self) > Self
Declared In
FloatingPoint
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
rule
: The rounding rule to use.
Declaration
mutating func round(_ rule: FloatingPointRoundingRule)
Declared In
FloatingPoint
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"
rule
: The rounding rule to use.
Returns: The integral value found by rounding using rule
.
Declaration
func rounded(_ rule: FloatingPointRoundingRule) > Self
Declared In
FloatingPoint
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
Returns: The square root of the value.
Declaration
func squareRoot() > Self
Declared In
FloatingPoint
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.
other
: The value to use when dividing this value.
Returns: The remainder of this value divided by other
using
truncating division.
Declaration
func truncatingRemainder(dividingBy other: Self) > Self
Declared In
FloatingPoint
Default Implementations
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.
value
: The integer to convert to a floatingpoint value.
Declaration
init<Source>(_ value: Source)
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.
value
: A floatingpoint value to be converted.
Declaration
init<Source>(_ value: Source)
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.
value
: The value to create.
Declaration
init(integerLiteral value: Self)
Declared In
ExpressibleByIntegerLiteral
Creates a new floatingpoint 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.
Parameters:
signOf: A value from which to use the sign. The result of the
initializer has the same sign as signOf
.
magnitudeOf: A value from which to use the magnitude. The result of
the initializer has the same magnitude as magnitudeOf
.
Declaration
init(signOf: Self, magnitudeOf: Self)
Creates a new value, if the given integer can be represented exactly.
If the given integer cannot be represented exactly, the result is nil
.
value
: The integer to convert to a floatingpoint value.
Declaration
init?<Source>(exactly value: Source)
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.
value
: A floatingpoint value to be converted.
Declaration
init?<Source>(exactly value: Source)
The radix, or base of exponentiation, for this floatingpoint type.
All binary floatingpoint types have a radix of 2. The magnitude of a
floatingpoint value x
of type F
can be calculated by using the
following formula, where **
is exponentiation:
let magnitude = x.significand * F.radix ** x.exponent
Declaration
static var radix: Int { get }
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
static var ulpOfOne: Self { get }
Declared In
FloatingPoint
The classification of this value.
A value's floatingPointClass
property describes its "class" as
described by the IEEE 754 specification.
Declaration
var floatingPointClass: FloatingPointClassification { get }
Declared In
FloatingPoint
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:
 If
x
isinfinity
, thenx.nextDown
isgreatestFiniteMagnitude
.  If
x
isleastNonzeroMagnitude
, thenx.nextDown
is0.0
.  If
x
is zero, thenx.nextDown
isleastNonzeroMagnitude
.  If
x
isgreatestFiniteMagnitude
, thenx.nextDown
isinfinity
.
Declaration
var nextDown: Self { get }
Declared In
FloatingPoint
Returns a Boolean value indicating whether two values are not equal.
Inequality is the inverse of equality. For any values a
and b
, a != b
implies that a == b
is false
.
This is the default implementation of the notequalto operator (!=
)
for any type that conforms to Equatable
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func !=(lhs: Self, rhs: Self) > Bool
Declared In
Equatable
Returns the given number unchanged.
You can use the unary plus operator (+
) to provide symmetry in your
code for positive numbers when also using the unary minus operator.
let x = 21
let y = +21
// x == 21
// y == 21
Returns: The given argument without any changes.
Declaration
prefix func +(x: Self) > Self
Declared In
Numeric
Returns a partial range up to, and including, its upper bound.
Use the prefix closed range operator (prefix ...
) to create a partial
range of any type that conforms to the Comparable
protocol. This
example creates a PartialRangeThrough<Double>
instance that includes
any value less than or equal to 5.0
.
let throughFive = ...5.0
throughFive.contains(4.0) // true
throughFive.contains(5.0) // true
throughFive.contains(6.0) // false
You can use this type of partial range of a collection's indices to represent the range from the start of the collection up to, and including, the partial range's upper bound.
let numbers = [10, 20, 30, 40, 50, 60, 70]
print(numbers[...3])
// Prints "[10, 20, 30, 40]"
maximum
: The upper bound for the range.
Declaration
prefix func ...(maximum: Self) > PartialRangeThrough<Self>
Declared In
Comparable
Returns a closed range that contains both of its bounds.
Use the closed range operator (...
) to create a closed range of any type
that conforms to the Comparable
protocol. This example creates a
ClosedRange<Character>
from "a" up to, and including, "z".
let lowercase = "a"..."z"
print(lowercase.contains("z"))
// Prints "true"
Parameters: minimum: The lower bound for the range. maximum: The upper bound for the range.
Declaration
func ...(minimum: Self, maximum: Self) > ClosedRange<Self>
Declared In
Comparable
Returns a partial range up to, but not including, its upper bound.
Use the prefix halfopen range operator (prefix ..<
) to create a
partial range of any type that conforms to the Comparable
protocol.
This example creates a PartialRangeUpTo<Double>
instance that includes
any value less than 5.0
.
let upToFive = ..<5.0
upToFive.contains(3.14) // true
upToFive.contains(6.28) // false
upToFive.contains(5.0) // false
You can use this type of partial range of a collection's indices to represent the range from the start of the collection up to, but not including, the partial range's upper bound.
let numbers = [10, 20, 30, 40, 50, 60, 70]
print(numbers[..<3])
// Prints "[10, 20, 30]"
maximum
: The upper bound for the range.
Declaration
prefix func ..<(maximum: Self) > PartialRangeUpTo<Self>
Declared In
Comparable
Returns a halfopen range that contains its lower bound but not its upper bound.
Use the halfopen range operator (..<
) to create a range of any type
that conforms to the Comparable
protocol. This example creates a
Range<Double>
from zero up to, but not including, 5.0.
let lessThanFive = 0.0..<5.0
print(lessThanFive.contains(3.14)) // Prints "true"
print(lessThanFive.contains(5.0)) // Prints "false"
Parameters: minimum: The lower bound for the range. maximum: The upper bound for the range.
Declaration
func ..<(minimum: Self, maximum: Self) > Range<Self>
Declared In
Comparable
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
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func <(lhs: Self, rhs: Self) > Bool
Declared In
FloatingPoint
Returns a Boolean value indicating whether the value of the first argument is less than or equal to that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func <=(lhs: Self, rhs: Self) > Bool
Declared In
FloatingPoint
, Comparable
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
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func ==(lhs: Self, rhs: Self) > Bool
Declared In
FloatingPoint
Returns a Boolean value indicating whether the value of the first argument is greater than that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func >(lhs: Self, rhs: Self) > Bool
Declared In
FloatingPoint
, Comparable
Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
func >=(lhs: Self, rhs: Self) > Bool
Declared In
FloatingPoint
, Comparable
Returns the additive inverse of the specified value.
The negation operator (prefix 
) returns the additive inverse of its
argument.
let x = 21
let y = x
// y == 21
The resulting value must be representable in the same type as the argument. In particular, negating a signed, fixedwidth integer type's minimum results in a value that cannot be represented.
let z = Int8.min
// Overflow error
Returns: The additive inverse of the argument.
Declaration
prefix func (operand: Self) > Self
Declared In
SignedNumeric
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.
Parameters:
lhs: One of the values to multiply before adding to this value.
rhs: The other value to multiply.
Returns: The product of lhs
and rhs
, added to this value.
Declaration
func addingProduct(_ lhs: Self, _ rhs: Self) > Self
Declared In
FloatingPoint
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 lessthanorequalto 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 floatingpoint 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.
other
: A floatingpoint value to compare to this value.
Returns: true
if this value is ordered below or the same as other
in a total ordering of the floatingpoint type; otherwise, false
.
Declaration
func isTotallyOrdered(belowOrEqualTo other: Self) > Bool
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: The greater of x
and y
, or whichever is a number if the
other is NaN.
Declaration
static func maximum(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: Whichever of x
or y
has greater magnitude, or whichever is
a number if the other is NaN.
Declaration
static func maximumMagnitude(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: The minimum of x
and y
, or whichever is a number if the
other is NaN.
Declaration
static func minimum(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
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.
Parameters:
x: A floatingpoint value.
y: Another floatingpoint value.
Returns: Whichever of x
or y
has lesser magnitude, or whichever is
a number if the other is NaN.
Declaration
static func minimumMagnitude(_ x: Self, _ y: Self) > Self
Declared In
FloatingPoint
Replaces this value with its additive inverse.
The following example uses the negate()
method to negate the value of
an integer x
:
var x = 21
x.negate()
// x == 21
Declaration
mutating func negate()
Declared In
SignedNumeric
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.
other
: The value to use when dividing this value.
Returns: The remainder of this value divided by other
.
Declaration
func remainder(dividingBy other: Self) > Self
Declared In
FloatingPoint
Rounds this value to an integral value using "schoolbook rounding."
The round()
method uses the .toNearestOrAwayFromZero
rounding rule,
where a value halfway between two integral values is rounded to the one
with greater magnitude. The following example rounds several values
using this default rule:
var x = 5.2
x.round()
// x == 5.0
var y = 5.5
y.round()
// y == 6.0
var z = 5.5
z.round()
// z == 6.0
To specify an alternative rule for rounding, use the round(_:)
method
instead.
Declaration
mutating func round()
Declared In
FloatingPoint
Returns this value rounded to an integral value using "schoolbook rounding."
The rounded()
method uses the .toNearestOrAwayFromZero
rounding rule,
where a value halfway between two integral values is rounded to the one
with greater magnitude. The following example rounds several values
using this default rule:
(5.2).rounded()
// 5.0
(5.5).rounded()
// 6.0
(5.2).rounded()
// 5.0
(5.5).rounded()
// 6.0
To specify an alternative rule for rounding, use the rounded(_:)
method
instead.
Returns: The nearest integral value, or, if two integral values are equally close, the integral value with greater magnitude.
Declaration
func rounded() > Self
Declared In
FloatingPoint
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"
rule
: The rounding rule to use.
Returns: The integral value found by rounding using rule
.
Declaration
func rounded(_ rule: FloatingPointRoundingRule) > Self
Declared In
FloatingPoint
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
Returns: The square root of the value.
Declaration
func squareRoot() > Self
Declared In
FloatingPoint
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.
other
: The value to use when dividing this value.
Returns: The remainder of this value divided by other
using
truncating division.
Declaration
func truncatingRemainder(dividingBy other: Self) > Self
Declared In
FloatingPoint
Where RawSignificand : FixedWidthInteger, RawSignificand.Magnitude : UnsignedInteger, RawSignificand.Stride : SignedInteger
Returns a random value within the specified range.
Use this method to generate a floatingpoint value within a specific
range. This example creates three new values in the range
10.0...20.0
.
for _ in 1...3 {
print(Double.random(in: 10.0...20.0))
}
// Prints "18.1900709259179"
// Prints "14.2286325689993"
// Prints "13.1485686260762"
The random()
static method chooses a random value from a continuous
uniform distribution in range
, and then converts that value to the
nearest representable value in this type. Depending on the size and span
of range
, some concrete values may be represented more frequently than
others.
This method uses the default random generator, Random.default
. The call
to Double.random(in: 10.0...20.0)
above is equivalent to calling
Double.random(in: 10.0...20.0, using: &Random.default)
.
range
: The range in which to create a random value.
Returns: A random value within the bounds of range
.
Declaration
static func random(in range: ClosedRange<Self>) > Self
Returns a random value within the specified range.
Use this method to generate a floatingpoint value within a specific
range. This example creates three new values in the range
10.0..<20.0
.
for _ in 1...3 {
print(Double.random(in: 10.0..<20.0))
}
// Prints "18.1900709259179"
// Prints "14.2286325689993"
// Prints "13.1485686260762"
The random()
static method chooses a random value from a continuous
uniform distribution in range
, and then converts that value to the
nearest representable value in this type. Depending on the size and span
of range
, some concrete values may be represented more frequently than
others.
This method uses the default random generator, Random.default
. The call
to Double.random(in: 10.0..<20.0)
above is equivalent to calling
Double.random(in: 10.0..<20.0, using: &Random.default)
.
range
: The range in which to create a random value.
range
must not be empty.
Returns: A random value within the bounds of range
.
Declaration
static func random(in range: Range<Self>) > Self
Returns a random value within the specified range, using the given generator as a source for randomness.
Use this method to generate a floatingpoint value within a specific
range when you are using a custom random number generator. This example
creates three new values in the range 10.0...20.0
.
for _ in 1...3 {
print(Double.random(in: 10.0...20.0, using: &myGenerator))
}
// Prints "18.1900709259179"
// Prints "14.2286325689993"
// Prints "13.1485686260762"
The random(in:using:)
static method chooses a random value from a
continuous uniform distribution in range
, and then converts that value
to the nearest representable value in this type. Depending on the size and
span of range
, some concrete values may be represented more frequently
than others.
Parameters:
range: The range in which to create a random value.
generator: The random number generator to use when creating the
new random value.
Returns: A random value within the bounds of range
.
Declaration
static func random<T>(in range: ClosedRange<Self>, using generator: inout T) > Self where T : RandomNumberGenerator
Returns a random value within the specified range, using the given generator as a source for randomness.
Use this method to generate a floatingpoint value within a specific
range when you are using a custom random number generator. This example
creates three new values in the range 10.0..<20.0
.
for _ in 1...3 {
print(Double.random(in: 10.0..<20.0, using: &myGenerator))
}
// Prints "18.1900709259179"
// Prints "14.2286325689993"
// Prints "13.1485686260762"
The random(in:using:)
static method chooses a random value from a
continuous uniform distribution in range
, and then converts that value
to the nearest representable value in this type. Depending on the size and
span of range
, some concrete values may be represented more frequently
than others.
Parameters:
range: The range in which to create a random value.
range
must not be empty.
generator: The random number generator to use when creating the
new random value.
Returns: A random value within the bounds of range
.
Declaration
static func random<T>(in range: Range<Self>, using generator: inout T) > Self where T : RandomNumberGenerator
Where Stride : SignedInteger
Returns a countable closed range that contains both of its bounds.
Use the closed range operator (...
) to create a closed range of any type
that conforms to the Strideable
protocol with an associated signed
integer Stride
type, such as any of the standard library's integer
types. This example creates a ClosedRange<Int>
from zero up to,
and including, nine.
let singleDigits = 0...9
print(singleDigits.contains(9))
// Prints "true"
You can use sequence or collection methods on the singleDigits
range.
print(singleDigits.count)
// Prints "10"
print(singleDigits.last)
// Prints "9"
Parameters:)`. minimum: The lower bound for the range. maximum: The upper bound for the range.
Declaration
func ...(minimum: Self, maximum: Self) > ClosedRange<Self>
Declared In
Strideable
A radix2 (binary) floatingpoint type.
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.