A raw pointer for accessing and manipulating untyped data.
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
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.
Memory that has been bound to a type, whether it is initialized or uninitialized, is typically accessed using typed pointers—instances of
UnsafeMutablePointer. Initialization, assignment, and deinitialization can be performed using
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.
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:
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
Always remember to deallocate any memory that you allocate yourself.
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:
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.
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
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