Unreachable: A Swift repository from nvzqz

Unreachable is a Swift µframework that allows for letting the compiler know when a code path is unreachable.

Build Status
Installation
Usage
License

Build Status

Branch	Status
`master`

Installation

Compatibility

Platforms:
- macOS 10.9+
- iOS 8.0+
- watchOS 2.0+
- tvOS 9.0+
- Linux
Xcode 8.0+
Swift 3.0+ & 4.0

Install Using Swift Package Manager

The Swift Package Manager is a decentralized dependency manager for Swift.

Add the project to your Package.swift.

import PackageDescription

let package = Package(
    name: "MyAwesomeProject",
    dependencies: [
        .Package(url: "https://github.com/nvzqz/Unreachable.git",
                 majorVersion: 1)
    ]
)

Import the Unreachable module.
```
import Unreachable
```

Install Using CocoaPods

CocoaPods is a centralized dependency manager for Objective-C and Swift. Go here to learn more.

Add the project to your Podfile.

use_frameworks!

pod 'Unreachable', '~> 1.2.0'

If you want to be on the bleeding edge, replace the last line with:

pod 'Unreachable', :git => 'https://github.com/nvzqz/Unreachable.git'

Run pod install and open the .xcworkspace file to launch Xcode.
Import the Unreachable framework.
```
import Unreachable
```

Install Using Carthage

Carthage is a decentralized dependency manager for Objective-C and Swift.

Add the project to your Cartfile.
```
github "nvzqz/Unreachable"
```
Run carthage update and follow the additional steps in order to add Unreachable to your project.
Import the Unreachable framework.
```
import Unreachable
```

Install Manually

Simply add Unreachable.swift into your project.

Usage

Try it out for yourself! Download the repo and open 'Unreachable.playground'.

Dynamic Loop Exit

In some cases, the only way a function returns a value is from within a loop, but the compiler may not have enough information to know that.

func getValue() -> Int {
    for i in 0... {
        if i == 20 {
            return i
        }
    }
    assertUnreachable()
}

Switch Conditions

A switch statement may have conditions applied to its branches that make it exhaustive, but that may not obvious to the compiler.

func sign(of value: Double?) -> FloatingPointSign? {
    switch value {
    case let x? where x >= 0:
        return .plus
    case let x? where x < 0:
        return .minus
    case .some:
        assertUnreachable()
    case .none:
        return nil
    }
}

Safety

It is undefined behavior for unreachable() to be called. To protect against this, it is recommended to use assertUnreachable() instead.

With assertUnreachable(), debug builds will exit via a fatal error if the function is called. In optimized builds, it's no different than calling unreachable().

Unreachable vs `fatalError()`

The assertUnreachable() function can be used as somewhat of a drop-in replacement for fatalError(). In debug mode, they emit similar instructions. However, when compiling with optimizations, assertUnreachable() allows its parent to emit very few instructions.

Here we're checking whether a UnicodeScalar has a value in the lower or upper range. Because we know that these are the only valid ranges, we can let the compiler know that the third branch is unreachable. If at some point x has a value that's not within either range, it will emit an assertion failure in unoptimized builds.

With Unreachable

func isLowerRange(_ x: UnicodeScalar) -> Bool {
    switch x.value {
    case 0...0xD7FF:
        return true
    case 0xE000...0x10FFFF:
        return false
    default:
        assertUnreachable()
    }
}

Assembly output:

        .globl  __T011Unreachable12isLowerRangeSbs7UnicodeO6ScalarVF
        .p2align        4, 0x90
__T011Unreachable12isLowerRangeSbs7UnicodeO6ScalarVF:
        pushq   %rbp
        movq    %rsp, %rbp
        cmpl    $55296, %edi
        setb    %al
        popq    %rbp
        retq

With `fatalError()`

func isLowerRange(_ x: UnicodeScalar) -> Bool {
    switch x.value {
    case 0...0xD7FF:
        return true
    case 0xE000...0x10FFFF:
        return false
    default:
        fatalError("Unreachable")
    }
}