Unreachable

Platform Language: Swift CocoaPods - Unreachable Carthage codebeat badge License

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

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

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

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

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

Simply add Unreachable.swift into your project.

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

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()
}

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
 }
}

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().

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.

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

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

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.