UnsafeMutablePointer

struct UnsafeMutablePointer<Pointee>

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

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.

Important: The pointer created through implicit bridging of an instance or of an array's elements is only valid during the execution of the called function. Escaping the pointer to use after the execution of the function is undefined behavior. In particular, do not use implicit bridging when calling an UnsafeMutablePointer initializer.

  var number = 5
  let numberPointer = UnsafeMutablePointer<Int>(&number)
  // Accessing 'numberPointer' is undefined behavior.
Inheritance CVarArg, Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, Equatable, Hashable, Strideable View Protocol Hierarchy →
Associated Types
Distance = Int

A type that represents the distance between two pointers.
Import import Swift

Initializers

init(_: OpaquePointer)

Creates a new typed pointer from the given opaque pointer.

from: The opaque pointer to convert to a typed pointer.

Declaration

init(_ from: OpaquePointer)
init(_: UnsafeMutablePointer<Pointee>)

Creates a new pointer from the given typed pointer.

other: The typed pointer to convert.

Declaration

init(_ other: UnsafeMutablePointer<Pointee>)
init(mutating:)

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

other: The immutable pointer to convert.

Declaration

init(mutating other: UnsafePointer<Pointee>)
init?(_: OpaquePointer?)

Creates a new typed pointer from the given opaque pointer.

from: The opaque pointer to convert to a typed pointer. If from is nil, the result of this initializer is nil.

Declaration

init?(_ from: OpaquePointer?)
init?(_: UnsafeMutablePointer<Pointee>?)

Creates a new pointer from the given typed pointer.

other: The typed pointer to convert. If other is nil, the result is nil.

Declaration

init?(_ other: UnsafeMutablePointer<Pointee>?)
init?(bitPattern: Int)

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

The address passed as bitPattern must have the correct alignment for the pointer's Pointee type. That is, bitPattern % MemoryLayout<Pointee>.alignment must be 0.

bitPattern: A bit pattern to use for the address of the new pointer. If bitPattern is zero, the result is nil.

Declaration

init?(bitPattern: Int)
init?(bitPattern: UInt)

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

The address passed as bitPattern must have the correct alignment for the pointer's Pointee type. That is, bitPattern % MemoryLayout<Pointee>.alignment must be 0.

bitPattern: A bit pattern to use for the address of the new pointer. If bitPattern is zero, the result is nil.

Declaration

init?(bitPattern: UInt)
init?(mutating:)

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

other: The immutable pointer to convert. If other is nil, the result is nil.

Declaration

init?(mutating other: UnsafePointer<Pointee>?)

Instance Variables

var customMirror: Mirror

The custom mirror for this instance.

If this type has value semantics, the mirror should be unaffected by subsequent mutations of the instance.

Declaration

var customMirror: Mirror { get }
var customPlaygroundQuickLook: PlaygroundQuickLook

A custom playground Quick Look for this instance.

If this type has value semantics, the PlaygroundQuickLook instance should be unaffected by subsequent mutations.

Declaration

var customPlaygroundQuickLook: PlaygroundQuickLook { get }
var debugDescription: String

A textual representation of the pointer, suitable for debugging.

Declaration

var debugDescription: String { get }
var hashValue: Int

The pointer's hash value.

The hash value is not guaranteed to be stable across different invocations of the same program. Do not persist the hash value across program runs.

Declaration

var hashValue: Int { get }
var pointee: Pointee

Accesses the instance referenced by this pointer.

When reading from the pointee property, the instance referenced by this pointer must already be initialized. When pointee is used as the left side of an assignment, the instance must be initialized or this pointer's Pointee type must be a trivial type.

Do not assign an instance of a nontrivial type through pointee to uninitialized memory. Instead, use an initializing method, such as initialize(to:count:).

Declaration

var pointee: Pointee { get set }

Subscripts

subscript(_: Int)

Accesses the pointee at the specified offset from this pointer.

For a pointer p, the memory at p + i must be initialized when reading the value by using the subscript. When the subscript is used as the left side of an assignment, the memory at p + i must be uninitialized or the pointer's Pointee type must be a trivial type.

Do not assign an instance of a nontrivial type through the subscript to uninitialized memory. Instead, use an initializing method, such as initialize(to:count:).

i: The offset from this pointer at which to access an instance, measured in strides of the pointer's Pointee type.

Declaration

subscript(i: Int) -> Pointee { get nonmutating set }

Static Methods

static func allocate(capacity:)

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

The resulting pointer references a region of memory that is bound to Pointee and is count * MemoryLayout<Pointee>.stride bytes in size. You must eventually deallocate the memory referenced by the returned pointer.

The following example allocates enough new memory to store four Int instances and then initializes that memory with the elements of a range.

let intPointer = UnsafeMutablePointer<Int>.allocate(capacity: 4)
intPointer.initialize(from: 1...4)
print(intPointer.pointee)
// Prints "1"

When you allocate memory, always remember to deallocate once you're finished.

intPointer.deallocate(capacity: 4)

count: The amount of memory to allocate, counted in instances of Pointee.

Declaration

static func allocate(capacity count: Int) -> UnsafeMutablePointer<Pointee>

Instance Methods

func +(_: Int, rhs: UnsafeMutablePointer<Pointee>)

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

You use the addition operator (+) to advance a pointer by a number of contiguous instances. The resulting pointer must be within the bounds of the same allocation as rhs.

Parameters: lhs: The number of strides of the pointer's Pointee type to offset rhs. To access the stride, use MemoryLayout<Pointee>.stride. rhs: A pointer. Returns: A pointer offset from rhs by lhs instances of the Pointee type.

See Also: MemoryLayout

Declaration

func +(lhs: Int, rhs: UnsafeMutablePointer<Pointee>) -> UnsafeMutablePointer<Pointee>
func +(_: UnsafeMutablePointer<Pointee>, rhs: Int)

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

You use the addition operator (+) to advance a pointer by a number of contiguous instances. The resulting pointer must be within the bounds of the same allocation as lhs.

Parameters: lhs: A pointer. rhs: The number of strides of the pointer's Pointee type to offset lhs. To access the stride, use MemoryLayout<Pointee>.stride. Returns: A pointer offset from lhs by rhs instances of the Pointee type.

See Also: MemoryLayout

Declaration

func +(lhs: UnsafeMutablePointer<Pointee>, rhs: Int) -> UnsafeMutablePointer<Pointee>
func +=(_:rhs:)

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

You use the addition assignment operator (+=) to advance a pointer by a number of contiguous instances. The resulting pointer must be within the bounds of the same allocation as rhs.

Parameters: lhs: A pointer to advance in place. rhs: The number of strides of the pointer's Pointee type to offset lhs. To access the stride, use MemoryLayout<Pointee>.stride.

See Also: MemoryLayout

Declaration

func +=(lhs: inout UnsafeMutablePointer<Pointee>, rhs: Int)
func <(_:rhs:)

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

Parameters: lhs: A pointer. rhs: Another pointer. Returns: true if lhs references a memory address earlier than rhs; otherwise, false.

Declaration

func <(lhs: UnsafeMutablePointer<Pointee>, rhs: UnsafeMutablePointer<Pointee>) -> Bool
func ==(_:rhs:)

Returns a Boolean value indicating whether two pointers are equal.

Parameters: lhs: A pointer. rhs: Another pointer. Returns: true if lhs and rhs reference the same memory address; otherwise, false.

Declaration

func ==(lhs: UnsafeMutablePointer<Pointee>, rhs: UnsafeMutablePointer<Pointee>) -> Bool
func -(_: UnsafeMutablePointer<Pointee>, rhs: Int)

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

You use the subtraction operator (-) to shift a pointer backward by a number of contiguous instances. The resulting pointer must be within the bounds of the same allocation as lhs.

Parameters: lhs: A pointer. rhs: The number of strides of the pointer's Pointee type to offset lhs. To access the stride, use MemoryLayout<Pointee>.stride. Returns: A pointer offset backward from lhs by rhs instances of the Pointee type.

See Also: MemoryLayout

Declaration

func -(lhs: UnsafeMutablePointer<Pointee>, rhs: Int) -> UnsafeMutablePointer<Pointee>
func -(_: UnsafeMutablePointer<Pointee>, rhs: UnsafeMutablePointer<Pointee>)

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

Typed pointers are required to be properly aligned for their Pointee type. Proper alignment ensures that the result of the subtraction operator (-) accurately measures the distance between the two pointers, counted in strides of Pointee. To find the distance in bytes between two pointers, convert them to UnsafeRawPointer instances before subtracting.

Parameters: lhs: A pointer. rhs: Another pointer. Returns: The distance from lhs to rhs, in strides of the pointer's Pointee type. To access the stride, use MemoryLayout<Pointee>.stride.

See Also: MemoryLayout

Declaration

func -(lhs: UnsafeMutablePointer<Pointee>, rhs: UnsafeMutablePointer<Pointee>) -> Int
func -=(_:rhs:)

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

You use the subtraction assignment operator (-=) to shift a pointer backward by a number of contiguous instances. The resulting pointer must be within the bounds of the same allocation as rhs.

Parameters: lhs: A pointer to advance in place. rhs: The number of strides of the pointer's Pointee type to offset lhs. To access the stride, use MemoryLayout<Pointee>.stride.

See Also: MemoryLayout

Declaration

func -=(lhs: inout UnsafeMutablePointer<Pointee>, rhs: Int)
func advanced(by:)

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

With pointer p and distance n, the result of p.advanced(by: n) is equivalent to p + n.

The resulting pointer must be within the bounds of the same allocation as this pointer.

n: The number of strides of the pointer's Pointee type to offset this pointer. To access the stride, use MemoryLayout<Pointee>.stride. n may be positive, negative, or zero. Returns: A pointer offset from this pointer by n instances of the Pointee type.

See Also: MemoryLayout

Declaration

func advanced(by n: Int) -> UnsafeMutablePointer<Pointee>
func assign(from:count:)

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

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be initialized or Pointee must be a trivial type. After calling assign(from:count:), the region is initialized.

Parameters: source: A pointer to at least count initialized instances of type Pointee. The memory regions referenced by source and this pointer may overlap. count: The number of instances to copy from the memory referenced by source to this pointer's memory. count must not be negative.

Declaration

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

Deallocates memory that was allocated for count instances of Pointee.

The memory region that is deallocated is capacity * MemoryLayout<Pointee>.stride bytes in size. The memory must not be initialized or Pointee must be a trivial type.

capacity: The amount of memory to deallocate, counted in instances of Pointee.

Declaration

func deallocate(capacity: Int)
func deinitialize(_:)

Deinitializes the specified number of values starting at this pointer.

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be initialized. After calling deinitialize(count:), the memory is uninitialized, but still bound to the Pointee type.

count: The number of instances to deinitialize. count must not be negative. The default value is 1. Returns: A raw pointer to the same address as this pointer. The memory referenced by the returned raw pointer is still bound to Pointee.

Declaration

func deinitialize(count: Int = default) -> UnsafeMutableRawPointer
func distance(to:)

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

With pointers p and q, the result of p.distance(to: q) is equivalent to q - p.

Typed pointers are required to be properly aligned for their Pointee type. Proper alignment ensures that the result of distance(to:) accurately measures the distance between the two pointers, counted in strides of Pointee. To find the distance in bytes between two pointers, convert them to UnsafeRawPointer instances before calling distance(to:).

end: The pointer to calculate the distance to. Returns: The distance from this pointer to end, in strides of the pointer's Pointee type. To access the stride, use MemoryLayout<Pointee>.stride.

See Also: MemoryLayout

Declaration

func distance(to end: UnsafeMutablePointer<Pointee>) -> Int
func initialize(from:)

Deprecated: it will be removed in Swift 4.0. Please use 'UnsafeMutableBufferPointer.initialize(from:)' instead.

Declaration

func initialize<C where C : Collection, C.Iterator.Element == Pointee>(from source: C)
func initialize(from:count:)

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

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be uninitialized or Pointee must be a trivial type. After calling initialize(from:count:), the region is initialized.

Parameters: source: A pointer to the values to copy. The memory region source..<(source + count) must be initialized. The memory regions referenced by source and this pointer must not overlap. count: The number of instances to move from source to this pointer's memory. count must not be negative.

Declaration

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

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

The destination memory must be uninitialized or the pointer's Pointee must be a trivial type. After a call to initialize(to:count:), the memory referenced by this pointer is initialized.

Parameters: newValue: The instance to initialize this pointer's memory with. count: The number of consecutive copies of newValue to initialize. count must not be negative. The default is 1.

Declaration

func initialize(to newValue: Pointee, count: Int = default)
func move()

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

Calling the move() method on a pointer p that references memory of type T is equivalent to the following code, aside from any cost and incidental side effects of copying and destroying the value:

let value: T = {
    defer { p.deinitialize() }
    return p.pointee
}()

The memory referenced by this pointer must be initialized. After calling move(), the memory is uninitialized.

Returns: The instance referenced by this pointer.

Declaration

func move() -> Pointee
func moveAssign(from:count:)

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

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be initialized or Pointee must be a trivial type. After calling initialize(from:count:), the region is initialized and the memory region source..<(source + count) is uninitialized.

Parameters: source: A pointer to the values to copy. The memory region source..<(source + count) must be initialized. The memory regions referenced by source and this pointer must not overlap. count: The number of instances to move from source to this pointer's memory. count must not be negative.

Declaration

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

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

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be uninitialized or Pointee must be a trivial type. After calling initialize(from:count:), the region is initialized and the memory region source..<(source + count) is uninitialized.

Parameters: source: A pointer to the values to copy. The memory region source..<(source + count) must be initialized. The memory regions referenced by source and this pointer may overlap. count: The number of instances to move from source to this pointer's memory. count must not be negative.

Declaration

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

Returns a pointer to the previous consecutive instance.

The resulting pointer must be within the bounds of the same allocation as this pointer.

Returns: A pointer shifted backward from this pointer by MemoryLayout<Pointee>.stride bytes.

Declaration

func predecessor() -> UnsafeMutablePointer<Pointee>
func successor()

Returns a pointer to the next consecutive instance.

The resulting pointer must be within the bounds of the same allocation as this pointer.

Returns: A pointer advanced from this pointer by MemoryLayout<Pointee>.stride bytes.

Declaration

func successor() -> UnsafeMutablePointer<Pointee>
func withMemoryRebound(to:capacity:_:)

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

Use this method when you have a pointer to memory bound to one type and you need to access that memory as instances of another type. Accessing memory as type T requires that the memory be bound to that type. A memory location may only be bound to one type at a time, so accessing the same memory as an unrelated type without first rebinding the memory is undefined.

The region of memory starting at this pointer and covering count instances of the pointer's Pointee type must be initialized.

The following example temporarily rebinds the memory of a UInt64 pointer to Int64, then accesses a property on the signed integer.

let uint64Pointer: UnsafeMutablePointer<UInt64> = fetchValue()
let isNegative = uint64Pointer.withMemoryRebound(to: Int64.self) { ptr in
    return ptr.pointee < 0
}

Because this pointer's memory is no longer bound to its Pointee type while the body closure executes, do not access memory using the original pointer from within body. Instead, use the body closure's pointer argument to access the values in memory as instances of type T.

After executing body, this method rebinds memory back to the original Pointee type.

Parameters: type: The type to temporarily bind the memory referenced by this pointer. The type T must be the same size and be layout compatible with the pointer's Pointee type. count: The number of instances of T to bind to type. body: A closure that takes a mutable typed pointer to the same memory as this pointer, only bound to type T. The closure's pointer argument is valid only for the duration of the closure's execution. If body has a return value, it is used as the return value for the withMemoryRebound(to:capacity:_:) method. Returns: The return value of the body closure parameter, if any.

Declaration

func withMemoryRebound<T, Result>(to type: T.Type, capacity count: Int, _ body: (UnsafeMutablePointer<T>) throws -> Result) rethrows -> Result