iOS Developer Library — Pre-Release

Developer

The Swift Programming Language

iBooks
On This Page

Attributes

Attributes provide more information about a declaration or type. There are two kinds of attributes in Swift, those that apply to declarations and those that apply to types.

You specify an attribute by writing the @ symbol followed by the attribute’s name and any arguments that the attribute accepts:

  • @attribute name
  • @attribute name(attribute arguments)

Some declaration attributes accept arguments that specify more information about the attribute and how it applies to a particular declaration. These attribute arguments are enclosed in parentheses, and their format is defined by the attribute they belong to.

Declaration Attributes

You can apply a declaration attribute to declarations only. However, you can also apply the noreturn attribute to a function or method type.

availability

Apply this attribute to any declaration to indicate the declaration’s lifecycle relative to certain platforms and operating system versions.

The availability attribute always appears with a list of two or more comma-separated attribute arguments. These arguments begin with one of the following platform names: iOS, iOSApplicationExtension, OSX, or OSXApplicationExtension. You can also use an asterisk (*) to indicate the availability of the declaration on all of the platform names listed above. The remaining arguments can appear in any order and specify additional information about the declaration’s lifecycle, including important milestones.

  • The unavailable argument indicates that the declaration isn’t available on the specified platform.

  • The introduced argument indicates the first version of the specified platform in which the declaration was introduced. It has the following form:

    The introduced argument has the following form:

    • introduced=version number

    The version number consists of a positive integer or floating-point decimal number.

  • The deprecated argument indicates the first version of the specified platform in which the declaration was deprecated. It has the following form:

    • deprecated=version number

    The version number consists of a positive integer or floating-point decimal number.

  • The obsoleted argument indicates the first version of the specified platform in which the declaration was obsoleted. When a declaration is obsoleted, it’s removed from the specified platform and can no longer be used. The obsoleted argument has the following form:

    • obsoleted=version number

    The version number consists of a positive integer or floating-point decimal number.

  • The message argument is used to provide a textual message that’s displayed by the compiler when emitting a warning or error about the use of a deprecated or obsoleted declaration. It has the following form:

    • message=message

    The message consists of a string literal.

  • The renamed argument is used to provide a textual message that indicates the new name for a declaration that’s been renamed. The new name is displayed by the compiler when emitting an error about the use of a renamed declaration. It has the following form:

    • renamed=new name

    The new name consists of a string literal.

    You can use the renamed argument in conjunction with the unavailable argument and a type alias declaration to indicate to clients of your code that a declaration has been renamed. For example, this is useful when the name of a declaration is changed between releases of a framework or library.

    • // First release
    • protocol MyProtocol {
    • // protocol definition
    • }
    • // Subsequent release renames MyProtocol
    • protocol MyRenamedProtocol {
    • // protocol definition
    • }
    • @availability(*, unavailable, renamed="MyRenamedProtocol")
    • typealias MyProtocol = MyRenamedProtocol

You can apply multiple availability attributes on a single declaration to specify the declaration’s availability on different platforms. The compiler uses an availability attribute only when the attribute specifies a platform that matches the current target platform.

noreturn

Apply this attribute to a function or method declaration to indicate that the corresponding type of that function or method, T, is @noreturn T. You can mark a function or method type with this attribute to indicate that the function or method doesn’t return to its caller.

You can override a function or method that is not marked with the noreturn attribute with a function or method that is. That said, you can’t override a function or method that is marked with the noreturn attribute with a function or method that is not. Similar rules apply when you implement a protocol method in a conforming type.

NSApplicationMain

Apply this attribute to a class to indicate that it is the application delegate. Using this attribute is equivalent to calling the NSApplicationMain function and passing this class’s name as the name of the delegate class.

If you do not use this attribute, supply a main.swift file with a main function that calls the NSApplicationMain function. For example, if your app uses a custom subclass of NSApplication as its principal class, call the NSApplicationMain function instead of using this attribute.

NSCopying

Apply this attribute to a stored variable property of a class. This attribute causes the property’s setter to be synthesized with a copy of the property’s value—returned by the copyWithZone(_:) method—instead of the value of the property itself. The type of the property must conform to the NSCopying protocol.

The NSCopying attribute behaves in a way similar to the Objective-C copy property attribute.

NSManaged

Apply this attribute to a stored variable property of a class that inherits from NSManagedObject to indicate that the storage and implementation of the property are provided dynamically by Core Data at runtime based on the associated entity description.

objc

Apply this attribute to any declaration that can be represented in Objective-C—for example, non-nested classes, protocols, properties and methods (including getters and setters) of classes and protocols, initializers, deinitializers, and subscripts. The objc attribute tells the compiler that a declaration is available to use in Objective-C code.

If you apply the objc attribute to a class or protocol, it’s implicitly applied to the members of that class or protocol. The compiler also implicitly adds the objc attribute to a class that inherits from another class marked with the objc attribute. Protocols marked with the objc attribute can’t inherit from protocols that aren’t.

The objc attribute optionally accepts a single attribute argument, which consists of an identifier. Use this attribute when you want to expose a different name to Objective-C for the entity the objc attribute applies to. You can use this argument to name classes, protocols, methods, getters, setters, and initializers. The example below exposes the getter for the enabled property of the ExampleClass to Objective-C code as isEnabled rather than just as the name of the property itself.

  • @objc
  • class ExampleClass {
  • var enabled: Bool {
  • @objc(isEnabled) get {
  • // Return the appropriate value
  • }
  • }
  • }
UIApplicationMain

Apply this attribute to a class to indicate that it is the application delegate. Using this attribute is equivalent to calling the UIApplicationMain function and passing this class’s name as the name of the delegate class.

If you do not use this attribute, supply a main.swift file with a main function that calls the UIApplicationMain function. For example, if your app uses a custom subclass of UIApplication as its principal class, call the UIApplicationMain function instead of using this attribute.

Declaration Attributes Used by Interface Builder

Interface Builder attributes are declaration attributes used by Interface Builder to synchronize with Xcode. Swift provides the following Interface Builder attributes: IBAction, IBDesignable, IBInspectable, and IBOutlet. These attributes are conceptually the same as their Objective-C counterparts.

You apply the IBOutlet and IBInspectable attributes to property declarations of a class. You apply the IBAction attribute to method declarations of a class and the IBDesignable attribute to class declarations.

Type Attributes

You can apply type attributes to types only. However, you can also apply the noreturn attribute to a function or method declaration.

autoclosure

This attribute is used to delay the evaluation of an expression by automatically wrapping that expression in a closure with no arguments. Apply this attribute to a function or method type that takes no arguments and that returns the type of the expression. For an example of how to use the autoclosure attribute, see Function Type.

noreturn

Apply this attribute to the type of a function or method to indicate that the function or method doesn’t return to its caller. You can also mark a function or method declaration with this attribute to indicate that the corresponding type of that function or method, T, is @noreturn T.

Grammar of an attribute

attribute attribute-name­attribute-argument-clause­opt­

attribute-name identifier­

attribute-argument-clause balanced-tokens­opt­

attributes attribute­attributes­opt­

balanced-tokens balanced-token­balanced-tokens­opt­

balanced-token balanced-tokens­opt­

balanced-token balanced-tokens­opt­

balanced-token balanced-tokens­opt­

balanced-token Any identifier, keyword, literal, or operator

balanced-token Any punctuation except , , , , , or