Generics

What it is and why it exists

A generic declaration replaces one or more concrete types with named type parameters . When you call a generic function, its arguments and expected return type determine those parameters together. When you construct a generic type, the type arguments in angle brackets determine its storage and member signatures. Array<Int> and Array<String> share one declaration but are different static types.

Generics don’t mean “accept any value.” They mean “preserve a relationship without knowing the concrete type.” A function declared as choose<T>(_ left: T, _ right: T) -> T says that both parameters and the result use one T. Replacing all three positions with Any removes that guarantee and makes the caller cast the result.

You meet generics throughout the Swift standard library in Array<Element>, Dictionary<Key, Value>, Optional<Wrapped>, and Result<Success, Failure>. Application code also uses them for containers, transformations, data-access boundaries, and reusable algorithms. Code that serves one well-defined domain type doesn’t need to become generic for appearance’s sake.

A type parameter has no comparison, hashing, encoding, or domain-specific members on its own. When an implementation needs an ability, it declares a generic constraint , usually by requiring protocol conformance. The constraint lets the body use protocol members and rejects calls whose concrete types don’t qualify.

A generic abstraction should preserve type information that matters to its callers. A parameter that is only logged or returned unchanged may need no constraint. If an algorithm makes business sense only for Int, a concrete type is more honest. The contract, not the number of angle brackets, determines whether the abstraction is useful.

How it works

A generic function declares its parameter list after the function name, as in <Element>. The compiler collects requirements from every argument, explicit type annotation, and surrounding expression, then solves for a consistent concrete type. Swift doesn’t support call-site syntax such as identity<Int>(42) to specialize a generic function explicitly. When inference needs help, annotate an argument or the receiving result.

A colon constraint expresses protocol conformance or class inheritance. <Element: Comparable> lets the body use the comparison operations guaranteed by Comparable, but it doesn’t grant Hashable or Codable. You can write multiple requirements in the generic parameter list or move them into a where clause.

A where clause can constrain associated types and declare that two type expressions must be equal. Left.Element == Right.Element is a same-type requirement : the collection types may differ, but their elements must match. A generic declaration is available only when the compiler can prove every requirement at the call site.

A generic type includes its type parameters in its type identity. Stack<String> has a push that accepts String and a pop that returns String?; the same members use Int on Stack<Int>. You can’t change one Stack<String> instance into a stack of integers after construction.

An associated type in a protocol is selected by the conforming type. Associated types and generic parameters both express type relationships, but the choice happens in different places: users supply a generic type’s arguments, while conformers determine a protocol’s associated types through their implementations. The compiler can usually infer an associated type from property and method signatures, so an explicit typealias isn’t required.

Read the common forms by asking who declares the placeholder and who supplies its concrete type:

Type inference isn’t dynamic typing. Every expression still has a definite static type after compilation; inference merely avoids repeating it in source. When an error becomes long, one meaningful annotation at the call boundary usually exposes the conflict more clearly than a pile of conversions inside the implementation.

Inference collects information in both directions

Type inference doesn’t flow only from arguments to results. An assignment target, closure parameter and result types, overload candidates, and literal defaults all join the same constraint-solving process. In let ids: Set<Int> = [], the left side determines the empty literal’s type; let ids = [] doesn’t provide enough information.

When inspecting one generic call, mark these four sources of information in order:

• The static type of each argument.
• Any expected type declared where the result is received.
• Operations the closure body applies to its parameters and result.
• Requirements introduced by the generic declaration, where clause, and selected overload.

Those facts must form one consistent solution. If two arguments imply incompatible choices for T, the compiler doesn’t pick one and doesn’t insert a numeric conversion. Decide which type the domain requires, then perform a named conversion at the boundary.

Constraints belong on the narrowest capability boundary

Constraints can appear on a generic declaration, method, constrained extension, or conditional conformance. Their position determines whether the whole API or one capability is restricted. Moving a requirement outward affects more unrelated members.

The narrowest location isn’t always a method. If a type invariant depends on dictionary keys, Key: Hashable belongs on the type. If only a diagnostic export needs encoding, Codable shouldn’t infect the core declaration. Start at the expression that uses the ability and move outward to the first stable API boundary.

Examples

These four standalone programs progress from generic functions to generic types, where constraints, and associated types. This environment has no local Swift toolchain, so each block carries the required not-executed marker. Each displayed output was separately checked with a Swift 6.3.3 compiler.

Inferring type parameters at the call site

The two parameters and result of earlier share Value. Its Comparable constraint makes < available, while repeated doesn’t inspect the value and needs no extra constraint.

The first call infers Value as Int, and the second infers String. Both arguments in any one call still need the same type. A generic function doesn’t automatically combine Int and Double into a shared numeric type.

The result also participates in inference. When the arguments aren’t enough, write let result: DesiredType = ... or first construct an input with a known type. Don’t let generated code fake an unprovable relationship with a forced cast.

The precondition describes the valid range of count, which is separate from a generic constraint. Generic constraints check type abilities; runtime preconditions check a particular value. Neither can replace the other.

Storing one element type in a generic type

Stack uses the same Element for storage, push, and pop. Its map method introduces a separate Output, so the transformed result can be a different stack type.

// # not executed here: Swift toolchain is not installed.
struct Stack<Element> {
    private var storage: [Element] = []

    var count: Int { storage.count }

    mutating func push(_ element: Element) {
        storage.append(element)
    }

    mutating func pop() -> Element? {
        storage.popLast()
    }

    func map<Output>(_ transform: (Element) -> Output) -> Stack<Output> {
        var result = Stack<Output>()
        for element in storage {
            result.push(transform(element))
        }
        return result
    }

    func values() -> [Element] { storage }
}

var jobs = Stack<String>()
jobs.push("build")
jobs.push("deploy")
let lengths = jobs.map { $0.count }

print(jobs.pop() ?? "none")
print(lengths.values())

deploy
[5, 6]

The type of jobs is fixed as Stack<String>, so push(3) fails at compile time. map doesn’t turn the original stack into an integer stack. It creates a new Stack<Int>, and that result type preserves the relationship across the transformation.

pop returns an optional because an empty stack is a valid state. Generics don’t decide boundary behavior for an API. Element? describes absence more accurately than a force unwrap or a sentinel value that couldn’t work for every possible Element.

This implementation deliberately keeps the interface small. If you add search, require Element: Equatable only on the constrained extension that provides that operation. Don’t make the whole Stack reject non-equatable elements.

Describing cross-type relationships with where

sameElements accepts two different collection types but requires their element types to match and support equality. unique only needs hashable sequence elements and removes duplicates while preserving first-seen order.

// # not executed here: Swift toolchain is not installed.
func sameElements<Left: Collection, Right: Collection>(
    _ left: Left,
    _ right: Right
) -> Bool where Left.Element == Right.Element, Left.Element: Equatable {
    left.elementsEqual(right)
}

func unique<Values: Sequence>(_ values: Values) -> [Values.Element]
where Values.Element: Hashable {
    var seen: Set<Values.Element> = []
    return values.filter { seen.insert($0).inserted }
}

let states = ["queued", "running", "done"]
let activeStates = states[0...1]

print(sameElements(["queued", "running"], activeStates))
print(sameElements(["running", "queued"], activeStates))
print(unique(["A", "B", "A", "C", "B"]))

true
false
["A", "B", "C"]

The left side is Array<String> and the right is ArraySlice<String>, so the collection types needn’t match. Left.Element == Right.Element proves that elementsEqual compares one element type, while Equatable supplies equality.

unique uses a Set to track elements it has seen, which requires Hashable. The requirement belongs to this function, not to unrelated operations on the input type. The returned array keeps first-seen order and doesn’t rely on a set’s iteration order.

Constraints are part of the public API. If a later implementation no longer needs hashing, consider removing Hashable. Leaving a stale constraint excludes types for which the function would otherwise work correctly.

Letting a conformer select an associated type

Catalog declares Item as a primary associated type . The angle brackets make it possible to constrain that type with Catalog<Product>, but they don’t turn the protocol itself into a generic type like a Catalog structure would be.

// # not executed here: Swift toolchain is not installed.
struct Product {
    let id: Int
    let name: String
}

protocol Catalog<Item> {
    associatedtype Item
    var items: [Item] { get }
}

struct MemoryCatalog<Item>: Catalog {
    let items: [Item]
}

func first<C: Catalog>(in catalog: C) -> C.Item? {
    catalog.items.first
}

func names(in catalog: some Catalog<Product>) -> [String] {
    catalog.items.map(\.name)
}

let products = MemoryCatalog(items: [
    Product(id: 1, name: "Keyboard"),
    Product(id: 2, name: "Mouse")
])

if let product = first(in: products) {
    print("First: \(product.name)")
}
print(names(in: products).joined(separator: ", "))

First: Keyboard
Keyboard, Mouse

MemoryCatalog<Product> lets the compiler infer Catalog.Item == Product from its items property. first preserves the associated type of any conformer and returns C.Item?; it doesn’t degrade the result to Any?.

In parameter position, some Catalog<Product> is a generic parameter that doesn’t need a source-level name. Each call still passes one concrete conforming type, and the body knows that its Item is Product. If two parameters must share exactly the same catalog type, name the type parameter and use it twice.

A primary associated type name must correspond to an associated type declared by the protocol. Its main purpose is concise constraints such as some Catalog<Product> or any Catalog<Product>. It doesn’t mean callers fill an ordinary generic argument on the protocol declaration.

Pitfalls

Supplying explicit type arguments to a function call

Fix: let the arguments and expected result drive inference, as in let value: Int = identity(42). If ambiguity remains, annotate the data boundary instead of covering the problem with as!.

Replacing a type parameter with Any

Fix: use a named type parameter when a relationship exists, such as [Element] -> Element?. Choose Any or an existential only when heterogeneous values are part of the data model and every runtime branch has defined behavior.

Applying a constraint too broadly

Fix: put each requirement on the method, extension, or conditional conformance that uses it, and remove protocols the implementation doesn’t use. Keep one compile test for a supported type and one for a type that should be rejected.

Expecting one type parameter to hold heterogeneous elements

Fix: use T: Shape when you need one concrete type and its static relationships. Use [any Shape] or an appropriate enum when one collection genuinely stores different conformers at runtime. That choice affects available members and type identity, not just spelling.

Treating some and any as interchangeable

Fix: first state who chooses the concrete type and whether it may vary between calls. Use a generic parameter when the caller supplies one concrete type, some when the implementation hides one result type, and any for genuine runtime heterogeneity.

Further reading

• Swift Language Guide: Generics
• Swift Language Guide: Protocols
• Swift 6.3 release notes