# FloatingPoint

A floating-point numeric type.

`protocol FloatingPoint : Hashable, SignedNumeric, Strideable where Self == Self.Magnitude`

## Overview

Floating-point types are used to represent fractional numbers, like 5.5, 100.0, or 3.14159274. Each floating-point type has its own possible range and precision. The floating-point types in the standard library are `Float`

, `Double`

, and `Float80`

where available.

Create new instances of floating-point types using integer or floating-point literals. For example:

```
let temperature = 33.2
let recordHigh = 37.5
```

The `FloatingPoint`

protocol declares common arithmetic operations, so you can write functions and algorithms that work on any floating-point type. The following example declares a function that calculates the length of the hypotenuse of a right triangle given its two perpendicular sides. Because the `hypotenuse(_:_:)`

function uses a generic parameter constrained to the `FloatingPoint`

protocol, you can call it using any floating-point type.

```
func hypotenuse<T: FloatingPoint>(_ a: T, _ b: T) -> T {
return (a * a + b * b).squareRoot()
}
let (dx, dy) = (3.0, 4.0)
let distance = hypotenuse(dx, dy)
// distance == 5.0
```

Floating-point values are represented as a *sign* and a *magnitude*, where the magnitude is calculated using the type’s *radix* and the instance’s *significand* and *exponent*. This magnitude calculation takes the following form for a floating-point value `x`

of type `F`

, where `**`

is exponentiation:

`x.significand * F.radix ** x.exponent`

Here’s an example of the number -8.5 represented as an instance of the `Double`

type, which defines a radix of 2.

```
let y = -8.5
// y.sign == .minus
// y.significand == 1.0625
// y.exponent == 3
let magnitude = 1.0625 * Double(2 ** 3)
// magnitude == 8.5
```

Types that conform to the `FloatingPoint`

protocol provide most basic (clause 5) operations of the IEEE 754 specification. The base, precision, and exponent range are not fixed in any way by this protocol, but it enforces the basic requirements of any IEEE 754 floating-point type.

## Additional Considerations

In addition to representing specific numbers, floating-point types also have special values for working with overflow and nonnumeric results of calculation.

### Infinity

Any value whose magnitude is so great that it would round to a value outside the range of representable numbers is rounded to *infinity*. For a type `F`

, positive and negative infinity are represented as `F.infinity`

and `-F.infinity`

, respectively. Positive infinity compares greater than every finite value and negative infinity, while negative infinity compares less than every finite value and positive infinity. Infinite values with the same sign are equal to each other.

```
let values: [Double] = [10.0, 25.0, -10.0, .infinity, -.infinity]
print(values.sorted())
// Prints "[-inf, -10.0, 10.0, 25.0, inf]"
```

Operations with infinite values follow real arithmetic as much as possible: Adding or subtracting a finite value, or multiplying or dividing infinity by a nonzero finite value, results in infinity.

### NaN (“not a number”)

Floating-point types represent values that are neither finite numbers nor infinity as NaN, an abbreviation for “not a number.” Comparing a NaN with any value, including another NaN, results in `false`

.

```
let myNaN = Double.nan
print(myNaN > 0)
// Prints "false"
print(myNaN < 0)
// Prints "false"
print(myNaN == .nan)
// Prints "false"
```

Because testing whether one NaN is equal to another NaN results in `false`

, use the `isNaN`

property to test whether a value is NaN.

```
print(myNaN.isNaN)
// Prints "true"
```

NaN propagates through many arithmetic operations. When you are operating on many values, this behavior is valuable because operations on NaN simply forward the value and don’t cause runtime errors. The following example shows how NaN values operate in different contexts.

Imagine you have a set of temperature data for which you need to report some general statistics: the total number of observations, the number of valid observations, and the average temperature. First, a set of observations in Celsius is parsed from strings to `Double`

values:

```
let temperatureData = ["21.5", "19.25", "27", "no data", "28.25", "no data", "23"]
let tempsCelsius = temperatureData.map { Double($0) ?? .nan }
print(tempsCelsius)
// Prints "[21.5, 19.25, 27, nan, 28.25, nan, 23.0]"
```

Note that some elements in the `temperatureData `

array are not valid numbers. When these invalid strings are parsed by the `Double`

failable initializer, the example uses the nil-coalescing operator (`??`

) to provide NaN as a fallback value.

Next, the observations in Celsius are converted to Fahrenheit:

```
let tempsFahrenheit = tempsCelsius.map { $0 * 1.8 + 32 }
print(tempsFahrenheit)
// Prints "[70.7, 66.65, 80.6, nan, 82.85, nan, 73.4]"
```

The NaN values in the `tempsCelsius`

array are propagated through the conversion and remain NaN in `tempsFahrenheit`

.

Because calculating the average of the observations involves combining every value of the `tempsFahrenheit`

array, any NaN values cause the result to also be NaN, as seen in this example:

```
let badAverage = tempsFahrenheit.reduce(0.0, +) / Double(tempsFahrenheit.count)
// badAverage.isNaN == true
```

Instead, when you need an operation to have a specific numeric result, filter out any NaN values using the `isNaN`

property.

```
let validTemps = tempsFahrenheit.filter { !$0.isNaN }
let average = validTemps.reduce(0.0, +) / Double(validTemps.count)
```

Finally, report the average temperature and observation counts:

```
print("Average: \(average)°F in \(validTemps.count) " +
"out of \(tempsFahrenheit.count) observations.")
// Prints "Average: 74.84°F in 5 out of 7 observations."
```