Generic Structure

UnsafeMutablePointer

A pointer for accessing and manipulating data of a specific type.

Overview

You use instances of the UnsafeMutablePointer type to access data of a specific type in memory. The type of data that a pointer can access is the pointer’s Pointee type. UnsafeMutablePointer provides no automated memory management or alignment guarantees. You are responsible for handling the life cycle of any memory you work with through unsafe pointers to avoid leaks or undefined behavior.

Memory that you manually manage can be either untyped or bound to a specific type. You use the UnsafeMutablePointer type to access and manage memory that has been bound to a specific type.

Understanding a Pointer’s Memory State

The memory referenced by an UnsafeMutablePointer instance can be in one of several states. Many pointer operations must only be applied to pointers with memory in a specific state—you must keep track of the state of the memory you are working with and understand the changes to that state that different operations perform. Memory can be untyped and uninitialized, bound to a type and uninitialized, or bound to a type and initialized to a value. Finally, memory that was allocated previously may have been deallocated, leaving existing pointers referencing unallocated memory.

Uninitialized Memory

Memory that has just been allocated through a typed pointer or has been deinitialized is in an uninitialized state. Uninitialized memory must be initialized before it can be accessed for reading.

You can use methods like initialize(to:count:), initialize(from:), and moveInitializeMemory(from:count) to initialize the memory referenced by a pointer with a value or series of values.

Initialized Memory

Initialized memory has a value that can be read using a pointer’s pointee property or through subscript notation. In the following example, ptr is a pointer to memory initialized with a value of 23:

let ptr: UnsafeMutablePointer<Int> = ...
// ptr.pointee == 23
// ptr[0] == 23

Accessing a Pointer’s Memory as a Different Type

When you access memory through an UnsafeMutablePointer instance, the Pointee type must be consistent with the bound type of the memory. If you do need to access memory that is bound to one type as a different type, Swift’s pointer types provide type-safe ways to temporarily or permanently change the bound type of the memory, or to load typed instances directly from raw memory.

An UnsafeMutablePointer<UInt8> instance allocated with eight bytes of memory, uint8Pointer, will be used for the examples below.

let uint8Pointer = UnsafeMutablePointer<UInt8>.allocate(capacity: 8)
uint8Pointer.initialize(from: [39, 77, 111, 111, 102, 33, 39, 0])

When you only need to temporarily access a pointer’s memory as a different type, use the withMemoryRebound(to:capacity:) method. For example, you can use this method to call an API that expects a pointer to a different type that is layout compatible with your pointer’s Pointee. The following code temporarily rebinds the memory that uint8Pointer references from UInt8 to Int8 to call the imported C strlen function.

// Imported from C
func strlen(_ __s: UnsafePointer<Int8>!) -> UInt

let length = uint8Pointer.withMemoryRebound(to: Int8.self, capacity: 8) {
    return strlen($0)
}
// length == 7

When you need to permanently rebind memory to a different type, first obtain a raw pointer to the memory and then call the bindMemory(to:capacity:) method on the raw pointer. The following example binds the memory referenced by uint8Pointer to one instance of the UInt64 type:

let uint64Pointer = UnsafeMutableRawPointer(uint64Pointer)
                          .bindMemory(to: UInt64.self, capacity: 1)

After rebinding the memory referenced by uint8Pointer to UInt64, accessing that pointer’s referenced memory as a UInt8 instance is undefined.

var fullInteger = uint64Pointer.pointee          // OK
var firstByte = uint8Pointer.pointee             // undefined

Alternatively, you can access the same memory as a different type without rebinding through untyped memory access, so long as the bound type and the destination type are trivial types. Convert your pointer to an UnsafeMutableRawPointer instance and then use the raw pointer’s load(fromByteOffset:as:) and storeBytes(of:toByteOffset:as:) methods to read and write values.

let rawPointer = UnsafeMutableRawPointer(uint64Pointer)
fullInteger = rawPointer.load(as: UInt64.self)   // OK
firstByte = rawPointer.load(as: UInt8.self)      // OK

Performing Typed Pointer Arithmetic

Pointer arithmetic with a typed pointer is counted in strides of the pointer’s Pointee type. When you add to or subtract from an UnsafeMutablePointer instance, the result is a new pointer of the same type, offset by that number of instances of the Pointee type.

// 'intPointer' points to memory initialized with [10, 20, 30, 40]
let intPointer: UnsafeMutablePointer<Int> = ...

// Load the first value in memory
let x = intPointer.pointee
// x == 10

// Load the third value in memory
let offsetPointer = intPointer + 2
let y = offsetPointer.pointee
// y == 30

You can also use subscript notation to access the value in memory at a specific offset.

let z = intPointer[2]
// z == 30

Implicit Casting and Bridging

When calling a function or method with an UnsafeMutablePointer parameter, you can pass an instance of that specific pointer type or use Swift’s implicit bridging to pass a compatible pointer.

For example, the printInt(atAddress:) function in the following code sample expects an UnsafeMutablePointer<Int> instance as its first parameter:

func printInt(atAddress p: UnsafeMutablePointer<Int>) {
    print(p.pointee)
}

As is typical in Swift, you can call the printInt(atAddress:) function with an UnsafeMutablePointer instance. This example passes intPointer, a mutable pointer to an Int value, to print(address:).

printInt(atAddress: intPointer)
// Prints "42"

Alternatively, you can use Swift’s implicit bridging to pass a pointer to an instance or to the elements of an array. The following example passes a pointer to the value variable by using inout syntax:

var value: Int = 23
printInt(atAddress: &value)
// Prints "23"

A mutable pointer to the elements of an array is implicitly created when you pass the array using inout syntax. This example uses implicit bridging to pass a pointer to the elements of numbers when calling printInt(atAddress:).

var numbers = [5, 10, 15, 20]
printInt(atAddress: &numbers)
// Prints "5"

However you call printInt(atAddress:), Swift’s type safety guarantees that you can only pass a pointer to the type required by the function—in this case, a pointer to an Int.

Symbols

Type Aliases

Distance

A type that represents the distance between two pointers.

Initializers

init(OpaquePointer)

Creates a new typed pointer from the given opaque pointer.

init?(OpaquePointer?)

Creates a new typed pointer from the given opaque pointer.

init(UnsafeMutablePointer<Pointee>)

Creates a new pointer from the given typed pointer.

init?(UnsafeMutablePointer<Pointee>?)

Creates a new pointer from the given typed pointer.

init?(bitPattern: Int)

Creates a new typed pointer from the given address, specified as a bit pattern.

init?(bitPattern: UInt)

Creates a new typed pointer from the given address, specified as a bit pattern.

init?(mutating: UnsafePointer<Pointee>?)

Creates a mutable typed pointer referencing the same memory as the given immutable pointer.

init(mutating: UnsafePointer<Pointee>)

Creates a mutable typed pointer referencing the same memory as the given immutable pointer.

Instance Properties

var customMirror: Mirrorvar customPlaygroundQuickLook: PlaygroundQuickLook
var debugDescription: String

A textual representation of the pointer, suitable for debugging.

var hashValue: Int

The pointer’s hash value.

var pointee: Pointee

Accesses the instance referenced by this pointer.

Instance Methods

func advanced(by: Int)

Returns a pointer offset from this pointer by the specified number of instances.

func assign(from: UnsafePointer<Pointee>, count: Int)

Replaces this pointer’s initialized memory with the specified number of instances from the given pointer’s memory.

func deallocate(capacity: Int)

Deallocates memory that was allocated for count instances of Pointee.

func deinitialize(count: Int)

Deinitializes the specified number of values starting at this pointer.

func distance(to: UnsafeMutablePointer<Pointee>)

Returns the distance from this pointer to the given pointer, counted as instances of the pointer’s Pointee type.

func initialize(from: UnsafePointer<Pointee>, count: Int)

Initializes the memory referenced by this pointer with the values starting at the given pointer.

func initialize(to: Pointee, count: Int)

Initializes this pointer’s memory with the specified number of consecutive copies of the given value.

func move()

Retrieves and returns the referenced instance, returning the pointer’s memory to an uninitialized state.

func moveAssign(from: UnsafeMutablePointer<Pointee>, count: Int)

Replaces the memory referenced by this pointer with the values starting at the given pointer, and then deinitializes the source memory.

func moveInitialize(from: UnsafeMutablePointer<Pointee>, count: Int)

Initializes the memory referenced by this pointer with the values starting at the given pointer, and then deinitializes the source memory.

func predecessor()

Returns a pointer to the previous consecutive instance.

func successor()

Returns a pointer to the next consecutive instance.

func withMemoryRebound<T, Result>(to: T.Type, capacity: Int, (UnsafeMutablePointer<T>) -> Result)

Executes the given closure while temporarily binding the specified number of instances to the given type.

Type Methods

static func allocate(capacity: Int)

Allocates uninitialized memory for the specified number of instances of type Pointee.

Subscripts

subscript(Int)

Accesses the pointee at the specified offset from this pointer.

Operator Functions

static func +(UnsafeMutablePointer<Pointee>, Int)

Creates a new pointer, offset from a pointer by a specified number of instances of the pointer’s Pointee type.

static func +(Int, UnsafeMutablePointer<Pointee>)

Creates a new pointer, offset from a pointer by a specified number of instances of the pointer’s Pointee type.

static func +=(inout UnsafeMutablePointer<Pointee>, Int)

Advances a pointer by a specified number of instances of the pointer’s Pointee type.

static func -(UnsafeMutablePointer<Pointee>, Int)

Creates a new pointer, offset backward from a pointer by a specified number of instances of the pointer’s Pointee type.

static func -(UnsafeMutablePointer<Pointee>, UnsafeMutablePointer<Pointee>)

Returns the distance between two pointers, counted as instances of the pointers’ Pointee type.

static func -=(inout UnsafeMutablePointer<Pointee>, Int)

Shifts a pointer backward by a specified number of instances of the pointer’s Pointee type.

static func <(UnsafeMutablePointer<Pointee>, UnsafeMutablePointer<Pointee>)

Returns a Boolean value indicating whether the first pointer references an earlier memory location than the second pointer.

static func ==(UnsafeMutablePointer<Pointee>, UnsafeMutablePointer<Pointee>)

Returns a Boolean value indicating whether two pointers are equal.