nvzqz/Unreachable

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

• Build Status
• Installation
  • Compatibility
  • Swift Package Manager
  • CocoaPods
  • Carthage
• Usage
  • Dynamic Loop Exit
  • Switch Conditions
  • Safety
  • Unreachable vs fatalError
    • Unreachable Example
    • fatalError Example
• 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.

1. 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)
       ]
   )

2. 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.

1. 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'

2. Run pod install and open the .xcworkspace file to launch Xcode.

3. Import the Unreachable framework.

   import Unreachable

Install Using Carthage

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

1. Add the project to your Cartfile.

   github "nvzqz/Unreachable"
   

2. Run carthage update and follow the additional steps in order to add Unreachable to your project.

3. 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")
    }
}

Assembly output:

        .globl  __T011Unreachable12isLowerRangeSbs7UnicodeO6ScalarVF
        .p2align        4, 0x90
__T011Unreachable12isLowerRangeSbs7UnicodeO6ScalarVF:
        .cfi_startproc
        movb    $1, %al
        cmpl    $55296, %edi
        jb      LBB4_3
        addl    $-57344, %edi
        cmpl    $1056768, %edi
        jae     LBB4_4
        xorl    %eax, %eax
LBB4_3:
        retq
LBB4_4:
        pushq   %rbp
Lcfi0:
        .cfi_def_cfa_offset 16
Lcfi1:
        .cfi_offset %rbp, -16
        movq    %rsp, %rbp
Lcfi2:
        .cfi_def_cfa_register %rbp
        subq    $48, %rsp
        leaq    L___unnamed_2(%rip), %rax
        movq    %rax, (%rsp)
        movl    $0, 32(%rsp)
        movq    $56, 24(%rsp)
        movl    $2, 16(%rsp)
        movq    $69, 8(%rsp)
        leaq    L___unnamed_3(%rip), %rdi
        leaq    L___unnamed_4(%rip), %rcx
        movl    $11, %esi
        movl    $2, %edx
        movl    $11, %r8d
        xorl    %r9d, %r9d
        callq   __T0s17_assertionFailures5NeverOs12StaticStringV_SSAE4fileSu4lines6UInt32V5flagstFTfq4nxnnn_n
        subq    $40, %rsp
        .cfi_endproc

License

All source code for Unreachable is released under the MIT License.

Assets for Unreachable are released under the CC BY-SA 4.0 License and can be found in the assets branch.