ReadableStreamBYOBReader: read() メソッド
=====================================

**`read()`** は `ReadableStreamBYOBReader` インターフェイスのメソッドで、ユーザーが提供したバッファー上のビューに、関連付けられた読み取り可能なバイトストリームからデータを読み込むために使用します。
 データに対するリクエストは、データを説明しているものがあれば、ストリームの内部キューから満たされます。
 ストリームキューが空の場合、リクエストは、基盤のバイトソースからのゼロコピー移譲として供給されるかもしれません。

 このメソッドは、渡されたデータを読み込むバッファーに対するビューを引数として取り、プロミス (`Promise`) を返します。
 このプロミスは、データが利用できるようになったとき、またはストリームが取り消される可能性があるときに `value` と `done` のプロパティを持つオブジェクトで履行されます。
 ストリームがエラーになった場合、プロミスは関連するエラーオブジェクトと共に拒否されます。

 データのチャンクが渡された場合、 `value` プロパティには新しいビューが格納されます。
 これは `read()` メソッドに渡された元の `view` と同じバッファー/バッキングメモリ（および同じ型）上のビューになります。
 プロミスが履行されると、メソッドに渡された元の `view` は切り離され、使えなくなることに注意してください。
 ストリームが取り消された可能性がある場合、プロミスは `value: undefined` で履行されます。
 この場合、 `view` のバッキングメモリー領域は破棄され、呼び出し側には返されません（ビューのバッファー内の前回読み込んだデータはすべて失われます）。

`done` プロパティは、さらなるデータが期待されるかどうかを示します。
 この値は、ストリームが閉じられたり取り消されたり可能性がある場合は `true` に設定され、そうでない場合は `false` に設定されます。

構文
--


```js
read(view)
```

### 引数

`view`

読み込み先のビュー。

### 返値

プロミス (`Promise`) で、ストリームの状態に応じた結果で履行または拒否されます。

取りうる値は次の通りです。

* チャンクが利用でき、ストリームがまだアクティブであれば、プロミスは次の形のオブジェクトで履行されます。

```js
{ value: theChunk, done: false }
```

`theChunk` は新しいデータを格納するビューです。
 これは `read()` メソッドに渡された `view` と同じ型で、同じバッキングメモリー上のビューです。
 元の `view` は切り離されて使えなくなりました。
* ストリームが閉じられた場合、プロミスは（`theChunk` を上記と同じプロパティを持つ）形式のオブジェクトで履行されます。

```js
{ value: theChunk, done: true }
```

* If the stream is cancelled, the promise fulfills with an object of the form:

```js
{ value: undefined, done: true }
```

In this case the backing memory is discarded.
* If the stream throws an error, the promise rejects with the relevant error.
### 例外

`TypeError`

元のオブジェクトが `ReadableStreamBYOBReader` ではないか、ストリームにオーナーがいないか、ビューがオブジェクトでないか、切り離されているか、ビューの長さが 0 であるか、（待機中の読み取りリクエストがある場合に） `ReadableStreamBYOBReader.releaseLock()` が呼び出された場合。

例
-

以下の例は、読み取り可能なバイトストリームの使用から取ったものです。

 まず、ストリーム上で `ReadableStream.getReader()` を使用してリーダーを作成します。 options 引数に `mode: "byob"` を指定します。
 `ArrayBuffer` も作成する必要があります。これはビューの「バッキングメモリー」で、ここに書き込むことになります。


```js
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(4000);
```


 リーダーを使用する関数を下記に示します。
 これは `read()` メソッドを再帰的に呼び出して、データをバッファーに読み込みます。
 このメソッドは `Uint8Array` 型付き配列を取ります。これは、元の配列バッファーでまだ書き込まれていない部分のビューです。
 ビューの引数は、前回呼び出された際に受け取ったデータから計算され、元の配列バッファーへのオフセットを定義します。


```js
readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that fulfills when a value has been received
    reader
      .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
      .then(function processBytes({ done, value }) {
        // Result objects contain two properties:
        // done - true if the stream has already given all its data.
        // value - some data. 'undefined' if the reader is canceled.

        if (done) {
          // There is no more data in the stream
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        // Read some more, and call this function again
        // Note that here we create a new view over the original buffer.
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
          .then(processBytes);
      });
  }
}
```


ストリームにデータがなくなると、`read()` メソッドは `done` プロパティを `true` に設定したオブジェクトで履行され、関数を返します。

仕様書
---

| Specification |
| --- |
| Streams Standard # ref-for-byob-reader-read③ |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `ReadableStreamBYOBReader()` コンストラクター
* 読み取り可能なストリームの使用