[//]: # (title: Interoperability with Swift/Objective-C)

> The Objective-C libraries import is in [Beta](native-lib-import-stability.md#stability-of-c-and-objective-c-library-import).
> All Kotlin declarations generated by the cinterop tool from Objective-C libraries
> should have the `@ExperimentalForeignApi` annotation.
>
> Native platform libraries shipped with Kotlin/Native (like Foundation, UIKit, and POSIX)
> require opt-in only for some APIs.
>
{style="note"}

Kotlin/Native provides indirect interoperability with Swift through Objective-C. This document covers how you can use Kotlin
declarations in Swift/Objective-C code and Objective-C declarations in Kotlin code.

Some other resources you might find useful:

* The [Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia), a collection of examples
  on how to use Kotlin declarations in Swift code. 
* The [Integration with Swift/Objective-C ARC](native-arc-integration.md) section, covering the details of integration
  between Kotlin's tracing GC and Objective-C's ARC.

## Importing Swift/Objective-C libraries to Kotlin

Objective-C frameworks and libraries can be used in Kotlin code if properly imported to the build (system frameworks are imported by default).
For more details, see:

* [Create and configure a library definition file](native-definition-file.md)
* [Configure compilation for native libraries](https://kotlinlang.org/docs/multiplatform/multiplatform-configure-compilations.html#configure-interop-with-native-languages)

A Swift library can be used in Kotlin code if its API is exported to Objective-C with `@objc`.
Pure Swift modules are not yet supported.

## Using Kotlin in Swift/Objective-C

Kotlin modules can be used in Swift/Objective-C code if compiled into a framework:

* See [Build final native binaries](https://kotlinlang.org/docs/multiplatform/multiplatform-build-native-binaries.html#declare-binaries) to see how to declare binaries.
* Check out the [Kotlin Multiplatform sample project](https://github.com/Kotlin/kmm-basic-sample) for an example.

### Hide Kotlin declarations from Objective-C and Swift

<primary-label ref="experimental-opt-in"/>

To make your Kotlin code more Swift/Objective-C-friendly, use the `@HiddenFromObjC` annotation to hide a Kotlin declaration
from Objective-C and Swift. It disables the function or property export to Objective-C.

Alternatively, you can mark Kotlin declarations with the `internal` modifier to restrict their visibility in the
compilation module. Use `@HiddenFromObjC` if you want to hide the Kotlin declaration from Objective-C and Swift
while keeping it visible to other Kotlin modules.

[See an example in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/HiddenFromObjC.md).

### Use refining in Swift

<primary-label ref="experimental-opt-in"/>

`@ShouldRefineInSwift` helps to replace a Kotlin declaration with a wrapper written in Swift. The annotation marks a
function or property as `swift_private` in the generated Objective-C API. Such declarations get the `__` prefix,
which makes them invisible from Swift.

You can still use these declarations in your Swift code to create a Swift-friendly API, but they won't be suggested in
the Xcode autocomplete.

* For more information on refining Objective-C declarations in Swift, see the [official Apple documentation](https://developer.apple.com/documentation/swift/improving-objective-c-api-declarations-for-swift).
* For an example on how to use the `@ShouldRefineInSwift` annotation, see the [Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/ShouldRefineInSwift.md).

### Change declaration names

<primary-label ref="experimental-opt-in"/>

To avoid renaming Kotlin declarations, use the `@ObjCName` annotation. It instructs the Kotlin compiler to use the
custom Objective-C and Swift name for the annotated class, interface, or another Kotlin entity:

```kotlin
@ObjCName(swiftName = "MySwiftArray")
class MyKotlinArray {
    @ObjCName("index")
    fun indexOf(@ObjCName("of") element: String): Int = TODO()
}

// Usage with the ObjCName annotations
let array = MySwiftArray()
let index = array.index(of: "element")
```

[See another example in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/ObjCName.md).

### Provide documentation with KDoc comments

Documentation is essential for understanding any API. Providing documentation for
the shared Kotlin API allows you to communicate with its users on matters of usage, dos and don'ts, and so on.

When generating Objective-C headers, [KDoc](kotlin-doc.md) comments from Kotlin code are translated into corresponding
Objective-C comments. For example, the following Kotlin code with KDoc:

```kotlin
/**
 * Prints the sum of the arguments.
 * Properly handles the case when the sum doesn't fit in 32-bit integer.
 */
fun printSum(a: Int, b: Int) = println(a.toLong() + b)
```

Will produce an Objective-C header with the corresponding comment:

```objc
/**
 * Prints the sum of the arguments.
 * Properly handles the case when the sum doesn't fit in 32-bit integer.
 */
+ (void)printSumA:(int32_t)a b:(int32_t)b __attribute__((swift_name("printSum(a:b:)")));
```

KDoc comments are embedded into klibs and extracted from klibs into the produced Apple frameworks.
As a result, comments on classes and methods appear during autocompletion, for example in Xcode.
If you go to the definition of functions in the `.h` file, you'll see comments on `@param`, `@return`, and similar tags.

Known limitations:

* Dependency documentation is not exported unless it is compiled with the `-Xexport-kdoc` option. Libraries compiled with
  this compiler option might be incompatible with other compiler versions.
* KDoc comments are mostly exported as is, but many KDoc block tags, such as `@property`, are not supported.

If necessary, you can disable the export of KDoc comments from klibs to the produced Apple frameworks in the `binaries {}`
block of your Gradle build file:

```kotlin
// build.gradle.kts
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi

kotlin {
    iosArm64 {
        binaries {
            framework {
                baseName = "sdk"
                @OptIn(ExperimentalKotlinGradlePluginApi::class)
                exportKdoc.set(false)
            }
        }
    }
}
```

## Mappings

The table below shows how Kotlin concepts are mapped to Swift/Objective-C and vice versa.

"->" and "<-" indicate that mapping only goes one way.

| Kotlin                 | Swift                            | Objective-C                      | Notes                                                                              |
|------------------------|----------------------------------|----------------------------------|------------------------------------------------------------------------------------|
| `class`                | `class`                          | `@interface`                     | [note](#classes)                                                                   |
| `interface`            | `protocol`                       | `@protocol`                      |                                                                                    |
| `constructor`/`create` | Initializer                      | Initializer                      | [note](#initializers)                                                              |
| Property               | Property                         | Property                         | [note 1](#top-level-functions-and-properties), [note 2](#setters)                  |
| Method                 | Method                           | Method                           | [note 1](#top-level-functions-and-properties), [note 2](#method-names-translation) |
| `enum class`           | `class`                          | `@interface`                     | [note](#enums)                                                                     |
| `suspend` ->           | `completionHandler:`/ `async`    | `completionHandler:`             | [note 1](#errors-and-exceptions), [note 2](#suspending-functions)                  |
| `@Throws fun`          | `throws`                         | `error:(NSError**)error`         | [note](#errors-and-exceptions)                                                     |
| Extension              | Extension                        | Category member                  | [note](#extensions-and-category-members)                                           |
| `companion` member <-  | Class method or property         | Class method or property         |                                                                                    |
| `null`                 | `nil`                            | `nil`                            |                                                                                    |
| `Singleton`            | `shared` or `companion` property | `shared` or `companion` property | [note](#kotlin-singletons)                                                         |
| Primitive type         | Primitive type / `NSNumber`      |                                  | [note](#primitive-types)                                                           |
| `Unit` return type     | `Void`                           | `void`                           |                                                                                    |
| `String`               | `String`                         | `NSString`                       | [note](#strings)                                                                   |
| `String`               | `NSMutableString`                | `NSMutableString`                | [note](#nsmutablestring)                                                           |
| `List`                 | `Array`                          | `NSArray`                        |                                                                                    |
| `MutableList`          | `NSMutableArray`                 | `NSMutableArray`                 |                                                                                    |
| `Set`                  | `Set`                            | `NSSet`                          |                                                                                    |
| `MutableSet`           | `NSMutableSet`                   | `NSMutableSet`                   | [note](#collections)                                                               |
| `Map`                  | `Dictionary`                     | `NSDictionary`                   |                                                                                    |
| `MutableMap`           | `NSMutableDictionary`            | `NSMutableDictionary`            | [note](#collections)                                                               |
| Function type          | Function type                    | Block pointer type               | [note](#function-types)                                                            |
| Inline classes         | Unsupported                      | Unsupported                      | [note](#unsupported)                                                               |

### Classes

#### Name translation

Objective-C classes are imported into Kotlin with their original names.
Protocols are imported as interfaces with a `Protocol` name suffix, for example, `@protocol Foo` -> `interface FooProtocol`.
These classes and interfaces are placed into a package [specified in build configuration](#importing-swift-objective-c-libraries-to-kotlin)
(`platform.*` packages for preconfigured system frameworks).

The names of Kotlin classes and interfaces are prefixed when imported to Objective-C.
The prefix is derived from the framework name.

Objective-C does not support packages in a framework. If the Kotlin compiler finds Kotlin classes in the same framework
which have the same name but different packages, it renames them. This algorithm is not stable yet and can change between
Kotlin releases. To work around this, you can rename the conflicting Kotlin classes in the framework.

#### Strong linking

Whenever you use an Objective-C class in the Kotlin source, it's marked as a strongly linked symbol. The resulting build
artifact mentions related symbols as strong external references.

This means that the app tries to link symbols during the launch dynamically, and if they are unavailable, the app crashes.
The crash happens even if symbols were never used. Symbols might be unavailable on a particular device or OS version.

To work around this issue and avoid "Symbol not found" errors, use a Swift or Objective-C wrapper that checks
if the class is actually available. [See how this workaround was implemented in the Compose Multiplatform framework](https://github.com/JetBrains/compose-multiplatform-core/pull/1278/files).

### Initializers

A Swift/Objective-C initializer is imported to Kotlin as constructors or as factory methods named `create`.
The latter happens with initializers declared in the Objective-C category or as a Swift extension,
because Kotlin has no concept of extension constructors.

> Before importing Swift initializers to Kotlin, don't forget to annotate them with `@objc`.
>
{style="tip"}

Kotlin constructors are imported as initializers to Swift/Objective-C.

### Setters

Writeable Objective-C properties overriding read-only properties of the superclass are represented as the `setFoo()` method
for the property `foo`. The same goes for a protocol's read-only properties that are implemented as mutable.

### Top-level functions and properties

Top-level Kotlin functions and properties are accessible as members of special classes.
Each Kotlin file is translated into such a class, for example:

```kotlin
// MyLibraryUtils.kt
package my.library

fun foo() {}
```

You can then call the `foo()` function from Swift like this:

```swift
MyLibraryUtilsKt.foo()
```

See a collection of examples on accessing top-level Kotlin declarations in the Kotlin-Swift interopedia:

* [Top-level functions](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/Top-level%20functions.md)
* [Top-level read-only properties](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/functionsandproperties/Top-level%20val%20properties.md)
* [Top-level mutable properties](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/functionsandproperties/Top-level%20mutable%20var%20properties.md)

### Method names translation

Generally, Swift argument labels and Objective-C selector pieces are mapped to Kotlin parameter names. These two concepts
have different semantics, so sometimes Swift/Objective-C methods can be imported with a clashing Kotlin signature.
In this case, the clashing methods can be called from Kotlin using named arguments, for example:

```swift
[player moveTo:LEFT byMeters:17]
[player moveTo:UP byInches:42]
```

In Kotlin, it's:

```kotlin
player.moveTo(LEFT, byMeters = 17)
player.moveTo(UP, byInches = 42)
```

Here's how the `kotlin.Any` functions are mapped to Swift/Objective-C:

| Kotlin       | Swift          | Objective-C   |
|--------------|----------------|---------------|
| `equals()`   | `isEquals(_:)` | `isEquals:`   |
| `hashCode()` | `hash`         | `hash`        |
| `toString()` | `description`  | `description` |

[See an example with data classes in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/classesandinterfaces/Data%20classes.md).

You can specify a more idiomatic name in Swift or Objective-C, instead of renaming the Kotlin declaration with
the [`@ObjCName` annotation](#change-declaration-names).

### Errors and exceptions

All Kotlin exceptions are unchecked, meaning that errors are caught at runtime. However, Swift has only checked errors
that are handled at compile time. So, if Swift or Objective-C code calls a Kotlin method that throws an exception,
the Kotlin method should be marked with the `@Throws` annotation, specifying a list of "expected" exception classes.

When compiling to the Swift/Objective-C framework, non-`suspend` functions that have or inherit the `@Throws` annotation
are represented as `NSError*`-producing methods in Objective-C and as `throws` methods in Swift.
Representations for `suspend` functions always have an `NSError*`/`Error` parameter in the completion handler.

When a Kotlin function called from Swift/Objective-C code throws an exception which is an instance of one of
the classes specified with `@Throws` or their subclasses, the exception is propagated as an `NSError`.
Other Kotlin exceptions reaching Swift/Objective-C are considered unhandled and cause program termination.

`suspend` functions without `@Throws` propagate only `CancellationException` (as `NSError`).
Non-`suspend` functions without `@Throws` don't propagate Kotlin exceptions at all.

Note that the opposite reversed translation is not implemented yet: Swift/Objective-C error-throwing methods aren't
imported to Kotlin as exception-throwing.

[See an example in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/Exceptions.md).

### Enums

Kotlin enums are imported into Objective-C as `@interface` and into Swift as `class`.
These data structures have properties corresponding to each enum value. Consider this Kotlin code:

```kotlin
// Kotlin
enum class Colors {
    RED, GREEN, BLUE
}
```

You can access the properties of this enum class from Swift as follows:

```swift
// Swift
Colors.red
Colors.green
Colors.blue
```

To use variables of a Kotlin enum in a Swift `switch` statement, provide a default statement to prevent a compilation error:

```swift
switch color {
    case .red: print("It's red")
    case .green: print("It's green")
    case .blue: print("It's blue")
    default: fatalError("No such color")
}
```

[See another example in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/classesandinterfaces/Enum%20classes.md).

### Suspending functions

<primary-label ref="experimental-opt-in"/>

Kotlin's [suspending functions](coroutines-basics.md) (`suspend`) are presented in the generated Objective-C headers as
functions with callbacks, or [completion handlers](https://developer.apple.com/documentation/swift/calling_objective-c_apis_asynchronously)
in Swift/Objective-C terminology.

Starting from Swift 5.5, Kotlin's `suspend` functions are also available for calling from Swift as
`async` functions without using the completion handlers. Currently, this functionality is highly experimental and
has certain limitations. See [this YouTrack issue](https://youtrack.jetbrains.com/issue/KT-47610) for details.

* Learn more about the [`async`/`await` mechanism in the Swift documentation](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html).
* See an example and recommendations on third-party libraries that implement the same functionality in the [Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/coroutines/Suspend%20functions.md).

### Extensions and category members

Members of Objective-C categories and Swift extensions are generally imported to Kotlin as extensions. That's why
these declarations can't be overridden in Kotlin, and the extension initializers aren't available as Kotlin constructors.

> Currently, there are two exceptions. Starting with Kotlin 1.8.20, category members that are declared
> in the same headers as the NSView class (from the AppKit framework) or UIView classes (from the UIKit framework) are
> imported as members of these classes. This means that you can override methods that subclass from NSView or UIView.
>
{style="note"}

Kotlin extensions to "regular" Kotlin classes are imported to Swift and Objective-C as extensions and category members,
respectively. Kotlin extensions to other types are treated as [top-level declarations](#top-level-functions-and-properties)
with an additional receiver parameter. These types include:

* Kotlin `String` type
* Kotlin collection types and subtypes
* Kotlin `interface` types
* Kotlin primitive types
* Kotlin `inline` classes
* Kotlin `Any` type
* Kotlin function types and subtypes
* Objective-C classes and protocols

[See a collection of examples in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/tree/main/docs/extensions).

### Kotlin singletons

Kotlin singleton (made with an `object` declaration, including `companion object`) is imported to Swift/Objective-C
as a class with a single instance.

The instance is available through the `shared` and `companion` properties.

For the following Kotlin code:

```kotlin
object MyObject {
    val x = "Some value"
}

class MyClass {
    companion object {
        val x = "Some value"
    }
}
```

Access these objects as follows: 

```swift
MyObject.shared
MyObject.shared.x
MyClass.companion
MyClass.Companion.shared
```

> Access objects through `[MySingleton mySingleton]` in Objective-C and `MySingleton()` in Swift has been deprecated.
> 
{style="note"}

See more examples in the Kotlin-Swift interopedia:

* [How to access Kotlin objects using `shared`](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/classesandinterfaces/Objects.md)
* [How to access members of Kotlin companion objects from Swift](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/classesandinterfaces/Companion%20objects.md).

### Primitive types

Kotlin primitive type boxes are mapped to special Swift/Objective-C classes. For example, the `kotlin.Int` box is represented
as the `KotlinInt` class instance in Swift (or the `${prefix}Int` instance in Objective-C, where `prefix` is the framework's name prefix).
These classes are derived from `NSNumber`, so the instances are proper `NSNumber`s supporting all corresponding operations.

The `NSNumber` type is not automatically translated to Kotlin primitive types when used as a Swift/Objective-C parameter type
or return value. The reason is that the `NSNumber` type doesn't provide enough information about a wrapped primitive value
type, for example, `NSNumber` is statically not known to be `Byte`, `Boolean`, or `Double`. So Kotlin primitive values
should be [cast to and from `NSNumber` manually](#casting-between-mapped-types).

### Strings

When a Kotlin `String` is passed to Swift, it's first exported as an Objective-C object, and then the Swift compiler
copies it one more time for a Swift conversion. This results in additional runtime overhead.

To avoid that, access Kotlin strings in Swift directly as an Objective-C `NSString` instead.
[See the conversion example](#see-the-conversion-example).

#### NSMutableString

`NSMutableString` Objective-C class is not available from Kotlin.
All instances of `NSMutableString` are copied when passed to Kotlin.

### Collections

#### Kotlin -> Objective-C -> Swift

When a Kotlin collection is passed to Swift, it's first converted to an Objective-C equivalent, and then the Swift compiler
copies the entire collection and converts it into a Swift-native collection as described in the [mappings table](#mappings).

This last conversion leads to performance costs. To prevent this, when using Kotlin collections in Swift,
explicitly cast them to their Objective-C counterparts: `NSDictionary`, `NSArray`, or `NSSet`.

##### See the conversion example {initial-collapse-state="collapsed" collapsible="true"}

For example, the following Kotlin declaration:

```kotlin
val map: Map<String, String>
```

In Swift, might look like this:

```Swift
map[key]?.count ?? 0
```

Here, the `map` is implicitly converted to Swift's `Dictionary`, and its string values are mapped to Swift's `String`.
This results in a performance cost.

To avoid the conversion, explicitly cast `map` to Objective-C's `NSDictionary` and access values as `NSString` instead:

```Swift
let nsMap: NSDictionary = map as NSDictionary
(nsMap[key] as? NSString)?.length ?? 0
```

This ensures that the Swift compiler doesn't perform an additional conversion step.

#### Swift -> Objective-C -> Kotlin

Swift/Objective-C collections are mapped to Kotlin as described in the [mappings table](#mappings),
except for `NSMutableSet` and `NSMutableDictionary`.

`NSMutableSet` isn't converted to a Kotlin's `MutableSet`. To pass an object to Kotlin `MutableSet`, explicitly create this
kind of Kotlin collection. To do this, use, for example, the `mutableSetOf()` function in Kotlin or the
`KotlinMutableSet` class in Swift and `${prefix}MutableSet` in Objective-C (`prefix` is the framework names prefix).
The same is true for `MutableMap`.

[See an example in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/Collections.md).

### Function types

Kotlin function-typed objects (for example, lambdas) are converted to closures in Swift and blocks in Objective-C.
[See an example of a Kotlin function with a lambda in the Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/functionsandproperties/Functions%20returning%20function%20type.md).

However, there is a difference in how types of parameters and return values are mapped when translating a function and a
function type. In the latter case, primitive types are mapped to their boxed representation. Kotlin `Unit` return value
is represented as a corresponding `Unit` singleton in Swift/Objective-C. The value of this singleton can be retrieved the
same way as for any other Kotlin `object`. See singletons in the [table above](#mappings).

Consider the following Kotlin function:

```kotlin
fun foo(block: (Int) -> Unit) { ... }
```

It's represented in Swift as follows:

```swift
func foo(block: (KotlinInt) -> KotlinUnit)
```

And you can call it like this:

```swift
foo {
    bar($0 as! Int32)
    return KotlinUnit()
}
```

#### Explicit parameter names in Objective-C block types

Kotlin adds explicit parameter names to function types for exported Objective-C headers.
Xcode's autocompletion then suggests these names when calling Objective-C functions in the Objective-C block.

For example, for the following Kotlin code:

```kotlin
// Kotlin:
fun greetUser(block: (name: String) -> Unit) = block("John")
```

Kotlin forwards the parameter names from Kotlin function types to Objective-C block types, allowing Xcode to use them in
suggestions:

```objc
// Objective-C:
greetUserBlock:^(NSString *name) {
    // ...
};
```

> This option affects Objective-C interop only. It applies when calling generated Objective-C code from Objective-C in Xcode,
> and generally doesn't affect calls from Swift.
>
{style="note"}

If you encounter issues, you can disable explicit parameter names with the following [binary option](native-binary-options.md)
in your `gradle.properties` file:

```none
kotlin.native.binary.objcExportBlockExplicitParameterNames=false
```

Please report such problems in our issue tracker, [YouTrack](https://kotl.in/issue).

### Generics

Objective-C supports "lightweight generics" defined in classes, with a relatively limited feature set. Swift can import 
generics defined on classes to help provide additional type information to the compiler.

Generic feature support for Objective-C and Swift differ from Kotlin, so the translation will inevitably lose some
information, but the features supported retain meaningful information.

For specific examples on how to use Kotlin generics in Swift, see the [Kotlin-Swift interopedia](https://github.com/kotlin-hands-on/kotlin-swift-interopedia/blob/main/docs/overview/ShouldRefineInSwift.md).

#### Limitations

Objective-C generics do not support all features of either Kotlin or Swift, so there will be some information lost
in the translation.

Generics can only be defined on classes, not on interfaces (protocols in Objective-C and Swift) or functions.

#### Nullability

Kotlin and Swift both define nullability as part of the type specification, while Objective-C defines nullability on methods
and properties of a type. So, the following Kotlin code:

```kotlin
class Sample<T>() {
    fun myVal(): T
}
```

Looks in Swift like this:

```swift
class Sample<T>() {
    fun myVal(): T?
}
```

To support a potentially nullable type, the Objective-C header needs to define `myVal` with a nullable return value.

To mitigate this, when defining your generic classes, provide a non-nullable type constraint if the generic type should
_never_ be null:

```kotlin
class Sample<T : Any>() {
    fun myVal(): T
}
```

That will force the Objective-C header to mark `myVal` as non-nullable.

#### Variance

Objective-C allows generics to be declared covariant or contravariant. Swift has no support for variance. Generic classes coming
from Objective-C can be force-cast as needed.

```kotlin
data class SomeData(val num: Int = 42) : BaseData()
class GenVarOut<out T : Any>(val arg: T)
```

```swift
let variOut = GenVarOut<SomeData>(arg: sd)
let variOutAny : GenVarOut<BaseData> = variOut as! GenVarOut<BaseData>
```

#### Constraints

In Kotlin, you can provide upper bounds for a generic type. Objective-C also supports this, but that support is unavailable 
in more complex cases and is currently not supported in the Kotlin - Objective-C interop. The exception here being a non-nullable
upper bound will make Objective-C methods/properties non-nullable.

#### To disable

To have the framework header written without generics, add the following compiler option in your build file:

```kotlin
binaries.framework {
    freeCompilerArgs += "-Xno-objc-generics"
}
```

### Forward declarations

To import forward declarations, use the `objcnames.classes` and `objcnames.protocols` packages. For example,
to import a `objcprotocolName` forward declaration declared in an Objective-C library with a `library.package`,
use a special forward declaration package: `import objcnames.protocols.objcprotocolName`.

Consider two objcinterop libraries: one that uses `objcnames.protocols.ForwardDeclaredProtocolProtocol`
and another with an actual implementation in another package:

```ObjC
// First objcinterop library
#import <Foundation/Foundation.h>

@protocol ForwardDeclaredProtocol;

NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
    return [NSString stringWithUTF8String:"Protocol"];
}
```

```ObjC
// Second objcinterop library
// Header:
#import <Foundation/Foundation.h>
@protocol ForwardDeclaredProtocol
@end
// Implementation:
@interface ForwardDeclaredProtocolImpl : NSObject <ForwardDeclaredProtocol>
@end

id<ForwardDeclaredProtocol> produceProtocol() {
    return [ForwardDeclaredProtocolImpl new];
}
```

To transfer objects between the two libraries, use an explicit `as` cast in your Kotlin code:

```kotlin
// Kotlin code:
fun test() {
    consumeProtocol(produceProtocol() as objcnames.protocols.ForwardDeclaredProtocolProtocol)
}
```

> You can only cast to `objcnames.protocols.ForwardDeclaredProtocolProtocol` from the corresponding real class.
> Otherwise, you'll get an error.
>
{style="note"}

## Casting between mapped types

When writing Kotlin code, an object may need to be converted from a Kotlin type to the equivalent Swift/Objective-C type
or vice versa. In this case, you can use the [`as` cast](typecasts.md#unsafe-cast-operator), for example:

```kotlin
@file:Suppress("CAST_NEVER_SUCCEEDS")
import platform.Foundation.*

val nsNumber = 42 as NSNumber
val nsArray = listOf(1, 2, 3) as NSArray
val nsString = "Hello" as NSString
val string = nsString as String
```

IDEs might incorrectly emit "This cast can never succeed" warnings.
In such cases, use the `@Suppress("CAST_NEVER_SUCCEEDS")` annotation.

## Subclassing

### Subclassing Kotlin classes and interfaces from Swift/Objective-C

Kotlin classes and interfaces can be subclassed by Swift/Objective-C classes and protocols.

### Subclassing Swift/Objective-C classes and protocols from Kotlin

Swift/Objective-C classes and protocols can be subclassed with a Kotlin `final` class. Non-`final` Kotlin classes
inheriting Swift/Objective-C types aren't supported yet, so it is not possible to declare a complex class hierarchy
inheriting Swift/Objective-C types.

Normal methods can be overridden using the `override` Kotlin keyword. In this case, the overriding method must have the
same parameter names as the overridden one.

Sometimes it is required to override initializers, for example when subclassing `UIViewController`. Initializers imported
as Kotlin constructors can be overridden by Kotlin constructors marked with the `@OverrideInit` annotation:

```swift
class ViewController : UIViewController {
    @OverrideInit constructor(coder: NSCoder) : super(coder)

    ...
}
```

The overriding constructor must have the same parameter names and types as the overridden one.

To override different methods with clashing Kotlin signatures, you can add the `@ObjCSignatureOverride` annotation to the class.
The annotation instructs the Kotlin compiler to ignore conflicting overloads, in case several functions with the same
argument types, but different argument names, are inherited from the Objective-C class.

By default, the Kotlin/Native compiler doesn't allow calling a non-designated Objective-C initializer as a `super()`
constructor. This behavior can be inconvenient if the designated initializers aren't marked properly in the Objective-C
library. To disable these compiler checks, add the `disableDesignatedInitializerChecks = true` to the library's [`.def` file](native-definition-file.md).

## C features

See [Interoperability with C](native-c-interop.md) for an example case where the library uses some plain C features,
such as unsafe pointers, structs, and so on.

## Unsupported

Some features of the Kotlin programming language are not yet mapped into the respective features of Objective-C or Swift.
Currently, the following features are not properly exposed in generated framework headers:

* Inline classes (arguments are mapped as either underlying primitive type or `id`)
* Custom classes implementing standard Kotlin collection interfaces (`List`, `Map`, `Set`) and other special classes
* Kotlin subclasses of Objective-C classes
