UnsafeMutableRawPointer

Overview 概要

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. UnsafeMutableRawPointer型は、自動メモリ管理、型安全、そしてアライメント保証を提供しません。あなたは、リークや未定義挙動を避けるために、あなたが安全でないポインタを通して扱うあらゆるメモリの生涯の処理に責任があります。

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. あなたが手動で管理するメモリは、特定の型に対して型付けされないまたは束縛されるのいずれかが可能です。あなたは、UnsafeMutableRawPointer型を使ってメモリ中の生のバイトにアクセスおよび管理を、そのメモリが特定の型に束縛されているかどうかにかかわらず行います。

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. UnsafeMutableRawPointerインスタンスによって参照されるメモリは、いくつかの状態の１つであることが可能です。多くのポインタ演算はある特定の状態のメモリを持つポインタに適用されるだけであるべきです — あなたは、あなたが作業しているメモリの状態を見失わないようにして、異なる演算が実行するその状態の変更を理解していなければなりません。メモリは、型無しで未初期化、ある型に束縛されて未初期化、またはある型に束縛されてある値に初期化される可能性があります。結局、以前にアロケートされたメモリはデアロケートされるかもしれません、アロケートされないメモリを参照している既存のポインタはそのままです。

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. あなたは、initializeMemory(as:from:)とmoveInitializeMemory(as:from:count:)のようなメソッドを使うことで、生のメモリをある型に束縛して、それをある値または一連の値で初期化します。未初期化メモリをそれを初期化することなくある型に束縛するには、bindMemory(to:count:)メソッドを使用してください。これらのメソッドは、この後で型付アクセスをこのメモリにするために型付ポインタを返します。

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. ある型に束縛されているメモリは、それが初期化済みか未初期化かにかかわらず、一般的に型付ポインタを使ってアクセスされます — UnsafePointerおよびUnsafeMutablePointerではなくて。初期化、代入、そしてデイニシャライズは、UnsafeMutablePointerメソッドを使って実行されます。

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. ある型に束縛されているメモリは、それがデイニシャライズされた後にまたは束縛型がtrivial typeである場合にのみ、異なる型に再束縛が可能です。型付メモリのデイニシャライズは、そのメモリの型を束縛解除しません。デイニシャライズされたメモリは、同じ型の値で再初期化する、新しい型に束縛する、またはデアロケートできます。

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: 生のポインタを使うポインタ算術は、バイト水準で実行されます。あなたが生のポインタに加算または減算する時、結果はそのバイト数をオフセットした（補った、埋め合わせた）新しい生のポインタです。以下の例は、４バイトのメモリをアロケートして0xFFを４バイトすべての中に格納します：

let bytesPointer = UnsafeMutableRawPointer.allocate(byteCount: 4, alignment: 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. 上のコードは値0xFFFF_FFFFを４つの新しいアロケート済みバイトに格納して、それから最初のバイトをUInt8インスタンスとして、そして３番目と４番目のバイトをUInt16インスタンスとしてロードします。

Always remember to deallocate any memory that you allocate yourself. あなたがあなた自身でアロケートするメモリは何であれデアロケートするのを必ず忘れないでください。

bytesPointer.deallocate()

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. 関数やメソッドをUnsafeMutableRawPointerパラメータとともに呼び出すとき、あなたはその特定のポインタ型のインスタンスを渡す、互換ポインタ型のインスタンスを渡す、またはSwiftの暗黙的ブリッジを使って互換ポインタを渡すことが可能です。

For example, the print(address:as:) function in the following code sample takes an UnsafeMutableRawPointer instance as its first parameter: 例えば、print(address:as:)関数は以下のコード例において、UnsafeMutableRawPointerインスタンスをそれの最初のパラメータとして取ります。

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. Swiftでは普通であるように、あなたはprint(address:as:)関数をUnsafeMutableRawPointerインスタンスとともに呼び出せます。この例は、rawPointerを最初のパラメータとして渡します。

// '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. 型付ポインタは暗黙的に生のポインタにキャストされることがパラメータとして渡される時に可能なことから、あなたはまたprint(address:as:)を何らかの可変の型付ポインタとともに呼び出せます。

let intPointer: UnsafeMutablePointer<Int> = ...
print(address: intPointer, 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:): あるいはまた、あなたはSwiftの暗黙的ブリッジを使ってポインタをインスタンスへまたは配列の要素へと渡せます。インアウト構文を使って、任意の型のインスタンスへのポインタを暗黙的に作成してください。以下の例は、print(address:as:)を呼び出すとき、暗黙的ブリッジを使ってポインタをvalueへと渡します：

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:). 配列の要素への可変ポインタは、あなたが配列をinout構文を使って渡す時に暗黙的に作成されます。この例は、print(address:as:)を呼び出す時に、暗黙的ブリッジを使ってnumbersの要素へのポインタを渡します。

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