UnsafeMutableRawPointer

A raw pointer for accessing and manipulating untyped data.

The UnsafeMutableRawPointer type provides no automated memory management, no type safety, and no 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 UnsafeMutableRawPointer type to access and manage raw bytes in memory, whether or not that memory has been bound to a specific type.

Understanding a Pointer's Memory State

The memory referenced by an UnsafeMutableRawPointer 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.

Raw, Uninitialized Memory

Raw memory that has just been allocated is in an uninitialized, untyped state. Uninitialized memory must be initialized with values of a type before it can be used with any typed operations.

You can use methods like initializeMemory(as:from:) and moveInitializeMemory(as:from:count) to bind raw memory to a type and initialize it with a value or series of values. To bind uninitialized memory to a type without initializing it, use the bindMemory(to:count:) method. These methods all return typed pointers for further typed access to the memory.

Typed Memory

Memory that has been bound to a type, whether it is initialized or uninitialized, is typically accessed using typed pointers---instances of UnsafePointer and UnsafeMutablePointer. Initialization, assignment, and deinitialization can be performed using UnsafeMutablePointer methods.

Memory that has been bound to a type can be rebound to a different type only after it has been deinitialized or if the bound type is a trivial type. Deinitializing typed memory does not unbind that memory's type. The deinitialized memory can be reinitialized with values of the same type, bound to a new type, or deallocated.

Note: A trivial type can be copied bit for bit with no indirection or reference-counting operations. Generally, native Swift types that do not contain strong or weak references or other forms of indirection are trivial, as are imported C structs and enumerations.

When reading from or writing to memory as raw bytes when that memory is bound to a type, you must ensure that you satisfy any alignment requirements. Writing to typed memory as raw bytes must only be performed when the bound type is a trivial type.

Raw Pointer Arithmetic

Pointer arithmetic with raw pointers is performed at the byte level. When you add to or subtract from a raw pointer, the result is a new raw pointer offset by that number of bytes. The following example allocates four bytes of memory and stores 0xFF in all four bytes:

  • let bytesPointer = UnsafeMutableRawPointer.allocate(bytes: 4, alignedTo: 1)
  • bytesPointer.storeBytes(of: 0xFFFF_FFFF, as: UInt32.self)
  •  
  • // Load a value from the memory referenced by 'bytesPointer'
  • let x = bytesPointer.load(as: UInt8.self)       // 255
  •  
  • // Load a value from the last two allocated bytes
  • let offsetPointer = bytesPointer + 2
  • let y = offsetPointer.load(as: UInt16.self)     // 65535

The code above stores the value 0xFFFF_FFFF into the four newly allocated bytes, and then loads the first byte as a UInt8 instance and the third and fourth bytes as a UInt16 instance.

Always remember to deallocate any memory that you allocate yourself.

  • bytesPointer.deallocate(bytes: 4, alignedTo: 1)

Implicit Casting and Bridging

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

For example, the print(address:as:) function in the following code sample takes an UnsafeMutableRawPointer instance as its first parameter:

  • func print<T>(address p: UnsafeMutableRawPointer, as type: T.Type) {
  •     let value = p.load(as: type)
  •     print(value)
  • }

As is typical in Swift, you can call the print(address:as:) function with an UnsafeMutableRawPointer instance. This example passes rawPointer as the initial parameter.

  • // 'rawPointer' points to memory initialized with `Int` values.
  • let rawPointer: UnsafeMutableRawPointer = ...
  • print(address: rawPointer, as: Int.self)
  • // Prints "42"

Because typed pointers can be implicitly cast to raw pointers when passed as a parameter, you can also call print(address:as:) with any mutable typed pointer instance.

Alternatively, you can use Swift's implicit bridging to pass a pointer to an instance or to the elements of an array. Use inout syntax to implicitly create a pointer to an instance of any type. The following example uses implicit bridging to pass a pointer to value when calling print(address:as:):

  • var value: Int = 23
  • print(address: &value, as: Int.self)
  • // 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 print(address:as:).

  • var numbers = [5, 10, 15, 20]
  • print(address: &numbers, as: Int.self)
  • // Prints "5"

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 UnsafeMutableRawPointer initializer.

  • var number = 5
  • let numberPointer = UnsafeMutableRawPointer(&number)
  • // Accessing 'numberPointer' is undefined behavior.
Inheritance Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, Equatable, Hashable, Strideable View Protocol Hierarchy →
Import
  • import Swift

Initializers

init(_: OpaquePointer)

Creates a new raw pointer from the given opaque pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

other: The opaque pointer to convert.

Declaration

init(_: UnsafeMutableRawPointer)

Creates a new raw pointer from the given raw or typed pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

other: The pointer to convert.

Declaration

init<T>(_: AutoreleasingUnsafeMutablePointer<T>)

Creates a new raw pointer from an AutoreleasingUnsafeMutablePointer instance.

other: The pointer to convert.

Declaration

init<T>(_: UnsafeMutablePointer<T>)

Creates a new raw pointer from the given typed pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

other: The typed pointer to convert.

Declaration

init(mutating:)

Creates a new mutable raw pointer from the given immutable raw pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

other: The immutable raw pointer to convert.

Declaration

init?(_: OpaquePointer?)

Creates a new raw pointer from the given opaque pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

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

Declaration

init?(_: UnsafeMutableRawPointer?)

Creates a new raw pointer from the given raw or typed pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

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

Declaration

init?<T>(_: AutoreleasingUnsafeMutablePointer<T>?)

Creates a new raw pointer from an AutoreleasingUnsafeMutablePointer instance.

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

Declaration

init?<T>(_: UnsafeMutablePointer<T>?)

Creates a new raw pointer from the given typed pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

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

Declaration

init?(bitPattern: Int)

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

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

Declaration

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

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

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

Declaration

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

Creates a new mutable raw pointer from the given immutable raw pointer.

Use this initializer to explicitly convert other to an UnsafeMutableRawPointer instance. This initializer creates a new pointer to the same address as other and performs no allocation or copying.

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

Declaration

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 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 }

Static Methods

static func allocate(bytes:alignedTo:)

Allocates uninitialized memory with the specified size and alignment.

You are in charge of managing the allocated memory. Be sure to deallocate any memory that you manually allocate.

The allocated memory is not bound to any specific type and must be bound before performing any typed operations. If you are using the memory for a specific type, allocate memory using the UnsafeMutablePointer.allocate(capacity:) static method instead.

Parameters: size: The number of bytes to allocate. size must not be negative. alignedTo: The alignment of the new region of allocated memory. Returns: A pointer to a newly allocated region of memory. The memory is allocated, but not initialized.

See Also: UnsafeMutablePointer

Declaration

Instance Methods

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 ==(_: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 advanced(by:)

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

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 bytes to offset this pointer. n may be positive, negative, or zero. Returns: A pointer offset from this pointer by n bytes.

Declaration

func assumingMemoryBound(_:)

Returns a typed pointer to the memory referenced by this pointer, assuming that the memory is already bound to the specified type.

Use this method when you have a raw pointer to memory that has already been bound to the specified type. The memory starting at this pointer must be bound to the type T. Accessing memory through the returned pointer is undefined if the memory has not been bound to T. To bind memory to T, use bindMemory(to:capacity:) instead of this method.

to: The type T that the memory has already been bound to. Returns: A typed pointer to the same memory as this raw pointer.

See Also: bindMemory(to:capacity:)

Declaration

func bindMemory(to:capacity:)

Binds the memory to the specified type and returns a typed pointer to the bound memory.

Use the bindMemory(to:capacity:) method to bind the memory referenced by this pointer to the type T. The memory must be uninitialized or initialized to a type that is layout compatible with T. If the memory is uninitialized, it is still uninitialized after being bound to T.

In this example, 100 bytes of raw memory are allocated for the pointer bytesPointer, and then the first four bytes are bound to the Int8 type.

After calling bindMemory(to:capacity:), the first four bytes of the memory referenced by bytesPointer are bound to the Int8 type, though they remain uninitialized. The remainder of the allocated region is unbound raw memory. All 100 bytes of memory must eventually be deallocated.

Warning: A memory location may only be bound to one type at a time. The behavior of accessing memory as a type unrelated to its bound type is undefined.

Parameters: type: The type T to bind the memory to. count: The amount of memory to bind to type T, counted as instances of T. Returns: A typed pointer to the newly bound memory. The memory in this region is bound to T, but has not been modified in any other way. The number of bytes in this region is count * MemoryLayout<T>.stride.

Declaration

func copyBytes(from:count:)

Copies the specified number of bytes from the given raw pointer's memory into this pointer's memory.

If the count bytes of memory referenced by this pointer are bound to a type T, then T must be a trivial type, this pointer and source must be properly aligned for accessing T, and count must be a multiple of MemoryLayout<T>.stride.

After calling copyBytes(from:count:), the count bytes of memory referenced by this pointer are initialized to raw bytes. If the memory is bound to type T, then it contains values of type T.

Parameters: source: A pointer to the memory to copy bytes from. The memory in the region source..<(source + count) must be initialized to a trivial type. count: The number of bytes to copy. count must not be negative.

Declaration

func deallocate(bytes:alignedTo:)

Deallocates memory referenced by the pointer with the specified size and alignment.

The memory to be deallocated must be uninitialized or initialized to a trivial type.

Parameters: size: The number of bytes to deallocate. alignedTo: The alignment of the region to be deallocated.

Declaration

  • func deallocate(bytes size: Int, alignedTo: Int)
func distance(to:)

Returns the distance from this pointer to the given pointer.

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

x: The pointer to calculate the distance to. Returns: The distance from this pointer to x, in bytes.

Declaration

func initializeMemory(as:at:count:to:)

Initializes the memory referenced by this pointer with the given value, binds the memory to the value's type, and returns a typed pointer to the initialized memory.

The memory referenced by this pointer must be uninitialized or initialized to a trivial type, and must be properly aligned for accessing T.

The following example allocates enough raw memory to hold four instances of Int8, and then uses the initializeMemory(as:at:count:to:) method to initialize the allocated memory.

  • let count = 4
  • let bytesPointer = UnsafeMutableRawPointer.allocate(
  •         bytes: count * MemoryLayout<Int8>.stride,
  •         alignedTo: MemoryLayout<Int8>.alignment)
  • let int8Pointer = myBytes.initializeMemory(
  •         as: Int8.self, count: count, value: 0)
  •  
  • // After using 'int8Pointer':
  • int8Pointer.deallocate(count)

After calling this method on a raw pointer p, the region starting at p + index * MemoryLayout<T>.stride and continuing up to p + (index + count) * MemoryLayout<T>.stride is bound to type T and initialized. If T is a nontrivial type, you must eventually deinitialize or move from the values in this region to avoid leaks.

Parameters: type: The type to bind this memory to. index: The offset from this pointer to the region of memory to be initialized with value, in the stride of type T. index must not be negative. The default is zero. count: The number of copies of value to copy into memory. count must not be negative. The default is 1. value: The instance to copy into memory. Returns: A typed pointer to the memory referenced by this raw pointer, offset by index * MemoryLayout<T>.stride bytes.

Declaration

func initializeMemory(as:from:)

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

Declaration

func initializeMemory(as:from:count:)

Initializes the memory referenced by this pointer with the values starting at the given pointer, binds the memory to the values' type, and returns a typed pointer to the initialized memory.

The memory referenced by this pointer must be uninitialized or initialized to a trivial type, and must be properly aligned for accessing T.

The following example allocates enough raw memory to hold four instances of Int8, and then uses the initializeMemory(as:from:count:) method to initialize the allocated memory.

  • let count = 4
  • let bytesPointer = UnsafeMutableRawPointer.allocate(
  •         bytes: count * MemoryLayout<Int8>.stride,
  •         alignedTo: MemoryLayout<Int8>.alignment)
  • let values: [Int8] = [1, 2, 3, 4]
  • let int8Pointer = values.withUnsafeBufferPointer { buffer in
  •     return bytesPointer.initializeMemory(as: Int8.self,
  •               from: buffer.baseAddress!,
  •               count: buffer.count)
  • }
  • // int8Pointer.pointee == 1
  • // (int8Pointer + 3).pointee == 4
  •  
  • // After using 'int8Pointer':
  • int8Pointer.deallocate(count)

After calling this method on a raw pointer p, the region starting at p and continuing up to p + count * MemoryLayout<T>.stride is bound to type T and initialized. If T is a nontrivial type, you must eventually deinitialize or move from the values in this region to avoid leaks. The instances in the region source..<(source + count) are unaffected.

Parameters: type: The type to bind this memory to. source: A pointer to the values to copy. The memory in the region source..<(source + count) must be initialized to type T and must not overlap the destination region. count: The number of copies of value to copy into memory. count must not be negative. Returns: A typed pointer to the memory referenced by this raw pointer.

Declaration

func load(fromByteOffset:as:)

Returns a new instance of the given type, constructed from the raw memory at the specified offset.

The memory at this pointer plus offset must be properly aligned for accessing T and initialized to T or another type that is layout compatible with T.

Parameters: offset: The offset from this pointer, in bytes. offset must be nonnegative. The default is zero. type: The type of the instance to create. Returns: A new instance of type T, read from the raw bytes at offset. The returned instance is memory-managed and unassociated with the value in the memory referenced by this pointer.

Declaration

  • func load<T>(fromByteOffset offset: Int = default, as type: T.Type) -> T
func moveInitializeMemory(as:from:count:)

Initializes the memory referenced by this pointer with the values starting at the given pointer, binds the memory to the values' type, deinitializes the source memory, and returns a typed pointer to the newly initialized memory.

The memory referenced by this pointer must be uninitialized or initialized to a trivial type, and must be properly aligned for accessing T.

The memory in the region source..<(source + count) may overlap with the destination region. The moveInitializeMemory(as:from:count:) method automatically performs a forward or backward copy of all instances from the source region to their destination.

After calling this method on a raw pointer p, the region starting at p and continuing up to p + count * MemoryLayout<T>.stride is bound to type T and initialized. If T is a nontrivial type, you must eventually deinitialize or move from the values in this region to avoid leaks. Any memory in the region source..<(source + count) that does not overlap with the destination region is returned to an uninitialized state.

Parameters: type: The type to bind this memory to. source: A pointer to the values to copy. The memory in the region source..<(source + count) must be initialized to type T. count: The number of copies of value to copy into memory. count must not be negative. Returns: A typed pointer to the memory referenced by this raw pointer.

Declaration

func storeBytes(of:toByteOffset:as:)

Stores the given value's bytes into raw memory at the specified offset.

The type T to be stored must be a trivial type. The memory at this pointer plus offset must be properly aligned for accessing T. The memory must also be uninitialized, initialized to T, or initialized to another trivial type that is layout compatible with T.

After calling storeBytes(of:toByteOffset:as:), the memory is initialized to the raw bytes of value. If the memory is bound to a type U that is layout compatible with T, then it contains a value of type U. Calling storeBytes(of:toByteOffset:as:) does not change the bound type of the memory.

Note: A trivial type can be copied with just a bit-for-bit copy without any indirection or reference-counting operations. Generally, native Swift types that do not contain strong or weak references or other forms of indirection are trivial, as are imported C structs and enums.

If you need to store a copy of a nontrivial value into memory, or to store a value into memory that contains a nontrivial value, you cannot use the storeBytes(of:toByteOffset:as:) method. Instead, you must know the type of value previously in memory and initialize or assign the memory. For example, to replace a value stored in a raw pointer p, where U is the current type and T is the new type, use a typed pointer to access and deinitialize the current value before initializing the memory with a new value.

  • let typedPointer = p.bindMemory(to: U.self, capacity: 1)
  • typedPointer.deinitialize(count: 1)
  • p.initializeMemory(as: T.self, to: newValue)

Parameters: value: The value to store as raw bytes. offset: The offset from this pointer, in bytes. offset must be nonnegative. The default is zero. type: The type of value.

Declaration

  • func storeBytes<T>(of value: T, toByteOffset offset: Int = default, as type: T.Type)