Generic Instance Method

withUnsafeBufferPointer(_:)

Calls a closure with a pointer to the array’s contiguous storage.

Declaration

func withUnsafeBufferPointer<R>(_ body: (UnsafeBufferPointer<Element>) throws -> R) rethrows -> R

Parameters

body

A closure with an UnsafeBufferPointer parameter that points to the contiguous storage for the array. If no such storage exists, it is created. If body has a return value, that value is also used as the return value for the withUnsafeBufferPointer(_:) method. The pointer argument is valid only for the duration of the method’s execution.

Return Value

The return value, if any, of the body closure parameter.

Discussion

Often, the optimizer can eliminate bounds checks within an array algorithm, but when that fails, invoking the same algorithm on the buffer pointer passed into your closure lets you trade safety for speed.

The following example shows how you can iterate over the contents of the buffer pointer:

let numbers = [1, 2, 3, 4, 5]
let sum = numbers.withUnsafeBufferPointer { buffer -> Int in
    var result = 0
    for i in stride(from: buffer.startIndex, to: buffer.endIndex, by: 2) {
        result += buffer[i]
    }
    return result
}
// 'sum' == 9

The pointer passed as an argument to body is valid only during the execution of withUnsafeBufferPointer(_:). Do not store or return the pointer for later use.

See Also

Accessing Underlying Storage

func withUnsafeMutableBufferPointer<R>((inout UnsafeMutableBufferPointer<Element>) -> R) -> R

Calls the given closure with a pointer to the array’s mutable contiguous storage.

func withUnsafeBytes<R>((UnsafeRawBufferPointer) -> R) -> R

Calls the given closure with a pointer to the underlying bytes of the array’s contiguous storage.

func withUnsafeMutableBytes<R>((UnsafeMutableRawBufferPointer) -> R) -> R

Calls the given closure with a pointer to the underlying bytes of the array’s mutable contiguous storage.