Double

struct Double

A double-precision, floating-point value type.

Inheritance AbsoluteValuable, BinaryFloatingPoint, Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, CustomStringConvertible, Equatable, ExpressibleByFloatLiteral, ExpressibleByIntegerLiteral, FloatingPoint, Hashable, LosslessStringConvertible, SignedNumber, Strideable View Protocol Hierarchy →
Associated Types
Exponent = Int

A type that can represent any written exponent.

RawSignificand = UInt64

A type that can represent the encoded significand of a value.

Import import Swift

Initializers

init()

Creates a value initialized to zero.

Declaration

init()
init(_: Double)

Creates a new instance initialized to the given value.

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

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

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

other: The value to use for the new instance.

Declaration

init(_ other: Double)
init(_: Float)

Creates a new instance that approximates the given value.

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

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

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

other: The value to use for the new instance.

Declaration

init(_ other: Float)
init(_: Float80)

Creates a new instance that approximates the given value.

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

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

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

other: The value to use for the new instance.

Declaration

init(_ other: Float80)
init(_: Int)

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

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 floating-point value.

Declaration

init(_ v: Int)
init(_: Int8)

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

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 floating-point value.

Declaration

init(_ v: Int8)
init(_: Int16)

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

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 floating-point value.

Declaration

init(_ v: Int16)
init(_: Int32)

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

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 floating-point value.

Declaration

init(_ v: Int32)
init(_: Int64)

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

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 floating-point value.

Declaration

init(_ v: Int64)
init(_: NSNumber)

[Foundation]

Declaration

init(_ number: NSNumber)
init(_: UInt)

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

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 floating-point value.

Declaration

init(_ v: UInt)
init(_: UInt8)

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

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 floating-point value.

Declaration

init(_ v: UInt8)
init(_: UInt16)

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

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 floating-point value.

Declaration

init(_ v: UInt16)
init(_: UInt32)

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

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 floating-point value.

Declaration

init(_ v: UInt32)
init(_: UInt64)

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

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 floating-point value.

Declaration

init(_ v: UInt64)
init(bitPattern:)

Creates a new value with the given bit pattern.

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

bitPattern: The integer encoding of a Double instance.

See Also: bitPattern

Declaration

init(bitPattern: UInt64)
init(floatLiteral:)

Creates a new value from the given floating-point literal.

Do not call this initializer directly. It is used by the compiler when you create a new Double instance by using a floating-point literal. Instead, create a new value by using a literal.

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

let x: Double = 21.25
// x == 21.25

value: The new floating-point value.

Declaration

init(floatLiteral value: Double)
init(integerLiteral:)

Creates a new value from the given integer literal.

Do not call this initializer directly. It is used by the compiler when you create a new Double instance by using an integer literal. Instead, create a new value by using a literal.

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

let x: Double = 100
// x == 100.0

value: The new value.

Declaration

init(integerLiteral value: Int64)
init(nan:signaling:)

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

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

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

Parameters: payload: The payload to use for the new NaN value. signaling: Pass true to create a signaling NaN or false to create a quiet NaN.

Declaration

init(nan payload: Double.RawSignificand, signaling: Bool)
init(sign:exponent:significand:)

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

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

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

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

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

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

  • If the value you pass to significand is zero or infinite, the result is zero or infinite, regardless of the value of exponent.
  • If the value you pass to significand is NaN, the result is NaN.

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

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

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

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: Int, significand: Double)
init(sign:exponentBitPattern:significandBitPattern:)

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: UInt, significandBitPattern: UInt64)
init(signOf:magnitudeOf:)

Creates a new floating-point value using the sign of one value and the magnitude of another.

The following example uses this initializer to create a new Double instance with the sign of a and the magnitude of b:

let a = -21.5
let b = 305.15
let c = Double(signOf: a, magnitudeOf: b)
print(c)
// Prints "-305.15"

This initializer implements the IEEE 754 copysign operation.

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: Double, magnitudeOf: Double)

Declared In

BinaryFloatingPoint
init?(_:)

Creates a new instance from the given string.

The string passed as text can represent a real number in decimal or hexadecimal format or special floating-point values for infinty and NaN ("not a number").

The given string may begin with a plus or minus sign character (+ or -). The allowed formats for each of these representations is then as follows:

  • A decimal value contains the significand, a sequence of decimal digits that may include a decimal point.

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

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

    A decimal value may also include an exponent following the significand, indicating the power of 10 by which the significand should be multiplied. If included, the exponent is separated by a single character, e or E, and consists of an optional plus or minus sign character and a sequence of decimal digits.

    let e = Double("2837.5e-2") // e == 28.375

  • A hexadecimal value contains the significand, either 0X or 0x, followed by a sequence of hexadecimal digits. The significand may include a decimal point.

    let f = Double("0x1c.6") // f == 28.375

    A hexadecimal value may also include an exponent following the significand, indicating the power of 2 by which the significand should be multiplied. If included, the exponent is separated by a single character, p or P, and consists of an optional plus or minus sign character and a sequence of decimal digits.

    let g = Double("0x1.c6p4") // g == 28.375

  • A value of infinity contains one of the strings "inf" or "infinity", case insensitive.

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

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

  • A value of NaN contains the string "nan", case insensitive.

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

    An NaN value may also include a payload in parentheses following the "nan" keyword. The payload consists of a sequence of decimal digits, or the characters 0X or 0x followed by a sequence of hexadecimal digits. If the payload contains any other characters, it is ignored. If the value of the payload is larger than can be stored as the payload of a Double.nan, the least significant bits are used.

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

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

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

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

Declaration

init?(_ text: String)
init?(exactly: Double)

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

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

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

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

other: The value to use for the new instance.

Declaration

init?(exactly other: Double)
init?(exactly: Float)

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

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

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

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

other: The value to use for the new instance.

Declaration

init?(exactly other: Float)
init?(exactly: Float80)

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

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

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

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

other: The value to use for the new instance.

Declaration

init?(exactly other: Float80)

Static Variables

static var exponentBitCount: 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 exponentation:

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

static var exponentBitCount: Int { get }
static var greatestFiniteMagnitude: Double

The greatest finite number representable by this type.

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

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

Declaration

static var greatestFiniteMagnitude: Double { get }
static var infinity: Double

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: Double { get }
static var leastNonzeroMagnitude: Double

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: Double { get }
static var leastNormalMagnitude: Double

The least positive normal number.

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

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

Declaration

static var leastNormalMagnitude: Double { get }
static var nan: Double

A quiet NaN ("not a number").

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

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

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

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

See Also: isNaN, signalingNaN

Declaration

static var nan: Double { get }
static var pi: Double

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: Double { get }
static var radix: Int

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

All binary floating-point types have a radix of 2. The magnitude of a floating-point value x of type F can be calculated by using the following formula, where ** is exponentiation:

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

Declaration

static var radix: Int { get }

Declared In

BinaryFloatingPoint
static var signalingNaN: Double

A signaling NaN ("not a number").

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

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

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

See Also: nan

Declaration

static var signalingNaN: Double { get }
static var significandBitCount: 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

static var significandBitCount: Int { get }
static var ulpOfOne: Double

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: Double { get }

Declared In

BinaryFloatingPoint , FloatingPoint

Instance Variables

var binade: Double

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: Double { get }
var bitPattern: UInt64

The bit pattern of the value's encoding.

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

See Also: init(bitPattern:)

Declaration

var bitPattern: UInt64 { get }
var customMirror: Mirror

A mirror that reflects the Double instance.

Declaration

var customMirror: Mirror { get }
var customPlaygroundQuickLook: PlaygroundQuickLook

A custom playground Quick Look for this instance.

If this type has value semantics, the PlaygroundQuickLook instance should be unaffected by subsequent mutations.

Declaration

var customPlaygroundQuickLook: PlaygroundQuickLook { get }
var debugDescription: String

A textual representation of the value, suitable for debugging.

Declaration

var debugDescription: String { get }
var description: String

A textual representation of the value.

Declaration

var description: String { get }
var exponent: Int

The exponent of the floating-point value.

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

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

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

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

The exponent property has the following edge cases:

  • If x is zero, then x.exponent is Int.min.
  • If x is +/-infinity or NaN, then x.exponent is Int.max

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

Declaration

var exponent: Int { get }
var exponentBitPattern: UInt

The raw encoding of the value's exponent field.

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

See Also: exponentBitCount

Declaration

var exponentBitPattern: UInt { get }
var floatingPointClass: FloatingPointClassification

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

BinaryFloatingPoint , FloatingPoint
var hashValue: Int

The number's 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 }
var isCanonical: Bool

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 floating-point 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 }
var isFinite: Bool

A Boolean value indicating whether this instance is finite.

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

Declaration

var isFinite: Bool { get }
var isInfinite: Bool

A Boolean value indicating whether the instance is infinite.

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

Declaration

var isInfinite: Bool { get }
var isNaN: Bool

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

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

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

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

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

This property is true for both quiet and signaling NaNs.

Declaration

var isNaN: Bool { get }
var isNormal: Bool

A Boolean value indicating whether this instance is normal.

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

Declaration

var isNormal: Bool { get }
var isSignalingNaN: Bool

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

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

Declaration

var isSignalingNaN: Bool { get }
var isSubnormal: Bool

A Boolean value indicating whether the instance is subnormal.

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

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

Declaration

var isSubnormal: Bool { get }
var isZero: Bool

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

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

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

Declaration

var isZero: Bool { get }
var nextDown: Double

The greatest representable value that compares less than this value.

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

  • If x is infinity, then x.nextDown is greatestFiniteMagnitude.
  • If x is leastNonzeroMagnitude, then x.nextDown is 0.0.
  • If x is zero, then x.nextDown is -leastNonzeroMagnitude.
  • If x is -greatestFiniteMagnitude, then x.nextDown is -infinity.

Declaration

var nextDown: Double { get }

Declared In

BinaryFloatingPoint , FloatingPoint
var nextUp: Double

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 is -infinity, then x.nextUp is -greatestFiniteMagnitude.
  • If x is -leastNonzeroMagnitude, then x.nextUp is -0.0.
  • If x is zero, then x.nextUp is leastNonzeroMagnitude.
  • If x is greatestFiniteMagnitude, then x.nextUp is infinity.

Declaration

var nextUp: Double { get }
var sign: FloatingPointSign

The sign of the floating-point value.

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

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

Don't 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 }
var significand: Double

The significand of the floating-point value.

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

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

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

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

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

  • If x is zero, then x.significand is 0.0.
  • If x is infinity, then x.significand is 1.0.
  • If x is NaN, then x.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: Double { get }
var significandBitPattern: UInt64

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: UInt64 { get }
var significandWidth: Int

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, because significand is 1.0.
  • If x is 10, x.significand is 1.01 in binary, so x.significandWidth is 2.
  • If x is Float.pi, x.significand is 1.10010010000111111011011 in binary, and x.significandWidth is 23.

Declaration

var significandWidth: Int { get }
var ulp: Double

The unit in the last place of self.

This is the unit of the least significant digit in the significand of self. 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:

  • greatestFiniteMagnitude.ulp is a finite number, even though the next greater representable value is infinity.
  • x.ulp is NaN if x is not a finite number.
  • If x is very small in magnitude, then x.ulp may be a subnormal number. On targets that do not support subnormals, x.ulp may be rounded to zero.

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: Double { get }

Static Methods

static func abs(_:)

The magnitude of this value.

For any value x, x.magnitude.sign is .plus. If x is not NaN, x.magnitude is the absolute value of x.

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.

let targetDistance: Double = 5.25
let throwDistance: Double = 5.5

let margin = targetDistance - throwDistance
// margin == -0.25
// margin.magnitude == 0.25

// Use 'abs(_:)' instead of 'magnitude'
print("Missed the target by \(abs(margin)) meters.")
// Prints "Missed the target by 0.25 meters."

See Also: abs(_:)

Declaration

static func abs(_ x: Double) -> Double
static func maximum(_:_:)

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 floating-point value. y: Another floating-point value. Returns: The greater of x and y, or whichever is a number if the other is NaN.

Declaration

static func maximum(_ x: Double, _ y: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
static func maximumMagnitude(_:_:)

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 floating-point value. y: Another floating-point 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: Double, _ y: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
static func minimum(_:_:)

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 floating-point value. y: Another floating-point value. Returns: The minimum of x and y, or whichever is a number if the other is NaN.

Declaration

static func minimum(_ x: Double, _ y: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
static func minimumMagnitude(_:_:)

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 floating-point value. y: Another floating-point 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: Double, _ y: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint

Instance Methods

mutating func add(_:)

Adds the given value to this value in place, rounded to a representable value.

This method serves as the basis for the in-place addition operator (+=). For example:

var (x, y) = (2.25, 2.25)
x.add(7.0)
// x == 9.25
y += 7.0
// y == 9.25

other: The value to add.

See Also: adding(_:)

Declaration

mutating func add(_ other: Double)
mutating func addProduct(_:_:)

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: Double, _ rhs: Double)
func adding(_:)

Returns the sum of this value and the given value, rounded to a representable value.

This method serves as the basis for the addition operator (+). For example:

let x = 1.5
print(x.adding(2.25))
// Prints "3.75"
print(x + 2.25)
// Prints "3.75"

The adding(_:) method implements the addition operation defined by the IEEE 754 specification.

other: The value to add. Returns: The sum of this value and other, rounded to a representable value.

See Also: add(_:)

Declaration

func adding(_ other: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func addingProduct(_:_:)

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: Double, _ rhs: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func advanced(by:)

Returns a new value advanced by the given distance.

For two values x and d, the result of a x.advanced(by: d) is equal to x + d---a new value y such that x.distance(to: y) approximates d. For example:

let x = 21.5
let y = x.advanced(by: -6.5)
// y == 15.0

print(x.distance(to: y))
// Prints "-6.5"

amount: The distance to advance this value. Returns: A new value that is amount added to this value.

Declaration

func advanced(by amount: Double) -> Double
func distance(to:)

Returns the distance from this value to the specified value.

For two values x and y, the result of x.distance(to: y) is equal to y - x---a distance d such that x.advanced(by: d) approximates y. For example:

let x = 21.5
let d = x.distance(to: 15.0)
// d == -6.5

print(x.advanced(by: d))
// Prints "15.0"

other: A value to calculate the distance to. Returns: The distance between this value and other.

Declaration

func distance(to other: Double) -> Double
mutating func divide(by:)

Divides this value by the given value in place, rounding to a representable value.

This method serves as the basis for the in-place division operator (/=). For example:

var (x, y) = (16.875, 16.875)
x.divide(by: 2.25)
// x == 7.5
y /= 2.25
// y == 7.5

other: The value to use when dividing this value.

See Also: divided(by:)

Declaration

mutating func divide(by other: Double)
func divided(by:)

Returns the quotient of this value and the given value, rounded to a representable value.

This method serves as the basis for the division operator (/). For example:

let x = 7.5
let y = x.divided(by: 2.25)
// y == 16.875
let z = x * 2.25
// z == 16.875

The divided(by:) method implements the division operation defined by the IEEE 754 specification.

other: The value to use when dividing this value. Returns: The quotient of this value and other, rounded to a representable value.

See Also: divide(by:)

Declaration

func divided(by other: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
mutating func formRemainder(dividingBy:)

Replaces this value with the remainder of itself divided by the given value.

For two finite values x and y, the remainder r of dividing x by y satisfies x == y * q + r, where q is the integer nearest to x / y. If x / y is exactly halfway between two integers, q is chosen to be even. Note that q is not x / y computed in floating-point arithmetic, and that q may not be representable in any available integer type.

The following example calculates the remainder of dividing 8.625 by 0.75:

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

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

let x1 = 0.75 * q + x
// x1 == 8.625

If this value and other are finite numbers, the remainder is in the closed range -abs(other / 2)...abs(other / 2). The remainder(dividingBy:) method is always exact.

other: The value to use when dividing this value.

See Also: remainder(dividingBy:), formTruncatingRemainder(dividingBy:)

Declaration

mutating func formRemainder(dividingBy other: Double)
mutating func formSquareRoot()

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

See Also: sqrt(_:), squareRoot()

Declaration

mutating func formSquareRoot()
mutating func formTruncatingRemainder(dividingBy:)

Replaces this value with the remainder of itself divided by the given value using truncating division.

Performing truncating division with floating-point values results in a truncated integer quotient and a remainder. For values x and y and their truncated integer quotient q, the remainder r satisfies x == y * q + r.

The following example calculates the truncating remainder of dividing 8.625 by 0.75:

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

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

let x1 = 0.75 * q + x
// x1 == 8.625

If this value and other are both finite numbers, the truncating remainder has the same sign as other and is strictly smaller in magnitude. The formtruncatingRemainder(dividingBy:) method is always exact.

other: The value to use when dividing this value.

See Also: truncatingRemainder(dividingBy:), formRemainder(dividingBy:)

Declaration

mutating func formTruncatingRemainder(dividingBy other: Double)
func isEqual(to:)

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

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

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

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

other: The value to compare with this value. Returns: true if other has the same value as this instance; otherwise, false.

Declaration

func isEqual(to other: Double) -> Bool
func isLess(than:)

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

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

  • Because NaN compares not less than nor greater than any value, this method returns false when called on NaN or when NaN is passed as other.
  • -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 less-than predicate defined by the IEEE 754 specification.

other: The value to compare with this value. Returns: true if other is less than this value; otherwise, false.

Declaration

func isLess(than other: Double) -> Bool
func isLessThanOrEqualTo(_:)

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

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

  • Because NaN is incomparable with any value, this method returns false when called on NaN or when NaN is passed as other.
  • -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 less-than-or-equal predicate defined by the IEEE 754 specification.

other: The value to compare with this value. Returns: true if other is less than this value; otherwise, false.

Declaration

func isLessThanOrEqualTo(_ other: Double) -> Bool
func isTotallyOrdered(belowOrEqualTo:)

Returns a Boolean value indicating whether this instance should precede the given value in an ascending sort.

This relation is a refinement of the less-than-or-equal-to operator (<=) that provides a total order on all values of the type, including noncanonical encodings, signed zeros, and NaNs. Because it is used much less frequently than the usual comparisons, there is no operator form of this relation.

The following example uses isTotallyOrdered(below:) to sort an array of floating-point values, including some that are NaN:

var numbers = [2.5, 21.25, 3.0, .nan, -9.5]
numbers.sort { $0.isTotallyOrdered(below: $1) }
// 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 floating-point value to compare to this value. Returns: true if this value is ordered below other in a total ordering of the floating-point type; otherwise, false.

Declaration

func isTotallyOrdered(belowOrEqualTo other: Double) -> Bool

Declared In

BinaryFloatingPoint
func multiplied(by:)

Returns the product of this value and the given value, rounded to a representable value.

This method serves as the basis for the multiplication operator (*). For example:

let x = 7.5
print(x.multiplied(by: 2.25))
// Prints "16.875"
print(x * 2.25)
// Prints "16.875"

The multiplied(by:) method implements the multiplication operation defined by the IEEE 754 specification.

other: The value to multiply by this value. Returns: The product of this value and other, rounded to a representable value.

See Also: multiply(by:)

Declaration

func multiplied(by other: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
mutating func multiply(by:)

Multiplies this value by the given value in place, rounding to a representable value.

This method serves as the basis for the in-place multiplication operator (*=). For example:

var (x, y) = (7.5, 7.5)
x.multiply(by: 2.25)
// x == 16.875
y *= 2.25
// y == 16.875

other: The value to multiply by this value.

See Also: multiplied(by:)

Declaration

mutating func multiply(by other: Double)
mutating func negate()

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

See Also: negated()

Declaration

mutating func negate()
func negated()

Returns the additive inverse of this value.

The result is always exact. This method serves as the basis for the negation operator (prefixed -). For example:

let x = 21.5
let y = x.negated()
// y == -21.5

Returns: The additive inverse of this value.

See Also: negate()

Declaration

func negated() -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func remainder(dividingBy:)

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.

other: The value to use when dividing this value. Returns: The remainder of this value divided by other.

See Also: formRemainder(dividingBy:), truncatingRemainder(dividingBy:)

Declaration

func remainder(dividingBy rhs: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
mutating func round()

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.

See Also: round(_:), rounded(), FloatingPointRoundingRule

Declaration

mutating func round()

Declared In

BinaryFloatingPoint, FloatingPoint
mutating func round(_:)

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.

See Also: round(), rounded(_:), FloatingPointRoundingRule

Declaration

mutating func round(_ rule: FloatingPointRoundingRule)
func rounded()

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.

See Also: rounded(_:), round(), FloatingPointRoundingRule

Declaration

func rounded() -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func rounded(_:)

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.

See Also: rounded(), round(_:), FloatingPointRoundingRule

Declaration

func rounded(_ rule: FloatingPointRoundingRule) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func squareRoot()

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.

See Also: sqrt(_:), formSquareRoot()

Declaration

func squareRoot() -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
mutating func subtract(_:)

Subtracts the given value from this value in place, rounding to a representable value.

This method serves as the basis for the in-place subtraction operator (-=). For example:

var (x, y) = (7.5, 7.5)
x.subtract(2.25)
// x == 5.25
y -= 2.25
// y == 5.25

other: The value to subtract.

See Also: subtracting(_:)

Declaration

mutating func subtract(_ other: Double)
func subtracting(_:)

Returns the difference of this value and the given value, rounded to a representable value.

This method serves as the basis for the subtraction operator (-). For example:

let x = 7.5
print(x.subtracting(2.25))
// Prints "5.25"
print(x - 2.25)
// Prints "5.25"

The subtracting(_:) method implements the addition operation defined by the IEEE 754 specification.

other: The value to subtract from this value. Returns: The difference of this value and other, rounded to a representable value.

See Also: subtract(_:)

Declaration

func subtracting(_ other: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint
func truncatingRemainder(dividingBy:)

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 other and is strictly smaller in magnitude. 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.

See Also: formTruncatingRemainder(dividingBy:), remainder(dividingBy:)

Declaration

func truncatingRemainder(dividingBy other: Double) -> Double

Declared In

BinaryFloatingPoint, FloatingPoint