ReadableStreamBYOBReader: read() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

データのチャンクが渡された場合、 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
# ref-for-byob-reader-read③

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
read
options.min parameter
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
Has more compatibility info.

関連情報