# FloatingPointApproximation

A correct way to determine if two floating-point numbers are approximately equal to one another.

This functionality is discussed in Chapter 3 of Flight School Guide to Swift Numbers.

## Requirements

- Swift 4.0+

## Installation

### Swift Package Manager

Add the FloatingPointApproximation package to your target dependencies in `Package.swift`

:

```
import PackageDescription
let package = Package(
name: "YourProject",
dependencies: [
.package(
url: "https://github.com/Flight-School/FloatingPointApproximation",
from: "1.0.0"
),
]
)
```

Then run the `swift build`

command to build your project.

### Carthage

To use `FloatingPointApproximation`

in your Xcode project using Carthage,
specify it in `Cartfile`

:

```
github "Flight-School/FloatingPointApproximation" ~> 1.0.0
```

Then run the `carthage update`

command to build the framework,
and drag the built FloatingPointApproximation.framework into your Xcode project.

## Usage

Floating-point arithmetic can produce unexpected results,
such as `0.1 + 0.2 != 0.3`

.
The reason for this is that many fractional numbers,
including `0.1`

, `0.2`

, and `0.3`

,
cannot be precisely expressed in a binary number representation.

A common mistake is to use an arbitrarily small constant
(such as `.ulpOfOne`

)
to determine whether two floating-point numbers are approximately equal.
For example:

```
let actual = 0.1 + 0.2
let expected = 0.3
abs(expected - actual) < .ulpOfOne // true
```

However, this doesn't work for large scale numbers:

```
let actual = 1e25 + 2e25
let expected = 3e25
abs(expected - actual) < .ulpOfOne // false
```

A better approach for determining approximate equality would be to count how many representable values, or ULPs, exist between two floating-point numbers.

The `==~`

operator (and its complement, `!=~`

)
defined by this package
returns a Boolean value indicating whether
two floating-point numbers are approximately equal.

```
import FloatingPointApproximation
0.1 + 0.2 == 0.3 // false
0.1 + 0.2 ==~ 0.3 // true
```

Floating-point numbers are defined to be approximately equal
if they are within one *unit of least precision*, or
ULP,
of one another.

Because of how Swift implements floating-point numbers,
the implementation of the `==~`

operator is quite simple:

```
func ==~<T> (lhs: T, rhs: T) -> Bool where T: FloatingPoint {
return lhs == rhs || lhs.nextDown == rhs || lhs.nextUp == rhs
}
```

A more complete approach combines both absolute and relative comparisons.
The `isApproximatelyEqual(to:within:maximumULPs:)`

method
determines whether a floating-point number
is approximately equal to another value
by first checking to see if it is within a given absolute margin, if provided,
and then checking to see if it falls within a given number of ULPs:

```
import FloatingPointApproximation
(0.1 + 0.2).isApproximatelyEqual(to: 0.3, within: 1e-12, maximumULPs: 2)
```

Ultimately, it's your responsibility to determine how to compare two floating-point numbers for approximate equality based on the requirements of your domain.

## License

MIT

## Contact

Mattt (@mattt)