UnsafeRawPointer

A raw pointer for accessing untyped data.

Inheritance Strideable
Associated Types
  • public typealias Pointee = UInt8

The UnsafeRawPointer 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 UnsafeRawPointer 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 UnsafeRawPointer 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.

To bind uninitialized memory to a type without initializing it, use the bindMemory(to:count:) method. This method returns a typed pointer 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 memory as raw bytes when that memory is bound to a type, you must ensure that you satisfy any alignment requirements.

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(byteCount: 4, alignment: 4)
  • 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()

Implicit Casting and Bridging

When calling a function or method with an UnsafeRawPointer 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 UnsafeRawPointer instance as its first parameter:

  • func print<T>(address p: UnsafeRawPointer, 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 UnsafeRawPointer instance. This example passes rawPointer as the initial parameter.

  • // 'rawPointer' points to memory initialized with `Int` values.
  • let rawPointer: UnsafeRawPointer = ...
  • 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 or immutable typed pointer instance.

  • let intPointer: UnsafePointer<Int> = ...
  • print(address: intPointer, as: Int.self)
  • // Prints "42"
  •  
  • let mutableIntPointer = UnsafeMutablePointer(mutating: intPointer)
  • print(address: mutableIntPointer, as: Int.self)
  • // Prints "42"

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"

An immutable pointer to the elements of an array is implicitly created when you pass the array as an argument. This example uses implicit bridging to pass a pointer to the elements of numbers when calling print(address:as:).

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

You can also use inout syntax to pass a mutable pointer to the elements of an array. Because print(address:as:) requires an immutable pointer, although this is syntactically valid, it isn't necessary.

  • var mutableNumbers = numbers
  • print(address: &mutableNumbers, as: Int.self)

Important:

  • var number = 5
  • let numberPointer = UnsafeRawPointer(&number)
  • // Accessing 'numberPointer' is undefined behavior.

Initializers

init init(_:) Required

Creates a new raw pointer from the given typed pointer.

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

  • Parameter other: The typed pointer to convert.

Declaration

init init(_:) Required

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

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

  • Parameter other: The mutable raw pointer to convert.

Declaration

init init(_:) Required

Creates a new raw pointer from the given typed pointer.

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

  • Parameter other: The typed pointer to convert.

Declaration

init init(_:) Required

Creates a new raw pointer from an AutoreleasingUnsafeMutablePointer instance.

  • Parameter other: The pointer to convert.

Declaration

init init?(_:) Required

Creates a new raw pointer from the given typed pointer.

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

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

Declaration

init init?(_:) Required

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

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

  • Parameter other: The mutable raw pointer to convert. If other is nil, the result is nil.

Declaration

init init?(_:) Required

Creates a new raw pointer from the given typed pointer.

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

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

Declaration

init init?(_:) Required

Creates a new raw pointer from an AutoreleasingUnsafeMutablePointer instance.

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

Declaration

Instance Variables

var customPlaygroundQuickLook Required

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

Instance Methods

func advanced(by n: Int) -> UnsafeRawPointer Required

Returns a value that is offset the specified distance from this value.

Use the advanced(by:) method in generic code to offset a value by a specified distance. If you're working directly with numeric values, use the addition operator (+) instead of this method.

  • func addOne<T: Strideable>(to x: T) -> T
  •     where T.Stride: ExpressibleByIntegerLiteral
  • {
  •     return x.advanced(by: 1)
  • }
  •  
  • let x = addOne(to: 5)
  • // x == 6
  • let y = addOne(to: 3.5)
  • // y = 4.5

If this type's Stride type conforms to BinaryInteger, then for a value x, a distance n, and a value y = x.advanced(by: n), x.distance(to: y) == n. Using this method with types that have a noninteger Stride may result in an approximation.

  • Parameter n: The distance to advance this value.

Complexity: O(1)

Declaration

func assumingMemoryBound(to: T.Type) -> UnsafePointer<T> Required

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.

  • Parameter to: The type T that the memory has already been bound to.

Declaration

  • public func assumingMemoryBound<T>(to: T.Type) -> UnsafePointer<T>
func bindMemory(to type: T.Type, capacity count: Int) -> UnsafePointer<T> Required

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.

  • let count = 4
  • let bytesPointer = UnsafeMutableRawPointer.allocate(
  •         bytes: 100,
  •         alignedTo: MemoryLayout<Int8>.alignment)
  • let int8Pointer = bytesPointer.bindMemory(to: Int8.self, capacity: count)

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.

Declaration

  • public func bindMemory<T>(to type: T.Type, capacity count: Int) -> UnsafePointer<T>
func deallocate() Required

Deallocates the previously allocated memory block referenced by this pointer.

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

Declaration

  • @inlinable public func deallocate()
func load(fromByteOffset offset: Int = 0, as type: T.Type) -> T Required

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.

Declaration

  • @inlinable public func load<T>(fromByteOffset offset: Int = 0, as type: T.Type) -> T

Type Methods

func <(x: Self, y: Self) -> Bool Required

Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

This function is the only requirement of the Comparable protocol. The remainder of the relational operator functions are implemented by the standard library for any type that conforms to Comparable.

Declaration

  • @inlinable public static func <(x: Self, y: Self) -> Bool
func ==(x: Self, y: Self) -> Bool Required

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values a and b, a == b implies that a != b is false.

Declaration

  • @inlinable public static func ==(x: Self, y: Self) -> Bool