NEW: My new book Pro SwiftUI is out now – level up your SwiftUI skills today! >>

How to use @available to deprecate old APIs

Swift version: 5.6

Paul Hudson    @twostraws   

Swift availability checking is most commonly used to mark sections of code that should target specific versions of iOS or other platforms. However, it’s also useful when you make Swift APIs for others to use, because you can use it to mark certain calls as deprecated or even obsoleted as needed.

Let’s start with a simple example: if you have a function that used to parse some data, but now you want users to stop calling it. To do that, use @available with the deprecated flag, passing in the message you want to show:

@available(*, deprecated, message: "Parse your data by hand instead")
func parseData() { }

If you are renaming the API – for example the way one usage of flatMap() became compactMap() in Swift 4.1 – you can pass the new function name to the renamed flag like this:

@available(*, deprecated, renamed: "loadData")
func fetchData() { }

This will cause Xcode to generate a fix-it automatically – users can click Fix to have Xcode perform the rename for them.

Deprecated APIs generate warnings but can still be called. If you want to obsolete an API – stop it from being called entirely – you should use the obsoleted flag instead, specifying the minimum Swift version where it is no longer available:

@available(swift, obsoleted: 4.1, renamed: "attemptConnection")
func testConnection() { }

You can even combine deprecated and obsoleted together if you want:

@available(swift, deprecated: 4.0, obsoleted: 5.0, message: "This will be removed in v5.0; please migrate to a different API.")

Finally, there’s an introduced flag that lets you control when specific API was introduced, like this:

@available(swift, introduced: 4.2)
func loadUsers() { }

Using @available in this way lets your APIs behave just like Apple’s own – Xcode will draw red lines through deprecated methods, issue compile warnings and errors, and even automatically generate fix-its as needed.

Hacking with Swift is sponsored by Play

SPONSORED Play is the first native iOS design tool created for designers and engineers. You can install Play for iOS and iPad today and sign up to check out the Beta of our macOS app with SwiftUI code export. We're also hiring engineers!

Click to learn more about Play!

Sponsor Hacking with Swift and reach the world's largest Swift community!

Available from iOS 8.0

Similar solutions…

About the Swift Knowledge Base

This is part of the Swift Knowledge Base, a free, searchable collection of solutions for common iOS questions.

BUY OUR BOOKS
Buy Pro Swift Buy Pro SwiftUI Buy Swift Design Patterns Buy Testing Swift Buy Hacking with iOS Buy Swift Coding Challenges Buy Swift on Sundays Volume One Buy Server-Side Swift Buy Advanced iOS Volume One Buy Advanced iOS Volume Two Buy Advanced iOS Volume Three Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with macOS Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Beyond Code

Was this page useful? Let us know!

Average rating: 4.7/5

 
Unknown user

You are not logged in

Log in or create account
 

Link copied to your pasteboard.