Guides and Sample Code

Developer

Using Swift with Cocoa and Objective-C (Swift 3.1)

iBooks
On This Page

Adopting Cocoa Design Patterns

One aid in writing well-designed, resilient apps is to use Cocoa’s established design patterns. Many of these patterns rely on classes defined in Objective-C. Because of Swift’s interoperability with Objective-C, you can take advantage of these common patterns in your Swift code. In many cases, you can use Swift language features to extend or simplify existing Cocoa patterns, making them more powerful and easier to use.

Delegation

In both Swift and Objective-C, delegation is often expressed with a protocol that defines the interaction and a conforming delegate property. Just as in Objective-C, before you send a message that a delegate may not respond to, you ask the delegate whether it responds to the selector. In Swift, you can use optional chaining to invoke an optional protocol method on a possibly nil object and unwrap the possible result using if–let syntax. The code listing below illustrates the following process:

  1. Check that myDelegate is not nil.

  2. Check that myDelegate implements the method window:willUseFullScreenContentSize:.

  3. If 1 and 2 hold true, invoke the method and assign the result of the method to the value named fullScreenSize.

  4. Print the return value of the method.

  1. class MyDelegate: NSObject, NSWindowDelegate {
  2. func window(_ window: NSWindow, willUseFullScreenContentSize proposedSize: NSSize) -> NSSize {
  3. return proposedSize
  4. }
  5. }
  6. myWindow.delegate = MyDelegate()
  7. if let fullScreenSize = myWindow.delegate?.window(myWindow, willUseFullScreenContentSize: mySize) {
  8. print(NSStringFromSize(fullScreenSize))
  9. }

Lazy Initialization

A lazy property is a property whose underlying value is only initialized when the property is first accessed. Lazy properties are useful when the initial value for a property either requires complex or computationally expensive setup, or cannot be determined until after an instance’s initialization is complete.

In Objective-C, a property may override its synthesized getter method such that the underlying instance variable is conditionally initialized if its value is nil:

  1. @property NSXMLDocument *XML;
  2. - (NSXMLDocument *)XML {
  3. if (_XML == nil) {
  4. _XML = [[NSXMLDocument alloc] initWithContentsOfURL:[[Bundle mainBundle] URLForResource:@"/path/to/resource" withExtension:@"xml"] options:0 error:nil];
  5. }
  6. return _XML;
  7. }

In Swift, a stored property with an initial value can be declared with the lazy modifier to have the expression calculating the initial value only evaluated when the property is first accessed:

  1. lazy var XML: XMLDocument = try! XMLDocument(contentsOf: Bundle.main.url(forResource: "document", withExtension: "xml")!, options: 0)

Because a lazy property is only computed when accessed for a fully-initialized instance it may access constant or variable properties in its default value initialization expression:

  1. var pattern: String
  2. lazy var regex: NSRegularExpression = try! NSRegularExpression(pattern: self.pattern, options: [])

For values that require additional setup beyond initialization, you can assign the default value of the property to a self-evaluating closure that returns a fully-initialized value:

  1. lazy var currencyFormatter: NumberFormatter = {
  2. let formatter = NumberFormatter()
  3. formatter.numberStyle = .currency
  4. formatter.currencySymbol = "¤"
  5. return formatter
  6. }()

For more information, see Lazy Stored Properties in The Swift Programming Language (Swift 3.1).

Error Handling

In Cocoa, methods that produce errors take an NSError pointer parameter as their last parameter, which populates its argument with an NSError object if an error occurs. Swift automatically translates Objective-C methods that produce errors into methods that throw an error according to Swift’s native error handling functionality.

For example, consider the following Objective-C method from NSFileManager:

  1. - (BOOL)removeItemAtURL:(NSURL *)URL
  2. error:(NSError **)error;

In Swift, it’s imported like this:

  1. func removeItem(at: URL) throws

Notice that the removeItem(at:) method is imported by Swift with a Void return type, no error parameter, and a throws declaration.

If the last non-block parameter of an Objective-C method is of type NSError **, Swift replaces it with the throws keyword, to indicate that the method can throw an error. If the Objective-C method’s error parameter is also its first parameter, Swift attempts to simplify the method name further, by removing the “WithError” or “AndReturnError” suffix, if present, from the first part of the selector. If another method is declared with the resulting selector, the method name is not changed.

If an error producing Objective-C method returns a BOOL value to indicate the success or failure of a method call, Swift changes the return type of the function to Void. Similarly, if an error producing Objective-C method returns a nil value to indicate the failure of a method call, Swift changes the return type of the function to a nonoptional type.

Otherwise, if no convention can be inferred, the method is left intact.

Catching and Handling an Error

In Objective-C, error handling is opt-in, meaning that errors produced by calling a method are ignored unless an error pointer is provided. In Swift, calling a method that throws requires explicit error handling.

Here’s an example of how to handle an error when calling a method in Objective-C:

  1. NSFileManager *fileManager = [NSFileManager defaultManager];
  2. NSURL *fromURL = [NSURL fileURLWithPath:@"/path/to/old"];
  3. NSURL *toURL = [NSURL fileURLWithPath:@"/path/to/new"];
  4. NSError *error = nil;
  5. BOOL success = [fileManager moveItemAtURL:fromURL toURL:toURL error:&error];
  6. if (!success) {
  7. NSLog(@"Error: %@", error.domain);
  8. }

And here’s the equivalent code in Swift:

  1. let fileManager = FileManager.default
  2. let fromURL = URL(fileURLWithPath: "/path/to/old")
  3. let toURL = URL(fileURLWithPath: "/path/to/new")
  4. do {
  5. try fileManager.moveItem(at: fromURL, to: toURL)
  6. } catch let error as NSError {
  7. print("Error: \(error.domain)")
  8. }

Additionally, you can use catch clauses to match on particular error codes as a convenient way to differentiate possible failure conditions:

  1. do {
  2. try fileManager.moveItem(at: fromURL, to: toURL)
  3. } catch CocoaError.fileNoSuchFile {
  4. print("Error: no such file exists")
  5. } catch CocoaError.fileReadUnsupportedScheme {
  6. print("Error: unsupported scheme (should be 'file://')")
  7. }

Converting Errors to Optional Values

In Objective-C, you pass NULL for the error parameter when you only care whether there was an error, not what specific error occurred. In Swift, you write try? to change a throwing expression into one that returns an optional value, and then check whether the value is nil.

For example, the NSFileManager instance method URL(for:in:appropriateForURL:create:) returns a URL in the specified search path and domain, or produces an error if an appropriate URL does not exist and cannot be created. In Objective-C, the success or failure of the method can be determined by whether an NSURL object is returned.

  1. NSFileManager *fileManager = [NSFileManager defaultManager];
  2. NSURL *tmpURL = [fileManager URLForDirectory:NSCachesDirectory
  3. inDomain:NSUserDomainMask
  4. appropriateForURL:nil
  5. create:YES
  6. error:nil];
  7. if (tmpURL != nil) {
  8. // ...
  9. }

You can do the same in Swift as follows:

  1. let fileManager = FileManager.default
  2. if let tmpURL = try? fileManager.url(for: .cachesDirectory, in: .userDomainMask, appropriateFor: nil, create: true) {
  3. // ...
  4. }

Throwing an Error

If an error occurs in an Objective-C method, that error is used to populate the error pointer argument of that method:

  1. // an error occurred
  2. if (errorPtr) {
  3. *errorPtr = [NSError errorWithDomain:NSURLErrorDomain
  4. code:NSURLErrorCannotOpenFile
  5. userInfo:nil];
  6. }

If an error occurs in a Swift method, the error is thrown, and automatically propagated to the caller:

  1. // an error occurred
  2. throw NSError(domain: NSURLErrorDomain, code: NSURLErrorCannotOpenFile, userInfo: nil)

If Objective-C code calls a Swift method that throws an error, the error is automatically propagated to the error pointer argument of the bridged Objective-C method.

For example, consider the read(from:ofType:) method in NSDocument. In Objective-C, this method’s last parameter is of type NSError **. When overriding this method in a Swift subclass of NSDocument, the method replaces its error parameter and throws instead.

  1. class SerializedDocument: NSDocument {
  2. static let ErrorDomain = "com.example.error.serialized-document"
  3. var representedObject: [String: Any] = [:]
  4. override func read(from fileWrapper: FileWrapper, ofType typeName: String) throws {
  5. guard let data = fileWrapper.regularFileContents else {
  6. throw NSError(domain: NSURLErrorDomain, code: NSURLErrorCannotOpenFile, userInfo: nil)
  7. }
  8. if case let JSON as [String: Any] = try JSONSerialization.jsonObject(with: data, options: []) {
  9. self.representedObject = JSON
  10. } else {
  11. throw NSError(domain: SerializedDocument.ErrorDomain, code: -1, userInfo: nil)
  12. }
  13. }
  14. }

If the method is unable to create an object with the regular file contents of the document, it throws an NSError object. If the method is called from Swift code, the error is propagated to its calling scope. If the method is called from Objective-C code, the error instead populates the error pointer argument.

In Objective-C, error handling is opt-in, meaning that errors produced by calling a method are ignored unless you provide an error pointer. In Swift, calling a method that throws requires explicit error handling.

Key-Value Observing

Key-value observing is a mechanism that allows objects to be notified of changes to specified properties of other objects. You can use key-value observing with a Swift class, as long as the class inherits from the NSObject class. You can use these three steps to implement key-value observing in Swift.

  1. Add the dynamic modifier to any property you want to observe. For more information on dynamic, see Requiring Dynamic Dispatch.

    1. class MyObjectToObserve: NSObject {
    2. dynamic var myDate = NSDate()
    3. func updateDate() {
    4. myDate = NSDate()
    5. }
    6. }
  2. Create a global context variable.

    1. private var myContext = 0
  3. Add an observer for the key-path, override the observeValue(for:of:change:context:) method, and remove the observer in deinit.

    1. class MyObserver: NSObject {
    2. var objectToObserve = MyObjectToObserve()
    3. override init() {
    4. super.init()
    5. objectToObserve.addObserver(self, forKeyPath: #keyPath(MyObjectToObserve.myDate), options: .new, context: &myContext)
    6. }
    7. override func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?) {
    8. if context == &myContext {
    9. if let newValue = change?[.newKey] {
    10. print("Date changed: \(newValue)")
    11. }
    12. } else {
    13. super.observeValue(forKeyPath: keyPath, of: object, change: change, context: context)
    14. }
    15. }
    16. deinit {
    17. objectToObserve.removeObserver(self, forKeyPath: #keyPath(MyObjectToObserve.myDate), context: &myContext)
    18. }
    19. }

Undo

In Cocoa, you register operations with NSUndoManager to allow users to reverse that operation’s effect. You can take advantage of Cocoa’s undo architecture in Swift just as you would in Objective-C.

Objects in an app’s responder chain—that is, subclasses of NSResponder on macOS and UIResponder on iOS—have a read-only undoManager property that returns an optional NSUndoManager value, which manages the undo stack for the app. Whenever an action is taken by the user, such as editing the text in a control or deleting an item at a selected row, an undo operation can be registered with the undo manager to allow the user to reverse the effect of that operation. An undo operation records the steps necessary to counteract its corresponding operation, such as setting the text of a control back to its original value or adding a deleted item back into a table.

NSUndoManager supports two ways to register undo operations: a “simple undo”, which performs a selector with a single object argument, and an “invocation-based undo”, which uses an NSInvocation object that takes any number and any type of arguments.

For example, consider a simple Task model, which is used by a ToDoListController to display a list of tasks to complete:

  1. class Task {
  2. var text: String
  3. var completed: Bool = false
  4. init(text: String) {
  5. self.text = text
  6. }
  7. }
  8. class ToDoListController: NSViewController, NSTableViewDataSource, NSTableViewDelegate {
  9. @IBOutlet var tableView: NSTableView!
  10. var tasks: [Task] = []
  11. // ...
  12. }

For methods that take more than one argument, you can create an undo operation using an NSInvocation, which invokes the method with arguments that effectively revert the app to its previous state:

  1. @IBOutlet var remainingLabel: NSTextView!
  2. func mark(task: Task, asCompleted completed: Bool) {
  3. if let target = undoManager?.prepare(withInvocationTarget: self) as? ToDoListController {
  4. target.mark(task: task, asCompleted: !completed)
  5. undoManager?.setActionName(NSLocalizedString("todo.task.mark", comment: "Mark As Completed"))
  6. }
  7. task.completed = completed
  8. tableView.reloadData()
  9. let numberRemaining = tasks.filter{ $0.completed }.count
  10. remainingLabel.string = String(format: NSLocalizedString("todo.task.remaining", comment: "Tasks Remaining: %d"), numberRemaining)
  11. }

The prepare(withInvocationTarget:) method returns a proxy to the specified target. By casting to ToDoListController, this return value can make the corresponding call to mark(task:asCompleted:) directly.

For more information, see Undo Architecture.

Target-Action

Target-action is a common Cocoa design pattern in which one object sends a message to another object when a specific event occurs. The target-action model is fundamentally similar in Swift and Objective-C. In Swift, you use the Selector type to refer to Objective-C selectors. For an example of using target-action in Swift code, see Selectors.

Singleton

Singletons provide a globally accessible, shared instance of an object. You can create your own singletons as a way to provide a unified access point to a resource or service that’s shared across an app, such as an audio channel to play sound effects or a network manager to make HTTP requests.

In Objective-C, you can ensure that only one instance of a singleton object is created by wrapping its initialization in a call the dispatch_once function, which executes a block once and only once for the lifetime of an app:

  1. + (instancetype)sharedInstance {
  2. static id _sharedInstance = nil;
  3. static dispatch_once_t onceToken;
  4. dispatch_once(&onceToken, ^{
  5. _sharedInstance = [[self alloc] init];
  6. });
  7. return _sharedInstance;
  8. }

In Swift, you can simply use a static type property, which is guaranteed to be lazily initialized only once, even when accessed across multiple threads simultaneously:

  1. class Singleton {
  2. static let sharedInstance = Singleton()
  3. }

If you need to perform additional setup beyond initialization, you can assign the result of the invocation of a closure to the global constant:

  1. class Singleton {
  2. static let sharedInstance: Singleton = {
  3. let instance = Singleton()
  4. // setup code
  5. return instance
  6. }()
  7. }

For more information, see Type Properties in The Swift Programming Language (Swift 3.1).

Introspection

In Objective-C, you use the isKindOfClass: method to check whether an object is of a certain class type, and the conformsToProtocol: method to check whether an object conforms to a specified protocol. In Swift, you accomplish this task by using the is operator to check for a type, or the as? operator to downcast to that type.

You can check whether an instance is of a certain subclass type by using the is operator. The is operator returns true if the instance is of that subclass type, and false if it is not.

  1. if object is UIButton {
  2. // object is of type UIButton
  3. } else {
  4. // object is not of type UIButton
  5. }

You can also try and downcast to the subclass type by using the as? operator. The as? operator returns an optional value that can be bound to a constant using an if-let statement.

  1. if let button = object as? UIButton {
  2. // object is successfully cast to type UIButton and bound to button
  3. } else {
  4. // object could not be cast to type UIButton
  5. }

For more information, see Type Casting in The Swift Programming Language (Swift 3.1).

Checking for and casting to a protocol follows exactly the same syntax as checking for and casting to a class. Here is an example of using the as? operator to check for protocol conformance:

  1. if let dataSource = object as? UITableViewDataSource {
  2. // object conforms to UITableViewDataSource and is bound to dataSource
  3. } else {
  4. // object not conform to UITableViewDataSource
  5. }

Note that after this cast, the dataSource constant is of type UITableViewDataSource, so you can only call methods and access properties defined on the UITableViewDataSource protocol. You must cast it back to another type to perform other operations.

For more information, see Protocols in The Swift Programming Language (Swift 3.1).

Serializing

Serialization allows you to encode and decode objects in your application to and from architecture-independent representations, such as JSON or property lists. These representations can then be written to a file or transmitted to another process locally or over a network.

In Objective-C, you can use the Foundation framework classes NSJSONSerialiation and NSPropertyListSerialization to initialize objects from a decoded JSON or property list serialization value—usually an object of type NSDictionary<NSString *, id>. You can do the same in Swift, but because Swift enforces type safety, additional type casting is required in order to extract and assign values.

For example, consider the following Venue structure, which contains a name property of type String, a coordinate property of type CLLocationCoordinate2D, and a category property of a nested Category enumeration type:

  1. import Foundation
  2. import CoreLocation
  3. struct Venue {
  4. enum Category: String {
  5. case entertainment
  6. case food
  7. case nightlife
  8. case shopping
  9. }
  10. var name: String
  11. var coordinates: CLLocationCoordinate2D
  12. var category: Category
  13. }

An app that interacts with Venue instances may communicate with a web server that vends JSON representations of venues, such as:

  1. {
  2. "name": "Caffè Macs",
  3. "coordinates": {
  4. "lat": 37.330576,
  5. "lng": -122.029739
  6. },
  7. "category": "food"
  8. }

You can provide a failable Venue initializer that takes an attributes parameter of type [String: Any] corresponding to the value returned from NSJSONSerialiation or NSPropertyListSerialization:

  1. init?(attributes: [String: Any]) {
  2. guard let name = attributes["name"] as? String,
  3. let coordinates = attributes["coordinates"] as? [String: Double],
  4. let latitude = coordinates["lat"],
  5. let longitude = coordinates["lng"],
  6. let category = Category(rawValue: attributes["category"] as? String ?? "Invalid")
  7. else {
  8. return nil
  9. }
  10. self.name = name
  11. self.coordinates = CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
  12. self.category = category
  13. }

A guard statement consisting of multiple optional binding expressions ensures that the attributes argument provides all of the required information in the expected format. If any one of the optional binding expressions fails to assign a value to a constant, the guard statement immediately stops evaluating its condition and executes its else branch, which returns nil.

You can create a Venue from a JSON representation by creating a dictionary of attributes using the NSJSONSerialization class and then passing that into the corresponding Venue initializer:

  1. let JSON = "{\"name\": \"Caffè Macs\",\"coordinates\": {\"lat\": 37.330576,\"lng\": -122.029739},\"category\": \"food\"}"
  2. let data = JSON.data(using: String.Encoding.utf8)!
  3. let attributes = try! JSONSerialization.jsonObject(with: data, options: []) as! [String: Any]
  4. let venue = Venue(attributes: attributes)!
  5. print(venue.name)
  6. // Prints "Caffè Macs"

Validating Serialized Representations

In the previous example, the Venue initializer optionally returns an instance only if all of the required information is provided. If not, the initializer simply returns nil.

It is often useful to determine and communicate the specific reason why a given collection of values failed to produce a valid instance. To do this, you can refactor the failable initializer into an initializer that throws:

  1. enum ValidationError: Error {
  2. case missing(String)
  3. case invalid(String)
  4. }
  5. init(attributes: [String: Any]) throws {
  6. guard let name = attributes["name"] as? String else {
  7. throw ValidationError.missing("name")
  8. }
  9. guard let coordinates = attributes["coordinates"] as? [String: Double] else {
  10. throw ValidationError.missing("coordinates")
  11. }
  12. guard let latitude = coordinates["lat"],
  13. let longitude = coordinates["lng"]
  14. else {
  15. throw ValidationError.invalid("coordinates")
  16. }
  17. guard let categoryName = attributes["category"] as? String else {
  18. throw ValidationError.missing("category")
  19. }
  20. guard let category = Category(rawValue: categoryName) else {
  21. throw ValidationError.invalid("category")
  22. }
  23. self.name = name
  24. self.coordinates = CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
  25. self.category = category
  26. }

Instead of capturing all of the attributes values at once in a single guard statement, this initializer checks each value individually and throws an error if any particular value is either missing or invalid.

For instance, if the provided JSON didn’t have a value for the key "name", the initializer would throw the enumeration value ValidationError.missing with an associated value corresponding to the "name" field:

  1. {
  2. "coordinates": {
  3. "lat": 37.7842,
  4. "lng": -122.4016
  5. },
  6. "category": "Convention Center"
  7. }
  1. let JSON = "{\"coordinates\": {\"lat\": 37.7842, \"lng\": -122.4016}, \"category\": \"Convention Center\"}"
  2. let data = JSON.data(using: String.Encoding.utf8)!
  3. let attributes = try! JSONSerialization.jsonObject(with: data, options: []) as! [String: Any]
  4. do {
  5. let venue = try Venue(attributes: attributes)
  6. } catch ValidationError.missing(let field) {
  7. print("Missing Field: \(field)")
  8. }
  9. // Prints "Missing Field: name"

Or, if the provided JSON specified all of the required fields but had a value for the "category" key that didn’t correspond with the rawValue of any of the defined Category cases, the initializer would throw the enumeration value ValidationError.invalid with an associated value corresponding to the "category" field:

  1. {
  2. "name": "Moscone West",
  3. "coordinates": {
  4. "lat": 37.7842,
  5. "lng": -122.4016
  6. },
  7. "category": "Convention Center"
  8. }
  1. let JSON = "{\"name\": \"Moscone West\", \"coordinates\": {\"lat\": 37.7842, \"lng\": -122.4016}, \"category\": \"Convention Center\"}"
  2. let data = JSON.data(using: String.Encoding.utf8)!
  3. let attributes = try! JSONSerialization.jsonObject(with: data, options: []) as! [String: Any]
  4. do {
  5. let venue = try Venue(attributes: attributes)
  6. } catch ValidationError.invalid(let field) {
  7. print("Invalid Field: \(field)")
  8. }
  9. // Prints "Invalid Field: category"

Localization

In Objective-C, you typically use the NSLocalizedString family of macros to localize strings. These include NSLocalizedString, NSLocalizedStringFromTable, NSLocalizedStringFromTableInBundle, and NSLocalizedStringWithDefaultValue. In Swift, the functionality of these macros is made available through a single function: NSLocalizedString(_:tableName:bundle:value:comment:).

Rather than defining separate functions that correspond to each Objective-C macro, the Swift NSLocalizedString(_:tableName:bundle:value:) function specifies default values for the tableName, bundle, and value arguments, so that they may be overridden as necessary.

For example, the most common form of a localized string in an app may only need a localization key and a comment:

  1. let format = NSLocalizedString("Hello, %@!", comment: "Hello, {given name}!")
  2. let name = "Mei"
  3. let greeting = String(format: format, arguments: [name as CVarArg])
  4. print(greeting)
  5. // Prints "Hello, Mei!"

Or, an app may require more complex usage in order to use localization resources from a separate bundle:

  1. if let path = Bundle.main.path(forResource: "Localization", ofType: "strings", inDirectory: nil, forLocalization: "ja"),
  2. let bundle = Bundle(path: path) {
  3. let translation = NSLocalizedString("Hello", bundle: bundle, comment: "")
  4. print(translation)
  5. }
  6. // Prints "こんにちは"

For more information, see Internationalization and Localization Guide.

Autorelease Pools

Autorelease pool blocks allow objects to relinquish ownership without being deallocated immediately. Typically, you don’t need to create your own autorelease pool blocks, but there are some situations in which either you must—such as when spawning a secondary thread—or it is beneficial to do so—such as when writing a loop that creates many temporary objects.

In Objective-C, autorelease pool blocks are marked using @autoreleasepool. In Swift, you can use the autoreleasepool(_:) function to execute a closure within an autorelease pool block.

  1. import Foundation
  2. autoreleasepool {
  3. // code that creates autoreleased objects.
  4. }

For more information, see Advanced Memory Management Programming Guide.

API Availability

Some classes and methods are not available to all versions of all platforms that your app targets. To ensure that your app can accommodate any differences in functionality, you check the availability those APIs.

In Objective-C, you use the respondsToSelector: and instancesRespondToSelector: methods to check for the availability of a class or instance method. Without a check, the method call throws an NSInvalidArgumentException “unrecognized selector sent to instance” exception. For example, the requestWhenInUseAuthorization method is only available to instances of CLLocationManager starting in iOS 8.0 and macOS 10.10:

  1. if ([CLLocationManager instancesRespondToSelector:@selector(requestWhenInUseAuthorization)]) {
  2. // Method is available for use.
  3. } else {
  4. // Method is not available.
  5. }

In Swift, attempting to call a method that is not supported on all targeted platform versions causes a compile-time error.

Here’s the previous example, in Swift:

  1. let locationManager = CLLocationManager()
  2. locationManager.requestWhenInUseAuthorization()
  3. // error: only available on iOS 8.0 or newer

If the app targets a version of iOS prior to 8.0 or macOS prior to 10.10, requestWhenInUseAuthorization() is unavailable, so the compiler reports an error.

Swift code can use the availability of APIs as a condition at run-time. Availability checks can be used in place of a condition in a control flow statement, such as an if, guard, or while statement.

Taking the previous example, you can check availability in an if statement to call requestWhenInUseAuthorization() only if the method is available at runtime:

  1. let locationManager = CLLocationManager()
  2. if #available(iOS 8.0, macOS 10.10, *) {
  3. locationManager.requestWhenInUseAuthorization()
  4. }

Alternatively, you can check availability in a guard statement, which exits out of scope unless the current target satisfies the specified requirements. This approach simplifies the logic of handling different platform capabilities.

  1. let locationManager = CLLocationManager()
  2. guard #available(iOS 8.0, macOS 10.10, *) else { return }
  3. locationManager.requestWhenInUseAuthorization()

Each platform argument consists of one of platform names listed below, followed by corresponding version number. The last argument is an asterisk (*), which is used to handle potential future platforms.

Platform Names:

  • iOS

  • iOSApplicationExtension

  • macOS

  • macOSApplicationExtension

  • watchOS

  • watchOSApplicationExtension

  • tvOS

  • tvOSApplicationExtension

All of the Cocoa APIs provide availability information, so you can be confident the code you write works as expected on any of the platforms your app targets.

You can denote the availability of your own APIs by annotating declarations with the @available attribute. The @available attribute uses the same syntax as the #available runtime check, with the platform version requirements provided as comma-delimited arguments.

For example:

  1. @available(iOS 8.0, macOS 10.10, *)
  2. func useShinyNewFeature() {
  3. // ...
  4. }

Processing Command-Line Arguments

On macOS, you typically open an app by clicking its icon in the Dock or Launchpad, or by double-clicking its icon from the Finder. However, you can also open an app programmatically and pass command-line arguments from Terminal.

You can get a list of any command-line arguments that are specified at launch by accessing the CommandLine.arguments type property.

  1. $ /path/to/app --argumentName value
  1. for argument in CommandLine.arguments {
  2. print(argument)
  3. }
  4. // prints "/path/to/app"
  5. // prints "--argumentName"
  6. // prints "value"

The first element in CommandLine.arguments is a path to the executable. Any command-line arguments that are specified at launch begin at CommandLine.arguments[1].